23 ** |
23 ** |
24 ****************************************************************************/ |
24 ****************************************************************************/ |
25 |
25 |
26 /*! |
26 /*! |
27 \class HbIndicator |
27 \class HbIndicator |
28 \brief HbIndicator can be used to activate and deactivate indicators. |
28 \brief HbIndicator can be used to activate, update and deactivate indicators. |
29 |
29 |
30 HbIndicator sends a request for indicator activation and deactivation to |
30 Indicators are used to indicate events to user. For example unread mail, missed calls, etc. |
31 server side. Indicators are identified by their type-string and there must be a |
31 They appear as icon in status bar and/or indicator menu. In addition of an icon, indicator menu |
32 server side indicator implementation for that type. |
32 may also contains text for an indicator. From the menu, user can interact with an indicator |
|
33 by tapping it. |
33 |
34 |
34 Active indicators may appear in the status indicator area as an icon, |
35 Indicators are implemented by plugins loaded by indicator service. Indicator implementations |
35 and/or inside universal indicator popup showing icon and text. |
36 in plugins are identified by unique strings. |
36 Depending on the indicator implementation, activated indicator may also show up with |
|
37 a discreet popup and some indicators can be interacted by the user in universal indicator popup. |
|
38 |
37 |
39 When deactivated, icons are removed from the status |
38 Activating indicator adds it into status bar and/or menu. Deactivating removes it. |
40 indicator area and in universal indicator popup. |
|
41 |
39 |
42 User can interact with indicator from the indicator menu. Client is notified about |
40 Activating an already active indicator updates it with a new data set. The plugin implementation |
43 the user interaction via userActivated signal. Interaction notification and data |
41 is called the same way as first time activate is called. |
44 sent by the indicator is a contract between HbIndicator class and indicator. |
42 |
45 |
43 HbIndicator indicates data from the plugin implementation by HbIndicator::userActivated() signal. |
46 \sa HbIndicatorPluginInterface |
44 The pugin may trigger this signal for example when user interacts with the indicator from |
|
45 indicator menu. Data accompanying the signal originates from indicator plugin and is |
|
46 passed by indicator framework unmodified. All instances of HbIndicator that have activated |
|
47 the indicator, receive the signal. |
|
48 |
|
49 The code below activates and deactivates an indicator. |
|
50 \code |
|
51 static const char indicatorType[] = "com.nokia.hb.unittestfirstindicator0/1.0"; |
|
52 // Activate with an integer parameter value 0 |
|
53 mIndicator.activate(indicatorType, QVariant(0)); |
|
54 mIndicator.deactivate(indicatorType); |
|
55 \endcode |
|
56 |
|
57 \sa HbIndicatorPluginInterface, HbIndicatorInterface |
47 |
58 |
48 \stable |
59 \stable |
49 \hbcore |
60 \hbcore |
50 */ |
61 */ |
51 |
62 |
53 \enum HbIndicator::ErrorRange |
64 \enum HbIndicator::ErrorRange |
54 Defines indicator error ranges. |
65 Defines indicator error ranges. |
55 */ |
66 */ |
56 /*! |
67 /*! |
57 \var HbIndicator::ErrorRange HbIndicator::FrameworkErrors |
68 \var HbIndicator::ErrorRange HbIndicator::FrameworkErrors |
58 Start of an error range for errors originating from device dialog framework (client or server). |
69 Start of an error range for errors originating from indicator framework (client or server). |
59 Error codes are defined in hbdevicedialogerrors.h |
|
60 */ |
70 */ |
61 /*! |
71 /*! |
62 \var HbIndicator::ErrorRange HbIndicator::PluginErrors |
72 \var HbIndicator::ErrorRange HbIndicator::PluginErrors |
63 Start of an error range for errors originating from indicator plugins. |
73 Start of an error range for errors originating from indicator plugins. |
64 */ |
74 */ |
68 */ |
78 */ |
69 |
79 |
70 /*! |
80 /*! |
71 \fn void HbIndicator::userActivated(const QString &type, const QVariantMap &data) |
81 \fn void HbIndicator::userActivated(const QString &type, const QVariantMap &data) |
72 |
82 |
73 The class should emit this signal, when client needs to be notified of the |
83 Signal indicates data from indicator plugin implentation. Indicator plugin may originate the signal |
74 user interaction. |
84 for example when user interacts with the indicator from indicator menu. |
75 @param type Type of the indicator that user interacted with. |
85 |
|
86 @param type Indicator type (identification). |
76 @param data Data sent by indicator. |
87 @param data Data sent by indicator. |
77 */ |
88 */ |
78 |
89 |
79 #include "hbindicator.h" |
90 #include "hbindicator.h" |
80 |
91 |
112 { |
123 { |
113 delete d_ptr; |
124 delete d_ptr; |
114 } |
125 } |
115 |
126 |
116 /*! |
127 /*! |
117 Activates an indicator of type \a indicatorType. |
128 Activates an indicator. If indicator was already active, updates it. |
118 An extra parameter can be passed along to the indicator plugin. |
|
119 Returns true, if the indicator is activated, false, if an error occurred. |
|
120 |
129 |
121 \sa deactivate |
130 \param indicatorType Indicator to activate. |
|
131 \param parameter Parameter to pass into indicator plugin implementation. |
|
132 |
|
133 \return Returns true if the indicator was activated, false if an error occurred. |
|
134 |
|
135 \sa deactivate() |
122 */ |
136 */ |
123 bool HbIndicator::activate(const QString &indicatorType, const QVariant ¶meter) |
137 bool HbIndicator::activate(const QString &indicatorType, const QVariant ¶meter) |
124 { |
138 { |
125 return d_func()->activate(indicatorType, parameter); |
139 return d_func()->activate(indicatorType, parameter); |
126 } |
140 } |
127 |
141 |
128 /*! |
142 /*! |
129 Deactivates an indicator of type \a indicatorType. |
143 Deactivates an indicator. |
130 An extra parameter can be passed along to the indicator plugin. |
|
131 If indicator is not currently active, does nothing and returns true. |
|
132 Returns false, if error occurred. |
|
133 |
144 |
134 \sa activate |
145 \param indicatorType Indicator to deactivate. |
|
146 \param parameter Parameter to pass into indicator plugin implementation. |
|
147 |
|
148 \return Returns true if the indicator was deactivated or wasn't active, |
|
149 false if an error occurred. |
|
150 |
|
151 \sa activate() |
135 */ |
152 */ |
136 bool HbIndicator::deactivate(const QString &indicatorType, const QVariant ¶meter) |
153 bool HbIndicator::deactivate(const QString &indicatorType, const QVariant ¶meter) |
137 { |
154 { |
138 return d_func()->deactivate(indicatorType, parameter); |
155 return d_func()->deactivate(indicatorType, parameter); |
139 } |
156 } |