FCL/sf/mw/hb: comparison src/hbcore/devicedialogbase/hbdevicedialog.cpp

equal deleted inserted replaced

-:e6ad4ef83b23
+:b7da29130b0e
 HbDeviceDialog is not a widget but is the interface to a framework that handles the dialogs.
 \section _framework Device Dialog Framework
 Any application is able to generate device dialogs. However, in
 order to display the dialogs on top of all applications, the device dialog framework
-uses a server. To display a dialog an application uses the HbDeviceDialog client interface to send requests for
+uses a server. To display a dialog an application uses the HbDeviceDialog client interface
-dialogs to the server. The HbDeviceDialog class can also be used or extended as part of a set of specialization classes
+to send requests for dialogs to the server. The HbDeviceDialog class can also be used or
-to create different device dialog types.
+extended as part of a set of specialization classes to create different device dialog types.
 Device dialog widgets are implemented in plugins loaded by the server.
 Shown below is a runtime view of the device dialog framework.
 deviceDialogManager -> deviceDialog1 [label = "data"];
 deviceDialogManager -> deviceDialog2 [label = "data"];
 }
 \enddot
-<b>Platform dependent.</b> Currently server is implemented only for Symbian platform. On other platforms,
+HbDeviceDialog has no dependencies to other parts of the framework. Only to Qt.
-device dialog are displayed on client's mainwindow.
+Thus it can be used also from engine components that have no user interface.
-HbDeviceDialog has no dependencies to other parts of the framework. Only to Qt. Thus it can be used
-also from engine components that have no user interface.
 \section _types Types of device dialogs
-There are three classes of device dialogs:
+There are two classes of device dialogs intended for application use:
 -# Generic device dialogs are displayed on top
 of all applications, except in the case of an incoming call. Examples of these are a "Low memory"
 message box and a "Receive message via bluetooth?" query.
 -# Device notification dialogs are
 notifications displayed in the top left corner of the display. Examples are "New message" and
 "Low battery" notifications.
--# The Universal indicator menu shows enhanced status indicator
-information.
+Generic device dialogs interrupt the current foreground application.
-Generic device dialogs and the indicator menu interrupt the current foreground application.
 The user cannot interact with the application with a touch or keyboard until the dialog
 is dismissed. Device notification dialogs behave differently allowing interaction with the
-current foreground application.
+current foreground application. Another difference is that notification dialogs are shown
+serially instead of on top of each other.
+In addition, there are two device dialogs classes intended for platform use: Indicator menu and security.
+\section _operation Operation of device dialogs
+\subsection _construction Construction and identification
 Device dialog widgets are constructed dynamically by the device dialog service. Construction
 takes two parameters: a type and a set of parameters appropriate to the dialog type.
-The device dialog type is a unique string identifying the
+The device dialog type is a unique string identifying the dialog. A search is made to find a
-dialog. A search is made to find a plugin that can instantiate the requested
+plugin that can instantiate the requested dialog. The service loads the plugin and creates an
-dialog. The service loads the plugin and creates an instance of the widget.
+instance of the widget.
-The parameter set is encapsulated in QMap<QString, QVariant>. Each device dialog implementation has
+The parameter set is encapsulated in QMap<QString, QVariant>. Each device dialog implementation
-a default value for all parameters. Only parameters that differ from the default need to be
+has a default value for all parameters. Only parameters that differ from the default need to be
 given. Parameters are <name, value> pairs. How the parameters are used depends on
 the plugin implementing the dialog. Suggested usage is <name, value> used as property
 name and value pairs of the dialog implementation. This makes it easy to set properties using
 QObject::setProperty(const char*, const QVariant&). If data types supported by QVariant are
 not suitable for a specific device dialog, Q_DECLARE_METATYPE can be used to add data types.
-%Data can be sent to a device dialog after it has been launched using the update() function. %Data
+\subsection _updating Updating and receiving data
-sent by the dialog is received by the dataReceived signal. A copy of the last data received
-is held by the class and can be fetched by a call to the receivedData() function. This allows data to be received
+%Data can be sent to a device dialog after it has been launched using the update() function.
-without having to connect to a signal by waiting for a dialog to close and then
+%Data sent by the dialog is received by the dataReceived signal. A copy of the last data
-getting the received data.
+received is held by the class and can be fetched by a call to the receivedData() function.
+This allows data to be received without having to connect to a signal by waiting for a dialog
+to close and then getting the received data.
+\subsection _showing Showing device dialogs
 It is possible to launch multiple device dialogs from a single HbDeviceDialog object.
 However if there is a need to update a dialog or receive data from it, only the last dialog
