CBaseMtmUiData Class Reference

#include <mw/mtudcbas.h>

Link against: mtur.lib

class CBaseMtmUiData : public CBase, public CBase

Inherits from

CBaseMtmUiData
- CBase
- CBase

Nested Classes and Structures

CBaseMtmUiData::TMtmUiFunction

Public Member Type Definitions
typedef	CArrayPtr< CFbsBitmap > CBitmapArray

Protected Attributes
CCoeEnv *	iCoeEnv
CArrayPtr< CBitmapArray > *	iIconArrays
CArrayFix< TMtmUiFunction > *	iMtmSpecificFunctions

Public Member Functions
virtual	~CBaseMtmUiData()
pure virtual TBool	CanCancelL(const TMsvEntry &, TInt &)
pure virtual TBool	CanCloseEntryL(const TMsvEntry &, TInt &)
pure virtual TBool	CanCopyMoveFromEntryL(const TMsvEntry &, TInt &)
pure virtual TBool	CanCopyMoveToEntryL(const TMsvEntry &, TInt &)
pure virtual TBool	CanCreateEntryL(const TMsvEntry &, TMsvEntry &, TInt &)
pure virtual TBool	CanDeleteFromEntryL(const TMsvEntry &, TInt &)
pure virtual TBool	CanDeleteServiceL(const TMsvEntry &, TInt &)
pure virtual TBool	CanEditEntryL(const TMsvEntry &, TInt &)
pure virtual TBool	CanForwardEntryL(const TMsvEntry &, TInt &)
pure virtual TBool	CanOpenEntryL(const TMsvEntry &, TInt &)
pure virtual TBool	CanReplyToEntryL(const TMsvEntry &, TInt &)
virtual IMPORT_C TBool	CanUnDeleteFromEntryL(const TMsvEntry &, TInt &)
pure virtual TBool	CanViewEntryL(const TMsvEntry &, TInt &)
pure virtual const CBitmapArray &	ContextIcon(const TMsvEntry &, TInt)
IMPORT_C TBool	FunctionRecognised(TInt)
IMPORT_C const CArrayFix< TMtmUiFunction > &	MtmSpecificFunctions()
pure virtual TInt	OperationSupportedL(TInt, const TMsvEntry &)
pure virtual TInt	QueryCapability(TUid, TInt &)
pure virtual HBufC *	StatusTextL(const TMsvEntry &)
IMPORT_C TUid	Type()

Protected Member Functions
	CBaseMtmUiData(CRegisteredMtmDll &)
IMPORT_C void	ConstructL()
CFbsBitmap *	CreateBitmapL(const TDesC &, TInt)
IMPORT_C void	CreateBitmapsL(TInt, const TDesC &, TInt, TInt)
virtual IMPORT_C TAny *	GetInterface(TUid)
pure virtual void	GetResourceFileName(TFileName &)
pure virtual void	PopulateArraysL()
IMPORT_C void	ReadFunctionsFromResourceFileL(TInt)

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Detailed Description

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:

1. supplying MTM-specific icons for Message Server entries

2. supplying user interface text, e.g. for menus, for MTM-specific operations

3. providing checks that MTM functions are suitable for use on an entry. 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. 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.

Message client applications use the class to access such functionality polymorphically. MTM implementers implement this class to provide such functionality for their message protocol.

Member Type Definition Documentation

Typedef CBitmapArray

typedef CArrayPtr< CFbsBitmap >

CBitmapArray

Defines an array of icon bitmaps for the UI Data MTM.

It is used in the definition of CBaseMtmUiData::iIconArrays.

Member Attribute Documentation

iCoeEnv

CCoeEnv *

iCoeEnv

[protected]

Control environment object. It is set by the constructor.

iIconArrays

CArrayPtr< CBitmapArray > *

iIconArrays

[protected]

The array that stores the arrays of icon bitmaps for the UI Data MTM. Items are added to the array by PopulateArraysL().

iMtmSpecificFunctions

CArrayFix< TMtmUiFunction > *

iMtmSpecificFunctions

[protected]

The array that stores MTM-specific function information for the UI Data MTM. Items are added to the array by ReadFunctionsFromResourceFileL().

Constructor & Destructor Documentation

