List view item states
List View Control Reference

List view item states


An item's state value consists of the item's state, an optional overlay mask index, and an optional state image mask index.

An item's state determines its appearance and functionality. The state can be zero or one or more of the following values:
LVIS_ACTIVATING Version 4.71. The item is being activated in an LVN_ITEMACTIVATE notification.
LVIS_CUT The item is marked for a cut-and-paste operation.
LVIS_DROPHILITED The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED The item has the focus, so it is surrounded by a standard focus rectangle. Although more than one item may be selected, only one item can have the focus.
LVIS_SELECTED The item is selected. The appearance of a selected item depends on whether it has the focus and also on the system colors used for selection.

You can use the LVIS_OVERLAYMASK mask to isolate the one-based index of the overlay image. You can use the LVIS_STATEIMAGEMASK mask to isolate the one-based index of the state image.

List View Control Messages

This section contains information about messages used with list view controls.

LVM_APPROXIMATEVIEWRECT

LVM_APPROXIMATEVIEWRECT
    wParam = (WPARAM)(INT) iCount;
    lParam = (LPARAM) MAKELPARAM(cx, cy);

Calculates the approximate width and height required to display a given number of items. You can send this message explicitly or use the ListView_ApproximateViewRect macro.

iCount
Number of items to be displayed in the control. If this parameter is set to -1, the message uses the total number of items in the control.
cx and cy
Proposed dimensions of the control, in pixels. Either parameter can be set to -1 to allow the message to use the current width or height value.

Setting the size of the list view control based on the dimensions provided by this message can optimize redraw and reduce flicker.

Version 4.70

LVM_ARRANGE

LVM_ARRANGE 
    wParam = (WPARAM) (int) code; 
    lParam = 0; 

Arranges items in icon view. You can send this message explicitly or by using the ListView_Arrange macro.

code
Specifies the alignment, which can be one of the following values:
LVA_ALIGNLEFT Aligns items along the left edge of the window.
LVA_ALIGNTOP Aligns items along the top edge of the window.
LVA_DEFAULT Aligns items according to the list view control's current alignment styles (the default value).
LVA_SNAPTOGRID Snaps all icons to the nearest grid position.

LVM_CREATEDRAGIMAGE

LVM_CREATEDRAGIMAGE 
    wParam = (WPARAM) (int) iItem; 
    lParam = (LPARAM) (LPPOINT) lpptUpLeft; 

Creates a drag image list for the specified item. You can send this message explicitly or by using the ListView_CreateDragImage macro.

iItem
Index of the item.
lpptUpLeft
Address of a POINT structure that receives the initial location of the upper-left corner of the image, in view coordinates.

LVM_DELETEALLITEMS

LVM_DELETEALLITEMS 
    wParam = 0; 
    lParam = 0; 

Removes all items from a list view control. You can send this message explicitly or by using the ListView_DeleteAllItems macro.

When a list view control receives the LVM_DELETEALLITEMS message, it sends the LVN_DELETEALLITEMS notification message to its parent window.

LVM_DELETECOLUMN

LVM_DELETECOLUMN 
    wParam = (WPARAM) (int) iCol; 
    lParam = 0; 

Removes a column from a list view control. You can send this message explicitly or by using the ListView_DeleteColumn macro.

iCol
Index of the column to delete.

LVM_DELETEITEM

LVM_DELETEITEM 
    wParam = (WPARAM) (int) iItem; 
    lParam = 0; 

Removes an item from a list view control. You can send this message explicitly or by using the ListView_DeleteItem macro.

iItem
Index of the list view item to delete.

LVM_EDITLABEL

LVM_EDITLABEL 
    wParam = (WPARAM) (int) iItem; 
    lParam = 0; 

Begins in-place editing of the specified list view item's text. The message implicitly selects and focuses the specified item. You can send this message explicitly or by using the ListView_EditLabel macro.

iItem
Index of the list view item. To cancel editing, set iItem to -1.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but you should not destroy it.

