Class CEikDialog

Interface status:

deprecated

Quartz 6.0

class CEikDialog : public CEikBorderedControl, public MCoeControlObserver;

Description

Dialog base class.

Instances of the CEikDialog class may be created, and it is possible to add controls directly to them. However it is more normal to create a subclass, and to handle the controls appearing on the dialog dynamically.

The API defines a large number of functions, however only a fraction of these are required for implementing most custom dialogs. These include ExecuteLD(), and all the functions under the headings "Dialog initialisation and validity checking" and "Useful library functions".

Derivation

• MCoeControlObserver - Interface for a control to send events to its observer control
• MEikBorderedControl - Interface for bordered controls

MObjectProvider - An interface that allows an object to be part of a network of object providers

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

• CCoeControl - Control base class from which all other controls are derived
• CEikBorderedControl - A control which is drawn surrounded by a rectangular border
• CEikDialog - Dialog base class

Members

Defined in CEikDialog:
ActivateFirstPageL(), ActivateL(), ActivePageId(), ActivePageIndex(), AddCommandListL(), AddTabL(), AdjustAllIdsOnPage(), Border(), CEikDialog(), CEikDialog_Reserved_3(), CEikDialog_Reserved_4(), CEikDialog_Reserved_5(), CEikDialog_Reserved_6(), ComponentControl(), ConstructFromResourceL(), ConstructSleepingAlertDialogL(), ConstructSleepingDialogL(), Control(), ControlCaption(), ControlOrNull(), CountComponentControls(), CreateCustomControlL(), CreateLineByTypeL(), CreateLineByTypeL(), CurrentLine(), DeleteCommandListL(), DeleteLine(), DisableTitlePointerEvents(), DynInitOrDeleteCommandL(), EAllPersistence, ELandscapePersistence, ENoPersistence, EPortraitPersistence, ESoftkeyStyleSmallPersistence, ExecuteLD(), ExitSleepingDialog(), FindCompatibleUiConfig(), FindLineIndex(), FocusChanged(), GetColorUseListL(), GetHelpContext(), HandleAttemptDimmedSelectionL(), HandleCommandL(), HandleControlArrayEventL(), HandleControlEventL(), HandleControlStateChangeL(), HandleInteractionRefused(), HandlePointerBufferReadyL(), HandlePointerEventL(), HandleResourceChange(), HandleUiConfigChangedL(), HasBorder(), IdOfFocusControl(), InputCapabilities(), InsertLineL(), IsCommandListActive(), Layout(), Line(), LineChangedL(), MakeLineVisible(), MakeVisible(), MakeWholeLineVisible(), MapCommandHandler(), MinimumSize(), MopSupplyObject(), OfferKeyEventL(), OkToExitL(), PageChangedL(), Persistence(), PostLayoutDynInitL(), PreLayoutDynInitL(), PreferredSize(), PrepareForFocusGainL(), PrepareForFocusLossL(), PrepareForFocusTransitionL(), PrepareForcedExitL(), PrepareLC(), RequestRelayout(), ResetLineMinimumSizes(), RotateFocusByL(), RouseSleepingDialog(), RunLD(), SetActivePageL(), SetAdjacent(), SetBorder(), SetBorder(), SetCategoryModelAsCommandsL(), SetContainerWindowL(), SetControlCaptionL(), SetControlCaptionL(), SetDimmed(), SetHelpContext(), SetInitialCurrentLine(), SetLayoutManagerL(), SetLineDimmedNow(), SetLineNonFocusing(), SetNeighbor(), SetPageDensePacking(), SetPageDimmedNow(), SetParent(), SetPersistence(), SetSizeAndPosition(), SetTextBaselineSpacing(), SetTitleL(), SetTitleL(), SetTitleLeftImageL(), SizeChanged(), SwapCommandListL(), SwitchLineLatency(), TPersistenceFlag, TextBaselineOffset(), Title(), TryChangeFocusToL(), TryExitL(), operator class MQikCommandListOwner &(), operator class MQikCommandListOwner *(), operator const class MQikCommandListOwner &(), operator const class MQikCommandListOwner *(), ~CEikDialog()

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

