Class CCoeAppUi

CCoeAppUi

Support

Supported from 6.0

Description

General purpose application user interface class. This class handles application-wide aspects of the user interface, such as key-press events. The GUI may derive further to provide its own application user interface class to provide a more concrete framework for applications. An application derives once more to provide event handling facilities.

Note:

• this class derived additionally from MCoeInputObserver for ER5u, but not for ER5 or any of the DFRD releases

• the GUI class CEikAppUi is derived from this class

• the public header file coeaui.h declares a large number of public functions in addition to the ones described below, however these are for internal use only

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

Defined in CCoeAppUi:
ActivateViewL(), AddToStackL(), AppHelpContextL(), CCoeAppUi(), ConstructL(), DeregisterView(), HandleApplicationSpecificEventL(), HandleForegroundEventL(), HandleKeyEventL(), HandleMessageReadyL(), HandleStackChanged(), HandleStackedControlsResourceChange(), HandleSwitchOnEventL(), HandleSystemEventL(), HandleWsEventL(), HelpContextL(), InputCapabilities(), IsDisplayingControlBetweenPriorities(), IsDisplayingMenuOrDialog(), RegisterViewL(), RemoveFromStack(), SetAndDrawFocus(), UpdateStackedControlFlags(), ~CCoeAppUi()

Inherited from CBase:
operator new()

Inherited from CCoeAppUiBase:
PrepareToExit()

CCoeAppUi();

Description

Construction is only partial, to finish construction call ConstructL().

void ConstructL(CCoeAppUi* aPrevious=NULL);

Description

Completes construction of a CCoeAppUi. This function creates a control stack for the application. In post ER5u releases it also initiates a view server session.

Parameters

CCoeAppUi* aPrevious=NULL If non-NULL, the new control stack is initialised with the controls that existed on the control stack owned by aPrevious.

~CCoeAppUi();

Description

This frees all resources owned by the object, including the control stack and the view server session (after ER5u).

Description

Each control on the stack has a priority, and the position of each control on the stack is determined by its priority and the order in which the controls were added to the stack. Position 0 on the stack contains the control with the highest priority. If more than one control has the same priority, the most recently added has the lowest position. Each control on the stack also has a set of flags, which can be used to refuse key events and requests for focus.

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

Description

Adds a control to the control stack. This function is used by most GUI applications to add their application view — an application-specific control — to the stack.

Parameters

CCoeControl* aControl The control to add to the stack. TInt aPriority=ECoeStackPriorityDefault The control’s stack priority. This argument, and the other priority values, are given in an anonymous enumeration. Tint aStackingFlags=ECoeStackFlagStandard The control’s event handling behaviour. This argument, and the other flags, are given in an anonymous enumeration.

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

Support

Supported from 6.1

Description

Adds the control aControl to the control stack associated with the view aView.

Parameters

const MCoeView& aView,CCoeControl* aControl,TInt aPriority=ECoeStackPriorityDefault,TInt aStackingFlags=ECoeStackFlagStandard Adds a control to the control stack. Sets its stack priority aPriority and event handling flags aStackingFlags. High priority controls are offered key events first

void RemoveFromStack(CCoeControl* aControl);

Description

Removes a control from the control stack. The function also handles the change to the stack.

Parameters

CCoeControl* aControl The control to remove from the stack.

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

Description

Updates the value of the flags for a control on the control stack. The mask aMask defines which flags are modified, while aFlags defines the values they are set to.

The function panics if the control is not on the stack.

Parameters

CCoeControl* aControl The control whose flags are updated. 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.

void HandleStackChanged();

Description

Handles changes in control stack flags. This gives keyboard focus to the focusable control with the highest priority on the control stack.

It should be called whenever the flag values are modified, after calling UpdateStackedControlFlags() for example

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 the application is not currently displaying a menu bar or a dialog.

TBool IsDisplayingControlBetweenPriorities(TInt aLowerPriority, TInt aHigherPriority) const;

Description

Tests whether the application is displaying a control between given priorities. This function returns ETrue if the application is currently displaying a control which has a priority on the control stack of between (but not including) aLowerPriority and aHigherPriority.

Parameters

TInt aLowerPriority Lower bound of the control’s priority. TInt aHigherPriority Upper bound of the control’s priority.

Return value

TBool ETrue if a control with a priority between the specified bounds is currently being displayed.EFalse if no control with the specified priority is currently being displayed.

virtual TCoeInputCapabilities InputCapabilities() const;

Description

Returns the supported input capabilities of the control with focus.

Return value

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

Notes:

• In ER5u the function was inherited from MCoeInputObserver.
• Classes that override CCoeAppUi::HandleKeyEventL() should also override the InputCapabilities() virtual function, returning a TCoeInputCapabilities object whose attributes correspond to the behaviour of the HandleKeyEventL() function.
• Overriding InputCapabilities() functions 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.

void HandleStackedControlsResourceChange(TInt aType);

Description

Handles a change to the application's run-time resources for all controls on the control stack. These are resources which are shared across the environment, such as colours or fonts.

Note:

• In ER5u this function was protected.

Parameters

TInt aType Specifies a resource type.

protected: CArrayFix<TCoeHelpContext>* AppHelpContextL() const;

Description

Returns a list of relevant contexts within an application help file appropriate for the current state of the application. The array is generated from the application user interface and the controls on the control stack.

Return value

CArrayFix<TCoeHelpContext>* The list of pointers to relevant contexts that provide access to context-specific topics.

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

Description

Handles window server events.