The control must have the focus before you send this message to the control. Focus can be set using the SetFocus function.

See also WM_CANCELMODE

LVM_ENSUREVISIBLE

LVM_ENSUREVISIBLE 
    wParam = (WPARAM) (int) i; 
    lParam = (LPARAM) (BOOL) fPartialOK; 

Ensures that a list view item is either entirely or partially visible, scrolling the list view control if necessary. You can send this message explicitly or by using the ListView_EnsureVisible macro.

i
Index of the list view item.
fPartialOK
Value specifying whether the item must be entirely visible. If this parameter is TRUE, no scrolling occurs if the item is at least partially visible.

LVM_FINDITEM

LVM_FINDITEM 
    wParam = (WPARAM) (int) iStart; 
    lParam = (LPARAM) (const LPLVFINDINFO) plvfi; 

Searches for a list view item with the specified characteristics. You can send this message explicitly or by using the ListView_FindItem macro.

iStart
Index of the item to begin the search with or -1 to start from the beginning. The specified item is itself excluded from the search.
plvfi
Address of an LVFINDINFO structure that contains information about what to search for.

LVM_GETBKCOLOR

LVM_GETBKCOLOR 
    wParam = 0; 
    lParam = 0; 

Retrieves the background color of a list view control. You can send this message explicitly or by using the ListView_GetBkColor macro.

LVM_GETBKIMAGE

LVM_GETBKIMAGE
    wParam = 0;
    lParam = (LPARAM) (LPLVBKIMAGE) plvbki;

Retrieves the background image in a list view control. You can send this message explicitly or by using the ListView_GetBkImage macro.

plvbki
Address of an LVBKIMAGE structure that will receive the background image information.

Version 4.71

See also LVM_SETBKIMAGE

LVM_GETCALLBACKMASK

LVM_GETCALLBACKMASK 
    wParam = 0; 
    lParam = 0; 

Retrieves the callback mask for a list view control. You can send this message explicitly or by using the ListView_GetCallbackMask macro.

LVM_GETCOLUMN

LVM_GETCOLUMN 
    wParam = (WPARAM) (int) iCol; 
    lParam = (LPARAM) (LPLVCOLUMN) pcol; 

Retrieves the attributes of a list view control's column. You can send this message explicitly or by using the ListView_GetColumn macro.

iCol
Index of the column.
pcol
Address of an LVCOLUMN structure that specifies the information to retrieve and receives information about the column. The mask member specifies which column attributes to retrieve.
If the mask member specifies the LVCF_TEXT value, the pszText member must contain the address of the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

LVM_GETCOLUMNORDERARRAY

LVM_GETCOLUMNORDERARRAY
    wParam = (WPARAM) (int) iCount;
    lParam = (LPARAM) lpiArray;

Retrieves the current left-to-right order of columns in a list view control. You can send this message explicitly or use the ListView_GetColumnOrderArray macro.

iCount
Number of columns in the list view control.
lpiArray
Address of an array of integers that receives the index values of the columns in the list view control. The array must be large enough to hold iCount elements.

Version 4.70

LVM_GETCOLUMNWIDTH

LVM_GETCOLUMNWIDTH 
    wParam = (WPARAM) (int) iCol; 
    lParam = 0; 

Retrieves the width of a column in report or list view. You can send this message explicitly or by using the ListView_GetColumnWidth macro.

iCol
Index of the column. This parameter is ignored in list view.

LVM_GETCOUNTPERPAGE

LVM_GETCOUNTPERPAGE 
    wParam = 0; 
    lParam = 0; 

Calculates the number of items that can fit vertically in the visible area of a list view control when in list or report view. Only fully visible items are counted. You can send this message explicitly or by using the ListView_GetCountPerPage macro.

LVM_GETEDITCONTROL

LVM_GETEDITCONTROL 
    wParam = 0; 
    lParam = 0; 

Retrieves the handle to the edit control being used to edit a list view item's text. You can send this message explicitly or by using the ListView_GetEditControl macro.

