Class CQikAppUi

class CQikAppUi : public CEikAppUi, public MQikCommandHandler;

Description

Application UI layer with support for categories.

This App UI class implements functions to set up a categories menu and respond to user choices. It uses, but does not own, a category model class CQikCategoryModel to hold the application’s categories information. Methods to initialise the categories from an ini file or resource file, and to externalise to an ini file, are provided by QikCategoryUtils .

Developers should derive from this class to provide the App UI for their application, and also from MQikEditCategoryObserver if they wish to use stock dialogs to add, remove or change the available categories.

Derivation

• MQikCommandHandler - Interface for classes responsible of executing commands
• MObjectProvider - An interface that allows an object to be part of a network of object providers
• 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

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

• CCoeAppUi - Application user interface (app UI) base class
• CEikAppUi - 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
• CQikAppUi - Application UI layer with support for categories

Members

Defined in CQikAppUi:
AboutToOpenOrCreateFile(), AddViewL(), AddViewL(), ApplicationRect(), AutoExitOnAppSwitch(), BaseConstructL(), CQikAppUi(), CategoryModel(), CoeView(), CoeView(), ConstructL(), CreateFileL(), CurrentCoeView(), CurrentQikView(), CurrentViewAsControl(), DynInitCategoryMenuPaneL(), DynInitCategoryMenuPaneL(), Exit(), HandleApplicationSpecificEventL(), HandleCategoryChangeL(), HandleCommandL(), HandleCommandL(), HandleError(), HandleForegroundEventL(), HandleMessageL(), HandleModelChangeL(), HandleResourceChangeL(), HandleSystemEventL(), HandleWsEventL(), IgnorePointerEventsWhenInBackground(), InputCapabilities(), OpenFileL(), PrepareToExit(), ProcessCommandL(), ProcessCommandParametersL(), ProcessCommandParametersL(), ProcessMessageL(), QikView(), RemoveToolbarL(), RemoveView(), ReportResourceChangedToAppL(), SetAutoExitOnAppSwitch(), SetCategoryModel(), SetFadedL(), SetToolbarL(), StopDisplayingMenuBar(), ViewAsControl(), ViewAsControl(), ViewCount(), ViewSwitcher(), ZoomFactorL(), ~CQikAppUi()

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

Inherited from CCoeAppUi:
ActivateViewL(), AddToStackL(), AddToViewStackL(), AddViewDeactivationObserverL(), AppHelpContextL(), CCoeAppUi_Reserved1(), CCoeAppUi_Reserved2(), CheckSourceOfViewSwitchL(), DeactivateActiveViewL(), DeregisterApplicationView(), DeregisterView(), GetActiveViewId(), GetDefaultViewId(), HandleStackChanged(), HandleStackedControlsResourceChange(), IsDisplayingControlBetweenPriorities(), IsDisplayingDialog(), IsDisplayingMenuOrDialog(), IsViewConstructed(), NotifyNextDeactivation(), RegisterApplicationViewL(), RegisterViewL(), RemoveFromStack(), RemoveFromViewStack(), RemoveViewDeactivationObserver(), SetDefaultViewL(), TopFocusedControl(), UpdateStackedControlFlags(), WriteInternalStateOfStackedControlsL(), iCoeEnv

Inherited from CEikAppUi:
Application(), ApplicationLanguageL(), ClientRect(), ClosePopup(), ContainerAppUi(), CreateHotKeyControlL(), Document(), ELastReservedEikAppUiFlag, ENoAppResourceFile, ENoScreenFurniture, ENonStandardResourceFile, EStandardApp, FadeWhenInBackground(), HandleScreenDeviceChangedL(), HandleSideBarMenuL(), LaunchPopupMenuL(), MopNext(), MopSupplyObject(), ReadAppInfoResourceL(), ReportResourceChangedToAppStackL(), SaveAnyChangesL(), SaveL(), SetDocChanged(), SetDocument(), SetEmbeddedDocInfo(), SetFaded(), anonymous, iContainerAppUi, iDocument, iDoorObserver, iEmbeddedAndReadOnly, iFlags

