SysWin Gui ListBox

Home › All Categories › sys/win › sys/win/gui › ListBox

ListBox

Adds, finds, selects and reads the items of a list box control.

A list box shows a column of items, usually strings, from which the user picks one or several. Create one with CWindow.AddControl( "ListBox", ... ): it is sorted (LBS_SORT), keeps its strings (LBS_HASSTRINGS), has a border and both scroll bars, and sends notifications (LBS_NOTIFY). Every function here takes the control's handle first and is written with the namespace: ListBox.AddString( hList, "Apple" ).

Items are numbered from 0. Most functions send one list-box message and return what it returns: an index or a count on success, LB_ERR (-1) on failure and LB_ERRSPACE (-2) when the list box ran out of memory. Each item also holds one LONG_PTR of item data for the program's own use; the list box never frees what it points to. An owner-drawn list box without LBS_HASSTRINGS stores no text at all, and the *ItemData functions add and find its items by that value.

There are three kinds of selection, set by the style when the control is created:

Style	The user selects	Read the selection with
none	one item	GetCurSel
`LBS_MULTIPLESEL`	any number, each click toggles one	GetSel, GetSelItems
`LBS_EXTENDEDSEL`	ranges, with `Shift` and `Ctrl`	GetSel, GetSelItems, GetSelect

Several helpers look at the style and send a different message for each kind; their entries say which. The parent learns of changes through WM_COMMAND: LBN_SELCHANGE when the user changes the selection, LBN_DBLCLK on a double click. The functions here never notify.

Importing

#import "sys/win"
#import "sys/win/gui"
using win, gui

Example

A sorted list of fruit, each with its price as item data. Selecting one shows its price below the list; the button removes the selected item.

#import "sys/win"
#import "sys/win/gui"
using win, gui

const IDC_LIST = 101
const IDC_INFO = 102
const IDC_REMOVE = 103

declare function WndProc( byval hwnd as HWND, byval uMsg as UINT, byval wParam as WPARAM, byval lParam as LPARAM ) as LRESULT

function main() as long
    SetProcessDpiAwareness( PROCESS_SYSTEM_DPI_AWARE )
    dim pWindow as CWindow = "ListBoxDemo"
    dim hWin as HWND = pWindow.Create( NULL, "ListBox", @WndProc )
    pWindow.SetClientSize( 300, 240 )
    pWindow.Center()
    dim hList as HWND = pWindow.AddControl( "ListBox", hWin, IDC_LIST, "", 10, 10, 280, 180 )
    dim ustrFruit(0 to 4) as ustring = { "Pear", "Apple", "Cherry", "Banana", "Plum" }
    dim nCents(0 to 4) as long = { 120, 95, 450, 60, 210 }
    for i as long = 0 to 4
        dim idx as long = ListBox.AddString( hList, ustrFruit(i) )
        ListBox.SetItemData( hList, idx, nCents(i) )
    next
    pWindow.AddControl( "Label", hWin, IDC_INFO, "Pick a fruit", 10, 204, 180, 22 )
    pWindow.AddControl( "Button", hWin, IDC_REMOVE, "&Remove", 200, 200, 90, 28 )
    return pWindow.DoEvents( SW_NORMAL )
end function

function WndProc( byval hwnd as HWND, byval uMsg as UINT, byval wParam as WPARAM, byval lParam as LPARAM ) as LRESULT
    select case uMsg
        case WM_COMMAND
            dim hList as HWND = GetDlgItem( hwnd, IDC_LIST )
            select case CBCTL( wParam, lParam )
                case IDC_LIST
                    if CBCTLMSG( wParam, lParam ) = LBN_SELCHANGE then
                        dim i as long = ListBox.GetCurSel( hList )
                        if i >= 0 then
                            Label.SetText( GetDlgItem( hwnd, IDC_INFO ), _
                                           ListBox.GetText( hList, i ) & ": " & ListBox.GetItemData( hList, i ) & " cents" )
                        end if
                    end if
                case IDC_REMOVE
                    if CBCTLMSG( wParam, lParam ) = BN_CLICKED then
                        dim i as long = ListBox.GetCurSel( hList )
                        if i >= 0 then
                            dim nLeft as long = ListBox.DeleteString( hList, i )
                            if i >= nLeft then i = nLeft - 1
                            ListBox.SetCurSel( hList, i )
                        end if
                    end if
            end select
            return 0
        case WM_DESTROY
            PostQuitMessage( 0 )
            return 0
    end select
    return DefWindowProcW( hwnd, uMsg, wParam, lParam )
