MFC Extension Classes CListCtrlEx and CListViewEx

The CListCtrlEx and CListViewEx classes augment their base classes CListCtrl and CListView by implementing the following features:


  • The background of the sorted column can be displayed in a different color (like the detailed view of Windows XP Explorer).

  • The header of the sorted column can display an arrow that indicates the sort direction (like the detailed view of Windows XP Explorer).

  • You can give the user the opportunity to hide or redisplay selected columns by just clicking on the header control with the right mouse button (see picture below).

  • You can hide or redisplay a selected column entirely.

  • In contrast to the original list view control, the first column can have the LVCFMT_CENTER or LVCFMT_RIGHT style, too. For this feature, the list view control must have the LVS_OWNERDRAWFIXED style.

  • The label attributes state icon, small icon, and selection can always be shown in the leftmost column, independent of the order of the columns. For this feature, the listview control must have the LVS_OWNERDRAWFIXED style.

  • You can supply tooltips not only for the whole item, but also for the small icon, the state icon, and each subitem label.

  • The extended styles LVS_EX_CHECKBOXES, LVS_EX_ONECLICKACTIVATE, LVS_EX_SUBITEMIMAGES, LVS_EX_TWOCLICKACTIVATE, and LVS_EX_UNDERLINEHOT will be supported even if the list view control has the LVS_OWNERDRAWFIXED style.

  • If the LVS_EX_CHECKBOXES style has been applied and a selected item will be checked/unchecked, all other selected items will be checked/unchecked, too.

  • If the LVS_EX_LABELTIP style has been applied, not only the partially hidden text of the item label will be unfolded but also the partially hidden text of each subitem label.

    Note: The LVS_EX_LABELTIP style will be supported under all operating systems.

  • Tooltips and expanded labels can be displayed simultaneously.

  • The current state of the list view control (column widths, column order, hidden columns, and sort column and direction) can be saved and restored.

When CListCtrlEx and CListViewEx use the LVS_OWNERDRAWFIXED style for themselves, you can influence the drawing of the subitems nevertheless. To draw each subitem, CListCtrlEx and CListViewEx will call a virtual member function that you can overwrite.

To use all features mentioned above, the listview control must have the LVS_REPORT style.

CListCtrlEx and CListViewEx class members:


























Public member functions:
void ColorSortColumn(BOOL bEnable = TRUE) Turns the coloring of the sorted column on or off. The color used is the same as used by Windows XP Explorer.
virtual void DrawSmallIcon(CDC* pDC, LVITEM* pItem, LPRECT pRect) Called by CListCtrlEx or CListViewEx when the small icon of an owner-draw list view control is to be redrawn. pDC points to the current device context. pItem points to an LVITEM structure that contains the item’s attributes. pRect points to a RECT structure containing the rectangle bounding the small icon.
virtual void DrawStateIcon(CDC* pDC, LVITEM* pItem, LPRECT pRect) Called by CListCtrlEx or CListViewEx when the state icon of an owner-draw list view control is to be redrawn. pDC points to the current device context. pItem points to an LVITEM structure that contains the item’s attributes. pRect points to a RECT structure containing the rectangle bounding the state icon.
virtual void DrawSubItemText(CDC* pDC, LVITEM* pItem, LVCOLUMN* pColumn, LPRECT pRect) Called by CListCtrlEx or CListViewEx when the label of a subitem of an owner-draw list view control is to be redrawn. pDC points to the current device context. pItem points to an LVITEM structure that contains the item’s attributes. pColumn points to an LVCOLUMN structure that contains the column’s attributes. pRect points to a RECT structure containing the rectangle bounding the subitem’s label.
void EnableColumn(int nColumn, BOOL bEnableIt = TRUE) Hides or redisplays the column given by nColumn entirely. Hiding of only the first column is allowed, if the list view control is owner-drawn.
A column hidden in this way cannot be redisplayed by the user via the context menu or by calling the member function ShowColumn.
void EnableColumnSeparators(BOOL bEnable = TRUE) Shows or hides separator lines between the columns.
void EnableColumnHiding(int nColumn, BOOL bEnable = TRUE) Allows or disallows interactive hiding or redisplaying of the column given by nColumn. Hiding of the the first column is allowed only if the list view control is owner-drawn.
void EnableExplorerStyle() Causes the list view control to use the visual style of Windows Vista Explorer. If you call this member function under another operating system than Windows Vista, nothing will be done.
Attention: Once turned on, the explorer style cannot be turned off.
void EnableSortIcon(BOOL bEnable = TRUE) Turns on or off the arrow symbol that indicates the sort direction in the header of the sorted column.
void EnableSubItemTips(BOOL bEnable = TRUE) Enables distinct tooltips for the small icon, the state icon, and each subitem label. bEnable specifies whether subitem tooltips are enabled or disabled. TRUE enables them; FALSE disables them.
int GetColumnCount() Returns the number of columns in the list view control.
POSITION GetFirstCheckedItemPosition() const Gets the position of the first checked item in the list view control. Returns a POSITION value that can be used for iteration or object pointer retrieval; 0 if no items are selected.
int GetNextCheckedItem(POSITION& pos) const Returns the index of the checked list item identified by pos, and then updates pos to the POSITION of the next checked item. You can use GetNextCheckedItem in a forward iteration loop if you establish the initial position with a call to GetFirstCheckedItemPosition.
You must ensure that your POSITION value is valid.
int GetSortColumn() Returns the index+1 of the sort column in the list view control. A negative return value indicates a descending sort order. For example: The return value -2 means that the column with index 1 is sorted in descending order.
BOOL GetState(LPBYTE* ppState, LPUINT pnStateLen) const Saves the state of the list view control into a buffer pointed by contents of the pointer ppState. pnStateLen points to an UINT that will receive the size of the data (in bytes). Returns TRUE if successful; otherwise, FALSE.

