ListView_GetExtendedListViewStyle
List View Control Reference

ListView_GetExtendedListViewStyle


DWORD ListView_GetExtendedListViewStyle(
    HWND hwndLV
);

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

hwndLV
Handle to a list view control.

Version 4.70

ListView_GetHeader

HWND ListView_GetHeader(
    HWND hwndLV
);

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

hwndLV
Handle to a list view control.

Version 4.70

ListView_GetHotCursor

HCURSOR ListView_GetHotCursor(
    HWND hwndLV
);

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

hwndLV
Handle to a list view control.

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

Version 4.70

ListView_GetHotItem

INT ListView_GetHotItem(
    HWND hwndLV
);

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

hwndLV
Handle to a list view control.

Version 4.70

ListView_GetHoverTime

DWORD ListView_GetHoverTime(
   HWND hwndLV
);

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

hwndLV
Handle to a list view control.

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

ListView_GetImageList

HIMAGELIST ListView_GetImageList(
    HWND hwnd, 		
    int iImageList		
);		

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

hwnd
Handle to the list view control.
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.

ListView_GetISearchString

BOOL ListView_GetISearchString(
    HWND hwnd, 		
    LPSTR lpsz		
);		

Retrieves the incremental search string of a list view control. You can use this macro or send the LVM_GETISEARCHSTRING message explicitly.

hwnd
Handle to the list view control.
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.

ListView_GetItem

BOOL ListView_GetItem(
    HWND hwnd, 		
    LPLVITEM pitem		
);		

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

hwnd
Handle to the list view control.
pitem
Address of an LVITEM structure that specifies the information to retrieve and receives information about the list view item.

When the LVM_GETITEM 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.

ListView_GetItemCount

int ListView_GetItemCount(
    HWND hwnd		
);		

Retrieves the number of items in a list view control. You can use this macro or send the LVM_GETITEMCOUNT message explicitly.

hwnd
Handle to the list view control.

ListView_GetItemPosition

BOOL ListView_GetItemPosition(
    HWND hwnd, 		
    int i, 		
    POINT FAR *ppt		
);		

Retrieves the position of a list view item. You can use this macro or explicitly send the LVM_GETITEMPOSITION message.

hwnd
Handle to the list view control.
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.

ListView_GetItemRect

BOOL ListView_GetItemRect(
    HWND hwnd, 		
    int i, 		
    RECT FAR *prc, 		
    int code		
);		

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

hwnd
Handle to the list view control.
i
Index of the list view item.
prc
Address of a RECT structure that receives the bounding rectangle. When the LVM_GETITEMRECT message is sent, the left member of this structure contains the value of the code parameter.
code
Portion of the list view item for which to retrieve the bounding rectangle. This parameter can be one of the following values:
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 item text.
LVIR_SELECTBOUNDS Returns the union of the LVIR_ICON and LVIR_LABEL rectangles, but excludes columns in details view.

ListView_GetItemSpacing

DWORD ListView_GetItemSpacing(
    HWND hwnd, 		
    BOOL fSmall		
);		

Determines the spacing between items in a list view control. You can use this macro or send the LVM_GETITEMSPACING message explicitly.

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

ListView_GetItemState

UINT WINAPI ListView_GetItemState(
    HWND hwnd, 		
    int i, 		
    UINT mask		
);		

Retrieves the state of a list view item. You can use this macro or send the LVM_GETITEMSTATE message explicitly.

hwnd
Handle to the list view control.
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 ListView_SetItemState

ListView_GetItemText

void WINAPI ListView_GetItemText(
    HWND hwnd, 		
    int iItem, 		
    int iSubItem, 		
    LPSTR pszText, 		
    int cchTextMax		
);		

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

hwnd
Handle to the list view control.
iItem
Index of the list view item.
iSubItem
Index of the subitem, or zero to retrieve the item label.
pszText
Address of the buffer that receives the item or subitem text.
cchTextMax
Size of the buffer, in bytes.

See also LVITEM

ListView_GetNextItem

int ListView_GetNextItem(
    HWND hwnd, 		
    int iStart, 		
    UINT flags		
);		

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

hwnd
Handle to the list view control.
iStart
Index of the item with which to begin the search, 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, if specified, the state of the requested item. For a list of possible values, see the description of the flags parameter in the LVM_GETNEXTITEM message. If an item does not have all of the specified state flags set, the search continues with the next item.

