CTreeOptionsCtrl v1.21

Introduction

Welcome to CTreeOptionsCtrl, a control which implements a tree options control similar to the advanced tab as seen on the "Internet Options" dialog in Internet Explorer 4 and later. In addition to check boxes and radio buttons, it also allows edit boxes and combo boxes to be included in the tree control, similar to the new printer property dialogs which are in Windows 2000. Included below is a snapshot showing the demo application and what the control looks like.

Sample Image

Contacting the Author

Features

Derived from the MFC class CTreeCtrl so if you have used this class before, then you should get up to speed using the CTreeOptionsCtrl pretty easily.
Code is UNICODE enabled and build configurations are provided.
Combo boxes and edit boxes that are created can be customized without affected the base code.
All code compiles cleanly at level 4.
Small footprint, total size amounts to just c. 900 lines of code.

Usage

To use the class in your code simply include TreeOptionsCtrl.cpp in your project and #include "TreeOptionsCtrl.h" in which ever of your modules needs to make calls to the class.
You will need to copy over the IDB_TREE_CTRL_OPTIONS bitmap which is used for the image list for the tree control. Hooking up the image list to the tree control is done automatically so you do not need to handle this. You are free to use to add your own bitmaps to the end of this to represent customized groups but you should leave the first 8 items intact in the image list. The code in CTreeOptionsCtrl assumes that the unchecked check item is at offset 0, the checked check item is at offset 1, the unchecked radio item is at offset 2 and the checked radio item is at offset 3. The bitmaps from offset 4 to 7 represent the disabled versions of the first 4 bitmaps.
Your code will need to include MFC either statically or dynamically.
To see the class in action, have a look at the usage of the code in the module appDlg.cpp.

History

V1.0 (3 April 1999)

Initial public release.

V1.01 (20 April 1999)

Minor Update to the bitmap which is used as the image list for the tree control.

V1.1 (21 April 1999)

Added full support for enabling / disabling of group, check box and radio button items (see the screen shot above).

V1.11 (5 October 1999)

Made class more self contained by internally managing the image list.

V1.2 (8 October 1999)

Added support for including combo boxes aswell as edit boxes into the edit control.
Added support for customizing the image list to use.

V1.21 (29 February 2000)

Removed a VC 6 level 4 warning.

API Reference

The API consists of the following class members and global functions:

CTreeOptionsCtrl::SetImageListToUse
CTreeOptionsCtrl::InsertGroup
CTreeOptionsCtrl::InsertCheckBox
CTreeOptionsCtrl::InsertRadioButton
CTreeOptionsCtrl::IsGroup
CTreeOptionsCtrl::IsCheckBox
CTreeOptionsCtrl::IsRadioButton
CTreeOptionsCtrl::SetCheckBox
CTreeOptionsCtrl::GetCheckBox
CTreeOptionsCtrl::GetRadioButton
CTreeOptionsCtrl::SetRadioButton
CTreeOptionsCtrl::SetGroupEnable
CTreeOptionsCtrl::SetCheckBoxEnable
CTreeOptionsCtrl::SetRadioButtonEnable
CTreeOptionsCtrl::GetRadioButtonEnable
CTreeOptionsCtrl::GetCheckBoxEnable
CTreeOptionsCtrl::AddComboBox
CTreeOptionsCtrl::AddEditBox
CTreeOptionsCtrl::GetComboText
CTreeOptionsCtrl::GetEditText
CTreeOptionsCtrl::SetComboText
CTreeOptionsCtrl::SetEditText
DDX_TreeCheck
DDX_TreeRadio
DDX_TreeEdit
DDX_TreeCombo

CTreeOptionsCtrl::SetImageListToUse

void SetImageListToUse(UINT nResourceID);

Parameters:

nResourceID -- The resource ID of the bitmap to use.

Remarks:
Allows you to customize what bitmap to use as the image list for the tree options control.

CTreeOptionsCtrl::InsertGroup

BOOL InsertGroup(LPCTSTR lpszItem, int nImage, HTREEITEM hParent = TVI_ROOT);

Return Value:
TRUE if the group item was successfully added otherwise FALSE.

Parameters:

lpszItem -- The text of the item to add.
nImage -- The zero based index of the icon in the tree controls image list to use for this group item.
hParent -- Handle of the parent where the item should be inserted.

Remarks:
Adds a group item to the tree control. A group item is the parent of either a collection of radio items or check items. In the sample app, the two items which are group items are "Accessibility (Example of check options)" and "When Searching (Example of radio options)". The first 8 icons of the image list associated with the tree options control are reserved and you should specify a nImage value greater than 7 when adding a group item. By default the function will add items at the root level of the tree control but you can add them at any depth using the hParent parameter. You can see this in the "Internet options" dialog which the control emulates.

CTreeOptionsCtrl::InsertCheckBox

BOOL InsertCheckBox(LPCTSTR lpszItem, HTREEITEM hParent, BOOL bCheck = TRUE);

Return Value:
TRUE if the check box item was successfully added otherwise FALSE.

Parameters:

lpszItem -- The text of the item to add.
hParent -- Handle of the parent where the item should be inserted.
bCheck -- The initial checked state of the check box. TRUE if the item is to be checked, FALSE to leave it unchecked.

Remarks:
Adds a check box item to the tree control. A check box item behaves the same as a normal check box. Using the space bar or left mouse button will toggle its state. The parent of the check box item must be a group item as added with InsertGroup().

CTreeOptionsCtrl::InsertRadioButton

BOOL InsertRadioButton(LPCTSTR lpszItem, HTREEITEM hParent, BOOL bCheck = TRUE);

Return Value:
TRUE if the radio button item was successfully added otherwise FALSE.

Parameters:

lpszItem -- The text of the item to add.
hParent -- Handle of the parent where the item should be inserted.
bCheck -- The initial checked state of the check box. TRUE if the item is to be checked, FALSE to leave it unchecked.

Remarks:
Adds a radio button item to the tree control. A radio button item behaves the same as a normal radio button i.e. when a radio button is checked all the other items in the same group are unchecked. Using the space bar or left mouse button will toggle its state. The parent of the radio button item must be a group item as added with InsertGroup().

CTreeOptionsCtrl::IsGroup

BOOL IsGroup(HTREEITEM hItem);

Return Value:
TRUE if the specified item is a group item otherwise FALSE.

Parameters:

hItem -- Handle of the item to check the type of.

Remarks:
Checks to see if the specified item is a group item i.e. an item which is the parent of a collection of radio button or check box items.

CTreeOptionsCtrl::IsCheckBox

BOOL IsCheckBox(HTREEITEM hItem);

Return Value:
TRUE if the specified item is a check box item otherwise FALSE.

Parameters:

hItem -- Handle of the item to check the type of.

Remarks:
Checks to see if the specified item is a check box item.

CTreeOptionsCtrl::IsRadioButton

BOOL IsRadioButton(HTREEITEM hItem);

Return Value:
TRUE if the specified item is a radio button item otherwise FALSE.

Parameters:

hItem -- Handle of the item to check the type of.

Remarks:
Checks to see if the specified item is a radio button item.

CTreeOptionsCtrl::SetCheckBox

BOOL SetCheckBox(HTREEITEM hItem, BOOL bCheck);

Return Value:
TRUE if the check state of the item was successfully changed otherwise FALSE.

Parameters:

hItem -- Handle of the item to change the checked state of.
bCheck -- The state of the check box to be set. TRUE if the item is to be checked, FALSE to uncheck the item.

Remarks:
Changes the checked state of a check box item.

CTreeOptionsCtrl::GetCheckBox

BOOL GetCheckBox(HTREEITEM hItem, BOOL& bCheck);

Return Value:
TRUE if the check state of the item was successfully retrieved otherwise FALSE.

Parameters:

hItem -- Handle of the item to retrieve the checked state of.
bCheck -- Upon successful return, this will contain the state of the check box. TRUE if the item is checked, FALSE if unchecked.

Remarks:
Retrieves the checked state of a check box item.

CTreeOptionsCtrl::SetRadioButton

BOOL SetRadioButton(HTREEITEM hParent, int nIndex);
BOOL SetRadioButton(HTREEITEM hItem);

Return Value:
TRUE if the check state of the specified radio button in the specified group was successfully set otherwise FALSE.

Parameters:

hParent -- Handle of the parent group item which contains the radio button items.
nIndex -- The index of the radio button in the group to select.
hItem -- The item in the radio button group to check.

Remarks:
Changes the checked state of the specified item in the specified radio button group. The item specified by the value nIndex or hItem is checked and all the other items in the group are unchecked.

CTreeOptionsCtrl::GetRadioButton

BOOL GetRadioButton(HTREEITEM hParent, int& nIndex, HTREEITEM& hCheckItem);
BOOL GetRadioButton(HTREEITEM hItem, BOOL& bCheck);

Return Value:
TRUE if the check state was successfully retrieved otherwise FALSE.

Parameters:

hParent -- Handle of the parent group item which contains the radio button items.
nIndex -- Upon successful return, this will contain the index of the radio button in the group which is checked.
hCheckItem -- Upon successful return, this will contain the handle of the radio button item which is checked.
hItem -- Handle of the radio button item to check the state of.
bCheck -- Upon successful return, this will contain the state of the radio button. TRUE if the item is checked, FALSE if unchecked.

Remarks:
Retrieves the checked state of a radio button item.

CTreeOptionsCtrl::SetGroupEnable

BOOL SetGroupEnable(HTREEITEM hItem, BOOL bEnable);

Return Value:
TRUE if the check state of the items in the group were successfully enabled / disabled otherwise FALSE.

Parameters:

hItem -- Handle of the group item to enable or disable.
bEnable -- TRUE if the items should be enabled, FALSE to disable the items.

Remarks:
Enables or disables all the items under a group item.

CTreeOptionsCtrl::SetCheckBoxEnable

BOOL SetCheckBoxEnable(HTREEITEM hItem, BOOL bEnable);

Return Value:
TRUE if the check state of the check box item was successfully enabled / disabled otherwise FALSE.

Parameters:

hItem -- Handle of the check box item to enable or disable.
bEnable -- TRUE if the item should be enabled, FALSE to disable the item.

Remarks:
Enables or disables the specified check box item.

CTreeOptionsCtrl::SetRadioButtonEnable

BOOL SetRadioButtonEnable(HTREEITEM hItem, BOOL bEnable);

Return Value:
TRUE if the check state of the radio button item was successfully enabled / disabled otherwise FALSE.

Parameters:

hItem -- Handle of the radio button item to enable or disable.
bEnable -- TRUE if the item should be enabled, FALSE to disable the item.

Remarks:
Enables or disables the specified radio button item.

CTreeOptionsCtrl::GetRadioButtonEnable

BOOL GetRadioButtonEnable(HTREEITEM hItem, BOOL& bEnable);

Return Value:
TRUE if the enabled state of the item was successfully retrieved otherwise FALSE.

Parameters:

hItem -- Handle of the item to retrieve the enabled state of.
bEnable -- Upon successful return, this will contain the enabled state of the radio button. TRUE if the item is enabled, FALSE if disabled.

Remarks:
Retrieves the enabled state of a radio button item.

CTreeOptionsCtrl::GetCheckBoxEnable

BOOL GetCheckBoxEnable(HTREEITEM hItem, BOOL& bEnable);

Return Value:
TRUE if the enabled state of the item was successfully retrieved otherwise FALSE.

Parameters:

hItem -- Handle of the item to retrieve the enabled state of.
bEnable -- Upon successful return, this will contain the enabled state of the check box. TRUE if the item is enabled, FALSE if disabled.

Remarks:
Retrieves the enabled state of a check box item.

CTreeOptionsCtrl::AddComboBox

BOOL AddComboBox(HTREEITEM hItem, CRuntimeClass* pRuntimeClass);

Return Value:
TRUE if the combo box item was successfully added otherwise FALSE.

Parameters:

hItem -- Handle of the item to add the combo box at.
pRuntimeClass -- The runtime class pointer on a class derived from CTreeOptionsCombo which is to be added to the tree options control.

Remarks:
Adds a combo box item to the tree control. The combo box by default provides a choice of multiple strings from which to pick. You are free to derive your own class from CTreeOptionsCombo to implement customized behavior.

CTreeOptionsCtrl::AddEditBox

BOOL AddEditBox(HTREEITEM hItem, CRuntimeClass* pRuntimeClass);