This function is called whenever the window server sends an event aEvent (standard or special) to the application. It calls one of a number of functions, according to the type of the event received:

• For standard key press events this function calls CCoeControl::OfferKeyEventL() for each control on the stack, beginning with the control at the top (position 0) until a control returns EkeyWasConsumed. If no control on the stack consumes the key event, this function then calls HandleKeyEventL(). Note that CCoeControl::OfferKeyEventL() is not called for those controls whose flag ECoeStackFlagRefusesAllKeys is set.

• For standard pointer events this function calls CCoeControl::ProcessPointerEventL() on the control given by aDestination.

• For standard pointer buffer ready events this function calls ProcessPointerBufferReadyL() on the control given by aDestination.

• For special focus, switch on, user, and message ready events, this function calls one of the following private virtual functions:HandleForegroundEventL()HandleSwitchOnEventL()HandleSystemEventL()HandleMessageReadyL() (not available post ER5u)HandleApplicationSpecificEventL().All these functions have empty default implementations, and should be implemented by derived classes if required.

Parameters

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

See also:

• CCoeAppUiBase::HandleWsEventL()

Description

With the exception of HandleKeyEventL all of the virtual functions listed have empty default implementations.

The functions below are called by the system to handle responses to various kinds of events. They are not intended to be called by an application. They are provided to allow application developers to customise system responses to various kinds of events. These events can be handled at the level of the App UI by providing suitable implementations in derived classes.

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

Description

Handles key events.

This function is called by HandleWsEventL() if a key press event occurs and all of the controls on the control stack return EKeyWasNotConsumed from OfferKeyEventL(). It may be overridden by derived classes.

This function was replaced by another overload after ER5.

Parameters

const TKeyEvent& aKeyEvent The key event that occurred. TEventCode aType The event type.

Notes:

• In general, it is not recommended that derived classes overload this function. Key events should be handled by the view — see CCoeAppUi::AddToStackL().
• Classes that override CCoeAppUi::HandleKeyEventL() should also override the InputCapabilities() virtual function, returning a TCoeInputCapabilities object whose attributes correspond to the behaviour of the HandleKeyEventL() function. Note that the overriding InputCapabilities() function 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.

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

Description

Handles key events.

This function is called by HandleWsEventL() if a key press event occurs and all of the controls on the control stack return EKeyWasNotConsumed from OfferKeyEventL().

Key events come from the window server. Each keyboard key press generates three separate key events in the order; EEventKeyDown, EEventKey, and EEventKeyUp. Most controls are mainly interested in EEventKey for handling ordinary events.

This function may be overridden by derived classes.

Parameters

const TKeyEvent& aKeyEvent The key event that occurred. TEventCode aType The window server event type that is being handled.

Return value

TKeyResponse Value indicates whether or not the key event was consumed by the control. The default implementation simply returns EKeyWasNotConsumed.

private: virtual void HandleForegroundEventL(TBool aForeground);

Description

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

The function has an empty default implementation, and may be overridden by derived classes.

Parameters

TBool aForeground ETrue if the application is in the foreground, otherwise EFalse.

private: virtual void HandleSwitchOnEventL(CCoeControl* aDestination);

Description

Handles the special switch on event.

This function is called by HandleWsEventL() if the device is switched on. It has an empty default implementation, and may be overridden by derived classes.

Parameters

CCoeControl* aDestination The control associated with the event.

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

Description

Handles system events generated by the window server. It has an empty default implementation, and may be overridden by derived classes.

Parameters

const TWsEvent& aEvent The window server event that occurred.

private: virtual void HandleMessageReadyL();

Description

Handles message ready events generated by the window server. It has an empty default implementation, and may be overridden by derived classes.

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

Description

Handles the specified application-specific event. CCoeAppUi calls this function when it gets a window server event that is not in the system range (i.e type EEventUser). The type of event is usually identified by a UID value which some applications are expected to understand.

The function has an empty default implementation, and may be overridden by derived classes.

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.

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

Description

Gets a list of help contexts for a particular application user interface. This has an empty default implementation.

Return value

CArrayFix<TCoeHelpContext>* The array of help contexts.

void ActivateViewL(const TVwsViewId& aViewId);

Description

Activates a specified application view, without passing any message.

Parameters

const TVwsViewId& aViewId Identifier of the view to activate.

Leave codes

The function leaves if activation of the new view fails.

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

Description

Activates a specified application view, then passes the message text descriptor aCustomMessage for a message of type aCustomMessageId.

Notes:

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

• An application defines and publishes the message UIDs that it understands. For example, a contacts application activates an email editor view and passes 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 understandable.

Parameters

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

Leave codes

The function leaves if activation of the new view fails.

void RegisterViewL(MCoeView& aView);

Support

Supported from 6.1

Description

Registers the view aView with the view architecture. All views should be registered in the appUi ConstructL().

Parameters

MCoeView& aView The view to be registered.

void DeregisterView(const MCoeView& aView);

Support

Supported from 6.1

Description

Deregisters the view aView which is required before the application exits. Panics if there is no connection to the view server or if the view does not exist.

Parameters

const MCoeView& aView The view to be deregistered.

private: virtual void SetAndDrawFocus(TBool aFocus);

Description

Sets the keyboard focus of a control and then draws it. CCoeAppUi calls SetAndDrawFocus() when it gets a window server event on focus change, and in some cases when handling focus changes on the control stack.

The function has an empty default implementation, and may be overridden by derived classes. It is intended that implementation should set the value of a focus flag within the control is 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 currently has focus.

Parameters

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