CListBoxView Class Reference

The items which are selected within a list box list.

Cursor movement flags.

These describe the cursor movements recognised by MoveCursorL().

Enumerator:

ECursorNextItem	Cursors movement to next item.
ECursorPreviousItem	Cursors movement to previous item.
ECursorNextColumn	Cursors movement to next column.
ECursorPreviousColumn	Cursors movement to previous column.
ECursorPreviousPage	Cursors movement to previous page.
ECursorNextPage	Cursors movement to next page.
ECursorFirstItem	Cursors movement to the first item.
ECursorLastItem	Cursors movement to the last item.
ECursorNextScreen	Cursors movement to the next screen.
ECursorPrevScreen	Cursors movement to the previous screen.

List box view flags.

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

Enumerator:

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.
EPaintedSelection	If set, selected items are painted.
EMarkSelection	Item marking enabled.
EUnmarkSelection	Item unmarking enabled.
EItemCountModified	Item count changes enabled.

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 phone due to the wide range of possible input devices. The following description assumes a phone with a pointer and a keyboard.

Enumerator:

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.
EDisjointMarkSelection	Any single item in the list may be removed from the selection by an action, when unselecting for example.
EPenMultiselection	Multiple items can be added to the selection array by an action, when selecting with the edit key for example.
EChangeMarkMode	Mark mode is changed to EUnmarkSelection if item is marked or EMarkSelection if item is not marked by an action, when selecting or unselecting item for example.

Destructor.

C++ default constructor.

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

Gets the background colour for this view.

Returns:

The background colour.

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

Returns:

Index of the item at the bottom of this view.

Recalculates the index of the bottom item in the list by using 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.

Reimplemented in CAknGridView, CAknColumnListBoxView, CColumnListBoxView, CFormattedCellListBoxView, and CSnakingListBoxView.

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.

Reimplemented in CAknGridView, and CSnakingListBoxView.

Calculates which item should be selected in order to make a particular item visible.

Calling VScrollTo(CalcNewTopItemIndexSoItemIsVisible(idx)), for example, would make the item whose index is idx visible.

Parameters:

aItemIndex

The index of the new top item.

Returns:

The item to be selected.

Reimplemented in CAknGridView, and CSnakingListBoxView.

Clears this view’s flags according to a bitmask.

These flags are defined by the nested enum TFlags (below).

Parameters:

aMask

Flags to be removed.

Resets the selection state so that there is nothing selected.

Panic:

EEikPanicListBoxNoSelIndexArray Panics if selection indexes have not been defined for this class.

Resets the anchor index, the active end and the EAnchorExists flag.

By default Symbian 2nd phase constructor is private.

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:

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

Gets the current item’s index.

Returns:

Index number of the current item.

Reimplemented in CAknGridView.

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

Returns:

Data width in pixels.

Deselects an item by index.

Parameters:

aItemIndex

Item to deselect.

Panic:

EEikPanicListBoxNoSelIndexArray Panics if selection indexes have not been defined for this class.

Deselects range between given indexes.

Deprecated:

Parameters:

	aItemIndex1	First index of selectable range.
	aItemIndex2	Second index of selectable range.

Disables vertical line drawing.

Parameters:

aDisable

ETrue if disabled.

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:

aClipRect

The rectangle to draw into, this is ignored. Default value is NULL.

Panic:

EEikPanicListBoxNoModel Panics if the list box model for this class has not been defined.

Reimplemented in CAknGMSStyleGridView, CAknGridView, CSingleHeadingStyleView, CColumnListBoxView, CFormattedCellListBoxView, CSnakingListBoxView, and CSettingsListBoxView.

Not implemented.

Parameters:

aClientRect

Not used.

Reimplemented in CAknColumnListBoxView, CAknSetStyleListBoxView, CSingleHeadingStyleView, and CFormattedCellListBoxView.

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

Parameters:

aItemIndex

Index number of the item to draw.

Reimplemented in CAknGridView, and CSettingsListBoxView.

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

This is deprecated and broken and should not be used.

Deprecated:

Reimplemented in CAknGridView.

Gets an empty list box text.

Returns:

Pointer the empty list box text.

Gets this view’s flags.

These flags are defined by the nested enum TFlags (below).

Returns:

List box's flags.

Gets a copy of the array of currently selected items.

Parameters:

[in,out]

aSelectionArray

An instantiated CSelectionIndexArray. On return, contains a copy of selection indexes.

Panic:

EEikPanicListBoxInvalidSelIndexArraySpecified Panics if the given selection index array is not valid.

Panic:

EEikPanicListBoxNoSelIndexArray Panics if selection indexes have not been defined for this class.

Hides the matcher cursor.

Deprecated:

Scrolls horizontally by the specified number of pixels.

Parameters:

aHScrollAmount

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

Reimplemented in CSnakingListBoxView.

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

Returns:

The horizontal scroll offset in pixels.

Tests if this view is visible.

Returns:

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

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

Returns:

Pointer to the list box item drawer.

Reimplemented in CSettingsListBoxView.

Tests whether an item is selected.

Parameters:

aItemIndex

Index of item to test.

Returns:

ETrue if the item is selected.

Tests whether an item is visible.

