CListCtrl Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CListCtrl Class.

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

Also see:

  • Knowledge Base article Q250614: HOWTO: Sort Items in a CListCtrl in Report View

  • Knowledge Base article Q200054: PRB: OnTimer() Is Not Called Repeatedly for a List Control

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, [Using CListCtrl: Adding Items to the Control](../Topic/CListCtrl%20Class.md#not_found.md#adding_items_to_the_control, and [using clistctrl_ scrolling, arranging, sorting, and finding in list controls]--brokenlink--(../topic/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 is destroyed; however, the developer can customize this behavior by destroying each image list when it is 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 are not specified, the framework uses the current width or height values of the control.

iCount
Number of items to be displayed in the control. If this parameter is -1, the framework uses 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 topic 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 is not 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 topic 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 is 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

Parameter Description
[in] iIndex Zero-based index of a group.
[out] pGroup 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 following 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; 

Example

The following 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

Parameter Description
[in] iGroupId Specifies a group.
[in, out] lpRect Pointer to a RECT structure. If this method is successful, the structure receives the rectangle coordinates of the group that is specified by iGroupId.
[in] iCoords 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 following 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; 

Example

The following 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

Parameter Description
[in] iGroupId Zero-based index of a group.
[in] dwMask 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 is 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 lvim) const;  

Parameters

lvim
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 does not 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 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 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

Parameter Description
[in] pItemIndex 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.
[in] iColumn Zero-based index of a column in the control.
[in] rectType 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.
[out] pRect 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 following 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; 

Example

The following code example demonstrates the GetGroupRect method. Prior to 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

Parameter Description
[in] fSmall View for which to retrieve the item spacing. Specify true for small icon view, or false for icon view.
[out] pnHorzSpacing Contains the horizontal spacing between items.
[out] pnVertSpacing 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 does not 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

Parameter Description
[in, out] pItemIndex 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.
[in] nFlags 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 is 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 is 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 pti) const;  

Parameters

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

Return Value

The return value is not 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 is not 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 prc) const;  

Parameters

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

prc
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 is not 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 is 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 is not 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. See the Windows SDK topics LVITEM Structure for more information and List-View Item States for a list of valid flags.

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

lParam
A 32-bit application-specific value 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, refer to 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 lvim) const;  

Parameters

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

lvim
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

Parameter Description
[in] index 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

Parameter Description
[in] id 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.

Note that 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

Parameter Description
[in] index 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.

Note that 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 following 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; 

Example

The following 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 is not 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

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

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

Remarks

Note

This method currently is not 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 are not actually 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 hbm,  
    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.

hbm
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 is 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 is 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 is 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 lvim);

Parameters

lvim
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 does not equal the actual size of the structure, or when an insertion point does not 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 application-specific value to be associated 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.

Remarks

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 will not repaint unless affected items are currently in view. This is the default value.

  • LVSICF_NOSCROLL The list view control will not 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 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 to be associated 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

Parameter Description
[in] pItemIndex Pointer to an LVITEMINDEX structure that describes an item. The caller is responsible for allocating this structure and setting its members.
[in] dwState 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.
[in] dwMask 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.

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 is not 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 is not 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 pti);

Parameters

pti
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

[in] pfnCompare
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 is not a member of any class.

[in] dwData
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 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

Parameter Description
[in] pfnCompare 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 is not a member of any class.
[in] dwData 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 following 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; 

Example

The following 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.

See Also

MFC Sample ROWLIST
CWnd Class
Hierarchy Chart
CImageList Class