/*

* 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:

* CM Manager Application Settings UI interface.  

*

*/

#ifndef CMAPPLSETTINGSUI_H

#define CMAPPLSETTINGSUI_H

// System includes

#include <QObject>

#include <QFlags>

#include <QSet>

// User includes

// Forward declarations

class CmApplSettingsUiPrivate;

class TestCmApplSettingsUi;

// External data types

// Constants

#ifdef BUILD_CMAPPLSETTINGSUI_DLL

#define CMAPPLSETTINGSUIDLL_EXPORT Q_DECL_EXPORT

#else

#define CMAPPLSETTINGSUIDLL_EXPORT Q_DECL_IMPORT

#endif

// Class declaration

/*!

    \class CmApplSettingsUi

    \brief Class for launching the Application Settings UI.

    Displays a radio button list dialog for an application that can be used

    to select a destination or connection method.

*/

class CMAPPLSETTINGSUIDLL_EXPORT CmApplSettingsUi : public QObject

{

    Q_OBJECT

public:

    // Data types

    /*! 

       The selection type of a list item in application settings UI

     */

    enum SelectionType

        {

        //! The user selected a destination

        SelectionTypeDestination,

        //! The user selected a connection method

        SelectionTypeConnectionMethod

        };

    /*! 

       These flags control what items the selection UI can contain.

       Flags that are not listed in the enum are reserved for future usage

       and they are disabled by default. So extending these flags later on

       does not cause a BC break. These flags are used as bit fields.

       The following enumerations control how destinations and 

       Connection Methods are presented in the selection UI.

       ShowDestinations is set and ShowConnectionMethods is set:

         Destination list is shown in selection UI and alternatively

         the user can select a Connection Method.

       ShowDestinations is set and ShowConnectionMethods is not set:

         Destination list is shown in selection UI and no specific

         Connection Method can be selected. 

       ShowDestinations is not set and ShowConnectionMethods is set:

         Connection Method list is shown in selection UI. Destinations

         can not be selected.

       ShowDestinations is not set and ShowConnectionMethods is not set:

         The selection UI will not contain any Destination or

         Connection Method. If no extension(s) are implemented  (later

         on), no dialog is shown, and the execution is cancelled

         (ApplSettingsErrorNoContent).

     */

    enum SelectionDialogItems

        {

        //! Support destination selection

        ShowDestinations = 0x01,

        //! Support connection method selection

        ShowConnectionMethods = 0x02                              

        };

    /*!

       Error codes for the dialog.

     */

    enum ApplSettingsError {

        //! No error. Dialog succeeded.

        ApplSettingsErrorNone = 0,

        //! Selection was canceled.

        ApplSettingsErrorCancel,

        //! No items to show (e.g. too strict filters).

        ApplSettingsErrorNoContent,

        //! Settings reading failed.

        ApplSettingsErrorSettingsRead

    };

    /*!

       Details of a setting selection. Used both for configuring and

       selection result.

     */

    struct SettingSelection

        {

        /*!

           Selection type, refers to the type of the list item which

           is selected.

         */

        SelectionType result;

        /*!

           Id of the selected destination or connection method.

         */

        uint id;

        };

    /*!

       Typedef for the bearer filter parameter.

       This type is used to filter Connection Methods by bearer type.

       The Bearer types are defined in CM Manager's Connection Settings

       Shim (cmmanagerdefines_shim.h). 

     */

    typedef uint BearerTypeFilter;

    /*!

        Constructor.

        @param parent Parent object.

     */

    explicit CmApplSettingsUi(QObject *parent = 0);

    /*!

        Destructor.

     */

    virtual ~CmApplSettingsUi();

    /*!

        Set dialog options. If this function is not called before running the

        dialog, the default options are used:

        -listItems: ShowDestinations | ShowConnectionMethods

        -bearerFilter: empty

        @param[in] listItems Dialog list items configuration.

        @param[in] bearerFilter Dialog Connection Method bearer type filter.

        If empty, all bearers are supported.

     */

    void setOptions(

        const QFlags<SelectionDialogItems> &listItems,

        const QSet<BearerTypeFilter> &bearerFilter);

    /*!

        Dialog selection setter. Sets the current selection in the dialog.

        If not selected, or if the selection is invalid, the default

        selection is used (the first item in the dialog items list).

        @param[in] selection Dialog selection to set.

     */

    void setSelection(const SettingSelection &selection);

    /*!

        Dialog selection getter. Returns the current selection.

        @return Current dialog selection.

     */

    SettingSelection selection() const;

    /*!

        Launches the Application Settings UI provided for applications

        for selecting Destinations and/or Connection Methods.

        If a list of Destinations is displayed, and the selection is set to

        a Connection Method, the destination list highlight is set to

        "Dedicated access point".

        This function runs the dialog asynchronously.  After the dialog

        has been closed (or cancelled), the signal finished() is emmitted.

        If the dialog succeeded, the client can then check the new

        selection with selection() getter.

     */

    void open();

signals:

    /*!

       Signal used for informing that the dialog has finished.

       @param[in] status Dialog run status code (ApplSettingsError*).

     */

    void finished(uint status);

public slots:

protected:

protected slots:

private:

    Q_DISABLE_COPY(CmApplSettingsUi)

private slots:

private: // data

    CmApplSettingsUiPrivate *d_ptr;         //!< Private implementation

    // Friend classes

    // This is defined as a friend class in order to be able to emit

    // signals directly from private implementation code.

    friend class CmApplSettingsUiPrivate;

    // Test class needs direct access

    friend class TestCmApplSettingsUi;

};

#endif // CMAPPLSETTINGSUI_H