1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  FtuWizard class definition

    15 *

    16 */

    17 

    18 

    19 #ifndef FTUWIZARD_H

    20 #define FTUWIZARD_H

    21 

    22 #include "ftuwizardmodellib.h"

    23 

    24 #include <QFileInfo>

    25 #include <QObject>

    26 #include <QRectF>

    27 #include <QDate>

    28 #include <hbmenu>

    29 

    30 class QGraphicsWidget;

    31 

    32 /**

    33  * @ingroup group_ftuwizardmodel

    34  * @brief Represents a wizard plugin visualization information.

    35  *

    36  * FtuWizardSetting struct contains the information needed to construct the GUI in

    37  * the FTU fw.

    38  * 

    39  * @lib ?library

    40  * @since S60 ?S60_version

    41  */

    42 

    43 typedef struct {

    44     /**

    45      * The default icon to be shown in table of contents UI component.

    46      */ 

    47     QFileInfo mTocDefaultIcon;

    48     /**

    49      * The pressed icon to be shown in table of contents UI component.

    50      */ 

    51     QFileInfo mTocPressedIcon;

    52     /**

    53      * The focussed icon to be shown in table of contents UI component.

    54      */ 

    55     QFileInfo mTocFocussedIcon;

    56     /**

    57      * The text to be shown in table of contents UI component.

    58      */ 

    59     QString   mTocLabel;

    60 	 /**

    61      * Informs Framework whether a plugin is having any ftu view or not.

    62 	 * It should be set to false by plugin if it has any FTU view to be shown 

    63 	 * when the plugin is activated. It should be set to true if plugin 

    64 	 * is invoking any service/wizard, when plugin is selected/activated. 

    65      */

    66     bool mNoViews;

    67 } FtuWizardSetting; 

    68 

    69 /**

    70  * @ingroup group_ftuwizardmodel

    71  * @brief Represents a wizard plugin in the framework.

    72  *

    73  * FtuWizard is an interface through which setting wizard plugin can be 

    74  * executed in the FTU fw.

    75  *

    76  * @lib ?library

    77  * @since S60 ?S60_version

    78  */

    79 

    80 class FTUWIZARDMODEL_EXPORT FtuWizard : public QObject

    81 {

    82     Q_OBJECT

    83 public:

    84     /**

    85      * The reason why the FTU fw and the wizard plugin is being shut down.

    86      */

    87     enum ShutdownReason {MemoryLow, GraphicsMemoryLow, NormalBoot};

    88 

    89 public:

    90     

    91     /**

    92      * Destructor.

    93      * @since S60 ?S60_version.

    94      */

    95     virtual ~FtuWizard(){}

    96 

    97     /**

    98      * Called by the FTU fw during initialize cycle of the wizard, it is during

    99      * this phase the wizard widget

   100      * usually creates its initial view.

   101      * Once the initialization is done, wizardInitialized signal must be 

   102      * emitted.

   103 	 * @param cenrepOwnerId Id of the owner of Cenrep holding wizard completion Information.

   104 	 * @param wizardIdx Index of the Cenrep key for a wizard.

   105 	 * If wizard is invoking another application, it should provide cenrepOwnerId and wizardIdx

   106 	 * to the application. Application should write 1 into the wizardIdx cenrep on completion.

   107      * @since S60 ?S60_version.

   108      */

   109     virtual void initializeWizard(qint32 cenrepOwnerId, int wizardIdx) = 0;

   110 

   111     /**

   112      * Called by the FTU fw when the wizard becomes the current wizard.  

   113      * @since S60 ?S60_version.

   114      */

   115     virtual void activateWizard() = 0;

   116 

   117     /**

   118      * Called by the FTU fw when the wizard is no longer being displayed.  

   119      */

   120     virtual void deactivateWizard() = 0;

   121 

   122     /**

   123      * Called by the FTU fw before the wizard destructor is called.

   124      * @param reason The reason why the ftu fw is being killed.

   125      * @return The mode how wizard plugin is shut down. 

   126      *         true means the wizard can be deleted immediately.

   127      *         false means the wizard signals with shutdownDone when it can

   128      *         be released.

   129      */

   130     virtual bool shutdownWizard(ShutdownReason reason) = 0;

   131 

   132     /**

   133      * Called by the FTU fw to set the wizard size.

   134      * @param geometry The rectangle allocated to this wizard.

   135      */

   136     virtual void resizeWizard(const QRectF& geometry) = 0;

   137 

   138     /**

   139      * This wizard setting values is queryed by the FTU fw to get the display 

   140      * properties of the wizard required to be shown in the FTU fw's table of

   141      * contents view and menu strip (e.g the icon & name of the wizard).

   142      * The information must be available once the plugin instance has been 

   143      * created.

   144      * @return The plugin wizard gui settings. 

   145      */

   146     virtual const FtuWizardSetting& wizardSettings() = 0;

   147     

   148     /**

   149      * Called by FTU fw when back button is clicked in the plugin view.

   150      * In this method the wizard plugin can implement internally showing and

   151      * hiding GUI elements if the plugin has multiple 'views'.

   152      * @return true if back event is handled internally in wizard plugin

   153      *         false if the FTU fw is to handle the event.

   154      */

   155     virtual bool handleBackEvent() = 0;

   156     

   157      /**

   158      * Called by FTU fw to get the date when the settings have been saved.

   159      * @return The date when wizard settings have been completed.

   160      */    

   161     virtual QDate wizardCompletedDate() = 0;

   162     

   163 protected:

   164     

   165     /**

   166      * Constructor.

   167      * @since S60 ?S60_version.

   168      */

   169     FtuWizard(){}

   170     

   171     

   172 signals:

   173     /**

   174      * Emit this signal to update the text of the info text widget.

   175      * @param caller The calling wizard plugin instance.

   176      * @param text The info text to be shown.

   177      */

   178     void infoTextUpdated(FtuWizard *caller, QString text);

   179     

   180     /**

   181      * Emit this signal notify the progress on wizard settings.

   182      * @param caller The calling wizard plugin instance.

   183      * @param showCompleteness True if the progress is being indicated on the

   184      *                         UI.

   185      * @param completenessPercentage The progress of the settings operation.

   186      */

   187     void progressUpdated(FtuWizard *caller, bool showProgess, 

   188                          int progressPercentage);

   189     

   190     /**

   191      * Emit this signal when changing the view inside the wizard plugin.

   192      * @param caller The calling wizard plugin instance.

   193      * @param viewWidget The new plugin view widget to be shown.

   194     */

   195     void viewChanged(FtuWizard *caller, QGraphicsWidget* viewWidget);

   196     

   197     /**

   198      * Adds an over-lay widget on top of the current view, used to add an 

   199      * overlay animation on top of the current view

   200      * @param caller The calling wizard plugin instance.

   201      * @param overlay The overlay widget to be added.

   202      */    

   203     void overlayAdded(FtuWizard *caller, QGraphicsWidget* overlay);

   204     

   205     /**

   206      * Removes the overlay widget added by addOverlay signal. 

   207      * @param caller The calling wizard plugin instance.

   208      * @param overlay The overlay widget to be removed.

   209      */

   210     void overlayRemoved(FtuWizard *caller, QGraphicsWidget* overlay);

   211     

   212     /**

   213      * Emit this signal to indicate initialization is done. 

   214      * @param caller The calling wizard plugin instance.

   215      * @param success True if succeeded, false otherwise.

   216      */

   217     void wizardInitialized(FtuWizard *caller, bool success);

   218     

   219     /**

   220      * Emit this signal to indicate that the wizard plugin can be deleted. 

   221      * Note that this signal does not need to be emitted if true is returned

   222      * from shutdownWizard.

   223      * @param caller The calling wizard plugin instance.

   224      */

   225     void shutdownCompleted(FtuWizard *caller);

   226     

   227     /**

   228      * Emit this signal to indicate that the wizard plugin wants a custom view menu to be shown. 

   229      * from shutdownWizard.

   230      * @param caller The calling wizard plugin instance.

   231      * @param menu   The HbMenu instance that needs to be shown on the view

   232      */

   233     void updateMainMenu(FtuWizard *caller, HbMenu * menu);

   234 

   235     /**

   236      * Emit this signal to indicate that the wizard plugin wants to be deactivated. 

   237      * Wizard is deactivated and Table of Contents is shown by the application.

   238      * @param caller The calling wizard plugin instance.

   239      */

   240     void wizardDeactivated(FtuWizard *caller);

   241     

   242 };

   243 

   244 #endif // FTUWIZARD_H

   245