-launched supports this. In this case instantiate the HbDeviceDialog class for each device dialog
+launched supports this. In this case instantiate the HbDeviceDialog class for each device
-that needs communication (update or data receive) after a launch.
+dialog that needs communication (update or data receive) after a launch.
 HbDeviceDialog::show() method returns after the device dialog service has accepted the dialog.
-The service decides when the dialog is actually displayed. If there is no need to receive
+The service decides when the dialog is actually displayed. No assumption should be made
-data from the dialog widget, the HbDeviceDialog object can be destroyed after the show() method returns
+about the timing when the dialog will display. It may get delayed depending on system state.
-(can be allocated in a stack). A function is provided to wait for the device dialog to be dismissed,
+If there is no need to receive data from the dialog widget, the HbDeviceDialog object can be
-making the dialog display synchronous.
+destroyed after the show() method returns (can be allocated in a stack). In this case,
+it is assumed that the dialog widget closes itself by a timeout. System will close dialog
+widgets left running this way without a corresponding HbDialog instance, after 10 seconds.
 If any signals of HbDeviceDialog are connected, then the instance needs to exist until the
-dialog is dismissed. In this case the device dialog service will close all dialogs
+dialog widget is dismissed. In this case the device dialog service will close all dialogs
-launched by the instance when it is deleted making it inappropriate to allocate HbDeviceDialog
+launched by the HbDeviceDialog instance when it is deleted making it inappropriate to allocate
-into a stack.
+it into a stack.
-Several clients can share the same device dialog widget by agreeing on an unique tag. See
+A function is provided to wait for the device dialog to be dismissed, making the dialog
-HbDeviceDialogWidgetPlugin for more information.
+display synchronous.
+\subsection _misc Miscellaneous notes
 When the HbDeviceDialog object is created, it can reserve a communication channel to the device dialog
 service or the channel creation may be delayed until show(). This is controlled by a constructor
 flag. The default is the delayed resource reservation.
 The HbDeviceDialog class is not thread safe. If cancel() needs to called across threads, a queued
 signal slot connection can be used.
+\section _platform_hbdevicedialog Platform-specific implementation notes for HbDeviceDialog
+\subsection _nonsymbian_hbdevicedialog Non-Symbian
+The server is implemented only for the Symbian platform. On other platforms device dialogs are
+displayed on client's main window.
 \section _usecases Using the HbDeviceDialog class
 The code below launches a device dialog and continues execution
 \code
-// Launch a device dialog and continue execution.
+// Launch a device dialog and continue execution. Assumes that the dialog widget closes
+// itself by a timeout.
 HbDeviceDialog deviceDialog;
 QVariantMap parameters;
 parameters.insertMulti(QString("text"), QVariant(QString("Warning text")));
 const char *deviceDialogType = "hb.devdlg.examplemessagebox/1.0";
 A device dialog widget is a single instance and already exists (has been launched).
 See HbDeviceDialogPlugin::SingleInstance.
 */
 /*!
+\enum HbDeviceDialog::DeviceDialogFlag
+Defines construct flags.
+*/
+/*!
 \var HbDeviceDialog::DeviceDialogFlags HbDeviceDialog::NoFlags
 No flags specified.
-*/
-/*!
-\enum HbDeviceDialog::DeviceDialogFlag
-Defines construct flags.
-The DeviceDialogFlags type is a typedef for QFlags<DeviceDialogFlag>. It stores an OR combination of the DeviceDialogFlag values.
 */
 /*!
 \var HbDeviceDialog::DeviceDialogFlags HbDeviceDialog::ImmediateResourceReservationFlag
 Reserves resources immediately instead of delaying until show() is called.
 }
 /*!
 Shows a device dialog using the device dialog service.
-The function returns immediately after the
+The function returns immediately after the service has accepted the dialog.
-service has accepted the dialog. Returns \c true if the dialog was accepted, \c false if an error occurred.
+Returns \c true if the dialog was accepted, \c false if an error occurred.
-The service decides when the dialog is actually displayed.
+The service decides when the dialog is actually displayed. Displaying may be delayed
+depending on system state.
 \param deviceDialogType Identifies a device dialog to be displayed by a name.
 \param parameters Defines properties of the dialog.
 \sa update(), waitForClosed(), cancel()

changeset 28	b7da29130b0e
parent 5	627c4a0fd0e7
child 30	80e4d18b72f5