If no label is being edited, the return value is NULL. The edit control is not created until after the LVN_BEGINLABELEDIT notification message is sent.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but you should not destroy it. To cancel editing, you can send the list view control a WM_CANCELMODE message.

The list view item being edited is the currently focused item—that is, the item in the focused state. To find an item based on its state, use the LVM_GETNEXTITEM message.

LVM_GETEXTENDEDLISTVIEWSTYLE

LVM_GETEXTENDEDLISTVIEWSTYLE
    wParam = 0;
    lParam = 0;

Retrieves the extended styles that are currently in use for a given list view control. You can send this message explicitly or use the ListView_GetExtendedListViewStyle macro.

Version 4.70

LVM_GETHEADER

LVM_GETHEADER
    wParam = 0;
    lParam = 0;

Retrieves the handle to the header control used by the list view control. You can send this message explicitly or use the ListView_GetHeader macro.

Version 4.70

LVM_GETHOTCURSOR

LVM_GETHOTCURSOR
    wParam = 0;
    lParam = 0;

Retrieves the HCURSOR value used when the pointer is over an item while hot tracking is enabled. You can send this message explicitly or use the ListView_GetHotCursor macro.

A list view control uses hot tracking and hover selection when the LVS_EX_TRACKSELECT style is set.

Version 4.70

LVM_GETHOTITEM

LVM_GETHOTITEM
    wParam = 0;
    lParam = 0;

Retrieves the index of the hot item. You can send this message explicitly or use the ListView_GetHotItem macro.

Version 4.70

LVM_GETHOVERTIME

LVM_GETHOVERTIME
    wParam = 0;
    lParam = 0;

Retrieves the amount of time that the mouse cursor must hover over an item before it is selected. You can send this message explicitly or use the ListView_GetHoverTime macro.

The hover time only affects list view controls that have the LVS_EX_TRACKSELECT, LVS_EX_ONECLICKACTIVATE, or LVS_EX_TWOCLICKACTIVATE extended list view style.

Version 4.71

LVM_GETIMAGELIST

LVM_GETIMAGELIST 
    wParam = (WPARAM) (int) iImageList; 
    lParam = 0; 

Retrieves the handle to an image list used for drawing list view items. You can send this message explicitly or by using the ListView_GetImageList macro.

iImageList
Image list to retrieve. This parameter can be one of the following values:
LVSIL_NORMAL Image list with large icons.
LVSIL_SMALL Image list with small icons.
LVSIL_STATE Image list with state images.

LVM_GETISEARCHSTRING

LVM_GETISEARCHSTRING 
    wParam = 0; 
    lParam = (LPARAM) (LPSTR) lpsz; 

Retrieves the incremental search string of a list view control. You can send this message explicitly or by using the ListView_GetISearchString macro.

lpsz
Address of a buffer that receives the incremental search string.

The incremental search string is the character sequence that the user types while the list view has the input focus. Each time the user types a character, the system appends the character to the search string and then searches for a matching item. If the system finds a match, it selects the item and, if necessary, scrolls it into view.

A time-out period is associated with each character that the user types. If the time-out period elapses before the user types another character, the incremental search string is reset.

LVM_GETITEM

LVM_GETITEM 
    wParam = 0; 
    lParam = (LPARAM) (LPLVITEM) pitem; 

Retrieves some or all of a list view item's attributes. You can send this message explicitly or by using the ListView_GetItem macro.

pitem
Address of an LVITEM structure that specifies the information to retrieve and receives information about the list view item.
When the message is sent, the iItem and iSubItem members identify the item or subitem to retrieve information about, and the mask member specifies which attributes to retrieve. For a list of possible values, see the description of the LVITEM structure.
If the mask member specifies the LVIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text, and the cchTextMax member must specify the size of the buffer.

If the mask member specifies the LVIF_STATE value, the stateMask member must specify the item state bits to retrieve. On output, the state member contains the values of the specified state bits.

LVM_GETITEMCOUNT

LVM_GETITEMCOUNT 
    wParam = 0; 
    lParam = 0; 

