CEikonEnv Class Reference

aControl

)

Adds an alert dialog-like control (with a control stack priority of ECoeStackPriorityAlert) to the control stack.

Alert dialogs are used to indicate errors to the user.

It leaves with no alert if a control with a priority between ECoeStackPriorityAlert and ECoeStackPriorityFep is already being displayed by the appUi.

Parameter	Description
aControl	The control to add.

AddAppUiFactoryL ( MEikAppUiFactory * )

IMPORT_C void

AddAppUiFactoryL

(

MEikAppUiFactory *

aAppUiFactory

)

AddAutoMenuTitleL ( CEikAutoMenuTitle * )

IMPORT_C void

AddAutoMenuTitleL

(

CEikAutoMenuTitle *

aTitle

)

Adds a menu title to the menu bar for all applications.

Takes ownership of aTitle at the end of the function. Push the CEikAutoMenuTitle object on the cleanup stack before calling this method, and pop it after.

Parameter	Description
aTitle	Menu title to add to all applications' menu bars.

AddDialogLikeControlToStackL ( CCoeControl * )

IMPORT_C void

AddDialogLikeControlToStackL

(

aControl

)

Adds a dialog-like control (with a control stack priority of ECoeStackPriorityDialog) to the control stack.

It leaves with no alert if a control with a priority between ECoeStackPriorityDialog and ECoeStackPriorityFep is already being displayed by the appUi.

Parameter	Description
aControl	The control to add.

AddLibraryL ( TCreateByTypeFunction, TFileName * )

IMPORT_C TInt	AddLibraryL	(	TCreateByTypeFunction	aControlFactory,
			TFileName *	aResourceFile
		)

Adds the control factory and resource file to the Eikon Environment. This function does not add the control factory if it is NULL.

Parameter	Description
aControlFactory	Control factory that has to be added to the Eikon Environment.
aResourceFile	Resource file that has to be added to the Eikon Environment.

Returns: Zero, if the resource file is NULL otherwise the offset value defined for this resource file.

AddLibraryL ( TCreateByTypeFunction )

TInt

AddLibraryL

(

TCreateByTypeFunction

aControlFactory

)

[inline]

AddLibraryL ( TFileName * )

TInt

AddLibraryL

(

TFileName *

aResourceFile

)

[inline]

AddPictureFactoryL ( MEikPictureFactory & )

IMPORT_C void

AddPictureFactoryL

(

MEikPictureFactory &

aFactory

)

Adds the picture factory to the set of factories maintained by the Uikon environment.

Parameter	Description
aFactory	The picture factory to add.

AddSleepingAlertDialogToStackL ( CCoeControl * )

IMPORT_C void

AddSleepingAlertDialogToStackL

(

aControl

)

Adds a sleeping dialog to the control stack, with a control stack priority of ECoeStackPriorityAlert.

Sleeping dialogs pre-allocate their resources - they are not initially visible.

Parameter	Description
aControl	The control to add.

AddSleepingDialogToStackL ( CCoeControl * )

IMPORT_C void

AddSleepingDialogToStackL

(

aControl

)

Adds a sleeping dialog to the control stack, with a control stack priority of ECoeStackPriorityDialog.

Sleeping dialogs pre-allocate their resources - they are not initially visible.

Parameter	Description
aControl	The control to add.

AddWindowShadow ( CCoeControl * )

IMPORT_C void

AddWindowShadow

(

aWinArea

)

[static]

Adds a window shadow of the standard height to a control.

Alert ( )

const MEikAlertWin *

Alert

(

)

const [inline]

AlertWin ( const TDesC & )

IMPORT_C void

AlertWin

(

const TDesC &

aMsg

)

Displays the environment's alert window containing a single line message.

Parameter	Description
aMsg	Message to be displayed in the alert window.

AlertWin ( const TDesC &, const TDesC & )

IMPORT_C void	AlertWin	(	const TDesC &	aMsg1,
			const TDesC &	aMsg2
		)

Displays an alert window with a brief message.

Parameter	Description
aMsg1	First line of the message.
aMsg2	Second line of the message.

AllocInfoMsg ( )

IMPORT_C void

AllocInfoMsg

(

)

Constructs an allocation information message.

The message includes the total number of cells allocated on the current thread's heap and the total space allocated to them.

AnnotationFont ( )

IMPORT_C const CFont *

AnnotationFont

(

)

const

Gets the standard annotation font for this environment.

It is highly recommended to use CCoeControl::ScreenFont() instead of this function.

See also: CCoeControl::ScreenFont() CCoeFontProvider

Returns: Pointer to the annotation font.

AppServer ( )

IMPORT_C CEikAppServer *

AppServer

(

)

const

Gets required application server for running the application.

Returns: Pointer to the application server which is derived from CEikAppServer.

AppUiFactory ( )

IMPORT_C MEikAppUiFactory *

AppUiFactory

(

)

const

Gets the application UI factory object.

This object implements the MEikAppUiFactory interface.

Returns: App UI factory interface or NULL.

AppUiFactory ( const CEikAppUi & )

IMPORT_C MEikAppUiFactory *

AppUiFactory

(

const CEikAppUi &

aAppUi

)

const

Gets the application UI factory object for the specified app UI.

If the specified app UI does not exist in this environment, the function returns NULL. Otherwise the function returns an object which implements the MEikAppUiFactory interface.

Parameter	Description
aAppUi	The app UI for this application.

Returns: The app UI factory object, or NULL if aAppUi does't exist in this environment.

ApplicationLanguage ( )

TLanguage

ApplicationLanguage

(

)

const

AutoMenuTitleArray ( )

CEikAutoMenuTitleArray *

AutoMenuTitleArray

(

)

const [inline]

Beep ( )

IMPORT_C void

Beep

(

)

[static]

Emits a beep.

This method is deprecated.

Bitmap ( TUid )

IMPORT_C const CFbsBitmap *

Bitmap

(

TUid

aUidBmp

)

const

Gets the specified bitmap.

This function returns a bitmap from the list of bitmaps by using the UID as an index.

Parameter	Description
aUidBmp	The UID of the bitmap to retrieve.

