Tree Control with Columns

• Download demo source - 204.68 KB
• Download source - 13.15 KB

Introduction

The CColumnTreeCtrl control can be used in MFC projects where a hybrid of tree and list is needed (see the picture above).

This code is based on Michal Mecinski's control described in Multi-Column Tree View article available on CodeGuru.com. This control has several improvements and bug fixes but the general idea is the same - use standard CTreeCtrl as multi-column tree body, and CHeaderCtrl as its header.

I've added owner-drawing code (thanks to VividTree - A Colorful and Picturesque Owner Drawn CTreeCtrl article from CodeProject.com), so you can control every aspect of CColumnTreeCtrl's appearance (tree buttons, lines, background and so on). If you want to use standard drawing code - just disable owner drawing.

You can do everything you do with standard CTreeCtrl and some things related to the CListCtrl. See Using the Code for more information.

Improvements

The control described in Michal Mecinski's article already has everything you need, but there were several bugs and several missing methods (from my point of view), so I've tried to improve Michal's control a little.

Here is the list of improvements:

• The original control is CView-derived. This control is CStatic-derived that allows to use it in dialog-based applications.
• This control has improved scroll bars. If you noticed, the original control’s scrollbars are not displayed correctly.
• This control supports column formatting while the original control does not.
• This control allows to define the first column’s minimum size (if you use owner-drawing you can ignore this, but if not, then you have to define the minimum width for the first column to avoid problems with appearance);
• This control has convenient methods for adding columns and setting column text while the original one does not. I tried not to overweight the control by adding many methods, just added couple of methods that are really needed.
• The original control used incorrect colors for tree’s selected items and ours uses default system colors.
• This control supports owner-drawing that allows you to control every aspect of its appearance.

Control Internals

The CColumnTreeCtrl control is implemented as container for the following child controls (see the figure below):

1. The main header (CHeaderCtrl). It contains the columns you add to the control.
2. Additional header (CHeaderCtrl). It is used to just fill empty space when the vertical scroll bar of child tree control (3) is displayed.
3. The custom child tree control (CTreeCtrl). This child control contains items you add, and it also provides the vertical scroller.
4. The horizontal scroll bar (CScrollBar). It is used to scroll the control in horizontal direction.

It was a very interesting idea proposed by Michal Mecinsky - to use standard CTreeCtrl to store items and subitems and to use custom drawing to display them properly. So, for example, the first item in the figure above is stored as a single string:

"3.5\" Floppy (A:)\tRemovable\tFAT12\t1.44Mb"

The tabulation symbol '\t' is used as subitems separator.

When WM_PAINT message is processed by CTreeCtrl, it doesn't draw items by itself, but sends custom draw notifications to the parent container, so it is possible to draw subitems as we wish.

Using the Code

Linking to Your MFC Project

You can use this control in Visual C++ 2003 and higher. I tried to compile it under Visual C++ 6.0, but it seems that it has too old SDK and doesn't support common controls library ver. 6 (distributed with IE6).

Follow these simple steps to add CColumnTreeCtrl to your MFC dialog:

1. Copy ColumnTreeCtrl.h and ColumnTreeCtrl.cpp file to your project folder. If you place these files to another place, you may encounter some problems with linking to resources, so don't do that.
2. Copy TREEBTNS.bmp file to your res folder. This bitmap will be used to draw buttons of tree control in owner-drawn mode.
3. Add TREEBTNS.bmp to project resources, set its name to IDB_TREEBTNS.
4. Add Static control to your dialog.
5. Change its id to, for example IDC_COLUMNTREE.
6. Right-click the static and choose "Add variable..." in context menu.
7. In the "Variable name" field, type "m_columnTree"
8. In the header file of your dialog, Add "#include "ColumnTreeCtrl.h"" line;
9. In the header file of your dialog, replace "CStatic m_columnTree;" to "CColumnTreeCtrl m_columnTree;";

Owner-Drawing Support

