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 "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
16 #if !defined(__MTUDBAS_H__)
19 #if !defined(__MSVSTD_H__)
23 #if !defined(__MSVREG_H__)
27 #if !defined(__MTCLREG_H__)
31 #if !defined(__BARSREAD_H__)
40 // CBaseMtmUiData - MTM Ui data layer base API //
42 class CBaseMtmUiData : public CBase
43 /** Base class for UI Data MTM components.
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.
51 Specifically, functionality falls into the following three areas:
53 1. supplying MTM-specific icons for Message Server entries
55 2. supplying user interface text, e.g. for menus, for MTM-specific operations
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.
68 Message client applications use the class to access such functionality polymorphically.
69 MTM implementers implement this class to provide such functionality for their
77 /** Defines an array of icon bitmaps for the UI Data MTM.
79 It is used in the definition of CBaseMtmUiData::iIconArrays. */
80 typedef CArrayPtr<CFbsBitmap> CBitmapArray;
82 // --- Inline class ---
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.
87 The class encapsulates information relating to an MTM-specific operation:
89 1. human-readable name: for display on the UI
91 2. ID: used to invoke the operation through the CBaseMtmUi::InvokeSyncFunctionL()/InvokeAsyncFunctionL() functions on the associated User Interface MTM
93 3. a suggested hot-key that the UI should support for the operation
95 4. flags that describe further operation characteristics.
100 friend class CBaseMtmUiData;// For access to constructor
103 /** Enum to define UI Data base class constants. */
106 /** Maximum length for operation caption. Used in defining iCaption. */
111 // --- Construction ---
112 IMPORT_C TMtmUiFunction(TResourceReader& aResourceReader);
113 IMPORT_C TMtmUiFunction(const TMtmUiFunction& aFunc);
116 // --- Private functions ---
117 void SetModifiersFromResourceDefinition(TInt aResourceFileModifiers);
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. */
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
135 // --- Destruction ---
136 IMPORT_C virtual ~CBaseMtmUiData();
138 // --- Accessor functions ---
139 IMPORT_C TUid Type() const;
141 // --- Context icons ---
142 /** Gets an array of bitmaps relevant to the passed context entry.
144 The bitmaps within the array should be representations of the same bitmap at various sizes.
146 The aStateFlags argument indicates the user interface state, for example,
147 "open", of the entry.
151 Implementations should check the type of the context, using TMsvEntry::iType::iUid,
152 and the passed state, and return an appropriate bitmap array.
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;
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;
163 // --- Provide context-specific function information ---
164 /** Tests if an entry can be created as a child.
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.
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.
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.
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.
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.
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.
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.
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.
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.
230 @param aContext The entry to which the operation applies.
231 @param aReasonResourceId On return, a resource string ID, or 0 if operation
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.
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.
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.
252 @param aContext The entry to which the operation applies.
253 @param aReasonResourceId On return, a resource string ID, or 0 if operation
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;
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().
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.
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.
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.
283 Implementations should check aCapability for the standard capability values
284 and return a suitable response in aResponse. If aFunctionId is unknown, return
287 @param aFunctionId UID of capability to be queried
288 @param aResponse Response value. The format of the response varies according
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.
295 @param aContext Entry to query
296 @return Descriptor containing status text. */
297 virtual HBufC* StatusTextL(const TMsvEntry& aContext) const = 0;
300 // --- Construction ---
301 IMPORT_C CBaseMtmUiData(CRegisteredMtmDll& aRegisteredMtmDll);
302 IMPORT_C void ConstructL();
303 /** Initialises bitmaps and function information.
305 Client applications do not use this function. It is relevant only to implementers of derived classes.
309 This function is called by the base class ConstructL() function. Implementations
310 should provide this function to:
312 1. insert MTM-specific icon bitmap arrays into the iIconArrays array data member
314 2. insert MTM-specific operation information into the iMtmSpecificFunctions array
316 virtual void PopulateArraysL() = 0; // Should populate iCapabilities, iMtmSpecificFunctions and iIconArrays
317 /** Gets the resource file name.
319 Client applications do not use this function. It is relevant only to implementers of derived classes.
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
328 @param aFileName Filename buffer to be filled with the resource file path
330 virtual void GetResourceFileName(TFileName& aFileName) const = 0;
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;
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);
343 /** Control environment object. It is set by the constructor. */
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;
354 TInt iResourceFileOffset;
355 CRegisteredMtmDll& iRegisteredMtmDll; // Required in order to call ReleaseLibrary()
357 // Extra data member to allow for future extensions
358 TAny* iExtensionData;
362 #endif // __MTUDBAS_H__