Returns: Pointer to the bitmap.

BringForwards ( TBool, TInt )

IMPORT_C void	BringForwards	(	TBool	aForwards,
			TInt	aPriority = ECoeWinPriorityAlwaysAtFront
		)

Repositions the root window group in the stacking hierarchy, or pushes it to the back.

Calls to this function are ignored if the autoforward flag is set to ETrue.

Parameter	Description
aForwards	ETrue to reposition the root window group at aPriority. EFalse to push the root window group to the back.
aPriority	If aForwards is ETrue then this argument determines where the root window group is placed in the stacking hierarchy.

BusyMsgCancel ( )

IMPORT_C void

BusyMsgCancel

(

)

Cancels any existing busy message.

BusyMsgL ( const TDesC & )

IMPORT_C void

BusyMsgL

(

const TDesC &

aDes

)

Displays a flashing busy message in the system default corner of the screen.

Parameter	Description
aDes	Message to display.

BusyMsgL ( const TDesC &, TGulAlignment )

IMPORT_C void	BusyMsgL	(	const TDesC &	aDes,
			TGulAlignment	aCorner
		)

Displays a flashing busy message in the specified corner of the screen.

Parameter	Description
aDes	Message to display.
aCorner	Corner of the screen in which to display the message.

BusyMsgL ( TInt )

IMPORT_C void

BusyMsgL

(

aResourceId

)

Displays a flashing busy message in the system default corner of the screen.

The message's text is read from resource.

Parameter	Description
aResourceId	ID of the resource that specifies the text to display.

BusyMsgL ( const TDesC &, TTimeIntervalMicroSeconds32 )

IMPORT_C void	BusyMsgL	(	const TDesC &	aDes,
			TTimeIntervalMicroSeconds32	aInitialDelay
		)

Displays a flashing busy message in the system default corner of the screen for a specific amount of time.

Parameter	Description
aDes	Message to display.
aInitialDelay	Delay in microseconds before the message is first shown.

BusyMsgL ( const TDesC &, TGulAlignment, TTimeIntervalMicroSeconds32 )

IMPORT_C void	BusyMsgL	(	const TDesC &	aDes,
			TGulAlignment	aCorner,
			TTimeIntervalMicroSeconds32	aInitialDelay
		)

Displays a flashing busy message for a specific amount of time in the corner of the screen indicated by aCorner.

Parameter	Description
aDes	Message to display.
aCorner	Corner of the screen in which to display the message.
aInitialDelay	Delay in microseconds before the message is first shown.

BusyMsgL ( TInt, TTimeIntervalMicroSeconds32 )

IMPORT_C void	BusyMsgL	(	TInt	aResourceId,
			TTimeIntervalMicroSeconds32	aInitialDelay
		)

Displays a flashing busy message in the system default corner of the screen for a specific amount of time.

The message's text is read from resource.

Parameter	Description
aResourceId	The ID of a text resource specifying the message text.
aInitialDelay	Delay in microseconds before the message is first shown.

CDlgDialogFactory ( )

MEikCDlgDialogFactory *

CDlgDialogFactory

(

)

const [inline]

ClockDllL ( )

IMPORT_C RAnimDll &

ClockDllL

(

)

Gets the animated DLL that is used to animate the toolbar clock of the application using this CEikonEnv.

Returns: Reference to the RAnimDll.

Color ( TLogicalColor )

TRgb

Color

(

TLogicalColor

aLogicalColor

)

const [inline]

Gets the physical (TRgb) colour which corresponds to a logical colour.

Parameter	Description
aLogicalColor	A logical colour value.

Returns: The physical colour which corresponds to aLogicalColor.

ColorList ( )

CColorList &

ColorList

(

)

const [inline]

Gets the application's colour list.

The colour list provides member functions to retrieve and modify colours in the list, and to append new arrays of colours to the colour list.

Returns: The application's colour list

ConfirmLossOfAllChangesL ( )

IMPORT_C TBool

ConfirmLossOfAllChangesL

(

)

const

Displays a dialog asking the user to confirm that all changes will be lost to the current document, and returns the response.

Returns: Whether the user wants to lose all changes.

ConstructAppFromCommandLineL ( const TApaApplicationFactory &, const CApaCommandLine & )

IMPORT_C void	ConstructAppFromCommandLineL	(	const TApaApplicationFactory &	aApplicationFactory,
			const CApaCommandLine &	aCommandLine
		)

Initialises an application

Constructs a new application consisting of a CEikAppUi, a CEikApplication, and a CEikDocument. The new application starts with a new controlling process and runs in this Uikon environment. The new application is passed any command line file using the function CEikAppUi::ProcessCommandParametersL().

ConstructL ( )

IMPORT_C void

ConstructL

(

)

Reimplemented from CCoeEnv::ConstructL()

Second-phase constructor.

This calls the next overload with ETrue as the parameter.

ConstructL ( TBool )

IMPORT_C void

ConstructL

(

aInitialFocusState

)

Reimplemented from CCoeEnv::ConstructL(TBool)

Second-phase constructor.

Calls the next overload with a default window group ID which will be ignored.

Parameter	Description
aInitialFocusState	The window group's initial focus state. If ETrue, keyboard focus is enabled, if EFalse, keyboard focus is disabled.

ConstructL ( TBool, TInt )

IMPORT_C void	ConstructL	(	TBool	aInitialFocusState,
			TInt	aWindowGroupID
		)

Reimplemented from CCoeEnv::ConstructL(TBool,TInt)

Second-phase constructor.

Parameter	Description
aInitialFocusState	The window group's initial focus state. If ETrue, keyboard focus is enabled, if EFalse, keyboard focus is disabled.
aWindowGroupID	The window group ID of the parent window

ConstructorError ( )

TInt

ConstructorError

(

)

const

ControlColor ( TLogicalColor, const CCoeControl & )

IMPORT_C TRgb	ControlColor	(	TLogicalColor	aLogicalColor,
			const CCoeControl &	aControl
		)	const

Gets the physical (TRgb) colour which corresponds to the logical colour specified from the application's colour list.

If the colour of the control specified in aControl has been overridden using CCoeControl::OverrideColorL(), this function will return the overridden colour.

