Class CEikAppUi

class CEikAppUi : public CCoeAppUi, public MEikMenuObserver, public MCoeMessageObserver, public MObjectProvider;

Description

Handles application-wide aspects of the application's user interface such as the menu bar, toolbar pop-up menus, opening and closing files and exiting the application cleanly.

Every GUI application should use its own class derived from CEikAppUi.

An app UI's main role is to handle commands, in its CEikAppUi::HandleCommandL(TInt) function. These may be invoked using the menu bar, toolbar, or hotkeys; the commands that an app UI handles are specified in the application's resource file.

In addition, the app UI normally needs to respond to other kinds of events, by providing suitable implementations of the following virtual functions, all inherited from CCoeAppUi:

• CCoeAppUi::HandleKeyEventL(const TKeyEvent &,TEventCode): Key events.

• CEikAppUi::HandleForegroundEventL(TBool): Application switched to foreground.

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

• CEikAppUi::HandleSystemEventL(const TWsEvent &): System events.

• CEikAppUi::HandleApplicationSpecificEventL(TInt,const TWsEvent &): Application-specific events.

Derivation

• MObjectProvider - No description.
• MCoeMessageObserver - No description.

• MEikCommandObserver - Command observers respond to user commands, and have the secondary function of c...

• MEikMenuObserver - Menu observer interface.
• CCoeAppUi - No description.

• CEikAppUi - Handles application-wide aspects of the application's user interface such as the...

Members

Defined in CEikAppUi:

• Application()constGets a pointer to the application associated with this app UI.
• ApplicationLanguageL()constDetermines the current language the application is using to display its user int...
• ApplicationRect()constGets the total area of the screen available to the application.
• BaseConstructL(TInt)Initialises this app UI with standard values.
• CEikAppUi()Empty default constructor.
• ClientRect()constGets the area of the screen available to the application for drawing.
• ClosePopup()Closes any currently visible popup menu.
• ConstructL()Completes construction.
• ContainerAppUi()constReturns the app UI inside which this app UI is embedded. Embedded app UIs are us...
• CreateFileL(const TDesC &)Creates and opens a file with the given name.
• CreateHotKeyControlL(TInt)Creates a hotkey control.
• Document()constGets a pointer to the app UI's associated document.
• ELastReservedEikAppUiFlagIndicates the last value in the enum.
• ENoAppResourceFileApplication has no resource file.
• ENoScreenFurnitureApplication uses no screen furniture.
• ENonStandardResourceFileApplication uses a different resource file from the standard.
• EStandardAppApplication uses a standard resource file.
• Exit()Closes the app UI.
• FadeWhenInBackground()Tests whether the application is set to fade when in the background.
• HandleApplicationSpecificEventL(TInt,const TWsEvent &)Handles an application-specific event.
• HandleCommandL(TInt)Handles user commands.
• HandleError(TInt,const SExtendedError &,TDes &,TDes &)Handles errors.
• HandleForegroundEventL(TBool)Handles changes to the application when it switches to or from the foreground.
• HandleMessageL(TUint32,TUid,const TDesC8 &)
• HandleModelChangeL()Handles changes to the model associated with this CEikAppUi's application.
• HandleResourceChangeL(TInt)Handles a change to the application's resources which are shared across the envi...
• HandleScreenDeviceChangedL()
• HandleSideBarMenuL(TInt,const TPoint &,TInt,const CEikHotKeyTable *)Handles sidebar menu commands.
• HandleSystemEventL(const TWsEvent &)
• HandleWsEventL(const TWsEvent &,CCoeControl *)Handles window server events.
• LaunchPopupMenuL(TInt,const TPoint &,TPopupTargetPosType,const CEikHotKeyTable *)Launches a popup menu.
• MopNext()Retrieves the parent.
• MopSupplyObject(TTypeUid)Retrieves an object of the same type as that encapsulated in aId.
• OpenFileL(const TDesC &)Opens the specified file.
• PrepareToExit()Performs pre-exit processing to ensure the application will exit cleanly.
• ProcessCommandL(TInt)Checks for, and closes, popups and menubars before calling CEikAppUi::HandleComm...
• ProcessCommandParametersL(CApaCommandLine &)Processes shell commands.
• ProcessCommandParametersL(TApaCommand,TFileName &)This is a convinience utility method that an application can call from an overri...
• ProcessCommandParametersL(TApaCommand,TFileName &,const TDesC8 &)Processes shell commands.
• ProcessMessageL(TUid,const TDesC8 &)Processes Application Architecture messages.
• ReadAppInfoResourceL(TInt)Reads the application UI information at the specified offset in the app's standa...
• ReportResourceChangedToAppL(TInt)Reports a resource change to the application.
• ReportResourceChangedToAppStackL(CEikAppUi *,TInt)Calls ReportResourceChangedToAppL( aEventId ) on recursively on each ContainerAp...
• Reserved_3()
• Reserved_4()
• SaveAnyChangesL()Saves any changes made to the app UI's associated document, if the document is m...
• SaveL()Saves the app UI's associated document, or sets the document as changed, if the ...
• SetDocChanged()Marks the app UI's associated document as having changed.
• SetDocument(CEikDocument *)Sets this app UI's document.
• SetEmbeddedDocInfo(MApaEmbeddedDocObserver *,TBool)Sets the embedded document's observer and read only state.
• SetEmphasis(CCoeControl *,TBool)
• SetFaded(TBool)
• SetFadedL(TBool)This is a virtual function. The base class implemenatiation causes the root wind...
• StopDisplayingMenuBar()Stops displaying the application's menu bar.
• ValidFileType(TUid)constThis method is used in combination with CEikAppUi::ProcessCommandParametersL(TAp...
• anonymousApplication resource file and screen furniture flags, passed to CEikAppUi::BaseC...
• iContainerAppUiA pointer to the containing app UI. This is NULL for non-embedded apps.
• iDocumentA pointer to the application's document.
• iDoorObserverEmbedded document observer.
• iEmbeddedAndReadOnlyIndicates whether or not this is the app UI for an embedded, read-only document....
• iFlags
• ~CEikAppUi()Destructor.

Inherited from MEikMenuObserver:

• CheckHotKeyNotDimmedL(TInt)Determines whether a command should be passed to the application.
• CreateCustomCommandControlL(TInt)This functions simpy wraps MEikCommandObserver::CreateCustomCommandControlL(TInt...
• DynInitMenuBarL(TInt,CEikMenuBar *)As MEikMenuObserver::DynInitMenuPaneL(TInt,CEikMenuPane *), but for menu bars.
• DynInitMenuPaneL(TInt,CEikMenuPane *)Dynamically initialises a menu pane.
• EMenuBarMenu bar.
• EMenuPaneMenu pane.
• HandleAttemptDimmedSelectionL(TInt)Responds to a user's attempt to select a dimmed item by displaying a message (CE...
• OfferKeyToAppL(const TKeyEvent &,TEventCode)Called if a key which is not used by the menu is pressed while the observer's me...
• RestoreMenuL(CCoeControl *,TInt,TMenuType)Restores the menu window aMenuWindow.
• TMenuTypeMenu types

Related Topics

 » Symbian OS v9.4 » Examples » Application Framework example code » AnimExample: An UI application with a toolbar

• Animation example » Class summary

 » Symbian OS v9.4 » Examples » Application Framework example code » ControlFramework: An UI application with a toolbar

• ControlFramework: A UI application with a toolbar

 » Symbian OS v9.4 » Examples » Application Framework example code » EmbApp: An embedded application

• EmbApp: An embedded application » Class summary

 » Symbian OS v9.4 » Examples » Application Framework example code » MenuApp: An application with a menu

• MenuApp: An application with a menu » Class Summary

 » Symbian OS v9.4 » Examples » Application Framework example code » Minimal: A minimal UI application

• Minimal: A minimal UI application » Class Summary

IMPORT_C ~CEikAppUi();

Description

Destructor.

Deletes any resources allocated by this CEikAppUi during its construction.

IMPORT_C CEikAppUi();

Description

Empty default constructor.

IMPORT_C virtual void ConstructL();

Description

Completes construction.

This simply calls CEikAppUi::BaseConstructL(TInt).

IMPORT_C virtual void HandleModelChangeL();

Description

Handles changes to the model associated with this CEikAppUi's application.

The implementation is empty in CEikAppUi.

IMPORT_C TLanguage ApplicationLanguageL() const;

Description

Determines the current language the application is using to display its user interface.

Return value

TLanguage The application language.

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

IMPORT_C CEikDocument* Document() const;

Description

Gets a pointer to the app UI's associated document.

Return value

CEikDocument * Pointer to the app UI's associated document.

IMPORT_C void SetDocument(CEikDocument *aDocument);

Description

Sets this app UI's document.

The document associated with the app UI is initially owned by CEikProcess, and there is usually no reason to change it with this function.

Parameters

CEikDocument *aDocument The app UI's document.

inline CEikAppUi* ContainerAppUi() const;

Description

Returns the app UI inside which this app UI is embedded. Embedded app UIs are used for editing embedded documents.

Return value

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

IMPORT_C 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. EFalse if not.

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

Description

Processes shell commands.

The Uikon application framework calls this overload when an application is launched by the user opening a file from the shell or when a Create new file command is issued.

This overload simply returns whether or not the file aDocumentName exists.

Many document based applications will override this function to invoke the 2-parameter utility version of this methid.

Parameters

TApaCommand aCommand The shell command sent to the application. Not used in this implementation. TBuf &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. Not used in this implementation.

Return value

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

See also:

• CEikAppUi::ProcessCommandParametersL(TApaCommand,TFileName &)This is a convinience utility method that an application can call from an overri...

IMPORT_C virtual TBool ProcessCommandParametersL(CApaCommandLine &aCommandLine);

Description

Processes shell commands.

This is the CEikAppUi::ProcessCommandParametersL(TApaCommand,TFileName &,const TDesC8 &) method that the Uikon application framework will call at application startup. The implementation will extract the command, document file name, and tail parameteres from the command line and call the 3-parameter version of this method.

The default implementation will simply returns whether or not the file aDocumentName exists.

Parameters

CApaCommandLine &aCommandLine The command line used to initialise the new application.

Return value

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

See also:

• CEikAppUi::ProcessCommandParametersL(TApaCommand,TFileName &,const TDesC8 &)Processes shell commands.

IMPORT_C TRect ClientRect() const;

Description

Gets the area of the screen available to the application for drawing.

This does not include the space available for UI components like the menu bar.

The co-ordinates of the rectangle are relative to the whole screen area so, for example, the co-ordinate for the top, left point of the area available for drawing may be (0, 45).

Return value

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

IMPORT_C virtual TRect ApplicationRect() const;

Description

Gets the total area of the screen available to the application.

This includes the space available for UI components like the menu bar.

Return value

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

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

Description

Launches a popup menu.

This function is called by CEikAppUI::HandleSideBarMenuL().

Parameters

TInt aResourceId ID of the menu resource. 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 Optional menu hotkey table.

IMPORT_C virtual 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.

IMPORT_C TBool FadeWhenInBackground();

Description

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

Return value

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

IMPORT_C virtual void SetFadedL(TBool aFaded);

Description

This is a virtual function. The base class implemenatiation causes the root window and all of its children to change to the desired faded state.

Parameters

TBool aFaded The desired faded state

inline void SetFaded(TBool aFaded);

Description

Parameters

TBool aFaded

IMPORT_C virtual void ReportResourceChangedToAppL(TInt aType);

Description

Reports a resource change to the application.

Parameters

TInt aType The type of resource that has changed.

IMPORT_C virtual void HandleCommandL(TInt aCommand);

Description

Handles user commands.

This is overridden by subclasses to handle commands passed on by the application framework. This function is called by CEikAppUi::ProcessCommandL(TInt), and has an empty implementation. Commands can be invoked using a menu item, a hotkey, or a button (for instance in a toolbar or dialog).

Parameters

TInt aCommand The ID of the command.

IMPORT_C 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. This implementation only recognises the message UIDs KUidApaMessageSwitchOpenFileValue and KUidApaMessageSwitchCreateFileValue. It performs no action if the message contains other values.

Parameters

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

IMPORT_C virtual void OpenFileL(const TDesC &aFileName);

Description

Opens the specified file.

The default implementation is empty.

Parameters

const TDesC16 &aFileName The name of the file to open.

See also:

• CEikAppUi::ProcessMessageL(TUid,const TDesC8 &)Processes Application Architecture messages.

IMPORT_C virtual void CreateFileL(const TDesC &aFileName);

Description

Creates and opens a file with the given name.

The default implementation is empty.

Parameters

const TDesC16 &aFileName The name of the file to create.

See also:

• CEikAppUi::ProcessMessageL(TUid,const TDesC8 &)Processes Application Architecture messages.

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

Description

Handles errors.

The default implementation of this function returns EErrorNotHandled.

Parameters

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

Return value

TErrorHandlerResponse How the error was handled.

IMPORT_C virtual void HandleResourceChangeL(TInt aType);

Description

Handles a change to the application's resources which are shared across the environment, for instance colours or fonts.

Parameters

TInt aType The type of resources that have changed.

IMPORT_C virtual void PrepareToExit();

Description

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

protected: IMPORT_C void BaseConstructL(TInt aAppUiFlags=0);

Description

Initialises this app UI with standard values.

The application's standard resource file will be read unless either the ENoAppResourceFile or ENonStandardResourceFile flag is specified.

Parameters

TInt aAppUiFlags Application user interface flags, EStandardApp for example.

protected: IMPORT_C void ReadAppInfoResourceL(TInt aResourceFileOffset=0);

Description

Reads the application UI information at the specified offset in the app's standard resource file.

This function is called by CEikAppUi::BaseConstructL(TInt), unless either of the ENoAppResourceFile or ENonStandardResourceFile flags was specified.

Parameters

TInt aResourceFileOffset Offset of the application information in the resource file.

protected: IMPORT_C 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 ID of a hotkey table resource.

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

Description

This is a convinience utility method that an application can call from an overriden version of the virtual CEikAppUi::ProcessCommandParametersL(TApaCommand,TFileName &,const TDesC8 &) taking three arguments. This method will not be called unless explicitly used by the application in this way.

This method is useful for applications that are used to view or edit document files, such as text documents or spreadsheets.

This method will make an application automatically open the document file that was last open in the application, unless a document file is explicitly defined as part of the command line, and the Open or Create commands are specified.

This method will call CEikAppUi::ValidFileType(TUid)const to find out if the specified document file can be opened by this application.

In detail: If aCommand is EApaCommandCreate, the function simply returns EFalse as the file does not yet exist.

If aCommand is EApaCommandOpen, the function tests whether the specified document is valid and exists. If not, the function attempts to generate a valid default filename and returns that in aDocumentName provided the file name portion of the specified full path name has valid format.

If aCommand is any other value, the function tests whether the most recently open document that is valid for the application exists, and returns that in aDocumentName.

The file must be a valid document file, as indicated by the UID value(s),otherwise the function generates a new filename. An application may handle the request by overriding CEikAppUi::ValidFileType(TUid)const if required.

Parameters

TApaCommand aCommand The shell command sent to the application. TBuf &aDocumentName The name of the document as specified on the command line. On return, this contains the name of the file which will be created by the calling framework.

Return value

TBool Whether the returned value of aDocumentName represents an existing, valid file.

See also:

• CEikAppUi::ValidFileType(TUid)constThis method is used in combination with CEikAppUi::ProcessCommandParametersL(TAp...

protected: IMPORT_C void SetDocChanged();

Description

Marks the app UI's associated document as having changed.

protected: IMPORT_C void SaveAnyChangesL();

Description

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

protected: IMPORT_C void SaveL();

Description

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

protected: IMPORT_C virtual void Exit();

Description

Closes the app UI.

protected: IMPORT_C void ClosePopup();

Description

Closes any currently visible popup menu.

protected: IMPORT_C virtual 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 invocation of a sidebar menu. See also MEikMenuObserver::HandleSideBarMenuL(TInt,const TPoint &,TInt,const CEikHotKeyTable *).

Note that not all UIs support a sidebar.

Parameters

TInt aResourceId ID of the menu resource. 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.

protected: IMPORT_C virtual void HandleApplicationSpecificEventL(TInt aType, const TWsEvent &aEvent);

Description

Handles an application-specific event.

This implementation handles a change to the environment's colour scheme and informs everything on the control stack of the change.

Parameters

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

protected: IMPORT_C virtual void HandleForegroundEventL(TBool aForeground);

Description

Handles changes to the application when it switches to or from the foreground.

For instance it handles changes to the cursor visibility and to the fade state.

This function is called from CEikAppUi::HandleWsEventL(const TWsEvent &,CCoeControl *) when an event occurs of type EEventFocusLost or EEventFocusGained.

Any application overriding this should first call this base implementation.

Parameters

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

protected: IMPORT_C virtual 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: IMPORT_C virtual void HandleSystemEventL(const TWsEvent &aEvent);

Description

Parameters

const TWsEvent &aEvent

protected: IMPORT_C virtual void HandleScreenDeviceChangedL();

Description

protected: IMPORT_C virtual void ProcessCommandL(TInt aCommand);

Description

Checks for, and closes, popups and menubars before calling CEikAppUi::HandleCommandL(TInt)

Parameters

TInt aCommand

See also:

• MEikCommandObserver::ProcessCommandL(TInt)Processes user commands.
• CEikAppUi::HandleCommandL(TInt)Handles user commands.

private: IMPORT_C virtual void SetEmphasis(CCoeControl *aMenuWindow, TBool aEmphasis);

Description

Parameters

CCoeControl *aMenuWindow TBool aEmphasis

See also:

• MEikMenuObserver::SetEmphasis(CCoeControl *,TBool)Called by the Uikon framework to handle the emphasising or de-emphasising of a m...

protected: IMPORT_C virtual MCoeMessageObserver::TMessageResponse HandleMessageL(TUint32 aClientHandleOfTargetWindowGroup, TUid aMessageUid, const TDesC8 &aMessageParameters);

Description

Parameters

TUint32 aClientHandleOfTargetWindowGroup TUid aMessageUid const TDesC8 &aMessageParameters

Return value

MCoeMessageObserver::TMessageResponse

See also:

• CEikAppUi::HandleMessageL(TUint32,TUid,const TDesC8 &)

protected: IMPORT_C virtual TTypeUid::Ptr MopSupplyObject(TTypeUid aId);

Description

Retrieves an object of the same type as that encapsulated in aId.

This function is used to allow to ask owners for access to other objects that they own.

Other than in the case where NULL is returned, the object returned must be of the same object type - that is, the ETypeId member of the object pointed to by the pointer returned by this function must be equal to the iUid member of aId.

Parameters

TTypeUid aId An encapsulated object type ID.

Return value

TTypeUid::Ptr Encapsulates the pointer to the object provided. Note that the encapsulated pointer may be NULL.

protected: IMPORT_C virtual MObjectProvider* MopNext();

Description

Retrieves the parent.

Return value

MObjectProvider * A pointer to an object provider, or NULL if none is defined.

private: IMPORT_C virtual TBool ValidFileType(TUid aFileUid) const;

Description

This method is used in combination with CEikAppUi::ProcessCommandParametersL(TApaCommand,TFileName &).

Override this method to return ETure if the application can handle documents associated with the UID aFileUid. If not, return EFalse (default).

Parameters

TUid aFileUid

Return value

TBool

See also:

• CEikAppUi::ProcessCommandParametersL(TApaCommand,TFileName &)This is a convinience utility method that an application can call from an overri...

private: IMPORT_C virtual void Reserved_3();

Description

private: IMPORT_C virtual void Reserved_4();

Description

IMPORT_C void ReportResourceChangedToAppStackL(CEikAppUi *aTopApp, TInt aEventId);

Description

Calls ReportResourceChangedToAppL( aEventId ) on recursively on each ContainerAppUi. For use with embedded applications (where iContanerAppUI != NULL)

Parameters

CEikAppUi *aTopApp AppUi of an embedded application. TInt aEventId The type of resource that has changed.

See also:

• CEikAppUi::ReportResourceChangedToAppL(TInt)Reports a resource change to the application.

n/a

Description

Application resource file and screen furniture flags, passed to CEikAppUi::BaseConstructL(TInt).

EStandardApp Application uses a standard resource file. ENoAppResourceFile Application has no resource file. ENonStandardResourceFile Application uses a different resource file from the standard. ENoScreenFurniture Application uses no screen furniture. ELastReservedEikAppUiFlag Indicates the last value in the enum.

protected: CEikDocument * iDocument;

Description

A pointer to the application's document.

protected: CEikAppUi * iContainerAppUi;

Description

A pointer to the containing app UI. This is NULL for non-embedded apps.

protected: MApaEmbeddedDocObserver * iDoorObserver;

Description

Embedded document observer.

protected: TBool iEmbeddedAndReadOnly;

Description

Indicates whether or not this is the app UI for an embedded, read-only document.

protected: TInt iFlags;

Description