/*

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

 * All rights reserved.

 * This component and the accompanying materials are made available

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

 * which accompanies this distribution, and is available

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

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description: 

 *   WLAN Wizard Plugin API: Interface for wizard pages.

 *

 */

#ifndef WLANWIZARDPAGE_H

#define WLANWIZARDPAGE_H

// System includes

// User includes

// Forward declarations

class HbWidget;

// External data types

// Constants

/*!

   @addtogroup group_wlan_wizard_api_internal

   @{

 */

/*!

   Interface for wizard pages.

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

   information.

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

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

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

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

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

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

     wizard page.

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

     method returs true.

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

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

     protected pages.

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

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

   Wizard Page must implement all pure virtual methods

   - initializePage()

   - nextId()

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

 */

class WlanWizardPage

{

public:

    /*!

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

       Remember to update trace.properties file upon changes.

     */

    enum PageIds {

        //! No need to change the wizard page.

        PageNone = 0,

        //! Process settings. Start connection and runs ict

        PageProcessSettings,

        //! Generic Error note page

        PageGenericError,

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

        PageWlanStart = 0x1000,

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

        PageEapStart = 0x2000,

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

        PageWpsStart = 0x3000,

    };

public:

    /*!

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

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

       desctructor of WlanWizardPrivate implementation. WizardPage control

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

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

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

       called in both cases. 

       @return pointer to a visualization of the page.

     */

    virtual HbWidget* initializePage() = 0;

    /*!

       This method is called, after a visualization is created with

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

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

       enabled. This method is called everytime before the current 

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

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

       @return validity.       

     */

    virtual bool showPage()

    {

        return true;

    };

    /*!

       If the wizard page requires timer protection and asyncronous time

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

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

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

       operation takes place.

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

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

       - 1.5sec timer is used to protect the page

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

         next wizard page.

       @return true if protection is needed.

     */

    virtual bool requiresStartOperation()

    {

        return false;

    };

    /*!

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

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

       after requiresStartOperation() if true is returned with different call

       stack.

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

     */

    virtual void startOperation() {};

    /*!

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

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

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

       WlanWizardPage::PageNone MUST be returned.

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

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

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

       @return page identifier of next wizard page

     */

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

    /*!

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

       Default implementation: one page backwards

       @return how many steps should be gone backwards. 

     */

    virtual int previousTriggered()

    {

        return OneStepBackwards;

    };

    /*!

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

       Default implementation: No actions.

     */

    virtual void cancelTriggered() {};

signals:

public slots:

protected:

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

    static const int OneStepBackwards = 1;

protected slots:

private:

private slots:

private: // data

};

/*! @} */

#endif // WLANWIZARDPAGE_H