Parameter	Description
aLogicalColor	A logical colour value.
aControl	A pointer to the control itself.

Returns: The physical colour which corresponds to aLogicalColor.

ControlFactoryFuncArray ( )

CArrayFix< TCreateByTypeFunction > *

ControlFactoryFuncArray

(

)

const

Returns control factory function array (pointer)

ControlStackReadyL ( )

IMPORT_C void

ControlStackReadyL

(

)

Called by the framework to finish environment construction once the control stack has been created and is ready.

CreateBitmapL ( const TDesC &, TInt )

IMPORT_C CWsBitmap *	CreateBitmapL	(	const TDesC &	aFileName,
			TInt	aId
		)

Loads, allocates and returns a pointer to a bitmap loaded from a multi-bitmap file (.mbm).

If aFileName is an empty TDesC, then a default value of z:.mbm is used. If the default can't be found the alternative default location z:.mbm will be used. If a wildcard character ("*") is specified as the file name, the default application resource file will be used.

If the function leaves it will also display an error dialog to the user.

Parameter	Description
aFileName	File name specifying the bitmap file to load.
aId	Number of the bitmap in the file.

Returns: Pointer to the loaded bitmap. Ownership is transferred to the caller.

CreateBitmapL ( const TDesC &, TInt, TBool )

IMPORT_C CWsBitmap *	CreateBitmapL	(	const TDesC &	aFileName,
			TInt	aId,
			TBool	aShowDlgIfErr
		)

Loads, allocates and returns a pointer to a bitmap loaded from a multi-bitmap file (.mbm).

Parameter	Description
aFileName	File name specifying the bitmap file to load.
aId	Number of the bitmap in the file.
aShowDlgIfErr	If true then the function will also display an error dialog if it leaves.

Returns: Pointer to the loaded bitmap. Ownership is transferred to the caller.

CreateIconFromMaskedBitmapL ( const CApaMaskedBitmap & )

IMPORT_C CGulIcon *

CreateIconFromMaskedBitmapL

(

const CApaMaskedBitmap &

aApaMaskedBitmap

)

[static]

Creates an icon from a masked bitmap.

The icon is created by copying the image bitmap and mask from the masked bitmap aApaMaskedBitmap. It returns a pointer to the icon and transfers ownership to the caller.

Parameter	Description
aApaMaskedBitmap	The masked bitmap from which the icon is created.

Returns: Pointer to the icon.

CreateIconL ( const TDesC &, TInt, TInt )

IMPORT_C CGulIcon *	CreateIconL	(	const TDesC &	aFileName,
			TInt	aBitmapId,
			TInt	aMaskId = KErrNotFound
		)

Creates an icon.

The icon is created by loading the image bitmap identified by aBitmapId and the mask identified by aMaskId from the resource file aFileName. It returns a pointer to the icon and transfers ownership.

Parameter	Description
aFileName	The resource file name. If this is zero, the Uikon resource file will be used. If the wildcard character ('*') is specified, the default application resource file will be used.
aBitmapId	The bitmap ID.
aMaskId	The bitmap mask ID.

Returns: Pointer to the created icon.

CreateSystemColorListL ( )

IMPORT_C CColorList *

CreateSystemColorListL

(

)

Creates and returns a system colour list, which is a palette of standard colours used by the system.

The list is read from a system colour scheme file. The function returns NULL if no such file can be found. In this case, clients are expected to create the list using some other means (typically from a resource file).

Returns: Pointer to the system colour list, or NULL.

CreateSystemColorListL ( const CColorList & )

IMPORT_C CColorList *

CreateSystemColorListL

(

const CColorList &

aColorList

)

Creates and returns a system colour list, which is a palette of standard colours used by the system, and merges it with the colour list specified. CColorList::AddColorArrayL() should be called before this function.

Parameter	Description
aColorList	The color list to merge in.

Returns: Pointer to the system colour list.

CustomColorArray ( )

CColorArray &

CustomColorArray

(

)

const [inline]

Gets the custom colour array.

Returns: The custom colour array.

DefaultDisplayMode ( )

IMPORT_C TDisplayMode

DefaultDisplayMode

(

)

const

Gets the default display mode for the window server session with the maximum possible number of colours.

Returns: Default display mode.

DenseFont ( )

IMPORT_C const CFont *

DenseFont

(

)

const

Gets the standard dense font for this environment.

It is highly recommended to use CCoeControl::ScreenFont() instead of this function.

See also: CCoeControl::ScreenFont() CCoeFontProvider

Returns: Pointer to the dense font.

DestroyEnvironment ( )

IMPORT_C void

DestroyEnvironment

(

)

[virtual]

Reimplemented from CCoeEnv::DestroyEnvironment()

Framework function

DismissTaskList ( )

IMPORT_C void

DismissTaskList

(

)

Causes the task list, if displayed, to be closed.

DisplayTaskList ( )

IMPORT_C void

DisplayTaskList

(

)

Displays tasks present in the Task List.

DoGetErrorText ( TDes &, TInt )

IMPORT_C void	DoGetErrorText	(	TDes &	aDes,
			TInt	aError
		)	const

Exported for testing only.

DoGetErrorTextAndTitle ( TDes &, TInt, TInt &, TUint &, TDes &, TBool )

IMPORT_C TErrorValidity	DoGetErrorTextAndTitle	(	TDes &	aErrorText,
			TInt	aError,
			TInt &	aTextId,
			TUint &	aFlags,
			TDes &	aTitleText,
			TBool	aIsMemoryAllocatedByErrResolver = EFalse
		)	const

N.B. This method is also called from the CTextResolver::DoResolveErrorStringL() in the textresolver.cpp, located in the tools/s60_header_compat component, part of the CoreOS agreement.

Parameter	Description
aErrorText	On return, contains the error text.
aError	Error number.
aTextId	Output parameter - Error Text Resource Id.
aFlags	Output parameter - Error Resource Flag.
aTitleText	On return, contains the title text of the error.
aIsMemoryAllocatedByErrResolver	is mainly used by the CTextResolver::DoResolveErrorStringL() to indicate that memory for error text is unlimited, ie., the memory for the error text is allocated by the text resolver. By default it is EFalse.

