SysWin Gui ListView

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

ListView

Adds columns and rows to a list view and reads, selects, sorts and groups its items.

A list view shows a collection of items in one of five views: large icons, small icons, a list, a report (details) with one column per field, or tiles. Every function in the ListView namespace takes the control's handle first and sends it one message, or a few.

The model the reader needs:

• Items and subitems. Items (rows) are numbered from 0. In report view each item has one subitem per column, numbered like the columns: subitem 0 is the item's own text, shown in column 0. Deleting or inserting an item renumbers the items after it; sorting renumbers all of them. An item keeps an application value (lParam) and, with visual styles, a unique ID (MapIndexToID) that survive renumbering.
• Header. Report view draws its column titles with a separate header control, reached with GetHeader; several functions here work on it directly.
• Image lists. The control draws icons from image lists you give it with SetImageList. It destroys them when it is destroyed unless it has the LVS_SHAREIMAGELISTS style, in which case they stay yours to destroy.
• Visual styles. Groups, tiles, footers, item IDs and GetView/SetView need version 6 of the common controls: call EnableVisualStyles() at start-up, or ship a manifest. Without it these calls fail or return 0.
• Text. Text goes in and out as Unicode, with four exceptions noted on their entries: the structure forms of GetItem, SetItem, InsertColumn and the background-image calls send the ANSI messages.

CWindow.AddControl( "ListView", ... ) creates a report-view list view with a client edge and the styles LVS_SHOWSELALWAYS, LVS_SHAREIMAGELISTS, LVS_AUTOARRANGE, LVS_EDITLABELS and LVS_ALIGNTOP. What the user does arrives at the parent window as WM_NOTIFY messages with LVN_* codes.

Importing

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

Example

A report view of planets with three columns and full-row selection; selecting a row puts its name in the caption:

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

#define IDC_LIST 1001

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 )
    EnableVisualStyles()
    dim pWindow as CWindow = "ListViewDemo"
    dim hWin as HWND = pWindow.Create( NULL, "ListView", @WndProc )
    SetWindowClientSizeForDpi( hWin, 420, 240 )
    CenterWindow( hWin )
    dim hList as HWND = pWindow.AddControl( "ListView", hWin, IDC_LIST, "", 10, 10, 400, 220 )
    ListView.SetExtendedStyle( hList, LVS_EX_FULLROWSELECT or LVS_EX_GRIDLINES )
    ListView.AddColumn( hList, 0, "Planet", 100 )
    ListView.AddColumn( hList, 1, "Moons", 80, LVCFMT_RIGHT )
    ListView.AddColumn( hList, 2, "Kind", 100 )
    dim names(0 to 3) as ustring = { "Mercury", "Venus", "Earth", "Mars" }
    dim moons(0 to 3) as ustring = { "0", "0", "1", "2" }
    for i as long = 0 to 3
        ListView.AddItem( hList, i, 0, names(i) )
        ListView.SetItemText( hList, i, 1, moons(i) )
        ListView.SetItemText( hList, i, 2, wstr("rocky") )
    next
    ListView.AutoSizeHeader( hList )
    ListView.SelectItem( hList, 0 )
    SetFocus( hList )
    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_NOTIFY
            dim pnmv as NMLISTVIEW ptr = cast(NMLISTVIEW ptr, lParam)
            if pnmv->hdr.idFrom = IDC_LIST andalso pnmv->hdr.code = LVN_ITEMCHANGED then
                if ( pnmv->uNewState and LVIS_SELECTED ) <> 0 then
                    dim wszName as wstring * 64
                    ListView.GetItemText( pnmv->hdr.hwndFrom, pnmv->iItem, 0, @wszName, 64 )
                    dim ustrName as ustring = wszName
                    SetWindowText( hwnd, "Selected: " & ustrName )
                end if
            end if
            return 0
        case WM_DESTROY
            PostQuitMessage( 0 )
            return 0
    end select
    return DefWindowProcW( hwnd, uMsg, wParam, lParam )
end function

end main()

Functions

Function	Does
Columns
AddColumn	Adds a column with a title, a width and an alignment.
InsertColumn	Inserts a column, from a title or from a column structure.
DeleteColumn	Removes a column.
GetColumn	Reads a column's attributes.
SetColumn	Changes a column's attributes.
GetColumnText	Returns a column's title.
GetColumnCount	Returns the number of columns.
GetColumnWidth	Returns a column's width.
SetColumnWidth	Sets a column's width.
FitContent	Sizes a column to its widest item.
FitHeader	Sizes a column to its title, or the last one to the remaining width.
AutoSizeColumns	Sizes every column to its widest item.
AutoSizeHeader	Sizes every column to its title.
GetColumnOrderArray	Reads the left-to-right order of the columns.
SetColumnOrderArray	Sets the left-to-right order of the columns.
GetColumnOrder	Returns where one column is shown.
GetOrderArray	Reads the column order from the header control.
GetSelectedColumn	Returns the highlighted column.
SetSelectedColumn	Highlights a column.
Header
GetHeader	Returns the header control.
GetHeaderText	Returns a column title, read from the header control.
MakeHeaderFlat	Switches the header between button-like and flat titles.
SetHeaderFont	Creates a font and gives it to the header.
ModifyHeaderFont	Gives the header a changed copy of its font.
Items
AddItem	Inserts an item with a text.
InsertItem	Inserts an item, from a text or from an item structure.
AppendItem	Adds an item at the end.
DeleteItem	Removes an item.
DeleteAllItems	Removes every item.
GetItem	Reads an item's attributes.
SetItem	Changes an item's attributes.
GetItemCount	Returns the number of items.
SetItemCount	Reserves room for items, or sets a virtual list's count.
SetItemCountEx	Sets a virtual list's count, with flags.
GetItemState	Returns state bits of an item.
SetItemState	Changes state bits of an item or of all items.
Update	Updates an item and rearranges the control.
RedrawItems	Marks a range of items for repainting.
MapIndexToID	Returns the unique ID of an item.
MapIDToIndex	Returns the current index of an item ID.
GetCallbackMask	Returns the states the application keeps itself.
SetCallbackMask	Sets the states the application keeps itself.
Text
GetItemText	Copies the text of an item or subitem into a buffer.
SetItemText	Sets the text of an item or subitem.
GetStringWidth	Measures a text in the control's font.
EditLabel	Starts in-place editing of an item's text.
CancelEditLabel	Cancels in-place editing.
GetEditControl	Returns the edit control used for in-place editing.
GetEmptyText	Reads the text shown when the control is empty.
Searching
FindItem	Finds an item by text, lParam or position.
FindString	Finds the first item whose text starts with a string.
GetNextItem	Finds the next item with given properties.
GetNextItemIndex	Finds the next item with given properties, by item and group.
GetISearchString	Returns what the user has typed to find an item.
GetISearchStringLen	Returns the length of that search text.
Selection and focus
GetSelection	Returns the first selected item.
GetFocusedItem	Returns the item with the focus.
GetSelectedCount	Returns the number of selected items.
SelectItem	Selects an item and gives it the focus.
SelectAllItems	Selects every item.
UnselectItem	Deselects an item.
UnselectAllItems	Deselects every item and removes the focus.
GetSelectionMark	Returns the selection mark.
SetSelectionMark	Sets the selection mark.
SetItemIndexState	Changes the state of an item named by item and group.
GetHotItem	Returns the item under the pointer when hot tracking.
SetHotItem	Sets the hot item.
GetHotCursor	Returns the cursor shown over hot items.
SetHotCursor	Sets the cursor shown over hot items.
GetHoverTime	Returns the hover time before an item is selected.
SetHoverTime	Sets the hover time before an item is selected.
Check boxes
GetCheckState	Reads whether an item's check box is checked.
SetCheckState	Checks or unchecks an item's check box.
Styles and view
GetExtendedStyle	Returns the LVS_EX_* styles.
SetExtendedStyle	Replaces the LVS_EX_* styles.
SetExtendedStyleEx	Changes some LVS_EX_* styles.
GetView	Returns the current view.
SetView	Switches to another view.
SetDarkMode	Gives the control the dark Explorer theme.
RemoveDarkMode	Restores the default theme.
Colours and background
GetBkColor	Returns the background colour.
SetBkColor	Sets the background colour.
GetTextColor	Returns the text colour.
SetTextColor	Sets the text colour.
GetTextBkColor	Returns the text background colour.
SetTextBkColor	Sets the text background colour.
GetOutlineColor	Returns the border colour of LVS_EX_BORDERSELECT.
SetOutlineColor	Sets the border colour of LVS_EX_BORDERSELECT.
GetBkImage	Reads the background image.
SetBkImage	Sets the background image.
Images
GetImageList	Returns one of the control's image lists.
SetImageList	Gives the control an image list.
CreateDragImage	Creates a drag image for an item.
Layout, position and scrolling
ApproximateViewRect	Estimates the size needed for a number of items.
Arrange	Arranges the items in icon view.
GetCountPerPage	Returns how many items fit in the visible area.
GetTopIndex	Returns the first visible item.
EnsureVisible	Scrolls an item into view.
IsItemVisible	Reads whether an item is visible.
Scroll	Scrolls the content.
GetOrigin	Returns the view origin.
GetViewRect	Returns the rectangle around all items.
GetItemRect	Returns the rectangle of an item or part of it.
GetSubItemRect	Returns the rectangle of a subitem.
GetItemIndexRect	Returns the rectangle of a subitem named by item and group.
GetItemPosition	Returns where an item is.
SetItemPosition	Moves an item in icon view.
SetItemPosition32	Moves an item in icon view, with 32-bit coordinates.
GetItemSpacing	Returns the spacing between items.
GetItemHorizontalSpacing	Returns the horizontal spacing between items.
GetItemVerticalSpacing	Returns the vertical spacing between items.
SetIconSpacing	Sets the spacing between icons.
GetWorkAreas	Reads the working areas.
SetWorkAreas	Sets the working areas.
GetNumberOfWorkAreas	Meant to return the number of working areas.
Hit testing
HitTest	Finds the item at a point.
HitTestEx	Finds the item, subitem and group at a point.
SubItemHitTest	Finds the item and subitem at a point.
SubItemHitTestEx	Finds the item, subitem and group at a point.
Insertion mark
GetInsertMark	Reads where the insertion mark is.
SetInsertMark	Places or removes the insertion mark.
GetInsertMarkColor	Returns the insertion mark's colour.
SetInsertMarkColor	Sets the insertion mark's colour.
GetInsertMarkRect	Returns the rectangle of the insertion mark.
InsertMarkHitTest	Finds the insertion point nearest a point.
Sorting
SortItems	Sorts the items with a function comparing lParam values.
SortItemsEx	Sorts the items with a function comparing indexes.
SortGroups	Sorts the groups with a function comparing group IDs.
Groups
EnableGroupView	Turns group view on or off.
IsGroupViewEnabled	Reads whether group view is on.
InsertGroup	Inserts a group.
InsertGroupSorted	Inserts a group in sorted order.
RemoveGroup	Removes a group.
RemoveAllGroups	Removes every group.
HasGroup	Reads whether a group ID exists.
GetGroupCount	Returns the number of groups.
GetGroupInfo	Reads a group's attributes, by ID.
GetGroupInfoByIndex	Reads a group's attributes, by index.
SetGroupInfo	Changes a group's attributes.
GetGroupState	Returns state bits of a group.
SetGroupState	Changes state bits of a group.
GetGroupMetrics	Reads how groups are drawn.
SetGroupMetrics	Sets how groups are drawn.
GetGroupRect	Returns the rectangle of a group or part of it.
GetFocusedGroup	Returns the group with the focus.
GetGroupHeaderImageList	Returns the group header image list.
SetGroupHeaderImageList	Sets the group header image list.
Tiles
GetTileInfo	Reads which subitems a tile shows.
SetTileInfo	Sets which subitems a tile shows.
GetTileViewInfo	Reads the tile view settings.
SetTileViewInfo	Changes the tile view settings.
Footer
GetFooterInfo	Reads the footer's attributes.
GetFooterItem	Reads a footer item.
GetFooterItemRect	Returns the rectangle of a footer item.
GetFooterRect	Returns the rectangle of the footer.
Tooltips
GetToolTips	Returns the tooltip control.
SetToolTips	Gives the control another tooltip control.
SetInfoTip	Sets an item's tooltip text.
GetTooltipsFont	Returns the tooltip control's font.
SetTooltipsFont	Sets the tooltip control's font.

