ListView_SetItem
List View Control Reference

ListView_SetItem


BOOL ListView_SetItem(
    HWND hwnd, 		
    const LPLVITEM pitem		
);		

Sets some or all of a list view item's attributes. You can also use ListView_SetItem to set the text of a subitem. You can use this macro or send the LVM_SETITEM message explicitly.

hwnd
Handle to the list view control.
pitem
Address of an LVITEM structure that contains the new item attributes. The iItem and iSubItem members identify the item or subitem, and the mask member specifies which attributes to set.
If the mask member specifies the LVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.
If the mask member specifies the LVIF_STATE value, the stateMask member specifies which item states to change, and the state member contains the values for those states.

To set the attributes of a list view item, set the iItem member of the LVITEM structure to the index of the item, and set the iSubItem member to zero. For an item, you can use the state, pszText, iImage, and lParam members of the LVITEM structure to modify these item parameters.

To set the text of a subitem, set the iItem and iSubItem members to indicate the specific subitem, and use the pszText member to specify the text. Alternatively, you can use the ListView_SetItemText macro to set the text of a subitem. You cannot set the state, iImage, or lParam members for subitems because subitems do not have these attributes.

ListView_SetItemCount

void ListView_SetItemCount(
    HWND hwndLV,
    int cItems
);

Causes the list view control to allocate memory for the specified number of items. You can use this macro or send the LVM_SETITEMCOUNT message explicitly.

hwndLV
Handle to a list view control.
cItems
Number of items for which the list view control should allocate memory.

If the list view control was created without the LVS_OWNERDATA style, this macro causes the control to allocate its internal data structures for the specified number of items. This prevents the control from having to allocate the data structures every time an item is added.

If the list view control was created with the LVS_OWNERDATA style (a virtual list view), the ListView_SetItemCountEx macro should be used.

ListView_SetItemCountEx

void ListView_SetItemCountEx(
    HWND hwndLV,
    int cItems,
    DWORD dwFlags
);

Sets the virtual number of items in a virtual list view control. You can use this macro or send the LVM_SETITEMCOUNT message explicitly.

hwndLV
Handle to a virtual list view control.
cItems
Number of items that the list view control will contain.
dwFlags
Values that specify the behavior of the list view control after resetting the item count. This value can be a combination of the following:
LVSICF_NOINVALIDATEALL The list view control will not repaint unless affected items are currently in view.
LVSICF_NOSCROLL The list view control will not change the scroll position when the item count changes.

This macro is intended only for list view controls that use the LVS_OWNERDATA and LVS_REPORT or LVS_LIST styles.

If the list view control was created with the LVS_OWNERDATA style, this macro sets the virtual number of items that the control contains.

If the list view control was created without the LVS_OWNERDATA style, the ListView_SetItemCount macro should be used.

Version 4.70

ListView_SetItemPosition

BOOL ListView_SetItemPosition(
    HWND hwnd, 		
    int i, 		
    int x, 		
    int y		
);		

Moves an item to a specified position in a list view control (in icon or small icon view). You can use this macro or send the LVM_SETITEMPOSITION message explicitly.

hwnd
Handle to the list view control.
i
Index of the list view item.
x and y
New position of the item's upper-left corner, in view coordinates.

If the list view control has the LVS_AUTOARRANGE style, the list view control is arranged after the position of the item is set.

ListView_SetItemPosition32

void ListView_SetItemPosition32(
    HWND hwnd, 		
    int iItem, 		
    int x, 		
    int y		
);		

Moves an item to a specified position in a list view control (in icon or small icon view). This macro differs from the ListView_SetItemPosition macro in that it uses 32-bit coordinates. You can use the ListView_SetItemPosition32 macro or send the LVM_SETITEMPOSITION32 message explicitly.

hwnd
Handle to the list view control.
iItem
Index of the list view item for which to set the position.
x and y
New horizontal and vertical coordinates of the item.

See also POINT

ListView_SetItemState

BOOL WINAPI ListView_SetItemState(
    HWND hwnd, 		
    int i, 		
    UINT state, 		
    UINT mask		
);		