Returns: EErrorNumValid if the error code is valid, EErrorNumInvalid if the error code is invalid.

DocNameIsAFile ( )

IMPORT_C TBool

DocNameIsAFile

(

)

const

Tests whether the document name is a file.

Returns: ETrue if the document name is a file. EFalse otherwise.

DrawCursor ( const CCoeControl *, const TPoint &, TInt )

IMPORT_C void	DrawCursor	(	const CCoeControl *	aControl,
			const TPoint &	aPosition,
			TInt	aWidth
		)

Calls the other overload of DrawCursor() using the environment's standard screen font for the cursor's ascent and height.

Parameter	Description
aControl	Control to draw in.
aPosition	Position of the cursor's baseline in the control's co-ordinate space.
aWidth	Cursor width.

DrawCursor ( const CCoeControl *, const TPoint &, TInt, TInt, TInt )

IMPORT_C void	DrawCursor	(	const CCoeControl *	aControl,
			const TPoint &	aPosition,
			TInt	aWidth,
			TInt	aAscent,
			TInt	aHeight
		)

Draws the text cursor into a control with the specified position and width.

The cursor's height and ascent are by default suitable for this CEikonEnv's normal font. If aControl is not focused when this function is called, a panic is raised.

Parameter	Description
aControl	Control to draw into.
aPosition	Position of the cursor's baseline in the control's co-ordinate space.
aWidth	Cursor width.
aAscent	Cursor ascent.
aHeight	Cursor height.

EditableControlStandardHeight ( )

TInt

EditableControlStandardHeight

(

)

const [inline]

EikAppUi ( )

CEikAppUi *

EikAppUi

(

)

const [inline]

Gets the application UI of the application using this CEikonEnv.

Returns: Pointer to the CEikAppUi.

ExtendedPictureFactory ( TUid )

IMPORT_C MEikPictureFactory *

ExtendedPictureFactory

(

TUid

aPictureType

)

const

Gets a picture factory object in the environment which supports the specified picture type.

If none exists, then the function returns NULL.

Parameter	Description
aPictureType	The picture type.

Returns: A picture factory which supports the picture type aPictureType. NULL if no such factory exists in this environment.

Extension ( )

CBase *

Extension

(

)

const [inline]

DeprecatedWARNING: For internal use ONLY. Compatibility is not guaranteed in future releases.

FileDialogFactory ( )

MEikFileDialogFactory *

FileDialogFactory

(

)

const [inline]

Font ( const TLogicalFont & )

IMPORT_C const CFont *

Font

(

const TLogicalFont &

aLogicalFont

)

const

Gets the nearest match to the specified font.

It is highly recommended to use CCoeControl::ScreenFont() instead of this function.

See also: CCoeControl::ScreenFont() CCoeFontProvider

The return value is never NULL.

Parameter	Description
aLogicalFont	The font for which a match is sought.

Returns: Pointer to the font that most closely matches aLogicalFont.

FservAllocInfoMsg ( )

IMPORT_C void

FservAllocInfoMsg

(

)

Creates a file server allocation information message from resource.

The message indicates the number of resources currently open for the file server session.

GetErrorText ( TDes &, TInt )

IMPORT_C void	GetErrorText	(	TDes &	aDes,
			TInt	aError
		)	const

Gets the text for a standard error code.

Parameter	Description
aDes	On return, contains the error text.
aError	Error code.

GetErrorText ( TDes &, TInt, TUid )

IMPORT_C TErrorValidity	GetErrorText	(	TDes &	aErrorText,
			TInt	aError,
			TUid	aAppUid
		)	const

Gets the text for an error code, in the specified application.

It returns whether the error code is valid or not.

Parameter	Description
aErrorText	On return, contains the error text.
aError	Error number.
aAppUid	Application UID.

Returns: EErrorNumValid if the error code is valid, EErrorNumInvalid if the error code is invalid.

GetErrorTextAndTitle ( TDes &, TInt, TDes & )

IMPORT_C TErrorValidity	GetErrorTextAndTitle	(	TDes &	aErrorText,
			TInt	aError,
			TDes &	aTitleText
		)	const

Gets the text for an error code, in the specified application.

It returns whether the error code is valid or not.

Parameter	Description
aErrorText	On return, contains the error text.
aError	Error number.
aTitleText	On return, contains the title text of the error.

Returns: EErrorNumValid if the error code is valid, EErrorNumInvalid if the error code is invalid.

GetPrinterNamesL ( CPrinterModelList *, CDesCArray & )

IMPORT_C void	GetPrinterNamesL	(	CPrinterModelList *	aModelNameList,
			CDesCArray &	aPrinterNameList
		)	[static]

Gets the printer names from a CPrinterModelList.

The printer names are returned through aPrinterNameList.

Parameter	Description
aModelNameList	Input list of printer model information.
aPrinterNameList	On return, contains all the printer names from aModelNameList.

GrayBitmap ( )

IMPORT_C const CFbsBitmap *

GrayBitmap

(

)

const

HandleError ( TInt )

IMPORT_C void

HandleError

(

aError

)

[virtual]

Reimplemented from CCoeEnv::HandleError(TInt)

Handles an error that has occurred in the application.

It first offers the error to the app UI's HandleError() function. If that does not handle it, this function displays an alert window or an info message containing some appropriate text, read from a system resource file.

Parameter	Description
aError	One of the standard system error codes.

HandleErrorWithContext ( TInt, TInt )

IMPORT_C void	HandleErrorWithContext	(	TInt	aError,
			TInt	aContextResourceId
		)

Handles the specified error.

This function reads the error context text from the resource identified by aContextResourceId.

Parameter	Description
aError	ID of the error to handle.
aContextResourceId	ID of the resource from which the context is read.

HideCursor ( const CCoeControl * )

IMPORT_C void

HideCursor

(

const CCoeControl *

aControl

)

Removes the text cursor from a control.

In debug builds, a panic is raised when this function is called on a control which is not the cursor owner.

Parameter	Description
aControl	Control owning the cursor.

HighlightedOptionBitmap ( )