Inherited from MCoeMessageObserver:
EMessageHandled, EMessageNotHandled, TMessageResponse

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

Inherited from MObjectProvider:
MopGetObject(), MopGetObjectNoChaining()

See also:

• CQikCategoryModel
• QikCategoryUtils
• MQikEditCategoryObserver

IMPORT_C CQikAppUi();

Description

Default constructor.

First phase in the two phase construction. The construction process will be not complete until ConstructL() it's called and executed.

This constructor initialises the base class by calling the CEikAppUi default constructor. The class member method IgnorePointerEventsWhenInBackground() is also called.

See also:

• IgnorePointerEventsWhenInBackground()
• ConstructL()
• ~CQikAppUi()

IMPORT_C ~CQikAppUi();

Description

Destructor.

Frees all memory owned by the object, prior to its destruction.

virtual IMPORT_C void ConstructL();

Description

Second phase in the two phase construction. This function completes the construction of a newly allocated CQikAppUi instance.

This method should be overridden by the application's AppUi class deriving from this class. Usually the application's implementation of the App Ui class calls this method in its own ConstructL() method.

The BaseConstructL() method is called from within this method. Add application views from within this method.

See also:

• CQikAppUi()
• BaseConstructL()

IMPORT_C void AddViewL(CQikViewBase &aView);

Description

After you have created a view, use AddViewL to add the view to the framework. The framework will take over the ownership, register the view in the Viewserver and add it to CCoeAppUi's control stack. AddViewL needs to be called from ConstructL for at least one view to avoid the AppUi to be registered as viewless. Leaves if failed while registering the view, adding it to the control stack or due to OOM condition.

Parameters

CQikViewBase &aView The view to add to the framework.

See also:

• CCoeAppUi::RegisterViewL()
• CCoeAppUi::AddToStackL()

IMPORT_C void AddViewL(CCoeControl &aViewControl, MCoeView &aView);

Description

After you have created a view, use AddViewL to add the view to the framework. The framework will take over the ownership, register the view in the Viewserver and add it to CCoeAppUi's control stack. AddViewL needs to be called from ConstructL for at least one view to avoid the AppUi to be registered as viewless. Leaves if failed while registering the view, adding it to the control stack or due to OOM condition.

Parameters

CCoeControl &aViewControl MCoeView &aView The view to add to the framework.

See also:

• CCoeAppUi::RegisterViewL()
• CCoeAppUi::AddToStackL()

IMPORT_C void RemoveView(const CCoeControl &aView);

Description

Removing the active view will panic the view server. Removes the view from the framework by deregistering it and removing it from the control stack.

This should only be called if you want to destruct a view in runtime without closing the application. Normally there is no need for a developer to call this function as it is done by CQikAppUi's destructor.

Parameters

const CCoeControl &aView The view to remove from the framework must have been added with AddViewL() .

See also:

• CCoeAppUi::RemoveFromStack()
• CCoeAppUi::DeregisterView()
• AddViewL()

IMPORT_C TInt ViewCount() const;

Description

Returns the number of views.

Return value

TInt The number of views.

IMPORT_C MCoeView *CoeView(TInt aIndex);

Description

Returns a view for an index. Must have been added with AddViewL() .

Parameters

TInt aIndex The index of the view that will be fetched.

Return value

MCoeView * A pointer to a MCoeView view with the index aIndex or NULL if it has not found.

See also:

• AddViewL()

IMPORT_C CCoeControl *ViewAsControl(TInt aIndex);

Description

Returns a view for an index. Must have been added with AddViewL() .

Parameters

TInt aIndex The index of the view that will be fetched.

Return value

CCoeControl * A pointer to a CCoeControl view with the index aIndex or NULL if it has not found.

See also:

• AddViewL()

IMPORT_C MCoeView *CoeView(const TVwsViewId &aViewId);

Description

Returns a view for a viewid. Must have been added with AddViewL() .

Parameters

const TVwsViewId &aViewId The view id of the view that will be fetched.

Return value

