Class CEikAppUi

CEikAppUi

Support

Supported from 6.0

Description

Handles application-wide aspects of the application’s user interface such as toolbar pop-up menus, opening and closing files and exiting the application cleanly. App UIs handle commands, which are invoked using the menu bar, toolbar, toolband and hotkeys; the commands that an app UI handles are specified in its application’s resource file.

An application’s UI is responsible for opening and closing the application document’s files in response to user commands. It also owns and manages the core controls of the user interface, for example the tool bar and menu bar, and handles commands from these.

Every Uikon application should use its own class derived from CEikAppUi to handle application-wide user interface details. Responses to various kinds of events can be handled at the level of the app UI by providing suitable implementations of the following virtual functions:

• CCoeAppUi::HandleKeyEventL(): Key events

• CCoeAppUi::HandleForegroundEventL(): Application switched to foreground

• CCoeAppUi::HandleSwitchOnEventL(): Machine switched on.

• CCoeAppUi::HandleSystemEventL(): System events.

• CCoeAppUi::HandleMessageReadyL(): Message ready.

• CCoeAppUi::HandleApplicationSpecificEventL(): Application-specific events.

• CEikAppUi::HandleCommandL(): Handles commands defined in resource files.

Derivation

CBase Base class for all classes to be instantiated on the heap CCoeAppUi General purpose application user interface class CCoeAppUiBase Application UI abstract base class CEikAppUi Handles application-wide aspects of the application's user interface such as toolbar pop-up menus, opening and closing files and exiting the application cleanly MCoeMessageObserver Interface for handling incoming window server messages MEikCommandObserver Command observers respond to user commands, and have the secondary function of creating custom controls on request for classes such as CEikToolbar, or user-defined classes MEikMenuObserver Menu observer interface

Defined in CEikAppUi:
Anonymous, Application(), ApplicationRect(), BaseConstructL(), CEikAppUi(), ClientRect(), ClosePopup(), ConstructL(), ContainerAppUi(), CreateFileL(), CreateHotKeyControlL(), Document(), ENoAppResourceFile, ENoScreenFurniture, ENonStandardResourceFile, EStandardApp, Exit(), FadeWhenInBackground(), HandleApplicationSpecificEventL(), HandleCommandL(), HandleError(), HandleForegroundEventL(), HandleModelChangeL(), HandleResourceChangeL(), HandleSideBarMenuL(), HandleWsEventL(), LaunchPopupMenuL(), OpenFileL(), PrepareToExit(), ProcessCommandParametersL(), ProcessMessageL(), ReadAppInfoResourceL(), ReportResourceChangedToAppL(), SaveAnyChangesL(), SaveL(), SetDocChanged(), SetDocument(), SetEmbeddedDocInfo(), StopDisplayingMenuBar(), iContainerAppUi, iDocument, iDoorObserver, iEmbeddedAndReadOnly, ~CEikAppUi()

Inherited from CBase:
operator new()

Inherited from CCoeAppUi:
ActivateViewL(), AddToStackL(), AppHelpContextL(), DeregisterView(), HandleStackChanged(), HandleStackedControlsResourceChange(), InputCapabilities(), IsDisplayingControlBetweenPriorities(), IsDisplayingMenuOrDialog(), RegisterViewL(), RemoveFromStack(), UpdateStackedControlFlags()

Inherited from MCoeMessageObserver:
EMessageHandled, EMessageNotHandled, HandleMessageL(), TMessageResponse

Inherited from MEikCommandObserver:
CreateCustomCommandControlL(), ProcessCommandL()

Inherited from MEikMenuObserver:
CheckHotKeyNotDimmedL(), DynInitMenuBarL(), DynInitMenuPaneL(), EMenuBar, EMenuPane, HandleAttemptDimmedSelectionL(), OfferKeyToAppL(), RestoreMenuL(), SetEmphasis(), TMenuType

Description

The construction of a CEikAppUi is usually handled automatically by the Application Architecture framework; application writers usually don’t need to call the constructors themselves.

CEikAppUi();

Description

Empty default constructor.

~CEikAppUi();

Description

Destructor.

Deletes any resources acquired by this CEikAppUi during its construction phases.

virtual void ConstructL();

Description

Completes construction. The implementation of ConstructL() in CEikAppUi simply calls BaseConstructL().

protected: void BaseConstructL(TInt aAppUiFlags=0);

Description

Initialises this app UI with standard values. The application’s standard resource file will be read unless the ENoAppResourceFile or ENonStandardResourceFile flags are passed.

Parameters

TInt aAppUiFlags=0 Application user interface flags, EStandardApp for example.

protected: void ReadAppInfoResourceL(TInt aResourceFileOffset=0);

Description

Reads the application information for this application from the specified resource offset. This function is called automatically in BaseConstructL().

Parameters

TInt aResourceFileOffset=0 Offset of application information.

virtual void HandleCommandL(TInt aCommand);

Description

Handles user commands. This is overridden by subclasses to handle user commands passed on by the application framework. This function is called by CEikAppUi::ProcessCommandL(), and has a blank implementation. It may be overridden in order to provide custom responses to user commands. A command:

