28     \brief HbDeviceDialog displays dialogs on top of applications

    30     \brief HbDeviceDialog displays a dialog on top of all running applications

    29 

    31     

    30     HbDeviceDialog is a concrete class. It can be used directly or as a part of

    32     Device Dialogs are used to display information, queries and alerts for the device rather than

    31     specialization classes for different device dialog types. It's not a widget but interfaces

    33     for an application. Some example device dialogs are:

    32     to a device dialog service which is responsible for displaying device dialogs.

    34     - Low battery

    33     Device dialog widgets are implemented in plugins loaded by the service.

    35     - Low memory

    34 

    36     - Incoming bluetooth message

    35     Below is a runtime view of device dialog framework.

    37     - Text message received

    38     

    39     Due to the importance of these dialogs they are

    40     displayed on top of all applications. The HbDeviceDialog class provides the client

    41     interface for creating these dialogs. This differs from other dialog classes such as 

    42     HbMessageBox in that 

    43     HbDeviceDialog is not a widget but is the interface to a framework that handles the dialogs.

    44     

    45     \section _framework Device Dialog Framework

    46     

    47     Any application is able to generate device dialogs. However, in

    48     order to display the dialogs on top of all applications, the device dialog framework 

    49     uses a server. To display a dialog an application uses the HbDeviceDialog client interface to send requests for

    50     dialogs to the server. The HbDeviceDialog class can also be used or extended as part of a set of specialization classes

    51     to create different device dialog types. 

    52     

    53     Device dialog widgets are implemented in plugins loaded by the server.

    54 

    55     Shown below is a runtime view of the device dialog framework.

   111     There are three classes of device dialogs. Generic device dialogs which are displayed on top

   134     \section _types Types of device dialogs

   112     of all applications (incoming call is an exception). Examples of these are "Low memory"

   135 

   113     message box and "Receive message via bluetooth" query. Device notification dialogs are

   136     There are three classes of device dialogs:

   114     notifications displayed in a top left corner of a display. Examples are "New message" and

   137      -# Generic device dialogs are displayed on top

   115     "Low battery" notifications. Universal indicator menu shows enhanced status indicator

   138     of all applications, except in the case of an incoming call. Examples of these are a "Low memory"

   139     message box and a "Receive message via bluetooth?" query. 

   140      -# Device notification dialogs are

   141     notifications displayed in the top left corner of the display. Examples are "New message" and

   142     "Low battery" notifications. 

   143      -# The Universal indicator menu shows enhanced status indicator

   118     Generic device dialogs and indicator menu interrupt current foreground application.

   146     Generic device dialogs and the indicator menu interrupt the current foreground application.

   119     User cannot interact with the application with a touch or keyboard until the dialog

   147     The user cannot interact with the application with a touch or keyboard until the dialog

   120     is dismissed. Device notification dialog behaves differently allowing interaction with the

   148     is dismissed. Device notification dialogs behave differently allowing interaction with the

   125     Widgets are implemented by plugins. Device dialog type is an unique string identifying the

   153     The device dialog type is a unique string identifying the

   129     Parameter set is encapsulated in QMap<QString, QVariant>. Each device dialog implementation has

   157     The parameter set is encapsulated in QMap<QString, QVariant>. Each device dialog implementation has

   130     a default value for all parameters. Only parameters that differ from the default needs to be

   158     a default value for all parameters. Only parameters that differ from the default need to be

   137     Data can be sent to a device dialog after it has been launched using update() function. Data

   165     %Data can be sent to a device dialog after it has been launched using the update() function. %Data

   138     sent by the dialog is received by dataReceived signal. A copy of the last data received

   166     sent by the dialog is received by the dataReceived signal. A copy of the last data received

   139     is held by the class and can be fetched by a receivedData() function. This allows to receive

   167     is held by the class and can be fetched by a call to the receivedData() function. This allows data to be received

   140     data without having to connect to a signal by waiting for a dialog to close and then

   168     without having to connect to a signal by waiting for a dialog to close and then

   144     However if there is a need to update a dialog or receive data from it, only the last one

   172     However if there is a need to update a dialog or receive data from it, only the last dialog

   145     launched is able to do it. In this case instantiate HbDeviceDialog class for each device dialog

   173     launched supports this. In this case instantiate the HbDeviceDialog class for each device dialog

   148     HbDeviceDialog::show() method returns after device dialog service has accepted the dialog.

   176     HbDeviceDialog::show() method returns after the device dialog service has accepted the dialog.

   150     data from the dialog widget, HbDeviceDialog object can be destroyed after show method returns

   178     data from the dialog widget, the HbDeviceDialog object can be destroyed after the show() method returns

   151     (can be allocated in a stack). A function is provided to wait for device dialog to be dismissed

   179     (can be allocated in a stack). A function is provided to wait for the device dialog to be dismissed,

   155     dialog is dismissed. In this case device dialog service will close all dialogs

   183     dialog is dismissed. In this case the device dialog service will close all dialogs

   162     When HbDeviceDialog object is created, it can reserve a communication channel to device dialog

   190     When the HbDeviceDialog object is created, it can reserve a communication channel to the device dialog

   164     flag. Default is the delayed resource reservation.

   192     flag. The default is the delayed resource reservation.

   165 

   193 

   166     HbDeviceDialog class is not thread safe. If cancel() needs to called across threads, a queued

   194     The HbDeviceDialog class is not thread safe. If cancel() needs to called across threads, a queued

   168 

   196     

   169     \sa HbDeviceDialogPlugin

   197     \section _usecases Using the HbDeviceDialog class

   170 

   198     

   171     \beta

   199     The code below launches a device dialog and continues execution

   172     \hbcore

   173 */

   174 

   175 /*!

   176     \enum HbDeviceDialog::DeviceDialogError

   177     Defines device dialog error codes and ranges.

   178 */

   179 /*!

   180     \var HbDeviceDialog::DeviceDialogError HbDeviceDialog::FrameworkErrors

   181     Start of an error range for errors originating from device dialog framework (client or server).

   182 */

   183 /*!

   184     \var HbDeviceDialog::DeviceDialogError HbDeviceDialog::PluginErrors

   185     Start of an error range for errors originating from device dialog plugins. The framework passes

   186     these from the plugin unmodified.

   187 */

   188 /*!

   189     \var HbDeviceDialog::DeviceDialogError HbDeviceDialog::ErrorTypeMask

   190     Mask for error type part of the error code.

   191 */

   192 /*!

   193     \var HbDeviceDialog::DeviceDialogError HbDeviceDialog::CancelledError

   194     Operation was cancelled by cancel().

   195 */

   196 /*!

   197     \var HbDeviceDialog::DeviceDialogError HbDeviceDialog::SystemCancelledError

   198     Operation was cancelled by device dialog framework.

   199 */

   200 

   201 /*!

   202     \enum HbDeviceDialog::DeviceDialogFlags

   203     Defines construct flags.

   204 */

   205 /*!

   206     \var HbDeviceDialog::DeviceDialogFlags HbDeviceDialog::NoDeviceDialogFlags

   207     No flags specified.

   208 */

   209 /*!

   210     \var HbDeviceDialog::DeviceDialogFlags HbDeviceDialog::NoFlags

   211     No flags specified.

   212 */

   213 /*!

   214     \var HbDeviceDialog::DeviceDialogFlags HbDeviceDialog::ImmediateResourceReservationFlag

   215     Reserves resources immediately instead of delaying until show() is called.

   216 */

   217 

   218 /*!

   219      \fn void HbDeviceDialog::dataReceived(QVariantMap data)

   220 

   221       This signal is emitted when data is received from a device dialog. \a data contains data from

   222       the dialog. The structure and meaning of the data is a contract between the dialog and

   223       a client. Suggested usage is a set of signal names and parameters.

   224 */

   225 

   226 /*!

   227     \fn void HbDeviceDialog::deviceDialogClosed()

   228 

   229     This signal is emitted when a device dialog is closed. Any data sent by the dialog is indicated by

   230     the dataReceived() signal. If the signal is not connected, latest data received is saved and

   231     can be retrieved by a receivedData() function.

   232 

   233     \sa dataReceived() receivedData()

   234 */

   235 

   236 /*!

   237     \fn void HbDeviceDialog::error(int error)

   238 

   239     This signal is emitted when an error has occurred. \a error contains an error code.

   240 */

   241 

   242 #include "hbdevicedialog.h"

   243 

   244 #include <QtGlobal>

   245 

   246 // Device dialogs are implemented only for Symbian/S60 OS. All others use a stub which shows

   247 // device dialogs in the calling process.

   248 #if defined(Q_OS_SYMBIAN)

   249 #include "hbdevicedialogsym_p.h"

   250 #else

   251 #include "hbdevicedialogwin32_p.h"

   252 #endif // defined(Q_OS_SYMBIAN)

   253 

   254 /*!

   255     Constructs an object. \a f contains construct flags. \a parent is a parent pointer.

   256     HbDeviceDialog can be allocated into a stack if no signals are to be connected. Device dialog

   257     service keeps dialogs launched when the object goes out of scope. If any signals

   258     are connected, device dialog service will clean all dialogs launched when the instance is

   259     deleted. In this case the object must remain in existence until the dialog widget is

   260     dismissed.

   261 */

   262 HbDeviceDialog::HbDeviceDialog(DeviceDialogFlags f, QObject *parent) :

   263     QObject(parent), d_ptr(new HbDeviceDialogPrivate)

   264 {

   265     Q_D(HbDeviceDialog);

   266     d->q_ptr = this;

   267     d->init(f);

   268 }

   269 

   270 HbDeviceDialog::HbDeviceDialog(HbDeviceDialogPrivate &dd, DeviceDialogFlags f, QObject *parent) :

   271     QObject(parent), d_ptr(&dd)

   272 {

   273     Q_D(HbDeviceDialog);

   274     d->q_ptr = this;

   275     d->init(f);

   276 }

   277 

   278 HbDeviceDialog::~HbDeviceDialog()

   279 {

   280     delete d_ptr;

   281 }

   282 

   283 /*!

   284     Shows a device dialog using a device dialog service. The function returns immediately after the

   285     service has accepted the dialog. Returns true if dialog was accepted, false if error occurred.

   286     The service decides when the dialog is actually displayed.

   287 

   288     \arg deviceDialogType identifies a device dialog to be displayed by a name.

   289     \arg parameters defines properties of the dialog.

   290 

   291     \sa update(), waitForClosed(), cancel()

   292 

   294     // Below code launches a device dialog and continues execution.

   201     // Launch a device dialog and continue execution.

   304     // Below code has HbDeviceDialog as a member variable. It connects signals and launches a device dialog.

   212     // Connect signals and launch a device dialog.

   312     \endcode

   220     \endcode    

   313 */

   221     

   314 bool HbDeviceDialog::show(const QString &deviceDialogType, const QVariantMap &parameters)

   222     The code below shows how to wait until a dialog has closed

   315 {

   316     return d_func()->show(deviceDialogType, parameters);

   317 }

   318 

   319 /*!

   320     Updates device dialog parameters by a set of new values. show() must be called before an

   321     update() can be called. If multiple dialogs have been launched by a single HbDeviceDialog

   322     instance, the last dialog launched receives the update. Returns true on success and false

   323     if error occurred.

   324 

   325     \sa show()

   326 */

   327 bool HbDeviceDialog::update(const QVariantMap &parameters)

   328 {

   329     return d_func()->update(parameters);

   330 }

   331 

   332 /*!

   333     Waits for a device dialog to be displayed and dismissed. \a flags specifies flags passed to

   334     QEventLoop::exec() function. Returns true on success and false if error occurred.

   335 

   336     The wait is implemented by starting a new event loop. Consider following caveats before using

   337     this function. Stack usage increases. Depending on application program flow, several event

   338     loops may get instantiated on top of each other. Application event processing continues while

   339     waitForClosed() executes. When it returns application state may have changed. For example some

   340     objects may have been deleted or application may have exited.

   341 

   342     <b>Note that starting an event loop isn't compatible with gestures.</b> Therefore if an application

   343     has an user interface, please don't use this function. Instead connect to signals.

   344 

   345     \sa cancel()

   346 

   366     Returns the latest data received from a device dialog. This function can be called instead of

   424     Returns the latest data received from a device dialog.

   367     connecting to dataReceived() signal. If dataReceived() signal has connections, latest data is

   425 

   368     not saved and this function returns empty data structure.

   426     This function can be called instead of

   427     connecting to the dataReceived() signal. If the dataReceived() signal has connections, the latest data is

   428     not saved and this function returns an empty data structure.

   378     Returns a last error. Last error is cleared when any other API function than error() is called.

   438     Returns the last error.

   439 

   440     The last error is cleared when any other API function except error() is called.

   386     Cancels a device dialog. The dialog is removed from the device dialog service. Does nothing if

   448     Cancels a device dialog and removes the dialog from the device dialog service.

   387     the dialog has already been dismissed. Removes dialog if it's waiting to be displayed or

   449 

   388     currently on display. If multiple dialogs have been launched by a single HbDeviceDialog

   450     Removes the dialog if the dialog is waiting to be displayed or

   389     instance, the last dialog launched is cancelled. deviceDialogClosed() signal is emitted if

   451     currently on display. Has no effect if

   390     a dialog was closed. Returns true on success and false if error occurred.

   452     the dialog has already been dismissed. If multiple dialogs have been launched by a single HbDeviceDialog

   453     instance, the last dialog launched is cancelled. The deviceDialogClosed() signal is emitted if

   454     a dialog was closed.

   455 

   456     \return Returns \c true on success and \c false if an error occurred.