Reference

AddColumn

function AddColumn( byval hListView as HWND, byval iCol as long, byref wszText as wstring, byval nWidth as long, byval nFormat as long = LVCFMT_LEFT ) as long

Inserts a column at position iCol with the title wszText, nWidth pixels wide. In report view the column shows subitem iCol of every item. The leftmost column is always left-aligned, whatever nFormat says.

Parameter	Meaning
hListView	The list view.
iCol	Where to insert the column, from 0. A value past the last column appends it.
wszText	The column title: a literal, a ustring or a wstring.
nWidth	The width in pixels.
nFormat	LVCFMT_LEFT (the default), LVCFMT_RIGHT or LVCFMT_CENTER.

Returns the index of the new column, or -1 on failure.

Example

ListView.AddColumn( hCtrl, 0, "Name", 160 )
ListView.AddColumn( hCtrl, 1, "Size", 80, LVCFMT_RIGHT )

Microsoft Learn: LVM_INSERTCOLUMN

InsertColumn

function InsertColumn overload( byval hListView as HWND, byval iCol as long, byval pcol as LVCOLUMN ptr ) as long
function InsertColumn overload( byval hListView as HWND, byval iCol as long, byref col as LVCOLUMN ) as long
function InsertColumn( byval hListView as HWND, byval iCol as long, byref wszText as wstring, byval nWidth as long, byval nFormat as long = LVCFMT_LEFT ) as long

The form with a title is the same as AddColumn.

The structure forms pass your column structure as it is. They take LVCOLUMN, which is the ANSI LVCOLUMNA structure, and send the ANSI message, so pszText must point to a zstring. They return -1 at once for a null structure.

Returns the index of the new column, or -1 on failure.

Example

dim col as LVCOLUMN
dim szTitle as zstring * 16 = "Date"
col.mask = LVCF_TEXT or LVCF_WIDTH : col.pszText = @szTitle : col.cx = 100
ListView.InsertColumn( hCtrl, 2, col )

Microsoft Learn: LVM_INSERTCOLUMN

DeleteColumn

function DeleteColumn( byval hListView as HWND, byval iCol as long ) as boolean

Removes column iCol; the columns after it move left one index.

Returns true on success.

Example

ListView.DeleteColumn( hCtrl, 1 )

Microsoft Learn: LVM_DELETECOLUMN

GetColumn

function GetColumn overload( byval hListView as HWND, byval iCol as long, byval pcol as LVCOLUMNW ptr ) as boolean
function GetColumn overload( byval hListView as HWND, byval iCol as long, byref col as LVCOLUMNW ) as boolean
function GetColumn overload( byval hListView as HWND, byval iCol as long ) as LVCOLUMNW

Reads the attributes of column iCol that the structure's mask asks for (LVCF_WIDTH, LVCF_FMT, LVCF_TEXT with a buffer in pszText and its size in cchTextMax …). The form that returns the structure sends it with an empty mask, so it reads nothing; fill a structure yourself and pass it.

Returns true on success, or the structure.

Example

dim col as LVCOLUMNW
col.mask = LVCF_WIDTH or LVCF_FMT
if ListView.GetColumn( hCtrl, 1, col ) then print "width"; col.cx

Microsoft Learn: LVM_GETCOLUMN

SetColumn

function SetColumn overload( byval hListView as HWND, byval iCol as long, byval pcol as LVCOLUMNW ptr ) as boolean
function SetColumn overload( byval hListView as HWND, byval iCol as long, byref col as LVCOLUMNW ) as boolean

Changes the attributes of column iCol that the structure's mask names.

Returns true on success.

Example

dim col as LVCOLUMNW
col.mask = LVCF_TEXT : col.pszText = @wstr("Size (KB)")
ListView.SetColumn( hCtrl, 1, col )

Microsoft Learn: LVM_SETCOLUMN

GetColumnText

function GetColumnText( byval hListView as HWND, byval iCol as long, byval cchTextMax as long = 260 ) as ustring

Returns the title of column iCol, reading at most cchTextMax characters.

Returns the title in a buffer-sized ustring, or an empty string on failure.

Example

dim ustrTitle as ustring = ListView.GetColumnText( hListView, 1 )
print ustrTitle

Microsoft Learn: LVM_GETCOLUMN

GetColumnCount

function GetColumnCount( byval hListView as HWND ) as long

Returns the number of columns, counted on the header control.

Returns the count, or 0 when the control has no header.

Example

print "columns:"; ListView.GetColumnCount( hCtrl )

Microsoft Learn: HDM_GETITEMCOUNT

GetColumnWidth

function GetColumnWidth( byval hListView as HWND, byval iCol as long ) as long

Returns the width of column iCol in report view. In list view, where all columns are as wide, iCol is ignored.

Returns the width in pixels, or 0 on failure.

Example

print "width:"; ListView.GetColumnWidth( hCtrl, 0 )

Microsoft Learn: LVM_GETCOLUMNWIDTH

SetColumnWidth

function SetColumnWidth( byval hListView as HWND, byval iCol as long, byval cx as long ) as boolean

Sets the width of column iCol in report view, or of every column in list view (pass 0). cx is a width in pixels, or LVSCW_AUTOSIZE (fit the widest item) or LVSCW_AUTOSIZE_USEHEADER (fit the title; the last column fills the rest of the control).

Returns true on success.

Example

ListView.SetColumnWidth( hCtrl, 0, 200 )

Microsoft Learn: LVM_SETCOLUMNWIDTH

FitContent

function FitContent( byval hListView as HWND, byval iCol as long ) as boolean

Sizes column iCol to its widest item: SetColumnWidth with LVSCW_AUTOSIZE.

Returns true on success.

Example

ListView.FitContent( hCtrl, 0 )

Microsoft Learn: LVM_SETCOLUMNWIDTH

FitHeader

function FitHeader( byval hListView as HWND, byval iCol as long ) as boolean

Sizes column iCol to its title: SetColumnWidth with LVSCW_AUTOSIZE_USEHEADER. Used on the last column, it makes that column fill the rest of the control's width.

Returns true on success.

Example

ListView.FitHeader( hCtrl, ListView.GetColumnCount( hCtrl ) - 1 )

Microsoft Learn: LVM_SETCOLUMNWIDTH

AutoSizeColumns

function AutoSizeColumns( byval hListView as HWND ) as boolean

Calls FitContent on every column.

Returns the result for the last column; false when there are no columns or no header.

Example

ListView.AutoSizeColumns( hCtrl )

Microsoft Learn: LVM_SETCOLUMNWIDTH

AutoSizeHeader

function AutoSizeHeader( byval hListView as HWND ) as boolean

Calls FitHeader on every column, so each fits its title and the last fills the rest of the control.

Returns the result for the last column; false when there are no columns or no header.

Example

ListView.AutoSizeHeader( hCtrl )

Microsoft Learn: LVM_SETCOLUMNWIDTH

GetColumnOrderArray

function GetColumnOrderArray( byval hListView as HWND, byval iCount as long, byval lpiArray as long ptr ) as long

Fills lpiArray with the column indexes in the order they appear from left to right. The user can reorder columns when the control has LVS_EX_HEADERDRAGDROP.

Parameter	Meaning
iCount	The number of columns; the array must hold that many longs.
lpiArray	Receives the indexes.

Returns nonzero on success, 0 on failure.

Example

dim order(0 to 1) as long
if ListView.GetColumnOrderArray( hCtrl, 2, @order(0) ) then print "leftmost column:"; order(0)

Microsoft Learn: LVM_GETCOLUMNORDERARRAY

SetColumnOrderArray

sub SetColumnOrderArray( byval hListView as HWND, byval iCount as long, byval prgi as long ptr )

Shows the columns in the order the iCount indexes in prgi give, from left to right.

Example

dim order(0 to 1) as long = { 1, 0 }
ListView.SetColumnOrderArray( hCtrl, 2, @order(0) )

Microsoft Learn: LVM_SETCOLUMNORDERARRAY

GetColumnOrder

function GetColumnOrder( byval hListView as HWND, byval iCol as long ) as long

Returns the position, from the left and from 0, at which column iCol is shown. GetLastError() is nonzero afterwards when the header answered.

Returns the position, or 0 when the control has no header.

Example

print "column 1 is shown at"; ListView.GetColumnOrder( hCtrl, 1 )

Microsoft Learn: HDM_GETITEM

GetOrderArray

function GetOrderArray( byval hListView as HWND, byval iCount as DWORD, byval lpi as long ptr ) as long

Reads the left-to-right column order from the header control into lpi, which holds iCount longs. The result is the same as GetColumnOrderArray.

Returns nonzero on success; 0 on failure or when the control has no header.

Example

dim order(0 to 1) as long
ListView.GetOrderArray( hCtrl, 2, @order(0) )

Microsoft Learn: HDM_GETORDERARRAY

GetSelectedColumn

function GetSelectedColumn( byval hListView as HWND ) as UINT

Returns the column drawn highlighted, as sort-by-column lists do.

Returns the column index.

Example

print "highlighted column:"; clng( ListView.GetSelectedColumn( hCtrl ) )

Microsoft Learn: LVM_GETSELECTEDCOLUMN

SetSelectedColumn

sub SetSelectedColumn( byval hListView as HWND, byval iCol as long )

Highlights column iCol, typically the one the list is sorted by. -1 removes the highlight.

Example

ListView.SetSelectedColumn( hCtrl, 1 )

Microsoft Learn: LVM_SETSELECTEDCOLUMN

GetHeader

function GetHeader( byval hListView as HWND ) as HWND

Returns the header control that draws the column titles in report view. The functions of Header work on it.

Returns the header's handle, or NULL.

Example

dim hHeader as HWND = ListView.GetHeader( hCtrl )

Microsoft Learn: LVM_GETHEADER

GetHeaderText

function GetHeaderText( byval hListView as HWND, byval iCol as long, byval cchTextMax as long = MAX_PATH + 1 ) as ustring

Returns the title of column iCol, read from the header control, at most cchTextMax characters (a value below 1 means MAX_PATH + 1). As with GetColumnText the ustring keeps the buffer's length, cchTextMax + 1: cut it at the null character. GetLastError() is nonzero afterwards when the header answered.

Returns the title in a buffer-sized ustring; an empty string when the control has no header.

Example

dim ustrTitle as ustring = ListView.GetHeaderText( hCtrl, 0 )
ustrTitle = *cast( wstring ptr, strptr( ustrTitle ) )

Microsoft Learn: HDM_GETITEM

MakeHeaderFlat

sub MakeHeaderFlat( byval hListView as HWND )

Toggles the header's HDS_BUTTONS style: a header with button-like titles becomes flat, and a flat one gets buttons, so a second call undoes the first. It then asks the list view's parent to redraw its frame.

Example

ListView.MakeHeaderFlat( hCtrl )

Microsoft Learn: Header control styles

SetHeaderFont

function SetHeaderFont( byval hListView as HWND, byref wszFaceName as wstring, byval lPointSize as long, byval lWeight as long, byval bItalic as byte, byval bUnderline as byte, byval bStrikeOut as byte, byval bCharSet as byte ) as HFONT

Creates a font from the values given and gives it to the header control, which redraws. The point size is converted to pixels with the desktop's DPI.

The font is yours: delete it with DeleteObject once the header no longer uses it (after the control is destroyed, or after giving it another font). The header's previous font is not deleted.

Parameter	Meaning
wszFaceName	The typeface, such as "Segoe UI".
lPointSize	The size in points.
lWeight	FW_NORMAL, FW_BOLD or another weight from 0 to 1000.
bItalic, bUnderline, bStrikeOut	Nonzero for italic, underlined or struck-out text.
bCharSet	The character set, usually DEFAULT_CHARSET.

Returns the new font, or NULL when the control has no header or the font cannot be created.

Example

dim hFont as HFONT = ListView.SetHeaderFont( hCtrl, "Segoe UI", 10, FW_BOLD, 0, 0, 0, DEFAULT_CHARSET )

Microsoft Learn: CreateFontIndirectW

ModifyHeaderFont