• instructs the application to perform some function

• can be invoked using either a menu item, a hotkey, or a button (in a toolbar, toolband or dialog)

Parameters

TInt aCommand A command ID.

virtual void HandleModelChangeL();

Description

Handles changes to the model associated with this CEikAppUi’s application. This virtual function is empty in CEikAppUi.

void HandleWsEventL(const TWsEvent& aEvent, CCoeControl* aDestination);

Description

Handles window server events.

Parameters

const TWsEvent& aEvent The window server event that occurred. CCoeControl* aDestination The control associated with the event.

protected: TBool ProcessCommandParametersL(TApaCommand aCommand,TFileName& aDocumentName);

Description

Processes shell commands. The default implementation of this function returns whether or not the file aDocumentName exists, and does nothing else. The Uikon application framework calls the three-argument form when an application is started by selecting a file from the shell or by issuing a Create new file command.

Most file-based applications will override the virtual three-argument form of this function to invoke the two-argument form. If the passed value of aDocumentName is not the name of a file of the right type for this application, a new filename is returned through aDocumentName. Implementations of this function should not attempt to open the document. That is handled separately by the application framework after the command line has been processed.

When called automatically, aCommand is either EApaCommandCreate or EApaCommandRun.

Parameters

TApaCommand aCommand The shell command sent to the application. TFileName& aDocumentName At call time, the name of the document as specified on the command line. On return, the name for the file which will be created by the calling framework.

Return value

TBool Whether the final value of aDocumentName represents an existing file. For this form of the function this is ETrue if the Uikon application framework needs to open an existing file called aDocumentName. Otherwise, this will be EFalse if the Uikon application framework needs to create the file.

public: virtual TBool ProcessCommandParametersL(TApaCommand aCommand,TFileName& aDocumentName,const TDesC8& aTail);

Description

Processes shell commands. The default implementation of this function returns whether or not the file aDocumentName exists, and does nothing else. The Uikon application framework calls the three-argument form when an application is started by selecting a file from the shell or by issuing a Create new file command.

Most file-based applications will override the virtual three-argument form to invoke the two-argument form. If the passed value of aDocumentName is not the name of a file of the right type for this application, a new filename is returned through aDocumentName. Implementations of this function should not attempt to open the document. That is handled separately by the application framework after the command line has been processed.

When called automatically, aCommand is either EApaCommandCreate or EApaCommandRun.

Parameters

TApaCommand aCommand The shell command sent to the application. TFileName& aDocumentName At call time, the name of the document as specified on the command line. On return, the name for the file which will be created by the calling framework. const TDesC8& aTail Command line tail.

Return value

TBool Whether the final value of aDocumentName represents an existing file.

virtual void ProcessMessageL(TUid aUid,const TDesC8& aParams);

Description

Processes Application Architecture messages. This is overridden by subclasses to handle messages sent from the Application Architecture framework. As defined in CEikAppUi, this function recognises the message UIDs KUidApaMessageSwitchOpenFileValue and KUidApaMessageSwitchCreateFileValue, and performs no action if the message contains neither of these values.

See also: CCoeAppUi::HandleMessageReadyL() and CApaTask::SendMessage().

Parameters

TUid aUid The message’s unique identifier. const TDesC8& aParams Message parameters.

virtual TErrorHandlerResponse HandleError
    (TInt aError,
     const SExtendedError& aExtErr,
     TDes& aErrorText,
     TDes& aContextText);

Description

Handles errors. The default implementation of this function simply returns EErrorNotHandled.

Parameters

TInt aError The error code. const SExtendedError& aExtErr For extended error messages. TDes& aErrorText Error text. TDes& aContextText Text describing the context of the error.

Return value

TErrorHandlerResponse How the error was handled.

virtual void OpenFileL(const TDesC& aFileName);

Description

Opens the specified file in response to a corresponding message. The default implementation is empty; and can be overridden by application developers to provide a file opening capability.

Parameters

const TDesC& aFileName The file name to open.

See also:

• CEikAppUi::ProcessMessageL()

virtual void CreateFileL(const TDesC& aFileName);

Description

Creates and opens a file with the given name in response to the corresponding message. The default implementation is empty; and can be overridden by application developers.

Parameters

const TDesC& aFileName The name of the file to create and open.

See also:

• CEikAppUi::ProcessMessageL()

CEikAppUi* ContainerAppUi() const;

Description

Returns the app UI inside which this app UI is embedded. Embedded app UIs are used for example, for editing embedded documents and to stack a help application onto the context of a current application.

Return value

CEikAppUi* A pointer to this CEikAppUi’s container app UI. NULL if this app UI is not embedded

void SetEmbeddedDocInfo(MApaEmbeddedDocObserver* aObserver,TBool aReadOnly);

Description

Sets the embedded document’s observer and read only state.

Parameters

MApaEmbeddedDocObserver* aObserver Observer for the embedded document. TBool aReadOnly ETrue to set the embedded document as read-only. Otherwise EFalse.

CEikDocument* Document() const;

Description

Gets this application UI’s document pointer.

Return value

