
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.
This section contains information about messages used with list view controls.
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.
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
wParam = (WPARAM) (int) code;
lParam = 0;
Arranges items in icon view. You can send this message explicitly or by using the ListView_Arrange macro.
| 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
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.
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
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.
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.
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.
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
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.
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.
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
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.
Version 4.71
See also LVM_SETBKIMAGE
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
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.
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.
Version 4.70
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.
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
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 itemthat is, the item in the focused state. To find an item based on its state, use the LVM_GETNEXTITEM message.
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
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
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
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
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
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.
| LVSIL_NORMAL | Image list with large icons. |
| LVSIL_SMALL | Image list with small icons. |
| LVSIL_STATE | Image list with state images. |
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.
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
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.
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
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
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.
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.
This parameter is specified by the left member of the RECT structure pointed to by prc.
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.
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.
| 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
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.
If you can send this message implicitly by using the ListView_GetItemText macro, there is no return value.
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.
| 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. |
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.
Version 4.71
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.
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
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
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.
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
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.
| Member | Value |
| 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
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
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
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
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
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
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.
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.
Version 4.71
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.
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.
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.
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
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.
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.