ListView_GetNumberOfWorkAreas

BOOL ListView_GetNumberOfWorkAreas(
    HWND hwndLV,
    LPUINT lpuWorkAreas
);

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

hwndLV
Handle to the list view control.
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

ListView_GetOrigin

BOOL ListView_GetOrigin(
    HWND hwnd, 		
    LPPOINT lpptOrg		
);		

Retrieves the current view origin for a list view control. You can use this macro or send the LVM_GETORIGIN message explicitly.

hwnd
Handle to the list view control.
lpptOrg
Address of a POINT structure that receives the view origin.

ListView_GetSelectedCount

UINT ListView_GetSelectedCount(
    HWND hwnd		
);		

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

hwnd
Handle to the list view control.

ListView_GetSelectionMark

INT ListView_GetSelectionMark(
    HWND hwndLV
);

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

hwndLV
Handle to a list view control.

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

Version 4.71

See also ListView_SetSelectionMark

ListView_GetStringWidth

int ListView_GetStringWidth(
    HWND hwnd, 		
    LPCSTR psz		
);		

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

hwnd
Handle to the list view control.
psz
Address of a null-terminated string.

The ListView_GetStringWidth macro returns the exact width, in pixels, of the specified string. If you use the returned string width as the column width in a call to the ListView_SetColumnWidth macro, 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.

ListView_GetSubItemRect

BOOL ListView_GetSubItemRect(
    HWND hwndLV,
    int iItem,
    int iSubItem,
    int code,
    LPRECT lpRect
);

Retrieves information about the rectangle that surrounds a subitem in a list view control. You can use this macro (recommended) or send the LVM_GETSUBITEMRECT message explicitly. This macro is intended to be used only on list view controls that use the LVS_REPORT style.

hwndLV
Handle to a list view control.
iItem
Index of the subitem's parent item.
iSubItem
The one-based index of the subitem.
code
Portion of the list view subitem for which to retrieve the bounding rectangle information. This value can be one of the following:
LVIR_BOUNDSReturns the bounding rectangle of the entire item, including the icon and label.
LVIR_ICONReturns the bounding rectangle of the icon or small icon.
LVIR_LABELReturns the bounding rectangle of the entire item, including the icon and label. This is identical to LVIR_BOUNDS.
lpRect
Address of a RECT structure that receives the subitem bounding rectangle information.

Version 4.70

ListView_GetTextBkColor

COLORREF ListView_GetTextBkColor(
    HWND hwnd		
);		

Retrieves the text background color of a list view control. You can use this macro or send the LVM_GETTEXTBKCOLOR message explicitly.

hwnd
Handle to the list view control.

ListView_GetTextColor

COLORREF ListView_GetTextColor(
    HWND hwnd
);		

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

hwnd
Handle to the list view control.

ListView_GetToolTips

HWND ListView_GetToolTips(
    HWND hwnd
);

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

hwnd
Handle to the list view control.

See also ListView_SetToolTips

ListView_GetTopIndex

int ListView_GetTopIndex(
    HWND hwnd		
);		

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

hwnd
Handle to the list view control.

ListView_GetUnicodeFormat

BOOL ListView_GetUnicodeFormat(
    HWND hwnd
);

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

hwnd
Handle to the control.

See also ListView_SetUnicodeFormat

ListView_GetViewRect