CEikDocument* Pointer to the app UI’s document.

See also:

• SetDocument()

void SetDocument(CEikDocument* aDocument);

Description

Sets this Application UI’s document pointer. The document being presented in an app UI is initially owned by CEikProcess, and there is usually no reason to change it with this function.

Parameters

CEikDocument* aDocument App UI’s document.

protected: void SetDocChanged();

Description

Marks this CEikAppUi’s associated document as having changed.

protected: void SaveAnyChangesL();

Description

Saves changes made to the app UI’s associated document if the document is marked as having changed.

CEikApplication* Application() const;

Description

Gets a pointer to the application associated with this app UI.

Return value

CEikApplication* A pointer to the application associated with this app UI.

TRect ApplicationRect() const;

Description

Gets the total area of the screen available to the application. This includes the space that is available for a toolbar, toolband or title band, if the application requires them.

Return value

TRect The total area of the screen available to the application.

TRect ClientRect() const;

Description

Gets the area of the screen available to the application for drawing. This does not include the space that is available for a toolbar, toolband or title band, if the application requires them.

Return value

TRect The area of the screen available to the application for drawing.

protected: void CreateHotKeyControlL(TInt aResourceId);

Description

Creates a hotkey control.

Constructs a CEikHotKeyControl whose CEikHotKeytable is specified by a resource ID, and adds it to the control stack.

Parameters

TInt aResourceId A hot key table resource.

TBool FadeWhenInBackground();

Description

Tests whether the application is set to fade when in the background.

Return value

TBool ETrue if application is set to fade when in the background, EFalse otherwise.

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

Description

Launches a popup menu. This function is called by CEikAppUI::HandleSideBarMenuL().

Parameters

TInt aResourceId ID of the resource that defines the menu to be launched. const TPoint& aTargetPos Position of the corner of the menu identified by aTargetType. TPopupTargetPosType aTargetType The corner of the menu by which the menu will be positioned. const CEikHotKeyTable* aHotKeyTable=NULL Optional menu hotkey table.

void StopDisplayingMenuBar();

Description

Stops displaying the application’s menu bar. If the application has no menu bar, or if the menu bar is not visible, this function has no effect.

protected: void ClosePopup();

Description

Closes any currently visible sidebar popup menu. Calls to Popup() immediately after a ClosePopup() return NULL.

protected: void HandleSideBarMenuL(TInt aResourceId,const TPoint& aPos,TInt aModifiers,const CEikHotKeyTable* aTable);

Description

Handles sidebar menu commands. This is called by the Uikon framework to handle user invocation of a sidebar menu. See also MEikMenuObserver::HandleSideBarMenuL().

Parameters

TInt aResourceId ID of the resource that describes the menu. const TPoint& aPos Position of the menu’s reference point. For sidebar menus, this is the top-right corner. TInt aModifiers Bitwise OR of the modifiers held when the menu was invoked by the user. const CEikHotKeyTable* aTable Hotkey table for the menu.

void HandleApplicationSpecificEventL(TInt aType,const TWsEvent& aEvent);

Description

Handles an application specific event. This function takes action on notification of a change to the environment colour scheme and informs everything on the control stack of the change.

See also: CCoeAppUi.

Parameters

TInt aType The type of the event that occurred. This should be a unique identifier constant for the application specific event. const TWsEvent& aEvent The window server event that occurred.

void HandleForegroundEventL(TBool aForeground);

Description

Handles changes in keyboard focus when an application switches to, or from, the foreground. This function is called from HandleWsEventL() when an event occurs of type EEventFocusLost or EEventFocusGained.

Any application overriding this should first call the base function.

Parameters

TBool aForeground ETrue to switch to the foreground. EFalse to switch from the foreground..

void ReportResourceChangedToAppL(TInt aType);

Description

Reports a resource change to the application.

Parameters

TInt aType The type of resource that has changed.

virtual void HandleResourceChangeL(TInt aType);

Description

Handles a change to the application's resources which are shared across the environment. Colours or fonts for example.

Parameters

TInt aType The type of resources that have changed.

void PrepareToExit();

Description

Performs pre-exit processing to ensure the application will exit cleanly.

void Exit();

Description

Closes the app UI.

void SaveL();

Description

Saves the app UI’s document, or sets the document as changed if the app UI is embedded.

void SetDocChanged();

Description

Sets the application’s document as changed.

enum {...} //anonymous

Description

The following enums relate to the use of an application resource file and screen furniture.

EStandardApp Application uses its standard application resource file. ENoAppResourceFile Application has no application resource file. ENonStandardResourceFile Application uses a different application resource file from its standard. ENoScreenFurniture Application uses no screen furniture.

CEikAppUi* iContainerAppUi

Description

A pointer to the containing app UI. iContainerAppUi is NULL for non-embedded app UIs.

CEikDocument* iDocument

Description

Pointer to this app UI’s document. See GetDocument().

MApaEmbeddedDocObserver* iDoorObserver

Description

Door observer.

TBool iEmbeddedAndReadOnly

Description

ETrue only if this CEikAppUi is the app UI for an embedded document which is read-only.