end function

end main()

Functions

Function	Does
AddString	Adds a string, in sorted order when the list is sorted.
InsertString	Inserts a string at an index.
DeleteString	Deletes an item.
ResetContent	Deletes every item.
ReplaceString	Replaces an item's text and item data, then selects it.
SetText	Replaces an item's text, then selects it.
AddFile	Adds a file name to a list filled by Dir.
Dir	Adds the files, folders or drives that match a pattern.
InitStorage	Reserves memory before adding many items.
SetCount	Sets the number of items of a list box without data.
GetCount	Returns the number of items.
GetText	Returns an item's text.
GetTextLen	Returns the length of an item's text.
FindString	Finds the first item that begins with a string.
FindStringExact	Finds the first item equal to a string.
GetItemData	Returns an item's item data.
SetItemData	Sets an item's item data.
AddItemData	Adds an item to an owner-drawn list box without strings.
InsertItemData	Inserts an item into an owner-drawn list box without strings.
FindItemData	Finds the item with a given item data.
SelectItemData	Finds and selects the item with a given item data.
GetCurSel	Returns the selected item.
SetCurSel	Selects an item in a single-selection list box.
GetSelect	Returns the first selected item from a starting index.
GetSel	Returns whether an item is selected.
SetSel	Selects or deselects an item.
SelectString	Selects the first item that begins with a string, or an item by index.
UnselectString	Deselects an item.
GetSelCount	Returns the number of selected items.
GetSelItems	Reads the indexes of the selected items.
SelItemRange	Selects or deselects a range of items.
SelItemRangeEx	Selects or deselects a range of items.
GetAnchorIndex	Returns the item a range selection starts from.
SetAnchorIndex	Sets the item a range selection starts from.
GetCaretIndex	Returns the item with the focus rectangle.
SetCaretIndex	Moves the focus rectangle to an item.
GetTopIndex	Returns the first visible item.
SetTopIndex	Scrolls an item to the top.
GetItemHeight	Returns the height of the items.
SetItemHeight	Sets the height of the items.
GetItemRect	Returns the rectangle of an item.
ItemFromPoint	Returns the item nearest a point.
GetListBoxInfo	Returns the number of items in each column.
SetColumnWidth	Sets the column width of a multicolumn list box.
SetTabStops	Sets the tab stops used to draw item text.
GetHorizontalExtent	Returns the scrollable width.
SetHorizontalExtent	Sets the scrollable width.
CalcHorizontalExtent	Measures the widest item.
GetLocale	Returns the locale used for sorting.
SetLocale	Sets the locale used for sorting.
Enable	Lets the user use the list box.
Disable	Greys the list box out.
SetDarkMode	Draws the scroll bars with the dark theme.
RemoveDarkMode	Draws the scroll bars with the default theme again.

Reference

AddString

function AddString( byval hListBox as HWND, byval pwszText as wstring ptr ) as long

Adds a string. A list box with LBS_SORT inserts it in sorted order (case does not count); any other adds it at the end.

Returns the index the string went to, or LB_ERR / LB_ERRSPACE. In a sorted list box adding "Pear", "Apple", "Banana" and "apricot" returns 0, 0, 1 and 1.

Example

dim idx as long = ListBox.AddString( hCtrl, "Apple" )
ListBox.SetCurSel( hCtrl, idx )

Microsoft Learn: LB_ADDSTRING

InsertString

function InsertString( byval hListBox as HWND, byval index as long, byval pwszText as wstring ptr ) as long

Inserts a string before item index, or at the end when index is -1. A sorted list box is not re-sorted: the string stays where it was put.

Returns the index of the new item, or LB_ERR / LB_ERRSPACE.

Example

ListBox.InsertString( hCtrl, 0, "(none)" )

Microsoft Learn: LB_INSERTSTRING

DeleteString

function DeleteString( byval hListBox as HWND, byval index as long ) as long

Deletes item index. The item data goes with it; free whatever it pointed to first.

Returns the number of items left, or LB_ERR when index is not an item.

Example

dim i as long = ListBox.GetCurSel( hCtrl )
if i >= 0 then ListBox.DeleteString( hCtrl, i )

Microsoft Learn: LB_DELETESTRING

