Class CCoeAppUi

class CCoeAppUi : public CBase;

Description

Application user interface (app UI) base class.

The app UI's responsibilities include owning the application's control stack and views, handling user commands, (see the derived class CEikAppUi), and handling events sent by the OS to the application, for instance being brought to the foreground.

The UI framework class CEikAppUi is derived from this class. UIs may derive further to add their own UI-specific features to the app UI; each application must derive its own concrete app UI class from this.

Derivation

• CBase - Base class for all classes to be instantiated on the heap

• CCoeAppUi - Application user interface (app UI) base class

Members

Defined in CCoeAppUi:
ActivateViewL(), ActivateViewL(), AddToStackL(), AddToStackL(), AddToViewStackL(), AddViewDeactivationObserverL(), AppHelpContextL(), CCoeAppUi(), CheckSourceOfViewSwitchL(), ConstructL(), DeactivateActiveViewIfOwnerMatchL(), DeactivateActiveViewL(), DeregisterApplicationView(), DeregisterView(), GetActiveViewId(), GetDefaultViewId(), HandleApplicationSpecificEventL(), HandleForegroundEventL(), HandleKeyEventL(), HandleScreenDeviceChangedL(), HandleStackChanged(), HandleStackedControlsResourceChange(), HandleSwitchOnEventL(), HandleSystemEventL(), HandleWsEventL(), HelpContextL(), InputCapabilities(), IsDisplayingControlBetweenPriorities(), IsDisplayingDialog(), IsDisplayingMenuOrDialog(), IsViewConstructed(), NotifyNextDeactivation(), NotifyNextDeactivation(), PrepareToExit(), RegisterApplicationViewL(), RegisterViewL(), RemoveFromStack(), RemoveFromViewStack(), RemoveViewDeactivationObserver(), SetAndDrawFocus(), SetDefaultViewL(), UpdateStackedControlFlags(), WriteInternalStateOfStackedControlsL(), iCoeEnv, ~CCoeAppUi()

Inherited from CBase:
Delete(), Extension_(), operator new()

IMPORT_C CCoeAppUi();

Description

C++ constructor.

To complete construction, call ConstructL().

IMPORT_C ~CCoeAppUi();

Description

The destructor frees all resources owned by the object, including the control stack and the view server session.

IMPORT_C void ConstructL(CCoeAppUi *aPrevious=0);

Description

Completes construction of the CCoeAppUi object.

It creates the application's control stack and starts a view server session.

Parameters

CCoeAppUi *aPrevious If non-NULL, ConstructL() transfers ownership of all of the controls owned by aPrevious to the new app UI being constructed, adding them to the new app UI's control stack.

IMPORT_C void AddToStackL(const MCoeView &aView, CCoeControl *aControl, TInt aPriority=ECoeStackPriorityDefault, TInt aStackingFlags=ECoeStackFlagStandard);

Description

Inserts a control into the app UI's control stack.

Parameters

const MCoeView &aView The view that contains the control. CCoeControl *aControl The control to add to the stack. This may itself be a view. TInt aPriority An optional control stack priority. The default value is ECoeStackPriorityDefault. Higher priority controls are offered key events before lower priority controls. TInt aStackingFlags The control's event handling behaviour. The possible values are defined in coeaui.h, beginning with ECoeStackFlagStandard.

IMPORT_C void AddToStackL(CCoeControl *aControl, TInt aPriority=ECoeStackPriorityDefault, TInt aStackingFlags=ECoeStackFlagStandard);

Description

Inserts a control into the app UI's control stack.

Use the other AddToStackL() overload if the app UI uses multiple views.

Parameters

CCoeControl *aControl The control to add to the stack. TInt aPriority An optional control stack priority. The default value is ECoeStackPriorityDefault. Higher priority controls are offered key events before lower priority controls. TInt aStackingFlags The control's event handling behaviour. The possible values are defined in coeaui.h, beginning with ECoeStackFlagStandard.

IMPORT_C void RemoveFromStack(CCoeControl *aControl);

Description

Removes a control from the app UI's control stack.

This function also handles any focus changes that may occur.

Parameters

CCoeControl *aControl The control to remove from the stack.

IMPORT_C void HandleStackChanged();

Description

Handles changes to the control stack.

This function ensures that the focusable control with the highest priority on the control stack has keyboard focus.

It may need to be called when a control's flag values are modified, by calling UpdateStackedControlFlags(). It is called automatically when a control is added to or removed from the stack.

IMPORT_C void HandleStackedControlsResourceChange(TInt aType);

Description

Handles a change to the application's run-time resources for all controls on the app UI's control stack.

These are resources which are shared across the environment, such as colours, fonts or ZoomFactor.

Parameters

TInt aType Specifies a resource type.

IMPORT_C void UpdateStackedControlFlags(CCoeControl *aControl, TInt aFlags, TInt aMask);