Note: GetState allocates a buffer and returns its address in *ppState. The caller is responsible for freeing the buffer by using delete[].
virtual const CString GetToolTip(int nItem) Called by CListCtrlEx or CListViewEx when the tooltip for the item given by nItem is to be displayed. The default implementation returns an empty string and no tooltip will be displayed.
Note: You must apply the style LVS_EX_INFOTIP to enable the display of tooltips.
virtual const CString GetToolTip(int nItem, int nSubItem, UINT nFlags, BOOL& bAsLabel) Called by CListCtrlEx or CListViewEx when the tooltip for the subitem given by nItem and nSubItem is to be displayed. nFlags receives information about the position of the mouse cursor over the subitem:


LVHT_NOWHERE
The position is inside the list view control’s client window, but it is not over a list view item.
LVHT_ONITEMICON
The position over a list view subitem’s icon.
LVHT_ONITEMLABEL
The position over a list view subitem’s text.
LVHT_ONSTATEICON
The position over the state image of a list view item.

bAsLabel controls whether the tooltip will be displayed in the default format below the cursor (FALSE) or as an unfolded label over the text of the corresponding subitem (TRUE). The default value of bAsLabel is FALSE.
The default implementation of GetToolTip returns an empty string and no tooltip will be displayed.
Note: You must apply the style LVS_EX_INFOTIP to enable the display of tooltips.

BOOL IsColumnEnabled(int nColumn) const Returns TRUE if the display of the column given by nColumn is enabled, or FALSE otherwise.
virtual BOOL IsColumnWidthSufficient(int nColumn, LPCTSTR pszText) Called by CListCtrlEx or CListViewEx to decide whether the text pointed by pszText fits in the column nColumn. Returns TRUE if the column is wide enough, or FALSE otherwise.
BOOL KeepLabelLeft(BOOL bKeepLeft = TRUE) Draws the small icon and the state icon in the leftmost column regardless of the column ordering if bKeepLeft is TRUE. Returns FALSE if the list view control doesn’t have the style LVS_OWNERDRAWFIXED; otherwise, TRUE.
BOOL RestoreState(LPCTSTR pszSection, LPCTSTR pszEntry) Restores the state of the list view control last saved with SaveSettings. lpszSection points to a null-terminated string that specifies the section containing the entry. lpszEntry points to a null-terminated string that contains the entry with the state to be restored. This value must not be 0. Returns TRUE if the state could be restored successfully; otherwise, FALSE.
BOOL SaveState(LPCTSTR pszSection, LPCTSTR pszEntry) const Saves the state of the list view control (column widths, column order, hidden columns, and sort column and direction) into the specified section of the application’s Registry or .INI file. lpszSection points to a null-terminated string that specifies the section containing the entry. If the section does not exist, it is created. The name of the section is case independent; the string may be any combination of uppercase and lowercase letters. lpszEntry points to a null-terminated string that contains the entry into which the state is to be saved. If the entry does not exist in the specified section, it is created. Returns TRUE if the state could be saved successfully; otherwise, FALSE.
BOOL SetState(LPBYTE pState, UINT nStateLen) Restores the state of the list view control from the buffer pointed to by pState. nStateLen contains the length of the buffer in bytes. Returns TRUE if successful; otherwise, FALSE.
void ShowColumn(int nColumn, BOOL bShowIt = true) Redisplays or hides the column given by nColumn.

History

Date Posted: March 10, 2004

Date First Updated: July 2, 2004


  • Support for the extended style LVS_EX_SUBITEMIMAGES has been implemented.

  • A sample program showing the use of the CListViewEx class has been added.

Date Second Updated: November 29, 2004


  • The ability to hide selected columns entirely has been added.

  • Subitem specific tooltips have been added.

  • Extended support for the extended style LVS_EX_LABELTIP has been added.

  • Support for Microsoft Visual C++ 6 has been dropped.

  • The Windows 95 and Windows NT 4.0 operating systems will still be supported, but the implementation has not been tested under them.

Date Third Updated: February 8, 2006


  • The code for displaying tooltips and expanded labels has been rewritten. Now, a tooltip and an expanded label of the same item can be displayed together.
  • Support for the member function SetBkImage has been added.

  • Project files for Microsoft Visual C++ 2005 have been added.

Date Fourth Updated: February 20, 2006


  • Several bugs concerning column hiding and label unfolding have been fixed.

Date Fifth Updated: August 15, 2006


  • Support for the style LVS_EDITLABELS has been added.

  • Flickering during clicking on an expanded label has been eliminated.

Date Sixth Updated: January 16, 2008


  • Column separators have been added.

  • Support for Windows Vista explorer style has been added.

  • Project files for Microsoft Visual C++ 2008 have been added.

  • The Windows 98 and Windows Me operating systems will still be supported, but the implementation has not been tested under them.

Date Seventh Updated: October 11, 2010


  • Some minor bugs have been fixed.

  • Adaptions to Windows 7 have been made.

  • Project files for Microsoft Visual C++ 2010 have been added.

  • Support for Microsoft Visual C++ 2003 and 2005 has been dropped.

  • The Windows 2000 operating system will still be supported, but the implementation has not been tested under it.

More by Author

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Must Read