Inherited from CCoeControl:
AccumulatedZoom(), ActivateGc(), BackedUpWindow(), Background(), CapturesPointer(), ClaimPointerGrab(), CloseWindow(), ComponentArrayExists(), Components(), ControlContext(), ControlEnv(), CopyControlContextFrom(), CreateBackedUpWindowL(), CreateWindowL(), DeactivateGc(), DrawBackground(), DrawDeferred(), DrawForeground(), DrawNow(), DrawableWindow(), EAbsoluteZoom, ERelativeZoom, EnableDragEvents(), FindBackground(), FindFontProvider(), GetColor(), GetGc(), GetTextDrawer(), GrabbingComponent(), HandleComponentControlsResourceChange(), HandleRedrawEvent(), HitTest(), IgnoreEventsUntilNextPointerUp(), Index(), InitComponentArrayL(), IsActivated(), IsBackedUp(), IsBeingDestroyed(), IsBlank(), IsDimmed(), IsFocused(), IsNonFocusing(), IsReadyToDraw(), IsVisible(), LayoutManager(), MaximumWidth(), MopNext(), Observer(), OverrideColorL(), OwnsWindow(), Parent(), Position(), PositionRelativeToScreen(), Rect(), RecursivelyMergedInputCapabilities(), ReportEventL(), Reserved_2(), ResetGc(), ScreenFont(), SetAllowStrayPointers(), SetBackground(), SetBlank(), SetCanDrawOutsideRect(), SetComponentsToInheritVisibility(), SetControlContext(), SetCornerAndSize(), SetExtent(), SetExtentToWholeScreen(), SetFocus(), SetFocusing(), SetFontProviderL(), SetGc(), SetGloballyCapturing(), SetHitTest(), SetMaximumWidth(), SetMopParent(), SetNonFocusing(), SetObserver(), SetPointerCapture(), SetPosition(), SetRect(), SetSize(), SetSizeWithoutNotification(), SetUniqueHandle(), SetZoomFactorL(), Size(), SystemGc(), TZoomType, TextDrawer(), UniqueHandle(), Window(), ZoomWithType(), iCoeEnv, iContext, iPosition, iSize

Inherited from CEikBorderedControl:
Draw(), PositionChanged(), WriteInternalStateL(), iBorder

Inherited from MCoeControlObserver:
EEventInteractionRefused, EEventPrepareFocusTransition, EEventRequestCancel, EEventRequestExit, EEventRequestFocus, EEventStateChanged, MCoeControlObserver_Reserved1(), MCoeControlObserver_Reserved2(), TCoeEvent

Inherited from MEikBorderedControl:
ETypeId, anonymous

Inherited from MObjectProvider:
MObjectProvider_Reserved1(), MObjectProvider_Reserved2(), MopGetObject(), MopGetObjectNoChaining()

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C CEikDialog();

Description

Constructor. This function constructs the dialog and sets its border.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C ~CEikDialog();

Description

Destructor. This frees all memory owned by the dialog prior to its destruction. It is invoked before ExectuteLD() returns.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C operator class MQikCommandListOwner *();

Description

Return value

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C operator const class MQikCommandListOwner *() const;

Description

Return value

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C operator class MQikCommandListOwner &();

Description

Return value

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C operator const class MQikCommandListOwner &() const;

Description

Return value

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C TInt ExecuteLD(TInt aResourceId);

Description

Loads, displays, and destroys the dialog.