ResetContent

sub ResetContent( byval hListBox as HWND )

Deletes every item.

Example

ListBox.ResetContent( hCtrl )

Microsoft Learn: LB_RESETCONTENT

ReplaceString

function ReplaceString( byval hListBox as HWND, byval index as long, byval pwszNewText as wstring ptr, byval pNewData as LONG_PTR = NULL ) as long

Replaces item index with a new string and item data: it deletes the item, inserts pwszNewText at the same index (a sorted list box is not re-sorted), sets its item data to pNewData (0 by default) and then selects it.

The selection step depends on the style. A single-selection list box selects the new item. An LBS_EXTENDEDSEL list box keeps the new text but the selection step fails, and the function returns LB_ERR. An LBS_MULTIPLESEL list box gets LB_SETSEL with the index in the place of the select flag, so it selects item 0 (or, when index is 0, deselects it) and leaves the new item unselected.

Parameter	Meaning
`hListBox`	The list box.
`index`	The item to replace.
`pwszNewText`	Its new text.
`pNewData`	Its new item data.

Returns LB_ERR when index is not an item or the selection step fails, LB_ERRSPACE when memory ran out, otherwise the result of the selection step: the index in a single-selection list box.

Example

ListBox.ReplaceString( hCtrl, 2, "Cherry", 450 )

Microsoft Learn: LB_INSERTSTRING

SetText

function SetText( byval hListBox as HWND, byval index as long, byval pwszNewText as wstring ptr ) as long

Replaces the text of item index, like ReplaceString without the item-data step: the item is deleted and inserted again, so its item data becomes 0. The new item is then selected, with the same per-style behaviour as ReplaceString.

Returns as ReplaceString.

Example

ListBox.SetText( hCtrl, 0, "Apple (ripe)" )

Microsoft Learn: LB_DELETESTRING

AddFile

function AddFile( byval hListBox as HWND, byval pwszFileName as wstring ptr ) as long

Adds the name of an existing file to a list box that Dir filled.

Returns the index of the new item, or LB_ERR.

Example

ListBox.AddFile( hCtrl, "readme.txt" )

Microsoft Learn: LB_ADDFILE

Dir

function Dir( byval hListBox as HWND, byval Attr as DWORD, byval pwszFileSpec as wstring ptr ) as long

Adds the names of the files that match pwszFileSpec (a path with wildcards, such as *.txt) and have the attributes in Attr. Attr is a combination of DDL_* values: DDL_READWRITE (0) for ordinary files, DDL_DIRECTORY for folders, shown as [name], DDL_DRIVES for drives, shown as [-c-], and DDL_EXCLUSIVE for only the kinds named.

Returns the index of the last name added, or LB_ERR / LB_ERRSPACE.

Example

ListBox.Dir( hCtrl, DDL_READWRITE or DDL_DIRECTORY, "*.*" )

Microsoft Learn: LB_DIR

InitStorage

function InitStorage( byval hListBox as HWND, byval nItems as DWORD, byval nBytes as DWORD ) as long

Reserves memory for nItems more items and nBytes bytes of their strings before a long run of AddString calls, so that the list box does not grow its memory one item at a time.

Returns the number of items memory is now reserved for, the existing ones included (a list of 4 items reserving 100 more returns 104), or LB_ERRSPACE.

Example

ListBox.InitStorage( hCtrl, 10000, 10000 * 20 )

Microsoft Learn: LB_INITSTORAGE

SetCount

function SetCount( byval hListBox as HWND, byval nCount as DWORD ) as long

Sets the number of items of a list box created with LBS_NODATA and without LBS_HASSTRINGS, which stores nothing and has its items drawn by the owner from the program's own data.

Returns 0 on success, LB_ERR or LB_ERRSPACE otherwise.

Example

ListBox.SetCount( hCtrl, 100000 )

Microsoft Learn: LB_SETCOUNT

GetCount

function GetCount( byval hListBox as HWND ) as long

Returns the number of items.

Returns the count.

Example

for i as long = 0 to ListBox.GetCount( hCtrl ) - 1
    print ListBox.GetText( hCtrl, i )
next

Microsoft Learn: LB_GETCOUNT

GetText

function GetText( byval hListBox as HWND, byval index as long ) as ustring

Returns the text of item index. A negative index means the current item: the caret item in an LBS_MULTIPLESEL list box, the selected item in any other (see GetCurSel). The string is exactly the item's text, with no null character at the end.