Changes the state of an item in a list view control. You can use this macro or send the LVM_SETITEMSTATE message explicitly.

hwnd
Handle to the list view control.
i
Index of the list view item.
state
Specifies the new state bits for the item. The mask parameter indicates the valid bits of the state parameter. The macro ignores bits in the state parameter if the corresponding bit is not set in the mask parameter.

The low-order byte contains a set of bit flags that indicate the item's state. This byte 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.

Bits 8 through 11 of the state parameter specify the one-based index of an overlay image in the control's image lists. Both the full-sized icon image list and the small icon image list can have overlay images. The overlay image is superimposed over the item's icon image. If these bits are zero, the item has no overlay image. To isolate these bits, use the LVIS_OVERLAYMASK mask. To specify an overlay index, use the INDEXTOOVERLAYMASK macro.

Bits 12 through 15 of the state parameter specify the one-based index of an image in the control's state image list. The state image is displayed next to an item's icon to indicate an application-defined state. If these bits are zero, the item has no state image. To isolate these bits, use the LVIS_STATEIMAGEMASK mask. To specify a state image index, use the INDEXTOSTATEIMAGEMASK macro.

mask
Specifies the bits of the state parameter that you want to set. To set an item's overlay image index, set the LVIS_OVERLAYMASK bits. To set an item's state image index, set the LVIS_STATEIMAGEMASK bits.

An item's state value includes a set of bit flags that indicate the item's state. The state value can also include image list indexes that indicate the item's state image and overlay image.

The mask parameter specifies the state bits you want to modify, and the state parameter specifies the new value for those bits. To set a bit in the item's internal state, set it in both the mask and state parameters. To clear a bit in the item's internal state, set it in the mask parameter and clear it in the state parameter. To leave a bit unchanged in the item's internal state, clear it in the mask parameter.

See also ListView_GetItemState

ListView_SetItemText

VOID WINAPI ListView_SetItemText(
    HWND hwnd, 		
    int i, 		
    int iSubItem, 		
    LPCSTR pszText		
);		

Changes the text of a list view item or subitem. You can use this macro or send the LVM_SETITEMTEXT message explicitly.

hwnd
Handle to the list view control.
i
Index of the list view item.
iSubItem
Index of the subitem. To set the item label, set iSubItem to zero.
pszText
Address of a null-terminated string that contains the new text.
This parameter can be LPSTR_TEXTCALLBACK to indicate a callback item for which the parent window stores the text. In this case, the list view control sends the parent an LVN_GETDISPINFO notification message when it needs the text.
This parameter can be NULL.

ListView_SetSelectionMark

INT ListView_SetSelectionMark(
    HWND hwndLV,
    INT  iIndex
);

Sets the selection mark in a list view control. You can use this macro or send the LVM_SETSELECTIONMARK message explicitly.

hwndLV
Handle to a list view control.
iIndex
Zero-based index of the list view item to be selected.

The selection mark is the item index from which a multiple selection starts. This macro does not affect the selection state of the item.

Version 4.71

See also ListView_GetSelectionMark

ListView_SetTextBkColor

BOOL ListView_SetTextBkColor(
    HWND hwnd, 		
    COLORREF clrText		
);		

Sets the background color of text in a list view control. You can use this macro or send the LVM_SETTEXTBKCOLOR message explicitly.

hwnd
Handle to the list view control.
clrText
New text color.

ListView_SetTextColor

BOOL ListView_SetTextColor(
    HWND hwnd, 		
    COLORREF clrText		
);		

Sets the text color of a list view control. You can use this macro or send the LVM_SETTEXTCOLOR message explicitly.

hwnd
Handle to the list view control.
clrText
New text color.

ListView_SetToolTips

HWND ListView_SetToolTips(
    HWND hwnd,
    HWND hwndToolTip
);

Sets the tooltip control that the list view control will use to display tooltips. You can use this macro or send the LVM_SETTOOLTIPS message explicitly.

hwnd
Handle to the list view control.
hwndToolTip
Handle to the tooltip control to be set.

See also ListView_GetToolTips

ListView_SetUnicodeFormat

BOOL ListView_SetUnicodeFormat(
    HWND hwnd,
    BOOL fUnicode
);

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can use this macro or send the LVM_SETUNICODEFORMAT message explicitly.

hwnd
Handle to the control.
fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

See also ListView_GetUnicodeFormat

ListView_SetWorkAreas

void ListView_SetWorkAreas(
    HWND hwndLV,
    INT nWorkAreas,
    LPRECT lprc
);

Sets the working area within a list view control. You can use this macro or send the LVM_SETWORKAREAS message explicitly.

hwndLV
Handle to a list view control.
nWorkAreas
Number of RECT structures in the array at lprc. The maximum number of working areas allowed is defined by the LV_MAX_WORKAREAS value.
lprc
Address of an array of RECT structures that contain the new working areas of the list view control. Values in these structures are in client coordinates. If this parameter is NULL, the working area will be set to the client area of the control. nWorkAreas specifies the number of structures in this array.

Version 4.71

ListView_SortItems

BOOL ListView_SortItems(
    HWND hwnd, 		
    PFNLVCOMPARE pfnCompare, 		
    LPARAM lParamSort		
);		

Uses an application-defined comparison function to sort the items of a list view control. The index of each item changes to reflect the new sequence. You can use this macro or send the LVM_SORTITEMS message explicitly.

hwnd
Handle to the list view control.
pfnCompare
Address of the application-defined comparison function. The comparison function is called during the sort operation each time the relative order of two list items needs to be compared.
lParamSort
Application-defined value that is passed to the comparison function.

The comparison function has the following form:

int CALLBACK CompareFunc(LPARAM lParam1, LPARAM lParam2, 
	LPARAM lParamSort); 
 

The lParam1 parameter is the 32-bit value associated with the first item being compared; and the lParam2 parameter is the value associated with the second item. These are the values that were specified in the lParam member of the items' LVITEM structure when they were inserted into the list. The lParamSort parameter is the same value passed to the LVM_SORTITEMS message.

The comparison function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

ListView_SubItemHitTest

INT ListView_SubItemHitTest(
    HWND hwndLV,
    LPLVHITTESTINFO pInfo
);

Determines which list view item or subitem is located at a given position. You can use this macro or send the LVM_SUBITEMHITTEST message explicitly.

hwndLV
Handle to the list view control that will be hit-tested.
pInfo
Address of an LVHITTESTINFO structure. The POINT structure within LVHITTESTINFO must be set to the client coordinates to be hit-tested.

Version 4.70

ListView_Update

BOOL ListView_Update(
    HWND hwnd, 		
    int iItem		
);		

Updates a list view item. If the list view control has the LVS_AUTOARRANGE style, this macro causes the list view control to be arranged. You can use this macro or send the LVM_UPDATE message explicitly.

hwnd
Handle to the list view control.
iItem
Index of the item to update.

List View Control Notification Messages

This section contains information about the notification messages sent by list view controls.

LVN_BEGINDRAG

LVN_BEGINDRAG 
    pnmv = (LPNMLISTVIEW) lParam; 

Notifies a list view control's parent window that a drag-and-drop operation involving the left mouse button is being initiated. This notification message is sent in the form of a WM_NOTIFY message.

pnmv
Address of an NMLISTVIEW structure. The iItem member identifies the item being dragged, and the other members are zero.

LVN_BEGINLABELEDIT

LVN_BEGINLABELEDIT 
    pdi = (LPNMLVDISPINFO) lParam; 

Notifies a list view control's parent window about the start of label editing for an item. This notification message is sent in the form of a WM_NOTIFY message.

pdi
Address of an NMLVDISPINFO structure. The item member of this structure is an LVITEM structure whose iItem member identifies the item being edited.

When the user begins editing an item label, the parent window of the list view control receives an LVN_BEGINLABELEDIT notification message. When the user cancels or completes the editing, the parent window receives an LVN_ENDLABELEDIT notification message.

LVN_BEGINRDRAG

LVN_BEGINRDRAG 
    pnmv = (LPNMLISTVIEW) lParam; 