This function loads the specified dialog from a resource and displays it. The method then destroys the dialog when it exits therefore there is no need for the application program to destroy the dialog (this property is indicated by the function's "D" suffix).

In the resource file, use the EEikBidOk dialog button ID for an OK/Done/Continue button and EEikBidCancel for a Cancel button.

The function returns immediately unless EEikDialogFlagWait has been specified in the DIALOG resource. If EEikDialogFlagWait is specified, it returns when the dialog exits.

Parameters

TInt aResourceId The resource ID of the dialog to load.

Return value

TInt Zero, unless it is a waiting dialog. For a waiting dialog, the return value is the ID of the button that closed the dialog, or zero if it was the cancel button (EEikBidCancel).

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void PrepareLC(TInt aResourceId);

Description

Prepares to construct the dialog from a resource.

This function is called by the dialog framework (ExecuteLD()) to perform static construction/initialisation from a resource — prior to dynamic construction (layout) and display of the dialog using RunLD().

Parameters

TInt aResourceId The resource ID of the dialog.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C TInt RunLD();

Description

Runs and then destroys the dialog. The dialog is destroyed on exit.

This function is called by the dialog framework (ExecuteLD() ) to perform dynamic construction (layout) and to display/destroy the dialog. Static construction of the dialog must already be complete before this function is called, e.g. using PrepareLC() .

The function returns immediately unless EEikDialogFlagWait has been specified in the DIALOG resource. If EEikDialogFlagWait is specified, it returns when the dialog exits.

Return value

TInt Zero.

See also:

• CEikDialog::ExecuteLD()

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C CEikMover &Title() const;

Description

Gets a reference to the dialog title bar.

Return value

CEikMover & A reference to the dialog title bar.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void SetTitleL(const TDesC &aText);

Description

Sets the dialog title text from a descriptor.

Parameters

const TDesC &aText The descriptor containing the new title text.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void SetTitleL(TInt aResourceId);

Description

Sets the dialog title text from a resource.

Parameters

TInt aResourceId The ID of the resource containing the title text.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void SetTitleLeftImageL(CEikImage *aLeftImage);

Description

Sets the left image in the Title. The image height won't affect the Title height so make sure it is not too high.

Parameters

CEikImage *aLeftImage the image to be used. Ownership of the image is taken.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void DisableTitlePointerEvents(TBool aDisabled);

Description

Parameters

TBool aDisabled

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void SetPageDimmedNow(TInt aPageId, TBool aDimmed);

Description

Sets the specified page to be dimmed. The page is redrawn immediately. If the AddTabL function has been used to add tabs this will only dim the tab and not the whole page.

Parameters

TInt aPageId The ID of the page to be dimmed. TBool aDimmed ETrue to dim the page, EFalse to un-dim it.

See also:

• CEikDialog::AddTabL()

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void SetActivePageL(TInt aPageId);

Description

Sets the specified page to active. The page is redrawn immediately. If the AddTabL function has been used to add tabs this will only change tab and not the whole page.

Parameters

TInt aPageId The ID of the page to be dimmed.

See also:

• CEikDialog::AddTabL()

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void SetLineNonFocusing(TInt aControlId);

Description

Sets the specified dialog line to a non-focusing state. After this function is called, the line will never be given keyboard focus.

Note: On construction, dialog lines copy their state from the control they contain, so any line containing a non-focusing control will also by default be non-focusing.

Parameters

TInt aControlId The ID of the control in the line which is to be set as non-focusing.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void SetLineDimmedNow(TInt aControlId, TBool aDimmed);

Description

Dims or un-dims the specified line. Lines should be dimmed if it is not currently meaningful to select them.

Parameters

TInt aControlId The ID of the line to dim or un-dim. TBool aDimmed ETrue to dim the line, EFalse to un-dim it.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void MakeLineVisible(TInt aControlId, TBool aVisible);

Description

Makes the specified control visible or invisible. This function affects the specified control the visibility of the caption is not affected.

Parameters

TInt aControlId The ID of the control to make visible or invisible. TBool aVisible ETrue to make the control visible. EFalse to make the control invisible.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void MakeWholeLineVisible(TInt aControlId, TBool aVisible);

Description

Makes the whole specified line visible or invisible. This function affects both the specified control and the caption.

Parameters

TInt aControlId The ID of the control on the line to make visible or invisible. TBool aVisible ETrue to make the line visible. EFalse to make the line invisible.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void DeleteLine(TInt aControlId);

Description

Deletes the specified dialog line.

Parameters

TInt aControlId The dialog line to delete.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void InsertLineL(TInt aIndex, TInt aResourceId, TInt aPageId=0);

Description

Inserts a line in the dialog. The function takes as arguments the page and line index at which the line is to be inserted, and the resource used to construct it.

Parameters

TInt aIndex The index at which the line is to be inserted. TInt aResourceId The ID of the resource which defines the line. TInt aPageId The page on which the line is to be added.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void TryChangeFocusToL(TInt aControlId);

Description

Tries to change focus to the specified line.

The function first calls PrepareForFocusLossL() on the currently focused control. If this doesn't leave it then transfers focus to the specified control. This is the way to change focus — the specified control should only refuse the request if its state is invalid. The function leaves if the line ID is not valid.

Parameters

TInt aControlId The ID of the line to focus.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void SwitchLineLatency(TInt aBecomesLatent, TInt aNoLongerLatent);

Description

Switches the latent line. The latent line is switched from aNoLongerLatent to aBecomesLatent .

If dialog lines are latent they are not visible and are not taken into account when laying out the dialog. Latent lines can then be swapped around on the dialog later.

Parameters

TInt aBecomesLatent The line ID of the line to become latent. TInt aNoLongerLatent The line ID of the line to that is no longer to be latent.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void SetPageDensePacking(TInt aPageId, TBool aDensePacking);

Description

Sets the specified page to be densely packed. This reduces the spacing between the dialog's lines.

Parameters

TInt aPageId The ID of the page to be densely packed. TBool aDensePacking ETrue for dense packing. EFalse for normal packing.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void Layout();

Description

Layout the dialog after calculating the rectangle within which the dialog will be confined.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C CCoeControl *CreateLineByTypeL(const TDesC &aCaption, TInt aControlId, TInt aControlType, TAny *aReturnValue);

Description

Creates a control line on the caption specified active page in the dialog. The line can thereafter be accessed through the identifieraControlId .

A control of type aControlType is created by the control factory and the return value of the line set to aReturnValue . If the value of aControlType is not known to the control factory then the construction of the control must be handled by CreateCustomControlL() .

Parameters

const TDesC &aCaption The active page on which the control line is to be created. TInt aControlId Id The ID of the control. After the line is created this can be used to access it. TInt aControlType The type of control to create. TAny *aReturnValue Deprecated. A random pointer.

Return value

CCoeControl * A pointer to the newly created control.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C CCoeControl *CreateLineByTypeL(const TDesC &aCaption, TInt aPageId, TInt aControlId, TInt aControlType, TAny *aReturnValue);

Description

Creates a control line on the page ID specified active page in the dialog. The line can thereafter be accessed through the identifier aControlId .

A control of type aControlType is created by the control factory and the return value of the line set to aReturnValue . If the value of aControlType is not known to the control factory then the construction of the control must be handled by CreateCustomControlL() .

Parameters

const TDesC &aCaption The caption to appear in the dialog line. TInt aPageId The ID of the active page on which the control line is to be created. TInt aControlId The ID of the control. After the line is created this can be used to access it. TInt aControlType The type of control to create. TAny *aReturnValue Deprecated. A random pointer.

Return value

CCoeControl * A pointer to the newly created control.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void SetControlCaptionL(TInt aControlId, const TDesC &aText);

Description

Sets the specified control's caption text from a descriptor. For the correct dialog caption resize and caption show up, it is the callers responsibility to call RequestRelayout() if needed whenever SetControlCaptionL() is called.

Parameters

TInt aControlId The ID of the control for which the caption text is being set. const TDesC &aText The text for the caption.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void SetControlCaptionL(TInt aControlId, TInt aResourceId);

Description

Sets the specified control's caption text from a resource. For the correct dialog caption resize and caption show up, it is the callers responsibility to call RequestRelayout() if needed whenever SetControlCaptionL() is called.

Parameters

TInt aControlId The ID of the control for which the caption text is being set. TInt aResourceId The ID of the resource containing the text for the caption.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C CEikLabel *ControlCaption(TInt aControlId) const;

Description

Gets a pointer to the specified control's caption.

Note: The function does not transfer of ownership of the control to the caller.

Parameters

TInt aControlId The ID of the control for which the label is required.

Return value

CEikLabel * A pointer to the caption.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C CCoeControl *Control(TInt aControlId) const;

Description

Gets a pointer to the specified control — panics if the control ID is invalid.

This function is used to get a CCoeControl* pointer to a particular control within a dialog, based on its ID. The pointer can then be cast to the actual type of control that it represents, allowing access to the control's member functions.

For example, the fragment below gets a pointer to the control with ID =ECidOfAControl in this dialog:

CCoeControl* control = this->Control(ECidOfAControl) ;

Note: The function does not transfer ownership of the control to the caller. If the dialog has two controls with the same ID, the function returns a pointer to the first one.

Parameters

TInt aControlId The ID of the control for which a pointer is required.

Return value

CCoeControl * A pointer to the control with ID aControlId .

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C CCoeControl *ControlOrNull(TInt aControlId) const;

Description

Gets a pointer to the specified control. Returns NULL if the control ID is invalid.

This function is used to get a CCoeControl* pointer to a particular control within a dialog, based on its ID. The pointer can then be cast to the actual type of control that it represents, allowing access to the control's member functions.

For example, the fragment below gets a pointer to the control with ID =ECidOfAControl in this dialog:

CCoeControl* control = this->ControlOrNull(ECidOfAControl);

Note: The function does not transfer of ownership of the control to the caller. If the dialog has two controls with the same ID, the function returns a pointer to the first one.

Parameters

TInt aControlId The ID of the control for which a pointer is required.

Return value

CCoeControl * A pointer to the control with ID aControlId , or NULL if it doesn't exist.

See also:

• CEikDialog::Control()

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C TInt ActivePageId() const;

Description

Gets the ID of the active dialog page.

Return value

TInt The ID of the active dialog page.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void ActivateFirstPageL() const;

Description

Activates the first page on the dialog. At least one page must be activated before the dialog can be used.

This function is called automatically by the dialog framework when the dialog is constructed, and when the line with initial focus is set.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C TInt SetHelpContext(const TCoeHelpContext &aContext);

Description

Sets the help context. Use this function to get the help icon, or overload GetHelpContext() .

Parameters

const TCoeHelpContext &aContext The context to use.

Return value

TInt KErrNone if successful, otherwise one of the system-wide error codes.

Interface status:

deprecated

IMPORT_C TSize PreferredSize(const TSize &aMaxSize) const;

Description

Gets the preferred size of a dialog. The maximum size that the dialog must fit within must be specified e.g. the size of the physical screen.

The function takes account of screen items like status bars. It is used by Layout() , and during dynamic construction to correctly size the dialog.

Parameters

const TSize &aMaxSize The maximum size of the area in which the dialog must fit.

Return value

TSize The preferred size of the dialog.

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void AddTabL(TInt aTabId, const TDesC &aTabText);

Description

This method is used to add tabs to a one-paged dialog. Calling this method will not add more pages. This method shall only be used if one wants the tabs to change the state of a page rather than change to a different page.

Call this method from PreLayoutDynInit(). Calling this method in a multipage dialog will raise a EEikDialogPanicTooManyPages Panic.

When changing tabs after using this method, a call to PageChangedL() will be made with the param set to the id of the selected tab.

Parameters

TInt aTabId The Id of the tab. const TDesC &aTabText The text that shall be shown on the tab.

See also:

• CEikDialog::PageChangedL()

Interface status:

deprecated

Inherited from: CEikDialog

virtual IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent &aKeyEvent, TEventCode aType);

