Selection and Check Boxes

Selects one item or several of a ListView, gives the items check boxes, and reports each change of the selection, the focus and the check boxes.

Dim Watch As New SelectionWatcher
Set Watch.LV = ListView1
ListView1.ListItems.Add , , "alpha"
ListView1.ListItems.Add , , "beta"
ListView1.ListItems(2).Selected = True
Debug.Print ListView1.SelectedItem.Text; ListView1.GetSelectedCount
' Output:
' ItemFocus alpha
' ItemSelect alpha True
' ItemSelect alpha False
' ItemFocus beta
' ItemSelect beta True
' beta 1

SelectionWatcher in the samples of this page is a class of the program’s own that holds the control WithEvents and prints each of its item events.

Selected and focused items

Each item can be selected, and one item at a time has the focus: the dotted rectangle that the arrow keys move. While MultiSelect is False, selecting an item takes the selection from the others. With True, the user selects more with Ctrl and Shift, or by dragging a rectangle over them, and SelectedIndices returns their numbers.

SelectedItem is the item that has the focus, and that item need not be selected: an item whose Selected is set to False keeps the focus. Setting SelectedItem to an item selects it and gives it the focus. Setting it to Nothing takes the focus from every item and leaves the selection as it was.

When the first item comes into an empty control it gets the focus, and while AutoSelectFirstItem is True it is selected as well.

Each change raises an event, whether the user or the program makes it: ItemSelect for an item selected or no longer selected, and ItemFocus for the item that gets the focus. The sample above shows the order.

Check boxes

With Checkboxes True every item has a check box in front of its icon, which the user checks with a click or the Space key. An item’s Checked reads and sets it, and each change raises ItemCheck; assigning the state an item already has raises nothing. Setting Checkboxes to True unchecks every item, and raises ItemCheck for each item that was checked.

Dim Watch As New SelectionWatcher
ListView1.Checkboxes = True
ListView1.ListItems.Add , , "alpha"
ListView1.ListItems.Add , , "beta"
Set Watch.LV = ListView1
ListView1.ListItems(2).Checked = True
ListView1.ListItems(2).Checked = True
Debug.Print ListView1.CheckedIndices.Count; ListView1.CheckedIndices(1)
' Output:
' ItemCheck beta True
'  1  2

An item can also be ghosted, drawn dimmed as a file cut to the clipboard is, by its Ghosted. GhostedIndices returns the numbers of the ghosted items, as CheckedIndices does of the checked ones.

Hot tracking

With HotTracking True the item under the pointer is hot: it is highlighted, it is selected when the pointer rests on it for HoverSelectionTime, and one click activates it, which raises ItemActivate. HighlightHot and UnderlineHot draw the hot item’s text in the hot-tracking color or underlined. HoverSelection selects an item the pointer rests on without the rest of hot tracking.

Properties

AutoSelectFirstItem

Whether the first item that comes into an empty control is selected as well as given the focus. Boolean. Default: True.

Checkboxes

Whether each item has a check box. Boolean. Default: False. See Check boxes.

FullRowSelect

Whether a selected item is highlighted across all its columns in the report view, and whether a click anywhere in the row selects it. Boolean. Default: False, with which only the item’s own text is highlighted.

HideSelection

Whether the selection is hidden while the control does not have the focus. Boolean. Default: True. With False the selected items stay highlighted.

HighlightHot

Whether the text of the hot item is drawn in the hot-tracking color of Windows. Boolean. Default: False. It has an effect while HotTracking is True.

HotItem

The hot item. An LvwListItem, or Nothing when no item is hot. Setting it to an item makes that item hot; Nothing makes no item hot. It has a meaning while HotTracking is True.

HotMouseIcon

The pointer shown over an item while hot tracking, when HotMousePointer is CCMousePointerCustom. A picture that holds an icon or a cursor; a picture of another kind raises run-time error 380.

HotMousePointer

The pointer shown while the mouse is over an item and HotTracking or HoverSelection is True. A member of CCMousePointerConstants. Default: CCMousePointerDefault, the pointer the list view of Windows shows there. Another value raises run-time error 380.

HotTracking

Whether the item under the pointer is hot, is selected when the pointer rests on it, and is activated by one click. Boolean. Default: False. See Hot tracking.

HoverSelection

Whether an item is selected when the pointer rests on it for HoverSelectionTime. Boolean. Default: False. HotTracking does the same and more.

HoverSelectionTime

How long the pointer rests on an item before the item is selected, in milliseconds. Long. Default: -1, the time of Windows.

0, and a negative value other than -1, raise run-time error 380.

MultiSelect

Whether the user can select several items. Boolean. Default: False.

SelectedItem

The item that has the focus. An LvwListItem, or Nothing. See Selected and focused items for what an assignment does.

SelectionMark

The item from which a selection with Shift and a click or an arrow key goes on. An LvwListItem, or Nothing. A program sets it to an item, or to Nothing.

UnderlineHot

Whether the text of the hot item is underlined. Boolean. Default: False. It has an effect while HotTracking is True.

Methods

CheckedIndices

Returns a Collection of the numbers of the checked items, in their order in the control. An empty collection when none is checked.

Syntax: object.CheckedIndices( ) As Collection

GetSelectedCount

Returns the number of selected items. Long.

Syntax: object.GetSelectedCount( ) As Long

GhostedIndices

Returns a Collection of the numbers of the ghosted items, in their order in the control. In virtual mode it raises run-time error 91.

Syntax: object.GhostedIndices( ) As Collection

SelectedIndices

Returns a Collection of the numbers of the selected items, in their order in the control.

Syntax: object.SelectedIndices( ) As Collection

Dim Number As Variant
With ListView1
    .MultiSelect = True
    .ListItems.Add , , "alpha"
    .ListItems.Add , , "beta"
    .ListItems.Add , , "gamma"
    .ListItems(3).Selected = True
    For Each Number In .SelectedIndices
        Debug.Print .ListItems(Number).Text
    Next
End With
' Output:
' alpha
' gamma

Events

BeginMarqueeSelection

Raised when the user starts to drag a rectangle over the items to select them, while MultiSelect is True.

Syntax: object_BeginMarqueeSelection( Cancel As Boolean )

Cancel
False when the event is raised. A handler that sets it to True stops the rectangle.

ItemCheck

Raised when the check box of an item changes, by the user or by code.

Syntax: object_ItemCheck( ByVal Item As LvwListItem, ByVal Checked As Boolean )

Item
The LvwListItem.
Checked
The new state: True when the item is now checked.

ItemFocus

Raised when an item gets the focus, by the user or by code.

Syntax: object_ItemFocus( ByVal Item As LvwListItem )

ItemSelect

Raised when an item is selected or is no longer selected, by the user or by code.

Syntax: object_ItemSelect( ByVal Item As LvwListItem, ByVal Selected As Boolean )

Item
The LvwListItem. In virtual mode it is Nothing when every item is no longer selected at once.
Selected
The new state: True when the item is now selected.

See Also