MCoeView * A pointer to a MCoeView view with the view id aViewId or NULL if it has not found.

See also:

• AddViewL()

IMPORT_C CQikViewBase *QikView(const TVwsViewId &aViewId);

Description

Returns a view for aViewId . Checks if the view is a CQikViewBase using the MOP framework.

Parameters

const TVwsViewId &aViewId The id of the view.

Return value

CQikViewBase * The view, or NULL if the view doesn't exist or isn't a CQikViewBase

IMPORT_C CCoeControl *ViewAsControl(const TVwsViewId &aViewId);

Description

Returns a view for a viewid. Must have been added with AddViewL() .

Parameters

const TVwsViewId &aViewId The view id of the view that will be fetched.

Return value

CCoeControl * A pointer to a CCoeControl view with the view id aViewId or NULL if it has not found.

See also:

• AddViewL()

IMPORT_C MCoeView *CurrentCoeView();

Description

Only one view at a time can be active in an application. This method returns the currently active view.

Return value

MCoeView * The currently active view.

IMPORT_C CQikViewBase *CurrentQikView();

Description

Only one view at a time can be active in an application. This method returns the currently active view. It also checks so that the current view is a CQikViewBase using the MOP framework.

Return value

CQikViewBase * The currently active view, or NULL if none is active, or if the active view isn't a CQikViewBase

IMPORT_C CCoeControl *CurrentViewAsControl();

Description

Only one view at a time can be active in an application. This method returns the currently active view.

Return value

CCoeControl * The currently active view.

IMPORT_C CQikViewSwitcher &ViewSwitcher();

Description

Returns the view switcher member. The CQikViewSwitcher is used to handle view switching and back behaviour.

Return value

CQikViewSwitcher & The view switcher.

virtual IMPORT_C void HandleResourceChangeL(TInt aType);

Description

Handles a change to the application's run-time resources which are shared across the environment, colors or fonts for example.

Parameters

TInt aType The type of resource that has changed.

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

Description

Processes a message. This function calls CEikAppUi::ProcessMessageL() .

Parameters

TUid aUid The message Uid. const TDesC8 &aParams The message's parameters.

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

Description

Handles an application-defined error message.

This function allows application-defined error messages to be called from functions within the control framework’s active scheduler.

Parameters

TInt aError KErrNone or another error code. const SExtendedError &aExtErr Pointer to the extended error definition. TDes &aErrorText Pointer to the text associated to this error. TDes &aContextText Pointer to the context text.

Return value

TErrorHandlerResponse Response from the error handler.

Interface status:

deprecated

IMPORT_C CQikCategoryModel *CategoryModel() const;

Description

This method has been deprecated. Use the new Command Processing Framework instead.

Return value

CQikCategoryModel * The category model.

See also:

• CQikViewBase::CategoryModel()

Interface status:

deprecated

IMPORT_C void SetCategoryModel(CQikCategoryModel *aCategoryModel);

Description

This method has been deprecated. Use the new Command Processing Framework instead.

Set the CategoryModel to be used by the category menu pane. Note: Does NOT take ownership of the Category Model.

Parameters

CQikCategoryModel *aCategoryModel The category model used by the category menu pane.

See also:

• CQikViewBase::SetCategoryModel()

IMPORT_C void SetToolbarL(TUint aToolbarResId, TDrawNow aDrawNow=EDrawNow);

Description

Creates a toolbar from the resource with the given id.

Parameters

TUint aToolbarResId The resource-id of the toolbar. TDrawNow aDrawNow Whether the toolbar should be redrawn now. Default is EDrawNow .

Panic codes

EQikPanicFailedToCreateToolbar DEBUG_BUILDS: Toolbar creation failed but did not leave properly. RELEASE_BUILDS: does nothing.

See also:

• QIK_TOOLBAR

IMPORT_C void RemoveToolbarL();

Description

Removes the current toolbar from the application space.

No action is taken if there is no current toolbar.

static IMPORT_C TInt ZoomFactorL(TInt aZoomLevel, const CEikonEnv &aEikonEnv);

Description

