29 |
29 |
30 Device dialogs are widgets which are shown on top of all applications by a device dialog |
30 Device dialogs are widgets which are shown on top of all applications by a device dialog |
31 service. The service queues and displays device dialogs according to client requests and |
31 service. The service queues and displays device dialogs according to client requests and |
32 system state. The service displays widgets in it's window (HbApplication window). |
32 system state. The service displays widgets in it's window (HbApplication window). |
33 |
33 |
34 <b>Platform dependent.</b> Currently server is implemented only for Symbian platform. On other platforms, |
34 \section _creation Creation of device dialogs |
35 device dialog are displayed on client's mainwindow. |
|
36 |
35 |
37 Device dialog widgets are created by plugins. The service loads a plugin to create and display |
36 Device dialog widgets are created by plugins. The service loads a plugin to create and display |
38 a device dialog. A single plugin may implement several different dialogs or just one. |
37 a device dialog. A single plugin may implement several different dialogs or just one. |
|
38 |
|
39 \subsection _identification Identification |
|
40 |
39 Dialogs are identified by a string. By convention the string should follow |
41 Dialogs are identified by a string. By convention the string should follow |
40 inverted domain name format. For example com.nokia.hb.devicedialog.note/1.0. |
42 inverted domain name format. For example com.nokia.hb.devicedialog.note/1.0. |
41 Function deviceDialogTypes() returns a list of dialog types the plugin implements. |
43 Function deviceDialogTypes() returns a list of dialog types the plugin implements. |
|
44 |
|
45 \subsection _versioning Versioning |
42 |
46 |
43 Appending version number into device dialog type string enables versioning of device dialogs. |
47 Appending version number into device dialog type string enables versioning of device dialogs. |
44 A plugin should handle versioning by returning device dialog type string for all versions it |
48 A plugin should handle versioning by returning device dialog type string for all versions it |
45 implements in deviceDialogTypes() and then in createDeviceDialog() create a device dialog |
49 implements in deviceDialogTypes() and then in createDeviceDialog() create a device dialog |
46 instance compatible with the version requested. This could always be the latest version if it |
50 instance compatible with the version requested. This could always be the latest version if it |
47 is backwards compatible with older versions. Device dialog framework is unaware of version |
51 is backwards compatible with older versions. Device dialog framework is unaware of version |
48 numbers in type strings. It performs string comparison of the whole string when searching |
52 numbers in type strings. It performs string comparison of the whole string when searching |
49 for a plugin. |
53 for a plugin. |
50 |
54 |
51 Device dialogs are divided into four groups: generic, notification, indicator-menu and security |
55 \subsection _widgets Dialog widgets |
52 groups. The group dictates how and when a dialog is shown. Generic and |
|
53 notification dialogs are intended for application use. Indicator and security dialogs are |
|
54 for platform. Each dialog indicates which group it belongs to. The group need not be fixed. |
|
55 It may change depending on create parameters. |
|
56 |
|
57 Device dialog groups may prioritize (queueing) device dialogs in respect to other groups. |
|
58 In addition each device dialog has an individual queueing priority that may affect how it is |
|
59 shown inside a group. Currently there is no queueing implemented for device dialogs. All |
|
60 dialogs are displayed in order requests are received. Z-order of dialogs on display is |
|
61 determined by popup framework. Last dialog created is on top. Device dialog framework |
|
62 manipulates Z-order of dialogs. Device dialogs themselves should not change the popup Z-order. |
|
63 |
56 |
64 Device dialog widgets have to be derived from HbPopup either directly or by ancestry. |
57 Device dialog widgets have to be derived from HbPopup either directly or by ancestry. |
65 |
58 |
66 Device dialog widget can be derived from existing Hb class, eg. HbDialog or constructed from |
59 Device dialog widget can be derived from existing Hb class, eg. HbDialog or constructed from |
67 a docml using HbDocumentLoader. Structure of the plugin differs depending on which approach |
60 a docml using HbDocumentLoader. Structure of the plugin differs depending on which approach |
68 is selected. If docml is used the dialog widget cannot be multiple inherited from HbDialog |
61 is selected. If docml is used the dialog widget cannot be multiple inherited from HbDialog |
69 and HbDeviceDialogInterface. In this case a container can be used to to create and manage the |
62 and HbDeviceDialogInterface. In this case a container can be used to to create and manage the |
70 widget. See code example at the end. |
63 widget. See code example at the end. |
71 |
64 |
72 <div style="color:gray"> |
65 \section _types Types of device dialogs |
73 <b>For future needs. Not implemented.</b> |
66 |
74 Device dialog may be shared by several device dialog clients. Each client can update the |
67 Device dialogs are divided into four groups: |
75 device dialog and receive signals from it equally. Clients attach to a shared device dialog |
68 |
76 instance by agreeing on an unique tag. The tag is appended into device dialog type with a % |
69 - Generic |
77 separator. For example here the tag "#1" is appended into device dialog type |
70 - Notification |
78 "hb.devicedialog.note/1.0%#1". If a device dialog instance exists, a client is attached into it |
71 - Indicator-menu |
79 instead of creating a new one. To allow sharing, plugin must set |
72 - Security |
80 HbDeviceDialogPlugin::SharedDeviceDialog. |
73 |
81 </div> |
74 The group dictates how and when a dialog is shown. Generic and notification dialogs are |
82 |
75 intended for application use. Indicator-menu and security dialogs are for platform. |
83 <b>Symbian.</b>Plugins are run by a server with platform security capabilities ProtServ, SwEvent, |
76 Each dialog indicates which group it belongs to. The group need not be fixed. |
84 TrustedUI and ReadDeviceData. |
77 It may change depending on create parameters. |
|
78 |
|
79 \subsection _priority Priority |
|
80 |
|
81 Device dialog groups prioritize device dialogs (z-order) in respect to other groups. |
|
82 Dialogs belonging to the same group are displayed in order requests are received. |
|
83 Popup framework is utilized to manage z-order of dialogs. Z-order is set by devicedialog |
|
84 framework and device dialogs themselves should not change the popup z-order. |
|
85 |
|
86 \section _security Security |
85 |
87 |
86 Plugins are responsible for maintaining system security for their own part. If plugin |
88 Plugins are responsible for maintaining system security for their own part. If plugin |
87 performs operations that may compromise security or want's to limit access to specific |
89 performs operations that may compromise security or want's to limit access to specific |
88 clients, it should check client security credentials in accessAllowed() function. |
90 clients, it should check client security credentials in accessAllowed() function. |
89 Device dialog framework calls this function before creating or attaching client to a |
91 Device dialog framework calls this function before creating or attaching client to a |
90 plugin if HbDeviceDialogPlugin::SecurityCheck is set. Access is denied if the |
92 plugin if HbDeviceDialogPlugin::SecurityCheck is set. Access is denied if the |
91 function returns false. In addition, HbDeviceDialogPlugin constructor has a check which |
93 function returns false. In addition, HbDeviceDialogPlugin constructor has a check which |
92 allows only device dialog service to load plugins derived from it. |
94 allows only device dialog service to load plugins derived from it. |
93 |
95 |
94 <b>Symbian.</b>Device dialog plugins can be installed into a device. If a plugin doesn't have |
96 \section _checklist Checklist for well behaving device dialogs |
95 required platform security capabilities it will not load. Plugins are searched from device's |
|
96 local drives. The search order is rom-drives, non-removable drives and removable drives. Once |
|
97 a pluging is found the search stops. This implies that plugins on rom drives cannot be |
|
98 overridden by plugins on other drives. |
|
99 |
|
100 <b>Platform dependent.</b>Plugin location differs depending on platform. On Symbian, device dialog |
|
101 plugin stubs (.qtplugin) are located in /resource/plugins/devicedialogs directory and executables |
|
102 in /sys/bin directory. On other platforms plugin executables are searched from application's |
|
103 current directory and HB_PLUGINS_DIR/devicedialogs directory. |
|
104 |
97 |
105 Well behaving dialog widget should observe following rules: |
98 Well behaving dialog widget should observe following rules: |
106 - Should not create and show other dialogs |
99 - Should not create and show other dialogs |
107 - No calls to show(), hide() or setVisible() |
100 - No calls to show(), hide() or setVisible() |
108 - Not setting popup Z-order |
101 - Not setting popup Z-order |
109 - No time consuming operations performed |
102 - No time consuming operations performed |
|
103 |
|
104 \section _platform_hbdevicedialogplugin Platform-specific implementation notes for HbDeviceDialogPlugin |
|
105 |
|
106 \subsection _nonsymbian Non-Symbian |
|
107 |
|
108 The server is implemented only for the Symbian platform. On other platforms, plugins are loaded into client |
|
109 process and dialogs shown on client's main window. |
|
110 |
|
111 Plugin executables are searched from application's current directory and HB_PLUGINS_DIR/devicedialogs |
|
112 directory. |
|
113 |
|
114 \subsection _symbian Symbian |
|
115 |
|
116 Plugins are run by a server with platform security capabilities ProtServ, SwEvent, |
|
117 TrustedUI and ReadDeviceData. If a plugin doesn't have required platform security |
|
118 capabilities it will not load. |
|
119 |
|
120 Device dialog plugins can be installed into a device. Plugins are searched from device's |
|
121 local drives. The search order is rom-drives, non-removable drives and removable drives. |
|
122 Search order inside each group is alphabethical. Eclipsing is allowed only if plugin file |
|
123 names are the same. This means that in order to replace a device dialog in a plugin earlier |
|
124 in search order, the file name of the replacement plugin has to be the same as the the one |
|
125 it replaces. |
|
126 |
|
127 Device dialog plugin stubs (.qtplugin) are searched from /resource/plugins/devicedialogs directory |
|
128 and executables in /sys/bin directory in each drive. |
|
129 |
|
130 \section _creation Creating a plugin |
110 |
131 |
111 Creating a device dialog plugin and widget involves following steps. |
132 Creating a device dialog plugin and widget involves following steps. |
112 - Set in .pro file TEMPLATE = lib and CONFIG += hb plugin |
133 - Set in .pro file TEMPLATE = lib and CONFIG += hb plugin |
113 - Derive a class from HbPopup or derivatives and HbDeviceDialogInterface |
134 - Derive a class from HbPopup or derivatives and HbDeviceDialogInterface |
114 The example below is <b>not using docml</b> and dialog widget is derived from HbDialog and |
135 The example below is <b>not using docml</b> and dialog widget is derived from HbDialog and |