IMPORT_C const CFbsBitmap *

HighlightedOptionBitmap

(

)

const

InfoDialog ( )

IMPORT_C MEikInfoDialog *

InfoDialog

(

)

const

Gets the info dialog for this environment.

Returns: The info dialog.

InfoMsg ( const TDesC & )

IMPORT_C void

InfoMsg

(

const TDesC &

aDes

)

Displays a message in the system default corner of the screen.

The message disappears after a few seconds.

Parameter	Description
aDes	The message to display.

InfoMsg ( TInt, ... )

IMPORT_C void	InfoMsg	(	TInt	aResourceId,
			...
		)

Displays a message in the system default corner of the screen.

A TBUF resource string is used to build the message at run-time from arbitrary data in a similar way to C's printf(). The message disappears after a few seconds.

Parameter	Description
aResourceId	ID of a TBUF resource used to hold the string.

InfoMsg ( TInt, VA_LIST )

IMPORT_C void	InfoMsg	(	TInt	aResourceId,
			VA_LIST	aList
		)

Displays a message in the system default corner of the screen.

A TBUF resource string is used to build the message at run-time from arbitrary data in a similar way to C's printf(). The message disappears after a few seconds.

Parameter	Description
aResourceId	ID of a TBUF resource used to hold the string.
aList	List of values to be formatted.

InfoMsgCancel ( )

IMPORT_C void

InfoMsgCancel

(

)

Cancels the currently displaying information message.

InfoMsgWithAlignment ( TGulAlignment, const TDesC & )

IMPORT_C void	InfoMsgWithAlignment	(	TGulAlignment	aCorner,
			const TDesC &	aDes
		)

Displays a message in the specified corner of the screen.

The message disappears after a few seconds.

Parameter	Description
aCorner	The screen corner the message is displayed in.
aDes	The message to display.

InfoMsgWithAlignment ( TGulAlignment, TInt, ... )

IMPORT_C void	InfoMsgWithAlignment	(	TGulAlignment	aCorner,
			TInt	aResourceId,
			...
		)

Displays a message in the specified corner of the screen.

The information message is built at run-time from a formatting string defined as a TBUF resource and a list of arbitrary data.

Parameter	Description
aCorner	The corner of the screen the message is displayed in.
aResourceId	ID of a TBUF resource used to hold the string.

InfoMsgWithAlignment ( TGulAlignment, TInt, VA_LIST )

IMPORT_C void	InfoMsgWithAlignment	(	TGulAlignment	aCorner,
			TInt	aResourceId,
			VA_LIST	aList
		)

Displays a message in the specified corner of the screen.

The information message is built at run-time from a formatting string defined as a TBUF resource and a list of arbitrary data.

Parameter	Description
aCorner	The corner of the screen the message is displayed in.
aResourceId	ID of a TBUF resource used to hold the string.
aList	List of values to be formatted.

InfoMsgWithAlignmentAndDuration ( TGulAlignment, const TDesC &, TTimeIntervalMicroSeconds32 )

IMPORT_C void	InfoMsgWithAlignmentAndDuration	(	TGulAlignment	aCorner,
			const TDesC &	aDes,
			TTimeIntervalMicroSeconds32	aDuration
		)

Displays an info message with a specified alignment for a specified period.

The text displayed is supplied in a descriptor argument, and aligned using the aCorner parameter.

Parameter	Description
aCorner	The screen corner the message is displayed in.
aDes	Message to display.
aDuration	Duration of message.

InfoMsgWithAlignmentAndDuration ( TGulAlignment, TInt, TTimeIntervalMicroSeconds32, ... )

IMPORT_C void	InfoMsgWithAlignmentAndDuration	(	TGulAlignment	aCorner,
			TInt	aResourceId,
			TTimeIntervalMicroSeconds32	aDuration,
			...
		)

Displays an info message with a specified alignment for a specified period.

The text displayed is supplied in a resource file, as a string with some formatting information for extra arguments. These extra arguments are supplied through the variable argument list which is also passed into this function. The text is aligned using the aCorner parameter.

Parameter	Description
aCorner	The screen corner the message is displayed in.
aResourceId	ID of a TBUF resource used to contain the string.
aDuration	Duration of message.

InfoMsgWithAlignmentAndDuration ( TGulAlignment, TInt, TTimeIntervalMicroSeconds32, VA_LIST )

IMPORT_C void	InfoMsgWithAlignmentAndDuration	(	TGulAlignment	aCorner,
			TInt	aResourceId,
			TTimeIntervalMicroSeconds32	aDuration,
			VA_LIST	aList
		)

Displays an info message with a specified alignment for a specified period.

The text displayed is supplied in a resource file, as a string with some formatting information. Values for the formatting information are supplied as extra arguments. These extra arguments are packaged in a VA_LIST object which is also passed into this function. The text is aligned using the aCorner parameter.

Parameter	Description
aCorner	The screen corner the message is displayed in.
aResourceId	ID of a TBUF resource used to contain the string.
aDuration	Duration of message.
aList	List of values.

InfoMsgWithDuration ( const TDesC &, TTimeIntervalMicroSeconds32 )

IMPORT_C void	InfoMsgWithDuration	(	const TDesC &	aDes,
			TTimeIntervalMicroSeconds32	aDuration
		)

Displays an info message for a specified period.

Parameter	Description
aDes	Message to display.
aDuration	Duration of message.

InfoMsgWithDuration ( TInt, TTimeIntervalMicroSeconds32, ... )

IMPORT_C void	InfoMsgWithDuration	(	TInt	aResourceId,
			TTimeIntervalMicroSeconds32	aDuration,
			...
		)

Displays an info message for a specified period.

Parameter	Description
aResourceId	ID of a TBUF resource used to hold the string.
aDuration	Duration of the message.

InfoMsgWithDuration ( TInt, TTimeIntervalMicroSeconds32, VA_LIST )

IMPORT_C void	InfoMsgWithDuration	(	TInt	aResourceId,
			TTimeIntervalMicroSeconds32	aDuration,
			VA_LIST	aList
		)

Displays an info message for a specified period.