Returns the text, or "" when there is no such item; afterwards GetLastError() is the number of characters read, or LB_ERR when the item does not exist.

Example

print "selected: "; ListBox.GetText( hCtrl, -1 )

Microsoft Learn: LB_GETTEXT

GetTextLen

function GetTextLen( byval hListBox as HWND, byval index as long ) as long

Returns the number of characters in the text of item index.

Returns the length, or LB_ERR when index is not an item.

Example

print ListBox.GetTextLen( hCtrl, 0 ); " characters"

Microsoft Learn: LB_GETTEXTLEN

FindString

function FindString( byval hListBox as HWND, byval indexStart as long, byval pwszString as wstring ptr ) as long

Finds the first item whose text begins with pwszString, ignoring case. The search starts after item indexStart and wraps round to the top; pass -1 to search from the first item.

Returns the index of the item found, or LB_ERR.

Example

dim i as long = ListBox.FindString( hCtrl, -1, "ap" )   ' finds "Apple" or "apricot"

Microsoft Learn: LB_FINDSTRING

FindStringExact

function FindStringExact( byval hListBox as HWND, byval indexStart as long, byval pwszSearchString as wstring ptr ) as long

Finds the first item whose whole text is pwszSearchString, ignoring case. indexStart works as for FindString.

Returns the index of the item found, or LB_ERR.

Example

if ListBox.FindStringExact( hCtrl, -1, "banana" ) = LB_ERR then ListBox.AddString( hCtrl, "Banana" )

Microsoft Learn: LB_FINDSTRINGEXACT

GetItemData

function GetItemData( byval hListBox as HWND, byval index as long ) as LONG_PTR

Returns the item data of item index: the value set with SetItemData, or 0.

Returns the value, or LB_ERR when index is not an item.

Example

dim nId as LONG_PTR = ListBox.GetItemData( hCtrl, ListBox.GetCurSel( hCtrl ) )

Microsoft Learn: LB_GETITEMDATA

SetItemData

function SetItemData( byval hListBox as HWND, byval index as long, byval pData as LONG_PTR ) as long

Stores a value with item index: a number, or a pointer the program allocated and frees itself before the item is deleted.

Returns LB_ERR on failure, another value on success.

Example

ListBox.SetItemData( hCtrl, ListBox.AddString( hCtrl, "Plum" ), 210 )

Microsoft Learn: LB_SETITEMDATA

AddItemData

function AddItemData( byval hListBox as HWND, byval pData as LONG_PTR ) as long

Adds an item to an owner-drawn list box without LBS_HASSTRINGS, whose items have only item data: pData becomes the new item's item data. Without LBS_SORT the item goes at the end; with it, the list box asks the owner where with WM_COMPAREITEM. On a list box with strings, pData would be read as a string pointer.

Returns the index of the new item, or LB_ERR / LB_ERRSPACE.

Example

ListBox.AddItemData( hCtrl, 111 )

Microsoft Learn: LB_ADDSTRING

InsertItemData

function InsertItemData( byval hListBox as HWND, byval index as long, byval pData as LONG_PTR ) as long

Inserts an item with item data pData before item index of an owner-drawn list box without LBS_HASSTRINGS, or at the end when index is -1.

Returns the index of the new item, or LB_ERR / LB_ERRSPACE.

Example

ListBox.InsertItemData( hCtrl, 0, 333 )

Microsoft Learn: LB_INSERTSTRING

FindItemData

function FindItemData( byval hListBox as HWND, byval indexStart as long, byval pData as LONG_PTR ) as long

Finds the first item whose item data is pData in an owner-drawn list box without LBS_HASSTRINGS. indexStart works as for FindString. With LBS_SORT the list box asks the owner to compare with WM_COMPAREITEM instead.

Returns the index of the item found, or LB_ERR.

Example

dim i as long = ListBox.FindItemData( hCtrl, -1, 222 )

Microsoft Learn: LB_FINDSTRING

SelectItemData

function SelectItemData( byval hListBox as HWND, byval indexStart as long, byval pData as LONG_PTR ) as long

Finds the item whose item data is pData, as FindItemData does, and selects it. Single-selection list boxes only.

Returns the index of the item selected, or LB_ERR.

Example

ListBox.SelectItemData( hCtrl, -1, 111 )