function ModifyHeaderFont( byval hListView as HWND, byref wszFaceName as wstring, byval lPointSize as long, byval lWeight as long, byval bItalic as byte, byval bUnderline as byte, byval bStrikeOut as byte, byval bCharSet as byte ) as HFONT

Reads the header's current font, changes the values you pass that are not empty or zero, creates a font from the result and gives it to the header. Since zero means "leave as it is", it can turn italic, underline or strikeout on but not off. The header must have a font of its own; for a header that draws with the system font it returns NULL.

As with SetHeaderFont, the new font is yours to delete with DeleteObject, and the old one is not deleted.

Returns the new font, or NULL.

Example

dim hFont as HFONT = ListView.ModifyHeaderFont( hCtrl, "", 0, FW_BOLD, 0, 0, 0, 0 )   ' bold, the rest as it was

Microsoft Learn: WM_GETFONT

AddItem

function AddItem( byval hListView as HWND, byval iItem as long, byval iImage as long, byref wszText as wstring ) as long

Inserts an item with the text wszText at index iItem. An index past the end appends the item; the return value is the index it got. The item's other columns are empty until SetItemText fills them.

iImage is stored in the structure but not marked as set, so the item does not take that image; give it one afterwards with SetItem and LVIF_IMAGE.

Parameter	Meaning
iItem	Where to insert the item, from 0.
iImage	Not applied (see above).
wszText	The item's text: a literal, a ustring or a wstring.

Returns the index of the new item, or -1 on failure.

Example

dim i as long = ListView.AddItem( hCtrl, 0, 0, "Mercury" )
ListView.SetItemText( hCtrl, i, 1, wstr("0 moons") )

Microsoft Learn: LVM_INSERTITEM

InsertItem

function InsertItem overload( byval hListView as HWND, byval pitem as LVITEMW ptr ) as long
function InsertItem overload( byval hListView as HWND, byref item as LVITEMW ) as long
function InsertItem( byval hListView as HWND, byval iItem as long, byval iImage as long, byref wszText as wstring ) as long

The form with a text is the same as AddItem, iImage included. The structure forms send your LVITEMW as it is, with the Unicode message: set mask, iItem and the members mask names. They return -1 at once for a null structure.

Returns the index of the new item, or -1 on failure.

Example

dim lvi as LVITEMW
lvi.mask = LVIF_TEXT or LVIF_IMAGE or LVIF_PARAM
lvi.iItem = 0 : lvi.pszText = @wstr("Venus") : lvi.iImage = 1 : lvi.lParam = 2
ListView.InsertItem( hCtrl, lvi )

Microsoft Learn: LVM_INSERTITEM

AppendItem

function AppendItem( byval hListView as HWND, byval iImage as long, byval pwszText as wstring ptr ) as long

Adds an item with the text pwszText after the last one. As with AddItem, iImage is not applied.

Returns the index of the new item, or -1 on failure.

Example

ListView.AppendItem( hCtrl, 0, "Earth" )

Microsoft Learn: LVM_INSERTITEM

DeleteItem

function DeleteItem( byval hListView as HWND, byval i as long ) as boolean

Removes item i; the items after it move up one index. The parent receives LVN_DELETEITEM.

Returns true on success.

Example

dim iSel as long = ListView.GetSelection( hCtrl )
if iSel >= 0 then ListView.DeleteItem( hCtrl, iSel )

Microsoft Learn: LVM_DELETEITEM

DeleteAllItems

function DeleteAllItems( byval hListView as HWND ) as boolean

Removes every item. The columns stay.

Returns true on success.

Example

ListView.DeleteAllItems( hCtrl )

Microsoft Learn: LVM_DELETEALLITEMS

GetItem

function GetItem overload( byval hListView as HWND, byval pitem as LVITEMW ptr ) as boolean
function GetItem overload( byval hListView as HWND, byref item as LVITEMW ) as boolean

Reads the attributes of an item or subitem that the structure's mask asks for: set iItem, iSubItem and mask first.

Both forms send the ANSI message, although they take an LVITEMW. State, image, indent, lParam and group come back correctly; text comes back as 8-bit characters in the pszText buffer. Read text with GetItemText.

Returns true on success.

Example

dim lvi as LVITEMW
lvi.mask = LVIF_PARAM or LVIF_STATE : lvi.iItem = 0 : lvi.stateMask = LVIS_SELECTED
if ListView.GetItem( hCtrl, lvi ) then print "lParam"; lvi.lParam

Microsoft Learn: LVM_GETITEM

GetItemCount

function GetItemCount( byval hListView as HWND ) as long

Returns the number of items.

Example

print "items:"; ListView.GetItemCount( hCtrl )

Microsoft Learn: LVM_GETITEMCOUNT

SetItemCount

function SetItemCount( byval hListView as HWND, byval cItems as long ) as LRESULT

For an ordinary list view, reserves memory for cItems items before adding many of them; the item count does not change. For a virtual list view (LVS_OWNERDATA) it sets the number of items.

Returns nonzero on success.

Example

ListView.SetItemCount( hCtrl, 10000 )

Microsoft Learn: LVM_SETITEMCOUNT

SetItemCountEx

function SetItemCountEx( byval hListView as HWND, byval cItems as long, byval dwFlags as long ) as LRESULT

Sets the number of items of a virtual list view, with dwFlags saying how to redraw: LVSICF_NOINVALIDATEALL repaints only items that changed, LVSICF_NOSCROLL keeps the scroll position.

Returns nonzero on success.

Example

ListView.SetItemCountEx( hCtrl, 5000, LVSICF_NOINVALIDATEALL or LVSICF_NOSCROLL )

Microsoft Learn: LVM_SETITEMCOUNT

GetItemState

function GetItemState( byval hListView as HWND, byval i as long, byval mask as long ) as UINT

Returns the state bits of item i that mask selects: LVIS_SELECTED, LVIS_FOCUSED, LVIS_CUT, LVIS_DROPHILITED, LVIS_OVERLAYMASK, LVIS_STATEIMAGEMASK.

Returns the state bits.

Example

if ListView.GetItemState( hCtrl, 0, LVIS_SELECTED ) then print "item 0 is selected"

Microsoft Learn: LVM_GETITEMSTATE

SetItemState

sub SetItemState( byval hListView as HWND, byval i as long, byval dwState as DWORD, byval mask as DWORD )

Sets the state bits of item i that mask selects to the values in dwState. i = -1 changes every item.

Example

ListView.SetItemState( hCtrl, 2, LVIS_CUT, LVIS_CUT )   ' draw item 2 as cut

Microsoft Learn: LVM_SETITEMSTATE

Update

function Update( byval hListView as HWND, byval iItem as long ) as boolean

Redraws item iItem; with LVS_AUTOARRANGE, also rearranges the control.

Returns true on success.

Example

ListView.Update( hCtrl, 0 )

Microsoft Learn: LVM_UPDATE

RedrawItems

function RedrawItems( byval hListView as HWND, byval iFirst as long, byval iLast as long ) as boolean

Marks items iFirst to iLast for repainting; they are drawn at the next WM_PAINT. Call UpdateWindow to paint them at once.

Returns true on success.

Example

ListView.RedrawItems( hCtrl, 0, 9 )
UpdateWindow( hCtrl )

Microsoft Learn: LVM_REDRAWITEMS

MapIndexToID

function MapIndexToID( byval hListView as HWND, byval index as UINT ) as UINT

Returns the unique ID of the item at index. Unlike the index, the ID does not change when items are inserted, deleted or sorted. Needs visual styles.

Returns the ID.

Example

dim id as UINT = ListView.MapIndexToID( hCtrl, 2 )

Microsoft Learn: LVM_MAPINDEXTOID

MapIDToIndex

function MapIDToIndex( byval hListView as HWND, byval id as UINT ) as UINT

Returns the current index of the item with the unique ID id. Needs visual styles.

Returns the index.

Example

dim id as UINT = ListView.MapIndexToID( hCtrl, 2 )
ListView.DeleteItem( hCtrl, 0 )   ' the items after it move up
print "now at"; ListView.MapIDToIndex( hCtrl, id )

Microsoft Learn: LVM_MAPIDTOINDEX

GetCallbackMask

function GetCallbackMask( byval hListView as HWND ) as UINT

Returns the LVIS_* state bits that the application keeps itself and supplies through LVN_GETDISPINFO, instead of the control storing them.

Returns the mask.

Example

print "callback mask:"; ListView.GetCallbackMask( hCtrl )

Microsoft Learn: LVM_GETCALLBACKMASK

SetCallbackMask

function SetCallbackMask( byval hListView as HWND, byval mask as DWORD ) as boolean

Sets the LVIS_* state bits that the application keeps itself.

Returns true on success.

Example

ListView.SetCallbackMask( hCtrl, LVIS_SELECTED or LVIS_FOCUSED )

Microsoft Learn: LVM_SETCALLBACKMASK

GetItemText

sub GetItemText( byval hListView as HWND, byval i as long, byval iSubItem as long, byval pwszText as wstring ptr, byval cchTextMax as long = 260 )
function GetItemText( byval hListView as HWND, byval i as long, byval iSubItem as long, byval cchTextMax as long = 260 ) as ustring

Copies the text of subitem iSubItem of item i into pwszText, at most cchTextMax characters including the terminating null.

Parameter	Meaning
i	The zero-based item.
iSubItem	The zerp-based subitem (column).
pwszText	The buffer that receives the text.
cchTextMax	The size of the buffer in characters. The default assumes 260: pass the real size of a smaller buffer.

Examples

dim wszText as wstring * 260
ListView.GetItemText( hListView, 3, 1, @wszText, 260 )
dim ustrText as ustring = wszText

print ListView.GetItemText( hListView, 0, 1 )   ' column 1 of the first row

Microsoft Learn: LVM_GETITEMTEXT

SetItemText

function SetItemText( byval hListView as HWND, byval i as long, byval iSubItem as long, byref pwszText as wstring ptr ) as boolean

Sets the text of subitem iSubItem of item i.

pwszText is taken by reference as a wstring ptr. Pass a ustring, a wide literal written wstr("...") or the address of a wstring buffer.

Returns true on success.

Example

dim ustrSize as ustring = "12 KB"
ListView.SetItemText( hCtrl, 0, 1, ustrSize )
ListView.SetItemText( hCtrl, 0, 2, wstr("rocky") )

Microsoft Learn: LVM_SETITEMTEXT

GetStringWidth

function GetStringWidth( byval hListView as HWND, byref wszText as wstring ) as long

Measures wszText in the control's current font. Add some padding when you size a column with it: the control leaves a margin around item text.

Returns the width in pixels, or 0 on failure.

Example

print "width:"; ListView.GetStringWidth( hCtrl, "Jupiter" )

Microsoft Learn: LVM_GETSTRINGWIDTH

EditLabel

function EditLabel( byval hListView as HWND, byval i as long ) as HWND

Starts in-place editing of the text of item i, which is selected and focused. The control must have the focus and the LVS_EDITLABELS style. Pass -1 to stop editing. The parent receives LVN_BEGINLABELEDIT and, when editing ends, LVN_ENDLABELEDIT.

Returns the edit control's handle, or NULL on failure.

Example

SetFocus( hCtrl )
dim hEdit as HWND = ListView.EditLabel( hCtrl, 0 )

Microsoft Learn: LVM_EDITLABEL

CancelEditLabel

sub CancelEditLabel( byval hListView as HWND )

Cancels in-place editing; the item keeps its old text.

Example

ListView.CancelEditLabel( hCtrl )

Microsoft Learn: LVM_CANCELEDITLABEL

GetEditControl

function GetEditControl( byval hListView as HWND ) as HWND

Returns the edit control used while the user edits an item's text, for example to limit its length in LVN_BEGINLABELEDIT.

Returns the edit control's handle, or NULL when no item is being edited.

Example

dim hEdit as HWND = ListView.GetEditControl( hCtrl )
if hEdit then SendMessageW( hEdit, EM_LIMITTEXT, 32, 0 )

Microsoft Learn: LVM_GETEDITCONTROL

GetEmptyText

function GetEmptyText( byval hListView as HWND, byval pwszText as wstring ptr, byval cchText as DWORD ) as boolean

Copies into pwszText, at most cchText characters, the text the control shows when it has no items.

Returns true when there is such a text.

Example

