1 mtudcbas.h |
1 // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // 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 |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #if !defined(__MTUDBAS_H__) |
|
17 #define __MTUDBAS_H__ |
|
18 |
|
19 #if !defined(__MSVSTD_H__) |
|
20 #include <msvstd.h> |
|
21 #endif |
|
22 |
|
23 #if !defined(__MSVREG_H__) |
|
24 #include <msvreg.h> |
|
25 #endif |
|
26 |
|
27 #if !defined(__MTCLREG_H__) |
|
28 #include <mtclreg.h> |
|
29 #endif |
|
30 |
|
31 #if !defined(__BARSREAD_H__) |
|
32 #include <barsread.h> |
|
33 #endif |
|
34 |
|
35 // Forward references |
|
36 class CFbsBitmap; |
|
37 class CCoeEnv; |
|
38 |
|
39 /////////////////////////////////////////////////// |
|
40 // CBaseMtmUiData - MTM Ui data layer base API // |
|
41 /////////////////////////////////////////////////// |
|
42 class CBaseMtmUiData : public CBase |
|
43 /** Base class for UI Data MTM components. |
|
44 |
|
45 CBaseMtmUiData-derived classes allow message client applications to customise |
|
46 dynamically their user interfaces for a particular message type. For example, |
|
47 if a message client application currently had a fax entry selected, then it |
|
48 could use the fax MTM's concrete class to get information on the menus and |
|
49 icons that it should display. |
|
50 |
|
51 Specifically, functionality falls into the following three areas: |
|
52 |
|
53 1. supplying MTM-specific icons for Message Server entries |
|
54 |
|
55 2. supplying user interface text, e.g. for menus, for MTM-specific operations |
|
56 |
|
57 3. providing checks that MTM functions are suitable for use on an entry. It is |
|
58 intended that client applications will use these functions to select dynamically |
|
59 the user interface features available dependent on the entry currently selected |
|
60 within the application. For example, menu items that do not apply to particular |
|
61 entries could be greyed out. Note that OperationSupportedL() performs a similar |
|
62 function for MTM-specific functions. Implementations should determine if the |
|
63 operation is supported by checking the properties of the entry, such as its |
|
64 type. If the operation is not appropriate on the entry, then the aReasonResourceId |
|
65 argument is set to the ID of a string in the UI Data MTM's resource file |
|
66 that explains why not. Otherwise, aReasonResourceId is 0. |
|
67 |
|
68 Message client applications use the class to access such functionality polymorphically. |
|
69 MTM implementers implement this class to provide such functionality for their |
|
70 message protocol. |
|
71 @publishedAll |
|
72 @released |
|
73 */ |
|
74 { |
|
75 public: |
|
76 // --- Types --- |
|
77 /** Defines an array of icon bitmaps for the UI Data MTM. |
|
78 |
|
79 It is used in the definition of CBaseMtmUiData::iIconArrays. */ |
|
80 typedef CArrayPtr<CFbsBitmap> CBitmapArray; |
|
81 // |
|
82 // --- Inline class --- |
|
83 class TMtmUiFunction |
|
84 /** Provides the interface for clients to access MTM-specific functions, and present |
|
85 these functions to the user. A message client application can use this information to customise the UI. |
|
86 |
|
87 The class encapsulates information relating to an MTM-specific operation: |
|
88 |
|
89 1. human-readable name: for display on the UI |
|
90 |
|
91 2. ID: used to invoke the operation through the CBaseMtmUi::InvokeSyncFunctionL()/InvokeAsyncFunctionL() functions on the associated User Interface MTM |
|
92 |
|
93 3. a suggested hot-key that the UI should support for the operation |
|
94 |
|
95 4. flags that describe further operation characteristics. |
|
96 @publishedAll |
|
97 @released |
|
98 */ |
|
99 { |
|
100 friend class CBaseMtmUiData;// For access to constructor |
|
101 public: |
|
102 // --- Constants --- |
|
103 /** Enum to define UI Data base class constants. */ |
|
104 enum |
|
105 { |
|
106 /** Maximum length for operation caption. Used in defining iCaption. */ |
|
107 ECaptionMaxLen=40 |
|
108 }; |
|
109 |
|
110 public: |
|
111 // --- Construction --- |
|
112 IMPORT_C TMtmUiFunction(TResourceReader& aResourceReader); |
|
113 IMPORT_C TMtmUiFunction(const TMtmUiFunction& aFunc); |
|
114 |
|
115 private: |
|
116 // --- Private functions --- |
|
117 void SetModifiersFromResourceDefinition(TInt aResourceFileModifiers); |
|
118 |
|
119 public: |
|
120 // --- Data --- |
|
121 /** String, suitable for a menu, describing the operation. */ |
|
122 TBuf<ECaptionMaxLen> iCaption; |
|
123 /** Character code for a suggested hotkey for the operation. */ |
|
124 TInt iPreferredHotKeyKeyCode; |
|
125 /** Suggested key modifiers for the hotkey. */ |
|
126 TInt iPreferredHotKeyModifiers; |
|
127 /** The ID that can be used to invoke the operation. */ |
|
128 TInt iFunctionId; |
|
129 /** Flags setting location characteristics of the operation. */ |
|
130 TUint8 iFunctionType; // see MTUD.HRH |
|
131 /** Flags setting characteristics of the operation. */ |
|
132 TInt iFlags; // see MTUD.HRH |
|
133 }; |
|
134 // |
|
135 // --- Destruction --- |
|
136 IMPORT_C virtual ~CBaseMtmUiData(); |
|
137 // |
|
138 // --- Accessor functions --- |
|
139 IMPORT_C TUid Type() const; |
|
140 // |
|
141 // --- Context icons --- |
|
142 /** Gets an array of bitmaps relevant to the passed context entry. |
|
143 |
|
144 The bitmaps within the array should be representations of the same bitmap at various sizes. |
|
145 |
|
146 The aStateFlags argument indicates the user interface state, for example, |
|
147 "open", of the entry. |
|
148 |
|
149 Requirements: |
|
150 |
|
151 Implementations should check the type of the context, using TMsvEntry::iType::iUid, |
|
152 and the passed state, and return an appropriate bitmap array. |
|
153 |
|
154 @param aContext Context entry to return the icons for. |
|
155 @param aStateFlags Flasgs indicating the user interface state of the entry. |
|
156 @return Bitmap array for the given context.. */ |
|
157 virtual const CBitmapArray& ContextIcon(const TMsvEntry& aContext, TInt aStateFlags) const = 0; |
|
158 // |
|
159 // --- MTM-Specific function information (e.g. for dynamically-added menu items) --- |
|
160 IMPORT_C const CArrayFix<TMtmUiFunction>& MtmSpecificFunctions() const; |
|
161 IMPORT_C TBool FunctionRecognised(TInt aFunctionId) const; |
|
162 // |
|
163 // --- Provide context-specific function information --- |
|
164 /** Tests if an entry can be created as a child. |
|
165 |
|
166 @param aParent The entry under which aNewEntry should be created. |
|
167 @param aNewEntry The entry to which the operation applies. |
|
168 @param aReasonResourceId On return, a resource string ID or 0. |
|
169 @return ETrue, if the operation is appropriate on the entry; |
|
170 EFalse, if the operation is NOT appropriate on the entry. */ |
|
171 virtual TBool CanCreateEntryL(const TMsvEntry& aParent, TMsvEntry& aNewEntry, TInt& aReasonResourceId) const = 0; |
|
172 /** Tests if a delete operation is supported. |
|
173 |
|
174 @param aContext The entry to which the operation applies. |
|
175 @param aReasonResourceId On return, a resource string ID or 0. |
|
176 @return ETrue, if the operation is appropriate on the entry; |
|
177 EFalse, if the operation is NOT appropriate on the entry. */ |
|
178 virtual TBool CanDeleteFromEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; |
|
179 /** Tests if the entry can be undeleted. |
|
180 |
|
181 @param aContext The entry to which the operation applies. |
|
182 @param aReasonResourceId On return, a resource string ID or 0. |
|
183 @return ETrue, if the operation is appropriate on the entry; |
|
184 EFalse, if the operation is NOT appropriate on the entry. */ |
|
185 IMPORT_C virtual TBool CanUnDeleteFromEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const; |
|
186 /** Tests if the service entry can be deleted. |
|
187 |
|
188 @param aService The service entry to which the operation applies. |
|
189 @param aReasonResourceId On return, a resource string ID or 0. |
|
190 @return ETrue, if the operation is appropriate on the entry; |
|
191 EFalse, if the operation is NOT appropriate on the entry. */ |
|
192 virtual TBool CanDeleteServiceL(const TMsvEntry& aService, TInt& aReasonResourceId) const = 0; |
|
193 /** Tests if an entry can be replied to. |
|
194 |
|
195 @param aContext The entry to which the operation applies. |
|
196 @param aReasonResourceId On return, a resource string ID or 0. |
|
197 @return ETrue, if the operation is appropriate on the entry; |
|
198 EFalse, if the operation is NOT appropriate on the entry. */ |
|
199 virtual TBool CanReplyToEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; |
|
200 /** Tests if an entry can be forwarded. |
|
201 |
|
202 @param aContext The entry to which the operation applies. |
|
203 @param aReasonResourceId On return, a resource string ID or 0. |
|
204 @return ETrue, if the operation is appropriate on the entry; |
|
205 EFalse, if the operation is NOT appropriate on the entry. */ |
|
206 virtual TBool CanForwardEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; |
|
207 /** Tests if the entry can be edited. |
|
208 |
|
209 @param aContext The entry to which the operation applies. |
|
210 @param aReasonResourceId On return, a resource string ID or 0. |
|
211 @return ETrue, if the operation is appropriate on the entry; |
|
212 EFalse, if the operation is NOT appropriate on the entry. */ |
|
213 virtual TBool CanEditEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; |
|
214 /** Tests if an entry can be viewed. |
|
215 |
|
216 @param aContext The entry to which the operation applies. |
|
217 @param aReasonResourceId On return, a resource string ID or 0. |
|
218 @return ETrue, if the operation is appropriate on the entry; |
|
219 EFalse, if the operation is NOT appropriate on the entry. */ |
|
220 virtual TBool CanViewEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; |
|
221 /** Tests if an entry can be opened. |
|
222 |
|
223 @param aContext The entry to which the operation applies. |
|
224 @param aReasonResourceId On return, a resource string ID or 0. |
|
225 @return ETrue, if the operation is appropriate on the entry; |
|
226 EFalse, if the operation is NOT appropriate on the entry. */ |
|
227 virtual TBool CanOpenEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; |
|
228 /** Tests if a close operation is supported. |
|
229 |
|
230 @param aContext The entry to which the operation applies. |
|
231 @param aReasonResourceId On return, a resource string ID, or 0 if operation |
|
232 is supported. |
|
233 @return ETrue, if the operation is appropriate on the entry; |
|
234 EFalse, if the operation is NOT appropriate on the entry. */ |
|
235 virtual TBool CanCloseEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; |
|
236 /** Tests if a copy from or move to operation is supported. |
|
237 |
|
238 @param aContext The entry to which the operation applies. |
|
239 @param aReasonResourceId On return, a resource string ID or 0. |
|
240 @return ETrue, if the operation is appropriate on the entry; |
|
241 EFalse, if the operation is NOT appropriate on the entry. */ |
|
242 virtual TBool CanCopyMoveToEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; |
|
243 /** Tests whether a copy from or move from operation is supported. |
|
244 |
|
245 @param aContext The entry to which the operation applies. |
|
246 @param aReasonResourceId On return, a resource string ID or 0. |
|
247 @return ETrue, if the operation is appropriate on the entry; |
|
248 EFalse, if the operation is NOT appropriate on the entry. */ |
|
249 virtual TBool CanCopyMoveFromEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; |
|
250 /** Tests if the current operation on the entry can be cancelled. |
|
251 |
|
252 @param aContext The entry to which the operation applies. |
|
253 @param aReasonResourceId On return, a resource string ID, or 0 if operation |
|
254 is supported. |
|
255 @return ETrue, if the operation is appropriate on the entry; |
|
256 EFalse, if the operation is NOT appropriate on the entry. */ |
|
257 virtual TBool CanCancelL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; |
|
258 // |
|
259 // --- RTTI --- |
|
260 /** Tests if an MTM-specific operation is appropriate to the specified entry. The |
|
261 operation specified must have been obtained from a call to MtmSpecificFunctions(). |
|
262 |
|
263 It is intended that client applications will use this function to select dynamically |
|
264 the MTM-specific user interface features available dependent on the entry |
|
265 currently selected within the application. |
|
266 |
|
267 Requirements: |
|
268 |
|
269 Implementations should check the type of the context, using TMsvEntry::iType::iUid, |
|
270 and use any other information required available from the context, to determine |
|
271 if the operation is supported. |
|
272 |
|
273 @param aOperationId ID of operation to query. |
|
274 @param aContext The entry to which the operation applies. |
|
275 @return KErrNone: operation is appropriate to User Interface MTM and entry. |
|
276 Other: if the operation is not appropriate on the entry, then this is the |
|
277 ID of a string in the UI Data MTM's resource file that explains why not. */ |
|
278 virtual TInt OperationSupportedL(TInt aOperationId, const TMsvEntry& aContext) const = 0; // returns 0 if operation *IS* supported, otherwise a resource ID for the reason text |
|
279 /** Queries if the MTM supports a particular capability, specified by a UID. |
|
280 |
|
281 Requirements: |
|
282 |
|
283 Implementations should check aCapability for the standard capability values |
|
284 and return a suitable response in aResponse. If aFunctionId is unknown, return |
|
285 KErrNotSupported. |
|
286 |
|
287 @param aFunctionId UID of capability to be queried |
|
288 @param aResponse Response value. The format of the response varies according |
|
289 to the capability. |
|
290 @return KErrNone: aFunctionId is a recognised value and a response is returned |
|
291 KErrNotSupported: aFunctionId is not a recognised value */ |
|
292 virtual TInt QueryCapability(TUid aFunctionId, TInt& aResponse) const = 0; |
|
293 /** Provides status text for the sending state of the entry. |
|
294 |
|
295 @param aContext Entry to query |
|
296 @return Descriptor containing status text. */ |
|
297 virtual HBufC* StatusTextL(const TMsvEntry& aContext) const = 0; |
|
298 |
|
299 protected: |
|
300 // --- Construction --- |
|
301 IMPORT_C CBaseMtmUiData(CRegisteredMtmDll& aRegisteredMtmDll); |
|
302 IMPORT_C void ConstructL(); |
|
303 /** Initialises bitmaps and function information. |
|
304 |
|
305 Client applications do not use this function. It is relevant only to implementers of derived classes. |
|
306 |
|
307 Requirements: |
|
308 |
|
309 This function is called by the base class ConstructL() function. Implementations |
|
310 should provide this function to: |
|
311 |
|
312 1. insert MTM-specific icon bitmap arrays into the iIconArrays array data member |
|
313 |
|
314 2. insert MTM-specific operation information into the iMtmSpecificFunctions array |
|
315 data member */ |
|
316 virtual void PopulateArraysL() = 0; // Should populate iCapabilities, iMtmSpecificFunctions and iIconArrays |
|
317 /** Gets the resource file name. |
|
318 |
|
319 Client applications do not use this function. It is relevant only to implementers of derived classes. |
|
320 |
|
321 Requirements: |
|
322 |
|
323 Each UI Data MTM can have a resource file associated with it. Implementations |
|
324 should set aFilename to the full path and name of this resource file. The |
|
325 function is called by CBaseMtmUiData::ConstructL(), which then loads the resource |
|
326 file. |
|
327 |
|
328 @param aFileName Filename buffer to be filled with the resource file path |
|
329 and name */ |
|
330 virtual void GetResourceFileName(TFileName& aFileName) const = 0; |
|
331 // |
|
332 // --- Utility --- |
|
333 IMPORT_C void ReadFunctionsFromResourceFileL(TInt aResourceId);// Up to clients to call this if necessary |
|
334 IMPORT_C void CreateBitmapsL(TInt aNumZoomStates, const TDesC& aBitmapFile, TInt aStartBitmap, TInt aEndBitmap); |
|
335 CFbsBitmap* CreateBitmapL(const TDesC& aFileName, TInt aId) const; |
|
336 |
|
337 // Method used for extension: called by non virtual methods that need |
|
338 // to have a polymorphic behaviour. |
|
339 IMPORT_C virtual TAny* GetInterface(TUid aUid); |
|
340 |
|
341 protected: |
|
342 // --- Data --- |
|
343 /** Control environment object. It is set by the constructor. */ |
|
344 CCoeEnv* iCoeEnv; |
|
345 /** The array that stores the arrays of icon bitmaps for the UI Data MTM. Items |
|
346 are added to the array by PopulateArraysL(). */ |
|
347 CArrayPtr<CBitmapArray>* iIconArrays; |
|
348 /** The array that stores MTM-specific function information for the UI Data MTM. |
|
349 Items are added to the array by ReadFunctionsFromResourceFileL(). */ |
|
350 CArrayFix<TMtmUiFunction>* iMtmSpecificFunctions; |
|
351 |
|
352 private: |
|
353 // --- Data --- |
|
354 TInt iResourceFileOffset; |
|
355 CRegisteredMtmDll& iRegisteredMtmDll; // Required in order to call ReleaseLibrary() |
|
356 |
|
357 // Extra data member to allow for future extensions |
|
358 TAny* iExtensionData; |
|
359 }; |
|
360 |
|
361 |
|
362 #endif // __MTUDBAS_H__ |