Owner-drawing is the technique when all drawing is performed by user's drawing procedure. Although it is rather difficult to paint the entire control, this gives you the opportunity to change its appearance as you wish. When owner-drawing is disabled, standard CTreeCtrl's drawing code plus additional custom drawing code is used.

What you can do without owner-drawing? The answer is everything. However, there are following benefits of owner-drawing:

• It allows to use background image.
• It allows not to set minimum width for the first column. In comparison, if you don't use it, you should set the minimum width for the first column by calling CColumnTreeCtrl::SetFirstColumnMinWidth(), otherwise you will have problems with control appearance.
• In theory, you can change every aspect of the control's appearance. Of course it means you have to understand and modify control's code for that purpose.

By default, owner-drawing is disabled. To enable it, uncomment this line in CColumnTreeCtrl.h:

//#define _OWNER_DRAWN_TREE  // comment this line if you want to use 
		           //standard drawing code

Adding and Deleting Columns

You should use these methods to add/remove columns:

// Inserts new column
int 
CColumnTreeCtrl::InsertColumn(
    int nCol,             // zero-based column index
    LPCTSTR lpszColumnHeading,     // column heading
    int nFormat=0,             // column formatting (as in CListViewCtrl)
    int nWidth=-1,             // column width
    int nSubItem=-1            // not used
    );

// Removes existing column
BOOL 
CColumnTreeCtrl::DeleteColumn(
    int nCol            // zero-based column index
    );

Example:

// insert two columns
m_columnTree.InsertColumn(0, _T("Name"), LVCFMT_LEFT, 180);
m_columnTree.InsertColumn(1, _T("Type"), LVCFMT_LEFT, 80);

// remove last column
m_columnTree.DeleteColumn(1); 

Adding/Removing Items

Example:

HTREEITEM hParent; // parent item

// add an item
HTREEITEM hItem = m_columnTree.GetTreeCtrl().InsertItem
			( _T("3.5\" Floppy (A:)"), hParent );

// remove 
m_columnTree.GetTreeCtrl().DeleteItem(hItem);

Retrieving and Setting Item Text

You should use CColumnTreeCtrl::GetItemText() and CColumnTreeCtrl::SetItemText() methods to get/set item or subitem text.

// gets item text
CString 
CColumnTreeCtrl::GetItemText(
    HTREEITEM hItem,     // item handle
    int nSubItem        // zero-based subitem index
    ); 
// sets item text
void 
CColumnTreeCtrl::SetItemText(
    HTREEITEM hItem,     // item handle
    int nSubItem,         // zero-based subitem index
    LPCTSTR lpszText    // pointer to text buffer
    );

Example:

// set text for the first and the second subitems
m_columnTree.SetItemText(hRoot, 1, _T("Removable"));
m_columnTree.SetItemText(hRoot, 2, _T("FAT12"));

Setting Minimum Width for the First Column

// sets the minimum available width for the first column
void 
CColumnTreeCtrl::SetFirstColumnMinWidth(
    UINT uMinWidth    // min. width
    );

Determining Which Item is Under the Mouse Cursor

You can use CColumnTreeCtrl::HitTest() method to determine which item is under the mouse cursor.

// CTVHITTESTINFO structure contains information used to determine the 
// location of a point relative to a CColumnTreeCtrl control. 
typedef struct _CTVHITTESTINFO { 
  POINT pt;   // Client coordinates of the point to test.
  UINT flags; // Standard TVHT -prefixed flags.
  HTREEITEM hItem; // Handle to the item that occupies the point.
  int iSubItem;    // Zero-based subitem index. 
} CTVHITTESTINFO;

// Call this function to determine the location of the specified point 
// relative to the client area of a CColumnTreeCtrl control.
HTREEITEM 
CColumnTreeCtrl::HitTest(
  CPoint pt, 
  UINT* pFlags
  ) const;
 
HTREEITEM 
CColumnTreeCtrl::HitTest(
  CTVHITTESTINFO* pHitTestInfo
  ) const;