Returns zoomfactor for any valid zoomlevel, panics otherwise. If a Zoom.ini file has been created, the zoomfactor values are read from this file rather than from the resource file. This enables runtime changes of the zoomfactors.

Parameters

TInt aZoomLevel The zoomlevel for which you want to retrieve a zoomfactor. const CEikonEnv &aEikonEnv A reference to a CEikonEnv .

Return value

TInt The zoom factor.

IMPORT_C TBool AutoExitOnAppSwitch() const;

Description

Checks if EAutoExitOnAppSwitch is set.

Return value

TBool ETrue if the EAutoExitOnAppSwitch flag is set.

virtual IMPORT_C void PrepareToExit();

Description

Performs pre-exit processing on the control environment. This function calls CEikAppUi::PrepareToExit() .

See also:

• CEikAppUi::PrepareToExit()

virtual IMPORT_C void HandleCommandL(CQikCommand &aCommand);

Description

This is where command selections for orphan commands ends up. The default implementation shows an infoprint in debug builds. From MQikCommandHandler .

Parameters

CQikCommand &aCommand The selected command that is to be handled.

Interface status:

deprecated

virtual IMPORT_C void HandleCommandL(TInt aCommandId);

Description

Parameters

TInt aCommandId

Interface status:

deprecated

protected: virtual IMPORT_C void HandleCategoryChangeL(TInt aCategoryHandle);

Description

This method has been deprecated. Use the new Command Processing Framework instead.

Empty default implementation of the HandleCategoryChangeL() method.

Parameters

TInt aCategoryHandle The handle of the category chosen by the user in the menu.

See also:

• CQikViewBase::HandleCommandL()

Interface status:

deprecated

protected: IMPORT_C void DynInitCategoryMenuPaneL(CEikMenuPane *aMenuPane);

Description

This method has been deprecated. Use the new Command Processing Framework instead.

Call this method from the applications DynInitMenuPaneL to add the categories in the CategoryModel to the category menu pane.

Parameters

CEikMenuPane *aMenuPane This is a pointer to the pane which is about to be displayed

See also:

• CQikViewBase::DynInitOrDeleteCommand()

Interface status:

deprecated

protected: IMPORT_C void DynInitCategoryMenuPaneL(CEikMenuPane *aMenuPane, const TArray< TInt > aExcludeHandles);

Description

This method has been deprecated. Use the new Command Processing Framework instead.

Call this method from the applications DynInitMenuPaneL to add the categories in the CategoryModel to the category menu pane.

Parameters

CEikMenuPane *aMenuPane This is a pointer to the pane which is about to be displayed. const TArray< TInt > aExcludeHandles A list of handles to exclude from the menu pane.

See also:

• CQikViewBase::DynInitOrDeleteCommand()

protected: IMPORT_C void SetAutoExitOnAppSwitch(TBool aAutoExit);

Description

Requests the framework to close the application when it loses foreground. This mechanism is typically only used by applications that behave as though they are part of another application, for instance viewers.

Note that this automatic exit flag can be set on embedded app UI objects, and such objects will be closed down when the user switches away to another application.

Parameters

TBool aAutoExit ETrue to request application closure, otherwise false.

protected: IMPORT_C void IgnorePointerEventsWhenInBackground(TBool aIgnore);

Description

Tells the framework not to send pointer events to the application when it is in the background.

Viewer applications may not cover the whole of the application screen space, so allowing the user to tap on another, backgrounded, application. It is rare for an application to want to process these events, so the default is for these not to be sent to the application.

Parameters

TBool aIgnore ETrue to ignore pointer events, EFalse to receive them.

protected: IMPORT_C TBool AboutToOpenOrCreateFile() const;

Description

Tests whether a file for the application is about to be opened or created.

This function is provided for viewer applications. The system can request the view to close its dialog through its MQikShutterTarget interface when either:

• The application is losing foreground, e.g. as another application is being opened.

• The viewer should open a different file.

Call this function to check which of these is happening.

Return value

TBool ETrue if there is a pending call to the app UI's OpenFileL() or CreateFileL() , otherwise EFalse .

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

