#include <mw/eiklbv.h>
| class CListBoxView : public CBase |
| Public Member Type Definitions | |
|---|---|
| typedef | CArrayFix< TInt > CSelectionIndexArray |
| Protected Attributes | |
|---|---|
| TInt | iBottomItemIndex |
| TInt | iCurrentItemIndex |
| TInt | iDataWidth |
| TBool | iDisableVerticalLineDrawing |
| CListBoxViewExtension * | iExtension |
| TInt | iFlags |
| CWindowGc * | iGc |
| RWindowGroup * | iGroupWin |
| TInt | iHScrollOffset |
| CListItemDrawer * | iItemDrawer |
| TInt | iItemHeight |
| HBufC * | iListEmptyText |
| MListBoxModel * | iModel |
| TInt | iSpare |
| TInt | iTopItemIndex |
| TInt | iVerticalOffset |
| TRect | iViewRect |
| RWindow * | iWin |
| Public Member Enumerations | |
|---|---|
| enum | TCursorMovement { ECursorNextItem, ECursorPreviousItem, ECursorNextColumn, ECursorPreviousColumn, ..., ECursorPrevScreen } |
| enum | TFlags { EAnchorExists, EEmphasized, EDimmed, EHasMatcherCursor, ..., EOffsetChanged } |
| enum | TSelectionMode { ENoSelection, ESingleSelection, EContiguousSelection, EDisjointSelection, ..., EChangeMarkMode } |
| Protected Member Functions | |
|---|---|
| void | ClearFlags(TInt) |
| TInt | Flags() |
| IMPORT_C void | SelectRangeL(TInt, TInt) |
| void | SetFlags(TInt) |
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. TechView supplies and uses the classes CHierarchicalListBoxView and CSnakingListBoxView, which provide two kinds of indented list views.
| TInt | iBottomItemIndex | [protected] |
Index of the item at the bottom of the view. This is not necessarily the item at the end of the list.
| TBool | iDisableVerticalLineDrawing | [protected] |
Indicates whether vertical line drawing is disabled.
| TInt | iFlags | [protected] |
The flags for this list box. These flags are defined by the nested enum TFlags (below).
| TInt | iHScrollOffset | [protected] |
Pixel offset of the visible portion of the data from the left margin.
| TInt | iTopItemIndex | [protected] |
Index of the item at the top of the view. This is not necessarily the item at the start of the list.
Cursor movement flags. These describe the cursor movements recognised by MoveCursorL().
List box view flags.
These flags may be combined with a logical OR to get a combination of effects.
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.
| IMPORT_C | CListBoxView | ( | ) |
C++ default constructor.
Allocates an area of memory for a CListBoxView, and begins its initialisation.
| IMPORT_C TRgb | BackColor | ( | ) | const |
Gets the background colour for this view.
Returns: The background colour.
| IMPORT_C TInt | BottomItemIndex | ( | ) | const |
Gets the index of the item at the bottom of this view.
Returns: Index of the item at the bottom of this view.
| IMPORT_C void | CalcBottomItemIndex | ( | ) | [virtual] |
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.
| IMPORT_C void | CalcDataWidth | ( | ) | [virtual] |
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.
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.
| Parameter | Description |
|---|---|
| aItemIndex | The index of the new top item. |
Returns: The item to be selected.
| void | ClearFlags | ( | TInt | aMask | ) | [protected, inline] |
Clears this view s flags according to a bitmask.
These flags are defined by the nested enum TFlags (below).
| Parameter | Description |
|---|---|
| aMask | Flags to be removed. |
| IMPORT_C void | ClearSelection | ( | ) |
Resets the selection state so that there is nothing selected.
| void | ClearSelection | ( | TBool | aDrawItems | ) |
Resets the selection state so that there is nothing selected.
| Parameter | Description |
|---|---|
| aDrawItems | Whether or not to draw the items which are deselected. |
| IMPORT_C void | ClearSelectionAnchorAndActiveIndex | ( | ) |
Resets the anchor index, the active end and the EAnchorExists flag.
| IMPORT_C void | ConstructL | ( | MListBoxModel * | aListBoxModel, |
| CListItemDrawer * | aItemDrawer, | |||
| CWsScreenDevice * | aScreen, | |||
| RWindowGroup * | aGroupWin, | |||
| RWindow * | aWsWindow, | |||
| const TRect & | aDisplayArea, | |||
| TInt | aItemHeight | |||
| ) | [virtual] | |||
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().
| Parameter | Description |
|---|---|
| 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. |
| IMPORT_C TInt | CurrentItemIndex | ( | ) | const [virtual] |
Gets the current item s index.
Returns: Index number of the current item.
| IMPORT_C TInt | DataWidth | ( | ) | const |
Gets the width of the widest item in the list in pixels.
Returns: Data width in pixels.
| IMPORT_C void | DeselectItem | ( | TInt | aItemIndex | ) |
Deselects an item by index.
| Parameter | Description |
|---|---|
| aItemIndex | Item to deselect. |
Deselects range between given indexes.
| Parameter | Description |
|---|---|
| aItemIndex1 | First index of selectable range. |
| aItemIndex2 | Second index of selectable range. |
| void | DisableVerticalLineDrawing | ( | TBool | aDisable | ) |
Disables vertical line drawing.
| Parameter | Description |
|---|---|
| aDisable | ETrue if disabled. |
| IMPORT_C void | Draw | ( | const TRect * | aClipRect = NULL | ) | const [virtual] |
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().
| Parameter | Description |
|---|---|
| aClipRect | The rectangle to draw into, this is ignored. Default value is NULL. |
| IMPORT_C void | DrawEmptyList | ( | const TRect & | aClientRect | ) | const [virtual] |
Not implemented.
| Parameter | Description |
|---|---|
| aClientRect | Not used. |
| IMPORT_C void | DrawItem | ( | TInt | aItemIndex | ) | const [virtual] |
Draws the specified item via CListBoxDrawer::DrawItem() if it is visible.
| Parameter | Description |
|---|---|
| aItemIndex | Index number of the item to draw. |
| IMPORT_C void | DrawMatcherCursor | ( | ) | [virtual] |
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.
| const TDesC * | EmptyListText | ( | ) | const [inline] |
Gets an empty list box text.
Return text currently in the empty list text
Returns: Pointer the empty list box text.
| TInt | Flags | ( | ) | const [protected, inline] |
Gets this view s flags.
These flags are defined by the nested enum TFlags (below).
Returns: List box's flags.
| IMPORT_C void | GetSelectionIndexesL | ( | CSelectionIndexArray * | aSelectionArray | ) | const |
Gets a copy of the array of currently selected items.
| Parameter | Description |
|---|---|
| aSelectionArray | An instantiated CSelectionIndexArray. On return, contains a copy of selection indexes. |
| IMPORT_C void | HScroll | ( | TInt | aHScrollAmount | ) | [virtual] |
Scrolls horizontally by the specified number of pixels.
| Parameter | Description |
|---|---|
| aHScrollAmount | The distance to scroll by in pixels. A negative value scrolls to the left, a positive value scrolls to the right. |
| IMPORT_C TInt | HScrollOffset | ( | ) | const |
Gets the offset of the visible portion of the data from the left margin in pixels.
Returns: The horizontal scroll offset in pixels.
| IMPORT_C TBool | IsVisible | ( | ) | const |
Tests if this view is visible.
Returns: ETrue if this view is visible. EFalse if this view is not visible or does not exist.
| CListItemDrawer * | ItemDrawer | ( | ) | const [inline] |
Gets the object used by this list box view to draw its items.
Returns: Pointer to the list box item drawer.
| TInt | ItemHeight | ( | ) | const [inline] |
Returns item's height. All items have the same height.
Tests whether an item is partially visible. Note that this returns EFalse also when item is fully visible, i.e. the whole item area is inside the list view rectangle.
| Parameter | Description |
|---|---|
| aItemIndex | Index of item to be tested. |
Returns: ETrue if the item is partially visible, EFalse if it's not visible or fully visible.
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.
| Parameter | Description |
|---|---|
| aItemIndex | Index of an item. Default value is 0. |
Returns: Size of the item.
| IMPORT_C TInt | MatcherCursorPos | ( | ) | const |
Gets the match cursor s position.
Returns: Character position of the match cursor within the current item s string.
| IMPORT_C void | MoveCursorL | ( | TCursorMovement | aCursorMovement, |
| TSelectionMode | aSelectionMode | |||
| ) | [virtual] | |||
Moves the current item cursor in the specified direction. This function is called by CEikListBox in response to user input.
| Parameter | Description |
|---|---|
| aCursorMovement | The cursor movement to apply. |
| aSelectionMode | The selection mode of the calling list box. |
| IMPORT_C TBool | RedrawDisabled | ( | ) | const |
Tests whether redraw is disabled.
Returns: ETrue if redraw is disabled.
| IMPORT_C void | SelectItemL | ( | TInt | aItemIndex | ) |
Selects an item by index.
This function leaves if memory could not be allocated for an extra item in the array of selected items.
| Parameter | Description |
|---|---|
| aItemIndex | Item to select. |
Selects items between given indexes.
| Parameter | Description |
|---|---|
| aItemIndex1 | First index of selectable range. |
| aItemIndex2 | Second index of selectable range. |
| IMPORT_C const CSelectionIndexArray * | SelectionIndexes | ( | ) | const |
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.
| IMPORT_C void | SetAnchor | ( | TInt | aItemIndex | ) |
Sets the anchor to the specified item.
| Parameter | Description |
|---|---|
| aItemIndex | The index of the item at which the anchor is set. |
| IMPORT_C void | SetBackColor | ( | TRgb | aColor | ) |
Sets the background colour.
| Parameter | Description |
|---|---|
| aColor | The background colour. |
| IMPORT_C void | SetCurrentItemIndex | ( | TInt | aItemIndex | ) |
Set the index of the current item. This function changes the current item, but does not redraw the list view or update the selection.
| Parameter | Description |
|---|---|
| aItemIndex | Which item to make current. |
| IMPORT_C void | SetDimmed | ( | TBool | aDimmed | ) |
Sets whether items will be drawn dimmed.
The function sets or resets the dim flag.
| Parameter | Description |
|---|---|
| aDimmed | If ETrue, this view will draw items dimmed. If EFalse this view will not draw items dimmed. |
| IMPORT_C void | SetDisableRedraw | ( | TBool | aDisableRedraw | ) |
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.
| Parameter | Description |
|---|---|
| aDisableRedraw | Disables redraw if ETrue. |
| IMPORT_C void | SetEmphasized | ( | TBool | aEmphasized | ) |
Sets whether or not items are drawn as emphasised.
The function sets or resets the emphasised flag.
| Parameter | Description |
|---|---|
| aEmphasized | If ETrue, this view will draw items emphasised. If EFalse will not draw items emphasised. |
| void | SetFlags | ( | TInt | aMask | ) | [protected, inline] |
Sets this view s flags according to a bitmask.
These flags are defined by the nested enum TFlags (below).
| Parameter | Description |
|---|---|
| aMask | Sets new flags for the list box. |
| IMPORT_C void | SetHScrollOffset | ( | TInt | aHorizontalOffset | ) |
Sets the horizontal scroll offset in pixels.
| Parameter | Description |
|---|---|
| aHorizontalOffset | New value for the horizontal scroll offset, in pixels. |
| IMPORT_C void | SetItemHeight | ( | TInt | aItemHeight | ) | [virtual] |
Sets the item height.
| Parameter | Description |
|---|---|
| aItemHeight | New item height. |
| IMPORT_C void | SetItemOffsetInPixels | ( | TInt | aOffset | ) |
Sets the offset for view.
| IMPORT_C void | SetListEmptyTextL | ( | const TDesC & | aText | ) |
Sets list box backroung text. This text is visible if the list box has no items.
| Parameter | Description |
|---|---|
| aText | The text for the empty list box background. |
| IMPORT_C void | SetMatcherCursor | ( | TBool | aMatcherCursor | ) |
Sets whether the matcher cursor flag to specify whether the match cursor is drawn.
| Parameter | Description |
|---|---|
| aMatcherCursor | If ETrue, the view will draw match cursor. |
| IMPORT_C void | SetMatcherCursorColor | ( | TRgb | aColor | ) |
Sets the match cursor s colour.
| Parameter | Description |
|---|---|
| aColor | Colour in which to display the incremental match cursor. |
| IMPORT_C void | SetMatcherCursorPos | ( | TInt | aPosWithinCurrentItem | ) |
Sets the match cursor's position.
| Parameter | Description |
|---|---|
| aPosWithinCurrentItem | Character position for the match cursor within the current item s string. |
| IMPORT_C void | SetPaintedSelection | ( | TBool | aPaintedSelection | ) |
Sets the painted selection flag.
| Parameter | Description |
|---|---|
| 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. |
| IMPORT_C void | SetSelectionIndexesL | ( | const CSelectionIndexArray * | aSelectionIndexes | ) |
Sets the currently selected items of this view from a selection index array.
| Parameter | Description |
|---|---|
| aSelectionIndexes | Items to select. |
| IMPORT_C void | SetTextColor | ( | TRgb | aColor | ) |
Sets the colour in which to display text.
| Parameter | Description |
|---|---|
| aColor | Colour in which to display text. |
| IMPORT_C void | SetTopItemIndex | ( | TInt | aItemIndex | ) | [virtual] |
Sets the item at the top of the view by its index in the list of all items. This function also invokes CalcBottomItemIndex().
| Parameter | Description |
|---|---|
| aItemIndex | Index of the item to start the view at. |
| IMPORT_C void | SetViewRect | ( | const TRect & | aRect | ) |
Sets the area within the list window in which the view can draw itself.
| Parameter | Description |
|---|---|
| aRect | New view rectangle. |
| void | SetVisibilityObserver | ( | MListVisibilityObserver * | aObserver | ) |
Sets the visibility observer.
| Parameter | Description |
|---|---|
| aObserver | New visibility observer for this control. |
| IMPORT_C TRgb | TextColor | ( | ) | const |
Gets the colour in which text is to be displayed.
Returns: Current text colour.
| IMPORT_C void | ToggleItemL | ( | TInt | aItemIndex | ) |
Toggles the selection of an item.
| Parameter | Description |
|---|---|
| aItemIndex | Item to toggle. |
| IMPORT_C TInt | TopItemIndex | ( | ) | const |
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.
| IMPORT_C void | UpdateSelectionL | ( | TSelectionMode | aSelectionMode | ) | [virtual] |
Updates item selection.
| Parameter | Description |
|---|---|
| aSelectionMode | The selection mode. |
| IMPORT_C void | VScrollTo | ( | TInt | aNewTopItemIndex | ) | [virtual] |
Sets the index of the item to be the top item.
| Parameter | Description |
|---|---|
| aNewTopItemIndex | The item to scroll to. |
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.
| Parameter | Description |
|---|---|
| aNewTopItemIndex | The distance by which to scroll. |
| aMinRedrawRect | On return, the minimum rectangle to redraw. |
| IMPORT_C void | VerticalMoveToItemL | ( | TInt | aTargetItemIndex, |
| TSelectionMode | aSelectionMode | |||
| ) | [virtual] | |||
Moves to the specified item, sets it as the current item and scrolls the display to make the item visible.
| Parameter | Description |
|---|---|
| aTargetItemIndex | The index of the item to which to move. |
| aSelectionMode | The selection mode. |
| IMPORT_C TRect | ViewRect | ( | ) | const |
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.
| Parameter | Description |
|---|---|
| aRect | The rectangle to get the visible width for. |
Returns: Visible width of aRect.
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.
| Parameter | Description |
|---|---|
| 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.