`CListCtrl` Class

Article
06/30/2022

Encapsulates the functionality of a "list view control," which displays a collection of items each consisting of an icon (from an image list) and a label.

Syntax

class CListCtrl : public CWnd

Members

Public Constructors

Name	Description
`CListCtrl::CListCtrl`	Constructs a `CListCtrl` object.

Public Methods

Name	Description
`CListCtrl::ApproximateViewRect`	Determines the width and height required to display the items of a list view control.
`CListCtrl::Arrange`	Aligns items on a grid.
`CListCtrl::CancelEditLabel`	Cancels item text editing operation.
`CListCtrl::Create`	Creates a list control and attaches it to a `CListCtrl` object.
`CListCtrl::CreateDragImage`	Creates a drag image list for a specified item.
`CListCtrl::CreateEx`	Creates a list control with the specified Windows extended styles and attaches it to a `CListCtrl` object.
`CListCtrl::DeleteAllItems`	Deletes all items from the control.
`CListCtrl::DeleteColumn`	Deletes a column from the list view control.
`CListCtrl::DeleteItem`	Deletes an item from the control.
`CListCtrl::DrawItem`	Called when a visual aspect of an owner-draw control changes.
`CListCtrl::EditLabel`	Begins in-place editing of an item's text.
`CListCtrl::EnableGroupView`	Enables or disables whether the items in a list view control display as a group.
`CListCtrl::EnsureVisible`	Ensures that an item is visible.
`CListCtrl::FindItem`	Searches for a list view item having specified characteristics.
`CListCtrl::GetBkColor`	Retrieves the background color of a list view control.
`CListCtrl::GetBkImage`	Retrieves the current background image of a list view control.
`CListCtrl::GetCallbackMask`	Retrieves the callback mask for a list view control.
`CListCtrl::GetCheck`	Retrieves the current display status of the state image associated with an item.
`CListCtrl::GetColumn`	Retrieves the attributes of a control's column.
`CListCtrl::GetColumnOrderArray`	Retrieves the column order (left to right) of a list view control.
`CListCtrl::GetColumnWidth`	Retrieves the width of a column in report view or list view.
`CListCtrl::GetCountPerPage`	Calculates the number of items that can fit vertically in a list view control.
`CListCtrl::GetEditControl`	Retrieves the handle of the edit control used to edit an item's text.
`CListCtrl::GetEmptyText`	Retrieves the string to display if the current list-view control is empty.
`CListCtrl::GetExtendedStyle`	Retrieves the current extended styles of a list view control.
`CListCtrl::GetFirstSelectedItemPosition`	Retrieves the position of the first selected list view item in a list view control.
`CListCtrl::GetFocusedGroup`	Retrieves the group that has the keyboard focus in the current list-view control.
`CListCtrl::GetGroupCount`	Retrieves the number of groups in the current list-view control.
`CListCtrl::GetGroupInfo`	Gets the information for a specified group of the list view control.
`CListCtrl::GetGroupInfoByIndex`	Retrieves information about a specified group in the current list-view control.
`CListCtrl::GetGroupMetrics`	Retrieves the metrics of a group.
`CListCtrl::GetGroupRect`	Retrieves the bounding rectangle for a specified group in the current list-view control.
`CListCtrl::GetGroupState`	Retrieves the state for a specified group in the current list-view control.
`CListCtrl::GetHeaderCtrl`	Retrieves the header control of a list view control.
`CListCtrl::GetHotCursor`	Retrieves the cursor used when hot tracking is enabled for a list view control.
`CListCtrl::GetHotItem`	Retrieves the list view item currently under the cursor.
`CListCtrl::GetHoverTime`	Retrieves the current hover time of a list view control.
`CListCtrl::GetImageList`	Retrieves the handle of an image list used for drawing list view items.
`CListCtrl::GetInsertMark`	Retrieves the current position of the insertion mark.
`CListCtrl::GetInsertMarkColor`	Retrieves the current color of the insertion mark.
`CListCtrl::GetInsertMarkRect`	Retrieves the rectangle that bounds the insertion point.
`CListCtrl::GetItem`	Retrieves a list view item's attributes.
`CListCtrl::GetItemCount`	Retrieves the number of items in a list view control.
`CListCtrl::GetItemData`	Retrieves the application-specific value associated with an item.
`CListCtrl::GetItemIndexRect`	Retrieves the bounding rectangle for all or part of a subitem in the current list-view control.
`CListCtrl::GetItemPosition`	Retrieves the position of a list view item.
`CListCtrl::GetItemRect`	Retrieves the bounding rectangle for an item.
`CListCtrl::GetItemSpacing`	Calculates the spacing between items in the current list-view control.
`CListCtrl::GetItemState`	Retrieves the state of a list view item.
`CListCtrl::GetItemText`	Retrieves the text of a list view item or subitem.
`CListCtrl::GetNextItem`	Searches for a list view item with specified properties and with specified relationship to a given item.
`CListCtrl::GetNextItemIndex`	Retrieves the index of the item in the current list-view control that has a specified set of properties.
`CListCtrl::GetNextSelectedItem`	Retrieves the index of a list view item position, and the position of the next selected list view item for iterating.
`CListCtrl::GetNumberOfWorkAreas`	Retrieves the current number of working areas for a list view control.
`CListCtrl::GetOrigin`	Retrieves the current view origin for a list view control.
`CListCtrl::GetOutlineColor`	Retrieves the color of the border of a list view control.
`CListCtrl::GetSelectedColumn`	Retrieves the index of the currently selected column in the list control.
`CListCtrl::GetSelectedCount`	Retrieves the number of selected items in the list view control.
`CListCtrl::GetSelectionMark`	Retrieves the selection mark of a list view control.
`CListCtrl::GetStringWidth`	Determines the minimum column width necessary to display all of a given string.
`CListCtrl::GetSubItemRect`	Retrieves the bounding rectangle of an item in a list view control.
`CListCtrl::GetTextBkColor`	Retrieves the text background color of a list view control.
`CListCtrl::GetTextColor`	Retrieves the text color of a list view control.
`CListCtrl::GetTileInfo`	Retrieves information about a tile in a list view control.
`CListCtrl::GetTileViewInfo`	Retrieves information about a list view control in tile view.
`CListCtrl::GetToolTips`	Retrieves the tooltip control that the list view control uses to display tooltips.
`CListCtrl::GetTopIndex`	Retrieves the index of the topmost visible item.
`CListCtrl::GetView`	Gets the view of the list view control.
`CListCtrl::GetViewRect`	Retrieves the bounding rectangle of all items in the list view control.
`CListCtrl::GetWorkAreas`	Retrieves the current working areas of a list view control.
`CListCtrl::HasGroup`	Determines if the list view control has the specified group.
`CListCtrl::HitTest`	Determines which list view item is at a specified position.
`CListCtrl::InsertColumn`	Inserts a new column in a list view control.
`CListCtrl::InsertGroup`	Inserts a group into the list view control.
`CListCtrl::InsertGroupSorted`	Inserts the specified group into an ordered list of groups.
`CListCtrl::InsertItem`	Inserts a new item in a list view control.
`CListCtrl::InsertMarkHitTest`	Retrieves the insertion point closest to a specified point.
`CListCtrl::IsGroupViewEnabled`	Determines whether group view is enabled for a list view control.
`CListCtrl::IsItemVisible`	Indicates whether a specified item in the current list-view control is visible.
`CListCtrl::MapIDToIndex`	Maps the unique ID of an item in the current list-view control to an index.
`CListCtrl::MapIndexToID`	Maps the index of an item in the current list-view control to a unique ID.
`CListCtrl::MoveGroup`	Moves the specified group.
`CListCtrl::MoveItemToGroup`	Moves the specified group to the specified zero based index of the list view control.
`CListCtrl::RedrawItems`	Forces a list view control to repaint a range of items.
`CListCtrl::RemoveAllGroups`	Removes all groups from a list view control.
`CListCtrl::RemoveGroup`	Removes the specified group from the list view control.
`CListCtrl::Scroll`	Scrolls the content of a list view control.
`CListCtrl::SetBkColor`	Sets the background color of the list view control.
`CListCtrl::SetBkImage`	Sets the current background image of a list view control.
`CListCtrl::SetCallbackMask`	Sets the callback mask for a list view control.
`CListCtrl::SetCheck`	Sets the current display status of the state image associated with an item.
`CListCtrl::SetColumn`	Sets the attributes of a list view column.
`CListCtrl::SetColumnOrderArray`	Sets the column order (left to right) of a list view control.
`CListCtrl::SetColumnWidth`	Changes the width of a column in report view or list view.
`CListCtrl::SetExtendedStyle`	Sets the current extended styles of a list view control.
`CListCtrl::SetGroupInfo`	Sets the information for the specified group of a list view control.
`CListCtrl::SetGroupMetrics`	Sets the group metrics of a list view control.
`CListCtrl::SetHotCursor`	Sets the cursor used when hot tracking is enabled for a list view control.
`CListCtrl::SetHotItem`	Sets the current hot item of a list view control.
`CListCtrl::SetHoverTime`	Sets the current hover time of a list view control.
`CListCtrl::SetIconSpacing`	Sets the spacing between icons in a list view control.
`CListCtrl::SetImageList`	Assigns an image list to a list view control.
`CListCtrl::SetInfoTip`	Sets the tooltip text.
`CListCtrl::SetInsertMark`	Sets the insertion point to the defined position.
`CListCtrl::SetInsertMarkColor`	Sets the color of the insertion point.
`CListCtrl::SetItem`	Sets some or all of a list view item's attributes.
`CListCtrl::SetItemCount`	Prepares a list view control for adding a large number of items.
`CListCtrl::SetItemCountEx`	Sets the item count for a virtual list view control.
`CListCtrl::SetItemData`	Sets the item's application-specific value.
`CListCtrl::SetItemIndexState`	Sets the state of an item in the current list-view control.
`CListCtrl::SetItemPosition`	Moves an item to a specified position in a list view control.
`CListCtrl::SetItemState`	Changes the state of an item in a list view control.
`CListCtrl::SetItemText`	Changes the text of a list view item or subitem.
`CListCtrl::SetOutlineColor`	Sets the color of the border of a list view control.
`CListCtrl::SetSelectedColumn`	Sets the selected column of the list view control.
`CListCtrl::SetSelectionMark`	Sets the selection mark of a list view control.
`CListCtrl::SetTextBkColor`	Sets the background color of text in a list view control.
`CListCtrl::SetTextColor`	Sets the text color of a list view control.
`CListCtrl::SetTileInfo`	Sets the information for a tile of the list view control.
`CListCtrl::SetTileViewInfo`	Sets information that a list view control uses in tile view.
`CListCtrl::SetToolTips`	Sets the tooltip control that the list view control will use to display tooltips.
`CListCtrl::SetView`	Sets the view of the list view control.
`CListCtrl::SetWorkAreas`	Sets the area where icons can be displayed in a list view control.
`CListCtrl::SortGroups`	Sorts the groups of a list view control with a user-defined function.
`CListCtrl::SortItems`	Sorts list view items using an application-defined comparison function.
`CListCtrl::SortItemsEx`	Sorts list view items using an application-defined comparison function.
`CListCtrl::SubItemHitTest`	Determines which list view item, if any, is at a given position.
`CListCtrl::Update`	Forces the control to repaint a specified item.

Remarks

In addition to an icon and label, each item can have information displayed in columns to the right of the icon and label. This control (and therefore the CListCtrl class) is available only to programs running under Windows 95/98 and Windows NT version 3.51 and later.

The following is a brief overview of the CListCtrl class. For a detailed, conceptual discussion, see Using CListCtrl and Controls.

Views

List view controls can display their contents in four different ways, called "views."

Icon view

Each item appears as a full-sized icon (32 x 32 pixels) with a label below it. The user can drag the items to any location in the list view window.
Small icon view

Each item appears as a small icon (16 x 16 pixels) with the label to the right of it. The user can drag the items to any location in the list view window.
List view

Each item appears as a small icon with a label to the right of it. Items are arranged in columns and cannot be dragged to any location in the list view window.
Report view

Each item appears on its own line, with additional information arranged in columns to the right. The leftmost column contains the small icon and label, and subsequent columns contain subitems as specified by the application. An embedded header control (class CHeaderCtrl) implements these columns. For more information on the header control and columns in a report view, see Using CListCtrl: Adding Columns to the Control (Report View).

The style of the control's current list view determines the current view. For more information on these styles and their usage, see Using CListCtrl: Changing List Control Styles.

Extended Styles

In addition to the standard list styles, class CListCtrl supports a large set of extended styles, providing enriched functionality. Some examples of this functionality include:

Hover selection

When enabled, allows automatic selection of an item when the cursor remains over the item for a certain period of time.
Virtual list views

When enabled, allows the control to support up to DWORD items. This is possible by placing the overhead of managing item data on the application. Except for the item selection and focus information, all item information must be managed by the application. For more information, see Using CListCtrl: Virtual List Controls.
One- and two- click activation