Parameter	Description
aResourceId	ID of a TBUF resource used to hold the string.
aDuration	Duration of message.
aList	List of values.

InfoWinL ( const TDesC &, const TDesC & )

IMPORT_C void	InfoWinL	(	const TDesC &	aFirstLine,
			const TDesC &	aSecondLine
		)	[static]

Displays a modal information dialog with the specified lines of text.

Parameter	Description
aFirstLine	First line of dialog text.
aSecondLine	Second line of dialog text.

InfoWinL ( TInt, TInt )

IMPORT_C void	InfoWinL	(	TInt	aFirstLineId,
			TInt	aSecondLineId = 0
		)	const

Displays a modal information dialog with a one or two-line info message read from the passed resources.

Parameter	Description
aFirstLineId	ID of the resource describing the first line.
aSecondLineId	ID of the resource describing the second line.

InitSystemBitmapsL ( )

void

InitSystemBitmapsL

(

)

Creates and populates array of bitmaps.

IrFactory ( )

MEikIrFactory *

IrFactory

(

)

const [inline]

IsBusy ( )

IMPORT_C TBool

IsBusy

(

)

const

Tests whether the application is marked as busy.

Returns: ETrue if the application is busy, EFalse otherwise.

IsEiksrvThread ( )

TBool

IsEiksrvThread

(

)

const

Returns: ETrue if threadname is EIKAPPUI_SERVER_THREAD_NAME

IsSystem ( )

IMPORT_C TBool

IsSystem

(

)

const

Tests the value of the system attribute.

Returns: ETrue if the system attribute is set, otherwise EFalse.

KeyPressLabel ( TInt )

IMPORT_C TPtrC

KeyPressLabel

(

aIndex

)

const

Returns the indexed keypress label. A keypress label is the text that is displayed on some buttons to identify which key press activates them. Examples might include Esc, Enter, Tab. Keypress labels are read from a resource file and are UI-specific.

Parameter	Description
aIndex	The position of the element within the array of keypress labels.

Returns: The keypress label.

LafEnv ( )

IMPORT_C MLafEnv &

LafEnv

(

)

const

LaunchPopupMenuL ( TInt, const TPoint &, TPopupTargetPosType, const CEikHotKeyTable * )

IMPORT_C void	LaunchPopupMenuL	(	TInt	aResourceId,
			const TPoint &	aTargetPos,
			TPopupTargetPosType	aTargetType = EPopupTargetTopLeft,
			const CEikHotKeyTable *	aHotKeyTable = NULL
		)

Allows an application to launch a popup menu, by calling the app UI's LaunchPopupMenuL() function.

Parameter	Description
aResourceId	ID of the resource that defines the menu to be launched.
aTargetPos	Position of the corner of the menu identified by aTargetType.
aTargetType	The corner of the menu by which the menu will be positioned.
aHotKeyTable	Optional menu hotkey table.

LeaveWithErrorContext ( TInt, const TDesC & )

IMPORT_C void	LeaveWithErrorContext	(	TInt	aError,
			const TDesC &	aContextText
		)

LeaveWithInfoMsg ( TInt, ... )

IMPORT_C void	LeaveWithInfoMsg	(	TInt	aResourceId,
			...
		)

Displays a formatted information message and then leaves.

Parameter	Description
aResourceId	ID of a TBUF resource used to hold the string.

LegendFont ( )

IMPORT_C const CFont *

LegendFont

(

)

const

Gets the standard legend font for this environment.

It is highly recommended to use CCoeControl::ScreenFont() instead of this function.

See also: CCoeControl::ScreenFont() CCoeFontProvider

Returns: Pointer to the legend font.

NewDefaultCharFormatLayerL ( )

IMPORT_C CCharFormatLayer *

NewDefaultCharFormatLayerL

(

)

[static]

Creates a default character format layer.

Returns: A new default CCharFormatLayer. The caller takes ownership.

NewDefaultParaFormatLayerL ( )

IMPORT_C CParaFormatLayer *

NewDefaultParaFormatLayerL

(

)

[static]

Creates a default paragraph format layer suitable for multiple lines of text.

It uses the default inter line spacing, which is UI specific.

Returns: A new CParaFormatLayer suitable for text that has more than one line. The caller takes ownership.

NewDefaultPrintSetupL ( )

IMPORT_C CPrintSetup *

NewDefaultPrintSetupL

(

)

Creates and returns a pointer to a new default printer setup object.

Returns: A default printer setup object.

NewDefaultSingleLineParaFormatLayerL ( )

IMPORT_C CParaFormatLayer *

NewDefaultSingleLineParaFormatLayerL

(

)

[static]

Creates a default paragraph format layer suitable for a single line of text.

It has an inter line spacing of zero.

Returns: A new CParaFormatLayer suitable for a single line of text. The caller takes ownership.

NotifyIdleError ( TInt, TInt )

IMPORT_C void	NotifyIdleError	(	TInt	aError,
			TInt	aContextResourceId
		)

Notifies this environment of an idle error.

This function reads the error context text from the resource identified by aContextResourceId. Calling this method will only trigger one error dialog per minute. Calling it any more frequent will result in no action.

Parameter	Description
aError	ID of the idle error.
aContextResourceId	ID of the resource from which the context text is read.

NotifyIdleErrorWhileRedrawing ( TInt )

IMPORT_C void

NotifyIdleErrorWhileRedrawing

(

aError

)

Notifies this environment that an idle error occurred while redrawing was in progress.

Parameter	Description
aError	ID of the idle error.

NudgeCharMinus ( )

TChar

NudgeCharMinus

(

)

const [inline]

Gets the minus nudge character, this could be the left arrow for example.

Returns: Minus nudge character.

NudgeCharPlus ( )

TChar

NudgeCharPlus

(

)

const [inline]

Gets the plus nudge character, this could be the right arrow for example.

Returns: Plus nudge character.

OptionBitmap ( )

IMPORT_C const CFbsBitmap *

OptionBitmap

(

)

const

Gets the bitmap that is used by horizontal option buttons in this environment.

Returns: A pointer to the option bitmap.

OptionMaskBitmap ( )

IMPORT_C const CFbsBitmap *

OptionMaskBitmap

