1.1 --- a/epoc32/include/mtudcbas.h Tue Mar 16 16:12:26 2010 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,362 +0,0 @@
1.4 -// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 -// All rights reserved.
1.6 -// This component and the accompanying materials are made available
1.7 -// 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
1.8 -// which accompanies this distribution, and is available
1.9 -// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 -//
1.11 -// Initial Contributors:
1.12 -// Nokia Corporation - initial contribution.
1.13 -//
1.14 -// Contributors:
1.15 -//
1.16 -// Description:
1.17 -//
1.18 -
1.19 -#if !defined(__MTUDBAS_H__)
1.20 -#define __MTUDBAS_H__
1.21 -
1.22 -#if !defined(__MSVSTD_H__)
1.23 -#include <msvstd.h>
1.24 -#endif
1.25 -
1.26 -#if !defined(__MSVREG_H__)
1.27 -#include <msvreg.h>
1.28 -#endif
1.29 -
1.30 -#if !defined(__MTCLREG_H__)
1.31 -#include <mtclreg.h>
1.32 -#endif
1.33 -
1.34 -#if !defined(__BARSREAD_H__)
1.35 -#include <barsread.h>
1.36 -#endif
1.37 -
1.38 -// Forward references
1.39 -class CFbsBitmap;
1.40 -class CCoeEnv;
1.41 -
1.42 -///////////////////////////////////////////////////
1.43 -// CBaseMtmUiData - MTM Ui data layer base API //
1.44 -///////////////////////////////////////////////////
1.45 -class CBaseMtmUiData : public CBase
1.46 -/** Base class for UI Data MTM components.
1.47 -
1.48 -CBaseMtmUiData-derived classes allow message client applications to customise
1.49 -dynamically their user interfaces for a particular message type. For example,
1.50 -if a message client application currently had a fax entry selected, then it
1.51 -could use the fax MTM's concrete class to get information on the menus and
1.52 -icons that it should display.
1.53 -
1.54 -Specifically, functionality falls into the following three areas:
1.55 -
1.56 -1. supplying MTM-specific icons for Message Server entries
1.57 -
1.58 -2. supplying user interface text, e.g. for menus, for MTM-specific operations
1.59 -
1.60 -3. providing checks that MTM functions are suitable for use on an entry. It is
1.61 -intended that client applications will use these functions to select dynamically
1.62 -the user interface features available dependent on the entry currently selected
1.63 -within the application. For example, menu items that do not apply to particular
1.64 -entries could be greyed out. Note that OperationSupportedL() performs a similar
1.65 -function for MTM-specific functions. Implementations should determine if the
1.66 -operation is supported by checking the properties of the entry, such as its
1.67 -type. If the operation is not appropriate on the entry, then the aReasonResourceId
1.68 -argument is set to the ID of a string in the UI Data MTM's resource file
1.69 -that explains why not. Otherwise, aReasonResourceId is 0.
1.70 -
1.71 -Message client applications use the class to access such functionality polymorphically.
1.72 -MTM implementers implement this class to provide such functionality for their
1.73 -message protocol.
1.74 -@publishedAll
1.75 -@released
1.76 -*/
1.77 - {
1.78 -public:
1.79 - // --- Types ---
1.80 - /** Defines an array of icon bitmaps for the UI Data MTM.
1.81 -
1.82 - It is used in the definition of CBaseMtmUiData::iIconArrays. */
1.83 - typedef CArrayPtr<CFbsBitmap> CBitmapArray;
1.84 - //
1.85 - // --- Inline class ---
1.86 - class TMtmUiFunction
1.87 - /** Provides the interface for clients to access MTM-specific functions, and present
1.88 - these functions to the user. A message client application can use this information to customise the UI.
1.89 -
1.90 - The class encapsulates information relating to an MTM-specific operation:
1.91 -
1.92 - 1. human-readable name: for display on the UI
1.93 -
1.94 - 2. ID: used to invoke the operation through the CBaseMtmUi::InvokeSyncFunctionL()/InvokeAsyncFunctionL() functions on the associated User Interface MTM
1.95 -
1.96 - 3. a suggested hot-key that the UI should support for the operation
1.97 -
1.98 - 4. flags that describe further operation characteristics.
1.99 -@publishedAll
1.100 -@released
1.101 -*/
1.102 - {
1.103 - friend class CBaseMtmUiData;// For access to constructor
1.104 - public:
1.105 - // --- Constants ---
1.106 - /** Enum to define UI Data base class constants. */
1.107 - enum
1.108 - {
1.109 - /** Maximum length for operation caption. Used in defining iCaption. */
1.110 - ECaptionMaxLen=40
1.111 - };
1.112 -
1.113 - public:
1.114 - // --- Construction ---
1.115 - IMPORT_C TMtmUiFunction(TResourceReader& aResourceReader);
1.116 - IMPORT_C TMtmUiFunction(const TMtmUiFunction& aFunc);
1.117 -
1.118 - private:
1.119 - // --- Private functions ---
1.120 - void SetModifiersFromResourceDefinition(TInt aResourceFileModifiers);
1.121 -
1.122 - public:
1.123 - // --- Data ---
1.124 - /** String, suitable for a menu, describing the operation. */
1.125 - TBuf<ECaptionMaxLen> iCaption;
1.126 - /** Character code for a suggested hotkey for the operation. */
1.127 - TInt iPreferredHotKeyKeyCode;
1.128 - /** Suggested key modifiers for the hotkey. */
1.129 - TInt iPreferredHotKeyModifiers;
1.130 - /** The ID that can be used to invoke the operation. */
1.131 - TInt iFunctionId;
1.132 - /** Flags setting location characteristics of the operation. */
1.133 - TUint8 iFunctionType; // see MTUD.HRH
1.134 - /** Flags setting characteristics of the operation. */
1.135 - TInt iFlags; // see MTUD.HRH
1.136 - };
1.137 - //
1.138 - // --- Destruction ---
1.139 - IMPORT_C virtual ~CBaseMtmUiData();
1.140 - //
1.141 - // --- Accessor functions ---
1.142 - IMPORT_C TUid Type() const;
1.143 - //
1.144 - // --- Context icons ---
1.145 - /** Gets an array of bitmaps relevant to the passed context entry.
1.146 -
1.147 - The bitmaps within the array should be representations of the same bitmap at various sizes.
1.148 -
1.149 - The aStateFlags argument indicates the user interface state, for example,
1.150 - "open", of the entry.
1.151 -
1.152 - Requirements:
1.153 -
1.154 - Implementations should check the type of the context, using TMsvEntry::iType::iUid,
1.155 - and the passed state, and return an appropriate bitmap array.
1.156 -
1.157 - @param aContext Context entry to return the icons for.
1.158 - @param aStateFlags Flasgs indicating the user interface state of the entry.
1.159 - @return Bitmap array for the given context.. */
1.160 - virtual const CBitmapArray& ContextIcon(const TMsvEntry& aContext, TInt aStateFlags) const = 0;
1.161 - //
1.162 - // --- MTM-Specific function information (e.g. for dynamically-added menu items) ---
1.163 - IMPORT_C const CArrayFix<TMtmUiFunction>& MtmSpecificFunctions() const;
1.164 - IMPORT_C TBool FunctionRecognised(TInt aFunctionId) const;
1.165 - //
1.166 - // --- Provide context-specific function information ---
1.167 - /** Tests if an entry can be created as a child.
1.168 -
1.169 - @param aParent The entry under which aNewEntry should be created.
1.170 - @param aNewEntry The entry to which the operation applies.
1.171 - @param aReasonResourceId On return, a resource string ID or 0.
1.172 - @return ETrue, if the operation is appropriate on the entry;
1.173 - EFalse, if the operation is NOT appropriate on the entry. */
1.174 - virtual TBool CanCreateEntryL(const TMsvEntry& aParent, TMsvEntry& aNewEntry, TInt& aReasonResourceId) const = 0;
1.175 - /** Tests if a delete operation is supported.
1.176 -
1.177 - @param aContext The entry to which the operation applies.
1.178 - @param aReasonResourceId On return, a resource string ID or 0.
1.179 - @return ETrue, if the operation is appropriate on the entry;
1.180 - EFalse, if the operation is NOT appropriate on the entry. */
1.181 - virtual TBool CanDeleteFromEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
1.182 - /** Tests if the entry can be undeleted.
1.183 -
1.184 - @param aContext The entry to which the operation applies.
1.185 - @param aReasonResourceId On return, a resource string ID or 0.
1.186 - @return ETrue, if the operation is appropriate on the entry;
1.187 - EFalse, if the operation is NOT appropriate on the entry. */
1.188 - IMPORT_C virtual TBool CanUnDeleteFromEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const;
1.189 - /** Tests if the service entry can be deleted.
1.190 -
1.191 - @param aService The service entry to which the operation applies.
1.192 - @param aReasonResourceId On return, a resource string ID or 0.
1.193 - @return ETrue, if the operation is appropriate on the entry;
1.194 - EFalse, if the operation is NOT appropriate on the entry. */
1.195 - virtual TBool CanDeleteServiceL(const TMsvEntry& aService, TInt& aReasonResourceId) const = 0;
1.196 - /** Tests if an entry can be replied to.
1.197 -
1.198 - @param aContext The entry to which the operation applies.
1.199 - @param aReasonResourceId On return, a resource string ID or 0.
1.200 - @return ETrue, if the operation is appropriate on the entry;
1.201 - EFalse, if the operation is NOT appropriate on the entry. */
1.202 - virtual TBool CanReplyToEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
1.203 - /** Tests if an entry can be forwarded.
1.204 -
1.205 - @param aContext The entry to which the operation applies.
1.206 - @param aReasonResourceId On return, a resource string ID or 0.
1.207 - @return ETrue, if the operation is appropriate on the entry;
1.208 - EFalse, if the operation is NOT appropriate on the entry. */
1.209 - virtual TBool CanForwardEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
1.210 - /** Tests if the entry can be edited.
1.211 -
1.212 - @param aContext The entry to which the operation applies.
1.213 - @param aReasonResourceId On return, a resource string ID or 0.
1.214 - @return ETrue, if the operation is appropriate on the entry;
1.215 - EFalse, if the operation is NOT appropriate on the entry. */
1.216 - virtual TBool CanEditEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
1.217 - /** Tests if an entry can be viewed.
1.218 -
1.219 - @param aContext The entry to which the operation applies.
1.220 - @param aReasonResourceId On return, a resource string ID or 0.
1.221 - @return ETrue, if the operation is appropriate on the entry;
1.222 - EFalse, if the operation is NOT appropriate on the entry. */
1.223 - virtual TBool CanViewEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
1.224 - /** Tests if an entry can be opened.
1.225 -
1.226 - @param aContext The entry to which the operation applies.
1.227 - @param aReasonResourceId On return, a resource string ID or 0.
1.228 - @return ETrue, if the operation is appropriate on the entry;
1.229 - EFalse, if the operation is NOT appropriate on the entry. */
1.230 - virtual TBool CanOpenEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
1.231 - /** Tests if a close operation is supported.
1.232 -
1.233 - @param aContext The entry to which the operation applies.
1.234 - @param aReasonResourceId On return, a resource string ID, or 0 if operation
1.235 - is supported.
1.236 - @return ETrue, if the operation is appropriate on the entry;
1.237 - EFalse, if the operation is NOT appropriate on the entry. */
1.238 - virtual TBool CanCloseEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
1.239 - /** Tests if a copy from or move to operation is supported.
1.240 -
1.241 - @param aContext The entry to which the operation applies.
1.242 - @param aReasonResourceId On return, a resource string ID or 0.
1.243 - @return ETrue, if the operation is appropriate on the entry;
1.244 - EFalse, if the operation is NOT appropriate on the entry. */
1.245 - virtual TBool CanCopyMoveToEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
1.246 - /** Tests whether a copy from or move from operation is supported.
1.247 -
1.248 - @param aContext The entry to which the operation applies.
1.249 - @param aReasonResourceId On return, a resource string ID or 0.
1.250 - @return ETrue, if the operation is appropriate on the entry;
1.251 - EFalse, if the operation is NOT appropriate on the entry. */
1.252 - virtual TBool CanCopyMoveFromEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
1.253 - /** Tests if the current operation on the entry can be cancelled.
1.254 -
1.255 - @param aContext The entry to which the operation applies.
1.256 - @param aReasonResourceId On return, a resource string ID, or 0 if operation
1.257 - is supported.
1.258 - @return ETrue, if the operation is appropriate on the entry;
1.259 - EFalse, if the operation is NOT appropriate on the entry. */
1.260 - virtual TBool CanCancelL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
1.261 - //
1.262 - // --- RTTI ---
1.263 - /** Tests if an MTM-specific operation is appropriate to the specified entry. The
1.264 - operation specified must have been obtained from a call to MtmSpecificFunctions().
1.265 -
1.266 - It is intended that client applications will use this function to select dynamically
1.267 - the MTM-specific user interface features available dependent on the entry
1.268 - currently selected within the application.
1.269 -
1.270 - Requirements:
1.271 -
1.272 - Implementations should check the type of the context, using TMsvEntry::iType::iUid,
1.273 - and use any other information required available from the context, to determine
1.274 - if the operation is supported.
1.275 -
1.276 - @param aOperationId ID of operation to query.
1.277 - @param aContext The entry to which the operation applies.
1.278 - @return KErrNone: operation is appropriate to User Interface MTM and entry.
1.279 - Other: if the operation is not appropriate on the entry, then this is the
1.280 - ID of a string in the UI Data MTM's resource file that explains why not. */
1.281 - virtual TInt OperationSupportedL(TInt aOperationId, const TMsvEntry& aContext) const = 0; // returns 0 if operation *IS* supported, otherwise a resource ID for the reason text
1.282 - /** Queries if the MTM supports a particular capability, specified by a UID.
1.283 -
1.284 - Requirements:
1.285 -
1.286 - Implementations should check aCapability for the standard capability values
1.287 - and return a suitable response in aResponse. If aFunctionId is unknown, return
1.288 - KErrNotSupported.
1.289 -
1.290 - @param aFunctionId UID of capability to be queried
1.291 - @param aResponse Response value. The format of the response varies according
1.292 - to the capability.
1.293 - @return KErrNone: aFunctionId is a recognised value and a response is returned
1.294 - KErrNotSupported: aFunctionId is not a recognised value */
1.295 - virtual TInt QueryCapability(TUid aFunctionId, TInt& aResponse) const = 0;
1.296 - /** Provides status text for the sending state of the entry.
1.297 -
1.298 - @param aContext Entry to query
1.299 - @return Descriptor containing status text. */
1.300 - virtual HBufC* StatusTextL(const TMsvEntry& aContext) const = 0;
1.301 -
1.302 -protected:
1.303 - // --- Construction ---
1.304 - IMPORT_C CBaseMtmUiData(CRegisteredMtmDll& aRegisteredMtmDll);
1.305 - IMPORT_C void ConstructL();
1.306 - /** Initialises bitmaps and function information.
1.307 -
1.308 - Client applications do not use this function. It is relevant only to implementers of derived classes.
1.309 -
1.310 - Requirements:
1.311 -
1.312 - This function is called by the base class ConstructL() function. Implementations
1.313 - should provide this function to:
1.314 -
1.315 - 1. insert MTM-specific icon bitmap arrays into the iIconArrays array data member
1.316 -
1.317 - 2. insert MTM-specific operation information into the iMtmSpecificFunctions array
1.318 - data member */
1.319 - virtual void PopulateArraysL() = 0; // Should populate iCapabilities, iMtmSpecificFunctions and iIconArrays
1.320 - /** Gets the resource file name.
1.321 -
1.322 - Client applications do not use this function. It is relevant only to implementers of derived classes.
1.323 -
1.324 - Requirements:
1.325 -
1.326 - Each UI Data MTM can have a resource file associated with it. Implementations
1.327 - should set aFilename to the full path and name of this resource file. The
1.328 - function is called by CBaseMtmUiData::ConstructL(), which then loads the resource
1.329 - file.
1.330 -
1.331 - @param aFileName Filename buffer to be filled with the resource file path
1.332 - and name */
1.333 - virtual void GetResourceFileName(TFileName& aFileName) const = 0;
1.334 - //
1.335 - // --- Utility ---
1.336 - IMPORT_C void ReadFunctionsFromResourceFileL(TInt aResourceId);// Up to clients to call this if necessary
1.337 - IMPORT_C void CreateBitmapsL(TInt aNumZoomStates, const TDesC& aBitmapFile, TInt aStartBitmap, TInt aEndBitmap);
1.338 - CFbsBitmap* CreateBitmapL(const TDesC& aFileName, TInt aId) const;
1.339 -
1.340 - // Method used for extension: called by non virtual methods that need
1.341 - // to have a polymorphic behaviour.
1.342 - IMPORT_C virtual TAny* GetInterface(TUid aUid);
1.343 -
1.344 -protected:
1.345 - // --- Data ---
1.346 - /** Control environment object. It is set by the constructor. */
1.347 - CCoeEnv* iCoeEnv;
1.348 - /** The array that stores the arrays of icon bitmaps for the UI Data MTM. Items
1.349 - are added to the array by PopulateArraysL(). */
1.350 - CArrayPtr<CBitmapArray>* iIconArrays;
1.351 - /** The array that stores MTM-specific function information for the UI Data MTM.
1.352 - Items are added to the array by ReadFunctionsFromResourceFileL(). */
1.353 - CArrayFix<TMtmUiFunction>* iMtmSpecificFunctions;
1.354 -
1.355 -private:
1.356 - // --- Data ---
1.357 - TInt iResourceFileOffset;
1.358 - CRegisteredMtmDll& iRegisteredMtmDll; // Required in order to call ReleaseLibrary()
1.359 -
1.360 - // Extra data member to allow for future extensions
1.361 - TAny* iExtensionData;
1.362 - };
1.363 -
1.364 -
1.365 -#endif // __MTUDBAS_H__