/****************************************************************************

**

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

** All rights reserved.

** Contact: Nokia Corporation (developer.feedback@nokia.com)

**

** This file is part of the HbCore module of the UI Extensions for Mobile.

**

** GNU Lesser General Public License Usage

** This file may be used under the terms of the GNU Lesser General Public

** License version 2.1 as published by the Free Software Foundation and

** appearing in the file LICENSE.LGPL included in the packaging of this file.

** Please review the following information to ensure the GNU Lesser General

** Public License version 2.1 requirements will be met:

** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at developer.feedback@nokia.com.

**

****************************************************************************/

/*!

    \class HbDeviceDialogPlugin

    \brief HbDeviceDialogPlugin is an abstract base class for device dialog widget plugins.

    Device dialogs are widgets which are shown on top of all applications by a device dialog

    service. The service queues and displays device dialogs according to client requests and

    system state. The service displays widgets in it's window (HbApplication window).

    Device dialog widgets are created by plugins. The service loads a plugin to create and display

    a device dialog. A single plugin may implement several different dialogs or just one.

    Dialogs are identified by a string. By convention the string should follow

    inverted domain name format. For example com.nokia.hb.devicedialog.note/1.0.

    Function deviceDialogTypes() returns a list of dialog types the plugin implements.

    Appending version number into device dialog type string enables versioning of device dialogs.

    A plugin should handle versioning by returning device dialog type string for all versions it

    implements in deviceDialogTypes() and then in createDeviceDialog() create a device dialog

    instance compatible with the version requested. This could always be the latest version if it

    is backwards compatible with older versions. Device dialog framework is unaware of version

    numbers in type strings. It performs string comparison of the whole string when searching

    for a plugin.

    Device dialog widgets have to be derived from HbPopup either directly or by ancestry.

    Device dialog widget can be derived from existing Hb class, eg. HbDialog or constructed from

    a docml using HbDocumentLoader. Structure of the plugin differs depending on which approach

    is selected. If docml is used the dialog widget cannot be multiple inherited from HbDialog

    and HbDeviceDialogInterface. In this case a container can be used to to create and manage the

    widget. See code example at the end.

    Plugins are responsible for maintaining system security for their own part. If plugin

    performs operations that may compromise security or want's to limit access to specific

    clients, it should check client security credentials in accessAllowed() function.

    Device dialog framework calls this function before creating or attaching client to a

    plugin if HbDeviceDialogPlugin::SecurityCheck is set. Access is denied if the

    function returns false. In addition, HbDeviceDialogPlugin constructor has a check which

    allows only device dialog service to load plugins derived from it.

    Well behaving dialog widget should observe following rules:

    - Should not create and show other dialogs

    - No calls to show(), hide() or setVisible()

    - Not setting popup Z-order

    - No time consuming operations performed

    Creating a device dialog plugin and widget involves following steps.

    - Set in .pro file TEMPLATE = lib and CONFIG += hb plugin

    - Derive a class from HbPopup or derivatives and HbDeviceDialogInterface

    The example below is <b>not using docml</b> and dialog widget is derived from HbDialog and

    HbDeviceDialogInterface.

    \code

    class HbSampleMessageBoxWidget : public HbMessageBox, public HbDeviceDialogInterface

    {

        Q_OBJECT

    \endcode

    - Implement device dialog widget and HbDeviceDialogInterface interface. Declare and emit

      deviceDialogClosed and optionally deviceDialogData signals. Do not call show(), hide() or

      setVisible() in the plugin. Device dialog framework calls show() to display the widget.

    \code

    public:

        bool setDeviceDialogParameters(const QVariantMap &parameters);

        int deviceDialogError() const;

        void closeDeviceDialog(bool byClient);

        HbPopup *deviceDialogWidget() const;

    signals:

        void deviceDialogClosed();

        void deviceDialogData(QVariantMap data);

    \endcode

    - Wrap the widget into a plugin derived from HbDeviceDialogPlugin

    \code

    class HbSampleMessageBoxPlugin : public HbDeviceDialogPlugin

    {

        Q_OBJECT

    \endcode

    - Implement HbDeviceDialogPlugin pure virtual functions

    \code

        bool accessAllowed(const QString &deviceDialogType,

            const QVariantMap &parameters, const QVariantMap &securityInfo) const;

        HbDeviceDialogInterface *createDeviceDialog(const QString &deviceDialogType, const QVariantMap &parameters);

        bool deviceDialogInfo(const QString &deviceDialogType,

            const QVariantMap &parameters, DeviceDialogInfo *info) const;

        QStringList deviceDialogTypes() const;

        PluginFlags pluginFlags() const;

        int error() const;

    \endcode

    <b> Class diagram of the sample plugin:</b>

    \dot

    digraph G {

        rankdir=LR;

        subgraph cluster_class_diagram {

            style=solid;

            node [shape = box, style=solid, fontsize = 10];

            HbSampleMessageBoxPlugin [label = "HbSampleMessageBoxPlugin"];

            QObject [label = "QObject"];

            HbDeviceDialogPluginInterface [label = "HbDeviceDialogPluginInterface"];

            HbDeviceDialogPlugin [label = "HbDeviceDialogPlugin"];

            edge [fontsize = 10, style = filled];

            QObject -> HbDeviceDialogPlugin [label = "is a"];

            HbDeviceDialogPluginInterface -> HbDeviceDialogPlugin [label = "is a"];

            HbDeviceDialogPlugin -> HbSampleMessageBoxPlugin [label = "is a"];

            HbSampleMessageBoxWidget [label = "HbSampleMessageBoxWidget"];

            HbMessageBox [label = "HbMessageBox"];

            HbDeviceDialogInterface [label = "HbDeviceDialogInterface"];

            HbMessageBox -> HbSampleMessageBoxWidget [label = "is a"];

            HbDeviceDialogInterface -> HbSampleMessageBoxWidget [label = "is a"];

            edge [fontsize = 10, style = dotted];

            HbSampleMessageBoxPlugin -> HbSampleMessageBoxWidget  [label = "creates"];

        }

        subgraph cluster_key {

            label = "Key";

            style=solid;

            node [shape = box, style=solid, fontsize = 10];

            Class1 [label = "Class"];

            Class2 [label = "Class"];

            Class3 [label = "Class"];

            edge [fontsize = 10, style = filled];

            Class2 -> Class1 [label = "generalization"];

            edge [fontsize = 10, style = dotted];

            Class3 -> Class1 [label = "dependency"];

            }

    }

    \enddot

    The example below is <b>using docml</b> and dialog widget is managed by a container.

    \code

    class HbSampleDialogContainer : public QObject, public HbDeviceDialogInterface

    {

        Q_OBJECT

    \endcode

    - In the constructor create the dialog widget using HbDocumentLoader

    - Implement HbDeviceDialogInterface functions

      - From deviceDialogWidget() function return the created (docml) widget

      - From signalSender() function return the container (HbSampleDialogContainer)

    - Declare and emit deviceDialogClosed and optionally deviceDialogData signals.

    - Do not call show(), hide() or setVisible() in the plugin. Device dialog

      framework calls show() to display the widget.

    \code

    public:

        bool setDeviceDialogParameters(const QVariantMap &parameters);

        int deviceDialogError() const;

        void closeDeviceDialog(bool byClient);

        HbPopup *deviceDialogWidget() const;

        QObject *signalSender() const;

    signals:

        void deviceDialogClosed();

        void deviceDialogData(QVariantMap data);

    \endcode

    - Wrap the widget into a plugin derived from HbDeviceDialogPlugin

    \code

    class HbSampleDeviceDialogPlugin : public HbDeviceDialogPlugin

    {

        Q_OBJECT

    \endcode

    - Implement HbDeviceDialogPlugin pure virtual functions

      - Return the container (HbSampleDialogContainer) from createDeviceDialog() function

    \code

        bool accessAllowed(const QString &deviceDialogType,

            const QVariantMap &parameters, const QVariantMap &securityInfo) const;

        HbDeviceDialogInterface *createDeviceDialog(const QString &deviceDialogType, const QVariantMap &parameters);

        bool deviceDialogInfo(const QString &deviceDialogType,

            const QVariantMap &parameters, DeviceDialogInfo *info) const;

        QStringList deviceDialogTypes() const;

        PluginFlags pluginFlags() const;

        int error() const;

    \endcode

    <b> Class diagram of the sample plugin using docml:</b>

    \dot

    digraph G {

        rankdir=LR;

        subgraph cluster_class_diagram {

            style=solid;

            node [shape = box, style=solid, fontsize = 10];

            HbSampleDeviceDialogPlugin [label = "HbSampleDeviceDialogPlugin"];

            QObject [label = "QObject"];

            HbDeviceDialogPluginInterface [label = "HbDeviceDialogPluginInterface"];

            HbDeviceDialogPlugin [label = "HbDeviceDialogPlugin"];

            edge [fontsize = 10, style = filled];

            QObject -> HbDeviceDialogPlugin [label = "is a"];

            HbDeviceDialogPluginInterface -> HbDeviceDialogPlugin [label = "is a"];

            HbDeviceDialogPlugin -> HbSampleDeviceDialogPlugin [label = "is a"];

            HbSampleDialogContainer [label = "HbSampleDialogContainer"];

            QObject2 [label = "QObject"];

            HbDeviceDialogInterface [label = "HbDeviceDialogInterface"];

            QObject2 -> HbSampleDialogContainer [label = "is a"];

            HbDeviceDialogInterface -> HbSampleDialogContainer [label = "is a"];

            edge [fontsize = 10, style = dotted];

            HbSampleDeviceDialogPlugin -> HbSampleDialogContainer [label = "creates"];

            DialogWidget [label = "Dialog widget (docml)"];

            edge [fontsize = 10, style = dotted];

            HbSampleDialogContainer -> DialogWidget [label = "creates"];

        }

        subgraph cluster_key {

            label = "Key";

            style=solid;

            node [shape = box, style=solid, fontsize = 10];

            Class1 [label = "Class"];

            Class2 [label = "Class"];

            Class3 [label = "Class"];

            edge [fontsize = 10, style = filled];

            Class2 -> Class1 [label = "generalization"];

            edge [fontsize = 10, style = dotted];

            Class3 -> Class1 [label = "dependency"];

            }

    }

    \enddot

    Sample plugin implementations can be found in src/hbplugins/devicedialogs directory.

    \sa HbDeviceDialogPluginInterface HbDeviceDialogInterface HbDeviceDialog HbPopup

    \stable

    \hbcore

*/