Description

Initialises this App UI with standard values.

The application's implementation of the App Ui class must make sure that this method is called during the construction phase. Either by calling the CQikAppUi::ConstructL() method from its own ConstructL() method or by calling this method directly, that is the method CQikAppUi::BaseConstructL() .

Parameters

TInt aAppUiFlags Application user interface flags. See CEikAppUi::EStandardApp as an example.

Panic codes

EQikPanicApplicationNotDerivedFromQikon DEBUG_BUILDS: No application instance exists or the application instance does not derive from CQikApplication. RELEASE_BUILDS: does nothing. EQikPanicDocumentNotDerivedFromQikon DEBUG_BUILDS: No document instance exists or the document instance does not derive from CQikDocument. RELEASE_BUILDS: does nothing.

See also:

• CEikAppUi::BaseConstructL()
• ConstructL()
• CEikAppUi::EStandardApp

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

Description

Handles a specific window server event for the application.

This function calls CEikAppUi::HandleApplicationSpecificEventL() which takes action on notification of a change to the environment color scheme and informs everything on the control stack of the change.

Parameters

TInt aType The type of event. const TWsEvent &aEvent The window server event.

See also:

• CEikAppUi::HandleApplicationSpecificEventL()

protected: virtual IMPORT_C void HandleForegroundEventL(TBool aForeground);

Description

Handles a change in keyboard focus when an application is about to get or lose the foreground.

This function should be overridden, and that function should call this implementation.

Parameters

TBool aForeground ETrue if the application is being foregrounded, EFalse if it is being backgrounded.

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

Description

Handles window server events.

It is called whenever the window server sends an event (standard or special) to the application. This function calls CEikAppUi::HandleWsEventL() .

Parameters

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

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

Description

Handles message ready events generated by the window server.

Parameters

const TWsEvent &aEvent The window server event that occurred.

See also:

• CCoeAppUi::HandleSystemEventL()

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

Description

Handles window server messages.

Parameters

TUint32 aClientHandleOfTargetWindowGroup The window group that the message was sent to. TUid aMessageUid The message UID. const TDesC8 &aMessageParameters The message parameters.

Return value

MCoeMessageObserver::TMessageResponse EMessageHandled if the window group can handle the message. EMessageNotHandled otherwise.

protected: virtual IMPORT_C void ProcessCommandL(TInt aCommand);

Description

Dispatches calls to HandleCommandL and HandleCategoryChangeL .

Parameters

TInt aCommand The Command Id of the menu item that was clicked.

Panic codes

EQikPanicNoAppUiFactory DEBUG_BUILDS: The app ui factory could not be retrieved from iEikonEnv . RELEASE_BUILDS: does nothing.

See also:

• MEikCommandObserver::ProcessCommandL()

virtual IMPORT_C TBool ProcessCommandParametersL(CApaCommandLine &aCommandLine);

Description

Processes shell commands. Called by the application framework when an application is launched by the user opening an application from the shell or when a Create new file command is issued.

Parameters

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

Return value

TBool ETrue if the application exist.

virtual IMPORT_C void HandleModelChangeL();

Description

Handles changes to the model associated with this application.

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

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

virtual IMPORT_C void SetFadedL(TBool aFaded);

Description

Sets whether the graphics context is faded.

Parameters

TBool aFaded ETrue if the application is being faded, EFalse otherwise.

virtual IMPORT_C void ReportResourceChangedToAppL(TInt aType);

Description

Reports a resource change to the application.

Parameters

TInt aType The type of resource that has changed.

virtual IMPORT_C void OpenFileL(const TDesC &aFileName);

Description

Opens the specified file.

Parameters

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

virtual IMPORT_C void CreateFileL(const TDesC &aFileName);

Description

Creates and opens a file with the given name.

Parameters

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

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

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 IMPORT_C TCoeInputCapabilities InputCapabilities() const;

Description

Returns the input capabilities of the control with focus.

Return value

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

See also:

• CCoeAppUi::InputCapabilities()

virtual IMPORT_C void Exit();

Description

Closes the app UI.