williamr@2: // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@2: // All rights reserved. williamr@2: // This component and the accompanying materials are made available williamr@2: // 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 williamr@2: // which accompanies this distribution, and is available williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". williamr@2: // williamr@2: // Initial Contributors: williamr@2: // Nokia Corporation - initial contribution. williamr@2: // williamr@2: // Contributors: williamr@2: // williamr@2: // Description: williamr@2: // williamr@2: williamr@2: #if !defined(__MTUDBAS_H__) williamr@2: #define __MTUDBAS_H__ williamr@2: williamr@2: #if !defined(__MSVSTD_H__) williamr@2: #include williamr@2: #endif williamr@2: williamr@2: #if !defined(__MSVREG_H__) williamr@2: #include williamr@2: #endif williamr@2: williamr@2: #if !defined(__MTCLREG_H__) williamr@2: #include williamr@2: #endif williamr@2: williamr@2: #if !defined(__BARSREAD_H__) williamr@2: #include williamr@2: #endif williamr@2: williamr@2: // Forward references williamr@2: class CFbsBitmap; williamr@2: class CCoeEnv; williamr@2: williamr@2: /////////////////////////////////////////////////// williamr@2: // CBaseMtmUiData - MTM Ui data layer base API // williamr@2: /////////////////////////////////////////////////// williamr@2: class CBaseMtmUiData : public CBase williamr@2: /** Base class for UI Data MTM components. williamr@2: williamr@2: CBaseMtmUiData-derived classes allow message client applications to customise williamr@2: dynamically their user interfaces for a particular message type. For example, williamr@2: if a message client application currently had a fax entry selected, then it williamr@2: could use the fax MTM's concrete class to get information on the menus and williamr@2: icons that it should display. williamr@2: williamr@2: Specifically, functionality falls into the following three areas: williamr@2: williamr@2: 1. supplying MTM-specific icons for Message Server entries williamr@2: williamr@2: 2. supplying user interface text, e.g. for menus, for MTM-specific operations williamr@2: williamr@2: 3. providing checks that MTM functions are suitable for use on an entry. It is williamr@2: intended that client applications will use these functions to select dynamically williamr@2: the user interface features available dependent on the entry currently selected williamr@2: within the application. For example, menu items that do not apply to particular williamr@2: entries could be greyed out. Note that OperationSupportedL() performs a similar williamr@2: function for MTM-specific functions. Implementations should determine if the williamr@2: operation is supported by checking the properties of the entry, such as its williamr@2: type. If the operation is not appropriate on the entry, then the aReasonResourceId williamr@2: argument is set to the ID of a string in the UI Data MTM's resource file williamr@2: that explains why not. Otherwise, aReasonResourceId is 0. williamr@2: williamr@2: Message client applications use the class to access such functionality polymorphically. williamr@2: MTM implementers implement this class to provide such functionality for their williamr@2: message protocol. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: williamr@2: // --- Types --- williamr@2: /** Defines an array of icon bitmaps for the UI Data MTM. williamr@2: williamr@2: It is used in the definition of CBaseMtmUiData::iIconArrays. */ williamr@2: typedef CArrayPtr CBitmapArray; williamr@2: // williamr@2: // --- Inline class --- williamr@2: class TMtmUiFunction williamr@2: /** Provides the interface for clients to access MTM-specific functions, and present williamr@2: these functions to the user. A message client application can use this information to customise the UI. williamr@2: williamr@2: The class encapsulates information relating to an MTM-specific operation: williamr@2: williamr@2: 1. human-readable name: for display on the UI williamr@2: williamr@2: 2. ID: used to invoke the operation through the CBaseMtmUi::InvokeSyncFunctionL()/InvokeAsyncFunctionL() functions on the associated User Interface MTM williamr@2: williamr@2: 3. a suggested hot-key that the UI should support for the operation williamr@2: williamr@2: 4. flags that describe further operation characteristics. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: friend class CBaseMtmUiData;// For access to constructor williamr@2: public: williamr@2: // --- Constants --- williamr@2: /** Enum to define UI Data base class constants. */ williamr@2: enum williamr@2: { williamr@2: /** Maximum length for operation caption. Used in defining iCaption. */ williamr@2: ECaptionMaxLen=40 williamr@2: }; williamr@2: williamr@2: public: williamr@2: // --- Construction --- williamr@2: IMPORT_C TMtmUiFunction(TResourceReader& aResourceReader); williamr@2: IMPORT_C TMtmUiFunction(const TMtmUiFunction& aFunc); williamr@2: williamr@2: private: williamr@2: // --- Private functions --- williamr@2: void SetModifiersFromResourceDefinition(TInt aResourceFileModifiers); williamr@2: williamr@2: public: williamr@2: // --- Data --- williamr@2: /** String, suitable for a menu, describing the operation. */ williamr@2: TBuf iCaption; williamr@2: /** Character code for a suggested hotkey for the operation. */ williamr@2: TInt iPreferredHotKeyKeyCode; williamr@2: /** Suggested key modifiers for the hotkey. */ williamr@2: TInt iPreferredHotKeyModifiers; williamr@2: /** The ID that can be used to invoke the operation. */ williamr@2: TInt iFunctionId; williamr@2: /** Flags setting location characteristics of the operation. */ williamr@2: TUint8 iFunctionType; // see MTUD.HRH williamr@2: /** Flags setting characteristics of the operation. */ williamr@2: TInt iFlags; // see MTUD.HRH williamr@2: }; williamr@2: // williamr@2: // --- Destruction --- williamr@2: IMPORT_C virtual ~CBaseMtmUiData(); williamr@2: // williamr@2: // --- Accessor functions --- williamr@2: IMPORT_C TUid Type() const; williamr@2: // williamr@2: // --- Context icons --- williamr@2: /** Gets an array of bitmaps relevant to the passed context entry. williamr@2: williamr@2: The bitmaps within the array should be representations of the same bitmap at various sizes. williamr@2: williamr@2: The aStateFlags argument indicates the user interface state, for example, williamr@2: "open", of the entry. williamr@2: williamr@2: Requirements: williamr@2: williamr@2: Implementations should check the type of the context, using TMsvEntry::iType::iUid, williamr@2: and the passed state, and return an appropriate bitmap array. williamr@2: williamr@2: @param aContext Context entry to return the icons for. williamr@2: @param aStateFlags Flasgs indicating the user interface state of the entry. williamr@2: @return Bitmap array for the given context.. */ williamr@2: virtual const CBitmapArray& ContextIcon(const TMsvEntry& aContext, TInt aStateFlags) const = 0; williamr@2: // williamr@2: // --- MTM-Specific function information (e.g. for dynamically-added menu items) --- williamr@2: IMPORT_C const CArrayFix& MtmSpecificFunctions() const; williamr@2: IMPORT_C TBool FunctionRecognised(TInt aFunctionId) const; williamr@2: // williamr@2: // --- Provide context-specific function information --- williamr@2: /** Tests if an entry can be created as a child. williamr@2: williamr@2: @param aParent The entry under which aNewEntry should be created. williamr@2: @param aNewEntry The entry to which the operation applies. williamr@2: @param aReasonResourceId On return, a resource string ID or 0. williamr@2: @return ETrue, if the operation is appropriate on the entry; williamr@2: EFalse, if the operation is NOT appropriate on the entry. */ williamr@2: virtual TBool CanCreateEntryL(const TMsvEntry& aParent, TMsvEntry& aNewEntry, TInt& aReasonResourceId) const = 0; williamr@2: /** Tests if a delete operation is supported. williamr@2: williamr@2: @param aContext The entry to which the operation applies. williamr@2: @param aReasonResourceId On return, a resource string ID or 0. williamr@2: @return ETrue, if the operation is appropriate on the entry; williamr@2: EFalse, if the operation is NOT appropriate on the entry. */ williamr@2: virtual TBool CanDeleteFromEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; williamr@2: /** Tests if the entry can be undeleted. williamr@2: williamr@2: @param aContext The entry to which the operation applies. williamr@2: @param aReasonResourceId On return, a resource string ID or 0. williamr@2: @return ETrue, if the operation is appropriate on the entry; williamr@2: EFalse, if the operation is NOT appropriate on the entry. */ williamr@2: IMPORT_C virtual TBool CanUnDeleteFromEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const; williamr@2: /** Tests if the service entry can be deleted. williamr@2: williamr@2: @param aService The service entry to which the operation applies. williamr@2: @param aReasonResourceId On return, a resource string ID or 0. williamr@2: @return ETrue, if the operation is appropriate on the entry; williamr@2: EFalse, if the operation is NOT appropriate on the entry. */ williamr@2: virtual TBool CanDeleteServiceL(const TMsvEntry& aService, TInt& aReasonResourceId) const = 0; williamr@2: /** Tests if an entry can be replied to. williamr@2: williamr@2: @param aContext The entry to which the operation applies. williamr@2: @param aReasonResourceId On return, a resource string ID or 0. williamr@2: @return ETrue, if the operation is appropriate on the entry; williamr@2: EFalse, if the operation is NOT appropriate on the entry. */ williamr@2: virtual TBool CanReplyToEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; williamr@2: /** Tests if an entry can be forwarded. williamr@2: williamr@2: @param aContext The entry to which the operation applies. williamr@2: @param aReasonResourceId On return, a resource string ID or 0. williamr@2: @return ETrue, if the operation is appropriate on the entry; williamr@2: EFalse, if the operation is NOT appropriate on the entry. */ williamr@2: virtual TBool CanForwardEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; williamr@2: /** Tests if the entry can be edited. williamr@2: williamr@2: @param aContext The entry to which the operation applies. williamr@2: @param aReasonResourceId On return, a resource string ID or 0. williamr@2: @return ETrue, if the operation is appropriate on the entry; williamr@2: EFalse, if the operation is NOT appropriate on the entry. */ williamr@2: virtual TBool CanEditEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; williamr@2: /** Tests if an entry can be viewed. williamr@2: williamr@2: @param aContext The entry to which the operation applies. williamr@2: @param aReasonResourceId On return, a resource string ID or 0. williamr@2: @return ETrue, if the operation is appropriate on the entry; williamr@2: EFalse, if the operation is NOT appropriate on the entry. */ williamr@2: virtual TBool CanViewEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; williamr@2: /** Tests if an entry can be opened. williamr@2: williamr@2: @param aContext The entry to which the operation applies. williamr@2: @param aReasonResourceId On return, a resource string ID or 0. williamr@2: @return ETrue, if the operation is appropriate on the entry; williamr@2: EFalse, if the operation is NOT appropriate on the entry. */ williamr@2: virtual TBool CanOpenEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; williamr@2: /** Tests if a close operation is supported. williamr@2: williamr@2: @param aContext The entry to which the operation applies. williamr@2: @param aReasonResourceId On return, a resource string ID, or 0 if operation williamr@2: is supported. williamr@2: @return ETrue, if the operation is appropriate on the entry; williamr@2: EFalse, if the operation is NOT appropriate on the entry. */ williamr@2: virtual TBool CanCloseEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; williamr@2: /** Tests if a copy from or move to operation is supported. williamr@2: williamr@2: @param aContext The entry to which the operation applies. williamr@2: @param aReasonResourceId On return, a resource string ID or 0. williamr@2: @return ETrue, if the operation is appropriate on the entry; williamr@2: EFalse, if the operation is NOT appropriate on the entry. */ williamr@2: virtual TBool CanCopyMoveToEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; williamr@2: /** Tests whether a copy from or move from operation is supported. williamr@2: williamr@2: @param aContext The entry to which the operation applies. williamr@2: @param aReasonResourceId On return, a resource string ID or 0. williamr@2: @return ETrue, if the operation is appropriate on the entry; williamr@2: EFalse, if the operation is NOT appropriate on the entry. */ williamr@2: virtual TBool CanCopyMoveFromEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; williamr@2: /** Tests if the current operation on the entry can be cancelled. williamr@2: williamr@2: @param aContext The entry to which the operation applies. williamr@2: @param aReasonResourceId On return, a resource string ID, or 0 if operation williamr@2: is supported. williamr@2: @return ETrue, if the operation is appropriate on the entry; williamr@2: EFalse, if the operation is NOT appropriate on the entry. */ williamr@2: virtual TBool CanCancelL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0; williamr@2: // williamr@2: // --- RTTI --- williamr@2: /** Tests if an MTM-specific operation is appropriate to the specified entry. The williamr@2: operation specified must have been obtained from a call to MtmSpecificFunctions(). williamr@2: williamr@2: It is intended that client applications will use this function to select dynamically williamr@2: the MTM-specific user interface features available dependent on the entry williamr@2: currently selected within the application. williamr@2: williamr@2: Requirements: williamr@2: williamr@2: Implementations should check the type of the context, using TMsvEntry::iType::iUid, williamr@2: and use any other information required available from the context, to determine williamr@2: if the operation is supported. williamr@2: williamr@2: @param aOperationId ID of operation to query. williamr@2: @param aContext The entry to which the operation applies. williamr@2: @return KErrNone: operation is appropriate to User Interface MTM and entry. williamr@2: Other: if the operation is not appropriate on the entry, then this is the williamr@2: ID of a string in the UI Data MTM's resource file that explains why not. */ williamr@2: virtual TInt OperationSupportedL(TInt aOperationId, const TMsvEntry& aContext) const = 0; // returns 0 if operation *IS* supported, otherwise a resource ID for the reason text williamr@2: /** Queries if the MTM supports a particular capability, specified by a UID. williamr@2: williamr@2: Requirements: williamr@2: williamr@2: Implementations should check aCapability for the standard capability values williamr@2: and return a suitable response in aResponse. If aFunctionId is unknown, return williamr@2: KErrNotSupported. williamr@2: williamr@2: @param aFunctionId UID of capability to be queried williamr@2: @param aResponse Response value. The format of the response varies according williamr@2: to the capability. williamr@2: @return KErrNone: aFunctionId is a recognised value and a response is returned williamr@2: KErrNotSupported: aFunctionId is not a recognised value */ williamr@2: virtual TInt QueryCapability(TUid aFunctionId, TInt& aResponse) const = 0; williamr@2: /** Provides status text for the sending state of the entry. williamr@2: williamr@2: @param aContext Entry to query williamr@2: @return Descriptor containing status text. */ williamr@2: virtual HBufC* StatusTextL(const TMsvEntry& aContext) const = 0; williamr@2: williamr@2: protected: williamr@2: // --- Construction --- williamr@2: IMPORT_C CBaseMtmUiData(CRegisteredMtmDll& aRegisteredMtmDll); williamr@2: IMPORT_C void ConstructL(); williamr@2: /** Initialises bitmaps and function information. williamr@2: williamr@2: Client applications do not use this function. It is relevant only to implementers of derived classes. williamr@2: williamr@2: Requirements: williamr@2: williamr@2: This function is called by the base class ConstructL() function. Implementations williamr@2: should provide this function to: williamr@2: williamr@2: 1. insert MTM-specific icon bitmap arrays into the iIconArrays array data member williamr@2: williamr@2: 2. insert MTM-specific operation information into the iMtmSpecificFunctions array williamr@2: data member */ williamr@2: virtual void PopulateArraysL() = 0; // Should populate iCapabilities, iMtmSpecificFunctions and iIconArrays williamr@2: /** Gets the resource file name. williamr@2: williamr@2: Client applications do not use this function. It is relevant only to implementers of derived classes. williamr@2: williamr@2: Requirements: williamr@2: williamr@2: Each UI Data MTM can have a resource file associated with it. Implementations williamr@2: should set aFilename to the full path and name of this resource file. The williamr@2: function is called by CBaseMtmUiData::ConstructL(), which then loads the resource williamr@2: file. williamr@2: williamr@2: @param aFileName Filename buffer to be filled with the resource file path williamr@2: and name */ williamr@2: virtual void GetResourceFileName(TFileName& aFileName) const = 0; williamr@2: // williamr@2: // --- Utility --- williamr@2: IMPORT_C void ReadFunctionsFromResourceFileL(TInt aResourceId);// Up to clients to call this if necessary williamr@2: IMPORT_C void CreateBitmapsL(TInt aNumZoomStates, const TDesC& aBitmapFile, TInt aStartBitmap, TInt aEndBitmap); williamr@2: CFbsBitmap* CreateBitmapL(const TDesC& aFileName, TInt aId) const; williamr@2: williamr@2: // Method used for extension: called by non virtual methods that need williamr@2: // to have a polymorphic behaviour. williamr@2: IMPORT_C virtual TAny* GetInterface(TUid aUid); williamr@2: williamr@2: protected: williamr@2: // --- Data --- williamr@2: /** Control environment object. It is set by the constructor. */ williamr@2: CCoeEnv* iCoeEnv; williamr@2: /** The array that stores the arrays of icon bitmaps for the UI Data MTM. Items williamr@2: are added to the array by PopulateArraysL(). */ williamr@2: CArrayPtr* iIconArrays; williamr@2: /** The array that stores MTM-specific function information for the UI Data MTM. williamr@2: Items are added to the array by ReadFunctionsFromResourceFileL(). */ williamr@2: CArrayFix* iMtmSpecificFunctions; williamr@2: williamr@2: private: williamr@2: // --- Data --- williamr@2: TInt iResourceFileOffset; williamr@2: CRegisteredMtmDll& iRegisteredMtmDll; // Required in order to call ReleaseLibrary() williamr@2: williamr@2: // Extra data member to allow for future extensions williamr@2: TAny* iExtensionData; williamr@2: }; williamr@2: williamr@2: williamr@2: #endif // __MTUDBAS_H__