Class CListBoxView

CListBoxView

Support

Supported from 6.0

Description

List box view.

A list box view displays the list items which are currently visible in a list box. List box views draw each of the items for display using methods defined in their associated list box drawer.

Together with its list item drawer, a CListBoxView encapsulates the on-screen appearance of data in a list box.

List box views also encapsulate item selection, the current item, and the fundamentals of how the selection and the current item are updated according to user input. Input events themselves are handled by CEikListBox, which calls member functions of CListBoxView appropriately.

This class is sufficient for plain list box views, and may be derived from in order to provide more complex list views. Uikon supplies and uses the classes CHierarchicalListBoxView and CSnakingListBoxView, which provide two kinds of indented list views.

Derivation

CBase Base class for all classes to be instantiated on the heap CListBoxView List box view

Defined in CListBoxView:
BackColor(), BottomItemIndex(), CListBoxView(), CSelectionIndexArray, CalcBottomItemIndex(), CalcDataWidth(), CalcNewTopItemIndexSoItemIsVisible(), ClearFlags(), ClearSelection(), ClearSelectionAnchorAndActiveIndex(), ConstructL(), CurrentItemIndex(), DataWidth(), DeselectItem(), Draw(), DrawItem(), DrawMatcherCursor(), EAnchorExists, EContiguousSelection, ECursorFirstItem, ECursorLastItem, ECursorNextColumn, ECursorNextItem, ECursorNextPage, ECursorPreviousColumn, ECursorPreviousItem, ECursorPreviousPage, EDimmed, EDisableRedraw, EDisjointSelection, EEmphasized, EHasMatcherCursor, ENoSelection, ESingleSelection, Flags(), GetSelectionIndexesL(), HScroll(), HScrollOffset(), HideMatcherCursor(), IsVisible(), ItemDrawer(), ItemIsSelected(), ItemIsVisible(), ItemPos(), ItemSize(), MatcherCursorPos(), MoveCursorL(), NumberOfItemsThatFitInRect(), RedrawDisabled(), ScrollToMakeItemVisible(), SelectItemL(), SelectRangeL(), SelectionIndexes(), SetAnchor(), SetBackColor(), SetCurrentItemIndex(), SetDimmed(), SetDisableRedraw(), SetEmphasized(), SetFlags(), SetHScrollOffset(), SetItemHeight(), SetMatcherCursor(), SetMatcherCursorColor(), SetMatcherCursorPos(), SetPaintedSelection(), SetSelectionIndexesL(), SetTextColor(), SetTopItemIndex(), SetViewRect(), SetVisibilityObserver(), TCursorMovement, TFlags, TSelectionMode, TextColor(), ToggleItemL(), TopItemIndex(), UpdateSelectionL(), VScrollTo(), VerticalMoveToItemL(), ViewRect(), VisibleWidth(), XYPosToItemIndex(), iBottomItemIndex, iCurrentItemIndex, iDataWidth, iFlags, iGc, iGroupWin, iHScrollOffset, iItemDrawer, iItemHeight, iModel, iTopItemIndex, iViewRect, iWin, ~CListBoxView()

Inherited from CBase:
operator new()

See also:

• CListItemDrawer
• CEikListBox

CListBoxView();

Description

Default constructor.

Allocates an area of memory for a CListBoxView, and begins its initialisation.

virtual void ConstructL
    (MListBoxModel* aListBoxModel,
     CListItemDrawer* aItemDrawer,
     CWsScreenDevice* aScreen,
     RWindowGroup* aGroupWin,
     RWindow* aWsWindow,
     const TRect& aDisplayArea,
     TInt aItemHeight);

Description

Second-phase constructor.

This function completes the initialisation of a default-constructed list box view. The item drawer’s graphics context is created on aScreen, and the list item drawer’s graphics context is set to this. See CListItemDrawer::SetGc().

Parameters

MListBoxModel* aListBoxModel The list box model to use. CListItemDrawer* aItemDrawer A default-constructed item drawer. CWsScreenDevice* aScreen Screen on which to display. RWindowGroup* aGroupWin This list box view’s window group. RWindow* aWsWindow Window for this view. const TRect& aDisplayArea The viewing rectangle this list box view is to use. TInt aItemHeight Height of a single list item.

~CListBoxView();

Description

Destructor.

The destructor destroys this list box view, its item drawer, its graphics context and its selection list.

Description

