--- a/src/hbcore/devicedialogbase/hbdevicedialogplugin.cpp Thu Sep 02 20:44:51 2010 +0300
+++ b/src/hbcore/devicedialogbase/hbdevicedialogplugin.cpp Fri Sep 17 08:32:10 2010 +0300
@@ -31,15 +31,19 @@
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,
- device dialog are displayed on client's mainwindow.
+ \section _creation Creation of device dialogs
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
@@ -48,18 +52,7 @@
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
- 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.
+ \subsection _widgets Dialog widgets
Device dialog widgets have to be derived from HbPopup either directly or by ancestry.
@@ -69,19 +62,28 @@
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">
- <b>For future needs. Not implemented.</b>
- Device dialog may be shared by several device dialog clients. Each client can update the
- 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 %
- separator. For example here the tag "#1" is appended into device dialog type
- "hb.devicedialog.note/1.0%#1". If a device dialog instance exists, a client is attached into it
- instead of creating a new one. To allow sharing, plugin must set
- HbDeviceDialogPlugin::SharedDeviceDialog.
- </div>
+ \section _types Types of device dialogs
+
+ Device dialogs are divided into four groups:
+
+ - Generic
+ - Notification
+ - Indicator-menu
+ - Security
- <b>Symbian.</b>Plugins are run by a server with platform security capabilities ProtServ, SwEvent,
- TrustedUI and ReadDeviceData.
+ 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.
+ Each dialog indicates which group it belongs to. The group need not be fixed.
+ 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
@@ -91,16 +93,7 @@
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
- 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.
+ \section _checklist Checklist for well behaving device dialogs
Well behaving dialog widget should observe following rules:
- Should not create and show other dialogs
@@ -108,6 +101,34 @@
- 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
@@ -459,24 +480,10 @@
Currently only Symbian is defined.
<table>
<caption> Symbian security information </caption>
- <tr>
- <th>Key</th>
- <th>Value type</th>
- <th>Description</th>
- </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>
+ <tr><th>Key</th><th>Value type</th><th>Description</th></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>
@@ -536,7 +543,7 @@
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
@@ -637,8 +644,9 @@
\fn virtual HbDeviceDialogPluginInterface *HbDeviceDialogPluginInterface::createDeviceDialog(
const QString &deviceDialogType, const QVariantMap ¶meters) = 0
- Creates a device dialog widget. The widget becomes visible immediately. Returns a pointer to
- the device dialog widget interface or null if widget cannot be created.
+ Called by device dialog framework to create a device dialog widget. The widget should be
+ 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