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 

    29 class QGraphicsWidget;

    30    

    31 /**

    32  * @ingroup group_ftuwizardmodel

    33  * @brief Represents a wizard plugin visualization information.

    34  *

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

    36  * the FTU fw.

    37  * 

    38  * @lib ?library

    39  * @since S60 ?S60_version

    40  */

    41 

    42 typedef struct {

    43     /**

    44      * The default icon to be shown in menustrip UI component.

    45      */ 

    46     QFileInfo mMenustripDefaultIcon;

    47     /**

    48      * The pressed icon to be shown in menustrip UI component.

    49      */ 

    50     QFileInfo mMenustripPressedIcon;

    51     /**

    52      * The focussed icon to be shown in menustrip UI component.

    53      */ 

    54     QFileInfo mMenustripFocussedIcon;

    55     /**

    56      * The text to be shown in menustrip UI component.

    57      */ 

    58     QString   mMenustripLabel;

    59     /**

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

    61      */ 

    62     QFileInfo mTocDefaultIcon;

    63     /**

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

    65      */ 

    66     QFileInfo mTocPressedIcon;

    67     /**

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

    69      */ 

    70     QFileInfo mTocFocussedIcon;

    71     /**

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

    73      */ 

    74     QString   mTocLabel;

    75 } FtuWizardSetting; 

    76 

    77 /**

    78  * @ingroup group_ftuwizardmodel

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

    80  *

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

    82  * executed in the FTU fw.

    83  *

    84  * @lib ?library

    85  * @since S60 ?S60_version

    86  */

    87 

    88 class FTUWIZARDMODEL_EXPORT FtuWizard : public QObject

    89 {

    90     Q_OBJECT

    91 public:

    92     /**

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

    94      */

    95     enum ShutdownReason {MemoryLow, GraphicsMemoryLow, NormalBoot};

    96 

    97 public:

    98     

    99     /**

   100      * Destructor.

   101      * @since S60 ?S60_version.

   102      */

   103     virtual ~FtuWizard(){}

   104 

   105     /**

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

   107      * this phase the wizard widget

   108      * usually creates its initial view.

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

   110      * emitted.

   111      * @since S60 ?S60_version.

   112      */

   113     virtual void initializeWizard() = 0;

   114 

   115     /**

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

   117      * @since S60 ?S60_version.

   118      */

   119     virtual void activateWizard() = 0;

   120 

   121     /**

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

   123      */

   124     virtual void deactivateWizard() = 0;

   125 

   126     /**

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

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

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

   130      *         true means the wizard can be deleted immediately.

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

   132      *         be released.

   133      */

   134     virtual bool shutdownWizard(ShutdownReason reason) = 0;

   135 

   136     /**

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

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

   139      */

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

   141 

   142     /**

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

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

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

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

   147      * created.

   148      * @return The plugin wizard gui settings. 

   149      */

   150     virtual const FtuWizardSetting& wizardSettings() = 0;

   151     

   152     /**

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

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

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

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

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

   158      */

   159     virtual bool handleBackEvent() = 0;

   160     

   161      /**

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

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

   164      */    

   165     virtual QDate wizardCompletedDate() = 0;

   166     

   167 protected:

   168     

   169     /**

   170      * Constructor.

   171      * @since S60 ?S60_version.

   172      */

   173     FtuWizard(){}

   174     

   175     

   176 signals:

   177     /**

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

   179      * @param caller The calling wizard plugin instance.

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

   181      */

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

   183     

   184     /**

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

   186      * @param caller The calling wizard plugin instance.

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

   188      *                         UI.

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

   190      */

   191     void progressUpdated(FtuWizard *caller, bool showProgess, 

   192                          int progressPercentage);

   193     

   194     /**

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

   196      * @param caller The calling wizard plugin instance.

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

   198     */

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

   200     

   201     /**

   202      * Emit this signal to put the ftu view to full-screen view, i.e. no 

   203      * titlebar, infotext & menustrip.

   204      * @param caller The calling wizard plugin instance.

   205      */

   206     void fullScreenModeRequested(FtuWizard *caller);

   207     

   208     /**

   209      * Emit this signal to come out of fullscreen mode, i.e. show the titlebar,

   210      * infotext and menustrip

   211      * @param caller The calling wizard plugin instance.

   212      */

   213     void partialScreenModeRequested(FtuWizard *caller);

   214     

   215     /**

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

   217      * overlay animation on top of the current view

   218      * @param caller The calling wizard plugin instance.

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

   220      */    

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

   222     

   223     /**

   224      * Removes the overlay widget added by addOverlay signal. 

   225      * @param caller The calling wizard plugin instance.

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

   227      */

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

   229     

   230     /**

   231      * Emit this signal to indicate initialization is done. 

   232      * @param caller The calling wizard plugin instance.

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

   234      */

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

   236     

   237     /**

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

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

   240      * from shutdownWizard.

   241      * @param caller The calling wizard plugin instance.

   242      */

   243     void shutdownCompleted(FtuWizard *caller);

   244 

   245 };

   246 

   247 #endif // FTUWIZARD_H

   248