![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Section Contents
Applications that use this class will not work correctly on a version of EPOC earlier than ER5.
CBase |
Abstract: CBase behaviour |
mtudcbas.h
mtur.lib
This class is the base class for UI Data MTM components. CBaseMtmUiData-derived classes allow message client applications to customise dynamically their user interfaces for a particular message type. For example, if a message client application currently had a fax entry selected, then it could use the fax MTMs concrete class to get information on the menus and icons that it should display.
Specifically, functionality falls into the following three areas:
Message client applications use the class to access such functionality polymorphically. MTM implementers implement this class to provide such functionality for their message protocol.
For more on CBaseMtmUiData-derived classes, see UI Data MTMs.
protected: CBaseMtmUiData(CRegisteredMtmDll& aRegisteredMtmDll);
Client applications do not use this function. It is relevant only to implementers of derived classes.
The base class constructor initialises private member variables. Derived classes can implement a constructor to perform any additional MTM-specific setup that can be safely carried out in a constructor. Such constructors must call the base class constructor function.
CRegisteredMtmDll& aRegisteredMtmDll |
Registration data for the DLL. |
protected: void ConstructL();
Client applications do not use this function. It is relevant only to implementers of derived classes.
Derived classes implement two-phase construction functions (NewL(), ConstructL()) to create a new instance of the object, in which any dynamic allocation should be performed. ConstructL() should be called from the NewL() function of the derived class.
The default implementation of this function initiates the loading of required resources:
Derived classes can implement this function to perform any additional MTM-specific second stage construction tasks that they require. Implementations must call the base class ConstructL() function.
Concrete MTMs must also implement a factory function by which a MTM registry can request an instance of the class: for details, see MtmUiDataFactoryFunctionL typedef.
Dependent on the implementation, this function may leave with system error codes. See Error codes.
protected: virtual void PopulateArraysL() = 0;
Client applications do not use this function. It is relevant only to implementers of derived classes.
This function is called by the base class ConstructL() function. Implementations should provide this function to:
Dependent on the implementation, this function may leave with system error codes. See Error codes.
protected: virtual void GetResourceFileName(TFileName& aFileName) const = 0;
Client applications do not use this function. It is relevant only to implementers of derived classes.
Each UI Data MTM can have a resource file associated with it. Implementations should set aFilename to the full path and name of this resource file. The function is called by CBaseMtmUiData::ConstructL(), which then loads the resource file.
TFileName& aFileName |
Filename buffer to be filled with the resource file path and name |
virtual ~CBaseMtmUiData();
CBaseMtmUiData-derived objects must be deleted by client applications when they are no longer required. This function cleans up the base class, including:
Derived classes can implement a destructor to do any additional clean up tasks that they require.
TUid Type() const;
Use this function to get the Type UID of the message type associated with the UI Data MTM.
TUid |
UID of the message type associated with the MTM |
virtual const CBitmapArray& ContextIcon(const TMsvEntry& aContext) const = 0;
Use this function to get an array of bitmaps relevant to the passed context entry. The bitmaps within the array should be representations of the same bitmap at various sizes.
Implementations should check the type of the context, using TMsvEntry::iType::iUid, and on this basis return the appropriate bitmap array for that context type.
const TMsvEntry& aContext |
Context entry to return the icons for. |
CBitmapArray& |
Bitmap array for the given context.. |
const CArrayFix<TMtmUiFunction>& MtmSpecificFunctions() const;
Use this function to obtain an array of MTM-specific operations that can be carried out through the associated User Interface MTMs CBaseMtmUi::InvokeSyncFunctionL()/InvokeAsyncFunctionL() functions.
It is intended that message client applications will use this function to add dynamically user interface features, such as menu items, dependent on the MTM type of the entry currently selected within the application. Message client applications can also use OperationSupportedL() to check dynamically if a particular operation is appropriate to a particular entry.
Implementers should note that this function returns a pointer to the iMtmSpecificFunctions data member.
CArrayFix<TMtmUiFunction>& |
Array of operations relevant to the MTM and context. |
TBool FunctionRecognised(TInt aFunctionId) const;
Use this function to check if an operation with ID aFunctionId is recognised by the UI Data MTM.
Implementers should note that this function searches the iMtmSpecificFunctions array for the aFunctionId.
TInt aFunctionId |
The operation to check |
TBool |
ETrue: operation aFunctionId is supported by this UI Data MTM. EFalse: operation aFunctionId is not supported by this UI Data MTM. |
Use these functions to check if a particular operation provided by CBaseMtmUi interface can be carried out on a specified entry. Note that OperationSupportedL() performs a similar function for MTM-specific functions. Implementations should determine if the operation is supported by checking the properties of the entry, such as its type.
If the operation is not appropriate on the entry, then the aReasonResourceId argument is set to the ID of a string in the UI Data MTMs resource file that explains why not. Otherwise, aReasonResourceId is 0.
It is intended that client applications will use these functions to select dynamically the user interface features available dependent on the entry currently selected within the application. For example, menu items that do not apply to particular entries could be greyed out.
For the exact semantics of an action given below, such as editing, see the CBaseMtmUi documentation.
virtual TBool CanCloseEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
Use this function to check if a close operation is supported for aContext.
const TMsvEntry& aContext |
The entry to which the operation applies. |
TInt& aReasonResourceId |
On return, a resource string ID, or 0 if operation is supported. |
TBool |
KErrNone: the operation is appropriate on the entry. KErrNotSupported: the operation is not appropriate on the entry. |
virtual TBool CanCopyMoveFromEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
Use this function to check if a copy from or move from operation is supported for aContext.
const TMsvEntry& aContext |
The entry to which the operation applies. |
TInt& aReasonResourceId |
On return, a resource string ID or 0. |
TBool |
KErrNone: the operation is appropriate on the entry. KErrNotSupported: the operation is not appropriate on the entry. |
virtual TBool CanCopyMoveToEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
Use this function to check if a copy from or move to operation is supported for aContext.
const TMsvEntry& aContext |
The entry to which the operation applies. |
TInt& aReasonResourceId |
On return, a resource string ID or 0. |
TBool |
KErrNone: the operation is appropriate on the entry. KErrNotSupported: the operation is not appropriate on the entry. |
virtual TBool CanCreateEntryL(const TMsvEntry& aParent, const TMsvEntry& aNewEntry, TInt& aReasonResourceId) const = 0;
Use this function to check if aNewEntry can be created as a child of aParent.
const TMsvEntry& aParent |
The entry under which aNewEntry should be created. |
const TMsvEntry& aNewEntry |
The entry to which the operation applies. |
TInt& aReasonResourceId |
On return, a resource string ID or 0. |
TBool |
KErrNone: the operation is appropriate on the entry. KErrNotSupported: the operation is not appropriate on the entry. |
virtual TBool CanDeleteFromEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
Use this function to check if a delete operation is supported for aContext.
const TMsvEntry& aContext |
The entry to which the operation applies. |
TInt& aReasonResourceId |
On return, a resource string ID or 0. |
TBool |
KErrNone: the operation is appropriate on the entry. KErrNotSupported: the operation is not appropriate on the entry. |
virtual TBool CanDeleteServiceL(const TMsvEntry& aService, TInt& aReasonResourceId) const = 0;
Use this function to check if the service aService can be deleted.
const TMsvEntry& aService |
The service entry to which the operation applies. |
TInt& aReasonResourceId |
On return, a resource string ID or 0. |
TBool |
KErrNone: the operation is appropriate on the entry. KErrNotSupported: the operation is not appropriate on the entry. |
virtual TBool CanEditEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
Use this function to check if aContext can be edited.
const TMsvEntry& aContext |
The entry to which the operation applies. |
TInt& aReasonResourceId |
On return, a resource string ID or 0. |
TBool |
KErrNone: the operation is appropriate on the entry. KErrNotSupported: the operation is not appropriate on the entry. |
virtual TBool CanForwardEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
Use this function to check if aContext can be forwarded.
const TMsvEntry& aContext |
The entry to which the operation applies. |
TInt& aReasonResourceId |
On return, a resource string ID or 0. |
TBool |
KErrNone: the operation is appropriate on the entry. KErrNotSupported: the operation is not appropriate on the entry. |
virtual TBool CanOpenEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
Use this function to check if aContext can be opened.
const TMsvEntry& aContext |
The entry to which the operation applies. |
TInt& aReasonResourceId |
On return, a resource string ID or 0. |
TBool |
KErrNone: the operation is appropriate on the entry. KErrNotSupported: the operation is not appropriate on the entry. |
virtual TBool CanReplyToEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
Use this function to check if aContext can be replied to.
const TMsvEntry& aContext |
The entry to which the operation applies. |
TInt& aReasonResourceId |
On return, a resource string ID or 0. |
TBool |
KErrNone: the operation is appropriate on the entry. KErrNotSupported: the operation is not appropriate on the entry. |
virtual TBool CanViewEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;
Use this function to check if aContext can be viewed.
const TMsvEntry& aContext |
The entry to which the operation applies. |
TInt& aReasonResourceId |
On return, a resource string ID or 0. |
TBool |
KErrNone: the operation is appropriate on the entry. KErrNotSupported: the operation is not appropriate on the entry. |
virtual TInt OperationSupportedL(TInt aOperationId, const TMsvEntry& aContext) const = 0;
Use this function to check if an MTM-specific operation is appropriate to the entry specified in aContext. The operation specified must have been obtained from a call to MtmSpecificFunctions().
It is intended that client applications will use this function to select dynamically the MTM-specific user interface features available dependent on the entry currently selected within the application.
Implementations should check the type of the context, using TMsvEntry::iType::iUid, and use any other information required available from the context, to determine if the operation is supported.
TInt aOperationId |
ID of operation to query. |
const TMsvEntry& aContext |
The entry to which the operation applies. |
TInt |
KErrNone: operation is appropriate to User Interface MTM and entry. Other: if the operation is not appropriate on the entry, then this is the ID of a string in the UI Data MTMs resource file that explains why not. |
virtual TInt QueryCapability(TUid aFunctionId, TInt& aResponse) const = 0;
Use this function to query if the MTM supports a particular capability, specified by a UID. For a list of standard capability UIDs, see Capability constants.
Implementations should check aCapability for the standard capability values and return a suitable response in aResponse. If aFunctionId is unknown, return KErrNotSupported.
TUid aFunctionId |
UID of capability to be queried |
TInt& aResponse |
Response value. The format of the response varies according to the capability. See Capability constants for the standard responses. |
TInt |
KErrNone: aFunctionId is a recognised value and a response is returned KErrNotSupported: aFunctionId is not a recognised value |
protected: void ReadFunctionsFromResourceFileL(TInt aResourceId);
Client applications do not use this function. It is relevant only to implementers of derived classes.
Implementers can call this function to fill the iMtmSpecificFunctions array with MTM-specific operation definitions from the UI Data MTMs resource file. For each MTM-specific operation definition in the resource file, it adds a corresponding TMtmUiFunction object to iMtmSpecificFunctions.
The function is typically called from PopulateArraysL().
TInt aResourceId |
Resource ID of MTM-specific operation definition array |
This function may leave with system error codes. See Error codes.
protected: void CreateBitmapsL(TInt aNumZoomStates, const TDesC& aBitmapFile, TInt aStartBitmap, TInt aEndBitmap);
Client applications do not use this function. It is relevant only to implementers of derived classes.
Implementers can call this function to fill the iIconArrays array with icon bitmaps from an EPOC .mbm
file. The bitmaps to load must be contiguous within the file between the positions indicated by aStartBitmap and aEndBitmap.
The function is typically called from PopulateArraysL().
TInt aNumZoomStates |
Number of zoom states for each icon. This is used as the array size of each element in iIconArrays. |
const TDesC& aBitmapFile |
Filename of |
TInt aStartBitmap |
First bitmap within the file for this MTM. |
TInt aEndBitmap |
Final bitmap within the file for this MTM. |
This function may leave with system error codes. See Error codes.
The following protected data members can be accessed by implementers of derived classes.
CCoeEnv* iCoeEnv |
CONE environment object. It is set by the constructor. |
CArrayPtr<CBitmapArray>* iIconArrays |
The array that stores the arrays of icon bitmaps for the UI Data MTM. Items are added to the array by PopulateArraysL(). |
CArrayFix<TMtmUiFunction>* iMtmSpecificFunctions |
The array that stores MTM-specific function information for the UI Data MTM. Items are added to the array by ReadFunctionsFromResourceFileL(). |
typedef CArrayPtr<CFbsBitmap> CBitmapArray;
mtudcbas.h
This type defines an arrays of icon bitmaps for the UI Data MTM. It is used in the definition of CBaseMtmUiData::iIconArrays.
Section Contents
Applications that use this class will not work correctly on a version of EPOC earlier than ER5.
mtudcbas.h
mtur.lib
Provides the interface for clients to access MTM-specific functions, and present these functions to the user. A message client application can use this information to customise the UI.
The class encapsulates information relating to an MTM-specific operation:
See also CBaseMtmUiData members ReadFunctionsFromResourceFileL(), PopulateArraysL(), MtmSpecificFunctions(), and iMtmSpecificFunctions.
TMtmUiFunction(const TDesC& aCaption, TInt aFunctionId, TInt aHotKey, TInt aModifiers, TInt aFlags=0);
Use this function to create a TMtmUiFunction with the specified values.
const TDesC& aCaption |
String, suitable for a menu, describing the operation |
TInt aFunctionId |
The ID that can be used to invoke the operation |
TInt aHotKey |
Character code for a suggested hotkey for the operation |
TInt aModifiers |
Suggested key modifiers for the hotkey. See Key flags |
TInt aFlags=0 |
Flags setting characteristics of the operation: for details see Function flags |
TMtmUiFunction(TResourceReader& aResourceReader);
Use this function to create a TMtmUiFunction with its values read from the resource file location specified by TResourceReader. This position should be at a MTUD_FUNCTION resource.
TResourceReader& aResourceReader |
Position in UI Data MTM resource file to read operation |
TBuf<ECaptionMaxLen> iCaption |
String, suitable for a menu, describing the operation |
TInt iPreferredHotKeyKeyCode |
Character code for a suggested hotkey for the operation |
TInt iPreferredHotKeyModifiers |
Suggested key modifiers for the hotkey. See Key flags |
TInt iFunctionId |
The ID that can be used to invoke the operation |
TInt iFlags |
Flags setting characteristics of the operation: for details see Function flags |
Maximum length for operation caption. Used in defining iCaption |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |