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
- ListView control
- LvwListItem class – the Selected, Checked, Ghosted and Hot of an item