Return Value:
TRUE if the edit box item was successfully added otherwise FALSE.

Parameters:

hItem -- Handle of the item to add the combo box at.
pRuntimeClass -- The runtime class pointer on a class derived from CTreeOptionsEdit which is to be added to the tree options control.

Remarks:
Adds a edit box item to the tree control. The edit box by default allows any text to be set. You are free to derive your own class from CTreeOptionsCombo to implement customized behavior.

CTreeOptionsCtrl::GetComboText

CString GetComboText(HTREEITEM hItem);

Return Value:
The text associated with this combo box item.

Parameters:

hItem -- Handle of the item to retrieve the combo box text of.

Remarks:
Retrieves the combo text of a combo box item.

CTreeOptionsCtrl::GetEditText

CString GetEditText(HTREEITEM hItem);

Return Value:
The text associated with this edit box item.

Parameters:

hItem -- Handle of the item to retrieve the edit box text of.

Remarks:
Retrieves the edit text of a edit box item.

CTreeOptionsCtrl::SetComboText

BOOL SetComboText(HTREEITEM hItem, const CString& sComboText);

Return Value:
TRUE if the text of the item was successfully changed otherwise FALSE.

Parameters:

hItem -- Handle of the item to change the combo box text of.
sComboText -- The text to set in the combo box.

Remarks:
Changes the combo box text of a combo box item.

CTreeOptionsCtrl::SetEditText

BOOL SetEditText(HTREEITEM hItem, const CString& sEditText);

Return Value:
TRUE if the text of the item was successfully changed otherwise FALSE.

Parameters:

hItem -- Handle of the item to change the combo box text of.
sEditText -- The text to set in the edit box.

Remarks:
Changes the edit box text of an edit box item.

DDX_TreeCheck

void DDX_TreeCheck(CDataExchange* pDX, int nIDC, HTREEITEM hItem, BOOL& bCheck);

Parameters:

pDX -- A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.
nIDC -- The resource ID of the tree control associated with the control property.
hItem -- Handle of the check box item to get/set the state of.
bCheck -- A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged.

Remarks:
The DDX_TreeCheck() function manages the transfer of BOOL data between a check box item in the CTreeOptionsCtrl in a dialog box, form view, or control view object and a BOOL data member of the dialog box, form view, or control view object.

DDX_TreeRadio

void DDX_TreeRadio(CDataExchange* pDX, int nIDC, HTREEITEM hParent, int& nIndex);

Parameters:

pDX -- A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.
nIDC -- The resource ID of the tree control associated with the control property.
hParent -- Handle of the parent group item which contains the radio button items.
nIndex -- A reference to a member variable of the dialog box, form view, or control view object with which data is exchanged.

Remarks:
The DDX_TreeRadio() function manages the transfer of int data between a radio button group in the CTreeOptionsCtrl in a dialog box, form view, or control view object and an int data member of the dialog box, form view, or control view object.

DDX_TreeEdit

void DDX_TreeEdit(CDataExchange* pDX, int nIDC, HTREEITEM hItem, CString& sText);

Parameters:

pDX -- A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.
nIDC -- The resource ID of the tree control associated with the control property.
hItem -- Handle of the parent group item which contains the radio button items.
sText -- A reference to a CString which is the text to display or retrieve from the tree options control.

Remarks:
The DDX_TreeEdit() function manages the transfer of CString data between a edit box in the CTreeOptionsCtrl in a dialog box, form view, or control view object and an CString data member.

DDX_TreeCombo

void DDX_TreeCombo(CDataExchange* pDX, int nIDC, HTREEITEM hItem, CString& sText);

Parameters:

pDX -- A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.
nIDC -- The resource ID of the tree control associated with the control property.
hItem -- Handle of the parent group item which contains the radio button items.
sText -- A reference to a CString which is the text to display or retrieve from the tree options control.

Remarks:
The DDX_TreeCombo() function manages the transfer of CString data between a combo box in the CTreeOptionsCtrl in a dialog box, form view, or control view object and an CString data member.

Planned Enhancements

If you have any other suggested improvements, please let me know so that I can incorporate them into the next release.

Contacting the Author

PJ Naughter
Email: pjn@indigo.ie
Web: http://www.naughter.com
29 February 2000

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here