Description

Updates the flag values for a control on the control stack.

The mask defines which flags are modified, while aFlags defines the values they are set to.

Parameters

CCoeControl *aControl The control to update. TInt aFlags Contains the required value for each of the flag bits whose bit is set in aMask. TInt aMask Contains a set bit for each flag bit to modify.

Panic codes

CONE 4 The specified control is not on the stack.

IMPORT_C CArrayFix< TCoeHelpContext > *AppHelpContextL() const;

Description

Returns a list of help contexts appropriate to the current state of the application.

The array is generated from the help contexts for all visible controls on the app UI's control stack, and from the app UI itself (via CCoeAppUi::HelpContextL()).

Return value

CArrayFix< TCoeHelpContext > * A list of pointers to relevant help contexts.

virtual IMPORT_C TCoeInputCapabilities InputCapabilities() const;

Description

Returns the input capabilities of the control with focus.

Classes that override CCoeAppUi::HandleKeyEventL() should also override this virtual function. The TCoeInputCapabilities object returned should have attributes that match the behaviour of the HandleKeyEventL() function.

Overriding app UIs should do a base-call and "merge" the returned input capabilities with its own input capabilities. If the overriding InputCapabilities() function needs to get the input capabilities of any top-level control, it should do so by calling CCoeControl::RecursivelyMergedInputCapabilities() on that control.

Return value

TCoeInputCapabilities The types of input which can be consumed by the focussed control.

IMPORT_C TBool IsDisplayingMenuOrDialog() const;

Description

Tests whether the application is displaying a menu bar or dialog.

Return value

TBool ETrue if the application is currently displaying a menu bar or a dialog. EFalse if not.

IMPORT_C TBool IsDisplayingDialog() const;

Description

Tests whether the application is displaying a dialog.

Return value

TBool ETrue if the application is currently displaying a dialog. EFalse if not.

IMPORT_C TBool IsDisplayingControlBetweenPriorities(TInt aLowerPriority, TInt aHigherPriority) const;

Description

Tests whether the application is displaying a control between the given control stack priorities.

Parameters

TInt aLowerPriority Lower bound. TInt aHigherPriority Upper bound.

Return value

TBool ETrue if the application is currently displaying a control which has a control stack priority between (but not including) aLowerPriority and aHigherPriority. EFalse if not.

IMPORT_C void RegisterViewL(MCoeView &aView);

Description

Registers a view with the view server.

All views should be registered in the app UI's ConstructL().

Parameters

MCoeView &aView The view to be registered.

IMPORT_C void DeregisterView(const MCoeView &aView);

Description

Deregisters a view.

All views must be deregistered before the application exits. This is usually done in the app UI's destructor.

It has no effect if the specified view does not exist.

Parameters

const MCoeView &aView The view to be deregistered.

IMPORT_C void SetDefaultViewL(const MCoeView &aView);

Description

Sets one of the app UI's views as the default.

The default view should be constructed, drawn, registered and set as the default as early as possible in the app UI's ConstructL() function.

The meaning of the default view varies depending on the UI. It is normally the view that is displayed when the application is launched. It may also be the view that is displayed when the application is brought to the foreground.

Parameters

const MCoeView &aView The view to set as the default.

IMPORT_C TInt GetDefaultViewId(TVwsViewId &aViewId) const;

Description

Gets this app UI's default view ID.

Parameters

TVwsViewId &aViewId On return, contains the ID of the app UI's default view. This is unchanged if there is no default view.

Return value

TInt KErrNone if this app UI has a default view, KErrNotFound if it doesn't.

IMPORT_C void RegisterApplicationViewL(TUid aAppUid);

Description

Registers a pseudo-view for the application identified by aAppUid.

The view server is notified that a view exists for the application, which allows it to participate in the view switching mechanism, even though it does not implement any views.

Activating the application view means bringing the application into the foreground.

Parameters

TUid aAppUid The ID of the application for which a view should be registered.

IMPORT_C void DeregisterApplicationView();

Description

Deregisters the application view from the view architecture.

IMPORT_C TBool IsViewConstructed(const TVwsViewId &aViewId) const;

Description

Checks if the view has been constructed or not.

Parameters

const TVwsViewId &aViewId The id of the view

Return value

TBool ETrue if the view has been constructed, EFalse otherwise.

IMPORT_C void ActivateViewL(const TVwsViewId &aViewId);

Description

Activates an application view.

A leave occurs if view activation fails.

Parameters

const TVwsViewId &aViewId Identifier of the view to activate.

IMPORT_C void ActivateViewL(const TVwsViewId &aViewId, TUid aCustomMessageId, const TDesC8 &aCustomMessage);

Description

Activates an application view and passes a message to it.

A leave occurs if view activation fails.