Retrieves the number of items in a list view control. You can send this message explicitly or by using the ListView_GetItemCount macro.

LVM_GETITEMPOSITION

LVM_GETITEMPOSITION 
    wParam = (WPARAM) (int) i; 
    lParam = (LPARAM) (POINT FAR *) ppt; 

Retrieves the position of a list view item. You can send this message explicitly or by using the ListView_GetItemPosition macro.

i
Index of the list view item.
ppt
Address of a POINT structure that receives the position of the item's upper-left corner, in view coordinates.

LVM_GETITEMRECT

LVM_GETITEMRECT 
    wParam = (WPARAM) (int) i; 
    lParam = (LPARAM) (LPRECT) prc; 

Retrieves the bounding rectangle for all or part of an item in the current view. You can send this message explicitly or by using the ListView_GetItemRect macro.

i
Index of the list view item.
prc
Address of a RECT structure that receives the bounding rectangle. When the message is sent, the left member of this structure is used to determine the portion of the list view item for which to retrieve the bounding rectangle. This will be one of the code values defined in ListView_GetItemRect.

This parameter is specified by the left member of the RECT structure pointed to by prc.

LVM_GETITEMSPACING

LVM_GETITEMSPACING 
    wParam = (WPARAM) (BOOL) fSmall; 
    lParam = 0; 

Determines the spacing between items in a list view control. You can send this message explicitly or by using the ListView_GetItemSpacing macro.

fSmall
View for which to retrieve the item spacing. This parameter is TRUE for small icon view, or FALSE for icon view.

LVM_GETITEMSTATE

LVM_GETITEMSTATE 
    wParam = (WPARAM) (int) i; 
    lParam = (LPARAM) (UINT) mask; 

Retrieves the state of a list view item. You can send this message explicitly or by using the ListView_GetItemState macro.

i
Index of the list view item.
mask
Specifies the state information to retrieve. This parameter can be a combination of the following values:
LVIS_CUT The item is marked for a cut-and-paste operation.
LVIS_DROPHILITED The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED The item has the focus, so it is surrounded by a standard focus rectangle. Although more than one item may be selected, only one item can have the focus.
LVIS_SELECTED The item is selected. The appearance of a selected item depends on whether it has the focus and also on the system colors used for selection.
LVIS_OVERLAYMASK Use this mask to retrieve the item's overlay image index.
LVIS_STATEIMAGEMASK Use this mask to retrieve the item's state image index.

An item's state information includes a set of bit flags as well as image list indexes that indicate the item's state image and overlay image.

See also LVM_SETITEMSTATE

LVM_GETITEMTEXT

LVM_GETITEMTEXT 
    wParam = (WPARAM) (int) iItem; 
    lParam = (LPARAM) (LPLVITEM) pitem; 

Retrieves the text of a list view item or subitem. You can send this message explicitly or by using the ListView_GetItemText macro.

iItem
Index of the list view item.
pitem
Address of an LVITEM structure. The iSubItem member specifies the index of a subitem, or it can be zero to get the item label. The pszText member points to a buffer that receives the text, and the cchTextMax member specifies the size of the buffer.

LVM_GETNEXTITEM

LVM_GETNEXTITEM 
    wParam = (WPARAM) (int) iStart; 
    lParam = MAKELPARAM((UINT) flags, 0); 

Searches for a list view item that has the specified properties and bears the specified relationship to a specified item. You can send this message explicitly or by using the ListView_GetNextItem macro.

iStart
Index of the item to begin the search with, or -1 to find the first item that matches the specified flags. The specified item itself is excluded from the search.
flags
Geometric relation of the requested item to the specified item and the state of the requested item, if one is specified.
The geometric relation can be one of the following values:

LVNI_ABOVE Searches for an item that is above the specified item.
LVNI_ALL Searches for a subsequent item by index (the default value).
LVNI_BELOW Searches for an item that is below the specified item.
LVNI_TOLEFT Searches for an item to the left of the specified item.
LVNI_TORIGHT Searches for an item to the right of the specified item.

