![[Index]](../../../stock/btn_index.gif){kind=small}
![[Glossary]](../../../stock/btn_glossary.gif){kind=small}
![[Previous]](../../../stock/btn_prev.gif){kind=small}
![[Next]](../../../stock/btn_next.gif){kind=small}
| |
|
| |
Location:
eiklbx.h
Link against: eikcoctl.lib
CEikListBox
Supported from 6.0
Base class for an on-screen list box control from which one or more
items can be selected. CEikListBox implements the basics of a list
box — it has a scroll bar frame, an item drawer, and a model, and reports
events to a list box observer.
List boxes display a number of items within a scrolling frame; the items in a list box which are visible at one time are represented by a list box view.
Writing derived classes:
This class may be derived from to provide specialisations of the
basic list box behaviour. It is usual when subclassing CEikListBox
to also provide specialisations of CListItemDrawer and
CListBoxView for representing the data of such a list box
effectively.
|
Defined in CEikListBox:
AdjustRectHeightToWholeNumberOfItems(), AdjustTopItemIndex(), Anonymous, BackColor(), BottomItemIndex(), Buffer(), CEikListBox(), CalcHeightBasedOnNumOfItems(), CalcSizeInPixels(), CalcWidthBasedOnNumOfChars(), CalcWidthBasedOnRequiredItemWidth(), CalculatePopoutRect(), CheckCreateBufferL(), CheckCreateExtension(), CheckCreateExtensionL(), ClearMargins(), ClearMatchBuffer(), ClearSelection(), ComponentControl(), ConstructL(), CountComponentControls(), CreateMatchBufferL(), CreateScrollBarFrameL(), CreateViewL(), CurrentItemIndex(), Draw(), DrawItem(), DrawMatcherCursor(), ECreateOwnWindow, EIncrementalMatching, EItemDoubleClicked, EKeepModel, ELeftDownInViewRect, EMultipleSelection, ENoExtendedSelection, ENoFirstLetterMatching, EPaintedSelection, EPopout, EScrollBarSizeExcluded, EStateChanged, EditItemL(), FocusChanged(), GetColorUseListL(), HandleDragEventL(), HandleItemAdditionL(), HandleItemRemovalL(), HandleLeftArrowKeyL(), HandlePointerEventL(), HandleResourceChange(), HandleRightArrowKeyL(), HandleScrollEventL(), HandleViewRectSizeChangeL(), HorizScrollGranularityInPixels(), HorizontalMargin(), HorizontalNudgeValue(), InputCapabilities(), InterItemGap(), IsMatchBuffer(), ItemEditor(), ItemExists(), ItemHeight(), KEikListBoxInterItemGap, KEikMaxMatchingBufferLength, ListBoxMargins(), MakeViewClassInstanceL(), MatchBuffer(), MatchTypedCharL(), MinimumSize(), Model(), OfferKeyEventL(), ReasonForFocusLostL(), ReportListBoxEventL(), Reset(), ResetItemEditor(), RestoreClientRectFromViewRect(), RestoreCommonListBoxPropertiesL(), ScrollBarFrame(), ScrollToMakeItemVisible(), SelectionIndexes(), SetContainerWindowL(), SetCurrentItemIndex(), SetCurrentItemIndexAndDraw(), SetDimmed(), SetHorizontalMargin(), SetItemEditor(), SetItemHeightL(), SetLaunchingButton(), SetListBoxObserver(), SetReasonForFocusLostL(), SetSelectionIndexesL(), SetTopItemIndex(), SetVerticalMargin(), SetViewRectFromClientRect(), SimulateArrowKeyEventL(), SizeChanged(), StopEditingL(), TFlags, TopItemIndex(), UndoLastChar(), UpdateCurrentItem(), UpdateItemDrawerColors(), UpdateScrollBarThumbs(), UpdateScrollBarsL(), UpdateViewColors(), VerticalInterItemGap(), VerticalMargin(), View(), ViewRectHeightAdjustment(), iItemDrawer, iItemHeight, iLaunchingButton, iListBoxFlags, iListBoxObserver, iModel, iRequiredHeightInNumOfItems, iSBFrame, iView, ~CEikListBox()
Inherited from CBase:
operator new()
Inherited from CCoeControl:
ActivateGc(),
ActivateL(),
BackedUpWindow(),
CapturesPointer(),
ClaimPointerGrab(),
CloseWindow(),
ConstructFromResourceL(),
ControlContext(),
ControlEnv(),
CopyControlContextFrom(),
CreateBackedUpWindowL(),
CreateWindowL(),
DeactivateGc(),
DrawDeferred(),
DrawNow(),
DrawableWindow(),
EnableDragEvents(),
GetColor(),
GetHelpContext(),
GrabbingComponent(),
HandleComponentControlsResourceChange(),
HandlePointerBufferReadyL(),
HandleRedrawEvent(),
IgnoreEventsUntilNextPointerUp(),
Index(),
IsActivated(),
IsBackedUp(),
IsBeingDestroyed(),
IsBlank(),
IsDimmed(),
IsFocused(),
IsNonFocusing(),
IsReadyToDraw(),
IsVisible(),
MakeVisible(),
Observer(),
OverrideColorL(),
OwnsWindow(),
Position(),
PositionChanged(),
PositionRelativeToScreen(),
PrepareForFocusGainL(),
PrepareForFocusLossL(),
Rect(),
RecursivelyMergedInputCapabilities(),
ReportEventL(),
ResetGc(),
SetAllowStrayPointers(),
SetBlank(),
SetCanDrawOutsideRect(),
SetComponentsToInheritVisibility(),
SetContainerWindow(),
SetControlContext(),
SetCornerAndSize(),
SetCornerAndSizeL(),
SetExtent(),
SetExtentL(),
SetExtentToWholeScreen(),
SetExtentToWholeScreenL(),
SetFocus(),
SetFocusing(),
SetGloballyCapturing(),
SetNeighbor(),
SetNonFocusing(),
SetObserver(),
SetPointerCapture(),
SetPosition(),
SetRect(),
SetRectL(),
SetSize(),
SetSizeL(),
SetSizeWithoutNotification(),
SetSizeWithoutNotificationL(),
Size(),
SizeChangedL(),
SystemGc(),
Window()
Inherited from CEikBorderedControl:
Border(),
HasBorder(),
SetAdjacent(),
SetBorder(),
iBorder
Inherited from MEikScrollBarObserver:
EEikScrollBottom,
EEikScrollDown,
EEikScrollEnd,
EEikScrollHome,
EEikScrollLeft,
EEikScrollPageDown,
EEikScrollPageLeft,
EEikScrollPageRight,
EEikScrollPageUp,
EEikScrollRight,
EEikScrollThumbDragHoriz,
EEikScrollThumbDragVert,
EEikScrollThumbReleaseHoriz,
EEikScrollThumbReleaseVert,
EEikScrollTop,
EEikScrollUp,
TEikScrollEvent
CEikListBox();
Default constructor.
This function allocates memory for a list box, and initialises its stack-based members.
protected: void ConstructL(const CCoeControl* aParent,TInt aFlags = 0);
Protected second-phase constructor.
This protected form is overridden non-virtually by the
second-phase constructors of each subclass, and should be invoked by them using
CEikListBox::ConstructL().
|
void ConstructL(MListBoxModel* aListBoxModel,CListItemDrawer* aListItemDrawer,const CCoeControl* aParent,TInt aFlags = 0);
Second-phase construction of a list box.
These functions complete construction of this list box,
initialising its heap-stored members with the information provided by the
arguments. The functions invoke ConstructL(CCoeControl*,
TInt).
|
void ConstructL(MListBoxModel* aListBoxModel,CListItemDrawer* aListItemDrawer,const CCoeControl* aParent,TGulBorder aBorder,TInt aFlags = 0);
Second-phase construction of a list box with a border.
These functions complete construction of this list box,
initialising its heap-stored members with the information provided by the
arguments. The functions invoke ConstructL(CCoeControl*,
TInt).
The protected form is overridden non-virtually by the
second-phase constructors of each subclass, and should be invoked by them using
CEikListBox::ConstructL().
|
~CEikListBox();
Destructor. This frees any resources owned by this list box. If
EKeepModel was not specified, the list box model will also be
freed.
|
The following virtual functions are invoked by the constructors
of CEikListBox to build its fields and ready it for being
used.
TInt CalcHeightBasedOnNumOfItems(TInt aNumOfItems) const;
Gets the height of the list box based on the number of list box items. The height returned includes the list box margins, border and if present, the scroll bar frame.
|
|
TSize CalcSizeInPixels(TInt aWidthAsNumOfChars, TInt aHeightAsNumOfItems) const;
Gets the size of the list box in pixels based on the height of the list box in items.
|
|
TInt CalcWidthBasedOnNumOfChars(TInt aNumOfChars) const;
Gets the width of the list box in pixels based on the width of the list box in characters.
|
|
TInt CalcWidthBasedOnRequiredItemWidth(TInt aTextWidthInPixels) const;
Gets the width of the list box in pixels based on the width of the list box text in pixels.
|
|
void CalculatePopoutRect(TInt aTargetItemIndex, TInt aTargetYPos, TRect& aListBoxRect, TInt aMinHeightInNumOfItems = 1);
Gets the size of the rectangle required to display a pop out.
|
protected: virtual CListBoxView* MakeViewClassInstanceL();
Creates the list box view.
The function is called by ConstructL() to create
an instance of the appropriate list box view class for this list box. The
returned instance is owned by this object, and does not have to have its
second-phase constructor run. This function is called by
CreateViewL().
|
protected: virtual void CreateViewL();
Completes the list box view’s construction.
This function is called by ConstructL() to
complete construction of the resource view, calling its
ConstructL() with appropriate arguments and assigning it to
iView. Also prepares the view for use.
protected: void RestoreCommonListBoxPropertiesL(TResourceReader& aReader);
Restores the list box properties shared by all subclasses from
a resource reader. This function is not called within CEikListBox
itself, but is used by subclasses which support construction from
resources.
|
virtual void SetContainerWindowL(const CCoeControl& aContainer);
Sets this list box’s container. This enables drag events and pointer grab.
If the ECreateOwnWindow or EPopout
flags have been set, a window is first created for this control and this
control becomes a window-owning control. Pop-out list boxes’ windows
have backup set on them.
|
void SetLaunchingButton(CEikButtonBase* aButton);
Provides a call back mechanism to the button which just launched a popout menu.
|
|
MListBoxModel* Model() const;
Gets a pointer to the list box model.
|
CListBoxView* View() const;
Gets a pointer to the list box view.
|
|
These functions access the view of this list box (see
CListBoxView). The list box view must be instantiated before
any of these functions are called.
TInt TopItemIndex() const;
Gets the index number of the item at the top of the view.
|
virtual void SetTopItemIndex(TInt aItemIndex) const;
Sets which item is displayed at the top of the view. The view updates the scroll bar thumb to reflect this.
|
TInt BottomItemIndex() const;
Gets the index number of the item at the bottom of the view.
|
TInt CurrentItemIndex() const;
Gets the index number of the current item in the view.
|
void SetCurrentItemIndex(TInt aItemIndex) const;
Sets the current item, but does not redraw the list.
If the item was not previouly visible it is set to the top item in the view.
|
void SetCurrentItemIndexAndDraw(TInt aItemIndex) const;
Sets the current item and redraws the list. The list box view is scrolled so that the new current item is visible.
If the item was not previouly visible it is set to the top item in the view.
|
virtual void AdjustTopItemIndex() const;
Called by various functions of this class to ensure that the
top item index is always a sane value. The implementation in
CEikListBox tries to ensure the minimum amount of white space at
the bottom of the list box. Note that this function does not affect the current
item index.
|
const CListBoxView::CSelectionIndexArray* SelectionIndexes() const;
Gets the items which are currently selected.
|
void SetSelectionIndexesL(CListBoxView::CSelectionIndexArray* aArrayOfSelectionIndexes);
Sets a new list of items as selected.
|
|
List box objects need to be informed when data is added to or removed from their models. These functions may be used to update a list box’s internal state in response to changing data.
void HandleItemAdditionL();
Handles the addition of an item to the model.
This method should be called after one or more items have been
added to the model. Unlike HandleItemRemoval(), below, this
function redraws the list box and leaves the selection in a sensible state.
void HandleItemRemovalL();
Handles the removal of an item from the model.
This method should be called after one or more items have been removed from the model. It is then up to the application to make sure that the current item index is set to an appropriate value and to redraw the list box.
void Reset();
Resets the selection indices, top and current item indices, the selection, and the horizontal scroll offset of this list box. This function does not redraw the list box.
|
virtual void SetItemHeightL(TInt aHeight);
Sets the item height.
|
TInt ItemHeight() const;
Gets the item height in pixels.
|
|
protected: void UpdateScrollBarThumbs() const;
Updates the position of this list box’s scroll bars’ thumbs to reflect the horizontal and vertical position of the list view within the list.
void UpdateScrollBarsL();
Updates the size, span and thumb position of this list box’s scroll bars.
virtual TInt HorizScrollGranularityInPixels() const;
Gets the granularity for horizontal scrolls.
The granularity is the minimum size of a horizontal move of the client area.
|
virtual TInt HorizontalNudgeValue() const;
Gets the number of grains to move horizontally when a nudge button is tapped.
For simple list boxes, this value is a fraction of the width of the client area.
|
|
virtual void Draw(const TRect& aRect) const;
Redraws the specified area of this list box into the specified rectangle.
|
void DrawItem(TInt aItemIndex) const;
Draws a list box item, first scrolling the list to make it
visible if it is not already. DrawItem() panics if there is no
list box view currently set.
|
void ScrollToMakeItemVisible(TInt aItemIndex) const;
Makes an item visible in the list, scrolling it if necessary.
|
void DrawMatcherCursor() const;
Draws the matcher cursor in the correct location for the
current match. If there is no match buffer, this function returns immediately;
otherwise the cursor is drawn on the current item using
CListBoxView::DrawMatcherCursor() after scrolling to make the
current item visible.
A list box control’s matcher cursor is an on-screen
cursor which is drawn to indicate to the user the location of the current text.
Whether the cursor is drawn is dependent on the
CListBoxView::TFlags::EHasMatcherCursor flag, which may be set on
the list box’s view.
|
Uikon list boxes support observation of list box events using the
interface defined by MEikListBoxObserver.
void SetListBoxObserver(MEikListBoxObserver* aObserver);
Sets the list box observer. This observer receives future list box events from this list box.
|
virtual void ReportListBoxEventL(MEikListBoxObserver::TListBoxEvent aEvent);
Reports a list box event to any observer of this list box. This function returns immediately if no observer is set.
|
|
virtual TInt AdjustRectHeightToWholeNumberOfItems(TRect& aRect) const;
Rounds down the height of the rectangle (if necessary) so that only a whole number of items can be displayed inside the list box.
|
|
virtual void SizeChanged();
Updates the viewing rectangle of this control appropriately.
The function updates the viewing rectangle, and invokes
HandleViewRectSizeChangeL().
virtual void HandleViewRectSizeChangeL();
Handles a change in size of the viewing rectangle.
This function is called by framework functions to update the content, view, and scroll bars of this list box after the viewing rectangle has changed size. This implementation ensures that the current item is visible after a resize.
virtual void RestoreClientRectFromViewRect(TRect& aClientRect) const;
Calculates the client area.
This method is called by various functions of this class to
recalculate the extent of the client area from iViewRect. This
implementation takes into account any rounding of the viewing rectangle made to
fit a whole number of items.
|
|
virtual TInt CountComponentControls() const;
Gets a count of the component controls of this list box
control. This information is used for DrawNow().
|
virtual CCoeControl* ComponentControl(TInt aIndex) const;
Gets a pointer to the specified component control. This is used
for DrawNow().
|
|
|
TInt VerticalInterItemGap() const;
Gets the size of the vertical gap between items. This space is used by the view to allow a box to be drawn around each item.
|
protected: virtual void FocusChanged(TDrawNow aDrawNow);
Handles focus changes.
The function emphasises or de-emphasises the view as needed, and shows or hides the matcher cursor.
|
TBool ItemExists(TInt aItemIndex) const;
Tests whether an item exists.
|
|
|
OfferKeyEventL(), HandlePointerEventL()
and HandleScrollEventL() are implementations of interfaces defined
elsewhere. They are documented here for the sake of
completeness.
virtual TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType);
Handles key events.
|
|
virtual void HandlePointerEventL(const TPointerEvent& aPointerEvent);
Handles pointer events.
|
virtual void HandleDragEventL(TPoint aPointerPos);
Handles drag events.
This function is called by HandlePointerEventL()
to handle pointer drag events appropriately.
|
virtual void HandleScrollEventL(CEikScrollBar* aScrollBar,TEikScrollEvent aEventType);
Handles scroll bar events. These are passed by this list box’s scroll bars.
|
|
virtual TSize MinimumSize();
Gets the smallest area in which this list box can be completely displayed.
|
virtual void SetDimmed(TBool aDimmed);
Sets the list box dim state.
|
CEikScrollBarFrame* CreateScrollBarFrameL(TBool aPreAlloc=EFalse);
Creates a scroll bar frame.
If aPreAlloc is ETrue, any scroll
bars that the scroll bar frame may need are pre-allocated.
|
|
void EditItemL(TInt aMaxLength);
Creates an item editor and starts editing the current item
The editor can edit the current item up to a maximum length of
aMaxLength characters. Also reports an
EEventEditingStarted event to any list box observer by
default.
The function only creates a new editor if one does not already exist.
|
void GetColorUseListL(CArrayFix<TCoeColorUse>& aColorUseList) const;
Gets the list of logical colours employed in the drawing of the
control, paired with an explanation of how they are used. Appends the list to
aColorUseList.
|
virtual void HandleLeftArrowKeyL(CListBoxView::TSelectionMode aSelectionMode);
Handles a left arrow key event.
The method used to handle the event depends on the selection mode, e.g. whether the user has pressed the SHIFT or CONTROL key.
|
void HandleResourceChange(TInt aType);
Handles a change to the list box’s resources of type
aType which are shared across the environment, colours or fonts
for example.
|
virtual void HandleRightArrowKeyL(CListBoxView::TSelectionMode aSelectionMode);
Handles a right arrow key event.
The method used to handle the event depends on the selection mode, e.g. whether the user has pressed the SHIFT or CONTROL key.
|
TCoeInputCapabilities InputCapabilities() const;
Gets the list box’s input capabilities as set through the list box flags.
|
MEikListBoxEditor* ItemEditor();
Gets a pointer to the item editor. Does not imply transfer of ownership.
|
CEikScrollBarFrame* const ScrollBarFrame();
Gets a pointer to the scroll bar frame.
|
void SetItemEditor(MEikListBoxEditor* aEditor);
Sets the item editor. Ownership of the item editor is transferred to this class.
|
void StopEditingL( TBool aUpdateModel );
Stops editing and deletes the item editor.
The function reports an EEventEditingStopped event
to any list box observer, and updates the list box model if
aUpdateModel is ETrue.
|
|
TRgb BackColor() const;
Gets the background colour.
|
CMatchBuffer* Buffer() const;
Gets the list box match buffer.
|
void CheckCreateBufferL();
Checks the list box match buffer exists. If a buffer does not exist, one is created.
TBool CheckCreateExtension();
Checks for a list box extension, creates one if not present.
|
void CheckCreateExtensionL();
Checks for a list box extension, attempts to create one if not present.
This function leaves automatically if an extension cannot be created.
void SetReasonForFocusLostL(TReasonForFocusLost aReasonForFocusLost);
Sets the reason for the list box’s loss of focus.
This is required so the list box can determine whether loss of focus is due to an external control or an internal component.
|
TReasonForFocusLost ReasonForFocusLostL();
Gets the reason for the list box’s loss of focus.
|
void ClearMargins() const;
Clears the list box margins. The list box is redrawn only if redraws are enabled for the list box view.
void CreateMatchBufferL();
Creates a match buffer.
This is a utility function called from RestoreL()
of subclasses such as CEikTextListBox.
TInt HorizontalMargin() const;
Deprecated.
This function gets the horizontal margin. Use
CEikListBox::ListBoxMargins() instead, as this provides a more
accurate value due to the bit shifting involved.
|
TInt InterItemGap();
Gets the vertical gap between elements in the list box.
|
TBool IsMatchBuffer() const;
Tests whether the list box match buffer exists.
|
RIncrMatcherBase* MatchBuffer() const;
Gets a pointer to the match buffer. Returns NULL
if the match buffer does not exist.
|
void MatchTypedCharL(TUint aCode);
Searches the match buffer for a match to a typed character. Displays the item corresponding to the typed character if a match is found. No effect if no match is found.
|
void SetHorizontalMargin(TInt aMargin);
Sets the horizontal margin..
|
void SetVerticalMargin(TInt aMargin);
Sets the vertical margin to aMargin.
|
void SetViewRectFromClientRect(const TRect& aClientRect);
Sets the view rectangle from the client rectangle making sure a whole number of items is displayed.
|
void SimulateArrowKeyEventL(TKeyCode aKeyCode);
Simulates an arrow key event.
If the list box flags include EMultipleSelection,
this has the effect of pressing SHIFT with the arrow key represented by
aKeyCode. Calls CEikListBox::OfferKeyEventL() with
aKeyCode translated into a key event.
|
void UndoLastChar();
Removes one character from the matcher buffer, then finds the
first item which matches the new buffer, if any. Redraws the list box to
reflect the change. This should not be called from within another
Draw() function.
void UpdateCurrentItem(TInt aItemIndex) const;
Sets an item as the current item, even if it is not currently
visible. Redraws the list box to reflect the change. This should not be called
from within another Draw function.
|
void UpdateItemDrawerColors();
Updates the item drawer colours in line with the colours in effect for the Uikon environment. Has no effect if there is no item drawer.
void UpdateViewColors();
Updates the view colours in line with the colours in effect for the Uikon environment. Has no effect if there is no view.
TInt VerticalMargin() const;
Deprecated.
This function gets the vertical margin. This function is
deprecated, use CEikListBox::ListBoxMargins() instead, this
provides a more accurate value due to the bit shifting involved.
|
TMargins8 ListBoxMargins() const
Gets list box margins.
|
TInt ViewRectHeightAdjustment() const;
Gets the view rectangle height adjustment.
These are the adjustments that were made to the view rectangle
when the SetViewRectFromClientRect() function was called.
|
|
TFlags
Construction flags.
The aFlags argument of
CEikListBox::ConstructL() is formed from an ORed combination of
the following flag values:
|
|
Miscellaneous constants.
|
|
The following data members are declared as
protected:, and may be accessed from subclasses of
CEikListBox.
TInt iRequiredHeightInNumOfItems
The required height of this list box expressed in terms of a
number of items. This field is used only by subclasses and by
CEikListBox::MinimumSize().
CListBoxView* iView
This list box’s view.
Copyright ©2002 Symbian Ltd. 6.1-00174 |
|
![[Top]](../../../stock/arrow_up_2.gif){kind=icon}
![[Top]](../../../stock/arrow_up.gif){kind=icon}