1 cmapplicationsettingsui.h |
1 /* |
|
2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * |
|
16 */ |
|
17 |
|
18 #ifndef C_CMAPPLICATIONSETTINGSUI_H |
|
19 #define C_CMAPPLICATIONSETTINGSUI_H |
|
20 |
|
21 #include <E32def.h> |
|
22 #include <e32base.h> |
|
23 |
|
24 class CCmConnSettingsUiImpl; |
|
25 namespace CMManager |
|
26 { |
|
27 |
|
28 /** |
|
29 * CCmApplicationSettingsUi::RunApplicationSettingsL leaves with this |
|
30 * error code if the selection dialog would have zero elements caused |
|
31 * by filtering out all the Connection Methods with the aFilterArray |
|
32 * and not requesting other list elements by the aListItems bitfield. |
|
33 * See the comment of the RunApplicationSettingsL method for more |
|
34 * detailes. |
|
35 * This error code is supported by the error resolver. |
|
36 */ |
|
37 const TInt KErrConnectionNotFound = -32700; |
|
38 |
|
39 /** |
|
40 * The selection type of a list item in application settings UI |
|
41 */ |
|
42 enum TCmSettingSelectionMode |
|
43 { |
|
44 EAlwaysAsk, /**< |
|
45 * The user selected Always ask |
|
46 */ |
|
47 EDestination, /**< |
|
48 * The user selected a destination |
|
49 */ |
|
50 EConnectionMethod, /**< |
|
51 * The user selected a connection method |
|
52 */ |
|
53 EDefaultConnection // The user selected Default Connection |
|
54 |
|
55 }; |
|
56 |
|
57 |
|
58 /** |
|
59 * These bitmasks controls what items does the selection UI containes. |
|
60 * Bitmasks not listed in the enum are reserved for future usage and they |
|
61 * are disabled by default. So extending these bitmasks does not cause |
|
62 * BC break later. |
|
63 */ |
|
64 enum TCmSelectionDialogItems |
|
65 { |
|
66 EShowAlwaysAsk = 0x01, /**< |
|
67 * AlwaysAsk is added to the |
|
68 * selection UI. |
|
69 */ |
|
70 EShowDefaultConnection = 0x02, /**< |
|
71 * DefaultConnection is added to the |
|
72 * selection UI. |
|
73 */ |
|
74 |
|
75 /** |
|
76 * The following enumerations controls how destinations and |
|
77 * Connection Methods are presented in the selection UI. |
|
78 * EShowDestinations is set and EShowConnectionMethods is set: |
|
79 * Destination list is added to the selection UI and a Connection |
|
80 * Method can be selected inside a Destination. |
|
81 * EShowDestinations is set and EShowConnectionMethods is not set: |
|
82 * Destination list is added to the selection UI and no Connection |
|
83 * Method can be selected inside a Destination. |
|
84 * EShowDestinations is not set and EShowConnectionMethods is set: |
|
85 * Connection Method list is added to the selection UI. Connection |
|
86 * Methods are ordered according to the global bearer type |
|
87 * priorities. Destination cannot be selected. |
|
88 * EShowDestinations is not set and EShowConnectionMethods is not set: |
|
89 * The selection UI will not contain any Destination or Connection |
|
90 * Method. E.g. If EShowAlwaysAsk and EShowDefaultConnection was set |
|
91 * then the selection UI will contain two entries (AlwaysAsk and |
|
92 * DefaultConnection). |
|
93 */ |
|
94 EShowDestinations = 0x04, /**< |
|
95 * Destination list is added to the |
|
96 * selection UI. Destinations which |
|
97 * does not contain any Connection |
|
98 * Methods are not shown. |
|
99 */ |
|
100 EShowConnectionMethods = 0x08, /**< |
|
101 * If EShowDestinations is set: |
|
102 * Connection Method can be selected |
|
103 * inside a destination. |
|
104 * If EShowDestinations is not set: |
|
105 * Connection Method list is added to |
|
106 * the selection UI. |
|
107 */ |
|
108 }; |
|
109 |
|
110 }// namespace CMManger |
|
111 |
|
112 |
|
113 // Structs |
|
114 |
|
115 /** |
|
116 * Stores the details of a setting selection |
|
117 * |
|
118 * @lib cmmanager.lib |
|
119 * @since S60 3.2 |
|
120 */ |
|
121 NONSHARABLE_STRUCT( TCmSettingSelection ) |
|
122 { |
|
123 /** |
|
124 * Selection mode, refers to the type of the list item which is selected |
|
125 */ |
|
126 CMManager::TCmSettingSelectionMode iResult; |
|
127 |
|
128 /** |
|
129 * Id of the selected destination or connection method |
|
130 */ |
|
131 TUint iId; |
|
132 }; |
|
133 |
|
134 /** |
|
135 * Typedef of the bearer filter array. |
|
136 * This type of array is used to filter Connection Methods |
|
137 * by bearer types. |
|
138 * |
|
139 * The array elements are bearer IDs. The IDs are defined in the bearer |
|
140 * type specific cmplugin...def.h files. E.g. the ID of the CSD bearer |
|
141 * type (KUidCSDBearerType) can be found in the cmplugincsddef.h header. |
|
142 */ |
|
143 typedef RArray<TUint32> TBearerFilterArray; |
|
144 |
|
145 /** |
|
146 * For launching the Application Settings UI |
|
147 * |
|
148 * Displays a radio button page for an application used to select |
|
149 * a destination or connection method |
|
150 * |
|
151 * @lib cmmanager.lib |
|
152 * @since S60 3.2 |
|
153 */ |
|
154 NONSHARABLE_CLASS( CCmApplicationSettingsUi ) : public CBase |
|
155 { |
|
156 |
|
157 public: // construction/destruction |
|
158 |
|
159 /** Epoc constructor */ |
|
160 IMPORT_C static CCmApplicationSettingsUi* NewL(); |
|
161 |
|
162 /** Epoc constructor |
|
163 * Pushes the object on the cleanup stack |
|
164 */ |
|
165 IMPORT_C static CCmApplicationSettingsUi* NewLC(); |
|
166 |
|
167 /** Destructor. */ |
|
168 virtual ~CCmApplicationSettingsUi(); |
|
169 |
|
170 //======================================================================= |
|
171 // UI API |
|
172 // |
|
173 public: |
|
174 |
|
175 /** |
|
176 * Launches the 'easy to use' Settings UI provided for applications |
|
177 * for handling Destinations and Connection Methods. |
|
178 * This function call launches the same selection dialog as the |
|
179 * the extended RunApplicationSettingsL do (see below) with the |
|
180 * list items Default Connection, Destinations and Connection Methods |
|
181 * without any filtering. |
|
182 * |
|
183 * @since 3.2 |
|
184 * @param aSelection If initialised to a valid value, sets the higlight to the |
|
185 * corresponding list item at startup. If a list of Destinations is displayed, and |
|
186 * the initial highlight is set to a Connection Method, the parent Destination |
|
187 * gets highlighted. On return, holds user selection. |
|
188 * @return TBool seleceted or not. |
|
189 */ |
|
190 IMPORT_C TBool RunApplicationSettingsL( |
|
191 TCmSettingSelection& aSelection ); |
|
192 |
|
193 /** |
|
194 * Launches the 'easy to use' Settings UI provided for applications |
|
195 * for handling Destinations and Connection Methods |
|
196 * |
|
197 * @since 3.2 |
|
198 * @param aSelection If initialised to a valid value, sets the higlight to the |
|
199 * corresponding list item at startup. If a list of Destinations is displayed, and |
|
200 * the initial highlight is set to a Connection Method, the parent Destination |
|
201 * gets highlighted. On return, holds user selection. |
|
202 * @param aListItems A bit field which indicates which items shoud be |
|
203 * shown in the selection dialog. The bitmasks are |
|
204 * defined in the TCmSelectionDialogItems enum. |
|
205 * |
|
206 * The function leaves with KErrNotSupported if all the items which |
|
207 * were set to be shown are not supported/enabled. |
|
208 * E.g. Default Connection availability/support is controlled by the |
|
209 * Feature Manager so if only EShowDefaultConnection is set and the |
|
210 * Default Connection feature is not enabled than the function leaves |
|
211 * with KErrNotSupported. |
|
212 * |
|
213 * In other cases (when an item or items are not supported/enabled but |
|
214 * not all) the selected but not supported/enabled items are not added |
|
215 * to the list. The request to show such an item is silently ignored. |
|
216 * |
|
217 * |
|
218 * Special note about the EShowDestinations and EShowConnectionMethods |
|
219 * bitmasks: |
|
220 * The following enumerations controls how how destinations and |
|
221 * Connection Methods are presented in the selection UI. |
|
222 * General rule about the EShowDestinations: |
|
223 * Destinations which does not contain any Connection Methods are |
|
224 * not shown in the selection dialog. The same rule is applied if |
|
225 * the Destination containes Connection Methods but all of them |
|
226 * are filtered out by the filtering criteria. |
|
227 * EShowDestinations is set and EShowConnectionMethods is set: |
|
228 * Destination list is added to the selection UI and a Connection |
|
229 * Method can be selected inside a Destination. |
|
230 * EShowDestinations is set and EShowConnectionMethods is not set: |
|
231 * Destination list is added to the selection UI and no Connection |
|
232 * Method can be selected inside a Destination. |
|
233 * EShowDestinations is not set and EShowConnectionMethods is set: |
|
234 * Connection Method list is added to the selection UI. Connection |
|
235 * Methods are ordered according to the global bearer type |
|
236 * priorities. Destination cannot be selected. |
|
237 * EShowDestinations is not set and EShowConnectionMethods is not set: |
|
238 * The selection UI will not contain any Destination or Connection |
|
239 * Method. E.g. If EShowAlwaysAsk and EShowDefaultConnection was |
|
240 * set then the selection UI will contain two entries (AlwaysAsk |
|
241 * and DefaultConnection). |
|
242 * |
|
243 * @param aFilterArray Only Connection Methods with bearer types from |
|
244 * the aFilterArray will be shown. |
|
245 * All Connection Methods will be listed if the |
|
246 * array has no element. |
|
247 * @return TBool seleceted or not. |
|
248 * |
|
249 * @leave KErrArgument If the selection dialog would have zero |
|
250 * elements based on the aListItems bitmask |
|
251 * (aListItems is equal to zero). |
|
252 * |
|
253 * @leave KErrNotSupported |
|
254 * If the selection dialog would have zero |
|
255 * elements based on the aListItems bitmask |
|
256 * (all the selected elements in aListItems |
|
257 * are not supported/disabled). |
|
258 * E.g. aListItems = EShowDefaultConnection but |
|
259 * Default Connection feature is not enabled. |
|
260 * |
|
261 * @leave KErrConnectionNotFound |
|
262 * If the selection dialog would have zero |
|
263 * elements caused by filtering out all the |
|
264 * Connection Methods with the aFilterArray |
|
265 * and not requesting other list elements by |
|
266 * the aListItems bitfield than the function |
|
267 * call leaves with KErrConnectionNotFound |
|
268 * error code. A corresponding error note can |
|
269 * be shown using the error resolver. |
|
270 * E.g. |
|
271 * - aListItems = EShowConnectionMethods |
|
272 * but all Connection Methods are filtered |
|
273 * out by the aFilterArray. |
|
274 */ |
|
275 IMPORT_C TBool RunApplicationSettingsL( |
|
276 TCmSettingSelection& aSelection, |
|
277 TUint aListItems, |
|
278 TBearerFilterArray& aFilterArray); |
|
279 |
|
280 private: |
|
281 |
|
282 /** C++ constructor */ |
|
283 CCmApplicationSettingsUi(); |
|
284 |
|
285 /** |
|
286 * Epoc 2nd phase constructor |
|
287 * |
|
288 * @since S60 3.2 |
|
289 */ |
|
290 void ConstructL(); |
|
291 |
|
292 private: // data |
|
293 |
|
294 /** |
|
295 * implementation of the class |
|
296 */ |
|
297 CCmConnSettingsUiImpl* iImpl; |
|
298 }; |
|
299 |
|
300 #endif // C_CMAPPLICATIONSETTINGSUI_H |