Notifies a list view control's parent window that a drag-and-drop operation involving the right mouse button is being initiated. This notification message is sent in the form of a WM_NOTIFY message.

pnmv
Address of an NMLISTVIEW structure. The iItem member identifies the item being dragged, and the other members are zero.

LVN_COLUMNCLICK

LVN_COLUMNCLICK 
    pnmv = (LPNMLISTVIEW) lParam; 

Notifies a list view control's parent window that a column was clicked. This notification message is sent in the form of a WM_NOTIFY message.

pnmv
Address of an NMLISTVIEW structure. The iItem member is -1, and the iSubItem member identifies the column. All other members are zero.

LVN_DELETEALLITEMS

LVN_DELETEALLITEMS 
    pnmv = (LPNMLISTVIEW) lParam; 

Notifies a list view control's parent window that all items in the control are about to be deleted. This notification message is sent in the form of a WM_NOTIFY message.

pnmv
Address of an NMLISTVIEW structure. The iItem member is -1, and the other members are zero.

A list view control sends the LVN_DELETEALLITEMS notification message when it is destroyed or when it receives the LVM_DELETEALLITEMS message. If LVN_DELETEALLITEMS does not return TRUE, the control will also send an LVN_DELETEITEM notification message as each item is deleted.

If the LVN_DELETEALLITEMS message handler is in a dialog procedure, return TRUE from the dialog procedure, and use the SetWindowLong function with DWL_MSGRESULT to set the message return value.

LVN_DELETEITEM

LVN_DELETEITEM 
    pnmv = (LPNMLISTVIEW) lParam; 

Notifies a list view control's parent window that an item is about to be deleted. This notification message is sent in the form of a WM_NOTIFY message.

pnmv
Address of an NMLISTVIEW structure. The iItem member identifies the item being deleted. All other members of this structure are zero.

LVN_ENDLABELEDIT

LVN_ENDLABELEDIT 
    pdi = (LPNMLVDISPINFO) lParam; 

Notifies a list view control's parent window about the end of label editing for an item. This notification message is sent in the form of a WM_NOTIFY message.

pdi
Address of an NMLVDISPINFO structure. The item member of this structure is an LVITEM structure whose iItem member identifies the item being edited. The pszText member of item contains a valid value when the LVN_ENDLABELEDIT message is sent, regardless of whether the LVIF_TEXT flag is set in the mask member of the LVITEM structure.

If the user cancels editing, the pszText member of the LVITEM structure is NULL; otherwise, pszText is the address of the edited text.

When the user begins editing an item label, the parent window of the list view control receives an LVN_BEGINLABELEDIT notification message. When the user cancels or completes the editing, the parent window receives an LVN_ENDLABELEDIT notification message.

LVN_GETDISPINFO

LVN_GETDISPINFO 
    pnmv = (LPNMLVDISPINFO) lParam; 

Sent by a list view control to its parent window. It is a request for the parent window to provide information needed to display or sort a list view item. This notification message is sent in the form of a WM_NOTIFY message.

pnmv
Address of an NMLVDISPINFO structure. On input, the LVITEM structure contained in this structure specifies the type of information required and identifies the item or subitem of interest.
Use the LVITEM structure to return the requested information to the control. If your message handler sets the LVIF_DI_SETITEM flag in the mask member of the LVITEM structure, the list view control stores the requested information and will not ask for it again.

A list view control sends the LVN_GETDISPINFO message for items for which the application stores callback information. The information can be the text or icon information stored for a callback item. It can also be item state information specified by the list view control's callback mask.

For more informationon list view callbacks, see Callback Items and the Callback Mask.

See also LVN_SETDISPINFO

LVN_GETINFOTIP

LVN_GETINFOTIP
    pGetInfoTip = (LPNMLVGETINFOTIP)lParam;

Sent by a large icon view list view control that has the LVS_EX_INFOTIP extended style. This notification is sent when the list view control is requesting additional text information to be displayed in a tooltip. It is sent in the form of a WM_NOTIFY message.

pGetInfoTip
Address of an NMLVGETINFOTIP structure that contains information about this notification.