Notes:

Activation works synchronously so that in general, this method returns when the view is activated.

An application defines and publishes the message UIDs that it recognises. For example, a contacts application might activate an email editor view, passing an email address as a custom message. To do this, the contacts application must use a message UID, and descriptor encoding that the email application has published as being recognisable.

Parameters

const TVwsViewId &aViewId Identifies the view to activate. TUid aCustomMessageId Specifies the message type. const TDesC8 &aCustomMessage The message to pass to the activated view.

IMPORT_C void DeactivateActiveViewIfOwnerMatchL();

Description

Deactivates the active view if the current view is owned by this application.

Deactivating the active view is necessary before exiting if the app UI has an active view. This function is called by the UI framework during application closure.

IMPORT_C void DeactivateActiveViewL();

Description

Deactivates the active view.

Deactivating the active view is necessary before exiting if the app UI has an active view. In most cases, DeactivateActiveViewIfOwnerMatch should be used instead of this function.

IMPORT_C TInt GetActiveViewId(TVwsViewId &aViewId) const;

Description

Gets the ID of the app UI's currently active view.

Parameters

TVwsViewId &aViewId On return, contains the ID of the currently active view. This is unchanged if there is no active view.

Return value

TInt KErrNone if this app UI has an active view, KErrNotFound if it does not.

IMPORT_C TBool CheckSourceOfViewSwitchL(const TSecurityPolicy &aSecurityPolicy, const char *aDiagnostic=0) const;

Description

Checks whether the view-server client that initiated the current view-switch matches the security-policy given in the parameter.

This function leaves with KErrUnknown if called outside of an implementation of MCoeView's ViewConstructL or of MCoeView's ViewActivatedL.

Parameters

const TSecurityPolicy &aSecurityPolicy The TSecurityPolicy object which the client that initiated the current view switch must match. const char *aDiagnostic A string that will be emitted along with any diagnostic message that may be issued if the policy check fails. This string should be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system.

Return value

TBool EFalse (zero) if the security-policy does not match the client that initiated the current view switch, other-wise returns "true", i.e. a non-zero value.

See also:

• TSecurityPolicy

IMPORT_C void AddViewDeactivationObserverL(MCoeViewDeactivationObserver *aViewDeactivationObserver);

Description

Adds an observer to the list of observers to be notified of view deactivations.

All view deactivation observers that have been added to the app UI are notified via their HandleViewDeactivation() function when any of this app UI's views are deactivated.

Parameters

MCoeViewDeactivationObserver *aViewDeactivationObserver The observer to add.

IMPORT_C void RemoveViewDeactivationObserver(MCoeViewDeactivationObserver *aViewDeactivationObserver);

Description

Removes an observer from the list to be notified of view deactivations.

This has no effect if the observer is not found in the list.

Parameters

MCoeViewDeactivationObserver *aViewDeactivationObserver The observer to remove.

IMPORT_C void NotifyNextDeactivation(const TVwsViewId &aViewId, MCoeViewDeactivationObserver &aViewDeactivationObserver);

Description

Requests that the next deactivation of the view identified by aViewId be notified to the specified view deactivation observer.

The request is cleared after the notification: the observer can only be notified once, and this app UI can have no more than one such request pending.

Parameters

const TVwsViewId &aViewId The view to be observed. This can any view registered with the view server. MCoeViewDeactivationObserver &aViewDeactivationObserver The observer to be notified.

Panic codes

CONE 39 In debug builds, there was already a request pending when this function was called.

IMPORT_C void NotifyNextDeactivation(MCoeViewDeactivationObserver &aViewDeactivationObserver);

Description

Requests that the next deactivation of any view registered with the view server be notified to the specified view deactivation observer.

The request is cleared after the notification: the observer can only be notified once, and this app UI can have no more than one such request pending.

Parameters

MCoeViewDeactivationObserver &aViewDeactivationObserver The observer to be notified.

Panic codes

CONE 39 In debug builds, there was already a request pending when this function was called.

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

Description

Handles events sent to the application by the window server.

This function is called whenever the window server sends key or pointer events or some other special events to the application. It calls one of a number of functions, according to the type of event.

For key events, it calls CCoeControl::OfferKeyEventL() for each control on the control stack, beginning with the control at the top (position 0) until a control consumes it. If no control on the stack consumes the key event, the app UI's HandleKeyEventL() is called. Note that CCoeControl::OfferKeyEventL() is not called for controls whose ECoeStackFlagRefusesAllKeys flag is set.

For pointer events, CCoeControl::ProcessPointerEventL() is called on the control specified in aDestination.

For pointer buffer ready events, ProcessPointerBufferReadyL() is called on the control specified in aDestination.

For other events, for instance focus change events, this function calls one of the following CCoeAppUi private virtual functions:

• HandleForegroundEventL()

