VListBox class

A VListBox is a list box that holds no items: the program tells it how many items there are, and supplies the text of an item in an event each time the control shows it.

A list box that shows rows 50,001 to 50,005 of a long list, row 50,003 selected, the thumb of its scroll bar halfway down
VListBox1.ListCount = 100000
VListBox1.ListIndex = 99999
Debug.Print VListBox1.ListCount; VListBox1.ListIndex
' Output:
'  100000  99999

It is the ListBoxW control without a list of its own, and most of its members are the same. VB6 has no such control.

Of the common members, the control has every member under Name and place, Window handles, Font and visual styles, Mouse, Keyboard and focus, Dragging the control, OLE drag and drop and Right-to-left but RightToLeftLayout. Its Click has a meaning of its own, and its mouse events give the position in twips.

Items that the program supplies

The program sets ListCount to the number of items. From then on the list scrolls and selects as any list box, and raises GetVirtualItem whenever it needs the text of an item: to draw it, to return it from List or Text, or to give it to a program that reads the list. The handler looks the text up where the program keeps its data, such as an array:

Private Cities() As String          ' filled elsewhere, from index 0

Private Sub VListBox1_GetVirtualItem(ByVal Item As Long, Text As String)
    Text = Cities(Item)
End Sub

The handler is called often, for the items in view each time the list is drawn, so it must be quick and must not change the list.

The control keeps no text. Without a handler every item is empty. When the data changes, the program sets ListCount again if the number of items changed and calls Refresh. An assignment to ListCount leaves no item selected, and raises no event.

When to choose it

A ListBoxW copies the text of every item when it is filled, which takes time and memory in proportion to the list. A VListBox takes the same short time for a hundred items and for a million, since it asks for the few items in view. Choose it for a list of many thousands of items, and for data that the program holds anyway, in an array, a collection or a recordset.

What it gives up follows from having no items: there is no AddItem, RemoveItem or Clear, no ItemData, no Sorted, and no check boxes. The order of the items is the order of the program’s data, and searching is the program’s work as well.

Searching

The control cannot search texts that it does not have, so it raises an event for each search and the handler answers with an index.

FindVirtualItem is raised by FindItem, by SelectItem, by an assignment to Text, and when another program asks the list to find a text. The handler receives the text, the item after which to start, and whether the beginning of an item’s text is enough.

Private Sub VListBox1_FindVirtualItem(ByVal StartIndex As Long, ByVal SearchText As String, ByVal Partial As Boolean, FoundIndex As Long)
    Dim Index As Long, Candidate As String
    For Index = StartIndex + 1 To VListBox1.ListCount - 1
        Candidate = VListBox1.List(Index)
        If Partial Then Candidate = Left$(Candidate, Len(SearchText))
        If StrComp(Candidate, SearchText, vbTextCompare) = 0 Then
            FoundIndex = Index
            Exit Sub
        End If
    Next
End Sub

IncrementalSearch is raised when the user types a character in the list, to jump to an item. The control collects the characters typed in quick succession into one search string; the handler sets the item to select, and the control selects it and raises Click.

What is shared with ListBoxW

Selection, columns, scrolling, the insertion mark and drawing work as in ListBoxW, whose sections explain them: Selecting one item, Selecting several items, Columns and scrolling, Dragging items and Drawing the items. The items of a VListBox all have one height.

Properties

AllowSelection

Whether the list shows a selection. Boolean. Default: True. With False the user can look at the items and scroll, and a click selects nothing.

AnchorIndex

The item from which the user’s next selection with the Shift key extends, in a list that selects several items. Long. A value less than -1, or one that is not an item, raises run-time error 380.

BackColor

The background color of the list. OLE_COLOR. A new control has vbWindowBackground.

BorderStyle

The border of the control. A member of CCBorderStyleConstants. Default: CCBorderStyleSunken. Another value raises run-time error 380.

DisableNoScroll

Whether the list shows a disabled scroll bar when all its items fit. Boolean. Default: False, with which the list has a scroll bar only when it needs one.

DrawMode

Whether the control or the program draws the items. A member of VlbDrawModeConstants. Default: VlbDrawModeNormal. With VlbDrawModeOwnerDrawFixed the control raises ItemDraw for each item to show, and no GetVirtualItem to draw it.

It is set at design time. At run time an assignment raises run-time error 382, and a value that is not a member raises 380.

ForeColor

The color of the items’ text. OLE_COLOR.

HorizontalExtent

The width over which a list in one column can be scrolled sideways, in the scale units of the control’s container. Single. Default: 0. The list has a horizontal scroll bar while this is greater than its own width. A negative value raises run-time error 380.

InsertMark

The item at which the insertion mark is drawn, or -1 for no mark. Long. Default: -1. See Dragging items.

Syntax: object.InsertMark[( After )] [ = value ]

After
optional A Boolean variable. In an assignment, True draws the mark below the item and False, the default, above it. When the property is read, the variable receives which of the two the mark is.

A value that is not an item raises run-time error 381.

InsertMarkColor

The color of the insertion mark. OLE_COLOR. Default: black.

IntegralHeight

Whether the list shows whole items only. Boolean. Default: True, with which the control makes itself a little lower so that its last item is not cut.

It is set at design time: an assignment at run time raises run-time error 382.

ItemHeight

The height of an item, in the scale units of the control’s container. Single. All items have this height. A negative value raises run-time error 380.

List

The text of an item, as the handler of GetVirtualItem supplies it. String, read-only.

Syntax: object.List( Index )

An Index that is not an item raises run-time error 5.

ListCount

The number of items in the list. Long. Default: 0. The program sets it.

A negative value raises run-time error 380.

ListIndex

The index of the selected item, or -1 when no item is selected. Long. Default: -1. In a list that selects several items it is the index of the item with the focus rectangle.

An assignment selects the item, or moves the focus rectangle, and raises Click unless the value is the one the property has. -1 removes the selection. A value that is not an item raises run-time error 380.

In a list that selects several items, -1 leaves the focus rectangle and the selection as they are, and raises Click.

MultiColumn

Whether the items are laid out in columns and the list scrolls sideways. Boolean. Default: False. See Columns and scrolling.

MultiSelect

Whether the user can select several items, and how. A member of MultiSelectConstants. Default: vbMultiSelectNone. See Selecting several items. Another value raises run-time error 380.

It can be assigned at run time, and the list keeps its ListCount. An empty list accepts it too.

OLEDragDropScroll

Whether the list scrolls by itself while data is dragged over it near an edge. Boolean. Default: True. It has an effect while OLEDropMode is OLEDropModeManual.

OLEDragMode

Whether the user can drag items out of the list. A member of OLEDragConstants. Default: vbOLEDragManual, with which only OLEDrag starts a drag. With vbOLEDragAutomatic a drag that begins on a selected item carries the texts of the selected items, one to a line, to copy. Another value raises run-time error 380.

OLEDraggedItem

The index of the item on which the drag that is going on began. Long, read-only. It is -1 while no drag is going on.

Redraw

Whether the control draws itself when its list changes. Boolean. Default: True. Setting it to True again draws the control.

ScrollTrack

Whether the list scrolls while the user drags the scroll box of a scroll bar. Boolean. Default: True. With False the list scrolls when the user releases the scroll box.

SelCount

The number of selected items. Long, read-only.

Selected

Whether an item is selected. Boolean.

Syntax: object.Selected( Index ) [ = value ]

An assignment selects the item or removes its selection, and raises Click when that changes the selection. An Index that is not an item raises run-time error 381.

Text

The text of the selected item, or an empty string when none is selected. String. It is the control’s default property.

An assignment raises FindVirtualItem for an item whose whole text is the value, and selects the item that the handler names. When the handler names none, the selection is removed; in a list that selects several items the assignment changes nothing.

TopIndex

The index of the first item shown. Long. An assignment scrolls the list. A negative value raises run-time error 380.

UseTabStops

Whether a tab character in an item’s text moves the text after it to the next tab stop, which lines the items up in columns. Boolean. Default: True.

Methods

FindItem

Raises FindVirtualItem and returns the index that its handler found, or -1.

Syntax: object.FindItem( Text [, Index [, Partial ] ] )

Text
required A String: the text to look for.
Index
optional A Long: the item after which the search starts. The default, -1, searches from the top. A value that is not an item raises run-time error 381.
Partial
optional A Boolean: True asks for an item that begins with Text, False (the default) for one whose whole text is Text.

GetIdealHorizontalExtent

Returns the HorizontalExtent with which the widest item can be scrolled into view, as a Single in the scale units of the control’s container. It raises GetVirtualItem for every item of the list, so it is slow on a long one.

Syntax: object.GetIdealHorizontalExtent

HitTest

Returns the index of the item at a position, or -1 when no item is there.

Syntax: object.HitTest( X, Y )

X, Y
required The position as two Single values, measured from the list’s top left corner in the scale units of the control’s container, as the OLE drag-and-drop events give it.

HitTestInsertMark

Returns the index of the item at a position, as HitTest does, and says in which half of the item the position is.

Syntax: object.HitTestInsertMark( X, Y [, After ] )

X, Y
required The position, as for HitTest.
After
optional A Boolean variable that receives True when the position is in the lower half of the item, where an insertion mark belongs below it.

ItemsPerColumn

Returns the number of items that one column of a MultiColumn list holds, as a Long.

Syntax: object.ItemsPerColumn

SelectedIndices

Returns a Collection of the indexes of the selected items, in rising order.

Syntax: object.SelectedIndices

SelectItem

Raises FindVirtualItem for an item that begins with a text, selects the item that the handler found, and returns its index, or -1. It raises Click when it selects another item than before.

Syntax: object.SelectItem( Text [, Index ] )

Text
required A String: the beginning of the item’s text.
Index
optional A Long: the item after which the search starts, as in FindItem.

SetColumnWidth

Sets the width of the columns of a MultiColumn list.

Syntax: object.SetColumnWidth Value

Value
required A Single: the width in the scale units of the control’s container. A value that is not greater than 0 raises run-time error 380.

SetSelRange

Selects a run of items, or removes their selection, in a list that selects several items.

Syntax: object.SetSelRange StartIndex, EndIndex

StartIndex, EndIndex
required Two Long indexes. When StartIndex is less than EndIndex, the items from the one to the other are selected as well as those selected already. When it is not less, as when the two are the same, the selection is removed from those items.

The method raises Click when the number of selected items changes. In a list that selects one item it selects StartIndex. An index that is not an item raises run-time error 381.

Events

Click

Raised when the user selects an item, with the mouse or the keyboard, and when ListIndex, Selected, SelectItem, SetSelRange or Text changes the selection. A mouse click on the empty part of the list raises no Click.

Syntax: object_Click( )

ContextMenu

Raised when the user asks for the control’s shortcut menu, with the right mouse button or with Shift+F10.

Syntax: object_ContextMenu( ByVal X As Single, ByVal Y As Single )

X, Y
The position of the pointer, measured from the list’s top left corner in the scale units of the control’s container. Both are -1 when the user asked with the keyboard.

FindVirtualItem

Raised when an item is to be found by its text. See Searching.

Syntax: object_FindVirtualItem( ByVal StartIndex As Long, ByVal SearchText As String, ByVal Partial As Boolean, FoundIndex As Long )

StartIndex
The item after which the search starts, or -1 to search from the top.
SearchText
The text to look for.
Partial
True when an item that begins with SearchText is asked for, False when the item’s whole text must be SearchText.
FoundIndex
-1 when the event is raised. The handler sets it to the index of the item found, and leaves it when there is none.

GetVirtualItem

Raised when the control needs the text of an item. See Items that the program supplies.

Syntax: object_GetVirtualItem( ByVal Item As Long, Text As String)

Item
The index of the item, from 0 to ListCount - 1.
Text
Empty when the event is raised. The handler sets it to the item’s text.

IncrementalSearch

Raised when the user types a character while the list has the focus. See Searching.

Syntax: object_IncrementalSearch( ByVal SearchString As String, ByVal StartIndex As Long, FoundIndex As Long )

SearchString
The characters typed. A character typed soon after the one before is added to the string; after a pause the string starts again.
StartIndex
The value of ListIndex.
FoundIndex
-1 when the event is raised. The handler sets it to the index of the item to select.

ItemDraw

Raised when an item is to be drawn, while DrawMode is VlbDrawModeOwnerDrawFixed. Its arguments are those of the ItemDraw event of ListBoxW.

Syntax: object_ItemDraw( ByVal Item As Long, ByVal ItemAction As Long, ByVal ItemState As Long, ByVal hDC As Long, ByVal Left As Long, ByVal Top As Long, ByVal Right As Long, ByVal Bottom As Long )

MouseDown, MouseMove, MouseUp

As the common events of these names, but X and Y are in twips, whatever the scale units of the control’s container, and are measured from the top left corner of the list.

Scroll

Raised when the list has scrolled, so that another item is the first one shown.

Syntax: object_Scroll( )

VlbDrawModeConstants

The values of DrawMode.

Member Value Description
VlbDrawModeNormal 0 The control draws the items, with the texts that GetVirtualItem supplies.
VlbDrawModeOwnerDrawFixed 1 The program draws the items, which all have one height.

See Also

  • Common members – the members this control shares with the package’s other controls
  • ListBoxW – the list box that holds its items
  • VirtualCombo – a combo box whose items the program supplies