One item, usually visible in the view, is current at any time. Moving the current item in a list box control may also change the box’s selection state: see TSelectionMode below.

TInt CurrentItemIndex() const;

Description

Gets the current item’s index.

Return value

TInt Index number of the current item.

virtual void MoveCursorL(TCursorMovement aCursorMovement,TSelectionMode aSelectionMode);

Description

Moves the current item cursor in the specified direction. This function is called by CEikListBox in response to user input.

Parameters

TCursorMovement aCursorMovement The cursor movement to apply. TSelectionMode aSelectionMode The selection mode of the calling list box.

void VerticalMoveToItemL(TInt aTargetItemIndex, TSelectionMode aSelectionMode);

Description

Moves to the specified item, sets it as the current item and scrolls the display to make the item visible.

Parameters

TInt aTargetItemIndex The index of the item to which to move. TSelectionMode aSelectionMode The selection mode.

void SetCurrentItemIndex(TInt aItemIndex);

Description

Set the index of the current item. This function changes the current item, but does not redraw the list view or update the selection.

Parameters

TInt aItemIndex Which item to make current.

Description

Multiple items can be selected in a list box at a time if the appropriate flags are set.

const CSelectionIndexArray* SelectionIndexes() const;

Description

Gets a pointer to the selection list of this view.

Return value

CSelectionIndexArray* Pointer to an array describing the items in the list which are currently selected. The object pointed to is owned by the CListBoxView.

See also:

• ~CListBoxView()

void GetSelectionIndexesL(CSelectionIndexArray* aSelectionArray) const;

Description

Gets a copy of the array of currently selected items.

Parameters

CSelectionIndexArray* aSelectionArray An instantiated CSelectionIndexArray. On return, contains a copy of SelectionIndexes().

See also:

• SelectionIndexes()

void SetSelectionIndexesL
    (const CSelectionIndexArray* aSelectionIndexes);

Description

Sets the currently selected items of this view from a selection index array.

Parameters

const CSelectionIndexArray* aSelectionIndexes Items to select.

void ClearSelection();

Description

Resets the selection state so that there is nothing selected.

void ToggleItemL(TInt aItemIndex);

Description

Toggles the selection of an item.

Parameters

TInt aItemIndex Item to toggle.

void SelectItemL(TInt aItemIndex);

Description

Selects an item by index.

This function leaves if memory could not be allocated for an extra item in the array of selected items.

Parameters

TInt aItemIndex Item to select.

void DeselectItem(TInt aItemIndex);

Description

Deselects an item by index.

Parameters

TInt aItemIndex Item to deselect.

void SelectRangeL(TInt aItemIndex1, TInt aItemIndex2);

Description

Selects all items in the list between the two specified indices, inclusively.

Parameters

TInt aItemIndex1 One end of the range to select. TInt aItemIndex2 The other end of the range to select.

Description

The view rectangle is the area of the host window in which the items are drawn.

TRect ViewRect() const;

Description

Gets the list box’s view rectangle.

Return value

TRect This list box view’s viewing rectangle.

void SetViewRect(const TRect& aRect);

Description

Sets the area within the list window in which the view can draw itself.

Parameters

const TRect& aRect New viewing rectangle.

Description

Miscellaneous access functions for the main attributes.

TInt TopItemIndex() const;

Description

Gets the index of the item at the top of the view.

Return value

TInt The item currently displayed at the top of this list box view.

virtual void SetTopItemIndex(TInt aItemIndex);

Description

Sets the item at the top of the view by its index in the list of all items. This function also invokes CalcBottomItemIndex().

Parameters

TInt aItemIndex Index of the item to start the view at.

TInt BottomItemIndex() const;

Description

Gets the index of the item at the bottom of this view.

Return value

TInt Index of the item at the bottom of this view.

virtual void CalcBottomItemIndex();

Description

Recalculates the index of the bottom item in the list from the top item index and the size of the display.

This function is called by the owning list box control when either the size of the list box or the number of items in its model changes.

virtual void SetItemHeight(TInt aItemHeight);

Description

Sets the item height.

Parameters

TInt aItemHeight New item height.

void SetCurrentItemIndex(TInt aItemIndex);

Description

Sets the item at the specified index to be the current item. The function panics if the specified item index is not valid.

Parameters

TInt aItemIndex The position of the item to set as the current item.

void ClearSelectionAnchorAndActiveIndex();

Description