Microsoft Learn: LB_SELECTSTRING

GetCurSel

function GetCurSel( byval hListBox as HWND ) as long

Returns the current item. In a single-selection list box that is the selected item. In an LBS_MULTIPLESEL list box it is the caret item, the one with the focus rectangle, whether it is selected or not; in an LBS_EXTENDEDSEL list box Windows also returns the focused item. Use GetSel or GetSelItems to read a multiple selection.

Returns the index, or LB_ERR when nothing is selected in a single-selection list box.

Example

dim i as long = ListBox.GetCurSel( hCtrl )
if i = LB_ERR then print "nothing selected"

Microsoft Learn: LB_GETCURSEL

SetCurSel

function SetCurSel( byval hListBox as HWND, byval index as long ) as long

Selects item index of a single-selection list box, scrolling it into view and deselecting the item selected before. -1 clears the selection. A multiple-selection list box refuses it.

Returns index, or LB_ERR on failure and when index is -1.

Example

ListBox.SetCurSel( hCtrl, 0 )

Microsoft Learn: LB_SETCURSEL

GetSelect

function GetSelect( byval hListBox as HWND, byval startIndex as long = 0 ) as long

Returns the first selected item at or after startIndex, in an LBS_EXTENDEDSEL list box. Call it again from the index found plus one to walk the whole selection. Any other list box returns the same as GetCurSel and startIndex is ignored; in an LBS_MULTIPLESEL list box that is the caret item, which may not be selected.

Returns the index, or -1 when no selected item is found. With items 1 to 3 selected, GetSelect( h ) is 1, GetSelect( h, 2 ) is 2 and GetSelect( h, 4 ) is -1.

Example

dim i as long = ListBox.GetSelect( hCtrl )
while i >= 0
    print ListBox.GetText( hCtrl, i )
    i = ListBox.GetSelect( hCtrl, i + 1 )
wend

GetSel

function GetSel( byval hListBox as HWND, byval Index as long ) as boolean

Returns whether item Index is selected. Works in every kind of list box.

Returns true when it is selected; false when it is not or is not an item.

Example

if ListBox.GetSel( hCtrl, 2 ) then print "item 2 is selected"

Microsoft Learn: LB_GETSEL

SetSel

function SetSel( byval hListBox as HWND, byval fSelect as boolean, byval index as long = -1 ) as long

Selects (fSelect true) or deselects item index of an LBS_EXTENDEDSEL list box; -1, the default, means every item. Any other list box gets SetCurSel with index, and fSelect is ignored: a single-selection list box selects index even when fSelect is false (-1 clears its selection), and an LBS_MULTIPLESEL list box refuses the call and returns LB_ERR.

Parameter	Meaning
`hListBox`	The list box.
`fSelect`	`true` to select, `false` to deselect (extended selection only).
`index`	The item, or -1 for all.

Returns LB_ERR on failure; otherwise 0 (extended selection) or index.

Example

ListBox.SetSel( hCtrl, true, 5 )     ' add item 5 to the selection
ListBox.SetSel( hCtrl, false )       ' deselect everything

Microsoft Learn: LB_SETSEL

SelectString

function SelectString( byval hListBox as HWND, byval start as long, byval pwszText as wstring ptr ) as long
function SelectString( byval hListBox as HWND, byval index as long = -1 ) as long

The first form finds the first item whose text begins with pwszText, ignoring case and starting after item start (-1 for the top), and selects it, scrolling it into view. Single-selection list boxes only.

The second form selects by index, not by text: in an LBS_EXTENDEDSEL list box it adds item index to the selection (-1, the default, selects every item); in any other it calls SetCurSel with index.

Returns the index of the item selected, or LB_ERR (first form); 0 or index, or LB_ERR (second form).

Example

ListBox.SelectString( hCtrl, -1, "Ba" )   ' selects "Banana"
ListBox.SelectString( hCtrl, 3 )          ' selects item 3

Microsoft Learn: LB_SELECTSTRING

UnselectString

function UnselectString( byval hListBox as HWND, byval index as long = -1 ) as long

Deselects item index of an LBS_EXTENDEDSEL list box; -1, the default, deselects every item. Any other list box clears its whole selection, whatever index is.

Returns 0 in an extended-selection list box, LB_ERR on failure. In any other list box it returns LB_ERR (-1) also when the selection was cleared.

Example

ListBox.UnselectString( hCtrl, 2 )

