EPOC   SDK Home Glossary Indexes Previous Next Up

CBaseMtmUiData class


Contents


CBaseMtmUiData class — UI Data MTM base

Section Contents


Overview

Compatibility

Applications that use this class will not work correctly on a version of EPOC earlier than ER5.

Derivation

CBase

Abstract: CBase behaviour

Defined in

mtudcbas.h

Link against

mtur.lib

Description

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 MTM’s 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.


Construction, initialisation, and destruction


CBaseMtmUiData() — Constructor

protected: CBaseMtmUiData(CRegisteredMtmDll& aRegisteredMtmDll);

Description

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.

Arguments

CRegisteredMtmDll& aRegisteredMtmDll

Registration data for the DLL.


ConstructL() — Second stage construction

protected: void ConstructL();

Description

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.

Leave considerations

Dependent on the implementation, this function may leave with system error codes. See Error codes.


PopulateArraysL() — Initialise bitmaps and function information

protected: virtual void PopulateArraysL() = 0;

Description

Client applications do not use this function. It is relevant only to implementers of derived classes.

Requirements

This function is called by the base class ConstructL() function. Implementations should provide this function to:

Leave considerations

Dependent on the implementation, this function may leave with system error codes. See Error codes.


GetResourceFileName() — Resource file name

protected: virtual void GetResourceFileName(TFileName& aFileName) const = 0;

Description

Client applications do not use this function. It is relevant only to implementers of derived classes.

Requirements

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.

Arguments

TFileName& aFileName

Filename buffer to be filled with the resource file path and name


~CBaseMtmUiData() — Destructor

virtual ~CBaseMtmUiData();

Description

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.


Accessors


Type() — Get Type UID

TUid Type() const;

Description

Use this function to get the Type UID of the message type associated with the UI Data MTM.

Return value

TUid

UID of the message type associated with the MTM


Context-specific icons


ContextIcon() — Get context-specific icon

virtual const CBitmapArray& ContextIcon(const TMsvEntry& aContext) const = 0;

Description

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.

Requirements

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.

Arguments

const TMsvEntry& aContext

Context entry to return the icons for.

Return value

CBitmapArray&

Bitmap array for the given context..


MTM-specific function information


MtmSpecificFunctions() — Get MTM-specific operation information

const CArrayFix<TMtmUiFunction>& MtmSpecificFunctions() const;

Description

Use this function to obtain an array of MTM-specific operations that can be carried out through the associated User Interface MTM’s 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.

Return value

CArrayFix<TMtmUiFunction>&

Array of operations relevant to the MTM and context.


FunctionRecognised() — Query operation support

TBool FunctionRecognised(TInt aFunctionId) const;

Description

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.

Arguments

TInt aFunctionId

The operation to check

Return value

TBool

ETrue: operation aFunctionId is supported by this UI Data MTM.

EFalse: operation aFunctionId is not supported by this UI Data MTM.


Context-specific information

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 MTM’s 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.


CanCloseEntryL() — Can close entry

virtual TBool CanCloseEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;

Description

Use this function to check if a close operation is supported for aContext.

Arguments

const TMsvEntry& aContext

The entry to which the operation applies.

TInt& aReasonResourceId

On return, a resource string ID, or 0 if operation is supported.

Return value

TBool

KErrNone: the operation is appropriate on the entry.

KErrNotSupported: the operation is not appropriate on the entry.


CanCopyMoveFromEntryL() — Can copy or move from entry

virtual TBool CanCopyMoveFromEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;

Description

Use this function to check if a copy from or move from operation is supported for aContext.

Arguments

const TMsvEntry& aContext

The entry to which the operation applies.

TInt& aReasonResourceId

On return, a resource string ID or 0.

Return value

TBool

KErrNone: the operation is appropriate on the entry.

KErrNotSupported: the operation is not appropriate on the entry.


CanCopyMoveToEntryL() — Can copy or move to entry

virtual TBool CanCopyMoveToEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;

Description

Use this function to check if a copy from or move to operation is supported for aContext.

Arguments

const TMsvEntry& aContext

The entry to which the operation applies.

TInt& aReasonResourceId

On return, a resource string ID or 0.

Return value

TBool

KErrNone: the operation is appropriate on the entry.

KErrNotSupported: the operation is not appropriate on the entry.


CanCreateEntryL() — Can create entry

virtual TBool CanCreateEntryL(const TMsvEntry& aParent, const TMsvEntry& aNewEntry, TInt& aReasonResourceId) const = 0;

Description

Use this function to check if aNewEntry can be created as a child of aParent.

Arguments

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.

Return value

TBool

KErrNone: the operation is appropriate on the entry.

KErrNotSupported: the operation is not appropriate on the entry.


CanDeleteFromEntryL() — Can delete entry

virtual TBool CanDeleteFromEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;

Description

Use this function to check if a delete operation is supported for aContext.

Arguments

const TMsvEntry& aContext

The entry to which the operation applies.

TInt& aReasonResourceId

On return, a resource string ID or 0.

Return value

TBool

KErrNone: the operation is appropriate on the entry.

KErrNotSupported: the operation is not appropriate on the entry.


CanDeleteServiceL() — Can delete service

virtual TBool CanDeleteServiceL(const TMsvEntry& aService, TInt& aReasonResourceId) const = 0;

Description

Use this function to check if the service aService can be deleted.