dim wszEmpty as wstring * 128
if ListView.GetEmptyText( hCtrl, @wszEmpty, 128 ) then print "has an empty-list text"

Microsoft Learn: LVM_GETEMPTYTEXT

FindItem

function FindItem overload( byval hListView as HWND, byval iStart as long, byval pvfi as LVFINDINFOW ptr ) as long
function FindItem overload( byval hListView as HWND, byval iStart as long, byref vfi as LVFINDINFOW ) as long

Searches for an item matching the LVFINDINFOW structure: by text (LVFI_STRING, with LVFI_PARTIAL for a prefix), by lParam (LVFI_PARAM) or by position (LVFI_NEARESTXY). The search starts after item iStart; -1 searches from the beginning. LVFI_WRAP continues from the top.

Returns the index of the item found, or -1.

Example

dim lvfi as LVFINDINFOW
lvfi.flags = LVFI_PARAM : lvfi.lParam = 42
print "item with lParam 42:"; ListView.FindItem( hCtrl, -1, lvfi )

Microsoft Learn: LVM_FINDITEM

FindString

function FindString( byval hListView as HWND, byval pwszText as wstring ptr ) as long

Returns the first item whose text starts with pwszText, ignoring case, searching from the first item. "on" finds "One".

Returns the index of the item, or -1.

Example

dim i as long = ListView.FindString( hCtrl, "Ear" )
if i >= 0 then ListView.SelectItem( hCtrl, i )

Microsoft Learn: LVM_FINDITEM

GetNextItem

function GetNextItem( byval hListView as HWND, byval iStart as long, byval flags as UINT ) as long

Searches from item iStart for an item with the properties in flags: a state (LVNI_SELECTED, LVNI_FOCUSED, LVNI_CUT, LVNI_DROPHILITED) and/or a direction (LVNI_ABOVE, LVNI_BELOW, LVNI_TOLEFT, LVNI_TORIGHT). LVNI_ALL searches by index. iStart = -1 starts before the first item.

Returns the index of the item found, or -1.

Example

dim i as long = ListView.GetNextItem( hCtrl, -1, LVNI_SELECTED )
do while i >= 0
    print "selected:"; i
    i = ListView.GetNextItem( hCtrl, i, LVNI_SELECTED )
loop

Microsoft Learn: LVM_GETNEXTITEM

GetNextItemIndex

function GetNextItemIndex overload( byval hListView as HWND, byval plvii as LVITEMINDEX ptr, byval flags as ..LPARAM ) as long
function GetNextItemIndex overload( byval hListView as HWND, byref lvii as LVITEMINDEX, byval flags as ..LPARAM ) as long

Like GetNextItem, but the start and the result are an LVITEMINDEX (item and group), so it can walk items in group order. lvii is updated to the item found. Needs visual styles.

Returns nonzero when an item was found.

Example

dim lvii as LVITEMINDEX
lvii.iItem = -1 : lvii.iGroup = 0
if ListView.GetNextItemIndex( hCtrl, lvii, LVNI_SELECTED ) then print "item"; lvii.iItem

Microsoft Learn: LVM_GETNEXTITEMINDEX

GetISearchString

function GetISearchString( byval hListView as HWND ) as ustring

Returns the incremental search text: the characters the user has typed in quick succession to jump to an item.

Returns the text, or an empty string when the user is not searching.

Example

print "typed so far: "; ListView.GetISearchString( hCtrl )

Microsoft Learn: LVM_GETISEARCHSTRING

GetISearchStringLen

function GetISearchStringLen( byval hListView as HWND ) as long

Returns the length of the incremental search text, or 0 when the user is not searching.

Example

if ListView.GetISearchStringLen( hCtrl ) then print "the user is typing a search"

Microsoft Learn: LVM_GETISEARCHSTRING

GetSelection

function GetSelection( byval hListView as HWND ) as long

Returns the first selected item. In a multiple-selection list use GetNextItem with LVNI_SELECTED to visit the others.

Returns the index, or -1 when nothing is selected.

Example

dim iSel as long = ListView.GetSelection( hCtrl )

Microsoft Learn: LVM_GETNEXTITEM

GetFocusedItem

function GetFocusedItem( byval hListView as HWND ) as long

Returns the item with the focus rectangle, which may or may not be selected.

Returns the index, or -1.

Example

print "focused item:"; ListView.GetFocusedItem( hCtrl )

Microsoft Learn: LVM_GETNEXTITEM

GetSelectedCount

function GetSelectedCount( byval hListView as HWND ) as UINT

Returns the number of selected items.

Example

print ListView.GetSelectedCount( hCtrl ); " selected"

Microsoft Learn: LVM_GETSELECTEDCOUNT

SelectItem

function SelectItem( byval hListView as HWND, byval iIndex as long ) as boolean

Selects item iIndex and gives it the focus; it also clears its cut and drop-highlight states. Other selected items stay selected in a multiple-selection list. The item is not scrolled into view: call EnsureVisible for that.

Returns true on success.

Example

ListView.SelectItem( hCtrl, 0 )
ListView.EnsureVisible( hCtrl, 0, false )

Microsoft Learn: LVM_SETITEMSTATE

SelectAllItems

function SelectAllItems( byval hListView as HWND ) as boolean

Selects every item. A list with LVS_SINGLESEL allows only one selected item.

Returns true on success.

Example

ListView.SelectAllItems( hCtrl )

Microsoft Learn: LVM_SETITEMSTATE

UnselectItem

function UnselectItem( byval hListView as HWND, byval iIndex as long ) as boolean

Deselects item iIndex; its focus is left as it is.

Returns true on success.

Example

ListView.UnselectItem( hCtrl, 0 )

Microsoft Learn: LVM_SETITEMSTATE

UnselectAllItems

function UnselectAllItems( byval hListView as HWND ) as boolean

Deselects every item and takes the focus rectangle away, so GetFocusedItem returns -1 afterwards.

Returns true on success.

Example

ListView.UnselectAllItems( hCtrl )

Microsoft Learn: LVM_SETITEMSTATE

GetSelectionMark

function GetSelectionMark( byval hListView as HWND ) as long

Returns the selection mark: the item a Shift+click range selection starts from.

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

Example

print "selection mark:"; ListView.GetSelectionMark( hCtrl )

Microsoft Learn: LVM_GETSELECTIONMARK

SetSelectionMark

function SetSelectionMark( byval hListView as HWND, byval iIndex as long ) as long

Makes item iIndex the selection mark.

Returns the previous selection mark, or -1.

Example

ListView.SetSelectionMark( hCtrl, 0 )

Microsoft Learn: LVM_SETSELECTIONMARK

SetItemIndexState

function SetItemIndexState overload( byval hListView as HWND, byval plvii as LVITEMINDEX ptr, byval dwData as UINT, byval mask as UINT ) as HRESULT
function SetItemIndexState overload( byval hListView as HWND, byref lvii as LVITEMINDEX, byval dwData as UINT, byval mask as UINT ) as HRESULT

Sets the state bits that mask selects to the values in dwData, for the item that an LVITEMINDEX (item and group) names. Needs visual styles.

Returns S_OK on success, otherwise an error HRESULT.

Example

dim lvii as LVITEMINDEX
lvii.iItem = 0 : lvii.iGroup = 0
ListView.SetItemIndexState( hCtrl, lvii, LVIS_SELECTED, LVIS_SELECTED )

Microsoft Learn: LVM_SETITEMINDEXSTATE

GetHotItem

function GetHotItem( byval hListView as HWND ) as long

Returns the hot item: the one under the pointer when hot tracking (LVS_EX_TRACKSELECT, LVS_EX_ONECLICKACTIVATE or LVS_EX_TWOCLICKACTIVATE) is on.

Returns the index, or -1.

Example

print "hot item:"; ListView.GetHotItem( hCtrl )

Microsoft Learn: LVM_GETHOTITEM

SetHotItem

function SetHotItem( byval hListView as HWND, byval iIndex as DWORD ) as long

Makes item iIndex the hot item.

Returns the previous hot item.

Example

ListView.SetHotItem( hCtrl, 1 )

Microsoft Learn: LVM_SETHOTITEM

GetHotCursor

function GetHotCursor( byval hListView as HWND ) as HCURSOR

Returns the cursor shown while the pointer is over an item with hot tracking on.

Example

dim hCur as HCURSOR = ListView.GetHotCursor( hCtrl )

Microsoft Learn: LVM_GETHOTCURSOR

SetHotCursor

function SetHotCursor( byval hListView as HWND, byval hCur as HCURSOR ) as HCURSOR

Sets the cursor shown while the pointer is over an item with hot tracking on.

Returns the previous cursor.

Example

ListView.SetHotCursor( hCtrl, LoadCursorW( NULL, IDC_HAND ) )

Microsoft Learn: LVM_SETHOTCURSOR

GetHoverTime

function GetHoverTime( byval hListView as HWND ) as DWORD

Returns how long, in milliseconds, the pointer must rest on an item before it is selected with LVS_EX_TRACKSELECT.

Returns the time; &hFFFFFFFF (-1) for the system default.

Example

print "hover time:"; clng( ListView.GetHoverTime( hCtrl ) )

Microsoft Learn: LVM_GETHOVERTIME

SetHoverTime

sub SetHoverTime( byval hListView as HWND, byval dwHoverTimeMs as DWORD )

Sets the hover time in milliseconds; -1 restores the system default.

Example

ListView.SetHoverTime( hCtrl, 800 )

Microsoft Learn: LVM_SETHOVERTIME

GetCheckState

function GetCheckState( byval hListView as HWND, byval i as long ) as UINT

Reads the check box of item i in a list view with LVS_EX_CHECKBOXES. The value is not a boolean, and both results are nonzero:

Check box	Returns
checked	&hFFFFFFFF (-1 as a long)
unchecked	&hFFFFFFFE (-2 as a long)

An item with no check box at all (no LVS_EX_CHECKBOXES) also returns &hFFFFFFFF. Compare with &hFFFFFFFF; never test the result for truth.

Returns &hFFFFFFFF when checked, &hFFFFFFFE when unchecked.

Example

if ListView.GetCheckState( hCtrl, 0 ) = &hFFFFFFFF then print "item 0 is checked"

Microsoft Learn: LVM_GETITEMSTATE

SetCheckState

sub SetCheckState( byval hListView as HWND, byval iIndex as long, byval fCheck as boolean )

Checks (fCheck = true) or unchecks the check box of item iIndex, by setting its state image to 2 or 1. The control needs LVS_EX_CHECKBOXES. iIndex = -1 changes every item.

Example

ListView.SetExtendedStyleEx( hCtrl, LVS_EX_CHECKBOXES, LVS_EX_CHECKBOXES )
ListView.SetCheckState( hCtrl, 0, true )

Microsoft Learn: LVM_SETITEMSTATE

GetExtendedStyle

function GetExtendedStyle( byval hListView as HWND ) as DWORD

Returns the control's LVS_EX_* extended styles. They are not window styles: GetWindowLong does not show them.

Example

if ListView.GetExtendedStyle( hCtrl ) and LVS_EX_GRIDLINES then print "grid lines on"

Microsoft Learn: LVM_GETEXTENDEDLISTVIEWSTYLE

SetExtendedStyle

sub SetExtendedStyle( byval hListView as HWND, byval dwExStyle as DWORD )

Replaces all the LVS_EX_* extended styles with dwExStyle; styles not in it are turned off. To add one, combine it with GetExtendedStyle or use SetExtendedStyleEx.

Example

ListView.SetExtendedStyle( hCtrl, ListView.GetExtendedStyle( hCtrl ) or LVS_EX_FULLROWSELECT )

Microsoft Learn: LVM_SETEXTENDEDLISTVIEWSTYLE

SetExtendedStyleEx

sub SetExtendedStyleEx( byval hListView as HWND, byval dwExMask as DWORD, byval dwExStyle as DWORD )

Changes only the extended styles in dwExMask, turning each on or off as dwExStyle says.

Example

ListView.SetExtendedStyleEx( hCtrl, LVS_EX_GRIDLINES, 0 )   ' grid lines off, the rest unchanged

Microsoft Learn: LVM_SETEXTENDEDLISTVIEWSTYLE

GetView

function GetView( byval hListView as HWND ) as DWORD

