Class CEikChoiceList

class CEikChoiceList : public CEikChoiceListBase, public MQikCommandListOwner, public MQikCommandHandler;

Description

Allows a user to view a single item at a time from a list of items, and to scroll through these items. Users can select the desired item from the drop-down dialog, launched by a single tap on the choice list control's down arrow.

Flags set during initialisation can be used to allow item selection through incremental matching of entered text. A flag can also be set to disable the drop-out dialog.

When the array is set it should not be altered externally. The correct way to set new data in the choicelist is to set a completely new array, not altering the old one. If the caller choses to change the array anyway it is up to him to call CEikChoiceListBase::SetCurrentItem(TInt aItem) to ensure that the index is updated accordingly.

It is possible to use icons in the choicelist. The icons must be added to an array which is set to the choicelist by SetIconArray(). Each textitem is divided into two parts; the icon index part and the text part. The parts is separated by \t. The icon index part can be omitted (the icon part will be empty).

RPointerArray<CGulIcon>* icons = new(ELeave)RPointerArray<CGulIcon>(2);
//Add two CGulIcon to the array.
...
//Give the icon array to the choice list.
choiceList->SetIconArrayL(icons);

//Create some texts and add them to an array.
_LIT(text0, "0\thello");
_LIT(text1, "1\texample");
_LIT(text2, "2\tone"); //We do only have two icons. This item will not have any icon.
_LIT(text2, "-1\tone"); //We do not want this item to have any icon.

CDesCArrayFlat* array = new(ELeave) CDesCArrayFlat(1);
array->AppendL(text0);
array->AppendL(text1);
array->AppendL(text2);
array->AppendL(text3);

//Give the texts to the choice list.
choiceList->SetArrayL(array);

See HowTo guide for Choice List in UIQ Developer Library for further details.

Derivation

• MQikCommandHandler - Interface for classes responsible of executing commands
• MQikCommandListOwner - Interface for classes adding commands
• MCoeControlObserver - Interface for a control to send events to its observer control

• CCoeControl - Control base class from which all other controls are derived
• CEikBorderedControl - A control which is drawn surrounded by a rectangular border
• CEikChoiceListBase - Base class for a choice list control
• CEikChoiceList - Allows a user to view a single item at a time from a list of items, and to scroll through these items

Members

Defined in CEikChoiceList:
ActivateListBoxL(), CEikChoiceList(), ClosePopout(), ConstructFromResourceL(), ConstructL(), ConstructL(), CreateListBoxL(), CreatePopoutL(), DestroyIconArray(), DestroyPopout(), DoCreatePopoutL(), DoDrawContent(), DrawContent(), ECenter, ELeft, ERight, GetColorUseListL(), GetTextDrawer(), HandleCommandL(), HandleResourceChange(), InitializeListBoxL(), MakeVisible(), MapCommandHandler(), MinimumSize(), PopoutCurrentItem(), PopoutTextListBox(), PopoutTextListBox(), PrepareForFocusGainL(), PrepareForFocusLossL(), SetArrowVisible(), SetContentArray(), SetIconArray(), SetListBoxExtentL(), SetTextAlignment(), TTextAlignment, TextBaselineOffset(), TextRect(), ~CEikChoiceList()

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(), 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:
Border(), ComponentControl(), CountComponentControls(), GetHelpContext(), HandleControlArrayEventL(), HandlePointerBufferReadyL(), HasBorder(), MopSupplyObject(), PositionChanged(), RequestRelayout(), SetBorder(), SetContainerWindowL(), SetDimmed(), SetLayoutManagerL(), SetNeighbor(), SetParent(), SetTextBaselineSpacing(), WriteInternalStateL(), iBorder

Inherited from CEikChoiceListBase:
ActivateL(), AllowPopout(), Array(), CEikChoiceListBase_Reserved_1(), CalculateTextWidth(), ContentHasChangedL(), CurrentItem(), CurrentItemChangedL(), CursorPos(), DesCArray(), DestroyArray(), DisplayCursor(), Draw(), DrawContentNow(), EArrayOwnedExternally, EIncrementalMatching, EMirrorOutput, ENoPopout, FocusChanged(), Font(), HandleControlEventL(), HandleInteractionConfirmedL(), HandlePointerEventL(), InputCapabilities(), KEikMaxMatchingBufLength, MatchTypedChar(), OfferKeyEventL(), ResetMatchBuf(), SetAdjacent(), SetArrayExternalOwnership(), SetArrayL(), SetCurrentItem(), SetIncrementalMatching(), SizeChanged(), TFlags, TextEdgeMargin(), UndoLastChar(), anonymous, iArray, iChoiceListFlags, iCurrentItem, iMatchBuf, iMaxDisplayChar

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

Inherited from MEikBorderedControl:
ETypeId

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

Inherited from MQikCommandHandler:
HandleAttemptDimmedSelectionL()

IMPORT_C ~CEikChoiceList();

Description

Destructor.

IMPORT_C CEikChoiceList();

Description

Constructor.

Complete construction with ConstructL() .

IMPORT_C void ConstructL(TInt aFlags=0, TInt aMaxDisplayChar=0);

Description

Completes construction of this choice list.

Parameters