Microsoft Learn: LB_SETSEL

GetSelCount

function GetSelCount( byval hListBox as HWND ) as long

Returns the number of selected items in a multiple-selection list box.

Returns the count, or LB_ERR in a single-selection list box.

Example

print ListBox.GetSelCount( hCtrl ); " selected"

Microsoft Learn: LB_GETSELCOUNT

GetSelItems

function GetSelItems( byval hListBox as HWND, byval items as DWORD, byval prgItems as long ptr ) as long

Reads the indexes of the selected items of a multiple-selection list box, in ascending order, into an array of items longs.

Parameter	Meaning
`hListBox`	The list box.
`items`	How many indexes the array holds.
`prgItems`	The first element of the array.

Returns the number of indexes written, or LB_ERR in a single-selection list box.

Example

dim n as long = ListBox.GetSelCount( hCtrl )
if n > 0 then
    dim sel(0 to n - 1) as long
    n = ListBox.GetSelItems( hCtrl, n, @sel(0) )
end if

Microsoft Learn: LB_GETSELITEMS

SelItemRange

function SelItemRange( byval hListBox as HWND, byval fSel as boolean, byval startIndex as short, byval endIndex as short ) as long

Selects (fSel true) or deselects items startIndex to endIndex of a multiple-selection list box. The indexes are 16-bit; use SelItemRangeEx beyond item 32767.

Returns 0, or LB_ERR on failure.

Example

ListBox.SelItemRange( hCtrl, true, 0, 2 )

Microsoft Learn: LB_SELITEMRANGE

SelItemRangeEx

function SelItemRangeEx( byval hListBox as HWND, byval startIndex as long, byval endIndex as long ) as long

Selects items startIndex to endIndex of a multiple-selection list box. When startIndex is greater than endIndex, the items from endIndex to startIndex are deselected instead.

Returns 0, or LB_ERR on failure.

Example

ListBox.SelItemRangeEx( hCtrl, 1, 3 )   ' select 1 to 3
ListBox.SelItemRangeEx( hCtrl, 3, 1 )   ' deselect them

Microsoft Learn: LB_SELITEMRANGEEX

GetAnchorIndex

function GetAnchorIndex( byval hListBox as HWND ) as long

Returns the anchor item of a multiple-selection list box: the item a Shift-click selection extends from to the caret item.

Returns the index, or -1 when there is none yet.

Example

print "anchor"; ListBox.GetAnchorIndex( hCtrl )

Microsoft Learn: LB_GETANCHORINDEX

SetAnchorIndex

function SetAnchorIndex( byval hListBox as HWND, byval index as long ) as long

Sets the anchor item of a multiple-selection list box.

Returns 0, or LB_ERR on failure.

Example

ListBox.SetAnchorIndex( hCtrl, 1 )

Microsoft Learn: LB_SETANCHORINDEX

GetCaretIndex

function GetCaretIndex( byval hListBox as HWND ) as long

Returns the item that has the focus rectangle, selected or not. In a single-selection list box it is the selected item, or 0.

Returns the index.

Example

print "focus on item"; ListBox.GetCaretIndex( hCtrl )

Microsoft Learn: LB_GETCARETINDEX

SetCaretIndex

function SetCaretIndex( byval hListBox as HWND, byval index as long, byval fVisibility as boolean = false ) as long

Moves the focus rectangle of a multiple-selection list box to item index and scrolls it into view: wholly with fVisibility false (the default), partly with true.

Returns 0, or LB_ERR on failure.

Example

ListBox.SetCaretIndex( hCtrl, 3 )

Microsoft Learn: LB_SETCARETINDEX

GetTopIndex

function GetTopIndex( byval hListBox as HWND ) as long

Returns the first visible item: 0 until the list is scrolled.

Returns the index.

Example

print "top item"; ListBox.GetTopIndex( hCtrl )

Microsoft Learn: LB_GETTOPINDEX

SetTopIndex

function SetTopIndex( byval hListBox as HWND, byval index as long ) as long

Scrolls the list so that item index is at the top, or as near as the end of the list allows.

Returns 0, or LB_ERR on failure.

Example

ListBox.SetTopIndex( hCtrl, ListBox.GetCount( hCtrl ) - 1 )

Microsoft Learn: LB_SETTOPINDEX

GetItemHeight

function GetItemHeight( byval hListBox as HWND, byval index as long ) as long