This notification is only sent by list view controls that have the LVS_ICON style and the LVS_EX_INFOTIP extended style.

Version 4.71

LVN_INSERTITEM

LVN_INSERTITEM 
    pnmv = (LPNMLISTVIEW) lParam; 

Notifies a list view control's parent window that a new item was inserted. This notification message is sent in the form of a WM_NOTIFY message.

pnmv
Address of an NMLISTVIEW structure. The iItem member identifies the new item, and the other members are zero.

LVN_HOTTRACK

LVN_HOTTRACK
    lpnmlv = (LPNMLISTVIEW)lParam;

Sent by a list view control when the user moves the mouse over an item. This notification is only sent by list view controls that have the LVS_EX_TRACKSELECT extended list view style. It is sent in the form of a WM_NOTIFY message.

lpnmlv
Address of an NMLISTVIEW structure that contains information about this notification. The iItem, iSubItem, and ptAction members of this structure contain information about the item. The receiving application can modify the iItem member to specify the item that will be selected. If iItem is set to -1, no item will be selected.

Version 4.71

LVN_ITEMACTIVATE

LVN_ITEMACTIVATE
#if (_WIN32_IE >= 0x0400)
    lpnmia = (LPNMITEMACTIVATE)lParam;
#else
    lpnm = (LPNMHDR)lParam;
#endif

Sent by a list view control when the user activates an item. This notification is sent in the form of a WM_NOTIFY message.

lpnmia
Version 4.71. Address of an NMITEMACTIVATE structure that contains information about this notification.
lpnm
Version 4.70 and earlier. Address of an NMHDR structure that contains information about this notification.

To obtain the items being activated, the receiving application should use the LVM_GETSELECTEDCOUNT message to get the number of items that are selected and then send the LVM_GETNEXTITEM message with LVNI_SELECTED until all of the items have been retrieved.

Version 4.70

LVN_ITEMCHANGED

LVN_ITEMCHANGED 
    pnmv = (LPNMLISTVIEW) lParam; 

Notifies a list view control's parent window that an item has changed. This notification message is sent in the form of a WM_NOTIFY message.

pnmv
Address of an NMLISTVIEW structure that identifies the item and specifies which of its attributes have changed.

LVN_ITEMCHANGING

LVN_ITEMCHANGING 
    pnmv = (LPNMLISTVIEW) lParam; 

Notifies a list view control's parent window that an item is changing. This notification message is sent in the form of a WM_NOTIFY message.

pnmv
Address of an NMLISTVIEW structure that identifies the item and specifies which of its attributes are changing.

LVN_KEYDOWN

LVN_KEYDOWN 
    pnkd = (LPNMLVKEYDOWN) lParam; 

Notifies a list view control's parent window that a key has been pressed. This notification message is sent in the form of a WM_NOTIFY message.

pnkd
Address of an NMLVKEYDOWN structure.

LVN_MARQUEEBEGIN

LVN_MARQUEEBEGIN
    pnmv = (LPNMLISTVIEW) lParam;

Notifies a list view control's parent window that a bounding box (marquee) selection has begun. This notification message is sent in the form of a WM_NOTIFY message.

Note A bounding box selection is the process of clicking the list view window's client area and dragging to select multiple items simultaneously.

pnmv
Address of an NMHDR structure.

Version 4.70

LVN_ODCACHEHINT

LVN_ODCACHEHINT
    pCachehint = (NMLVCACHEHINT *)lParam;

Sent by a virtual list view control when the contents of its display area have changed. For example, a list view control sends this notification when the user scrolls the control's display. The LVN_ODCACHEHINT notification message is sent in the form of a WM_NOTIFY message.

pCachehint
Address of an NMLVCACHEHINT structure containing information about the range of items to be cached.

Handling this message allows the application to update the item information held in cache so that it is readily available when an LVN_GETDISPINFO notification message is sent.

Note that this message is not always an exact representation of the items that will be requested by LVN_GETDISPINFO. Therefore, if the requested item is not cached while handling LVN_GETDISPINFO, the application must be prepared to supply the requested information from a source outside the cache.

Version 4.70