CBaseMtmUiData ( CRegisteredMtmDll & )

IMPORT_C

CBaseMtmUiData

(

CRegisteredMtmDll &

aRegisteredMtmDll

)

[protected]

Constructor.

This creates a CBaseMtmUiData and initialises its private member variables. Client applications do not use this function. It is relevant only to implementers of derived classes.

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.

Parameters
aRegisteredMtmDll	Registration data for the DLL.

~CBaseMtmUiData ( )

IMPORT_C

~CBaseMtmUiData

(

)

[virtual]

Destructor.

This cleans up the base class. CBaseMtmUiData-derived objects must be deleted by client applications when they are no longer required. Clean up includes:

1. cleaning up the iIconArrays and iMtmSpecificFunctions

2. unloading the UI Data MTM resource file

Derived classes can implement a destructor to do any additional clean up tasks that they require.

Member Function Documentation

CanCancelL ( const TMsvEntry &, TInt & )

TBool	CanCancelL	(	const TMsvEntry &	aContext,
			TInt &	aReasonResourceId
		)	const [pure virtual]

Tests if the current operation on the entry can be cancelled.

Parameters
aContext	The entry to which the operation applies.
aReasonResourceId	On return, a resource string ID, or 0 if operation is supported.

Return Value: ETrue, if the operation is appropriate on the entry; EFalse, if the operation is NOT appropriate on the entry.

CanCloseEntryL ( const TMsvEntry &, TInt & )

TBool	CanCloseEntryL	(	const TMsvEntry &	aContext,
			TInt &	aReasonResourceId
		)	const [pure virtual]

Tests if a close operation is supported.

Parameters
aContext	The entry to which the operation applies.
aReasonResourceId	On return, a resource string ID, or 0 if operation is supported.

Return Value: ETrue, if the operation is appropriate on the entry; EFalse, if the operation is NOT appropriate on the entry.

CanCopyMoveFromEntryL ( const TMsvEntry &, TInt & )

TBool	CanCopyMoveFromEntryL	(	const TMsvEntry &	aContext,
			TInt &	aReasonResourceId
		)	const [pure virtual]

Tests whether a copy from or move from operation is supported.

Parameters
aContext	The entry to which the operation applies.
aReasonResourceId	On return, a resource string ID or 0.

Return Value: ETrue, if the operation is appropriate on the entry; EFalse, if the operation is NOT appropriate on the entry.

CanCopyMoveToEntryL ( const TMsvEntry &, TInt & )

TBool	CanCopyMoveToEntryL	(	const TMsvEntry &	aContext,
			TInt &	aReasonResourceId
		)	const [pure virtual]

Tests if a copy from or move to operation is supported.

Parameters
aContext	The entry to which the operation applies.
aReasonResourceId	On return, a resource string ID or 0.

Return Value: ETrue, if the operation is appropriate on the entry; EFalse, if the operation is NOT appropriate on the entry.

CanCreateEntryL ( const TMsvEntry &, TMsvEntry &, TInt & )

TBool	CanCreateEntryL	(	const TMsvEntry &	aParent,
			TMsvEntry &	aNewEntry,
			TInt &	aReasonResourceId
		)	const [pure virtual]

Tests if an entry can be created as a child.

Parameters
aParent	The entry under which aNewEntry should be created.
aNewEntry	The entry to which the operation applies.
aReasonResourceId	On return, a resource string ID or 0.

Return Value: ETrue, if the operation is appropriate on the entry; EFalse, if the operation is NOT appropriate on the entry.

CanDeleteFromEntryL ( const TMsvEntry &, TInt & )

TBool	CanDeleteFromEntryL	(	const TMsvEntry &	aContext,
			TInt &	aReasonResourceId
		)	const [pure virtual]

Tests if a delete operation is supported.

Parameters
aContext	The entry to which the operation applies.
aReasonResourceId	On return, a resource string ID or 0.

Return Value: ETrue, if the operation is appropriate on the entry; EFalse, if the operation is NOT appropriate on the entry.

CanDeleteServiceL ( const TMsvEntry &, TInt & )

TBool	CanDeleteServiceL	(	const TMsvEntry &	aService,
			TInt &	aReasonResourceId
		)	const [pure virtual]

Tests if the service entry can be deleted.