/*!

    \enum HbDeviceDialogPlugin::PluginFlag

    Defines flags for the plugin.

    \sa pluginFlags

*/

/*!

    \var HbDeviceDialogPlugin::PluginFlag HbDeviceDialogPlugin::NoPluginFlags

    No flags specified.

*/

/*!

    \var HbDeviceDialogPlugin::PluginFlag HbDeviceDialogPlugin::PreloadPlugin

    Load plugin on startup. This also implies KeepPluginLoaded flag.

*/

/*!

    \var HbDeviceDialogPlugin::PluginFlag HbDeviceDialogPlugin::KeepPluginLoaded

    Keep the plugin loaded in memory. Flag is ignored for third party plugins.

*/

/*!

    \enum HbDeviceDialogPlugin::DeviceDialogGroup

    Defines device dialog groups. Each of these groups have different rules for showing

    device dialogs.

*/

/*!

    \var HbDeviceDialogPlugin::DeviceDialogGroup HbDeviceDialogPlugin::GenericDeviceDialogGroup

    Common device dialogs.

*/

/*!

    \var HbDeviceDialogPlugin::DeviceDialogGroup HbDeviceDialogPlugin::DeviceNotificationDialogGroup

    Device notification dialogs.

*/

/*!

    \var HbDeviceDialogPlugin::DeviceDialogGroup HbDeviceDialogPlugin::IndicatorGroup

*/