Sets the anchor index and active end index to NULL, clears the EAnchorExists flag.

void SetAnchor(TInt aItemIndex);

Description

Sets the anchor to the specified item.

Parameters

TInt aItemIndex The index of the item at which the anchor is set.

const CSelectionIndexArray* SelectionIndexes() const;

Description

Gets the selection index array.

Return value

CSelectionIndexArray* The selection index array.

void SetBackColor(TRgb aColor);

Description

Sets the background colour.

Parameters

TRgb aColor The background colour.

void SetPaintedSelection( TBool aPaintedSelection );

Description

Sets the painted selection flag.

Parameters

TBool aPaintedSelection If ETrue the painted selection flag is set on.If EFalse the selection flag is set off.If NULL the painted selection flag is cleared.

void SetTextColor(TRgb aColor);

Description

Sets the colour in which to display text.

Parameters

TRgb aColor Colour in which to display text.

TRgb TextColor() const;

Description

Gets the colour in which text is to be displayed.

Return value

TRgb Current text colour.

virtual void UpdateSelectionL(TSelectionMode aSelectionMode);

Description

Updates item selection.

Parameters

TSelectionMode aSelectionMode The selection mode.

Description

Functions for getting and setting information about the state of the incremental match cursor in this view. Pixel-level positioning of the matching cursor is implemented in a list box’s item drawer (see CListItemDrawer).

void SetMatcherCursorColor(TRgb aColor);

Description

Sets the match cursor’s colour.

Parameters

TRgb aColor Colour in which to display the incremental match cursor.

void SetMatcherCursorPos(TInt aPosWithinCurrentItem);

Description

Sets the match cursor’s position.

Parameters

TInt aPosWithinCurrentItem Character position for the match cursor within the current item’s string.

TInt MatcherCursorPos() const;

Description

Gets the match cursor’s position.

Return value

TInt Character position of the match cursor within the current item’s string.

void DrawMatcherCursor();

Description

Draws the match cursor in its current screen position if the matcher cursor flag has been set.

void HideMatcherCursor();

Description

Hides the match cursor.

void SetMatcherCursor(TBool aMatcherCursor);

Description

Sets or resets the matcher cursor flag to specify whether the match cursor is drawn.

Parameters

TBool aMatcherCursor If ETrue, this view will draw match cursors. If EFalse will not draw match cursors.

void SetEmphasized(TBool aEmphasized);

Description

Sets whether or not items are drawn emphasised.

The function sets or resets the emphasised flag.

Parameters

TBool aEmphasized If ETrue, this view will draw items emphasised. If EFalse will not draw items emphasised.

void SetDimmed(TBool aDimmed);

Description

Sets whether or not items will be drawn dimmed.

The function sets or resets the dim flag.

Parameters

TBool aDimmed If ETrue, this view will draw items dimmed. If EFalse will not draw items dimmed.

void SetDisableRedraw(TBool aDisableRedraw);

Description

Disables or enables redraws.

If this flag is set to ETrue, all member functions which draw items will return immediately without drawing anything. Functions which update the internal state of the list box will still work, but nothing will be drawn or updated on the screen.

Parameters

TBool aDisableRedraw Disables redraw if ETrue.

TBool RedrawDisabled() const;

Description

Tests whether redraw is disabled.

Return value

TBool ETrue if redraw is disabled.

Description

Vertical scrolling is measured in numbers of items.

void VScrollTo(TInt aNewTopItemIndex);

Description

Scroll vertically to the specified item. Scrolls the contents of this list view so that the specified item is the top item, and redraws the view.

Parameters

TInt aNewTopItemIndex The item to scroll to.

void VScrollTo(TInt aNewTopItemIndex, TRect& aMinRedrawRect);

Description

Scroll vertically to the specified item and get the minimum rectangle to redraw. Scrolls the contents of this list view so that the specified item is the top item, and redraws the view.

This two argument version returns the area which needs redrawing via aMinRedrawRect&.

Parameters

TInt aNewTopItemIndex The item to scroll to. TRect& aMinRedrawRect On return, the minimum rectangle to redraw.

virtual TBool ScrollToMakeItemVisible(TInt aItemIndex);

Description

Scrolls vertically to make a particular item visible.

Parameters

TInt aItemIndex The item to make visible.

Return value

TBool ETrue if any scrolling was done, EFalse if no scrolling was necessary.

See also:

• CalcNewTopItemIndexSoItemIsVisible()
• VScrollTo()

void VScrollTo(TInt aNewTopItemIndex);

Description

Sets the index of the item to be the top item.

Parameters

TInt aNewTopItemIndex The item to scroll to.

void VScrollTo(TInt aNewTopItemIndex,TRect& aMinRedrawRect);

Description

Sets the index of the item to be the top item.

This two argument version returns the area which needs redrawing via aMinRedrawRect&. This function does not perform the redraw.

Parameters

TInt aNewTopItemIndex The distance by which to scroll. TRect& aMinRedrawRect On return, the minimum rectangle to redraw.

Description

Horizontal scrolling is measured in pixels.

virtual void HScroll(TInt aHScrollAmount);

Description

Scrolls horizontally by the specified number of pixels.

Parameters

TInt aHScrollAmount The distance to scroll by in pixels. A negative value scrolls to the left, a positive value scrolls to the right.

TInt HScrollOffset() const;

Description

Gets the offset of the visible portion of the data from the left margin in pixels.

Return value

TInt The horizontal scroll offset in pixels.

void SetHScrollOffset(TInt aHorizontalOffset);

Description

Sets the horizontal scroll offset in pixels.

Parameters

TInt aHorizontalOffset New value for the horizontal scroll offset, in pixels.

TInt DataWidth() const;

Description

Gets the width of the widest item in the list in pixels.

Return value

TInt Data width in pixels.

virtual void CalcDataWidth();

Description

Recalculates the data width of this list box view from the item width of its list item drawer. This method is called directly by CEikListBox when the list box’s size changes or when data is added.

See also:

• CListItemDrawer::ItemWidthInPixels()
• iDataWidth

virtual TInt VisibleWidth(const TRect& aRect) const;

Description

Gets the visible width of the specified rectangle in pixels. This function is called by CListBoxView itself on its own viewing rectangle.

Parameters

const TRect& aRect The rectangle to get the visible width for.

Return value

TInt Visible width of aRect.

virtual TInt CalcNewTopItemIndexSoItemIsVisible(TInt aItemIndex) const;

Description

Calculates which item should be scrolled to in order to make a particular item visible. Calling VScrollTo(CalcNewTopItemIndexSoItemIsVisible(idx)), for example, would make the item whose index is idx visible.

Parameters

TInt aItemIndex The index of the new top item.

Return value

TInt The item to scroll to.

Description

Methods for drawing the items in the list box view.

virtual void Draw(const TRect* aClipRect = NULL) const;

Description

Draws every visible item into the specified rectangle.

As implemented in CListBoxView, this function's argument is ignored and the internal viewing rectangle is used. See SetViewRect().

Parameters

const TRect* aClipRect = NULL The rectangle to draw into, this is ignored.

virtual void DrawItem(TInt aItemIndex) const;

Description

Draws the specified item via CListBoxDrawer::DrawItem() if it is visible.

Parameters

TInt aItemIndex Index number of the item to draw.

Description

Functions for querying an item’s position and size, selection status, and visibility status.

virtual TBool XYPosToItemIndex(TPoint aPosition,TInt& aItemIndex) const;

Description

Converts a pixel position into an item index.

The function returns ETrue and sets aItemIndex to the index of the item whose bounding box contains aPosition. Returns EFalse if no such item exists.

Parameters

TPoint aPosition A position relative to the origin of the list box control. TInt& aItemIndex Is set to the item at that position.

Return value

TBool Whether there was an item at aPosition.

TBool ItemIsSelected(TInt aItemIndex) const;

Description

Tests whether an item is selected.

Parameters

TInt aItemIndex Index of item to test.

Return value

TBool ETrue if the item is selected.

TBool ItemIsVisible(TInt aItemIndex) const;

Description

Tests whether an item is visible.

Parameters

TInt aItemIndex Index of item to test.

Return value

TBool ETrue if the item is visible.

virtual TPoint ItemPos(TInt aItemIndex) const;

Description

Gets the on-screen position of an item.

Parameters

TInt aItemIndex Index of an item.

Return value

TPoint Position of the item.

virtual TSize ItemSize(TInt aItemIndex=0) const;

Description

Gets the on-screen size of an item.

As implemented in CListBoxView, all items report the same size. The size returned may be larger than the width of the list box view, but will not be smaller.

Parameters

TInt aItemIndex=0 Index of an item.

Return value