BOOL ListView_GetViewRect(
    HWND hwnd, 		
    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 use this macro or send the LVM_GETVIEWRECT message explicitly.

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

ListView_GetWorkAreas

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

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

hwndLV
Handle to the list view control.
nWorkAreas
The number of RECT structures in the array at lprc.
lprc
Address of an array of RECT structures that receive the 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

ListView_HitTest

int ListView_HitTest(
    HWND hwnd, 		
    LPLVHITTESTINFO pinfo		
);		

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

hwnd
Handle to the list view control.
pinfo
Address of an LVHITTESTINFO structure that contains the position to hit test and receives information about the results of the hit test.

ListView_InsertColumn

int ListView_InsertColumn(
    HWND hwnd, 		
    int iCol, 		
    const LPLVCOLUMN pcol		
);		

Inserts a new column in a list view control. You can use this macro or send the LVM_INSERTCOLUMN message explicitly.

hwnd
Handle to the list view control.
iCol
Index of the new column.
pcol
Address of an LVCOLUMN structure that contains the attributes of the new column.

ListView_InsertItem

int ListView_InsertItem(
    HWND hwnd, 		
    const LPLVITEM pitem		
);		

Inserts a new item in a list view control. You can use this macro or send the LVM_INSERTITEM message explicitly.

hwnd
Handle to the list view control.
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.

ListView_RedrawItems

BOOL ListView_RedrawItems(
    HWND hwnd, 		
    int iFirst, 		
    int iLast		
);		

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

hwnd
Handle to the list view control.
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.

ListView_Scroll

BOOL ListView_Scroll(
    HWND hwnd, 		
    int dx, 		
    int dy		
);		

Scrolls the content of a list view control. You can use this macro or send the LVM_SCROLL message explicitly.

hwnd
Handle to the list view control.
dx
Integer value that specifies the amount of horizontal scrolling in pixels. If the list view control is in list view, this value specifies the number of columns to scroll.
dy
Integer value that specifies the amount of vertical scrolling in pixels.

When the list view control is in report view, the control can only be scrolled vertically in whole line increments. Therefore, the dy parameter will be rounded to the nearest number of pixels that form a whole line increment. For example, if the height of a line is 16 pixels and 8 is passed for dy, the list will be scrolled by 16 pixels (1 line). If 7 is passed for dy, the list will be scrolled 0 pixels (0 lines).

ListView_SetBkColor

BOOL ListView_SetBkColor(
    HWND hwnd, 		
    COLORREF clrBk		
);		

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

hwnd
Handle to the list view control.
clrBk
Background color to set or the CLR_NONE value for no background color. List view controls with background colors redraw themselves significantly faster than those without background colors.

ListView_SetBkImage

BOOL ListView_SetBkImage(
    HWND hwndLV,
    LPLVBKIMAGE plvbki;
);

Sets the background image in a list view control. You can use this macro or send the LVM_SETBKIMAGE message explicitly.

hwndLV
Handle to the list view control.
plvbki
Address of an LVBKIMAGE structure that contains the new background image information.

Because the list view control uses OLE COM to manipulate the background images, the calling application must call CoInitialize or OleInitialize before using this macro. It is best to call one of these functions when the application is initialized, and call either CoUnitialize or OleUnitialize when the application is terminating.

Version 4.71

See also ListView_GetBkImage

ListView_SetCallbackMask

BOOL ListView_SetCallbackMask(
    WND hwnd, 		
    UINT mask		
);		

Changes the callback mask for a list view control. You can use this macro or send the LVM_SETCALLBACKMASK message explicitly.

hwnd
Handle to the list view control.
mask
Specifies the value of the callback mask. The bits of the mask indicate the item states or images for which the application stores the current state data. This value can be any combination of the following constants:
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.
LVIS_SELECTED The item is selected.
LVIS_OVERLAYMASK The application stores the image list index of the current overlay image for each item.
LVIS_STATEIMAGEMASK The application stores the image list index of the current state image for each item.

The callback mask of a list view control is a set of bit flags that specify the item states for which the application, rather than the control, stores the current data. The callback mask applies to all of the control's items, unlike the callback item designation, which applies to a specific item. The callback mask is zero by default, meaning that the list view control stores all item state information. After creating a list view control and initializing its items, you can use the ListView_SetCallbackMask macro or LVM_SETCALLBACKMASK message to change the callback mask. To get the current callback mask, send the LVM_GETCALLBACKMASK message.

For more information about overlay images and state images, see List View Image Lists.

For more information on list view callbacks, see Callback Items and the Callback Mask

See also LVN_GETDISPINFO

ListView_SetColumn

BOOL ListView_SetColumn(
    HWND hwnd, 		
    int iCol, 		
    LPLVCOLUMN pcol		
);		

Sets the attributes of a list view column. You can use this macro or send the LVM_SETCOLUMN message explicitly.

hwnd
Handle to the list view control.
iCol
Index of the column.
pcol
Address of an LVCOLUMN structure that contains the new column attributes. The mask member specifies which column attributes to set.
If the mask member specifies the LVCF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

ListView_SetColumnOrderArray

BOOL ListView_SetColumnOrderArray(
    HWND hwndLV,
    int iCount,
    int *lpiArray
);

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

hwndLV
Handle to a list view control.
iCount
Number of columns in the list view control.
lpiArray
Address of an array specifying the order in which columns should be displayed, from left to right. For example, if the contents of the array are {2,0,1}, the control displays column 2, column 0, and column 1, from left to right.

Version 4.70

ListView_SetColumnWidth

BOOL ListView_SetColumnWidth(
    HWND hwnd, 		
    int iCol, 		
    int cx		
);		

Changes the width of a column in report or list view. You can use this macro or send the LVM_SETCOLUMNWIDTH message explicitly.

hwnd
Handle to the list view control.
iCol
Index of the column. In list view, the iCol parameter must be -1.
cx
New width of the column, in list view coordinates, or one of the following values:
LVSCW_AUTOSIZE Automatically sizes the column.
LVSCW_AUTOSIZE_USEHEADER Automatically sizes the column to fit the header text.

Note that ListView_SetColumnWidth converts the cx parameter to a 16-bit value.

ListView_SetExtendedListViewStyle

void ListView_SetExtendedListViewStyle(
    HWND hwndLV,
    DWORD dwExStyle
);

Sets extended styles for list view controls. You can use this macro or send the LVM_SETEXTENDEDLISTVIEWSTYLE message explicitly.

hwndLV
Handle to the list view control that will receive the style change.
dwExStyle
Value specifying the extended list view control style. This parameter can be a combination of extended styles.

For backward compatibility reasons, the ListView_SetExtendedListViewStyle macro has not been updated to use dwExMask. To use the dwExMask value, use the ListView_SetExtendedListViewStyleEx macro.

Version 4.70

ListView_SetExtendedListViewStyleEx

void ListView_SetExtendedListViewStyleEx(
    HWND hwndLV,
    DWORD dwExMask,
    DWORD dwExStyle
);

Sets extended styles for list view controls using the style mask. You can use this macro or send the LVM_SETEXTENDEDLISTVIEWSTYLE message explicitly.

hwndLV
Handle to the list view control that will receive the style change.
dwExMask
DWORD value that indicates which styles in dwExStyle are to be affected. This parameter can be a combination of extended styles. Only the extended styles in dwExMask will be changed. All other styles will be maintained as they are. If this parameter is zero, then all of the styles in dwExStyle will be affected.
dwExStyle
Value specifying the extended list view control style. This parameter can be a combination of extended styles.

Version 4.71

ListView_SetHotCursor

HCURSOR ListView_SetHotCursor(
    HWND    hwndLV,
    HCURSOR hCursor
);

Sets the HCURSOR that the list view control uses when the pointer is over an item while hot tracking is enabled. You can use this macro or send the LVM_SETHOTCURSOR message explicitly.

hwndLV
Handle to a list view control.
hCursor
Handle to the cursor to be set.

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

Version 4.70

ListView_SetHotItem

INT ListView_SetHotItem(
    HWND hwndLV,
    INT  iIndex
);

Sets the hot item in a list view control. You can use this macro or send the LVM_SETHOTITEM message explicitly.

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

Version 4.70

ListView_SetHoverTime

ListView_SetHoverTime(
    HWND hwndLV, 
    DWORD dwHoverTime
);

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

hwndLV
Handle to a list view control.
dwHoverTime
The new amount of time, in milliseconds, that the mouse cursor must hover over an item before it is selected. If this value is (DWORD)-1, then the hover time is set to the default hover time.

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

ListView_SetIconSpacing

DWORD ListView_SetIconSpacing(
    HWND hwndLV,
    int cx,
    int cy
);

Sets the spacing between icons in list view controls set to the LVS_ICON style. You can use this macro or send the LVM_SETICONSPACING message explicitly.

hwndLV
Handle to a list view control.
cx
Distance, in pixels, to set between icons on the x-axis.
cy
Distance, in pixels, to set between icons on the y-axis.

The cx and cy parameters are relative to the upper-left corner of an icon bitmap. Therefore, to set spacing between icons that do not overlap, the cx or cy values must include the size of the icon, plus the amount of empty space desired between icons. Values that do not include the width of the icon will result in overlaps.

Version 4.70

ListView_SetImageList

HIMAGELIST ListView_SetImageList(
    HWND hwnd, 		
    HIMAGELIST himl, 		
    int iImageList		
);		

Assigns an image list to a list view control. You can use this macro or send the LVM_SETIMAGELIST message explicitly.

hwnd
Handle to the list view control.
himl
Handle to the image list to assign.
iImageList
Type of image list. 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.

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