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
DWORDitems. 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
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_ALIGNLEFTAligns items along the left edge of the window.LVA_ALIGNTOPAligns items along the top edge of the window.LVA_DEFAULTAligns items according to the list view's current alignment styles (the default value).LVA_SNAPTOGRIDSnaps 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_NORMALImage list with large icons.LVSIL_SMALLImage list with small icons.LVSIL_STATEImage 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_BOUNDSReturns the bounding rectangle of the entire item, including the icon and label.LVIR_ICONReturns the bounding rectangle of the icon or small icon.LVIR_LABELReturns the bounding rectangle of the 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_ABOVESearches for an item that is above the specified item.LVNI_ALLSearches for a subsequent item by index (the default value).LVNI_BELOWSearches for an item that is below the specified item.LVNI_TOLEFTSearches for an item to the left of the specified item.LVNI_TORIGHTSearches 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_DROPHILITEDThe item has theLVIS_DROPHILITEDstate flag set.LVNI_FOCUSEDThe item has theLVIS_FOCUSEDstate flag set.LVNI_SELECTEDThe item has theLVIS_SELECTEDstate 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_BOUNDSReturns the bounding rectangle of the entire item, including the icon and label.LVIR_ICONReturns the bounding rectangle of the icon or small icon.LVIR_LABELReturns the bounding rectangle of the entire item, including the icon and label. This is identical toLVIR_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_NORMALImage list with large icons.LVSIL_SMALLImage list with small icons.LVSIL_STATEImage 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_TEXTThe pszText member or thelpszItemparameter is the address of a null-terminated string; the cchTextMax member is ignored.LVIF_STATEThe stateMask member ornStateMaskparameter specifies which item states to change and the state member ornStateparameter 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