(

)

const

PictureFactory ( )

IMPORT_C MPictureFactory *

PictureFactory

(

)

const

Gets the picture factory for this environment.

Returns: The picture factory.

PopulateColorArrayL ( )

IMPORT_C CColorList *

PopulateColorArrayL

(

)

Creates and populates a colour list, a palette of standard colours used by the system. If the first attempt fails a separate executable, Z:\SYS\BIN\UPDATESYSTEMCOLORLIST.EXE, is run to update system colours.

Returns: populated colour list. Ownership is passed to caller.

PostAppUiDestroy ( )

void

PostAppUiDestroy

(

)

PostAppUiInitializeL ( )

void

PostAppUiInitializeL

(

)

Calls (virtual) PostAppUiInitializeL on all loaded libraries.

PrintDialogFactory ( )

MEikPrintDialogFactory *

PrintDialogFactory

(

)

const [inline]

Process ( )

CEikProcess *

Process

(

)

const [inline]

Gets the Uikon process that manages the files of applications started in this environment.

Returns: The CEikProcess object.

QueryDialog ( )

IMPORT_C MEikInfoDialog *

QueryDialog

(

)

const

Gets the query dialog for this environment.

Returns: The query dialog.

QueryWinL ( const TDesC &, const TDesC & )

IMPORT_C TBool	QueryWinL	(	const TDesC &	aFirstLine,
			const TDesC &	aSecondLine
		)	[static]

Requests a yes or no response from the user using a modal query dialog.

Parameter	Description
aFirstLine	First line of query text.
aSecondLine	Second line of query text.

Returns: User's response.

QueryWinL ( TInt, TInt )

IMPORT_C TBool	QueryWinL	(	TInt	aFirstLineId,
			TInt	aSecondLineId = 0
		)	const

Requests a yes or no response from the user using a modal query dialog.

The query text is read from the passed resource IDs.

User input cannot continue outside a modal dialog until the dialog is dismissed, although applications can be switched.

Parameter	Description
aFirstLineId	ID of resource describing the first line.
aSecondLineId	ID of resource describing the second line.

Returns: User's response to the question, either ETrue or EFalse.

RemoveAppUiFactory ( )

IMPORT_C void

RemoveAppUiFactory

(

)

RemoveFromStack ( CCoeControl * )

IMPORT_C void

RemoveFromStack

(

aControl

)

Removes a control from the control stack.

Parameter	Description
aControl	The control to remove.

RemoveLibrary ( TCreateByTypeFunction, TInt )

IMPORT_C void	RemoveLibrary	(	TCreateByTypeFunction	aControlFactory,
			TInt	aResourceFileOffset
		)

RemoveLibrary ( TCreateByTypeFunction )

void

RemoveLibrary

(

TCreateByTypeFunction

aControlFactory

)

[inline]

RemoveLibrary ( TInt )

void

RemoveLibrary

(

aResourceFileOffset

)

[inline]

RemovePictureFactory ( TUid )

IMPORT_C void

RemovePictureFactory

(

TUid

aFactoryId

)

Removes the specified picture factory, if it exists, from the set of picture factories owned by the Uikon environment.

Parameter	Description
aFactoryId	The Id of the picture factory to be removed.

ResolveError ( TInt, TUid )

IMPORT_C void	ResolveError	(	TInt	aError,
			TUid	aAppUid = KNullUid
		)	const

Displays an error message appropriate to the error code aError in an alert window. The message is read from a resource file and has a maximum of 256 characters.

Parameter	Description
aError	Error code.
aAppUid	Application UID. By default, this is KNullUid. If a non null UID is specified and the error code is not known to UIKON, then the UID enables an application-specific error resource file to be scanned (if one exists) to try to resolve the error.

RespondsToShutdownEvent ( )

IMPORT_C TBool

RespondsToShutdownEvent

(

)

const

Tests whether the application responds to shutdown events.

Returns: ETrue if the application responds to shutdown events, EFalse otherwise.

RespondsToSwitchFilesEvent ( )

IMPORT_C TBool

RespondsToSwitchFilesEvent

(

)

const

Tests whether an application responds to switch files events.

Returns: ETrue if the application responds to switch files events, EFalse otherwise.

RouseSleepingDialog ( CCoeControl *, TBool )

IMPORT_C void	RouseSleepingDialog	(	CCoeControl *	aControl,
			TBool	aRoused
		)

Sets a sleeping dialog's state.

Parameter	Description
aControl	The sleeping dialog to rouse or put to sleep.
aRoused	ETrue to rouse aControl, EFalse to put it to sleep.

SendEventToEikonServer ( TInt, const TAny *, TInt )

IMPORT_C void	SendEventToEikonServer	(	TInt	aEvent,
			const TAny *	aPtr,
			TInt	aLength
		)

Sends the event to the Eikon Server.

Parameter	Description
aEvent	Event that has to be sent to Eikon Server.
aPtr	Pointer to the message that has to be sent to Eikon Server.
aLength	Length of the message that has to be sent to Eikon Server.

SetAlertWin ( MEikAlertWin * )

IMPORT_C void

SetAlertWin

(

MEikAlertWin *

aAlertWin

)

Sets the enviroment's alert window.

Parameter	Description
aAlertWin	A custom alert window.

SetAppUiFactoryL ( MEikAppUiFactory * )

IMPORT_C void

SetAppUiFactoryL

(

MEikAppUiFactory *

aAppUiFactory

)

SetAutoForwarding ( TBool )

IMPORT_C void

SetAutoForwarding

(

aAutoBringToForeground

)

Use this method to set whether the application's window group shall be automatically brought to the foreground when the user taps on it.

SetBusy ( TBool )

IMPORT_C void

SetBusy

(

aBusy

)

Sets the application's busy state.

Parameter	Description
aBusy	ETrue to set as busy, EFalse otherwise.

SetCDlgDialogFactory ( MEikCDlgDialogFactory * )

void

SetCDlgDialogFactory

(

MEikCDlgDialogFactory *

aDialogFactory

)

[inline]

SetColor ( TLogicalColor, TRgb )

void	SetColor	(	TLogicalColor	aLogicalColor,
			TRgb	aColor
		)	[inline]