When enabled, allows hot tracking (automatic highlighting of the item text) and one- or two- click activation of the highlighted item.
Drag and drop column ordering

When enabled, allows drag-and-drop reordering of columns in a list view control. Only available in report view.

For information on using these new extended styles, see Using CListCtrl: Changing List Control Styles.

Items and Subitems

Each item in a list view control consists of an icon (from an image list), a label, a current state, and an application-defined value (referred to as "item data"). One or more subitems can also be associated with each item. A "subitem" is a string that, in report view, can be displayed in a column to the right of an item's icon and label. All items in a list view control must have the same number of subitems.

Class CListCtrl provides several functions for inserting, deleting, finding, and modifying these items. For more information, see CListCtrl::GetItem, CListCtrl::InsertItem, and CListCtrl::FindItem, Adding Items to the Control, and Scrolling, Arranging, Sorting, and Finding in list controls.

By default, the list view control is responsible for storing an item's icon and text attributes. However, in addition to these item types, class CListCtrl supports "callback items." A "callback item" is a list view item for which the application—rather than the control—stores the text, icon, or both. A callback mask is used to specify which item attributes (text and/or icon) are supplied by the application. If an application uses callback items, it must be able to supply the text and/or icon attributes on demand. Callback items are helpful when your application already maintains some of this information. For more information, see Using CListCtrl: Callback Items and the Callback Mask.

Image Lists

The icons, header item images, and application- defined states for list view items are contained in several image lists (implemented by class CImageList), which you create and assign to the list view control. Each list view control can have up to four different types of image lists:

Large icon

Used in the icon view for full-sized icons.
Small icon

Used in the small icon, list, and report views for smaller versions of the icons used in the icon view.
Application-defined state

Contains state images, which are displayed next to an item's icon to indicate an application-defined state.
Header item

Used in the report view for small images that appear in each header control item.

By default, a list view control destroys the image lists assigned to it when it's destroyed; however, the developer can customize this behavior by destroying each image list when it's no longer used, as determined by the application. For more information, see Using CListCtrl: List Items and Image Lists.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CListCtrl

Requirements

Header: afxcmn.h

`CListCtrl::ApproximateViewRect`

Determines the width and height required to display the items of a list view control.

CSize ApproximateViewRect(
    CSize sz = CSize(-1, -1),
    int iCount = -1) const;

Parameters

sz
The proposed dimensions of the control, in pixels. If dimensions aren't specified, the framework uses the current width or height values of the control.

iCount
Number of items to be displayed in the control. Pass -1 to use the total number of items currently in the control.

Return Value

A CSize object that contains the approximate width and height needed to display the items, in pixels.

Remarks

This member function implements the behavior of the Win32 macro, ListView_ApproximateViewRect, as described in the Windows SDK.

`CListCtrl::Arrange`

Repositions items in an icon view so that they align on a grid.

BOOL Arrange(UINT nCode);

Parameters

nCode
Specifies the alignment style for the items. It 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's current alignment styles (the default value).
LVA_SNAPTOGRID Snaps all icons to the nearest grid position.

Return Value

Nonzero if successful; otherwise zero.

Remarks

The nCode parameter specifies the alignment style.

Example

// Align all of the list view control items along the top
// of the window (the list view control must be in icon or
// small icon mode).
m_myListCtrl.Arrange(LVA_ALIGNTOP);

`CListCtrl::CancelEditLabel`

Cancels item text editing operation.

void CancelEditLabel();

Remarks

This member function emulates the functionality of the LVM_CANCELEDITLABEL message, as described in the Windows SDK.

`CListCtrl::CListCtrl`

Constructs a CListCtrl object.

CListCtrl();

`CListCtrl::Create`

Creates a list control and attaches it to a CListCtrl object.

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parameters

dwStyle
Specifies the list control's style. Apply any combination of list control styles to the control. See List view window styles in the Windows SDK for a complete list of these styles. Set extended styles specific to a control using SetExtendedStyle.

rect
Specifies the list control's size and position. It can be either a CRect object or a RECT structure.

pParentWnd
Specifies the list control's parent window, usually a CDialog. It must not be NULL.

nID
Specifies the list control's ID.

Return Value

Nonzero if successful; otherwise zero.

Remarks

You construct a CListCtrl in two steps. First, call the constructor and then call Create, which creates the list view control and attaches it to the CListCtrl object.

To apply extended Windows styles to the list control object, call CreateEx instead of Create.

Example

m_myListCtrl.Create(
    WS_CHILD|WS_VISIBLE|WS_BORDER|LVS_REPORT|LVS_EDITLABELS,
    CRect(10,10,400,200), pParentWnd, IDD_MYLISTCTRL);

`CListCtrl::CreateEx`

Creates a control (a child window) and associates it with the CListCtrl object.