Returns the current view: LV_VIEW_ICON, LV_VIEW_SMALLICON, LV_VIEW_LIST, LV_VIEW_DETAILS (report) or LV_VIEW_TILE. Needs visual styles; without them it returns 0 whatever the view.

Returns the view.

Example

if ListView.GetView( hCtrl ) = LV_VIEW_DETAILS then print "report view"

Microsoft Learn: LVM_GETVIEW

SetView

function SetView( byval hListView as HWND, byval iView as DWORD ) as long

Switches to view iView (LV_VIEW_*). This is the only way into tile view. Needs visual styles.

Returns 1 on success, -1 on failure.

Example

ListView.SetView( hCtrl, LV_VIEW_TILE )

Microsoft Learn: LVM_SETVIEW

SetDarkMode

function SetDarkMode( byval hListView as HWND ) as HRESULT

Gives the control the DarkMode_Explorer visual theme, which draws its scroll bars and selection in dark colours. The background and text colours are not changed: set them with SetBkColor, SetTextColor and SetTextBkColor.

Returns S_OK on success, otherwise an error HRESULT.

Example

ListView.SetDarkMode( hCtrl )
ListView.SetBkColor( hCtrl, BGR( 32, 32, 32 ) )
ListView.SetTextBkColor( hCtrl, BGR( 32, 32, 32 ) )
ListView.SetTextColor( hCtrl, BGR( 230, 230, 230 ) )

Microsoft Learn: SetWindowTheme

RemoveDarkMode

function RemoveDarkMode( byval hListView as HWND ) as HRESULT

Restores the control's default visual theme.

Returns S_OK on success, otherwise an error HRESULT.

Example

ListView.RemoveDarkMode( hCtrl )

Microsoft Learn: SetWindowTheme

GetBkColor

function GetBkColor( byval hListView as HWND ) as COLORREF

Returns the background colour, or CLR_NONE when the control has no background colour.

Example

print "background: &h"; hex( ListView.GetBkColor( hCtrl ), 6 )

Microsoft Learn: LVM_GETBKCOLOR

SetBkColor

function SetBkColor( byval hListView as HWND, byval clrBk as COLORREF ) as boolean

Sets the background colour; CLR_NONE gives no background, for a background image.

Returns true on success.

Example

ListView.SetBkColor( hCtrl, BGR( 255, 255, 224 ) )

Microsoft Learn: LVM_SETBKCOLOR

GetTextColor

function GetTextColor( byval hListView as HWND ) as COLORREF

Returns the text colour.

Example

dim clr as COLORREF = ListView.GetTextColor( hCtrl )

Microsoft Learn: LVM_GETTEXTCOLOR

SetTextColor

function SetTextColor( byval hListView as HWND, byval clrText as COLORREF ) as boolean

Sets the text colour.

Returns true on success.

Example

ListView.SetTextColor( hCtrl, BGR( 0, 0, 128 ) )

Microsoft Learn: LVM_SETTEXTCOLOR

GetTextBkColor

function GetTextBkColor( byval hListView as HWND ) as COLORREF

Returns the colour behind item text.

Example

dim clr as COLORREF = ListView.GetTextBkColor( hCtrl )

Microsoft Learn: LVM_GETTEXTBKCOLOR

SetTextBkColor

function SetTextBkColor( byval hListView as HWND, byval clrTextBk as COLORREF ) as boolean

Sets the colour behind item text; CLR_NONE makes it transparent.

Returns true on success.

Example

ListView.SetTextBkColor( hCtrl, CLR_NONE )

Microsoft Learn: LVM_SETTEXTBKCOLOR

GetOutlineColor

function GetOutlineColor( byval hListView as HWND ) as COLORREF

Returns the colour of the border drawn around a selected item with LVS_EX_BORDERSELECT.

Example

dim clr as COLORREF = ListView.GetOutlineColor( hCtrl )

Microsoft Learn: LVM_GETOUTLINECOLOR

SetOutlineColor

function SetOutlineColor( byval hListView as HWND, byval clr as COLORREF ) as COLORREF

Sets the colour of the LVS_EX_BORDERSELECT border.

Returns the previous colour.

Example

ListView.SetOutlineColor( hCtrl, BGR( 255, 0, 0 ) )

Microsoft Learn: LVM_SETOUTLINECOLOR

GetBkImage

function GetBkImage overload( byval hListView as HWND, byval pvbki as LVBKIMAGEW ptr ) as boolean
function GetBkImage overload( byval hListView as HWND, byref vbki as LVBKIMAGEW ) as boolean
function GetBkImage overload( byval hListView as HWND ) as LVBKIMAGEW

Reads the background image into an LVBKIMAGEW. The forms that take a structure send the ANSI message, so a URL or file name comes back in 8-bit characters; the form that returns the structure sends the Unicode one. ulFlags says what kind of image is set.

Returns true on success, or the structure.

Example

dim bki as LVBKIMAGEW = ListView.GetBkImage( hCtrl )
if ( bki.ulFlags and LVBKIF_SOURCE_MASK ) = LVBKIF_SOURCE_NONE then print "no background image"

Microsoft Learn: LVM_GETBKIMAGE

SetBkImage

function SetBkImage overload( byval hListView as HWND, byval pvbki as LVBKIMAGE ptr ) as boolean
function SetBkImage overload( byval hListView as HWND, byref vbki as LVBKIMAGE ) as boolean

Sets or removes the background image, from a bitmap (LVBKIF_SOURCE_HBITMAP) or from a file or URL. It takes LVBKIMAGE, the ANSI LVBKIMAGEA structure, and sends the ANSI message, so a file name in pszImage is a zstring. Set the background colour to CLR_NONE for the image to show.

Returns true on success.

Example

dim bki as LVBKIMAGE
dim hbmp as HBITMAP = cast( HBITMAP, LoadImageW( NULL, "back.bmp", IMAGE_BITMAP, 0, 0, LR_LOADFROMFILE ) )
bki.ulFlags = LVBKIF_SOURCE_HBITMAP or LVBKIF_STYLE_TILE : bki.hbm = hbmp
ListView.SetBkImage( hCtrl, bki )

Microsoft Learn: LVM_SETBKIMAGE

GetImageList

function GetImageList( byval hListView as HWND, byval iImageList as long ) as HIMAGELIST

Returns one of the control's image lists: LVSIL_NORMAL (large icons), LVSIL_SMALL, LVSIL_STATE (check boxes and other state images) or LVSIL_GROUPHEADER.

Returns the image list, or NULL.

Example

dim himl as HIMAGELIST = ListView.GetImageList( hCtrl, LVSIL_SMALL )

Microsoft Learn: LVM_GETIMAGELIST

SetImageList

function SetImageList( byval hListView as HWND, byval himl as HIMAGELIST, byval nImageList as long ) as HIMAGELIST

Gives the control the image list himl for the use nImageList names (LVSIL_NORMAL, LVSIL_SMALL, LVSIL_STATE, LVSIL_GROUPHEADER). Items choose their image by index with LVIF_IMAGE.

Who destroys the list: the control, when it is destroyed, unless it has LVS_SHAREIMAGELISTS (which CWindow.AddControl sets); then destroy it yourself with ImageList_Destroy after the control is gone.

Returns the image list it replaces, or NULL.

Example

dim himl as HIMAGELIST = ImageList_Create( 16, 16, ILC_COLOR32 or ILC_MASK, 4, 4 )
ListView.SetImageList( hCtrl, himl, LVSIL_SMALL )

Microsoft Learn: LVM_SETIMAGELIST

CreateDragImage

function CreateDragImage overload( byval hListView as HWND, byval i as long, byval lpptUpLeft as POINT ptr ) as HIMAGELIST
function CreateDragImage overload( byval hListView as HWND, byval i as long, byref tUpLeft as POINT ) as HIMAGELIST
function CreateDragImage overload( byval hListView as HWND, byval i as long, byval x as long, byval y as long ) as HIMAGELIST

Creates an image list holding a picture of item i, for dragging it with the ImageList_Drag* functions. The control writes the image's upper-left corner, in view coordinates, into the POINT you pass. In the form with x and y those values are ignored: the corner is written to a local point and lost.

The image list is yours: destroy it with ImageList_Destroy when the drag ends.

Returns the image list, or NULL on failure.

Example

dim ptCorner as POINT
dim himlDrag as HIMAGELIST = ListView.CreateDragImage( hCtrl, 0, ptCorner )
if himlDrag then ImageList_Destroy( himlDrag )

Microsoft Learn: LVM_CREATEDRAGIMAGE

ApproximateViewRect

function ApproximateViewRect( byval hListView as HWND, byval iWidth as short, byval iHeight as short, byval iCount as long ) as DWORD

Estimates the width and height the control needs to show iCount items (-1 for all of them) when given the proposed size iWidth × iHeight (-1 for the current size).

Returns the width in the low word and the height in the high word.

Example

dim dwSize as DWORD = ListView.ApproximateViewRect( hCtrl, -1, -1, -1 )
print "needs"; LOWORD( dwSize ); " x"; HIWORD( dwSize )

Microsoft Learn: LVM_APPROXIMATEVIEWRECT

Arrange

function Arrange( byval hListView as HWND, byval code as UINT ) as boolean

Arranges the items in icon or small icon view: LVA_DEFAULT follows the control's alignment style, LVA_ALIGNLEFT and LVA_ALIGNTOP align them to an edge, LVA_SNAPTOGRID snaps them to the nearest grid position.

Returns true on success.

Example

ListView.Arrange( hCtrl, LVA_SNAPTOGRID )

Microsoft Learn: LVM_ARRANGE

GetCountPerPage

function GetCountPerPage( byval hListView as HWND ) as long

Returns how many items fit in the visible area in list or report view; in icon views, the total number of items.

Returns the count.

Example

print "rows per page:"; ListView.GetCountPerPage( hCtrl )

Microsoft Learn: LVM_GETCOUNTPERPAGE

GetTopIndex

function GetTopIndex( byval hListView as HWND ) as long

Returns the first visible item in list or report view; 0 in icon views.

Returns the index.

Example

print "first visible row:"; ListView.GetTopIndex( hCtrl )

Microsoft Learn: LVM_GETTOPINDEX

EnsureVisible

function EnsureVisible( byval hListView as HWND, byval i as long, byval fPartialOK as boolean ) as boolean

Scrolls the control, if needed, so that item i is visible. With fPartialOK = true an item already partly visible is left where it is.

Returns true on success.

Example

ListView.EnsureVisible( hCtrl, ListView.GetItemCount( hCtrl ) - 1, false )   ' show the last row

Microsoft Learn: LVM_ENSUREVISIBLE

IsItemVisible

function IsItemVisible( byval hListView as HWND, byval index as UINT ) as boolean

Reads whether item index is visible. Needs visual styles.

Returns true when the item is visible.

Example

if ListView.IsItemVisible( hCtrl, 5 ) = false then ListView.EnsureVisible( hCtrl, 5, false )

Microsoft Learn: LVM_ISITEMVISIBLE

Scroll

function Scroll( byval hListView as HWND, byval dx as long, byval dy as long ) as boolean

Scrolls the content by dx and dy pixels. In list view dx is rounded to whole columns, and in report view dy to whole rows.

Returns true on success.

Example

ListView.Scroll( hCtrl, 0, 40 )

Microsoft Learn: LVM_SCROLL

GetOrigin

function GetOrigin overload( byval hListView as HWND, byval pptOrg as POINT ptr ) as boolean
function GetOrigin overload( byval hListView as HWND, byref ptOrg as POINT ) as boolean
function GetOrigin overload( byval hListView as HWND ) as POINT

Reads the view origin, which converts view coordinates (item positions) to client coordinates. Only icon and small icon views have one.

Returns true on success (false in list and report view), or the point.

Example

dim ptOrg as POINT
if ListView.GetOrigin( hCtrl, ptOrg ) then print "origin"; ptOrg.x; ","; ptOrg.y

Microsoft Learn: LVM_GETORIGIN

GetViewRect

function GetViewRect overload( byval hListView as HWND, byval prc as RECT ptr ) as boolean
function GetViewRect overload( byval hListView as HWND, byref rc as RECT ) as boolean
function GetViewRect overload( byval hListView as HWND ) as ( long, long, long, long )

Reads the rectangle that bounds all items, in view coordinates, in icon or small icon view. The tuple form returns ( left, top, right, bottom ) and leaves GetLastError() nonzero on success.