Sets a mapping in the application's colour list between the logical and physical colours specified.

Parameter	Description
aLogicalColor	A logical colour value.
aColor	A physical colour value.

SetDebugKeys ( MEikDebugKeys * )

IMPORT_C void

SetDebugKeys

(

MEikDebugKeys *

aDebugKeys

)

Sets a debug keys object. This function enables the default debug keys to be overridden with custom ones. The debug keys object only receives key events in debug builds or, in release builds, if the CEikDebugPreferences::EFlagDebugKeysOn flag has been set.

Must be called before the environment object has been fully constructed, e.g. from a control (widget) library initialisation function, or it will have no effect. Must be called only once.

Parameter	Description
aDebugKeys	A custom debug keys object.

SetDocNameIsAFile ( TBool )

IMPORT_C void

SetDocNameIsAFile

(

aDocNameIsAFile

)

Sets whether a document name is a file.

Parameter	Description
aDocNameIsAFile	ETrue to set the document name as a file, EFalse otherwise.

SetExtension ( CBase * )

IMPORT_C void

SetExtension

(

CBase *

aExtension

)

Use CCoeStatic instead

SetFileDialogFactory ( MEikFileDialogFactory * )

void

SetFileDialogFactory

(

MEikFileDialogFactory *

aDialogFactory

)

[inline]

SetInfoDialog ( MEikInfoDialog * )

IMPORT_C void

SetInfoDialog

(

MEikInfoDialog *

aInfoDialog

)

Sets the dialog.

Parameter	Description
aInfoDialog	The information dialog.

SetIrFactory ( MEikIrFactory * )

void

SetIrFactory

(

MEikIrFactory *

aIrFactory

)

[inline]

SetPrintDialogFactory ( MEikPrintDialogFactory * )

void

SetPrintDialogFactory

(

MEikPrintDialogFactory *

aDialogFactory

)

[inline]

SetQueryDialog ( MEikInfoDialog * )

IMPORT_C void

SetQueryDialog

(

MEikInfoDialog *

aQueryDialog

)

Sets the query dialog.

Parameter	Description
aQueryDialog	The query dialog.

SetRequestInfoDialogFunc ( TRequestDialogFunc )

IMPORT_C void

SetRequestInfoDialogFunc

(

TRequestDialogFunc

aInfoDialogFunc

)

Sets the request information dialog.

Parameter	Description
aInfoDialogFunc	The request information dialog.

SetRequestQueryDialogFunc ( TRequestDialogFunc )

IMPORT_C void

SetRequestQueryDialogFunc

(

TRequestDialogFunc

aQueryDialogFunc

)

Sets the request query dialog.

Parameter	Description
aQueryDialogFunc	Request query dialog.

SetRespondsToShutdownEvent ( TBool )

IMPORT_C void

SetRespondsToShutdownEvent

(

aRespondsToShutdownEvent

)

Sets whether the application responds to shutdown events.

Parameter	Description
aRespondsToShutdownEvent	ETrue if the application responds to shutdown events, EFalse otherwise.

SetRespondsToSwitchFilesEvent ( TBool )

IMPORT_C void

SetRespondsToSwitchFilesEvent

(

aRespondsToSwitchFilesEvent

)

Sets whether the application responds to switch files events.

Parameter	Description
aRespondsToSwitchFilesEvent	ETrue if the application responds to switch files events, EFalse otherwise.

SetStatusPaneCoreResId ( TInt )

void

SetStatusPaneCoreResId

(

aStatusPaneCoreResId

)

[inline]

SetSystem ( TBool )

IMPORT_C void

SetSystem

(

aSystem

)

Sets the application's system attribute.

While the system attribute is set, the application cannot be closed down e.g. by using the TApaTask::EndTask function unless the requester has the capability PowerMgmt.

Parameter	Description
aSystem	ETrue to set the system attribute, EFalse to unset it.

SetVerboseInfoReporting ( TBool )

IMPORT_C void

SetVerboseInfoReporting

(

aVerbose

)

Sets the Verbose Information Reporting state.

Parameter	Description
aVerbose	ETrue to set Verbose Information Reporting, EFalse otherwise.

StartedAsServerApp ( )

IMPORT_C TBool

StartedAsServerApp

(

)

const

Gets whether server is required or not.

Returns: ETrue if application requires a server, EFalse otherwise.

Static ( )

CEikonEnv *

Static

(

)

[static, inline]

Reimplemented from CCoeEnv::Static()

Gets the CEikonEnv maintained by the framework for the application.

This function should never be run in a thread where such a static Uikon environment does not exist. Code that may run on the server side of an application server is one such case.

StatusPaneCoreResId ( )

TInt

StatusPaneCoreResId

(

)

const [inline]

SymbolFont ( )

IMPORT_C const CFont *

SymbolFont

(

)

const

Gets the standard symbol font for this environment.

It is highly recommended to use CCoeControl::ScreenFont() instead of this function.

See also: CCoeControl::ScreenFont() CCoeFontProvider

Returns: Pointer to the symbol font.

SystemCharFormatLayerL ( )

IMPORT_C CCharFormatLayer *

SystemCharFormatLayerL

(

)

Gets the character format layer, if it exists.

If it does not exist, it calls CEikonEnv::NewDefaultCharFormatLayerL() to create a new one.

Returns: Character format layer.

SystemParaFormatLayerL ( )

IMPORT_C CParaFormatLayer *

SystemParaFormatLayerL

(

)

Gets the paragraph format layer if it exists.

If it does not exist, it calls CEikonEnv::NewDefaultParaFormatLayerL() to create a new one.

Returns: Paragraph format layer.

SystemSingleLineParaFormatLayerL ( )

IMPORT_C CParaFormatLayer *

SystemSingleLineParaFormatLayerL

(

)

Gets the single line paragraph format layer if it exists.

If one does not exist, it calls CEikonEnv::NewDefaultSingleLineParaFormatLayerL() to create a new one.

Returns: Single line paragraph format layer.

TexturedBitmap ( )

IMPORT_C const CFbsBitmap *

TexturedBitmap

(

)

const