The state can be zero, or it can be one or more of the following values:
LVNI_ACTIVATING The item has the LVIS_ACTIVATING state flag set.
LVNI_CUT The item has the LVIS_CUT state flag set.
LVNI_DROPHILITED The item has the LVIS_DROPHILITED state flag set.
LVNI_FOCUSED The item has the LVIS_FOCUSED state flag set.
LVNI_SELECTED The item has the LVIS_SELECTED state flag set.

If an item does not have all of the specified state flags set, the search continues with the next item.

LVM_GETNUMBEROFWORKAREAS

LVM_GETNUMBEROFWORKAREAS
    wParam = 0;
    lParam = (LPARAM)(LPUINT) lpuWorkAreas;

Retrieves the number of working areas in a list view control. You can send this message explicitly or use the ListView_GetNumberOfWorkAreas macro.

lpuWorkAreas
Address of a UINT value that receives the number of working areas in the list view control. If zero is placed in this variable, then no working areas are currently set. This value cannot be NULL.

Version 4.71

LVM_GETORIGIN

LVM_GETORIGIN 
    wParam = 0; 
    lParam = (LPARAM) (LPPOINT) lpptOrg; 

Retrieves the current view origin for a list view control. You can send this message explicitly or by using the ListView_GetOrigin macro.

lpptOrg
Address of a POINT structure that receives the view origin.

LVM_GETSELECTEDCOUNT

LVM_GETSELECTEDCOUNT 
    wParam = 0; 
    lParam = 0; 

Determines the number of selected items in a list view control. You can send this message explicitly or by using the ListView_GetSelectedCount macro.

LVM_GETSELECTIONMARK

LVM_GETSELECTIONMARK
    wParam = 0;
    lParam = 0;

Retrieves the selection mark from a list view control. You can send this message explicitly or use the ListView_GetSelectionMark macro.

The selection mark is the item index from which a multiple selection starts.

Version 4.71

See also LVM_SETSELECTIONMARK

LVM_GETSTRINGWIDTH

LVM_GETSTRINGWIDTH 
    wParam = 0; 
    lParam = (LPARAM) (LPCSTR) psz; 

Determines the width of a specified string using the specified list view control's current font. You can send this message explicitly or by using the ListView_GetStringWidth macro.

psz
Address of a null-terminated string.

The LVM_GETSTRINGWIDTH message returns the exact width, in pixels, of the specified string. If you use the returned string width as the column width in the LVM_SETCOLUMNWIDTH message, the string will be truncated. To get the column width that can contain the string without truncating it, you must add padding to the returned string width.

LVM_GETSUBITEMRECT

LVM_GETSUBITEMRECT
    wParam = (WPARAM)(int) iItem;
    lParam = (LPARAM)(LPRECT) lpRect;

Retrieves information about the bounding rectangle for a subitem in a list view control. You can send this message explicitly or by using the ListView_GetSubItemRect macro (recommended). This message is intended to be used only with list view controls that use the LVS_REPORT style.

iItem
Index of the subitem's parent item.
lpRect
Address of a RECT structure that will receive the subitem bounding rectangle information. Its members must be initialized according to the following member/value relationships:
MemberValue
top The one-based index of the subitem.
left Flag value (see following). Indicates the portion of the list view subitem for which to retrieve the bounding rectangle.
Flag Value Meaning
LVIR_BOUNDS Returns the bounding rectangle of the entire item, including the icon and label.
LVIR_ICON Returns the bounding rectangle of the icon or small icon.
LVIR_LABEL Returns the bounding rectangle of the entire item, including the icon and label. This is identical to LVIR_BOUNDS.

Version 4.70

LVM_GETTEXTBKCOLOR

LVM_GETTEXTBKCOLOR 
    wParam = 0; 
    lParam = 0; 

Retrieves the text background color of a list view control. You can send this message explicitly or by using the ListView_GetTextBkColor macro.

LVM_GETTEXTCOLOR