Returns true on success, or the four edges.

Example

var (l, t, r, b) = ListView.GetViewRect( hCtrl )
if GetLastError() then print "all items fit in"; r - l; " x"; b - t

Microsoft Learn: LVM_GETVIEWRECT

GetItemRect

function GetItemRect overload( byval hListView as HWND, byval i as long, byval prc as RECT ptr ) as boolean
function GetItemRect overload( byval hListView as HWND, byval i as long, byref rc as RECT ) as boolean
function GetItemRect overload( byval hListView as HWND, byval i as long, byval code as long ) as ( long, long, long, long )

Reads the rectangle of item i, in client coordinates. Which part is set by code: LVIR_BOUNDS (the whole item), LVIR_ICON, LVIR_LABEL or LVIR_SELECTBOUNDS.

The tuple form takes code and returns ( left, top, right, bottom ), leaving GetLastError() nonzero on success. The forms that take a RECT read the code from its left member: set it before the call.

Returns true on success, or the four edges.

Example

var (l, t, r, b) = ListView.GetItemRect( hCtrl, 0, LVIR_BOUNDS )
if GetLastError() then print "row height:"; b - t

Microsoft Learn: LVM_GETITEMRECT

GetSubItemRect

function GetSubItemRect overload( byval hListView as HWND, byval iItem as long, byval iSubItem as long, byval nCode as long, byval prc as RECT ptr ) as boolean
function GetSubItemRect overload( byval hListView as HWND, byval iItem as long, byval iSubItem as long, byval nCode as long, byref rc as RECT ) as boolean
function GetSubItemRect overload( byval hListView as HWND, byval iItem as long, byval iSubItem as long, byval nCode as long ) as ( long, long, long, long )

Reads the rectangle of subitem iSubItem of item iItem in report view, in client coordinates; nCode is LVIR_BOUNDS, LVIR_ICON or LVIR_LABEL. For subitem 0 the bounds are those of the whole row. The tuple form leaves GetLastError() nonzero on success; the pointer form returns false for a null pointer.

Returns true on success, or the four edges.

Example

var (l, t, r, b) = ListView.GetSubItemRect( hCtrl, 0, 1, LVIR_BOUNDS )
if GetLastError() then print "column 1 spans"; l; " to"; r

Microsoft Learn: LVM_GETSUBITEMRECT

GetItemIndexRect

function GetItemIndexRect overload( byval hListView as HWND, byval pvii as LVITEMINDEX ptr, byval iSubItem as long, byval code as long, byval prc as RECT ptr ) as boolean
function GetItemIndexRect overload( byval hListView as HWND, byref lvii as LVITEMINDEX, byval iSubItem as long, byval code as long, byref rc as RECT ) as boolean
function GetItemIndexRect overload( byval hListView as HWND, byref vii as LVITEMINDEX, byval iSubItem as long, byval code as long ) as ( long, long, long, long )

Like GetSubItemRect, for the item that an LVITEMINDEX (item and group) names. The tuple form leaves GetLastError() nonzero on success. Needs visual styles.

Returns true on success, or the four edges.

Example

dim lvii as LVITEMINDEX
lvii.iItem = 0 : lvii.iGroup = 0
var (l, t, r, b) = ListView.GetItemIndexRect( hCtrl, lvii, 0, LVIR_BOUNDS )

Microsoft Learn: LVM_GETITEMINDEXRECT

GetItemPosition

function GetItemPosition overload( byval hListView as HWND, byval i as long, byval ppt as POINT ptr ) as boolean
function GetItemPosition overload( byval hListView as HWND, byval i as long, byref pt as POINT ) as boolean
function GetItemPosition overload( byval hListView as HWND, byval i as long ) as POINT

Reads the position of item i's upper-left corner, in view coordinates.

Returns true on success, or the point.

Example

dim pt as POINT = ListView.GetItemPosition( hCtrl, 0 )
print "item 0 at"; pt.x; ","; pt.y

Microsoft Learn: LVM_GETITEMPOSITION

SetItemPosition

function SetItemPosition( byval hListView as HWND, byval i as long, byval x as short, byval y as short ) as boolean

Moves item i to (x, y) in view coordinates, in icon or small icon view. The coordinates are 16-bit; for larger ones use SetItemPosition32. An auto-arranged control moves it back on the next arrangement.

Returns true on success.

Example

ListView.SetItemPosition( hCtrl, 0, 100, 40 )

Microsoft Learn: LVM_SETITEMPOSITION

SetItemPosition32

sub SetItemPosition32( byval hListView as HWND, byval i as long, byval x as long, byval y as long )

Moves item i to (x, y) in view coordinates, in icon or small icon view, with 32-bit coordinates.

Example

ListView.SetItemPosition32( hCtrl, 0, 100000, 40 )

Microsoft Learn: LVM_SETITEMPOSITION32

GetItemSpacing

function GetItemSpacing( byval hListView as HWND, byval fSmall as boolean ) as DWORD

Returns the distance between items in icon view (fSmall = false) or small icon view (true).

Returns the horizontal spacing in the low word and the vertical spacing in the high word.

Example

dim dwSpacing as DWORD = ListView.GetItemSpacing( hCtrl, false )
print LOWORD( dwSpacing ); " x"; HIWORD( dwSpacing )

Microsoft Learn: LVM_GETITEMSPACING

GetItemHorizontalSpacing

function GetItemHorizontalSpacing( byval hListView as HWND, byval fSmall as boolean ) as DWORD

Returns the low word of GetItemSpacing: the horizontal distance between items.

Example

print ListView.GetItemHorizontalSpacing( hCtrl, false )

Microsoft Learn: LVM_GETITEMSPACING

GetItemVerticalSpacing

function GetItemVerticalSpacing( byval hListView as HWND, byval fSmall as boolean ) as DWORD

Returns the high word of GetItemSpacing: the vertical distance between items.

Example

print ListView.GetItemVerticalSpacing( hCtrl, false )

Microsoft Learn: LVM_GETITEMSPACING

SetIconSpacing

function SetIconSpacing( byval hListView as HWND, byval cx as short, byval cy as short ) as DWORD

Sets the distance between icons in icon view, in pixels, including the icon itself; -1 for both values restores the default spacing.

Returns the previous spacing, horizontal in the low word and vertical in the high word.

Example

ListView.SetIconSpacing( hCtrl, 96, 80 )

Microsoft Learn: LVM_SETICONSPACING

GetWorkAreas

sub GetWorkAreas overload( byval hListView as HWND, byval nWorkAreas as long, byval prc as RECT ptr )
sub GetWorkAreas overload( byval hListView as HWND, byval nWorkAreas as long, byref rc as RECT )

Reads nWorkAreas working areas: rectangles of the icon view that items are arranged in. The RECT forms write nWorkAreas rectangles, so pass the first element of an array that large.

Example

dim rcAreas(0 to 1) as RECT
ListView.GetWorkAreas( hCtrl, 2, rcAreas(0) )

Microsoft Learn: LVM_GETWORKAREAS

SetWorkAreas

sub SetWorkAreas overload( byval hListView as HWND, byval nWorkAreas as long, byval prc as RECT ptr )
sub SetWorkAreas overload( byval hListView as HWND, byval nWorkAreas as long, byref rc as RECT )

Sets up to LV_MAX_WORKAREAS working areas, from the nWorkAreas rectangles of an array (pass its first element); 0 removes them.

Example

dim rcAreas(0 to 1) as RECT
rcAreas(0).right = 200 : rcAreas(0).bottom = 300
rcAreas(1).left = 200 : rcAreas(1).right = 400 : rcAreas(1).bottom = 300
ListView.SetWorkAreas( hCtrl, 2, rcAreas(0) )

Microsoft Learn: LVM_SETWORKAREAS

GetNumberOfWorkAreas

function GetNumberOfWorkAreas( byval hListView as HWND ) as DWORD

Meant to return the number of working areas. The control writes the count into a variable and the message itself returns nothing; this function returns the message's result, so it gives 0 however many areas there are. Read the count with the message directly, as below.

Returns 0.

Example

dim nAreas as UINT
SendMessageW( hCtrl, LVM_GETNUMBEROFWORKAREAS, 0, cast(LPARAM, @nAreas) )
print "work areas:"; nAreas

Microsoft Learn: LVM_GETNUMBEROFWORKAREAS

HitTest

function HitTest overload( byval hListView as HWND, byval pinfo as LVHITTESTINFO ptr ) as long
function HitTest overload( byval hListView as HWND, byref info as LVHITTESTINFO ) as long
function HitTest overload( byval hListView as HWND ) as LVHITTESTINFO

Finds the item at the point pt of an LVHITTESTINFO, in client coordinates. The control fills flags (LVHT_ONITEMLABEL, LVHT_NOWHERE …) and iItem. The form without a structure tests the point (0, 0) and returns the filled structure, leaving the item index in GetLastError().

Returns the index of the item, or -1; or the structure.

Example

dim hti as LVHITTESTINFO
GetCursorPos( @hti.pt ) : ScreenToClient( hCtrl, @hti.pt )
print "item under the pointer:"; ListView.HitTest( hCtrl, hti )

Microsoft Learn: LVM_HITTEST

HitTestEx

function HitTestEx overload( byval hListView as HWND, byref pinfo as LVHITTESTINFO ptr ) as long
function HitTestEx overload( byval hListView as HWND, byref info as LVHITTESTINFO ) as long
function HitTestEx overload( byval hListView as HWND ) as LVHITTESTINFO

Like HitTest, but asks the control to fill the extended members as well: the subitem (iSubItem) and the group (iGroup) at the point.

Returns the index of the item, or -1; or the structure.

Example

dim hti as LVHITTESTINFO
hti.pt.x = 10 : hti.pt.y = 30
if ListView.HitTestEx( hCtrl, hti ) >= 0 then print "group"; hti.iGroup

Microsoft Learn: LVM_HITTEST

SubItemHitTest

function SubItemHitTest overload( byval hListView as HWND, byval plvhti as LVHITTESTINFO ptr ) as long
function SubItemHitTest overload( byval hListView as HWND, byref lvhti as LVHITTESTINFO ) as long

Finds the item and subitem at the point in an LVHITTESTINFO, in client coordinates; the control fills iItem, iSubItem and flags. Use it in report view to know which cell was clicked.

Returns the index of the item, or -1.

Example

dim hti as LVHITTESTINFO
hti.pt.x = 150 : hti.pt.y = 30
if ListView.SubItemHitTest( hCtrl, hti ) >= 0 then print "row"; hti.iItem; " column"; hti.iSubItem

Microsoft Learn: LVM_SUBITEMHITTEST

SubItemHitTestEx

function SubItemHitTestEx overload( byval hListView as HWND, byval plvhti as LVHITTESTINFO ptr ) as long
function SubItemHitTestEx overload( byval hListView as HWND, byref lvhti as LVHITTESTINFO ) as long

Like SubItemHitTest, and fills the group (iGroup) as well.

Returns the index of the item, or -1.

Example

dim hti as LVHITTESTINFO
hti.pt.x = 150 : hti.pt.y = 30
ListView.SubItemHitTestEx( hCtrl, hti )

Microsoft Learn: LVM_SUBITEMHITTEST

GetInsertMark

function GetInsertMark overload( byval hListView as HWND, byval pvim as LVINSERTMARK ptr ) as boolean
function GetInsertMark overload( byval hListView as HWND, byref vim as LVINSERTMARK ) as boolean
function GetInsertMark overload( byval hListView as HWND ) as LVINSERTMARK

Reads where the insertion mark is: the item it is next to (iItem, -1 for none) and, in dwFlags, whether it is after it (LVIM_AFTER). The function sets cbSize itself. The form that returns the structure leaves the message's result in GetLastError().

Returns true on success, or the structure.

Example

dim lvim as LVINSERTMARK = ListView.GetInsertMark( hCtrl )
print "insertion mark at item"; lvim.iItem

Microsoft Learn: LVM_GETINSERTMARK

SetInsertMark

function SetInsertMark overload( byval hListView as HWND, byval plvim as LVINSERTMARK ptr ) as boolean
function SetInsertMark overload( byval hListView as HWND, byref lvim as LVINSERTMARK ) as boolean