/*!

    \var HbDeviceDialogPlugin::DeviceDialogGroup HbDeviceDialogPlugin::SecurityGroup

*/

/*!

    \var HbDeviceDialogPlugin::DeviceDialogGroup HbDeviceDialogPlugin::CriticalGroup

    High priority dialogs shown on top other dialogs. Only platform device dialogs may

    belong to this group.

*/

/*!

    \enum HbDeviceDialogPlugin::DeviceDialogFlag

    Defines flags for a device dialog created by the plugin.

    \sa deviceDialogInfo() HbIndicatorInterface

*/

/*!

    \var HbDeviceDialogPlugin::DeviceDialogFlag HbDeviceDialogPlugin::NoDeviceDialogFlags

    No flags specified.

*/

/*!

    \var HbDeviceDialogPlugin::DeviceDialogFlag HbDeviceDialogPlugin::SharedDeviceDialog

    <em>For future needs. Not used.</em>

    The device dialog may be shared. Several clients may share the same device dialog instance.

    If the flag is not set, device dialog service doesn't allow sharing of the device dialog.

*/

/*!

    \var HbDeviceDialogPlugin::DeviceDialogFlag HbDeviceDialogPlugin::SecurityCheck

    If the flag is set, device dialog service calls accessAllowed() before creating or

    attaching to a device dialog widget.

*/

