CTreeOptionsCtrl v1.21

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. 

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 (2 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.

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.

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.

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.

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.

bCheck 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::GetCheckBoxButtonEnable

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.

bCheck 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 edit 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 box 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 edit box text of.

sEditText The text to set in the edit box.

Remarks

Changes the edit box text of a edit box item.

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.

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.

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.

hParent 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.

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.

hParent 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://indigo.ie/~pjn
29 February 2000