Parameters
aService	The service entry to which the operation applies.
aReasonResourceId	On return, a resource string ID or 0.

Return Value: ETrue, if the operation is appropriate on the entry; EFalse, if the operation is NOT appropriate on the entry.

CanEditEntryL ( const TMsvEntry &, TInt & )

TBool	CanEditEntryL	(	const TMsvEntry &	aContext,
			TInt &	aReasonResourceId
		)	const [pure virtual]

Tests if the entry can be edited.

Parameters
aContext	The entry to which the operation applies.
aReasonResourceId	On return, a resource string ID or 0.

Return Value: ETrue, if the operation is appropriate on the entry; EFalse, if the operation is NOT appropriate on the entry.

CanForwardEntryL ( const TMsvEntry &, TInt & )

TBool	CanForwardEntryL	(	const TMsvEntry &	aContext,
			TInt &	aReasonResourceId
		)	const [pure virtual]

Tests if an entry can be forwarded.

Parameters
aContext	The entry to which the operation applies.
aReasonResourceId	On return, a resource string ID or 0.

Return Value: ETrue, if the operation is appropriate on the entry; EFalse, if the operation is NOT appropriate on the entry.

CanOpenEntryL ( const TMsvEntry &, TInt & )

TBool	CanOpenEntryL	(	const TMsvEntry &	aContext,
			TInt &	aReasonResourceId
		)	const [pure virtual]

Tests if an entry can be opened.

Parameters
aContext	The entry to which the operation applies.
aReasonResourceId	On return, a resource string ID or 0.

Return Value: ETrue, if the operation is appropriate on the entry; EFalse, if the operation is NOT appropriate on the entry.

CanReplyToEntryL ( const TMsvEntry &, TInt & )

TBool	CanReplyToEntryL	(	const TMsvEntry &	aContext,
			TInt &	aReasonResourceId
		)	const [pure virtual]

Tests if an entry can be replied to.

Parameters
aContext	The entry to which the operation applies.
aReasonResourceId	On return, a resource string ID or 0.

Return Value: ETrue, if the operation is appropriate on the entry; EFalse, if the operation is NOT appropriate on the entry.

CanUnDeleteFromEntryL ( const TMsvEntry &, TInt & )

IMPORT_C TBool	CanUnDeleteFromEntryL	(	const TMsvEntry &	aContext,
			TInt &	aReasonResourceId
		)	const [virtual]

Tests if the entry can be undeleted.

Parameters
aContext	The entry to which the operation applies.
aReasonResourceId	On return, a resource string ID or 0.

Return Value: ETrue, if the operation is appropriate on the entry; EFalse, if the operation is NOT appropriate on the entry.KErrNone: the operation is appropriate on the entry. KErrNotSupported: the operation is not appropriate on the entry.

CanViewEntryL ( const TMsvEntry &, TInt & )

TBool	CanViewEntryL	(	const TMsvEntry &	aContext,
			TInt &	aReasonResourceId
		)	const [pure virtual]

Tests if an entry can be viewed.

Parameters
aContext	The entry to which the operation applies.
aReasonResourceId	On return, a resource string ID or 0.

Return Value: ETrue, if the operation is appropriate on the entry; EFalse, if the operation is NOT appropriate on the entry.

ConstructL ( )

IMPORT_C void

ConstructL

(

)

[protected]

Second-phase constructor.

This implements two-phase construction functions (NewL(), ConstructL()) to create a new instance of the object. Client applications do not use this function. It is relevant only to implementers of derived classes.

The function should perform any necessary dynamic allocation. ConstructL() should be called from the NewL() function of the derived class.

The default implementation of this function initiates the loading of required resources:

1. instantiates objects for the iIconArrays and iMtmSpecificFunctions protected members

2. loads the UI Data MTM's resource file, as specified by GetResourceFileName()

3. calls PopulateArraysL() so that the derived class can load 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:

ContextIcon ( const TMsvEntry &, TInt )

const CBitmapArray &	ContextIcon	(	const TMsvEntry &	aContext,
			TInt	aStateFlags
		)	const [pure virtual]

Gets 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.

The aStateFlags argument indicates the user interface state, for example, "open", of the entry.

Requirements:

Implementations should check the type of the context, using TMsvEntry::iType::iUid, and the passed state, and return an appropriate bitmap array.

Parameters
aContext	Context entry to return the icons for.
aStateFlags	Flasgs indicating the user interface state of the entry.

Return Value: Bitmap array for the given context..

CreateBitmapL ( const TDesC &, TInt )

CFbsBitmap *	CreateBitmapL	(	const TDesC &	aFileName,
			TInt	aId
		)	const [protected]

CreateBitmapsL ( TInt, const TDesC &, TInt, TInt )

IMPORT_C void	CreateBitmapsL	(	TInt	aNumZoomStates,
			const TDesC &	aBitmapFile,
			TInt	aStartBitmap,
			TInt	aEndBitmap
		)	[protected]

Fills the iIconArrays array with icon bitmaps from an mbm file.

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

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

Parameters
aNumZoomStates	Number of zoom states for each icon. This is used as the array size of each element in iIconArrays.
aBitmapFile	Filename of .mbm format bitmap array file.
aStartBitmap	First bitmap within the file for this MTM.
aEndBitmap	Final bitmap within the file for this MTM.

FunctionRecognised ( TInt )

IMPORT_C TBool

FunctionRecognised

(

TInt

aFunctionId

)

const

Tests if an operation with the specified ID is recognised by the UI Data MTM.

Implementers should note that this function searches the iMtmSpecificFunctions array for the aFunctionId.

Parameters
aFunctionId	The operation to check

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

GetInterface ( TUid )

IMPORT_C TAny *

GetInterface

(

TUid

aUid

)

[protected, virtual]

Returns a pointer to the interface with the specified Uid.

This method is the first part of an extension pattern to allow for more functionality to be supported without adding virtual methods to this base class.

The default implementation returns a NULL pointer.

Parameters
aUid	Uid of the extension interface

Return Value: Pointer to the extension interface

GetResourceFileName ( TFileName & )

void

GetResourceFileName

(

TFileName &

aFileName

)

const [protected, pure virtual]

Gets the resource file name.

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.

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

MtmSpecificFunctions ( )

IMPORT_C const CArrayFix< TMtmUiFunction > &

MtmSpecificFunctions

(

)

const

Gets 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: Array of operations relevant to the MTM and context.

OperationSupportedL ( TInt, const TMsvEntry & )

TInt	OperationSupportedL	(	TInt	aOperationId,
			const TMsvEntry &	aContext
		)	const [pure virtual]

Tests if an MTM-specific operation is appropriate to the specified entry. 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.

Parameters
aOperationId	ID of operation to query.
aContext	The entry to which the operation applies.

Return Value: 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.

PopulateArraysL ( )

void

PopulateArraysL

(

)

[protected, pure virtual]

Initialises bitmaps and function information.

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:

1. insert MTM-specific icon bitmap arrays into the iIconArrays array data member

2. insert MTM-specific operation information into the iMtmSpecificFunctions array data member

QueryCapability ( TUid, TInt & )

TInt	QueryCapability	(	TUid	aFunctionId,
			TInt &	aResponse
		)	const [pure virtual]

Queries if the MTM supports a particular capability, specified by a UID.

Requirements:

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

Parameters
aFunctionId	UID of capability to be queried
aResponse	Response value. The format of the response varies according to the capability.

Return Value: KErrNone: aFunctionId is a recognised value and a response is returned KErrNotSupported: aFunctionId is not a recognised value

ReadFunctionsFromResourceFileL ( TInt )

IMPORT_C void

ReadFunctionsFromResourceFileL

(

TInt

aResourceId

)

[protected]

Fills the iMtmSpecificFunctions array with MTM-specific operation definitions from the UI Data MTM's resource file.

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

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

Parameters
aResourceId	Resource ID of MTM-specific operation definition array

StatusTextL ( const TMsvEntry & )

HBufC *

StatusTextL

(

const TMsvEntry &

aContext

)

const [pure virtual]

Provides status text for the sending state of the entry.

Parameters
aContext	Entry to query

Return Value: Descriptor containing status text.

Type ( )

IMPORT_C TUid

Type

(

)

const

Gets the Type UID of the message type associated with the UI Data MTM.

Return Value: UID of the message type associated with the MTM