LVM_GETTEXTCOLOR 
    wParam = 0; 
    lParam = 0; 

Retrieves the text color of a list view control. You can send this message explicitly or by using the ListView_GetTextColor macro.

LVM_GETTOOLTIPS

LVM_GETTOOLTIPS
    wParam = 0;
    lParam = 0;

Retrieves the tooltip control that the list view control uses to display tooltips. You can send this message explicitly or use the ListView_GetToolTips macro.

See also LVM_SETTOOLTIPS

LVM_GETTOPINDEX

LVM_GETTOPINDEX 
    wParam = 0; 
    lParam = 0; 

Retrieves the index of the topmost visible item when in list or report view. You can send this message explicitly or by using the ListView_GetTopIndex macro.

LVM_GETUNICODEFORMAT

LVM_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Retrieves the UNICODE character format flag for the control. You can send this message explicitly or use the ListView_GetUnicodeFormat macro.

See also LVM_SETUNICODEFORMAT

LVM_GETVIEWRECT

LVM_GETVIEWRECT 
    wParam = 0; 
    lParam = (LPARAM) (RECT FAR *) prc; 

Retrieves the bounding rectangle of all items in the list view control. The list view must be in icon or small icon view. You can send this message explicitly or by using the ListView_GetViewRect macro.

prc
Address of a RECT structure that receives the bounding rectangle. All coordinates are relative to the visible area of the list view control.

LVM_GETWORKAREAS

LVM_GETWORKAREAS
    wParam = (WPARAM)(INT) nWorkAreas;
    lParam = (LPARAM)(LPRECT) lprc;

Retrieves the working areas from a list view control. You can send this message explicitly or use the ListView_GetWorkAreas macro.

nWorkAreas
The number of RECT structures in the array at lprc.
lprc
Address of an array of RECT structures that receive the current working areas of the list view control. Values in these structures are in client coordinates. nWorkAreas specifies the number of structures in this array.

Version 4.71

LVM_HITTEST

LVM_HITTEST 
    wParam = 0; 
    lParam = (LPARAM) (LPLVHITTESTINFO) pinfo; 

Determines which list view item, if any, is at a specified position. You can send this message explicitly or by using the ListView_HitTest macro.

pinfo
Address of an LVHITTESTINFO structure that contains the position to hit test and receives information about the results of the hit test.

LVM_INSERTCOLUMN

LVM_INSERTCOLUMN 
    wParam = (WPARAM) (int) iCol; 
    lParam = (LPARAM) (const LPLVCOLUMN) pcol; 

Inserts a new column in a list view control. You can send this message explicitly or by using the ListView_InsertColumn macro.

iCol
Index of the new column.
pcol
Address of an LVCOLUMN structure that contains the attributes of the new column.

LVM_INSERTITEM

LVM_INSERTITEM 
    wParam = 0; 
    lParam = (LPARAM) (const LPLVITEM) pitem; 

Inserts a new item in a list view control. You can send this message explicitly or by using the ListView_InsertItem macro.

pitem
Address of an LVITEM structure that specifies the attributes of the list view item. The iItem member specifies the index of the new item.
You cannot use ListView_InsertItem or LVM_INSERTITEM to insert subitems; the iSubItem member of the LVITEM structure must be zero.

If a list view control has either the LVS_SORTASCENDING or LVS_SORTDESCENDING window style, an LVM_INSERTITEM message will fail if you try to insert an item that has LPSTR_TEXTCALLBACK as the pszText member of its LVITEM structure.

LVM_REDRAWITEMS

LVM_REDRAWITEMS 
    wParam = (int) iFirst;
    lParam = (int) iLast;

Forces a list view control to redraw a range of items. You can send this message explicitly or by using the ListView_RedrawItems macro.

iFirst
Index of the first item to redraw.
iLast
Index of the last item to redraw.

The specified items are not actually redrawn until the list view window receives a WM_PAINT message to repaint. To repaint immediately, call the UpdateWindow function after using this macro.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.