Places the insertion mark next to item iItem of an LVINSERTMARK, before it or after it (LVIM_AFTER); iItem = -1 removes it. Set cbSize yourself. Used while dragging items in icon view.

Returns true on success.

Example

dim lvim as LVINSERTMARK
lvim.cbSize = sizeof( LVINSERTMARK ) : lvim.iItem = 2 : lvim.dwFlags = LVIM_AFTER
ListView.SetInsertMark( hCtrl, lvim )

Microsoft Learn: LVM_SETINSERTMARK

GetInsertMarkColor

function GetInsertMarkColor( byval hListView as HWND ) as COLORREF

Returns the colour of the insertion mark.

Example

dim clr as COLORREF = ListView.GetInsertMarkColor( hCtrl )

Microsoft Learn: LVM_GETINSERTMARKCOLOR

SetInsertMarkColor

function SetInsertMarkColor( byval hListView as HWND, byval clr as COLORREF ) as COLORREF

Sets the colour of the insertion mark.

Returns the previous colour.

Example

ListView.SetInsertMarkColor( hCtrl, BGR( 255, 0, 0 ) )

Microsoft Learn: LVM_SETINSERTMARKCOLOR

GetInsertMarkRect

function GetInsertMarkRect overload( byval hListView as HWND, byval prc as RECT ptr ) as long
function GetInsertMarkRect overload( byval hListView as HWND, byref rc as RECT ) as long
function GetInsertMarkRect overload( byval hListView as HWND ) as ( long, long, long, long )

Reads the rectangle around the insertion mark, in client coordinates. The tuple form leaves GetLastError() nonzero when there is a mark.

Returns nonzero when a rectangle was found, or the four edges.

Example

var (l, t, r, b) = ListView.GetInsertMarkRect( hCtrl )
if GetLastError() then InvalidateRect( hCtrl, NULL, true )

Microsoft Learn: LVM_GETINSERTMARKRECT

InsertMarkHitTest

function InsertMarkHitTest overload( byval hListView as HWND, byval ppt as POINT ptr, byval pvim as LVINSERTMARK ptr ) as boolean
function InsertMarkHitTest overload( byval hListView as HWND, byref pt as POINT, byref vim as LVINSERTMARK ) as boolean

Finds the insertion point closest to a point in client coordinates and describes it in an LVINSERTMARK, ready for SetInsertMark. Set the structure's cbSize first.

Returns true on success.

Example

dim pt as POINT = ( 40, 60 )
dim lvim as LVINSERTMARK
lvim.cbSize = sizeof( LVINSERTMARK )
if ListView.InsertMarkHitTest( hCtrl, pt, lvim ) then ListView.SetInsertMark( hCtrl, lvim )

Microsoft Learn: LVM_INSERTMARKHITTEST

SortItems

function SortItems( byval hListView as HWND, byval _pfnCompare as PFNLVCOMPARE ptr, byval _lPrm as LPARAM ) as long

Sorts the items with a comparison function, which receives the lParam values of two items and _lPrm, and returns a negative number when the first comes first, a positive number when the second does, and 0 when they are equal. The items are renumbered to the new order.

The parameter is a pointer to PFNLVCOMPARE, so pass the function's address cast to it, as below.

Returns nonzero on success.

Example

function CompareByParam( byval lParam1 as LPARAM, byval lParam2 as LPARAM, byval lParamSort as LPARAM ) as long
    return lParam1 - lParam2
end function

sub SortList( byval hList as HWND )
    ListView.SortItems( hList, cast( PFNLVCOMPARE ptr, @CompareByParam ), 0 )
end sub

Microsoft Learn: LVM_SORTITEMS

SortItemsEx

function SortItemsEx( byval hListView as HWND, byval _pfnCompare as PFNLVCOMPARE ptr, byval _lPrm as LPARAM ) as long

Like SortItems, but the comparison function receives the current indexes of the two items, so it can read their text with GetItemText.

Returns nonzero on success.

Example

function CompareByText( byval i1 as LPARAM, byval i2 as LPARAM, byval hList as LPARAM ) as long
    dim as wstring * 128 w1, w2
    ListView.GetItemText( cast( HWND, hList ), i1, 0, @w1, 128 )
    ListView.GetItemText( cast( HWND, hList ), i2, 0, @w2, 128 )
    return lstrcmpiW( @w1, @w2 )
end function

sub SortListByText( byval hList as HWND )
    ListView.SortItemsEx( hList, cast( PFNLVCOMPARE ptr, @CompareByText ), cast( LPARAM, hList ) )
end sub

Microsoft Learn: LVM_SORTITEMSEX

SortGroups

function SortGroups( byval hListView as HWND, byval _pfnGroupCompare as PFNLVGROUPCOMPARE ptr, byval _plv as any ptr ) as boolean

Sorts the groups with a comparison function, which receives two group IDs and _plv. Pass the function's address cast to PFNLVGROUPCOMPARE ptr.

Returns true on success.

Example

function CompareGroups( byval id1 as long, byval id2 as long, byval pv as any ptr ) as long
    return id1 - id2
end function

sub SortGroupsById( byval hList as HWND )
    ListView.SortGroups( hList, cast( PFNLVGROUPCOMPARE ptr, @CompareGroups ), NULL )
end sub

Microsoft Learn: LVM_SORTGROUPS

EnableGroupView

function EnableGroupView( byval hListView as HWND, byval fEnable as boolean ) as long

Turns group view on or off. With it on, items are shown under the group their iGroupId names (set with SetItem and LVIF_GROUPID); items in no group are not shown. Needs visual styles.

Returns 1 when the setting changed, 0 when it already was so, -1 on failure.

Example

ListView.EnableGroupView( hCtrl, true )

Microsoft Learn: LVM_ENABLEGROUPVIEW

IsGroupViewEnabled

function IsGroupViewEnabled( byval hListView as HWND ) as boolean

Returns true when group view is on.

Example

if ListView.IsGroupViewEnabled( hCtrl ) then print "grouped"

Microsoft Learn: LVM_ISGROUPVIEWENABLED

InsertGroup

function InsertGroup overload( byval hListView as HWND, byval index as long, byval pgrp as LVGROUP ptr ) as long
function InsertGroup overload( byval hListView as HWND, byval index as long, byref grp as LVGROUP ) as long

Inserts a group described by an LVGROUP at position index (-1 appends it). Set cbSize, mask and the members it names; iGroupId is the ID items use to join the group.

Returns the index of the new group, or -1 on failure.

Example

dim grp as LVGROUP
grp.cbSize = sizeof( LVGROUP ) : grp.mask = LVGF_HEADER or LVGF_GROUPID
grp.pszHeader = @wstr("Inner planets") : grp.iGroupId = 1
ListView.InsertGroup( hCtrl, -1, grp )

Microsoft Learn: LVM_INSERTGROUP

InsertGroupSorted

sub InsertGroupSorted overload( byval hListView as HWND, byval pstructInsert as LVINSERTGROUPSORTED ptr )
sub InsertGroupSorted overload( byval hListView as HWND, byref structInsert as LVINSERTGROUPSORTED )

Inserts a group into an ordered list of groups, using the comparison function and the LVGROUP in an LVINSERTGROUPSORTED.

Example

dim igs as LVINSERTGROUPSORTED
igs.lvGroup.cbSize = sizeof( LVGROUP ) : igs.lvGroup.mask = LVGF_HEADER or LVGF_GROUPID
igs.lvGroup.pszHeader = @wstr("Gas giants") : igs.lvGroup.iGroupId = 2
ListView.InsertGroupSorted( hCtrl, igs )

Microsoft Learn: LVM_INSERTGROUPSORTED

RemoveGroup

function RemoveGroup( byval hListView as HWND, byval iGroupId as long ) as long

Removes the group with ID iGroupId.

Returns the index of the group removed, or -1 on failure.

Example

ListView.RemoveGroup( hCtrl, 2 )

Microsoft Learn: LVM_REMOVEGROUP

RemoveAllGroups

sub RemoveAllGroups( byval hListView as HWND )

Removes every group.

Example

ListView.RemoveAllGroups( hCtrl )

Microsoft Learn: LVM_REMOVEALLGROUPS

HasGroup

function HasGroup( byval hListView as HWND, byval iGroupId as long ) as boolean

Returns true when there is a group with ID iGroupId.

Example

if ListView.HasGroup( hCtrl, 1 ) = false then print "no group 1"

Microsoft Learn: LVM_HASGROUP

GetGroupCount

function GetGroupCount( byval hListView as HWND ) as long

Returns the number of groups.

Example

print "groups:"; ListView.GetGroupCount( hCtrl )

Microsoft Learn: LVM_GETGROUPCOUNT

GetGroupInfo

function GetGroupInfo overload( byval hListView as HWND, byval iGroupId as long, byval pgrp as LVGROUP ptr ) as long
function GetGroupInfo overload( byval hListView as HWND, byval iGroupId as long, byref grp as LVGROUP ) as long

Reads the attributes of the group with ID iGroupId that the LVGROUP's mask asks for. The function sets cbSize itself; for text, give pszHeader a buffer and cchHeader its size.

Returns the group's ID, or -1 on failure (and for a null pointer).

Example

dim grp as LVGROUP
grp.mask = LVGF_STATE : grp.stateMask = LVGS_COLLAPSED
if ListView.GetGroupInfo( hCtrl, 1, grp ) <> -1 andalso ( grp.state and LVGS_COLLAPSED ) <> 0 then print "collapsed"

Microsoft Learn: LVM_GETGROUPINFO

GetGroupInfoByIndex

function GetGroupInfoByIndex overload( byval hListView as HWND, byval iIndex as long, byref pgrp as LVGROUP ptr ) as boolean
function GetGroupInfoByIndex overload( byval hListView as HWND, byval iIndex as long, byref grp as LVGROUP ) as boolean

Like GetGroupInfo, for the group at position iIndex (from 0) rather than by ID. The function sets cbSize itself.

Returns true on success.

Example

dim grp as LVGROUP
grp.mask = LVGF_GROUPID
for i as long = 0 to ListView.GetGroupCount( hCtrl ) - 1
    if ListView.GetGroupInfoByIndex( hCtrl, i, grp ) then print "group ID"; grp.iGroupId
next

Microsoft Learn: LVM_GETGROUPINFOBYINDEX

SetGroupInfo

function SetGroupInfo overload( byval hListView as HWND, byval iGroupId as long, byval pgrp as LVGROUP ptr ) as long
function SetGroupInfo overload( byval hListView as HWND, byval iGroupId as long, byref grp as LVGROUP ) as long

Changes the attributes of the group with ID iGroupId that the LVGROUP's mask names. Set cbSize yourself.

Returns the group's ID, or -1 on failure.

Example

dim grp as LVGROUP
grp.cbSize = sizeof( LVGROUP ) : grp.mask = LVGF_HEADER : grp.pszHeader = @wstr("Rocky planets")
ListView.SetGroupInfo( hCtrl, 1, grp )

Microsoft Learn: LVM_SETGROUPINFO

GetGroupState

function GetGroupState( byval hListView as HWND, byval dwGroupId as UINT, byval dwMask as UINT ) as UINT

Returns the state bits of group dwGroupId that dwMask selects: LVGS_COLLAPSED, LVGS_COLLAPSIBLE, LVGS_HIDDEN …

Returns the state bits.

Example

if ListView.GetGroupState( hCtrl, 1, LVGS_COLLAPSED ) then print "group 1 is collapsed"

Microsoft Learn: LVM_GETGROUPSTATE

SetGroupState

function SetGroupState( byval hListView as HWND, byval dwGroupId as UINT, byval dwMask as UINT, byval dwState as UINT ) as long

Sets the state bits of group dwGroupId that dwMask selects to the values in dwState.

Returns the group's ID, or -1 on failure.

Example

ListView.SetGroupState( hCtrl, 1, LVGS_COLLAPSIBLE, LVGS_COLLAPSIBLE )

Microsoft Learn: LVM_SETGROUPINFO

GetGroupMetrics

sub GetGroupMetrics overload( byval hListView as HWND, byval pGroupMetrics as LVGROUPMETRICS ptr )
sub GetGroupMetrics overload( byval hListView as HWND, byref GroupMetrics as LVGROUPMETRICS )

Reads how groups are drawn (border sizes and colours) into an LVGROUPMETRICS, as its mask asks. The function sets cbSize itself and does nothing for a null pointer.