Returns the height of the items in pixels. index matters only with LBS_OWNERDRAWVARIABLE, where every item has its own height; pass 0 otherwise.

Returns the height, or LB_ERR.

Example

print "rows are"; ListBox.GetItemHeight( hCtrl, 0 ); " pixels high"

Microsoft Learn: LB_GETITEMHEIGHT

SetItemHeight

function SetItemHeight( byval hListBox as HWND, byval index as long, byval nHeight as DWORD ) as long

Sets the height of the items to nHeight pixels (at most 255). With LBS_OWNERDRAWVARIABLE it sets the height of item index only; otherwise of all items, and index is ignored.

Returns LB_ERR when the height is out of range, another value otherwise.

Example

ListBox.SetItemHeight( hCtrl, 0, 24 )

Microsoft Learn: LB_SETITEMHEIGHT

GetItemRect

function GetItemRect( byval hListBox as HWND, byval index as long, byval prc as RECT ptr ) as long
function GetItemRect( byval hListBox as HWND, byval index as long, byref rc as RECT ) as long
function GetItemRect( byval hListBox as HWND, byval index as long ) as ( long, long, long, long )

Returns the rectangle item index takes up in the list box, in its client coordinates, as it is displayed now: an item scrolled out of view lies outside the client area.

Returns LB_ERR on failure (first two forms), or ( left, top, right, bottom ); afterwards the third form leaves GetLastError() at 1 when the call succeeded, and at LB_ERR with four zeros when index is not an item.

Example

var (l, t, r, b) = ListBox.GetItemRect( hCtrl, 1 )
if GetLastError() = 1 then print "item 1 is"; b - t; " pixels high"

Microsoft Learn: LB_GETITEMRECT

ItemFromPoint

function ItemFromPoint( byval hListBox as HWND, byval x as short, byval y as short ) as long

Returns the item nearest the point (x, y), in the list box's client coordinates.

Returns two values in one: the index in the low word and, in the high word, 0 when the point is over an item and 1 when it is not. In a list box of 5 items, a point below the last item returns &h10004, whether it is inside the control or outside it.

Example

dim r as long = ListBox.ItemFromPoint( hCtrl, 10, 40 )
if HIWORD( r ) = 0 then print "over item"; LOWORD( r )

Microsoft Learn: LB_ITEMFROMPOINT

GetListBoxInfo

function GetListBoxInfo( byval hListBox as HWND ) as long

Returns how many items fit in each column of the list box, which is what a multicolumn list box (LBS_MULTICOLUMN) wraps at.

Returns the number of items per column.

Example

print ListBox.GetListBoxInfo( hCtrl ); " items per column"

Microsoft Learn: LB_GETLISTBOXINFO

SetColumnWidth

sub SetColumnWidth( byval hListBox as HWND, byval nWidth as DWORD )

Sets the width, in pixels, of every column of a multicolumn list box (LBS_MULTICOLUMN).

Example

ListBox.SetColumnWidth( hCtrl, 120 )

Microsoft Learn: LB_SETCOLUMNWIDTH

SetTabStops

sub SetTabStops( byval hListBox as HWND, byval cTabs as long, byval prgTabs as long ptr )

Sets where a tab character in an item's text moves to, for a list box created with LBS_USETABSTOPS. The positions are in dialog template units (a quarter of the average character width). cTabs 0 with prgTabs NULL sets a stop every 32 units; cTabs 1 sets stops at every multiple of prgTabs[0].

Parameter	Meaning
`hListBox`	The list box.
`cTabs`	The number of tab stops.
`prgTabs`	The first of `cTabs` positions, in ascending order.

Example

dim tabs(0 to 1) as long = { 80, 140 }
ListBox.SetTabStops( hCtrl, 2, @tabs(0) )
ListBox.AddString( hCtrl, "Apple" & chr(9) & "0.95" & chr(9) & "kg" )

Microsoft Learn: LB_SETTABSTOPS

GetHorizontalExtent

function GetHorizontalExtent( byval hListBox as HWND ) as long

Returns the width, in pixels, by which a list box with a horizontal scroll bar can be scrolled sideways. It is 0 until SetHorizontalExtent sets it.

Returns the width.

Example

print "scrollable width"; ListBox.GetHorizontalExtent( hCtrl )

Microsoft Learn: LB_GETHORIZONTALEXTENT