Parameters:

aItemIndex

Index of item to be tested.

Returns:

ETrue if the item is visible.

Gets the on-screen position of an item.

Parameters:

aItemIndex

Index of an item.

Returns:

Position of the item.

Reimplemented in CAknGridView, and CSnakingListBoxView.

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:

aItemIndex

Index of an item. Default value is 0.

Returns:

Size of the item.

Reimplemented in CAknGridView, and CSnakingListBoxView.

Gets the match cursor’s position.

Deprecated:

Returns:

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

Moves the current item cursor in the specified direction.

This function is called by CEikListBox in response to user input.

Parameters:

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

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

Parameters:

aRect

The rectangle.

Returns:

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

Reimplemented in CSnakingListBoxView.

Tests whether redraw is disabled.

Returns:

ETrue if redraw is disabled.

Scrolls vertically to make a particular item visible.

Parameters:

aItemIndex

The item to make visible.

Returns:

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

Reimplemented in CAknGridView, and CSnakingListBoxView.

Gets a pointer to the selection list of this view.

Returns:

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

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:

aItemIndex

Item to select.

Panic:

EEikPanicListBoxNoSelIndexArray Panics if selection indexes have not been defined for this class.

Selects items between given indexes.

Deprecated:

Parameters:

	aItemIndex1	First index of selectable range.
	aItemIndex2	Second index of selectable range.

Sets the anchor to the specified item.

Parameters:

aItemIndex

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

Sets the background colour.

Parameters:

aColor

The background colour.

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:

aItemIndex

Which item to make current.

Panic:

EEikPanicListBoxInvalidCurrentItemIndexSpecified Panics if the given index is not valid.

Sets whether items will be drawn dimmed.

The function sets or resets the dim flag.

Parameters:

aDimmed

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

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:

aDisableRedraw

Disables redraw if ETrue.

Sets whether or not items are drawn as emphasised.

The function sets or resets the emphasised flag.

Parameters:

aEmphasized

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

Sets this view’s flags according to a bitmask.

These flags are defined by the nested enum TFlags (below).

Parameters:

aMask

Sets new flags for the list box.

Sets the horizontal scroll offset in pixels.

Parameters:

aHorizontalOffset

New value for the horizontal scroll offset, in pixels.

Sets the item height.

Parameters:

aItemHeight

New item height.

Reimplemented in CAknGridView, and CSnakingListBoxView.

Sets list box backroung text.

This text is visible if the list box has no items.

Parameters:

aText

The text for the empty list box background.

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

Deprecated:

Parameters:

aMatcherCursor

If ETrue, the view will draw match cursor.

Sets the match cursor’s colour.

Deprecated:

Parameters:

aColor

Colour in which to display the incremental match cursor.

Sets the match cursor's position.

Deprecated:

Parameters:

aPosWithinCurrentItem

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

Sets the painted selection flag.

Deprecated:

Parameters:

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.

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

Parameters:

aSelectionIndexes

Items to select.

Panic:

EEikPanicListBoxInvalidSelIndexArraySpecified Panics if the given selection index array is not valid.

Sets the colour in which to display text.

Parameters:

aColor

Colour in which to display text.

Sets the item at the top of the view by its index in the list of all items.

This function also invokes CalcBottomItemIndex().

Parameters:

aItemIndex

Index of the item to start the view at.

Panic:

EEikPanicListBoxInvalidTopItemIndexSpecified Panics if the given index is not valid.

Reimplemented in CAknGridView, and CSnakingListBoxView.

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

Parameters:

aRect

New view rectangle.

Sets the visibility observer.

Parameters:

aObserver

New visibility observer for this control.

Gets the colour in which text is to be displayed.

Returns:

Current text colour.

Toggles the selection of an item.

Parameters:

aItemIndex

Item to toggle.

Panic:

EEikPanicListBoxNoSelIndexArray Panics if selection indexes have not been defined for this class.

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

Returns:

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

Updates item selection.

Parameters:

aSelectionMode

The selection mode.

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

Parameters:

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

Gets the list box’s view rectangle.

Returns:

This list box’s view rectangle.

Gets the visible width of the specified rectangle in pixels.

This function is called by CListBoxView itself on its own viewing rectangle.

Parameters:

aRect

The rectangle to get the visible width for.

Returns:

Visible width of aRect.

Reimplemented in CAknGridView, and CSnakingListBoxView.

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:

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

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

Parameters:

aNewTopItemIndex

The item to scroll to.

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:

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

Returns:

ETrue if there was an item at aPosition.

Reimplemented in CAknGridView, and CSnakingListBoxView.

List box base class.

To access SetFlags()/ClearFlags().

Index of the item at the bottom of the view.

This is not necessarily the item at the end of the list.

Index of the current item.

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

Indicates whether vertical line drawing is disabled.

The flags for this list box.

These flags are defined by the nested enum TFlags (below).

Graphics context for the control.

The window group of this view.

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

This view’s item drawer.

Not owned.

Height of each item in the list in pixels.

The empty list text.

This view’s model.

Not owned.

Index of the item at the top of the view.

This is not necessarily the item at the start of the list.

Graphics context for the control.

This list box view’s window.