Example

dim gm as LVGROUPMETRICS
gm.mask = LVGMF_BORDERSIZE
ListView.GetGroupMetrics( hCtrl, gm )
print "group border:"; gm.Left; gm.Top

Microsoft Learn: LVM_GETGROUPMETRICS

SetGroupMetrics

sub SetGroupMetrics overload( byval hListView as HWND, byval pGroupMetrics as LVGROUPMETRICS ptr )
sub SetGroupMetrics overload( byval hListView as HWND, byref GroupMetrics as LVGROUPMETRICS )

Sets how groups are drawn from an LVGROUPMETRICS. Unlike GetGroupMetrics, it does not set cbSize: set it yourself.

Example

dim gm as LVGROUPMETRICS
gm.cbSize = sizeof( LVGROUPMETRICS ) : gm.mask = LVGMF_BORDERSIZE
gm.Left = 8 : gm.Top = 8 : gm.Right = 8 : gm.Bottom = 8
ListView.SetGroupMetrics( hCtrl, gm )

Microsoft Learn: LVM_SETGROUPMETRICS

GetGroupRect

function GetGroupRect overload( byval hListView as HWND, byval iGroupId as long, byval nType as long, byval prc as RECT ptr ) as boolean
function GetGroupRect overload( byval hListView as HWND, byval iGroupId as long, byval nType as long, byref rc as RECT ) as boolean
function GetGroupRect overload( byval hListView as HWND, byval iGroupId as long, byval nType as long ) as ( long, long, long, long )

Reads the rectangle of group iGroupId, in client coordinates. nType picks the part: LVGGR_GROUP (the whole group), LVGGR_HEADER, LVGGR_LABEL or LVGGR_SUBSETLINK.

The tuple form and the RECT form pass nType to the control. The pointer form does not: it uses whatever prc->top holds, so set top to the part you want. The tuple form leaves GetLastError() nonzero on success.

Returns true on success, or the four edges.

Example

var (l, t, r, b) = ListView.GetGroupRect( hCtrl, 1, LVGGR_HEADER )
if GetLastError() then print "header height:"; b - t

Microsoft Learn: LVM_GETGROUPRECT

GetFocusedGroup

function GetFocusedGroup( byval hListView as HWND ) as long

Returns the index of the group with the focus, or -1.

Example

print "focused group:"; ListView.GetFocusedGroup( hCtrl )

Microsoft Learn: LVM_GETFOCUSEDGROUP

GetGroupHeaderImageList

function GetGroupHeaderImageList( byval hListView as HWND ) as HIMAGELIST

Returns the image list for group headers, or NULL: the same as GetImageList with LVSIL_GROUPHEADER.

Example

dim himl as HIMAGELIST = ListView.GetGroupHeaderImageList( hCtrl )

Microsoft Learn: LVM_GETIMAGELIST

SetGroupHeaderImageList

function SetGroupHeaderImageList( byval hListView as HWND, byval himl as HIMAGELIST ) as HIMAGELIST

Gives the control the image list for group headers: the same as SetImageList with LVSIL_GROUPHEADER. A group shows an image from it with LVGF_TITLEIMAGE.

Returns the image list it replaces, or NULL.

Example

dim himl as HIMAGELIST = ImageList_Create( 16, 16, ILC_COLOR32, 2, 2 )
ListView.SetGroupHeaderImageList( hCtrl, himl )

Microsoft Learn: LVM_SETIMAGELIST

GetTileInfo

sub GetTileInfo overload( byval hListView as HWND, byval pti as LVTILEINFO ptr )
sub GetTileInfo overload( byval hListView as HWND, byref ti as LVTILEINFO )
function GetTileInfo overload( byval hListView as HWND ) as LVTILEINFO

Reads which subitems the tile of an item shows, into an LVTILEINFO: set iItem, and give puColumns an array and cColumns its size. The function sets cbSize itself. The form that returns the structure asks about item 0 and passes no array.

Example

dim cols(0 to 3) as UINT
dim lvti as LVTILEINFO
lvti.iItem = 0 : lvti.cColumns = 4 : lvti.puColumns = @cols(0)
ListView.GetTileInfo( hCtrl, lvti )
print "tile shows"; lvti.cColumns; " subitems"

Microsoft Learn: LVM_GETTILEINFO

SetTileInfo

function SetTileInfo overload( byval hListView as HWND, byval plvtinfo as LVTILEINFO ptr ) as boolean
function SetTileInfo overload( byval hListView as HWND, byref lvtinfo as LVTILEINFO ) as boolean

Sets which subitems the tile of item iItem shows, below its text, from an LVTILEINFO. Set cbSize yourself.

Returns true on success.

Example

dim cols(0 to 1) as UINT = { 1, 2 }
dim lvti as LVTILEINFO
lvti.cbSize = sizeof( LVTILEINFO ) : lvti.iItem = 0 : lvti.cColumns = 2 : lvti.puColumns = @cols(0)
ListView.SetTileInfo( hCtrl, lvti )

Microsoft Learn: LVM_SETTILEINFO

GetTileViewInfo

sub GetTileViewInfo overload( byval hListView as HWND, byval ptvi as LVTILEVIEWINFO ptr )
sub GetTileViewInfo overload( byval hListView as HWND, byref tvi as LVTILEVIEWINFO )
function GetTileViewInfo overload( byval hListView as HWND ) as LVTILEVIEWINFO

Reads the tile view settings (tile size, lines of text, margins) that the LVTILEVIEWINFO's dwMask asks for. The function sets cbSize itself. The form that returns the structure sends an empty dwMask, so it asks for nothing.

Example

dim tvi as LVTILEVIEWINFO
tvi.dwMask = LVTVIM_COLUMNS
ListView.GetTileViewInfo( hCtrl, tvi )
print "lines per tile:"; tvi.cLines

Microsoft Learn: LVM_GETTILEVIEWINFO

SetTileViewInfo

function SetTileViewInfo overload( byval hListView as HWND, byval plvtvinfo as LVTILEVIEWINFO ptr ) as boolean
function SetTileViewInfo overload( byval hListView as HWND, byref lvtvinfo as LVTILEVIEWINFO ) as boolean

Changes the tile view settings that the LVTILEVIEWINFO's dwMask names. Set cbSize yourself.

Returns true on success.

Example

dim tvi as LVTILEVIEWINFO
tvi.cbSize = sizeof( LVTILEVIEWINFO ) : tvi.dwMask = LVTVIM_COLUMNS : tvi.cLines = 2
ListView.SetTileViewInfo( hCtrl, tvi )

Microsoft Learn: LVM_SETTILEVIEWINFO

GetFooterInfo

function GetFooterInfo overload( byval hListView as HWND, byval pvfi as LVFOOTERINFO ptr ) as boolean
function GetFooterInfo overload( byval hListView as HWND, byref vfi as LVFOOTERINFO ) as boolean
function GetFooterInfo overload( byval hListView as HWND ) as LVFOOTERINFO

Reads the attributes of the control's footer (the area below the items that a list view can show, with clickable items) that the LVFOOTERINFO's mask asks for. The form that returns the structure sends an empty mask.

Returns true on success, or the structure.

Example

dim lvfi as LVFOOTERINFO
lvfi.mask = LVFF_ITEMCOUNT
if ListView.GetFooterInfo( hCtrl, lvfi ) then print "footer items:"; lvfi.cItems

Microsoft Learn: LVM_GETFOOTERINFO

GetFooterItem

function GetFooterItem overload( byval hListView as HWND, byval iItem as long, byval pfi as LVFOOTERITEM ptr ) as boolean
function GetFooterItem overload( byval hListView as HWND, byval iItem as long, byref fi as LVFOOTERITEM ) as boolean
function GetFooterItem overload( byval hListView as HWND, byval iItem as UINT ) as LVFOOTERITEM

Reads footer item iItem into an LVFOOTERITEM, as its mask asks. The form that returns the structure sends an empty mask.

Returns true on success, or the structure.

Example

dim wszText as wstring * 64
dim lvfi as LVFOOTERITEM
lvfi.mask = LVFIF_TEXT : lvfi.pszText = @wszText : lvfi.cchTextMax = 64
ListView.GetFooterItem( hCtrl, 0, lvfi )

Microsoft Learn: LVM_GETFOOTERITEM

GetFooterItemRect

function GetFooterItemRect overload( byval hListView as HWND, byval iItem as UINT, byval prc as RECT ptr ) as boolean
function GetFooterItemRect overload( byval hListView as HWND, byval iItem as UINT, byref rc as RECT ) as boolean
function GetFooterItemRect overload( byval hListView as HWND, byval iItem as UINT ) as ( long, long, long, long )

Reads the rectangle of footer item iItem, in client coordinates. The tuple form leaves GetLastError() nonzero on success.

Returns true on success, or the four edges.

Example

var (l, t, r, b) = ListView.GetFooterItemRect( hCtrl, 0 )

Microsoft Learn: LVM_GETFOOTERITEMRECT

GetFooterRect

function GetFooterRect overload( byval hListView as HWND, byval prc as RECT ptr ) as boolean
function GetFooterRect overload( byval hListView as HWND, byref rc as RECT ) as boolean
function GetFooterRect overload( byval hListView as HWND ) as ( long, long, long, long )

Reads the rectangle of the footer, in client coordinates. The tuple form leaves GetLastError() nonzero on success.

Returns true on success, or the four edges.

Example

var (l, t, r, b) = ListView.GetFooterRect( hCtrl )
if GetLastError() then print "footer height:"; b - t

Microsoft Learn: LVM_GETFOOTERRECT

GetToolTips

function GetToolTips( byval hListView as HWND ) as HWND

Returns the tooltip control the list view uses. The functions of ToolTip work on it.

Returns its handle, or NULL.

Example

dim hTip as HWND = ListView.GetToolTips( hCtrl )

Microsoft Learn: LVM_GETTOOLTIPS

SetToolTips

function SetToolTips( byval hListView as HWND, byval hwndToolTip as HWND ) as HWND

Gives the list view another tooltip control.

Returns the tooltip control it used before, or NULL.

Example

dim hTip as HWND = CreateWindowExW( 0, TOOLTIPS_CLASSW, NULL, TTS_ALWAYSTIP, 0, 0, 0, 0, hwnd, NULL, NULL, NULL )
dim hOldTip as HWND = ListView.SetToolTips( hCtrl, hTip )

Microsoft Learn: LVM_SETTOOLTIPS

SetInfoTip

function SetInfoTip overload( byval hListView as HWND, byval plvInfoTip as LVSETINFOTIP ptr ) as boolean
function SetInfoTip overload( byval hListView as HWND, byref lvInfoTip as LVSETINFOTIP ) as boolean

Sets the tooltip text of an item or subitem from an LVSETINFOTIP (iItem, iSubItem, pszText). The function sets cbSize itself; the pointer form returns false for a null pointer. Tooltips for items need LVS_EX_INFOTIP.

Returns true on success.

Example

dim lvit as LVSETINFOTIP
lvit.iItem = 0 : lvit.pszText = @wstr("The closest planet to the Sun")
ListView.SetInfoTip( hCtrl, lvit )

Microsoft Learn: LVM_SETINFOTIP

GetTooltipsFont

function GetTooltipsFont( byval hListView as HWND ) as HFONT

Returns the font of the list view's tooltip control, or NULL when it draws with the system font.

Example

dim hFont as HFONT = ListView.GetTooltipsFont( hCtrl )

Microsoft Learn: WM_GETFONT

SetTooltipsFont

sub SetTooltipsFont( byval hListView as HWND, byval hFont as HFONT = NULL, byval fRedraw as boolean = false )

Sets the font of the list view's tooltip control; NULL returns it to the system font, and fRedraw = true redraws it at once. The font stays yours to delete after the control is gone. Does nothing when the list view has no tooltip control.

Example

ListView.SetTooltipsFont( hCtrl, cast( HFONT, GetStockObject( DEFAULT_GUI_FONT ) ), true )

Microsoft Learn: WM_SETFONT

See also

• sys/win/gui for the module and the other controls
• CWindow for AddControl, which creates the list view
• Header for the header control of report view
• TreeView and ListBox, the other list controls
• ToolTip for the list view's tooltip control
• Dark mode for dark title bars and the user's colour setting