SetHorizontalExtent

sub SetHorizontalExtent( byval hListBox as HWND, byval cxExtent as long )

Sets the width, in pixels, by which the list box can be scrolled sideways. A list box does not work it out itself: when the widest item is wider than the control, set this to its width and the horizontal scroll bar (WS_HSCROLL) appears; when the control is wider, the scroll bar is hidden.

Example

ListBox.SetHorizontalExtent( hCtrl, 600 )

Microsoft Learn: LB_SETHORIZONTALEXTENT

CalcHorizontalExtent

function CalcHorizontalExtent( byval hListBox as HWND ) as long

Measures the text of every item and returns the width of the widest, for SetHorizontalExtent.

The text is measured in the list box's device context as GetDC returns it, with the system font selected rather than the font the control draws with, so the width differs from what the user sees unless the control uses the system font. Each item's text is read into a buffer one character too short for the terminating null, which the list box writes past its end; in testing a program that called this crashed later, in unrelated code. Measuring the items yourself, with the control's font (WM_GETFONT) selected into the DC, avoids both.

Returns the width of the widest item, in logical units of that device context.

Example

dim cx as long = ListBox.CalcHorizontalExtent( hCtrl )
ListBox.SetHorizontalExtent( hCtrl, cx )

Microsoft Learn: GetTextExtentPoint32W

GetLocale

function GetLocale( byval hListBox as HWND ) as long

Returns the locale a sorted list box compares strings with: the language identifier in the low word and the country code in the high word.

Returns the locale.

Example

print "sorting language &h"; hex( LOWORD( ListBox.GetLocale( hCtrl ) ) )

Microsoft Learn: LB_GETLOCALE

SetLocale

function SetLocale( byval hListBox as HWND, byval wLocaleID as DWORD ) as long

Sets the locale a sorted list box compares strings with when items are added.

Returns the previous locale, or LB_ERR.

Example

ListBox.SetLocale( hCtrl, &h0409 )   ' English (United States)

Microsoft Learn: LB_SETLOCALE

Enable

function Enable( byval hListBox as HWND ) as boolean

Enables the list box, so that it takes mouse and keyboard input again.

Returns true when the list box was disabled before the call, false when it was already enabled.

Example

ListBox.Enable( hCtrl )

Microsoft Learn: EnableWindow

Disable

function Disable( byval hListBox as HWND ) as boolean

Disables the list box: it is greyed out and ignores the mouse and the keyboard.

Returns true when the list box was enabled before the call, false when it was already disabled (the opposite of what Button.Disable returns).

Example

if ListBox.Disable( hCtrl ) then print "was enabled"

Microsoft Learn: EnableWindow

SetDarkMode

function SetDarkMode( byval hListBox as HWND ) as HRESULT

Gives the list box the DarkMode_Explorer theme. Only the scroll bars change; the item colours come from the parent's WM_CTLCOLORLISTBOX handling.

Returns S_OK on success.

Example

if AppsUseDarkMode() then ListBox.SetDarkMode( hCtrl )

Microsoft Learn: SetWindowTheme

RemoveDarkMode

function RemoveDarkMode( byval hListBox as HWND ) as HRESULT

Gives the scroll bars the default theme again.

Returns S_OK on success.

Example

ListBox.RemoveDarkMode( hCtrl )

Microsoft Learn: SetWindowTheme

SysWin Gui ListBox

ListBox

Importing

Example

Functions

Reference

AddString

InsertString

DeleteString

ResetContent

ReplaceString

SetText

AddFile

Dir

InitStorage

SetCount

GetCount

GetText

GetTextLen

FindString

FindStringExact

GetItemData

SetItemData

AddItemData

InsertItemData

FindItemData

SelectItemData

GetCurSel

SetCurSel

GetSelect

GetSel

SetSel

SelectString

UnselectString

GetSelCount

GetSelItems

SelItemRange

SelItemRangeEx

GetAnchorIndex

SetAnchorIndex

GetCaretIndex

SetCaretIndex

GetTopIndex

SetTopIndex

GetItemHeight

SetItemHeight

GetItemRect

ItemFromPoint

GetListBoxInfo

SetColumnWidth

SetTabStops

GetHorizontalExtent

SetHorizontalExtent

CalcHorizontalExtent

GetLocale

SetLocale

Enable

Disable

SetDarkMode

RemoveDarkMode

See also

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!