Description

Handles key events.

Parameters

const TKeyEvent &aKeyEvent The key event. TEventCode aType The type of key event: EEventKey , EEventKeyUp or EEventKeyDown .

Return value

TKeyResponse Indicates whether or not the key event was used by this control. EKeyWasConsumed if the control takes action on the key event or EKeyWasNotConsumed otherwise.

See also:

• CCoeControl::OfferKeyEventL()

Interface status:

deprecated

Inherited from: CEikDialog

virtual IMPORT_C void GetColorUseListL(CArrayFix< TCoeColorUse > &aColorUseList) const;

Description

Gets the list of logical colours used to draw the dialog. The list includes an explanation of how each colour is used, and is appended to aColorUseList .

Parameters

CArrayFix< TCoeColorUse > &aColorUseList The colour list.

See also:

• CCoeControl::GetColorUseListL()

Interface status:

deprecated

Inherited from: CEikDialog

virtual IMPORT_C void HandleResourceChange(TInt aType);

Description

Handles a change to the dialog's resources. The types of resources handled are those which are shared across the environment, e.g. colours or fonts.

Parameters

TInt aType A message UID value.

See also:

• CCoeControl::HandleResourceChange()

Interface status:

deprecated

Inherited from: CEikDialog

virtual IMPORT_C void GetHelpContext(TCoeHelpContext &aContext) const;

Description

Gets the help context.

Parameters

TCoeHelpContext &aContext The help context.

Interface status:

deprecated

Inherited from: CEikDialog

virtual IMPORT_C TCoeInputCapabilities InputCapabilities() const;

Description

Gets the dialog's input capabilities.

Return value

TCoeInputCapabilities

See also:

• CCoeControl::HandleResourceChange()

Interface status:

deprecated

Inherited from: CEikDialog

virtual IMPORT_C TBool RequestRelayout(const CCoeControl *aChildControl);

Description

From CCoeControl

Parameters

const CCoeControl *aChildControl

Return value

TBool

Interface status:

deprecated

Inherited from: CEikDialog

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

Description

Parameters

TTypeUid aId

Return value

TTypeUid::Ptr

See also:

• CCoeControl::MopSupplyObject

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void SwapCommandListL(TInt aResourceId);

Description

Removes any currently inserted commands and inserts the ones defined by the given QIK_COMMAND_LIST resource.

Parameters

TInt aResourceId

Interface status:

deprecated

Inherited from: CEikDialog

IMPORT_C void AddCommandListL(TInt aResourceId);

Description

Adds another QIK_COMMAND_LIST to the dialog.

Parameters

TInt aResourceId