IMPORT_C void ConstructL(CCoeControl *, TInt aFlags, TInt aMaxDisplayChar);

Description

Parameters

IMPORT_C void SetTextAlignment(TTextAlignment aTextAlignment);

Description

Sets the alignment of the text displayed in the choice list box.

See the TTextAlignment enum.

Parameters

See also:

• TTextAlignment

IMPORT_C void SetArrowVisible(TBool aArrowVisible);

Description

Sets the visibility of the choice list arrow.

Parameters

IMPORT_C const CQikListBox *PopoutTextListBox() const;

Description

Gets the pop-out text list box.

Return value

IMPORT_C CQikListBox *PopoutTextListBox();

Description

Gets the pop-out text list box.

Return value

IMPORT_C void SetIconArray(RPointerArray< CGulIcon > *aIconArray);

Description

Sets the icon array. Any previosly added icon/content arrays are destroyed (if it is not externally owned).

Parameters

IMPORT_C void SetContentArray(RPointerArray< CQikContent > *aContentArray);

Description

Sets the content array. Any previosly added icon/content arrays are destroyed (if it is not externally owned).

Parameters

virtual IMPORT_C TSize MinimumSize();

Description

Gets the control's minimum size in pixels.

Return value

See also:

• CCoeControl::MinimumSize()

virtual IMPORT_C void MakeVisible(TBool aVisible);

Description

Parameters

See also:

• CCoeControl::MakeVisible()

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

Description

Gets the colours used to draw the control.

Parameters

See also:

• CEikBorderedControl::GetColorUseListL()

virtual IMPORT_C void HandleResourceChange(TInt aType);

Description

Handles a change to the control's resources.

The types of resources handled are those which are shared across the environment, e.g. colours or fonts.

Parameters

See also:

• CCoeControl::HandleResourceChange()

virtual IMPORT_C void PrepareForFocusGainL();

Description

Notifier called upon before the control gains focus.

See also:

• CCoeControl::PrepareForFocusGainL()

virtual IMPORT_C void PrepareForFocusLossL();

Description

Notifier called upon before the control loses focus.

See also:

• CCoeControl::PrepareForFocusLossL()

virtual IMPORT_C TInt TextBaselineOffset(const TSize &aSize) const;

Description

Gets the offset to the first text baseline relative to the top of the control. From CCoeControl .

Parameters

Return value

See also:

• CCoeControl::TextBaselineOffset()

virtual IMPORT_C MQikCommandHandler *MapCommandHandler(CQikCommand &aCommand);

Description

From MQikCommandListOwner

Parameters

Return value

virtual IMPORT_C void HandleCommandL(CQikCommand &aCommand);

Description

From MQikCommandHandler

Parameters

IMPORT_C void ClosePopout();

Description

Deletes/Closes the popout list.

protected: virtual IMPORT_C void ConstructFromResourceL(TResourceReader &aReader);

Description

Protected construction from resource.

Parameters

protected: virtual IMPORT_C void CreatePopoutL();

Description

Creates a pop-out list box.

Calls DoCreatePopoutL() .

If there is no array from which to create the pop-out, a beep is emitted.

protected: virtual IMPORT_C void DestroyPopout();

Description

Deletes the current popout list box and removes it from the stack.

protected: virtual IMPORT_C TInt PopoutCurrentItem() const;

Description

Gets the ID of the current popout item.

Return value

See also:

• CEikChoiceListBase::PopoutCurrentItem()

protected: virtual IMPORT_C void DrawContent() const;

Description

Gets a pointer to the text to draw.

Passes the pointer to DoDrawContent() function, which performs the drawing of the text.

protected: virtual IMPORT_C void DoDrawContent(const TDesC &aDes) const;

Description

Draws the content of the choice list box.

Accounts for the dim state of the control and clips the visible length of text to fit the available display area. Called by DrawContent() .

Parameters

protected: virtual IMPORT_C void DoCreatePopoutL();

Description

Creates a popout list box, sets its extent and activates the list box.

Called by CreatePopoutL() .

protected: virtual IMPORT_C void CreateListBoxL();

Description

Creates the popout listbox.

protected: virtual IMPORT_C void InitializeListBoxL();

Description

Initializes and constructs a list box as a popout from the choice list.

The list box is set as a popout list box, with incremental matching if this is already set for the choice list.

The list box has scroll bars if necessary, and its text is set from the current text array.

protected: virtual IMPORT_C void SetListBoxExtentL();

Description

Sets the extent of the popout list box.

Called by DoCreatePopoutL() .

protected: virtual IMPORT_C void ActivateListBoxL();

Description

Activates the popout listbox.

protected: virtual IMPORT_C TRect TextRect() const;

Description

Returns a TRect describing the rect inside the control available for e.g. text drawing.

Return value

protected: IMPORT_C void DestroyIconArray();

Description

Deletes the icon array if it not set as externally owned.

private: virtual IMPORT_C void GetTextDrawer(CCoeTextDrawerBase *&aTextDrawer, const CCoeControl *aDrawingControl, TInt aKey) const;

Description

Gets GetTextDrawer for the control.

Parameters

TTextAlignment

Description

Specifies text alignment in the choice list box.