TSize Size of the item.

TInt NumberOfItemsThatFitInRect (const Trect& aRect);

Description

Gets the number of items that will fit into a given rectangle.

Parameters

const Trect& aRect The rectangle.

Return value

TInt The number of items that will fit into the given rectangle.

void SetVisibilityObserver(MListVisibilityObserver* aObserver);

Description

Sets the visibility observer.

Parameters

MListVisibilityObserver* aObserver New visibility observer for this control.

TBool IsVisible() const;

Description

Tests if this view is visible.

Return value

TBool ETrue if this view is visible. EFalse if this view is not visible, or does not exist.

CListItemDrawer* ItemDrawer() const;

Description

Gets the object used by this list box view to draw its items.

Return value

CListItemDrawer* Pointer to the list box viewer.

TRgb BackColor() const;

Description

Gets the background colour for this view.

Return value

TRgb The background colour.

protected: TInt Flags() const;

Description

Gets this view’s flags.

Return value

TInt An OR-ed combination of TFlags.

protected: void SetFlags(TInt aMask);

Description

Sets this view’s flags according to a bitmask.

Parameters

TInt aMask An OR-ed combination of TFlags.

protected: void ClearFlags(TInt aMask);

Description

Clears this view’s flags according to a bitmask.

Parameters

TInt aMask An OR-ed combination of TFlags.

Description

The following protected member data may be accessed by classes derived from CListBoxView, or through the member functions above. Private data members are not documented.

TInt iFlags

Description

The flags for this list box; these flags are defined by the nested enum TFlags (below).

CListItemDrawer* iItemDrawer

Description

This view’s item drawer (not owned).

MListBoxModel* iModel

Description

This view’s model (not owned).

TInt iDataWidth

Description

Width (in pixels) of the longest item in the model.

TInt iTopItemIndex

Description

Index of the item at the top of the view. This is not necessarily the item at the start of the list.

TInt iBottomItemIndex

Description

Index of the item at the bottom of the view. This is not necessarily the item at the end of the list.

TInt iHScrollOffset

Description

Pixel offset of the visible portion of the data from the left margin.

TInt iCurrentItemIndex

Description

Index of the current item.

TInt iItemHeight

Description

Height of each item in the list in pixels.

RWindow* iWin

Description

This list box view’s window.

RWindowGroup* iGroupWin

Description

The window group of this view.

CWindowGc* iGc

Description

Graphics context for the control.

TRect iViewRect

Description

Control’s viewing rectangle.

enum TSelectionMode;

Description

Modes for modifying the selection.

Changing the current item of a list box view may also affect which items are selected. The selection mode of such an action describes how (or if) the selection is altered by the action.

Each function of CListBoxView which affects the current item is passed an appropriate selection mode by the calling input handler method of CEikListBox. The mode is varied according to the keyboard modifiers held down by the user, or whether a pointer action was a tap or a sweep.

Note that the behaviour of list box views may vary with the target platform due to the wide range of possible input devices. The following description assumes a device with a pointer and a keyboard.

ENoSelection The selection is not changed by actions while this is in effect, holding CTRL while pressing cursor up or down for example. ESingleSelection Only a single item in the list is allowed to be selected by an action; when selecting individual items with the pointer, or moving using the cursor keys without any modifiers for example. EContiguousSelection A single continuous run of items can be added to the selection array by an action, when keyboard-selecting with the shift key held down, or when sweeping a selection with the pointer for example. EDisjointSelection Any single item in the list may be added to the selection by an action, when selecting or drag-selecting with the pointer when the CTRL key is held down for example.

enum TCursorMovement;

Description

Cursor movement flags. These describe the cursor movements recognised by MoveCursorL().

ECursorNextItem Next item. ECursorPreviousItem Previous item. ECursorNextColumn Next column. ECursorPreviousColumn Previous. column. ECursorPreviousPage Previous page. ECursorNextPage Next page. ECursorFirstItem To the first item. ECursorLastItem To the last item.

enum TFlags;

Description

List box view flags

These flags may be combined with a logical OR to get a combination of effects.

EAnchorExists A selection anchor exists. EEmphasized The view is emphasised. EDimmed The view is dimmed. EHasMatcherCursor List box view has a cursor for incremental matching. EDisableRedraw Redraw is disabled.

typedef CArrayFix<TInt> CSelectionIndexArray;

Description

The items which are selected within a list box list.