
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.
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.
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.
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.
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.
| 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
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.
If the list view control has the LVS_AUTOARRANGE style, the list view control is arranged after the position of the item is set.
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.
See also POINT
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.
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.
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
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.
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.
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
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.
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 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.
See also ListView_GetToolTips
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.
See also ListView_GetUnicodeFormat
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.
Version 4.71
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.
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.
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.
Version 4.70
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.
This section contains information about the notification messages sent by list view controls.
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.
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.
To prevent the user from editing the label, return TRUE.
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
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.
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.
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.
To receive subsequent LVN_DELETEITEM notification messages, return FALSE.
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
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.
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.
If the pszText member of the LVITEM structure is NULL, the return value is ignored.
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
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.
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
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.
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
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.
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.
Version 4.71
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.
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
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.
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.
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.
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.
Version 4.70
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.
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
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.
Search information is sent in the form of an LVFINDINFO structure, which is a member of the NMLVFINDITEM structure.
Version 4.70
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.
Version 4.70
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.
See also LVN_GETDISPINFO
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.
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
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.
When dwDrawStage equals CDDS_PREPAINT:
|
When dwDrawStage equals CDDS_ITEMPREPAINT:
|
Version 4.70
See also Using Custom Draw
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.
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
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.
Version 4.70
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.
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.
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.