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

equal deleted inserted replaced

-:e6ad4ef83b23
+:b7da29130b0e
 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).
-<b>Platform dependent.</b> Currently server is implemented only for Symbian platform. On other platforms,
+\section _creation Creation of device dialogs
-device dialog are displayed on client's mainwindow.
 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.
+\subsection _identification Identification
 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.
+\subsection _versioning Versioning
 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 dialogs are divided into four groups: generic, notification, indicator-menu and security
+\subsection _widgets Dialog widgets
-groups. The group dictates how and when a dialog is shown. Generic and
-notification dialogs are intended for application use. Indicator and security dialogs are
-for platform. Each dialog indicates which group it belongs to. The group need not be fixed.
-It may change depending on create parameters.
-Device dialog groups may prioritize (queueing) device dialogs in respect to other groups.
-In addition each device dialog has an individual queueing priority that may affect how it is
-shown inside a group. Currently there is no queueing implemented for device dialogs. All
-dialogs are displayed in order requests are received. Z-order of dialogs on display is
-determined by popup framework. Last dialog created is on top. Device dialog framework
-manipulates Z-order of dialogs. Device dialogs themselves should not change the popup Z-order.
 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.
-<div style="color:gray">
+\section _types Types of device dialogs
-<b>For future needs. Not implemented.</b>
-Device dialog may be shared by several device dialog clients. Each client can update the
+Device dialogs are divided into four groups:
-device dialog and receive signals from it equally. Clients attach to a shared device dialog
-instance by agreeing on an unique tag. The tag is appended into device dialog type with a %
+- Generic
-separator. For example here the tag "#1" is appended into device dialog type
+- Notification
-"hb.devicedialog.note/1.0%#1". If a device dialog instance exists, a client is attached into it
+- Indicator-menu
-instead of creating a new one. To allow sharing, plugin must set
+- Security
-HbDeviceDialogPlugin::SharedDeviceDialog.
-</div>
+The group dictates how and when a dialog is shown. Generic and notification dialogs are
+intended for application use. Indicator-menu and security dialogs are for platform.
-<b>Symbian.</b>Plugins are run by a server with platform security capabilities ProtServ, SwEvent,
+Each dialog indicates which group it belongs to. The group need not be fixed.
-TrustedUI and ReadDeviceData.
+It may change depending on create parameters.
+\subsection _priority Priority
+Device dialog groups prioritize device dialogs (z-order) in respect to other groups.
+Dialogs belonging to the same group are displayed in order requests are received.
+Popup framework is utilized to manage z-order of dialogs. Z-order is set by devicedialog
+framework and device dialogs themselves should not change the popup z-order.
+\section _security Security
 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.
-<b>Symbian.</b>Device dialog plugins can be installed into a device. If a plugin doesn't have
+\section _checklist Checklist for well behaving device dialogs
-required platform security capabilities it will not load. Plugins are searched from device's
-local drives. The search order is rom-drives, non-removable drives and removable drives. Once
-a pluging is found the search stops. This implies that plugins on rom drives cannot be
-overridden by plugins on other drives.
-<b>Platform dependent.</b>Plugin location differs depending on platform. On Symbian, device dialog
-plugin stubs (.qtplugin) are located in /resource/plugins/devicedialogs directory and executables
-in /sys/bin directory. On other platforms plugin executables are searched from application's
-current directory and HB_PLUGINS_DIR/devicedialogs directory.
 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
+\section _platform_hbdevicedialogplugin Platform-specific implementation notes for HbDeviceDialogPlugin
+\subsection _nonsymbian Non-Symbian
+The server is implemented only for the Symbian platform. On other platforms, plugins are loaded into client
+process and dialogs shown on client's main window.
+Plugin executables are searched from application's current directory and HB_PLUGINS_DIR/devicedialogs
+directory.
+\subsection _symbian Symbian
+Plugins are run by a server with platform security capabilities ProtServ, SwEvent,
+TrustedUI and ReadDeviceData. If a plugin doesn't have required platform security
+capabilities it will not load.
+Device dialog plugins can be installed into a device. Plugins are searched from device's
+local drives. The search order is rom-drives, non-removable drives and removable drives.
+Search order inside each group is alphabethical. Eclipsing is allowed only if plugin file
+names are the same. This means that in order to replace a device dialog in a plugin earlier
+in search order, the file name of the replacement plugin has to be the same as the the one
+it replaces.
+Device dialog plugin stubs (.qtplugin) are searched from /resource/plugins/devicedialogs directory
+and executables in /sys/bin directory in each drive.
+\section _creation Creating a plugin
 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
 \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>
-<tr>
+<tr><th>Key</th><th>Value type</th><th>Description</th></tr>
-<th>Key</th>
+<tr><td>"sym-secureId"</td><td>quint32</td><td>Client's secure ID</td></tr>
-<th>Value type</th>
+<tr><td>"sym-vendorId"</td><td>quint32</td><td>Client's vendor ID</td></tr>
-<th>Description</th>
+<tr><td>"sym-caps"</td><td>quint32</td>
-</tr>
-<tr>
-<td>"sym-secureId"</td>
-<td>quint32</td>
-<td>Client's secure ID</td>
-</tr>
-<tr>
-<td>"sym-vendorId"</td>
-<td>quint32</td>
-<td>Client's vendor ID</td>
-</tr>
-<tr>
-<td>"sym-caps"</td>
-<td>quint32</td>
 <td>Client's capability set as a bitmap. Bit positions correspond to Symbian enum TCapability</td>
 </tr>
 </table>
 */
 Device dialog widgets must be derived from HbPopup or derivatives as described in
 HbDeviceDialogPlugin.
 Following popup convention, the widget is not visible immediately after is created.
-Device dialog framework calls HbPopup::show() to display the widget. The service may change
+Device dialog framework calls HbPopup::show() to display the widget.
 The service may change visibility of the widget by HbPopup::setVisible function.
 The widget should close itself by either a timeout or user interaction. It may also be closed
 gracefully either by system or the client by a closeDeviceDialog() function. It is assumed that
 the widget object can be ungracefully destroyed (delete) at any time.
 /*!
 \fn virtual HbDeviceDialogPluginInterface *HbDeviceDialogPluginInterface::createDeviceDialog(
 const QString &deviceDialogType, const QVariantMap &parameters) = 0
-Creates a device dialog widget. The widget becomes visible immediately. Returns a pointer to
+Called by device dialog framework to create a device dialog widget. The widget should be
-the device dialog widget interface or null if widget cannot be created.
+left unvisible. The framework calls show() at a suitable time to make it visible.
+Returns a pointer to the device dialog widget interface or null if widget cannot be created.
 \param deviceDialogType Device dialog type to create.
 \param parameters Device dialog parameters. The structure and meaning of parameters is a
 contract between the plugin and a client.

changeset 28	b7da29130b0e
parent 23	e6ad4ef83b23
child 30	80e4d18b72f5