The Ultimate Toolbox Option Tree Control

• Download demo executable - 140.2 KB

• Download the Ultimate Toolbox source code - 3 MB
• Download the Ultimate Toolbox sample projects - 5.4 MB
• Download the Ultimate Toolbox documentation in compiled HTML help (CHM) format - 4.9 MB

Visit the Ultimate Toolbox main page for an overview and configuration guide to the Ultimate Toolbox library.

Source code and project files for this sample can be found in the samples\gui\OptionTree directory of the sample projects download.

Overview

The COXOptionTreeControl is a CTreeCtrl derived class that allows you to use check boxes and radio buttons as tree items. The tree control functionality allows you to organize them in groups, which provides a compact way of displaying and navigating through a big number of options that can be represented using check boxes or radio buttons.

Using the Class

In most cases, the options in the tree control should be organized in some logical way. We associate a tree control branch with any of such a group of options and call them "control groups". Please note that the functionality of the tree control allows you to use multiple levels of dependency between groups and subgroups. To add new control groups in the tree control, call the AddControlGroup function:

HTREEITEM AddControlGroup(LPCTSTR pszText, HTREEITEM hParent=NULL, 
    BOOL bExpanded=TRUE, int nImageIndex=-1, int nSelectedImageIndex=-1, 
    HTREEITEM hInsertAfter=TVI_LAST)

Using this function, you may create any control group. This function returns a handle to the tree item that was created to display the control group title. You can use this value to add check boxes, radio buttons, or other control groups.

Call AddCheckBox to add a new check box item in the tree:

HTREEITEM AddCheckBox(UINT uID, LPCTSTR pszText, HTREEITEM hParent, 
    int nCheck=OTITEM_UNCHECKED, HTREEITEM hInsertAfter=TVI_LAST)

Call the AddRadioButton method to add a new radio button item in the tree:

HTREEITEM AddRadioButton(UINT uID, LPCTSTR pszText, HTREEITEM hParent, 
    int nCheck=OTITEM_UNCHECKED, HTREEITEM hInsertAfter=TVI_LAST)

Note that both of these functions require you to specify a unique ID of the new option control. This way, any check box or radio button can be uniquely identified throughout the tree control. In order to retrieve the ID of an option control that is specified by its handle to the tree item, you can call GetItemFromID:

HTREEITEM GetItemFromID(UINT uID) const

And if you need to get the handle of a tree item which corresponds to the given ID, you can call GetIDFromItem:

UINT GetIDFromItem(HTREEITEM hItemFrom) const

Using the first three functions, you can easily populate the option tree control. You also can use all standard CTreeCtrl functions that are used in order to populate a tree control with items.

One specific rule that applies to the way a COXOptionTreeCtrl must be used, which is different from the standard approach, needs special mention. You must not explicitly change the image list associated with the tree. The control uses its own image list internally in order to display the check box and radio button images. So what if you want to display some images for control group items? The AddControlGroup() function allows you to specify the image indexes for normal and selected states but these indexes must be returned by the AddImage function which adds a new image to the internal image list:

int AddImage(UINT nImageResourceID, COLORREF clrMask=RGB(192,192,192), 
    UINT nHighContrastImageResourceID=0, 
    COLORREF clrHighContrastMask=RGB(192,192,192))

int AddImage(LPCTSTR lpszImageResourceID, COLORREF clrMask=RGB(192,192,192), 
    LPCTSTR lpszHighContrastImageResourceID=NULL, 
    COLORREF clrHighContrastMask=RGB(192,192,192))

Using this function, you can add as many images as you want.

Although it is not supposed to be modified outside, a direct access to the internal image list is provided. You may retrieve a pointer to it using GetImageList:

CImageList* GetImageList()

One of the possible uses of the image list would be replacing of the images that are used to display check boxes and radio buttons. At this moment, the following images are predefined:

After the control is populated and displayed, a user can expand and collapse control groups and change the state of option items by left clicking the mouse or pressing down the SPACE key.

Whenever the state of an option item is changed, the following notification will be send in the form of a WM_NOTIFY message:

• OTN_OPTIONCHANGED

If you handle the notification, you have to cast the NMHDR* object to a NMOPTIONTREE* object.

The NMOPTIONTREE structure provides info about the item, which state has been changed, the old state, and the new state of the item. The NMOPTIONTREE structure is declared as follows:

typedef struct _tagNMOPTIONTREE
{    
    // standard header

    NMHDR hdr;
    // handle to the tree item (check box or radio button, which state 

    // has been changed)

    HTREEITEM hItem;
    // item ID

    UINT uItemID;
    // old item state: OTITEM_UNCHECKED or OTITEM_CHECKED

    int nOldCheck;
    // new item state: OTITEM_UNCHECKED or OTITEM_CHECKED

    int nNewCheck;
} NMOPTIONTREE, * LPNMOPTIONTREE;

The state of any option item can be programmatically retrieved and changed using the following set of functions:

• SetCheck();
• GetCheck();
• GetCheckedRadioButton();
• IsCheckBox();
• IsRadioButton();

And, finally, the functionality for the option settings to be saved to and loaded from the registry is also provided. We can use these two functions to do that:

• SaveState();
• LoadState();

See the Graphical User Interface | Tree Controls section of the compiled HTML help file for a full COXOptionTreeCtrl class reference.

History

Initial CodeProject release August 2007.