• HandleSwitchOnEventL()

• HandleSystemEventL()

• HandleScreenDeviceChangedL()

• HandleApplicationSpecificEventL().

All these functions have empty implementations in this class, and are implemented by derived classes, if required.

Parameters

const TWsEvent &aEvent A window server event. CCoeControl *aDestination The control associated with the event. This is only relevant for pointer events.

See also:

• CCoeAppUi::HandleWsEventL()

virtual IMPORT_C void PrepareToExit();

Description

Performs pre-exit processing on the control environment.

This function is called after the control environment's active scheduler exits, but before the control environment (i.e. the CCoeEnv object) is destroyed. The default implementation is empty, and this function is not implemented by CCoeAppUi, but it may be implemented by derived classes to perform pre-exit processing on the control environment.

protected: virtual IMPORT_C void HandleScreenDeviceChangedL();

Description

private: virtual IMPORT_C TKeyResponse HandleKeyEventL(const TKeyEvent &aKeyEvent, TEventCode aType);

Description

Handles key events.

This function is called by HandleWsEventL() if a key event occurred but none of the controls in the app UI's control stack consumed it.

Key events are sent to the application by the window server. A key press generates three separate key events in the order EEventKeyDown, EEventKey, and EEventKeyUp. Controls and app UIs are usually only interested in EEventKey events.

This default implementation simply returns EKeyWasNotConsumed. It may need to be overridden if the derived app UI needs to handle certain key events itself. For example, in some applications, arrow keys may be used to navigate between views. In this case, the app UI should override this function to consume the arrow keys.

Parameters

const TKeyEvent &aKeyEvent The key event details, including the key code and any modifiers. TEventCode aType The type of key event, for instance standard, key up or key down.

Return value

TKeyResponse This indicates whether or not the key event was consumed by the app UI.

private: virtual IMPORT_C void HandleForegroundEventL(TBool aForeground);

Description

Handles changes in keyboard focus when the application is brought to the foreground, or put into the background.

This function is called from HandleWsEventL() when an EEventFocusLost or EEventFocusGained event occurs.

This default implementation is empty.

Parameters

TBool aForeground ETrue if the application is being brought to the foreground, EFalse if it is being put into the background.

private: virtual IMPORT_C void HandleSwitchOnEventL(CCoeControl *aDestination);

Description

Handles the special switch on event.

This function is called by HandleWsEventL() if the device is switched on. This default implementation is empty.

Parameters

CCoeControl *aDestination The control associated with the event.

private: virtual IMPORT_C void HandleSystemEventL(const TWsEvent &aEvent);

Description

Handles system events generated by the window server.

This method should be overridden by the UI layer like CEikAppUi but not by individual applications. Application events (has a positive value greater than EEventUser) will be sent to HandleApplicationSpecificEventL .

Unrecognized events should be forwarded to the base class.

Parameters

const TWsEvent &aEvent The window server event that occurred.

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

Description

Handles an application-specific event.

This function is called from HandleWsEventL() when the app UI receives a window server event that is not in the standard range (in other words, it has a positive value greater than EEventUser).

This default implementation is empty.

Parameters

TInt aType The application-specific event value, greater than EEventUser. const TWsEvent &aEvent The window server event that occurred.

private: virtual IMPORT_C void SetAndDrawFocus(TBool aFocus);

Description

Sets the keyboard focus of a control and draws it.

This is called by HandleWsEventL() when it receives a focus change event and can also be called when a new control is moved to the top of the control stack.

This default implementation is empty. It is intended that an implementation should set the value of a focus flag within the control to the value given by aFocus. This flag indicates whether or not the control has keyboard focus. The function should then draw or change the appearance of the control to indicate whether or not it has focus.

Parameters

TBool aFocus ETrue sets the control as having keyboard focus. EFalse sets the control as not having keyboard focus.

private: virtual IMPORT_C CArrayFix< TCoeHelpContext > *HelpContextL() const;

Description

Gets a list of help contexts for the app UI.

This default implementation returns NULL.

Return value

CArrayFix< TCoeHelpContext > * The array of help contexts.

IMPORT_C void WriteInternalStateOfStackedControlsL(RWriteStream &aWriteStream) const;

Description

Parameters

RWriteStream &aWriteStream

IMPORT_C void RemoveFromViewStack(const MCoeView &aView, CCoeControl *aControl);

Description

Parameters

const MCoeView &aView CCoeControl *aControl

IMPORT_C void AddToViewStackL(const MCoeView &aView, CCoeControl *aControl, TInt aPriority=ECoeStackPriorityDefault, TInt aStackingFlags=ECoeStackFlagStandard);

Description

Parameters

const MCoeView &aView CCoeControl *aControl TInt aPriority TInt aStackingFlags

protected: CCoeEnv * iCoeEnv;

Description