1 /*

     2  * Copyright (c) 2010 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: 

    15  *   WLAN Wizard Plugin API: Interface for wizard pages.

    16  *

    17  */

    18 

    19 #ifndef WLANWIZARDPAGE_H

    20 #define WLANWIZARDPAGE_H

    21 

    22 // System includes

    23 

    24 // User includes

    25 

    26 // Forward declarations

    27 class HbWidget;

    28 

    29 // External data types

    30 

    31 // Constants

    32 

    33 /*!

    34    @addtogroup group_wlan_wizard_api_internal

    35    @{

    36  */

    37 

    38 /*!

    39    Interface for wizard pages.

    40    

    41    Princibles of the interface, see description of the method for detailed

    42    information.

    43    - initializePage() is called at first to create the UI visualizatio

    44    - showPage() is called to detect whether next button should be enabled. This 

    45      method is called every time before the current page is displayed.

    46    - requiresStartOperation() is called to check if page needs timer protection.

    47      This is mainly used for pages where are progress bar and some asyncronous 

    48      operation with network layer, which commands on success to progress to next

    49      wizard page.

    50    - startOperation() is called to start page operation, this is called if above 

    51      method returs true.

    52    - nextId() is called when user presses next toolbar button or when page has

    53      called WlanWizardHelper::nextPage() method, which is used with timer

    54      protected pages.

    55    - previousTriggered() is called when previous toolbar button is pressed.

    56    - cancelTriggered() is called when cancel toolbar button is pressed.

    57    

    58    Wizard Page must implement all pure virtual methods

    59    - initializePage()

    60    - nextId()

    61    

    62    For other methods there is default implementation, which can be overwritten.

    63  */

    64 class WlanWizardPage

    65 {

    66 public:

    67     /*!

    68        Defines common page ids for wizard and page id pools for wizard plugins.

    69        

    70        Remember to update trace.properties file upon changes.

    71      */

    72     enum PageIds {

    73         //! No need to change the wizard page.

    74         PageNone = 0,

    75         //! Process settings. Start connection and runs ict

    76         PageProcessSettings,

    77         //! Generic Error note page

    78         PageGenericError,

    79         //! Starting value for WLAN wizard page ids. Defined by WLAN Wizard.

    80         PageWlanStart = 0x1000,

    81         //! Starting value for EAP wizard page ids. Defined by EAP Wizard.

    82         PageEapStart = 0x2000,

    83         //! Starting value for WPS wizard page ids. Defined by WPS Wizard.

    84         PageWpsStart = 0x3000,

    85     };

    86 

    87 public:

    88 

    89     /*!

    90        Creates a visualization of the wizard page and returns ownership of the

    91        object to the caller. Wizard framework deletes the visualization at the

    92        desctructor of WlanWizardPrivate implementation. WizardPage control

    93        object can safely use the same pointer during the life time of the

    94        control object. This method is called every time when moving to a new

    95        page, not when user presses "previous" button. showPage() method is

    96        called in both cases. 

    97        

    98        @return pointer to a visualization of the page.

    99      */

   100     virtual HbWidget* initializePage() = 0;

   101 

   102     /*!

   103        This method is called, after a visualization is created with

   104        initializePage() method, to detect whether next button should be enabled

   105        or not. It is up to the policy of the page when next button should be

   106        enabled. This method is called everytime before the current 

   107        active page is displayed. In other words this method is "aboutToShow()"

   108        

   109        Default implementation: wizard page is valid and next button is enabled.

   110        

   111        @return validity.       

   112      */

   113     virtual bool showPage()

   114     {

   115         return true;

   116     };

   117 

   118     /*!

   119        If the wizard page requires timer protection and asyncronous time

   120        lasting operation, return true. This is used in pages e.g. where

   121        progressbar is shown. The whole point is to initialize the UI before

   122        starting the operation, so that the progress bar is painted before the

   123        operation takes place.

   124        

   125        In practise this means that if true is returned by this method.

   126        - WlanWizardPage::startOperation() is called to start the page operation.

   127        - 1.5sec timer is used to protect the page

   128        - wizardPage MUST call WlanWizardHelper::nextPage() to trigger entry to

   129          next wizard page.

   130        

   131        @return true if protection is needed.

   132      */

   133 

   134     virtual bool requiresStartOperation()

   135     {

   136         return false;

   137     };

   138 

   139     /*!

   140        In case the wizard page needs timer protection to the page use this

   141        method to start control operation of the page. This method will be called

   142        after requiresStartOperation() if true is returned with different call

   143        stack.

   144        

   145        See requiresStartOperation(), WlanWizardHelper::nextPage().

   146      */

   147     virtual void startOperation() {};

   148 

   149     /*!

   150        Returns id of next page. This method is called when end user has pressed

   151        "next" toolbar button or WlanWizardHelper::nextPage() is called.

   152        

   153        In case the wizard page does not want to make any movement forwards

   154        WlanWizardPage::PageNone MUST be returned.

   155        

   156        @param [out] removeFromStack return value to the caller, if this page

   157        needs to be removed from the stack, which means that this page cannot be

   158        accessible from the next page using "previous" toolbar button. 

   159        

   160        @return page identifier of next wizard page

   161      */

   162     virtual int nextId(bool &removeFromStack) const = 0;

   163 

   164     /*!

   165        This method is called when "previous" button has been pressed.

   166      

   167        Default implementation: one page backwards

   168        

   169        @return how many steps should be gone backwards. 

   170      */

   171     virtual int previousTriggered()

   172     {

   173         return OneStepBackwards;

   174     };

   175 

   176     /*!

   177        This method is called when "cancel" button has been pressed.

   178        

   179        Default implementation: No actions.

   180      */

   181     virtual void cancelTriggered() {};

   182     

   183 signals:

   184     

   185 public slots:

   186     

   187 protected:

   188     //! default value for previousTriggered(), step one step.

   189     static const int OneStepBackwards = 1;

   190     

   191 protected slots:

   192 

   193 private:

   194 

   195 private slots:

   196 

   197 private: // data

   198 };

   199 

   200 /*! @} */

   201 

   202 #endif // WLANWIZARDPAGE_H