Arguments

const TMsvEntry& aService

The service entry to which the operation applies.

TInt& aReasonResourceId

On return, a resource string ID or 0.

Return value

TBool

KErrNone: the operation is appropriate on the entry.

KErrNotSupported: the operation is not appropriate on the entry.


CanEditEntryL() — Can edit entry

virtual TBool CanEditEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;

Description

Use this function to check if aContext can be edited.

Arguments

const TMsvEntry& aContext

The entry to which the operation applies.

TInt& aReasonResourceId

On return, a resource string ID or 0.

Return value

TBool

KErrNone: the operation is appropriate on the entry.

KErrNotSupported: the operation is not appropriate on the entry.


CanForwardEntryL() — Can forward entry

virtual TBool CanForwardEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;

Description

Use this function to check if aContext can be forwarded.

Arguments

const TMsvEntry& aContext

The entry to which the operation applies.

TInt& aReasonResourceId

On return, a resource string ID or 0.

Return value

TBool

KErrNone: the operation is appropriate on the entry.

KErrNotSupported: the operation is not appropriate on the entry.


CanOpenEntryL() — Can open entry

virtual TBool CanOpenEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;

Description

Use this function to check if aContext can be opened.

Arguments

const TMsvEntry& aContext

The entry to which the operation applies.

TInt& aReasonResourceId

On return, a resource string ID or 0.

Return value

TBool

KErrNone: the operation is appropriate on the entry.

KErrNotSupported: the operation is not appropriate on the entry.


CanReplyToEntryL() — Can reply to entry

virtual TBool CanReplyToEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;

Description

Use this function to check if aContext can be replied to.

Arguments

const TMsvEntry& aContext

The entry to which the operation applies.

TInt& aReasonResourceId

On return, a resource string ID or 0.

Return value

TBool

KErrNone: the operation is appropriate on the entry.

KErrNotSupported: the operation is not appropriate on the entry.


CanViewEntryL() — Can view entry

virtual TBool CanViewEntryL(const TMsvEntry& aContext, TInt& aReasonResourceId) const = 0;

Description

Use this function to check if aContext can be viewed.

Arguments

const TMsvEntry& aContext

The entry to which the operation applies.

TInt& aReasonResourceId

On return, a resource string ID or 0.

Return value

TBool

KErrNone: the operation is appropriate on the entry.

KErrNotSupported: the operation is not appropriate on the entry.


MTM-specific functionality


OperationSupportedL() — Context-sensitive operation query

virtual TInt OperationSupportedL(TInt aOperationId, const TMsvEntry& aContext) const = 0;

Description

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.

Requirements

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.

Arguments

TInt aOperationId

ID of operation to query.

const TMsvEntry& aContext

The entry to which the operation applies.

Return value

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 MTM’s resource file that explains why not.


QueryCapability() — Query for capability

virtual TInt QueryCapability(TUid aFunctionId, TInt& aResponse) const = 0;

Description

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.

Requirements

Implementations should check aCapability for the standard capability values and return a suitable response in aResponse. If aFunctionId is unknown, return KErrNotSupported.

Arguments

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.

Return value

TInt

KErrNone: aFunctionId is a recognised value and a response is returned

KErrNotSupported: aFunctionId is not a recognised value


Utility


ReadFunctionsFromResourceFileL() — Fill operation array

protected: void ReadFunctionsFromResourceFileL(TInt aResourceId);

Description

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 MTM’s 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().

Arguments

TInt aResourceId

Resource ID of MTM-specific operation definition array

Leave considerations

This function may leave with system error codes. See Error codes.


CreateBitmapsL() — Fill bitmap array

protected: void CreateBitmapsL(TInt aNumZoomStates, const TDesC& aBitmapFile, TInt aStartBitmap, TInt aEndBitmap);

Description

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().

Arguments

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 .mbm format bitmap array file.

TInt aStartBitmap

First bitmap within the file for this MTM.

TInt aEndBitmap

Final bitmap within the file for this MTM.

Leave considerations

This function may leave with system error codes. See Error codes.


Protected data members

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().


Typedefs


CBitmapArray — Array of bitmaps

typedef CArrayPtr<CFbsBitmap> CBitmapArray;

Defined in

mtudcbas.h

Description

This type defines an arrays of icon bitmaps for the UI Data MTM. It is used in the definition of CBaseMtmUiData::iIconArrays.


CBaseMtmUiData::TMtmUiFunction class — MTM-specific operations

Section Contents


Overview

Compatibility

Applications that use this class will not work correctly on a version of EPOC earlier than ER5.

Defined in

mtudcbas.h

Link against

mtur.lib

Description

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.


Constructors


TMtmUiFunction() — Constructor

TMtmUiFunction(const TDesC& aCaption, TInt aFunctionId, TInt aHotKey, TInt aModifiers, TInt aFlags=0);

Description

Use this function to create a TMtmUiFunction with the specified values.

Arguments

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() — Construct from resource file

TMtmUiFunction(TResourceReader& aResourceReader);            

Description

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.

Arguments

TResourceReader& aResourceReader

Position in UI Data MTM resource file to read operation


Data members

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


Enumerations


Anonymous enum — Maximum caption length

ECaptionMaxLen

Maximum length for operation caption. Used in defining iCaption

EPOC       SDK Home Glossary Indexes Previous Next Up