virtual BOOL CreateEx(
    DWORD dwExStyle,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parameters

dwExStyle
Specifies the extended style of the control being created. For a list of extended Windows styles, see the dwExStyle parameter for CreateWindowEx in the Windows SDK.

dwStyle
Specifies the list control's style. Apply any combination of list control styles to the control. For a complete list of these styles, see List view window styles in the Windows SDK.

rect
A reference to a RECT structure describing the size and position of the window to be created, in client coordinates of pParentWnd.

pParentWnd
A pointer to the window that is the control's parent.

nID
The control's child-window ID.

Return Value

Nonzero if successful; otherwise 0.

Remarks

Use CreateEx instead of Create to apply extended Windows styles, specified by the Windows extended style preface WS_EX_.

CreateEx creates the control with the extended Windows styles specified by dwExStyle. To set extended styles specific to a control, call SetExtendedStyle. For example, use CreateEx to set such styles as WS_EX_CONTEXTHELP, but use SetExtendedStyle to set such styles as LVS_EX_FULLROWSELECT. For more information, see the styles described in the article Extended List View Styles in the Windows SDK.

`CListCtrl::CreateDragImage`

Creates a drag image list for the item specified by nItem.

CImageList* CreateDragImage(
    int nItem,
    LPPOINT lpPoint);

Parameters

*nItem*
Index of the item whose drag image list is to be created.

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

Return Value

A pointer to the drag image list if successful; otherwise NULL.

Remarks

The CImageList object is permanent, and you must delete it when finished. For example:

CImageList* pImageList = m_myListCtrl.CreateDragImage(nItem, &point);

// do something

delete pImageList;

`CListCtrl::DeleteAllItems`

Deletes all items from the list view control.

BOOL DeleteAllItems();

Return Value

Nonzero if successful; otherwise zero.

Example

// Delete all of the items from the list view control.
m_myListCtrl.DeleteAllItems();
ASSERT(m_myListCtrl.GetItemCount() == 0);

`CListCtrl::DeleteColumn`

Deletes a column from the list view control.

BOOL DeleteColumn(int nCol);

Parameters

nCol
Index of the column to be deleted.

Return Value

Nonzero if successful; otherwise zero.

Example

int nColumnCount = m_myListCtrl.GetHeaderCtrl()->GetItemCount();

// Delete all of the columns.
for (int i=0; i < nColumnCount; i++)
{
    m_myListCtrl.DeleteColumn(0);
}

`CListCtrl::DeleteItem`

Deletes an item from a list view control.

BOOL DeleteItem(int nItem);

Parameters

nItem
Specifies the index of the item to be deleted.

Return Value

Nonzero if successful; otherwise zero.

Example

int nCount = m_myListCtrl.GetItemCount();

// Delete all of the items from the list view control.
for (int i=0; i < nCount; i++)
{
    m_myListCtrl.DeleteItem(0);
}

`CListCtrl::DrawItem`

Called by the framework when a visual aspect of an owner-draw list view control changes.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parameters

lpDrawItemStruct
A long pointer to a DRAWITEMSTRUCT structure that contains information about the type of drawing required.

Remarks

The itemAction member of the DRAWITEMSTRUCT structure defines the drawing action that is to be performed.

By default, this member function does nothing. Override this member function to implement drawing for an owner-draw CListCtrl object.

The application should restore all graphics device interface (GDI) objects selected for the display context supplied in lpDrawItemStruct before this member function terminates.

`CListCtrl::EditLabel`

Begins in-place editing of an item's text.

CEdit* EditLabel(int nItem);

Parameters

nItem
Index of the list view item that is to be edited.

Return Value

If successful, a pointer to the CEdit object that is used to edit the item text; otherwise NULL.

Remarks

A list view control that has the LVS_EDITLABELS window style enables a user to edit item labels in place. The user begins editing by clicking the label of an item that has the focus.

Use this function to begin in-place editing of the specified list view item's text.

Example

// Make sure the focus is set to the list view control.
m_myListCtrl.SetFocus();

// Show the edit control on the label of the first
// item in the list view control.
CEdit* pmyEdit = m_myListCtrl.EditLabel(1);
ASSERT(pmyEdit != NULL);

`CListCtrl::EnableGroupView`

Enables or disables whether the items in a list view control display as a group.

LRESULT EnableGroupView(BOOL fEnable);

Parameters

fEnable
Indicates whether to enable a listview control to group displayed items. TRUE to enable grouping; FALSE to disable it.

Return Value

Returns one of the following values:

0 The ability to display list view items as a group is already enabled or disabled.
1 The state of the control was successfully changed.
-1 The operation failed.

Remarks

This member function emulates the functionality of the LVM_ENABLEGROUPVIEW message, as described in the Windows SDK.

`CListCtrl::EnsureVisible`

Ensures that a list view item is at least partially visible.

BOOL EnsureVisible(
    int nItem,
    BOOL bPartialOK);

Parameters

nItem
Index of the list view item that is to be visible.

bPartialOK
Specifies whether partial visibility is acceptable.

Return Value

Nonzero if successful; otherwise zero.

Remarks

The list view control is scrolled if necessary. If the bPartialOK parameter is nonzero, no scrolling occurs if the item is partially visible.

Example

// Ensure that the last item is visible.
int nCount = m_myListCtrl.GetItemCount();
if (nCount > 0)
    m_myListCtrl.EnsureVisible(nCount-1, FALSE);

`CListCtrl::FindItem`

Searches for a list view item having specified characteristics.

int FindItem(
    LVFINDINFO* pFindInfo,
    int nStart = -1) const;

Parameters

pFindInfo
A pointer to an LVFINDINFO structure containing information about the item to be searched for.

nStart
Index of the item to begin the search with, or -1 to start from the beginning. The item at nStart is excluded from the search if nStart isn't equal to -1.

Return Value

The index of the item if successful or -1 otherwise.

Remarks

The pFindInfo parameter points to an LVFINDINFO structure, which contains information used to search for a list view item.

Example

LVFINDINFO info;
int nIndex;

info.flags = LVFI_PARTIAL|LVFI_STRING;
info.psz = _T("item");

// Delete all of the items that begin with the string.
while ((nIndex = m_myListCtrl.FindItem(&info)) != -1)
{
    m_myListCtrl.DeleteItem(nIndex);
}

`CListCtrl::GetBkColor`

Retrieves the background color of a list view control.

COLORREF GetBkColor() const;

Return Value

A 32-bit value used to specify an RGB color.

Example

See the example for CListCtrl::SetBkColor.

`CListCtrl::GetBkImage`

Retrieves the current background image of a list view control.

BOOL GetBkImage(LVBKIMAGE* plvbkImage) const;

Parameters

plvbkImage
A pointer to an LVBKIMAGE structure containing the current background image of the list view.

Return Value

Returns nonzero if successful, or zero otherwise.

Remarks

This method implements the behavior of the Win32 macro, ListView_GetBkImage, as described in the Windows SDK.

Example

LVBKIMAGE bki;

// If no background image is set for the list view control use
// the Microsoft homepage image as the background image.
if (m_myListCtrl.GetBkImage(&bki) && (bki.ulFlags == LVBKIF_SOURCE_NONE))
{
    m_myListCtrl.SetBkImage(
        _T("https://www.microsoft.com/library/images/gifs/homepage/microsoft.gif"),
        TRUE);
}

`CListCtrl::GetCallbackMask`

Retrieves the callback mask for a list view control.

UINT GetCallbackMask() const;

Return Value

The list view control's callback mask.

Remarks

A "callback item" is a list view item for which the application—rather than the control—stores the text, icon, or both. Although a list view control can store these attributes for you, you may want to use callback items if your application already maintains some of this information. The callback mask specifies which item state bits are maintained by the application, and it applies to the whole control rather than to a specific item. The callback mask is zero by default, meaning that the control tracks all item states. If an application uses callback items or specifies a nonzero callback mask, it must be able to supply list view item attributes on demand.

Example

See the example for CListCtrl::SetCallbackMask.

`CListCtrl::GetCheck`

Retrieves the current display status of the state image that is associated with an item.

BOOL GetCheck(int nItem) const;

Parameters

nItem
The zero-based index of a list control item.

Return Value

Nonzero if the item is selected, otherwise 0.

Remarks

This member function implements the behavior of the Win32 macro, ListView_GetCheckState, as described in the Windows SDK.

Example

See the example for CListCtrl::SetCheck.

`CListCtrl::GetColumn`

Retrieves the attributes of a list view control's column.

BOOL GetColumn(
    int nCol,
    LVCOLUMN* pColumn) const;

Parameters

nCol
Index of the column whose attributes are to be retrieved.

pColumn
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.

Return Value

Nonzero if successful; otherwise zero.

Remarks

The LVCOLUMN structure contains information about a column in report view.

Example

LVCOLUMN col;

col.mask = LVCF_WIDTH;

// Double the column width of the first column.
if (m_myListCtrl.GetColumn(0, &col))
{
    col.cx *= 2;
    m_myListCtrl.SetColumn(0, &col);
}

`CListCtrl::GetColumnOrderArray`

Retrieves the column order (left to right) of a list view control.

BOOL GetColumnOrderArray(
    LPINT piArray,
    int iCount = -1);

Parameters

piArray
A pointer to a buffer that will contain the index values of the columns in the list view control. The buffer must be large enough to contain the total number of columns in the list view control.

iCount
Number of columns in the list view control. If this parameter is -1, the number of columns is automatically retrieved by the framework.

Return Value

Nonzero if successful; otherwise zero.

Remarks

This member function implements the behavior of the Win32 macro, ListView_GetColumnOrderArray, as described in the Windows SDK.

Example

// Reverse the order of the columns in the list view control
// (i.e. make the first column the last, the last column
// the first, and so on...).
CHeaderCtrl* pHeaderCtrl = m_myListCtrl.GetHeaderCtrl();

if (pHeaderCtrl != NULL)
{
    int  nColumnCount = pHeaderCtrl->GetItemCount();
    LPINT pnOrder = (LPINT) malloc(nColumnCount*sizeof(int));
    ASSERT(pnOrder != NULL);
    m_myListCtrl.GetColumnOrderArray(pnOrder, nColumnCount);

    int i, j, nTemp;
    for (i = 0, j = nColumnCount-1; i < j; i++, j--)
    {
        nTemp = pnOrder[i];
        pnOrder[i] = pnOrder[j];
        pnOrder[j] = nTemp;
    }

    m_myListCtrl.SetColumnOrderArray(nColumnCount, pnOrder);
    free(pnOrder);
}

`CListCtrl::GetColumnWidth`

Retrieves the width of a column in report view or list view.

int GetColumnWidth(int nCol) const;

Parameters

nCol
Specifies the index of the column whose width is to be retrieved.

Return Value

The width, in pixels, of the column specified by nCol.

Example

// Increase the column width of the second column by 20.
int nWidth = m_myListCtrl.GetColumnWidth(1);
m_myListCtrl.SetColumnWidth(1, 20 + nWidth);

`CListCtrl::GetCountPerPage`

Calculates the number of items that can fit vertically in the visible area of a list view control when in list view or report view.

int GetCountPerPage() const;

Return Value

The number of items that can fit vertically in the visible area of a list view control when in list view or report view.

Example

See the example for CListCtrl::GetTopIndex.

`CListCtrl::GetEditControl`

Retrieves the handle of the edit control used to edit a list view item's text.

CEdit* GetEditControl() const;

Return Value

If successful, a pointer to the CEdit object that is used to edit the item text; otherwise NULL.

Example

// The string replacing the text in the edit control.
LPCTSTR lpszmyString = _T("custom label!");

// If possible, replace the text in the label edit control.
CEdit* pEdit = m_myListCtrl.GetEditControl();

if (pEdit != NULL)
{
    pEdit->SetWindowText(lpszmyString);
}

`CListCtrl::GetEmptyText`

Retrieves the string to display if the current list-view control is empty.

CString GetEmptyText() const;

Return Value

A CString that contains the text to display if the control is empty.

Remarks

This method sends the LVM_GETEMPTYTEXT message, which is described in the Windows SDK.

`CListCtrl::GetExtendedStyle`

Retrieves the current extended styles of a list view control.

DWORD GetExtendedStyle();

Return Value

A combination of the extended styles currently in use by the list view control. For a descriptive list of these extended styles, see the Extended List View Styles article in the Windows SDK.

Remarks

This member function implements the behavior of the Win32 macro, ListView_GetExtendedListViewStyle, as described in the Windows SDK.

Example

See the example for CListCtrl::SetExtendedStyle.

`CListCtrl::GetFirstSelectedItemPosition`

Gets the position of the first selected item in the list view control.

POSITION GetFirstSelectedItemPosition() const;

Return Value

A POSITION value that can be used for iteration or object pointer retrieval; NULL if no items are selected.

Example

The following code sample demonstrates the usage of this function.

POSITION pos = m_myListCtrl.GetFirstSelectedItemPosition();
if (pos == NULL)
{
    TRACE(_T("No items were selected!\n"));
}
else
{
    while (pos)
    {
        int nItem = m_myListCtrl.GetNextSelectedItem(pos);
        TRACE(_T("Item %d was selected!\n"), nItem);
        // you could do your own processing on nItem here
    }
}

`CListCtrl::GetFocusedGroup`

Retrieves the group that has the keyboard focus in the current list-view control.

int GetFocusedGroup() const;

Return Value

The index of the group whose state is LVGS_FOCUSED, if there's such a group; otherwise, -1.

Remarks

This method sends the LVM_GETFOCUSEDGROUP message, which is described in the Windows SDK. For more information, see the LVGS_FOCUSED value of the state member of the LVGROUP structure.

`CListCtrl::GetGroupCount`

Retrieves the number of groups in the current list-view control.

int GetGroupCount()const;

Return Value

The number of groups in the list-view control.

Remarks

This method sends the LVM_GETGROUPCOUNT message, which is described in the Windows SDK -->.

`CListCtrl::GetGroupInfo`

Gets the information for a specified group of the list view control.

int GetGroupInfo(
    int iGroupId,
    PLVGROUP pgrp) const;

Parameters

iGroupId
The identifier of the group whose information is to be retrieved.

pgrp
A pointer to the LVGROUP containing information on the group specified.

Return Value

Returns the ID of the group if successful, or -1 otherwise.

Remarks

This member function emulates the functionality of the LVM_GETGROUPINFO message, as described in the Windows SDK.

`CListCtrl::GetGroupInfoByIndex`

Retrieves information about a specified group in the current list-view control.

BOOL GetGroupInfoByIndex(
    int iIndex,
    PLVGROUP pGroup) const;

Parameters

iIndex
[in] Zero-based index of a group.

pGroup
[out] Pointer to an LVGROUP structure that receives information about the group specified by the iIndex parameter. The caller is responsible for initializing the members of the LVGROUP structure. Set the cbSize member to the size of the structure, and the flags of the mask member to specify the information to retrieve.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method sends the LVM_GETGROUPINFOBYINDEX message, which is described in the Windows SDK -->.

Example

The first code example defines a variable, m_listCtrl, that is used to access the current list-view control. This variable is used in the next example.

public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;

The next code example demonstrates the GetGroupInfoByIndex method. In an earlier section of this code example, we created a list-view control that displays two columns titled "ClientID" and "Grade" in a report view. The following code example retrieves information about the group whose index is 0, if such a group exists.

// GetGroupInfoByIndex
const int GROUP_HEADER_BUFFER_SIZE = 40;

// Initialize the structure
LVGROUP gInfo = {0};
gInfo.cbSize = sizeof(LVGROUP);
wchar_t wstrHeadGet[GROUP_HEADER_BUFFER_SIZE] = {0};
gInfo.cchHeader = GROUP_HEADER_BUFFER_SIZE;
gInfo.pszHeader = wstrHeadGet;
gInfo.mask = (LVGF_ALIGN | LVGF_STATE | LVGF_HEADER | LVGF_GROUPID);
gInfo.state = LVGS_NORMAL;
gInfo.uAlign  = LVGA_HEADER_LEFT;

BOOL bRet = m_listCtrl.GetGroupInfoByIndex( 0, &gInfo );
if (bRet == TRUE) {
    CString strHeader = CString( gInfo.pszHeader );
    CString str;
    str.Format(_T("Header: '%s'"), strHeader);
    AfxMessageBox(str, MB_ICONINFORMATION);
}
else
{
    AfxMessageBox(_T("No group information was retrieved."));
}

`CListCtrl::GetGroupMetrics`

Retrieves the metrics of a group.

void GetGroupMetrics(PLVGROUPMETRICS pGroupMetrics) const;

Parameters

pGroupMetrics
A pointer to a LVGROUPMETRICS containing the group metrics information.

Remarks

This member function emulates the functionality of the LVM_GETGROUPMETRICS message, as described in the Windows SDK.

`CListCtrl::GetGroupRect`

Retrieves the bounding rectangle for a specified group in the current list-view control.

BOOL GetGroupRect(
    int iGroupId,
    LPRECT lpRect,
    int iCoords = LVGGR_GROUP) const;

Parameters

iGroupId
[in] Specifies a group.

lpRect
[in, out] Pointer to a RECT structure. If this method is successful, the structure receives the rectangle coordinates of the group that is specified by iGroupId.

iCoords
[in] Specifies the rectangle coordinates to retrieve. Use one of these values:

LVGGR_GROUP - (Default) Coordinates of the entire expanded group.
LVGGR_HEADER - Coordinates of only the header (collapsed group).
LVGGR_SUBSETLINK - Coordinates of only the subset link (markup subset).

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

The caller is responsible for allocating the RECT structure pointed to by the pRect parameter.

This method sends the LVM_GETGROUPRECT message, which is described in the Windows SDK.

Example

The first code example defines a variable, m_listCtrl, that is used to access the current list-view control. This variable is used in the next example.

public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;

The next code example demonstrates the GetGroupRect method. In an earlier section of this code example, we created a list-view control that displays two columns titled "ClientID" and "Grade" in a report view. The following code example draws a 3D rectangle around the group whose index is 0, if such a group exists.

// GetGroupRect

// Get the graphics rectangle that surrounds group 0.
CRect rect;
BOOL bRet = m_listCtrl.GetGroupRect( 0, &rect, LVGGR_GROUP);
// Draw a blue rectangle around group 0.
if (bRet == TRUE) {
    m_listCtrl.GetDC()->Draw3dRect( &rect, RGB(0, 0, 255), RGB(0, 0, 255));
}
else {
    AfxMessageBox(_T("No group information was retrieved."), MB_ICONINFORMATION);
}

`CListCtrl::GetGroupState`

Retrieves the state for a specified group in the current list-view control.

UINT GetGroupState(
    int iGroupId,
    DWORD dwMask) const;

Parameters

iGroupId
[in] Zero-based index of a group.

dwMask
[in] Mask that specifies the state value to retrieve for the specified group. For more information, see the mask member of the LVGROUP structure.

Return Value

The requested state for the specified group, or 0 if the group cannot be found.

Remarks

The return value is the result of a bitwise AND operation on the dwMask parameter and the value of the state member of an LVGROUP structure that represents the current list-view control.

This method sends the LVM_GETGROUPSTATE message, which is described in the Windows SDK. For more information, see the ListView_GetGroupState macro.

`CListCtrl::GetHeaderCtrl`

Retrieves the header control of a list view control.

CHeaderCtrl* GetHeaderCtrl();

Return Value

A pointer to the header control, used by the list view control.

Remarks

This member function implements the behavior of the Win32 macro, ListView_GetHeader, as described in the Windows SDK.

Example

See the example for CListCtrl::GetColumnOrderArray.

`CListCtrl::GetHotCursor`

Retrieves the cursor used when hot tracking is enabled for a list view control.

HCURSOR GetHotCursor();

Return Value

The handle to the current hot cursor resource being used by the list view control.

Remarks

This member function implements the behavior of the Win32 macro, ListView_GetHotCursor, as described in the Windows SDK. The hot cursor, only visible when hover selection is enabled, appears when the cursor passes over any list view item. Hover selection is enabled by setting the LVS_EX_TRACKSELECT extended style.

Example

// Set the hot cursor to be the system app starting cursor.
HCURSOR hCursor = ::LoadCursor(NULL, IDC_APPSTARTING);
m_myListCtrl.SetHotCursor(hCursor);
ASSERT(m_myListCtrl.GetHotCursor() == hCursor);

`CListCtrl::GetHotItem`

Retrieves the list view item currently under the cursor.

int GetHotItem();

Return Value

The index of the current hot item of the list view control.

Remarks

This member function implements the behavior of the Win32 macro, ListView_GetHotItem, as described in the Windows SDK. The hot item is defined as the currently selected item when hot tracking (and hover selection) is enabled.

If hot tracking is enabled, when a user pauses over a list view item, the item label is automatically highlighted without the use of a mouse button.

Example

// Set the hot item to the first item only if no other item is
// highlighted.
if (m_myListCtrl.GetHotItem() == -1)
    m_myListCtrl.SetHotItem(0);

`CListCtrl::GetHoverTime`

Retrieves the current hover time of a list view control.

DWORD GetHoverTime() const;

Return Value

Returns the delay, in milliseconds, which the mouse cursor must hover over an item before it's selected. If the return value is -1, then the hover time is the default hover time.

Remarks

This member function implements the behavior of the Win32 macro, ListView_GetHoverTime, as described in the Windows SDK.

Example

// If the hover time is the default set to 1 sec.
DWORD dwTime = m_myListCtrl.GetHoverTime();
if (dwTime == -1)
    m_myListCtrl.SetHoverTime(1000);

`CListCtrl::GetImageList`

Retrieves the handle of an image list used for drawing list view items.

CImageList* GetImageList(int nImageList) const;

Parameters

nImageList
Value specifying which image list to retrieve. It can be one of these values:

LVSIL_NORMAL Image list with large icons.
LVSIL_SMALL Image list with small icons.
LVSIL_STATE Image list with state images.

Return Value

A pointer to the image list used for drawing list view items.

Example

ASSERT(m_myListCtrl.GetImageList(LVSIL_NORMAL) == NULL);
m_myListCtrl.SetImageList(&m_lcImageList, LVSIL_NORMAL);
ASSERT(m_myListCtrl.GetImageList(LVSIL_NORMAL) == &m_lcImageList);

`CListCtrl::GetInsertMark`

Retrieves the current position of the insertion mark.

BOOL GetInsertMark(LPLVINSERTMARK plvim) const;

Parameters

plvim
A pointer to an LVINSERTMARK structure containing the information for the insert mark.

Return Value

Returns TRUE if successful, or FALSE otherwise. FALSE is returned if the size in the cbSize member of the LVINSERTMARK structure doesn't equal the actual size of the structure.

Remarks

This member function emulates the functionality of the LVM_GETINSERTMARK message, as described in the Windows SDK.

`CListCtrl::GetInsertMarkColor`

Retrieves the current color of the insertion mark.

COLORREF GetInsertMarkColor() const;

Return Value

Returns a COLORREF structure that contains the color of the insertion point.

Remarks

This member function emulates the functionality of the LVM_GETINSERTMARKCOLOR message, as described in the Windows SDK.

`CListCtrl::GetInsertMarkRect`

Retrieves the rectangle that bounds the insertion point.

int GetInsertMarkRect(LPRECT pRect) const;

Parameters

pRect
Pointer to a RECT structure that contains the coordinates of a rectangle that bounds the insertion point.

Return Value

Returns one of the following values:

0 No insertion point found.
1 Insertion point found.

Remarks

This member function emulates the functionality of the LVM_GETINSERTMARKRECT message, as described in the Windows SDK.

`CListCtrl::GetItem`

Retrieves some or all of a list view item's attributes.

BOOL GetItem(LVITEM* pItem) const;

Parameters

pItem
Pointer to an LVITEM structure that receives the item's attributes.

Return Value

Nonzero if successful; otherwise zero.

Remarks

The LVITEM structure specifies or receives the attributes of a list view item.

`CListCtrl::GetItemCount`

Retrieves the number of items in a list view control.

int GetItemCount() const;

Return Value

The number of items in the list view control.

Example

See the example for CListCtrl::DeleteItem.

`CListCtrl::GetItemData`

Retrieves the 32-bit application-specific value (64-bit if you're compiling for x64) associated with the item specified by nItem.

DWORD_PTR GetItemData(int nItem) const;

Parameters

nItem
Index of the list item whose data is to be retrieved.

Return Value

A 32-bit (64-bit if you're compiling for x64) application-specific value associated with the specified item.

Remarks

This value is the lParam member of the LVITEM structure, as described in the Windows SDK

Example

// If any item's data is equal to zero then reset it to -1.
for (int i=0; i < m_myListCtrl.GetItemCount(); i++)
{
    if (m_myListCtrl.GetItemData(i) == 0)
    {
        m_myListCtrl.SetItemData(i, (DWORD) -1);
    }
}

`CListCtrl::GetItemIndexRect`

Retrieves the bounding rectangle for all or part of a subitem in the current list-view control.

BOOL GetItemIndexRect(
    PLVITEMINDEX pItemIndex,
    int iColumn,
    int rectType,
    LPRECT pRect) const;

Parameters

pItemIndex
[in] Pointer to an LVITEMINDEX structure for the parent item of the subitem. The caller is responsible for allocating and setting the members of the LVITEMINDEX structure. This parameter cannot be NULL.

iColumn
[in] Zero-based index of a column in the control.

rectType
[in] Portion of the list-view subitem for which the bounding rectangle is retrieved. Specify one of the following values:

LVIR_BOUNDS - Returns the bounding rectangle of the entire subitem, including the icon and label.
LVIR_ICON - Returns the bounding rectangle of the icon or small icon of the subitem.
LVIR_LABEL - Returns the bounding rectangle of the subitem text.

pRect
[out] Pointer to a RECT structure that receives information about the bounding rectangle of the subitem. The caller is responsible for allocating the RECT structure. This parameter cannot be NULL.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method sends the LVM_GETITEMINDEXRECT message, which is described in the Windows SDK. For more information, see ListView_GetItemIndexRect Macro.

Example

The first code example defines a variable, m_listCtrl, that is used to access the current list-view control. This variable is used in the next example.

public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;

The next code example demonstrates the GetGroupRect method. Before entering this code example, we created a list-view control that displays two columns titled "ClientID" and "Grade" in a report view. The following code example draws a 3D rectangle around the second subitem in both columns.

// GetItemIndexRect
// Get the rectangle that bounds the second item in the first group.
LVITEMINDEX lvItemIndex;
lvItemIndex.iGroup = 0;
lvItemIndex.iItem = 1;
CRect rect;
BOOL bRet = m_listCtrl.GetItemIndexRect(
    &lvItemIndex, 0, LVIR_BOUNDS, &rect);

// Draw a red rectangle around the item.
m_listCtrl.GetDC()->Draw3dRect( &rect, RGB(255, 0, 0), RGB(255, 0, 0) );

`CListCtrl::GetItemPosition`

Retrieves the position of a list view item.

BOOL GetItemPosition(
    int nItem,
    LPPOINT lpPoint) const;

Parameters

nItem
The index of the item whose position is to be retrieved.

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

Return Value

Nonzero if successful; otherwise zero.

Example

POINT pt;

// Move all items in the list control 100 pixels to the right.
UINT i, nCount = m_myListCtrl.GetItemCount();

for (i=0; i < nCount; i++)
{
    m_myListCtrl.GetItemPosition(i, &pt);
    pt.x += 100;
    m_myListCtrl.SetItemPosition(i, pt);
}

`CListCtrl::GetItemRect`

Retrieves the bounding rectangle for all or part of an item in the current view.

BOOL GetItemRect(
    int nItem,
    LPRECT lpRect,
    UINT nCode) const;

Parameters

nItem
The index of the item whose position is to be retrieved.

lpRect
Address of a RECT structure that receives the bounding rectangle.

nCode
Portion of the list view item for which to retrieve the bounding rectangle. It can be one of these 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.

Return Value

Nonzero if successful; otherwise zero.

Example

// OnClick is the handler for the NM_CLICK notification
void CListCtrlDlg::OnClick(NMHDR* pNMHDR, LRESULT* pResult)
{
    UNREFERENCED_PARAMETER(pResult);
    LPNMITEMACTIVATE pia = (LPNMITEMACTIVATE)pNMHDR;

    // Get the current mouse location and convert it to client
    // coordinates.
    CPoint pos( ::GetMessagePos() );
    ScreenToClient(&pos);

    // Get indexes of the first and last visible items in
    // the listview control.
    int index = m_myListCtrl.GetTopIndex();
    int last_visible_index = index + m_myListCtrl.GetCountPerPage();
    if (last_visible_index > m_myListCtrl.GetItemCount())
        last_visible_index = m_myListCtrl.GetItemCount();

    // Loop until number visible items has been reached.
    while (index <= last_visible_index)
    {
        // Get the bounding rectangle of an item. If the mouse
        // location is within the bounding rectangle of the item,
        // you know you have found the item that was being clicked.
        CRect r;
        m_myListCtrl.GetItemRect(index, &r, LVIR_BOUNDS);
        if (r.PtInRect(pia->ptAction))
        {
            UINT flag = LVIS_SELECTED | LVIS_FOCUSED;
            m_myListCtrl.SetItemState(index, flag, flag);
            break;
        }

        // Get the next item in listview control.
        index++;
    }
}

`CListCtrl::GetItemSpacing`

Calculates the spacing between items in the current list-view control.

BOOL GetItemSpacing(
    BOOL fSmall,
    int* pnHorzSpacing,
    int* pnVertSpacing) const;

Parameters

fSmall
[in] View for which to retrieve the item spacing. Specify TRUE for small icon view, or FALSE for icon view.

pnHorzSpacing
[out] Contains the horizontal spacing between items.

pnVertSpacing
[out] Contains the vertical spacing between items.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method sends the LVM_GETITEMSPACING message, which is described in the Windows SDK.

`CListCtrl::GetItemState`

Retrieves the state of a list view item.

UINT GetItemState(
    int nItem,
    UINT nMask) const;

Parameters

nItem
The index of the item whose state is to be retrieved.

nMask
Mask specifying which of the item's state flags to return.

Return Value

The state flags for the specified list view item.

Remarks

An item's state is specified by the state member of the LVITEM structure, as described in the Windows SDK. When you specify or change an item's state, the stateMask member specifies which state bits you want to change.

Example

See the example for CListCtrl::GetTopIndex.

`CListCtrl::GetItemText`

Retrieves the text of a list view item or subitem.

int GetItemText(
    int nItem,
    int nSubItem,
    LPTSTR lpszText,
    int nLen) const;

CString GetItemText(
    int nItem,
    int nSubItem) const;

Parameters

nItem
The index of the item whose text is to be retrieved.

nSubItem
Specifies the subitem whose text is to be retrieved.

lpszText
Pointer to a string that is to receive the item text.

nLen
Length of the buffer pointed to by lpszText.

Return Value

The version returning int returns the length of the retrieved string.

The version returning a CString returns the item text.

Remarks

If nSubItem is zero, this function retrieves the item label; if nSubItem is nonzero, it retrieves the text of the subitem. For more information on the subitem argument, see the discussion of the LVITEM structure in the Windows SDK.

`CListCtrl::GetNextItem`

Searches for a list view item that has the specified properties and that bears the specified relationship to a given item.

int GetNextItem(
    int nItem,
    int nFlags) const;

Parameters

nItem
Index of the item to begin the searching with, or -1 to find the first item that matches the specified flags. The specified item itself is excluded from the search.

nFlags
Geometric relation of the requested item to the specified item, and the state of the requested item. The geometric relation can be one of these 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 these values:

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 doesn't have all of the specified state flags set, the search continues with the next item.

Return Value

The index of the next item if successful, or -1 otherwise.

`CListCtrl::GetNextItemIndex`

Retrieves the index of the item in the current list-view control that has a specified set of properties.

BOOL GetNextItemIndex(
    PLVITEMINDEX pItemIndex,
    int nFlags) const;

Parameters

pItemIndex
[in, out] Pointer to the LVITEMINDEX structure that describes the item where the search begins, or -1 to find the first item that matches the flags in the nFlags parameter. If this method is successful, the LVITEMINDEX structure describes the item found by the search.

nFlags
[in] A bitwise combination (OR) of flags that specify how to perform the search. The search can depend on the index, state, or appearance of the target item, or the target item's physical position relative to the item specified by the pItemIndex parameter. For more information, see the flags parameter in the LVM_GETNEXTITEMINDEX message.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

The caller is responsible for allocating and setting the members of the LVITEMINDEX structure pointed to by the pItemIndex parameter.

This method sends the LVM_GETNEXTITEMINDEX message, which is described in the Windows SDK.

`CListCtrl::GetNextSelectedItem`

Gets the index of the list item identified by pos, then sets pos to the POSITION value.

int GetNextSelectedItem(POSITION& pos) const;

Parameters

pos
A reference to a POSITION value returned by a previous call to GetNextSelectedItem or GetFirstSelectedItemPosition. The value is updated to the next position by this call.

Return Value

The index of the list item identified by pos.

Remarks

You can use GetNextSelectedItem in a forward iteration loop if you establish the initial position with a call to GetFirstSelectedItemPosition.

You must ensure that your POSITION value is valid. If it's invalid, then the Debug version of the Microsoft Foundation Class Library asserts.

Example

The following code sample demonstrates the usage of this function.

POSITION pos = m_myListCtrl.GetFirstSelectedItemPosition();
if (pos == NULL)
{
    TRACE(_T("No items were selected!\n"));
}
else
{
    while (pos)
    {
        int nItem = m_myListCtrl.GetNextSelectedItem(pos);
        TRACE(_T("Item %d was selected!\n"), nItem);
        // you could do your own processing on nItem here
    }
}

`CListCtrl::GetNumberOfWorkAreas`

Retrieves the current number of working areas for a list view control.

UINT GetNumberOfWorkAreas() const;

Return Value

Not used at this time.

Remarks

This member function implements the behavior of the Win32 macro, ListView_GetNumberOfWorkAreas, as described in the Windows SDK.

Example

UINT i, uCount = m_myListCtrl.GetNumberOfWorkAreas();
LPRECT lpRects = (LPRECT) malloc(uCount*sizeof(RECT));

if (lpRects != NULL)
{
    // Dump all of the work area dimensions.
    m_myListCtrl.GetWorkAreas(uCount, lpRects);

    for (i=0; i < uCount; i++)
    {
        TRACE(_T("Work area %d; left = %d, top = %d, right = %d, ")
            _T("bottom = %d\r\n"),
            i, lpRects[i].left, lpRects[i].top, lpRects[i].right,
            lpRects[i].bottom);
    }

    free(lpRects);
}
else
{
    TRACE(_T("Couldn't allocate enough memory!"));
}

`CListCtrl::GetOutlineColor`

Retrieves the color of the border of a list view control.

COLORREF GetOutlineColor() const;

Return Value

Returns a COLORREF structure containing the outline color.

Remarks

This member function emulates the functionality of the LVM_GETOUTLINECOLOR message, as described in the Windows SDK.

`CListCtrl::GetOrigin`

Retrieves the current view origin for a list view control.

BOOL GetOrigin(LPPOINT lpPoint) const;

Parameters

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

Return Value

Nonzero if successful; otherwise zero. However, if the control is in report view, the return value is always zero.

`CListCtrl::GetSelectedColumn`

Retrieves the index of the currently selected column in the list control.

UINT GetSelectedColumn() const;

Return Value

The index of the selected column.

Remarks

This member function emulates the functionality of the LVM_GETSELECTEDCOLUMN message, as described in the Windows SDK.

`CListCtrl::GetSelectedCount`

Retrieves the number of selected items in the list view control.

UINT GetSelectedCount() const;

Return Value

The number of selected items in the list view control.

Example

UINT i, uSelectedCount = m_myListCtrl.GetSelectedCount();
int  nItem = -1;

// Update all of the selected items.
if (uSelectedCount > 0)
{
    for (i=0; i < uSelectedCount; i++)
    {
        nItem = m_myListCtrl.GetNextItem(nItem, LVNI_SELECTED);
        ASSERT(nItem != -1);
        m_myListCtrl.Update(nItem);
    }
}

`CListCtrl::GetSelectionMark`

Retrieves the selection mark of a list view control.

int GetSelectionMark();

Return Value

The zero-based selection mark, or -1 if there's no selection mark.

Remarks

This member function implements the behavior of the Win32 macro, ListView_GetSelectionMark, as described in the Windows SDK.

Example

// Set the selection mark to the first item only if no other item is
// selected.
if (m_myListCtrl.GetSelectionMark() == -1)
    m_myListCtrl.SetSelectionMark(0);

`CListCtrl::GetStringWidth`

Determines the minimum column width necessary to display all of a given string.

int GetStringWidth(LPCTSTR lpsz) const;

Parameters

lpsz
Address of a null-terminated string whose width is to be determined.

Return Value

The width, in pixels, of the string pointed to by lpsz.

Remarks

The returned width takes into account the control's current font and column margins, but not the width of a small icon.

Example

CString strColumn;
int nWidth;

// Insert six columns in the list view control. Make the width of
// the column be the width of the column header plus 50%.
for (int i = 0; i < 6; i++)
{
    strColumn.Format(_T("column %d"), i);
    nWidth = 3*m_myListCtrl.GetStringWidth(strColumn)/2;
    m_myListCtrl.InsertColumn(i, strColumn, LVCFMT_LEFT, nWidth);
}

`CListCtrl::GetSubItemRect`

Retrieves the bounding rectangle of an item in a list view control.

BOOL GetSubItemRect(
    int iItem,
    int iSubItem,
    int nArea,
    CRect& ref);

Parameters

iItem
Index of the subitem's parent item.

iSubItem
The one-based index of the subitem.

nArea
Determines the portion of the bounding rectangle (of the list view subitem) to be retrieved. The portion (icon, label, or both) of the bounding rectangle is specified by applying the bitwise OR operator to one or more 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 entire item, including the icon and label. This is identical to LVIR_BOUNDS.

ref
Reference to a CRect object that contains the coordinates of the subitem's bounding rectangle.

Return Value

Nonzero if successful; otherwise zero.

Remarks

This member function implements the behavior of the Win32 macro, ListView_GetSubItemRect, as described in the Windows SDK.

`CListCtrl::GetTextBkColor`

Retrieves the text background color of a list view control.

COLORREF GetTextBkColor() const;

Return Value

A 32-bit value used to specify an RGB color.

Example

See the example for CListCtrl::SetTextBkColor.

`CListCtrl::GetTextColor`

Retrieves the text color of a list view control.

COLORREF GetTextColor() const;

Return Value

A 32-bit value used to specify an RGB color.

Example

See the example for CListCtrl::SetTextColor.

`CListCtrl::GetTileInfo`

Retrieves information about a tile in a list view control.

BOOL GetTileInfo(PLVTILEINFO plvti) const;

Parameters

plvti
A pointer to an LVTILEINFO structure that receives the tile information.

Return Value

The return value isn't used.

Remarks

This member function emulates the functionality of the LVM_GETTILEINFO message, as described in the Windows SDK.

`CListCtrl::GetTileViewInfo`

Retrieves information about a list view control in tile view.

BOOL GetTileViewInfo(PLVTILEVIEWINFO ptvi) const;

Parameters

ptvi
A pointer to an LVTILEVIEWINFO structure that receives the retrieved information.

Return Value

The return value isn't used.

Remarks

This member function emulates the functionality of the LVM_GETTILEVIEWINFO message, as described in the Windows SDK.

`CListCtrl::GetToolTips`

Retrieves the tooltip control that the list view control uses to display tooltips.

CToolTipCtrl* GetToolTips() const;

Return Value

A pointer to a CToolTipCtrl object to be used by the list control. If the Create member function uses the style LVS_NOTOOLTIPS, no tooltips are used, and NULL is returned.

Remarks

This member function implements the behavior of the Win32 message LVM_GETTOOLTIPS, as described in the Windows SDK. The MFC implementation of GetToolTips returns a CToolTipCtrl object, which is used by the list control, rather than a handle to a tooltip control.

Example

CToolTipCtrl* pTip = m_myListCtrl.GetToolTips();
if (NULL != pTip)
{
    pTip->UpdateTipText(_T("I'm a list view!"), &m_myListCtrl,
        IDD_MYLISTCTRL);
}

`CListCtrl::GetTopIndex`

Retrieves the index of the topmost visible item when in list view or report view.

int GetTopIndex() const;

Return Value

The index of the topmost visible item.

Example

// Make sure the focus is set to the list view control.
m_myListCtrl.SetFocus();

// Select all of the items that are completely visible.
int n = m_myListCtrl.GetTopIndex();
int nLast = n + m_myListCtrl.GetCountPerPage();

for (; n < nLast; n++)
{
    m_myListCtrl.SetItemState(n, LVIS_SELECTED, LVIS_SELECTED);
    ASSERT(m_myListCtrl.GetItemState(n, LVIS_SELECTED) == LVIS_SELECTED);
}

`CListCtrl::GetView`

Gets the view of the list view control.

DWORD GetView() const;

Return Value

The current view of the list view control.

Remarks

This member function emulates the functionality of the LVM_GETVIEW message, as described in the Windows SDK.

`CListCtrl::GetViewRect`

Retrieves the bounding rectangle of all items in the list view control.

BOOL GetViewRect(LPRECT lpRect) const;

Parameters

lpRect
Address of a RECT structure.

Return Value

Nonzero if successful; otherwise zero.

Remarks

The list view must be in icon view or small icon view.

`CListCtrl::GetWorkAreas`

Retrieves the current working areas of a list view control.

void GetWorkAreas(
    int nWorkAreas,
    LPRECT pRect) const;

Parameters

nWorkAreas
The number of RECT structures contained in the pRect array.

pRect
A pointer to an array of RECT structures (or CRect objects) that receive the working areas of the list view control. Values in these structures are in client coordinates.

Remarks

This member function implements the behavior of the Win32 macro, ListView_GetWorkAreas, as described in the Windows SDK.

Example

See the example for CListCtrl::GetNumberOfWorkAreas.

`CListCtrl::HasGroup`

Determines if the list view control has the specified group.

BOOL HasGroup(int iGroupId) const;

Parameters

iGroupId
The identifier of the group being requested.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

This member function emulates the functionality of the LVM_HASGROUP message, as described in the Windows SDK.

`CListCtrl::HitTest`

Determines which list view item, if any, is at a specified position.

int HitTest(LVHITTESTINFO* pHitTestInfo) const;

int HitTest(
    CPoint pt,
    UINT* pFlags = NULL) const;

Parameters

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

pt
Point to be tested.

pFlags
Pointer to an integer that receives information about the results of the test. See the explanation of the flags member of the LVHITTESTINFO structure in the Windows SDK.

Return Value

The index of the item at the position specified by pHitTestInfo, if any, or -1 otherwise.

Remarks

You can use the LVHT_ABOVE, LVHT_BELOW, LVHT_TOLEFT, and LVHT_TORIGHT values of the structure's flag member to determine whether to scroll the contents of a list view control. Two of these flags can be combined, for example, if the position is above and to the left of the client area.

You can test for the LVHT_ONITEM value of the structure's flag member to determine whether a given position is over a list view item. This value is a bitwise-OR operation on the LVHT_ONITEMICON, LVHT_ONITEMLABEL, and LVHT_ONITEMSTATEICON values of the structure's flag member.

Example

void CListCtrlDlg::OnRClick(NMHDR* pNMHDR, LRESULT* pResult)
{
    LPNMITEMACTIVATE pia = (LPNMITEMACTIVATE)pNMHDR;
    CPoint point(pia->ptAction);

    // Select the item the user clicked on.
    UINT uFlags;
    int nItem = m_myListCtrl.HitTest(point, &uFlags);

    if (uFlags & LVHT_ONITEMLABEL)
    {
        m_myListCtrl.SetItem(nItem, 0, LVIF_STATE, NULL, 0, LVIS_SELECTED,
            LVIS_SELECTED, 0);
    }

    *pResult = 0;
}

`CListCtrl::InsertColumn`

Inserts a new column in a list view control.

int InsertColumn(
    int nCol,
    const LVCOLUMN* pColumn);

int InsertColumn(
    int nCol,
    LPCTSTR lpszColumnHeading,
    int nFormat = LVCFMT_LEFT,
    int nWidth = -1,
    int nSubItem = -1);

Parameters

nCol
The index of the new column.

pColumn
Address of an LVCOLUMN structure that contains the attributes of the new column.

lpszColumnHeading
Address of a string containing the column's heading.

nFormat
Integer specifying the alignment of the column. It can be one of these values: LVCFMT_LEFT, LVCFMT_RIGHT, or LVCFMT_CENTER.

nWidth
Width of the column, in pixels. If this parameter is -1, the column width isn't set.

nSubItem
Index of the subitem associated with the column. If this parameter is -1, no subitem is associated with the column.

Return Value

The index of the new column if successful or -1 otherwise.

Remarks

The leftmost column in a list view control must be left-aligned.

The LVCOLUMN structure contains the attributes of a column in report view. It's also used to receive information about a column. This structure is described in the Windows SDK.

`CListCtrl::InsertGroup`

Inserts a group into the list view control.

LRESULT InsertGroup(
    int index,
    PLVGROUP pgrp);

Parameters

index
The index of the item where the group is to be inserted.

pgrp
A pointer to an LVGROUP structure containing the group to be added.

Return Value

Returns the index of the item that the group was added to, or -1 if the operation failed.

Remarks

This member function emulates the functionality of the LVM_INSERTGROUP message, as described in the Windows SDK.

`CListCtrl::InsertGroupSorted`

Inserts the specified group into an ordered list of groups.

LRESULT InsertGroupSorted(PLVINSERTGROUPSORTED pStructInsert);

Parameters

pStructInsert
A pointer to an LVINSERTGROUPSORTED structure that contains the group to insert.

Return Value

The return value isn't used.

Remarks

This member function emulates the functionality of the LVM_INSERTGROUPSORTED message, as described in the Windows SDK.

`CListCtrl::InsertItem`

Inserts an item into the list view control.

int InsertItem(const LVITEM* pItem);

int InsertItem(
    int nItem,
    LPCTSTR lpszItem);

int InsertItem(
    int nItem,
    LPCTSTR lpszItem,
    int nImage);

int InsertItem(
    UINT nMask,
    int nItem,
    LPCTSTR lpszItem,
    UINT nState,
    UINT nStateMask,
    int nImage,
    LPARAM lParam);

Parameters

pItem
Pointer to an LVITEM structure that specifies the item's attributes, as described in the Windows SDK.

nItem
Index of the item to be inserted.

lpszItem
Address of a string containing the item's label, or LPSTR_TEXTCALLBACK if the item is a callback item. For information on callback items, see CListCtrl::GetCallbackMask.

nImage
Index of the item's image, or I_IMAGECALLBACK if the item is a callback item. For information on callback items, see CListCtrl::GetCallbackMask.

nMask
The nMask parameter specifies which item attributes passed as parameters are valid. It can be one or more of the mask values described in LVITEM Structure in the Windows SDK. The valid values can be combined with the bitwise OR operator.

nState
Indicates the item's state, state image, and overlay image. For more information, see the Windows SDK topics LVITEM Structure and List-View Item States for a list of valid flags.

nStateMask
Indicates which bits of the state member will be retrieved or modified. For more information, see LVITEM Structure in the Windows SDK.

lParam
A 32-bit application-specific value (64-bit if you're compiling for x64) associated with the item. If this parameter is specified, you must set the nMask attribute LVIF_PARAM.

Return Value

The index of the new item if successful or -1 otherwise.

Remarks

Calling this method may cause the LVM_INSERTITEM message to be sent to your control window. The associated message handler for the control may fail to set the item text under certain conditions (such as using window styles such as LVS_OWNERDRAW). For more information on these conditions, see LVM_INSERTITEM in the Windows SDK.

Example

CString strText;
int nColumnCount = m_myListCtrl.GetHeaderCtrl()->GetItemCount();

// Insert 10 items in the list view control.
for (int i = 0; i < 10; i++)
{
    strText.Format(TEXT("item %d"), i);

    // Insert the item, select every other item.
    m_myListCtrl.InsertItem(LVIF_TEXT | LVIF_STATE, i, strText,
        (i % 2) == 0 ? LVIS_SELECTED : 0, LVIS_SELECTED, 0, 0);

    // Initialize the text of the subitems.
    for (int j = 1; j < nColumnCount; j++)
    {
        strText.Format(TEXT("sub-item %d %d"), i, j);
        m_myListCtrl.SetItemText(i, j, strText);
    }
}

`CListCtrl::InsertMarkHitTest`

Retrieves the insertion point closest to a specified point.

int InsertMarkHitTest(
    LPPOINT pPoint,
    LPLVINSERTMARK plvim) const;

Parameters

pPoint
A pointer to a POINT structure that contains the hit test coordinates, relative to the client area of the list control.

plvim
A pointer to an LVINSERTMARK structure that specifies the insertion point closest to the coordinates defined by the point parameter.

Return Value

The insertion point closest to the specified point.

Remarks

This member function emulates the functionality of the LVM_INSERTMARKHITTEST message, as described in the Windows SDK.

`CListCtrl::IsGroupViewEnabled`

Determines whether group view is enabled for a list view control.

BOOL IsGroupViewEnabled() const;

Return Value

Returns TRUE if group view is enabled, or FALSE otherwise.

Remarks

This member function emulates the functionality of the LVM_ISGROUPVIEWENABLED message, as described in the Windows SDK.

`CListCtrl::IsItemVisible`

Indicates whether a specified item in the current list-view control is visible.

BOOL IsItemVisible(int index) const;

Parameters

index
[in] Zero-based index of an item in the current list-view control.

Return Value

TRUE if the specified item is visible; otherwise, FALSE.

Remarks

This method sends the LVM_ISITEMVISIBLE message, which is described in the Windows SDK.

`CListCtrl::MapIDToIndex`

Maps the unique ID of an item in the current list-view control to an index.

UINT MapIDToIndex(UINT id) const;

Parameters

id
[in] The unique ID of an item.

Return Value

The current index for the specified ID.

Remarks

A list-view control internally tracks items by index. This can present problems because indexes can change during the control's lifetime. The list-view control can tag an item with an ID when the item is created and you can use this ID to guarantee uniqueness during the lifetime of the list-view control.

In a multithreaded environment the index is guaranteed only on the thread that hosts the list-view control, not on background threads.

This method sends the LVM_MAPIDTOINDEX message, which is described in the Windows SDK.

`CListCtrl::MapIndexToID`

Maps the index of an item in the current list-view control to a unique ID.

UINT MapIndexToID(UINT index) const;

Parameters

index
[in] The zero-based index of an item.

Return Value

A unique ID for the specified item.

Remarks

A list-view control internally tracks items by index. This can present problems because indexes can change during the control's lifetime. The list-view control can tag an item with an ID when the item is created. You can use this ID to access a specific item for the lifetime of the list-view control.

In a multithreaded environment the index is guaranteed only on the thread that hosts the list-view control, not on background threads.

This method sends the LVM_MAPINDEXTOID message, which is described in the Windows SDK.

Example

The first code example defines a variable, m_listCtrl, that is used to access the current list-view control. This variable is used in the next example.

public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;

The next code example demonstrates the MapIndexToID method. In an earlier section of this code example, we created a list-view control that displays two columns titled "ClientID" and "Grade" in a report view. The following example maps the index of each list-view item to an identification number, and then retrieves the index for each identification number. Finally, the example reports whether the original indexes were retrieved.

// MapIndexToID
int iCount = m_listCtrl.GetItemCount();
UINT nId = 0;
UINT nIndex = 0;
for (int iIndexOriginal = 0; iIndexOriginal < iCount; iIndexOriginal++)
{
    // Map index to ID.
    nId = m_listCtrl.MapIndexToID((UINT)iIndexOriginal);

    // Map ID to index.
    nIndex = m_listCtrl.MapIDToIndex(nId);

    if (nIndex != (UINT)(iIndexOriginal))
    {
        CString str;
        str.Format(_T("Mapped index (%d) is not equal to original index (%d)"),
            nIndex, (UINT)(iIndexOriginal));
        AfxMessageBox(str);
        return;
    }
}
AfxMessageBox(_T("The mapped indexes and original indexes are equal."),
    MB_ICONINFORMATION);

`CListCtrl::MoveGroup`

Moves the specified group to the specified zero based index of the list view control.

LRESULT MoveGroup(
    int iGroupId,
    int toIndex);

Parameters

iGroupId
The identifier of the group to be moved.

toIndex
The zero-based index where the group is to be moved.

Return Value

The return value isn't used.

Remarks

This member function emulates the functionality of the LVM_MOVEGROUP message, as described in the Windows SDK.

`CListCtrl::MoveItemToGroup`

Moves the specified item into the specified group.

void MoveItemToGroup(
    int idItemFrom,
    int idGroupTo);

Parameters

idItemFrom
[in] The index of the item to be moved.

idGroupTo
[in] The identifier of the group the item will be moved to.

Remarks

Note

This method currently isn't implemented.

This method emulates the functionality of the LVM_MOVEITEMTOGROUP message, as described in the Windows SDK.

`CListCtrl::RedrawItems`

Forces a list view control to repaint a range of items.

BOOL RedrawItems(
    int nFirst,
    int nLast);

Parameters

nFirst
Index of the first item to be repainted.

nLast
Index of the last item to be repainted.

Return Value

Nonzero if successful; otherwise zero.

Remarks

The specified items aren't repainted until the list view window receives a WM_PAINT message. To repaint immediately, call the Windows UpdateWindow function after using this function.

`CListCtrl::RemoveAllGroups`

Removes all groups from a list view control.

void RemoveAllGroups();

Remarks

This member function emulates the functionality of the LVM_REMOVEALLGROUPS message, as described in the Windows SDK.

`CListCtrl::RemoveGroup`

Removes the specified group from the list view control.

LRESULT RemoveGroup(int iGroupId);

Parameters

iGroupId
The identifier of the group to be removed.

Return Value

Returns the index of the group if successful, or -1 otherwise.

Remarks

This member function emulates the functionality of the LVM_REMOVEGROUP message, as described in the Windows SDK.

`CListCtrl::Scroll`

Scrolls the content of a list view control.

BOOL Scroll(CSize size);

Parameters

size
A CSize object specifying the amount of horizontal and vertical scrolling, in pixels. The y member of size is divided by the height, in pixels, of the list view control's line, and the control is scrolled by the resulting number of lines.

Return Value

Nonzero if successful; otherwise zero.

`CListCtrl::SetBkColor`

Sets the background color of the list view control.

BOOL SetBkColor(COLORREF cr);

Parameters

cr
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. For information, see COLORREF in the Windows SDK.

Return Value

Nonzero if successful; otherwise zero.

Example

// Use the 3D button face color for the background.
COLORREF crBkColor = ::GetSysColor(COLOR_3DFACE);
m_myListCtrl.SetBkColor(crBkColor);
ASSERT(m_myListCtrl.GetBkColor() == crBkColor);

`CListCtrl::SetBkImage`

Sets the background image of a list view control.

BOOL SetBkImage(LVBKIMAGE* plvbkImage);

BOOL SetBkImage(
    HBITMAP hBitmap,
    BOOL fTile = TRUE,
    int xOffsetPercent = 0,
    int yOffsetPercent = 0);

BOOL SetBkImage(
    LPTSTR pszUrl,
    BOOL fTile = TRUE,
    int xOffsetPercent = 0,
    int yOffsetPercent = 0);

Parameters

plvbkImage
Address of an LVBKIMAGE structure, containing the new background image information.

hBitmap
Handle to a bitmap.

pszUrl
A NULL-terminated string that contains the URL of the background image.

fTile
Nonzero if the image is to be tiled in the background of the list view control; otherwise 0.

xOffsetPercent
The offset, in pixels, of the image's left edge, from origin of the list view control.

yOffsetPercent
The offset, in pixels, of the image's top edge, from origin of the list view control.

Return Value

Returns nonzero if successful, or zero otherwise.

Remarks

Note

Because CListCtrl::SetBkImage makes use of OLE COM functionality, the OLE libraries must be initialized before using SetBkImage. It's best to initialize the COM libraries when the application is initialized and uninitialize the libraries when the application terminates. This is automatically done in MFC applications that make use of ActiveX technology, OLE Automation, OLE Linking/Embedding, or ODBC/DAO operations.

Example

See the example for CListCtrl::GetBkImage.

`CListCtrl::SetCallbackMask`

Sets the callback mask for a list view control.

BOOL SetCallbackMask(UINT nMask);

Parameters

nMask
New value of the callback mask.

Return Value

Nonzero if successful; otherwise zero.

Example

// Set the callback mask so that only the selected and focused states
// are stored for each item.
m_myListCtrl.SetCallbackMask(LVIS_SELECTED|LVIS_FOCUSED);
ASSERT(m_myListCtrl.GetCallbackMask() ==
    (LVIS_SELECTED|LVIS_FOCUSED));

`CListCtrl::SetCheck`

Determines if the state image of a list control item is visible.

BOOL SetCheck(
    int nItem,
    BOOL fCheck = TRUE);

Parameters

nItem
The zero-based index of a list control item.

fCheck
Specifies whether the state image of the item should be visible or not. By default, fCheck is TRUE and the state image is visible. If fCheck is FALSE, it's not visible.

Return Value

Nonzero if the item is checked, otherwise 0.

Example

int nCount = m_myListCtrl.GetItemCount();
BOOL fCheck = FALSE;

// Set the check state of every other item to TRUE and
// all others to FALSE.
for (int i = 0; i < nCount; i++)
{
    m_myListCtrl.SetCheck(i, fCheck);
    ASSERT((m_myListCtrl.GetCheck(i) && fCheck) ||
        (!m_myListCtrl.GetCheck(i) && !fCheck));
    fCheck = !fCheck;
}

`CListCtrl::SetColumn`

Sets the attributes of a list view column.

BOOL SetColumn(
    int nCol,
    const LVCOLUMN* pColumn);

Parameters

nCol
Index of the column whose attributes are to be set.

pColumn
Address of an LVCOLUMN structure that contains the new column attributes, as described in the Windows SDK. The structure's mask member specifies which column attributes to set. If the mask member specifies the LVCF_TEXT value, the structure's pszText member is the address of a null-terminated string and the structure's cchTextMax member is ignored.

Return Value

Nonzero if successful; otherwise zero.

Example

See the example for CListCtrl::GetColumn.

`CListCtrl::SetColumnOrderArray`

Sets the column order (left to right) of a list view control.

BOOL SetColumnOrderArray(
    int iCount,
    LPINT piArray);

Parameters

piArray
A pointer to a buffer containing the index values of the columns in the list view control (from left to right). The buffer must be large enough to contain the total number of columns in the list view control.

iCount
Number of columns in the list view control.

Return Value

Nonzero if successful; otherwise zero.

Remarks

This member function implements the behavior of the Win32 macro, ListView_SetColumnOrderArray, as described in the Windows SDK.

Example

See the example for CListCtrl::GetColumnOrderArray.

`CListCtrl::SetColumnWidth`

Changes the width of a column in report view or list view.

BOOL SetColumnWidth(
    int nCol,
    int cx);

Parameters

nCol
Index of the column for which the width is to be set. In list view, this parameter must be 0.

cx
The new width of the column. Can be either LVSCW_AUTOSIZE or LVSCW_AUTOSIZE_USEHEADER, as described in LVM_SETCOLUMNWIDTH in the Windows SDK.

Return Value

Nonzero if successful; otherwise zero.

`CListCtrl::SetExtendedStyle`

Sets the current extended styles of a list view control.

DWORD SetExtendedStyle(DWORD dwNewStyle);

Parameters

dwNewStyle
A combination of extended styles to be used by the list view control. For a descriptive list of these styles, see the Extended List View Styles topic in the Windows SDK.

Return Value

A combination of the previous extended styles used by the list view control.

Remarks

This member function implements the behavior of the Win32 macro, ListView_SetExtendedListViewStyle, as described in the Windows SDK.

Example

// Allow the header controls item to be movable by the user.
m_myListCtrl.SetExtendedStyle
    (m_myListCtrl.GetExtendedStyle()|LVS_EX_HEADERDRAGDROP);

`CListCtrl::SetGroupInfo`

Sets the information that describes the specified group of the current list-view control.

int SetGroupInfo(
    int iGroupId,
    PLVGROUP pgrp);

Parameters

iGroupId
The identifier of the group whose information is set.

pgrp
Pointer to an LVGROUP structure that contains the information to set. The caller is responsible for allocating this structure and setting its members.

Return Value

The ID of the group if the method is successful; otherwise, -1.

Remarks

This method sends the LVM_SETGROUPINFO message, which is described in the Windows SDK.

`CListCtrl::SetGroupMetrics`

Sets the group metrics of a list view control.

void SetGroupMetrics(PLVGROUPMETRICS pGroupMetrics);

Parameters

pGroupMetrics
A pointer to an LVGROUPMETRICS structure containing the group metrics information to be set.

Remarks

This member function emulates the functionality of the LVM_SETGROUPMETRICS message, as described in the Windows SDK.

`CListCtrl::SetHotCursor`

Sets the cursor used when hot tracking is enabled for a list view control.

HCURSOR SetHotCursor(HCURSOR hc);

Parameters

hc
A handle to a cursor resource, used to represent the hot cursor.

Return Value

The handle to the previous hot cursor resource being used by the list view control.

Remarks

This member function implements the behavior of the Win32 macro, ListView_SetHotCursor, as described in the Windows SDK.

The hot cursor, only visible when hover selection is enabled, appears as the cursor passes over any list view item. Hover selection is enabled by setting the LVS_EX_TRACKSELECT extended style.

Example

See the example for CListCtrl::GetHotCursor.

`CListCtrl::SetHotItem`

Sets the current hot item of a list view control.

int SetHotItem(int iIndex);

Parameters

iIndex
Zero-based index of the item to be set as the hot item.

Return Value

The zero-based index of the previously hot item.

Remarks

This member function implements the behavior of the Win32 macro, ListView_SetHotItem, as described in the Windows SDK.

Example

See the example for CListCtrl::GetHotItem.

`CListCtrl::SetHoverTime`

Sets the current hover time of a list view control.

DWORD SetHoverTime(DWORD dwHoverTime = (DWORD)-1);

Parameters

dwHoverTime
The new delay, in milliseconds, which the mouse cursor must hover over an item before it's selected. If the default value is passed, the time is set to the default hover time.

Return Value

The previous hover time, in milliseconds.

Remarks

This member function implements the behavior of the Win32 macro, ListView_SetHoverTime, as described in the Windows SDK.

Example

See the example for CListCtrl::GetHoverTime.

`CListCtrl::SetIconSpacing`

Sets the spacing between icons in a list view control.

CSize SetIconSpacing(
    int cx,
    int cy);

CSize SetIconSpacing(CSize size);

Parameters

cx
The distance (in pixels) between icons on the x-axis.

cy
The distance (in pixels) between icons on the y-axis.

size
A CSize object specifying the distance (in pixels) between icons on the x- and y-axes.

Return Value

A CSize object containing the previous values for icon spacing.

Remarks

This member function implements the behavior of the Win32 macro, ListView_SetIconSpacing, as described in the Windows SDK.

Example

// Leave lots of space between icons.
m_myListCtrl.SetIconSpacing(CSize(100, 100));

`CListCtrl::SetImageList`

Assigns an image list to a list view control.

CImageList* SetImageList(
    CImageList* pImageList,
    int nImageListType);

Parameters

pImageList
Pointer to the image list to assign.

nImageListType
Type of image list. It can be one of these values:

LVSIL_NORMAL Image list with large icons.
LVSIL_SMALL Image list with small icons.
LVSIL_STATE Image list with state images.

Return Value

A pointer to the previous image list.

Example

See the example for CListCtrl::GetImageList.

`CListCtrl::SetInfoTip`

Sets the tooltip text.

BOOL SetInfoTip(PLVSETINFOTIP plvInfoTip);

Parameters

plvInfoTip
A pointer to an LVFSETINFOTIP structure containing the information to be set.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

This member function emulates the functionality of the LVM_SETINFOTIP message, as described in the Windows SDK.

`CListCtrl::SetInsertMark`

Sets the insertion point to the defined position.

BOOL SetInsertMark(LPLVINSERTMARK plvim);

Parameters

plvim
A pointer to an LVINSERTMARK structure specifying where to set the insertion point.

Return Value

Returns TRUE if successful, or FALSE otherwise. FALSE is returned if the size in the cbSize member of the LVINSERTMARK structure doesn't equal the actual size of the structure, or when an insertion point doesn't apply in the current view.

Remarks

This member function emulates the functionality of the LVM_SETINSERTMARK message, as described in the Windows SDK.

`CListCtrl::SetInsertMarkColor`

Sets the color of the insertion point.

COLORREF SetInsertMarkColor(COLORREF color);

Parameters

color
A COLORREF structure specifying the color to set the insertion point.

Return Value

Returns a COLORREF structure containing the previous color.

Remarks

This member function emulates the functionality of the LVM_SETINSERTMARKCOLOR message, as described in the Windows SDK.

`CListCtrl::SetItem`

Sets some or all of a list view item's attributes.

BOOL SetItem(const LVITEM* pItem);

BOOL SetItem(
    int nItem,
    int nSubItem,
    UINT nMask,
    LPCTSTR lpszItem,
    int nImage,
    UINT nState,
    UINT nStateMask,
    LPARAM lParam);

BOOL SetItem(
    int nItem,
    int nSubItem,
    UINT nMask,
    LPCTSTR lpszItem,
    int nImage,
    UINT nState,
    UINT nStateMask,
    LPARAM lParam,
    int nIndent);

Parameters

pItem
Address of an LVITEM structure that contains the new item attributes, as described in the Windows SDK. The structure's iItem and iSubItem members identify the item or subitem, and the structure's mask member specifies which attributes to set. For more information on the mask member, see the Remarks.

nItem
Index of the item whose attributes are to be set.

nSubItem
Index of the subitem whose attributes are to be set.

nMask
Specifies which attributes are to be set (see the Remarks).

lpszItem
Address of a null-terminated string specifying the item's label.

nImage
Index of the item's image within the image list.

nState
Specifies values for states to be changed (see the Remarks).

nStateMask
Specifies which states are to be changed (see the Remarks).

lParam
A 32-bit (64-bit if you're compiling for x64) application-specific value to associate with the item.

nIndent
Width, in pixels, of the indentation. If nIndent is less than the system-defined minimum width, the new width is set to the system-defined minimum

Return Value

Nonzero if successful; otherwise zero.

Remarks

The iItem and iSubItem members of the LVITEM structure and the nItem and nSubItem parameters identify the item and subitem whose attributes are to be set.

The mask member of the LVITEM structure and the nMask parameter specify which item attributes are to be set:

LVIF_TEXT The pszText member or the lpszItem parameter is the address of a null-terminated string; the cchTextMax member is ignored.
LVIF_STATE The stateMask member or nStateMask parameter specifies which item states to change and the state member or nState parameter contains the values for those states.

Example

See the example for CListCtrl::HitTest.

`CListCtrl::SetItemCount`

Prepares a list view control for adding a large number of items.

void SetItemCount(int nItems);

Parameters

nItems
Number of items that the control will ultimately contain.

Remarks

To set the item count for a virtual list view control, see CListCtrl::SetItemCountEx.

This member function implements the behavior of the Win32 macro, ListView_SetItemCount, as described in the Windows SDK.

Example

CString str;

// Add 1024 items to the list view control.
m_myListCtrl.SetItemCount(1024);

for (int i = 0; i < 1024; i++)
{
    str.Format(TEXT("item %d"), i);
    m_myListCtrl.InsertItem(i, str);
}

`CListCtrl::SetItemCountEx`

Sets the item count for a virtual list view control.

BOOL SetItemCountEx(
    int iCount,
    DWORD dwFlags = LVSICF_NOINVALIDATEALL);

Parameters

iCount
Number of items that the control will ultimately contain.

dwFlags
Specifies 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 won't repaint unless affected items are currently in view. This is the default value.
LVSICF_NOSCROLL The list view control won't change the scroll position when the item count changes.

Return Value

Nonzero if successful; otherwise zero.

Remarks

This member function implements the behavior of the Win32 macro, ListView_SetItemCountEx, as described in the Windows SDKand should only be called for virtual list views.

Example

CString str;

// Add 1024 items to the list view control.

// Force my virtual list view control to allocate
// enough memory for my 1024 items.
m_myVirtualListCtrl.SetItemCountEx(1024, LVSICF_NOSCROLL|
    LVSICF_NOINVALIDATEALL);

for (int i = 0; i < 1024; i++)
{
    str.Format(TEXT("item %d"), i);
    m_myVirtualListCtrl.InsertItem(i, str);
}

`CListCtrl::SetItemData`

Sets the 32-bit (64-bit if you're compiling for x64) application-specific value associated with the item specified by nItem.

BOOL SetItemData(int nItem, DWORD_PTR dwData);

Parameters

nItem
Index of the list item whose data is to be set.

dwData
A 32-bit value (64-bit if you're compiling for x64) to associate with the item.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This value is the lParam member of the LVITEM structure, as described in the Windows SDK.

Example

// Set the data of each item to be equal to its index.
for (int i = 0; i < m_myListCtrl.GetItemCount(); i++)
{
    m_myListCtrl.SetItemData(i, i);
}

`CListCtrl::SetItemIndexState`

Sets the state of an item in the current list-view control.

BOOL SetItemIndexState(
    PLVITEMINDEX pItemIndex,
    DWORD dwState,
    DWORD dwMask) const;

Parameters

pItemIndex
[in] Pointer to an LVITEMINDEX structure that describes an item. The caller is responsible for allocating this structure and setting its members.

dwState
[in] The state to set the item, which is a bitwise combination of list view item states. Specify zero to reset, or one to set, a state.

dwMask
[in] A mask of the valid bits of the state specified by the dwState parameter. Specify a bitwise combination (OR) of list view item states.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

For more information about the dwState parameter, see List View Item States.

For more information about the dwMask parameter, see the stateMask member of the LVITEM structure.

This method sends the LVM_SETITEMINDEXSTATE message, which is described in the Windows SDK.

`CListCtrl::SetItemPosition`

Moves an item to a specified position in a list view control.

BOOL SetItemPosition(
    int nItem,
    POINT pt);

Parameters

nItem
Index of the item whose position is to be set.

pt
A POINT structure specifying the new position, in view coordinates, of the item's upper-left corner.

Return Value

Nonzero if successful; otherwise zero.

Remarks

The control must be in icon or small icon view.

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

Example

See the example for CListCtrl::GetItemPosition.

`CListCtrl::SetItemState`

Changes the state of an item in a list view control.

BOOL SetItemState(
    int nItem,
    LVITEM* pItem);

BOOL SetItemState(
    int nItem,
    UINT nState,
    UINT nMask);

Parameters

nItem
Index of the item whose state is to be set. Pass -1 to apply the state change to all items.

pItem
Address of an LVITEM structure, as described in the Windows SDK. The structure's stateMask member specifies which state bits to change, and the structure's state member contains the new values for those bits. The other members are ignored.

nState
New values for the state bits. For a list of possible values, see CListCtrl::GetNextItem and the LVITEM state member.

nMask
Mask specifying which state bits to change. This value corresponds to the stateMask member of the LVITEM structure.

Return Value

Nonzero if successful; otherwise zero.

Remarks

An item's "state" is a value that specifies the item's availability, indicates user actions, or otherwise reflects the item's status. A list view control changes some state bits, such as when the user selects an item. An application might change other state bits to disable or hide the item, or to specify an overlay image or state image.

Example

See the example for CListCtrl::GetTopIndex.

`CListCtrl::SetItemText`

Changes the text of a list view item or subitem.

BOOL SetItemText(
    int nItem,
    int nSubItem,
    LPCTSTR lpszText);

Parameters

nItem
Index of the item whose text is to be set.

nSubItem
Index of the subitem, or zero to set the item label.

lpszText
Pointer to a string that contains the new item text.

Return Value

Nonzero if successful; otherwise zero.

Remarks

This method isn't intended for use with controls containing the LVS_OWNERDATA window style (in fact, this will cause an assertion in Debug builds). For more information about this list control style, see List-View Controls Overview.

Example

See the example for CListCtrl::InsertItem.

`CListCtrl::SetOutlineColor`

Sets the color of the border of a list-view control if the LVS_EX_BORDERSELECT extended window style is set.

COLORREF SetOutlineColor(COLORREF color);

Parameters

color
The new COLORREF structure containing the outline color.

Return Value

The previous COLORREF structure containing the outline color

Remarks

This member function emulates the functionality of the LVM_SETOUTLINECOLOR message, as described in the Windows SDK.

CListCtrl::SetSelectedColumn

Sets the selected column of the list view control.

LRESULT SetSelectedColumn(int iCol);

Parameters

iCol
The index of the column to be selected.

Return Value

The return value isn't used.

Remarks

This member function emulates the functionality of the LVM_SETSELECTEDCOLUMN message, as described in the Windows SDK.

`CListCtrl::SetSelectionMark`

Sets the selection mark of a list view control.

int SetSelectionMark(int iIndex);

Parameters

iIndex
The zero-based index of the first item in a multiple selection.

Return Value

The previous selection mark, or -1 if there was no selection mark.

Remarks

This member function implements the behavior of the Win32 macro, ListView_SetSelectionMark, as described in the Windows SDK.

Example

See the example for CListCtrl::GetSelectionMark.

`CListCtrl::SetTextBkColor`

Sets the background color of text in a list view control.

BOOL SetTextBkColor(COLORREF cr);

Parameters

cr
A COLORREF specifying the new text background color. For information, see COLORREF in the Windows SDK.

Return Value

Nonzero if successful; otherwise zero.

Example

// Use the 3D button face color for the background.
COLORREF crBkColor = ::GetSysColor(COLOR_3DFACE);
m_myListCtrl.SetTextBkColor(crBkColor);
ASSERT(m_myListCtrl.GetTextBkColor() == crBkColor);

`CListCtrl::SetTextColor`

Sets the text color of a list view control.

BOOL SetTextColor(COLORREF cr);

Parameters

cr
A COLORREF specifying the new text color. For information, see COLORREF in the Windows SDK.

Return Value

Nonzero if successful; otherwise zero.

Example

// Use the window text color for
// the item text of the list view control.
COLORREF crTextColor = ::GetSysColor(COLOR_WINDOWTEXT);
m_myListCtrl.SetTextColor(crTextColor);
ASSERT(m_myListCtrl.GetTextColor() == crTextColor);

`CListCtrl::SetTileInfo`

Sets the information for a tile of the list view control.

BOOL SetTileInfo(PLVTILEINFO pTileInfo);

Parameters

pTileInfo
A pointer to an LVTILEINFO structure containing the information to be set.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

This member function emulates the functionality of the LVM_SETTILEINFO message, as described in the Windows SDK.

`CListCtrl::SetTileViewInfo`

Sets information that a list view control uses in tile view.

BOOL SetTileViewInfo(PLVTILEVIEWINFO ptvi);

Parameters

ptvi
A pointer to an LVTILEVIEWINFO structure containing the information to set.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

This member function emulates the functionality of the LVM_SETTILEVIEWINFO message, as described in the Windows SDK.

`CListCtrl::SetToolTips`

Sets the tooltip control that the list view control will use to display tooltips.

CToolTipCtrl* SetToolTips(CToolTipCtrl* pWndTip);

Parameters

pWndTip
A pointer to a CToolTipCtrl object that the list control will use.

Return Value

A pointer to a CToolTipCtrl object containing the tooltip previously used by the control, or NULL if no tooltips were used previously.

Remarks

This member function implements the behavior of the Win32 message LVM_SETTOOLTIPS, as described in the Windows SDK.

To not use tooltips, indicate the LVS_NOTOOLTIPS style when you create the CListCtrl object.

`CListCtrl::SetView`

Sets the view of the list view control.

DWORD SetView(int iView);

Parameters

iView
The view to be selected.

Return Value

Returns 1 if successful, or -1 otherwise. For example, -1 is returned if the view is invalid.

Remarks

This member function emulates the functionality of the LVM_SETVIEW message, as described in the Windows SDK.

`CListCtrl::SetWorkAreas`

Sets the area where icons can be displayed in a list view control.

void SetWorkAreas(
    int nWorkAreas,
    LPRECT lpRect);

Parameters

nWorkAreas
The number of RECT structures (or CRect objects) in the array pointed to by lpRect.

lpRect
The address of an array of RECT structures (or CRect objects) that specify the new work areas of the list view control. These areas must be specified in client coordinates. If this parameter is NULL, the working area will be set to the client area of the control.

Remarks

This member function implements the behavior of the Win32 macro, ListView_SetWorkAreas, as described in the Windows SDK.

Example

// Remove all working areas.
m_myListCtrl.SetWorkAreas(0, NULL);

`CListCtrl::SortGroups`

Uses an application-defined comparison function to sort groups by ID within a list view control.

BOOL SortGroups(
    PFNLVGROUPCOMPARE _pfnGroupCompare,
    LPVOID _plv);

Parameters

_pfnGroupCompare
A pointer to the group comparison function.

_plv
A void pointer.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

This member function emulates the functionality of the LVM_SORTGROUPS message, as described in the Windows SDK.

`CListCtrl::SortItems`

Sorts list view items by using an application-defined comparison function.

BOOL SortItems(
    PFNLVCOMPARE pfnCompare,
    DWORD_PTR dwData);

Parameters

pfnCompare
[in] Address of the application-defined comparison function.

The sort operation calls the comparison function each time the relative order of two list items needs to be determined. The comparison function must be either a static member of a class or a stand-alone function that isn't a member of any class.

dwData
[in] Application-defined value that is passed to the comparison function.

Return Value

TRUE if the method successful; otherwise FALSE.

Remarks

This method changes the index of each item to reflect the new sequence.

The comparison function, pfnCompare, has the following form:

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

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 equal.

The lParam1 parameter is the 32-bit value (64-bit if you're compiling for x64) associated with the first item that is 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 as the dwData value.

This method sends the LVM_SORTITEMS message, which is described in the Windows SDK.

Example

The following is a simple comparison function that results in items being sorted by their lParam values.

// Sort items by associated lParam
int CALLBACK CListCtrlDlg::MyCompareProc(LPARAM lParam1, LPARAM lParam2,
    LPARAM lParamSort)
{
    UNREFERENCED_PARAMETER(lParamSort);
    return (int)(lParam1 - lParam2);
}

// Sort the items by passing in the comparison function.
void CListCtrlDlg::Sort()
{
    m_myListCtrl.SortItems(&CListCtrlDlg::MyCompareProc, 0);
}

`CListCtrl::SortItemsEx`

Sorts the items of the current list-view control by using an application-defined comparison function.

BOOL SortItemsEx(
    PFNLVCOMPARE pfnCompare,
    DWORD_PTR dwData);

Parameters

pfnCompare
[in] Address of the application-defined comparison function. The sort operation calls the comparison function each time the relative order of two list items needs to be determined. The comparison function must be either a static member of a class or a stand-alone function that isn't a member of any class.

dwData
[in] Application-defined value passed to the comparison function.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method changes the index of each item to reflect the new sequence.

The comparison function, pfnCompare, has the following form:

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

This message is like LVM_SORTITEMS, except for the type of information passed to the comparison function. In LVM_SORTITEMS, lParam1 and lParam2 are the values of the items to compare. In LVM_SORTITEMSEX, lParam1 is the current index of the first item to compare and lParam2 is the current index of the second item. You can send an LVM_GETITEMTEXT message to retrieve more information about an item.

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 equal.

Note

During the sorting process, the list-view contents are unstable. If the callback function sends any messages to the list-view control other than LVM_GETITEM, the results are unpredictable.

This method sends the LVM_SORTITEMSEX message, which is described in the Windows SDK.

Example

The first code example defines a variable, m_listCtrl, that is used to access the current list-view control. This variable is used in the next example.

public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;

The next code example demonstrates the SortItemEx method. In an earlier section of this code example, we created a list-view control that displays two columns titled "ClientID" and "Grade" in a report view. The following code example sorts the table by using the values in the "Grade" column.

// The ListCompareFunc() method is a global function used by SortItemEx().
int CALLBACK ListCompareFunc(
                             LPARAM lParam1,
                             LPARAM lParam2,
                             LPARAM lParamSort)
{
    CListCtrl* pListCtrl = (CListCtrl*) lParamSort;
    CString    strItem1 = pListCtrl->GetItemText(static_cast<int>(lParam1), 1);
    CString    strItem2 = pListCtrl->GetItemText(static_cast<int>(lParam2), 1)
    int x1 = _tstoi(strItem1.GetBuffer());
    int x2 = _tstoi(strItem2.GetBuffer());
    int result = 0;
    if ((x1 - x2) < 0)
        result = -1;
    else if ((x1 - x2) == 0)
        result = 0;
    else
        result = 1;

    return result;
}

void CCListCtrl_s2Dlg::OnBnClickedButton1()
{
    // SortItemsEx
    m_listCtrl.SortItemsEx( ListCompareFunc, (LPARAM)&m_listCtrl );
}

`CListCtrl::SubItemHitTest`

Determines which list view item, if any, is at a given position.

int SubItemHitTest(LPLVHITTESTINFO pInfo);

Parameters

pInfo
A pointer to the LVHITTESTINFO structure.

Return Value

The one-based index of the item, or subitem, being tested (if any), or -1 otherwise.

Remarks

This member function implements the behavior of the Win32 macro, ListView_SubItemHitTest, as described in the Windows SDK.

Example

void CListCtrlDlg::OnDblClk(NMHDR* pNMHDR, LRESULT* pResult)
{
    UNREFERENCED_PARAMETER(pResult);
    LPNMITEMACTIVATE pia = (LPNMITEMACTIVATE)pNMHDR;
    LVHITTESTINFO lvhti;

    // Clear the subitem text the user clicked on.
    lvhti.pt = pia->ptAction;
    m_myListCtrl.SubItemHitTest(&lvhti);

    if (lvhti.flags & LVHT_ONITEMLABEL)
    {
        m_myListCtrl.SetItemText(lvhti.iItem, lvhti.iSubItem, NULL);
    }
}

`CListCtrl::Update`

Forces the list view control to repaint the item specified by nItem.

BOOL Update(int nItem);

Parameters

nItem
Index of the item to be updated.

Return Value

Nonzero if successful; otherwise zero.

Remarks

This function also arranges the list view control if it has the LVS_AUTOARRANGE style.

Example

See the example for CListCtrl::GetSelectedCount.

Share via

CListCtrl Class

Syntax

Members

Public Constructors

Public Methods

Remarks

Views

Extended Styles

Items and Subitems

Image Lists

Inheritance Hierarchy

Requirements

CListCtrl::ApproximateViewRect

Parameters

Return Value

Remarks

CListCtrl::Arrange

Parameters

Return Value

Remarks

Example

CListCtrl::CancelEditLabel

Remarks

CListCtrl::CListCtrl

CListCtrl::Create

Parameters

Return Value

Remarks

Example

CListCtrl::CreateEx

Parameters

Return Value

Remarks

CListCtrl::CreateDragImage

Parameters

Return Value

Remarks

CListCtrl::DeleteAllItems

Return Value

Example

CListCtrl::DeleteColumn

Parameters

Return Value

Example

CListCtrl::DeleteItem

Parameters

Return Value

Example

CListCtrl::DrawItem

Parameters

Remarks

CListCtrl::EditLabel

Parameters

Return Value

Remarks

Example

CListCtrl::EnableGroupView

Parameters

Return Value

Remarks

CListCtrl::EnsureVisible

Parameters

Return Value

Remarks

Example

CListCtrl::FindItem

Parameters

Return Value

Remarks

Example

CListCtrl::GetBkColor

Return Value

Example

CListCtrl::GetBkImage

Parameters

Return Value

Remarks

Example

CListCtrl::GetCallbackMask

`CListCtrl` Class

`CListCtrl::ApproximateViewRect`

`CListCtrl::Arrange`

`CListCtrl::CancelEditLabel`

`CListCtrl::CListCtrl`

`CListCtrl::Create`

`CListCtrl::CreateEx`

`CListCtrl::CreateDragImage`

`CListCtrl::DeleteAllItems`

`CListCtrl::DeleteColumn`

`CListCtrl::DeleteItem`

`CListCtrl::DrawItem`

`CListCtrl::EditLabel`

`CListCtrl::EnableGroupView`

`CListCtrl::EnsureVisible`

`CListCtrl::FindItem`

`CListCtrl::GetBkColor`

`CListCtrl::GetBkImage`

`CListCtrl::GetCallbackMask`

`CListCtrl::GetCheck`

`CListCtrl::GetColumn`

`CListCtrl::GetColumnOrderArray`

`CListCtrl::GetColumnWidth`

`CListCtrl::GetCountPerPage`

`CListCtrl::GetEditControl`

`CListCtrl::GetEmptyText`

`CListCtrl::GetExtendedStyle`

`CListCtrl::GetFirstSelectedItemPosition`

`CListCtrl::GetFocusedGroup`

`CListCtrl::GetGroupCount`

`CListCtrl::GetGroupInfo`

`CListCtrl::GetGroupInfoByIndex`

`CListCtrl::GetGroupMetrics`

`CListCtrl::GetGroupRect`

`CListCtrl::GetGroupState`

`CListCtrl::GetHeaderCtrl`