Example:

// NM_RCLICK notification handler
void CMainDlg::OnRclickedColumntree(LPNMHDR pNMHDR, LRESULT* pResult)
{
  CPoint pt;
  ::GetCursorPos(&pt);

  m_columnTree.ScreenToClient(&pt);

  CTVHITTESTINFO htinfo;
  htinfo.pt = pt;
  HTREEITEM hItem = m_columnTree.HitTest(&htinfo);

  if(hItem)
  {
    CString szState;
    if(htinfo.flags&TVHT_ONITEMBUTTON)
    szState += _T("Clicked on item's button.");
   
    // ... check other flags

    CString szItemText = m_columnTree.GetItemText(hItem, htinfo.iSubItem);
    MessageBox(szState + _T(" Item text: ") + szItemText);
  }
}

Accessing Child CTreeCtrl and CHeaderCtrl

You can access child tree control and header control and call their methods as usual:

// returns reference to the child tree ctrl
CCustomTreeChildCtrl&
CColumnTreeCtrl::GetTreeCtrl();

// returns reference to the child header ctrl
CHeaderCtrl&
CColumnTreeCtrl::GetHeaderCtrl();

Example:

// modify style of child tree control to enable lines
m_columnTree.GetTreeCtrl().ModifyStyle(TVS_HASLINES, 0);

Setting Background Bitmap

If owner-drawing is enabled, you can specify what background bitmap to use. Standard LVBKIMAGE structure is used to store background bitmap parameters.

// gets background image
BOOL 
CCustomTreeChildCtrl::GetBkImage(
    LVBKIMAGE* plvbkImage    // structure describing image and its position
    ) const;

// sets background image
BOOL 
CCustomTreeChildCtrl::SetBkImage(
    LVBKIMAGE* plvbkImage    // structure describing image and its position
    ); 

Example:

LVBKIMAGE bk;
bk.xOffsetPercent = bk.yOffsetPercent = 70;
bk.hbm = LoadBitmap(AfxGetInstanceHandle(),MAKEINTRESOURCE(IDB_BKGND));
m_columnTree.GetTreeCtrl().SetBkImage(&bk);  

Processing Child Tree and Header Notifications

You can easily process notifications from the child tree and header controls in your dialog's message map, because all notifications are forwarded to the parent.

Example:

//.. fragment of the message map
ON_NOTIFY(NM_CLICK , IDC_COLUMNTREE, OnTreeClk)

//.. notify handler
void CMainDlg::OnTreeClk(NMHDR *pNMHDR, LRESULT *pResult)
{
    NMTREEVIEW& nm = *(LPNMTREEVIEW)pNMHDR;

    // which item was selected?
    HTREEITEM hItem = m_columnTree.GetTreeCtrl().GetSelectedItem();
    if(!hItem) return;

    // the rest of processing code..
    
}

History

• February, 18 2008 - v.1.0 submitted
• March, 24 2008 - v.1.1 submitted
  • Added CColumnTreeCtrl::HitTest() method

Known Issues

These issues were reported so far:

• There is a problem with tooltips for now, so TVS_NOTOOLTIPS style is enabled for child tree control. Do not disable this style, or invalid tip will be displayed.
• In the demo, when you check/uncheck some options that result in style modifications, control appearance may become incorrect. For example, vertical lines may become missing and so on. This is the problem in this demo, but this won't be a real problem in your project, because you usually won't change control's style on fly.
• Under Windows Vista, vertical lines are drawn non-uniformly. That is not a very serious problem.
• Horizontal scroll bar is sometimes placed incorrectly when resizing control.

Report a Bug

I hope this control will be useful, but if you find a bug, please let me know. You can post a message to the discussion thread below or email me: olegkrivtsov@mail.ru Please do not forget to specify how I can reproduce the incorrect behavior of control, describe what you were doing when incorrect behavior occurred, specify your Windows version and your current desktop theme.