|
CListView Class |
Description
A list-view control is a window that displays a collection of items. Each item consists of an icon and a label. List-view controls provide several ways to arrange and display items. For example, additional information about each item can be displayed in columns to the right of the icon and label.
CListView is the class responsible for creating a list-view control. It can be used as a control in a Dialog, or as the View window in a Frame, Docker, or MDI child.
Refer to the documentation that ships with the Microsoft Windows Software Development Kit for more information on the use of list view controls.
CListView Members
Construction
| CListView | CListView() const;Constructor for CListView. |
Attributes
| ApproximateViewRect | CSize ApproximateViewRect(CSize sz = CSize(-1, -1), int iCount = -1) const;Calculates the approximate width and height required to display a given number of items. |
| GetBkColor | COLORREF GetBkColor( ) const;Retrieves the background color of a list-view control. |
| GetBkImage | BOOL GetBkImage( LVBKIMAGE& lvbkImage ) const;Retrieves the background image in a list-view control. |
| GetCallbackMask | UINT GetCallbackMask( ) const;Retrieves the callback mask for a list-view control. |
| GetCheckState | BOOL GetCheckState( UINT nItem ) const;Determines if an item in a list-view control is selected. |
| GetColumn | BOOL GetColumn( int iCol, LVCOLUMN& Column ) const;Retrieves the attributes of a list-view control's column. |
| GetColumnOrderArray | BOOL GetColumnOrderArray( LPINT piArray, int iCount = -1 );Retrieves the current left-to-right order of columns in a list-view control. |
| GetColumnWidth | int GetColumnWidth( int iCol ) const;Retrieves the width of a column in report or list-view. |
| GetCountPerPage | int GetCountPerPage( ) const;Calculates the number of items that can fit vertically in the visible area of a list-view control when in list or report view. Only fully visible items are counted. |
| GetEditControl | HWND GetEditControl( ) const;Retrieves the handle to the edit control being used to edit a list-view item's text. |
| GetExtendedStyle | DWORD GetExtendedStyle( ) const;Retrieves the extended styles that are currently in use for a given list-view control. |
| GetHeader | HWND GetHeader( ) const;Retrieves the handle to the header control used by a list-view control. |
| GetHotCursor | HCURSOR GetHotCursor( );Retrieves the HCURSOR used when the pointer is over an item while hot tracking is enabled. |
| GetHotItem | int GetHotItem( ) const;Retrieves the index of the hot item. |
| GetHoverTime | DWORD GetHoverTime( ) const;Retrieves the amount of time that the mouse cursor must hover over an item before it is selected. |
| GetImageList | CImageList* GetImageList( int nImageType ) const;Retrieves the handle to an image list used for drawing list-view items. |
| GetItem | BOOL GetItem( LVITEM& lvItem ) const;Retrieves some or all of a list-view item's attributes. |
| GetItemCount | int GetItemCount( ) const;Retrieves the number of items in a list-view control. |
| GetItemData | DWORD_PTR GetItemData( int iItem ) const;Retrieves the application data from a list-view's item. |
| GetItemPosition | BOOL GetItemPosition( int iItem, CPoint& pt ) const;Retrieves the position of a list-view item. |
| GetItemRect | BOOL GetItemRect( int iItem, CRect& rc, UINT nCode ) const;Retrieves the bounding rectangle for all or part of an item in the current view. |
| GetItemState | UINT GetItemState( int iItem, UINT nMask ) const;Retrieves the state of a list-view item. |
| GetItemText | CString GetItemText( int iItem, int iSubItem, UINT nTextMax = 260 ) const;Retrieves the text of a list-view item or subitem. |
| GetNextItem | int GetNextItem( int iItem, int iFlags ) const;Searches for a list-view item that has the specified properties and bears the specified relationship to a specified item. |
| GetNumberOfWorkAreas | UINT GetNumberOfWorkAreas( ) const;Retrieves the number of working areas in a list-view control. |
| GetOrigin | BOOL GetOrigin( CPoint& pt ) const;Retrieves the current view origin for a list-view control. |
| GetSelectedCount | UINT GetSelectedCount( ) const;Determines the number of selected items in a list-view control. |
| GetSelectionMark | int GetSelectionMark( );Retrieves the selection mark from a list-view control. |
| GetStringWidth | int GetStringWidth( LPCTSTR pszString ) const;Determines the width of a specified string using the specified list-view control's current font. |
| GetSubItemRect | BOOL GetSubItemRect( int iItem, int iSubItem, int iCode, CRect& rc );Retrieves information about the rectangle that surrounds a subitem in a list-view control. This macro is intended to be used only on list-view controls that use the |
| GetTextBkColor | COLORREF GetTextBkColor( ) const;Retrieves the text background color of a list-view control. |
| GetTextColor | COLORREF GetTextColor( ) const;Retrieves the text color of a list-view control. |
| GetToolTips | CToolTip* GetToolTips( ) const;Retrieves the ToolTip control that the list-view control uses to display ToolTips. |
| GetTopIndex | int GetTopIndex( ) const;Retrieves the index of the topmost visible item when in list or report view. |
| GetViewRect | BOOL GetViewRect( CRect& rc ) const;Retrieves the bounding rectangle of all items in the list-view control. |
| GetWorkAreas | void GetWorkAreas( int iWorkAreas, LPRECT pRectArray ) const;Retrieves the working areas from a list-view control. |
| SetBkColor | BOOL SetBkColor( COLORREF clrBk );Sets the background color of a list-view control. |
| SetBkImage | BOOL SetBkImage( LVBKIMAGE& plvbkImage );Sets the background image in a list-view control. |
| SetCallbackMask | BOOL SetCallbackMask( UINT nMask );Changes the callback mask for a list-view control. |
| SetCheckState | void SetCheckState( int iItem, BOOL fCheck = TRUE );Used to select or deselect an item in a list-view control. |
| SetColumn | BOOL SetColumn( int iCol, const LVCOLUMN& pColumn );Sets the attributes of a list-view column. |
| SetColumnOrderArray | BOOL SetColumnOrderArray( int iCount, LPINT piArray );Sets the left-to-right order of columns in a list-view control. |
| SetColumnWidth | BOOL SetColumnWidth( int iCol, int cx );Used to change the width of a column in report view or the width of all columns in list-view mode. |
| SetExtendedStyle | DWORD SetExtendedStyle( DWORD dwNewStyle );Sets extended styles for list-view controls. |
| SetHotCursor | HCURSOR SetHotCursor( HCURSOR hCursor );Sets the HCURSOR that the list-view control uses when the pointer is over an item while hot tracking is enabled. To check whether or not hot tracking is enabled, call |
| SetHotItem | int SetHotItem( int nIndex );Sets the hot item in a list-view control. |
| SetHoverTime | DWORD SetHoverTime( DWORD dwHoverTime = (DWORD)-1 );Sets the amount of time that the mouse cursor must hover over an item before it is selected. |
| SetIconSpacing | CSize SetIconSpacing( int cx, int cy ) const; CSize SetIconSpacing( CSize sz ) const;Sets the spacing between icons in list-view controls set to the |
| SetImageList | CImageList* SetImageList( CImageList* pNew, int iImageListType ) const;Assigns an image list to a list-view control, and returns the old image list (if any). |
| SetItem | BOOL SetItem( LVITEM& pItem ) const; BOOL SetItem( int iItem, int iSubItem, UINT nMask, LPCTSTR pszText, int iImage,
UINT nState, UINT nStateMask, LPARAM lParam, int iIndent ) const;
Sets some or all of a list-view
item's attributes. |
| SetItemCount | void SetItemCount( int iCount ) const;Causes the list-view control to allocate memory for the specified number of items. |
| SetItemCountEx | void SetItemCountEx( int iCount, DWORD dwFlags = LVSICF_NOINVALIDATEALL ) const;Sets the virtual number of items in a |
| SetItemData | BOOL SetItemData( int iItem, DWORD_PTR dwData ) const;Sets the application data for a list-view's item. |
| SetItemPosition | BOOL SetItemPosition( int iItem, CPoint& pt ) const;Moves an item to a specified position in a list-view control (in icon or small icon view). |
| SetItemState | BOOL SetItemState( int iItem, LVITEM& Item ) const; void SetItemState( int iItem, UINT nState, UINT nMask ) const;Changes the state of an item in a list-view control. |
| SetItemText | void SetItemText( int iItem, int iSubItem, LPCTSTR pszText ) const;Changes the text of a list-view item or subitem. |
| SetSelectionMark | int SetSelectionMark( int iIndex ) const;Sets the selection mark in a list-view control. |
| SetTextBkColor | BOOL SetTextBkColor( COLORREF clrBkText ) const;Sets the background color of text in a list-view control. |
| SetTextColor | BOOL SetTextColor( COLORREF clrText ) const;Sets the text color of a list-view control. |
| SetToolTips | CToolTip* SetToolTips ( CToolTip* pToolTip ) const;Sets the ToolTip control that the list-view control will use to display ToolTips. |
| SetWorkAreas | void SetWorkAreas( int nWorkAreas, CRect& pRectArray ) const;Sets the working area within a list-view control. |
| SubItemHitTest | int SubItemHitTest( LVHITTESTINFO& htInfo ) const;Determines which list-view item or subitem is located at a given position. |
Operations
| Arrange | BOOL Arrange( UINT nCode ) const;Arranges items in icon view. |
| CreateDragImage | CImageList* CreateDragImage( int iItem, CPoint& pt ) const;Creates a drag image list for the specified item. |
| DeleteAllItems | BOOL DeleteAllItems( ) const;Removes all items from a list-view control. |
| DeleteColumn | BOOL DeleteColumn( int iCol ) const;Removes a column from a list-view control. |
| DeleteItem | BOOL DeleteItem( int iItem ) const;Removes an item from a list-view control. |
| EditLabel | HWnd EditLabel( int iItem ) const;Begins in-place editing of the specified list-view item's text. This implicitly selects and focuses the specified item. |
| EnsureVisible | BOOL EnsureVisible( int iItem, BOOL fPartialOK ) const;Ensures that a list-view item is either entirely or partially visible, scrolling the list-view control if necessary. |
| FindItem | int FindItem( LVFINDINFO& FindInfo, int iStart = -1 ) const;Searches for a list-view item with the specified characteristics. |
| HitTest | int HitTest( LVHITTESTINFO& HitTestInfo ) const; int HitTest( CPoint pt, UINT* pFlags = NULL ) const;Determines which list-view item, if any, is at a specified position. |
| InsertColumn | int InsertColumn( int iCol, const LVCOLUMN& pColumn ) const; int InsertColumn( int iCol, LPCTSTR pszColumnHeading, int iFormat = LVCFMT_LEFT,
int iWidth = -1, int iSubItem = -1 ) const;
Inserts a new column in a
list-view control. |
| InsertItem | int InsertItem( const LVITEM& pItem ) const; int InsertItem( int iItem, LPCTSTR pszText ) const; int InsertItem( int iItem, LPCTSTR pszText, int iImage ) const;Inserts a new item in a list-view control. |
| RedrawItems | BOOL RedrawItems( int iFirst, int iLast ) const;Forces a list-view control to redraw a range of items. |
| Scroll | BOOL Scroll( CSize sz ) const;Scrolls the content of a list-view control. |
| SortItems | BOOL SortItems( PFNLVCOMPARE pfnCompare, DWORD_PTR dwData ) const;Uses an application-defined comparison function to sort the items of a list-view control. The index of each item changes to reflect the new sequence. |
| Update | BOOL Update( int iItem ) const;Updates a list-view item. If the list-view control has the |
Overidables
| PreRegisterClass | virtual void PreRegisterClass(WNDCLASS &wc);
Set the window class parameters before the window is
created. |
Base class Members
For base class members, refer to the members of CWnd.
Remarks
Like all common controls, the list-view control requires a parent window. This parent window is often a dialog, but simple windows can also be the parent window for a list-view control.
Refer to the explorer sample to see a demonstration of the CListView and CTreeView classes.
Summary Information
| Header file | listview.h |
| Win32/64 support | Yes |
| WinCE support | Yes |
| Library required | Comctl32.lib |