/*!

    \var HbDeviceDialogPlugin::DeviceDialogFlag HbDeviceDialogPlugin::SingleInstance

    If the flag is set, only one instance of the device dialog widget is allowed at

    one time. Attempt to launch the widget while one exists results in an error to be

    returned to the client.

*/

/*!

    \var HbDeviceDialogPlugin::DeviceDialogFlag HbDeviceDialogPlugin::ReceiveIndicatorStatus

    Indicates that the device dialog is interested in indicator activation/deactivation events.

    To receive indicator status the dialog has to implement two slots. Indicator activation is

    received by a slot indicatorActivated(HbIndicatorInterface*) and deactivation by a slot

    indicatorDeactivated(HbIndicatorInterface*).

*/

/*!

    \var HbDeviceDialogPlugin::DefaultPriority

    Default priority value to return in DeviceDialogInfo.

*/

/*!

    \struct HbDeviceDialogPlugin::DeviceDialogInfo

    \brief Structure containing device dialog widget information.

    Passed as a parameter to HbDeviceDialogPlugin::deviceDialogInfo().

    \sa HbDeviceDialogPlugin

*/

/*!

    \var HbDeviceDialogPlugin::DeviceDialogInfo::group

    Group the device dialog widget belongs to. HbDeviceDialogPlugin::DeviceDialogGroup.

*/

/*!

    \var HbDeviceDialogPlugin::DeviceDialogInfo::flags

    Device dialog flags. HbDeviceDialogPlugin::DeviceDialogFlag.

*/

/*!

    \var HbDeviceDialogPlugin::DeviceDialogInfo::priority

    <em>For future needs. Not used</em>.

    Device dialog display priority. Determines queuing order of dialogs. Fill with

    HbDeviceDialogPlugin::DefaultPriority.

*/

/*!

    \var HbDeviceDialogPlugin::DeviceDialogInfo::spare

    Spare space for future needs.

*/

/*!

    \fn virtual bool HbDeviceDialogPlugin::accessAllowed(const QString &deviceDialogType,

        const QVariantMap &parameters, const QVariantMap &securityInfo) const = 0

    Checks if client is allowed use the device dialog that the plugin creates. Device dialog service

    calls this function before creating a device dialog or attaching into an existing one if flag

    HbDeviceDialogPlugin::SecurityCheck is set. The implementation is operating system dependent.

    On Symbian this may involve checking client's platform security capabilities or secure ID for

    example. Returns true if client is allowed to use the device dialog.

     \param deviceDialogType Device dialog type.

     \param parameters Device dialog parameters.

     \param securityInfo Information for security check. Content is operating system dependent.

     The format is <key, value> pairs.

     Currently only Symbian is defined.

     <table>

         <caption> Symbian security information </caption>

         <td>Client's capability set as a bitmap. Bit positions correspond to Symbian enum TCapability</td>

         </tr>

     </table>

*/

/*!

    \fn virtual bool HbDeviceDialogPlugin::deviceDialogInfo(const QString &deviceDialogType,

        const QVariantMap &parameters, DeviceDialogInfo *info) const = 0

    Gets information of the device dialog created by the plugin. Device dialog manager calls this

    function before creating the device dialog widget to check

    HbDeviceDialogPlugin::DeviceDialogGroup, HbDeviceDialogPlugin::DeviceDialogFlag and priority.