LVN_ODFINDITEM

LVN_ODFINDITEM
    pFindInfo = (PNMLVFINDITEM) lParam;

Sent by a virtual list view control when it needs the owner to find a particular callback item. For example, the control will send this notification when it receives shortcut keyboard input or when it receives an LVM_FINDITEM message.

pFindInfo
Address of an NMLVFINDITEM structure that includes information to be used for the search.

Search information is sent in the form of an LVFINDINFO structure, which is a member of the NMLVFINDITEM structure.

Version 4.70

LVN_ODSTATECHANGED

LVN_ODSTATECHANGED
    lpStateChange = (LPNMLVODSTATECHANGE) lParam;

Sent by a list view control when the state of an item or range of items has changed. This notification is sent in the form of a WM_NOTIFY message.

lpStateChange
Address of an NMLVODSTATECHANGE structure that contains information about the item or items that have changed.

Version 4.70

LVN_SETDISPINFO

LVN_SETDISPINFO 
    pnmv = (LPNMLVDISPINFO) lParam; 

Notifies a list view control's parent window that it must update the information it maintains for an item. This notification message is sent in the form of a WM_NOTIFY message.

pnmv
Address of an NMLVDISPINFO structure that specifies information for the changed item. The item member of this structure is an LVITEM structure that contains information about the item that was changed. The pszText member of item contains a valid value, regardless of whether the LVIF_TEXT flag is set in the mask member of this structure.

See also LVN_GETDISPINFO

NM_CLICK (list view)

NM_CLICK
    lpnmlv = (LPNMLISTVIEW) lParam;

Sent by a list view control when the user clicks an item with the left mouse button. This notification message is sent in the form of a WM_NOTIFY message.

lpnmlv
Version 4.71. Address of an NMLISTVIEW structure that contains additional information about this notification message. The iItem, iSubItem, and ptAction members of this structure contain information about the item.

This notification is identical to the standard NM_CLICK notification except that, in version 4.71 and later, the list view supplies an NMLISTVIEW structure instead of an NMHDR structure for the lParam.

NM_CUSTOMDRAW (list view)

NM_CUSTOMDRAW
    lpNMCustomDraw = (LPNMLVCUSTOMDRAW) lParam;

Sent by a list view control to notify its parent windows about drawing operations. This notification is sent in the form of a WM_NOTIFY message.

lpNMCustomDraw
Address of a NMLVCUSTOMDRAW structure that contains information about the drawing operation.

Version 4.70

See also Using Custom Draw

NM_DBLCLK (list view)

NM_DBLCLK
    lpnmlv = (LPNMLISTVIEW) lParam;

Sent by a list view control when the user double-clicks an item with the left mouse button. This notification message is sent in the form of a WM_NOTIFY message.

lpnmlv
Version 4.71. Address of an NMLISTVIEW structure that contains additional information about this notification message. The iItem, iSubItem, and ptAction members of this structure contain information about the item.

This notification is identical to the standard NM_DBLCLK notification except that, in version 4.71 and later, the list view supplies an NMLISTVIEW structure instead of an NMHDR structure for the lParam.

NM_HOVER (list view)

NM_HOVER
    lpnmh = (LPNMHDR) lParam;

Sent by a list view control when the mouse hovers over an item. This notification message is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Version 4.70

NM_KILLFOCUS (list view)

NM_KILLFOCUS 
    lpnmh = (LPNMHDR) lParam; 

Notifies a list view control's parent window that the control has lost the input focus. NM_KILLFOCUS is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

NM_RCLICK (list view)

NM_RCLICK
    lpnmlv = (LPNMLISTVIEW) lParam;

Sent by a list view control when the user clicks an item with the right mouse button. This notification message is sent in the form of a WM_NOTIFY message.

lpnmlv
Version 4.71. Address of an NMLISTVIEW structure that contains additional information about this notification message. The iItem, iSubItem, and ptAction members of this structure contain information about the item.

This notification is identical to the standard NM_RCLICK notification except that, in version 4.71 and later, the list view supplies a NMLISTVIEW structure instead of an NMHDR structure for the lParam.

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