Click here to Skip to main content
15,171,851 members
Articles / Desktop Programming / MFC
Posted 7 May 2002


317 bookmarked


Rate me:
Please Sign up or sign in to vote.
4.95/5 (103 votes)
19 Sep 20025 min read
An article on an easy and neat way to include options, preferences, or settings into your applications


What's New with 2.0

The long awaited 2.0 version is here. Good news is you get new features, new options, new items, and new bugs. Bad news is, a lot has changed so you may need to change around your current code to implement the new version. (Thanks to Tom and Irfan for there fixes for bugs that haunted me at night when the lights are off. They deserve their names in bold.)



Below are some of the many features that COptionTree has.

  • Static controls.
  • Edit controls.
  • Combo box controls.
  • Check box controls.
  • Radio controls.
  • Spinner controls.
  • Color controls.
  • Date and time controls.
  • Image controls.
  • Font controls.
  • Files and folders controls.
  • IP Address controls..
  • Hyperlink controls.
  • Automatic column resize limit.
  • Easy customized options for different GUI style.
  • Easy customized options for each control item.
  • And more...


You have two options for using COptionTree, you can use it in static form or as a DLL.

Add The following files to your project:

// DLL
/COptionTreeDemo/COptionTree DLL/DLL.h

// Static
/COptionTreeDemo/COptionTree DLL/*.*
/COptionTreeDemo/COptionTree DLL/res/*.*

Creating the control:

#include "OptionTree.h"

// Declare variables
CRect rcClient;
DWORD dwStyle, dwOptions;

// Get the clients rectangle

// Setup the window style

// Setup the tree options

// Create tree options
if (m_otTree.Create(dwStyle, rcClient, this, dwOptions,
    TRACE0("Failed to create options control.\r\n");
    return FALSE;

// Insert tree items
// ...
Available Tree Options
OT_OPTIONS_SHOWINFOWINDOW        // Show information window
OT_OPTIONS_NOTIFY            // Send parent notifications        
OT_OPTIONS_DEFINFOTEXTNOSEL        // Show default info text for no 
                                     // selected item, otherwise blank
OT_OPTIONS_SHADEEXPANDCOLUMN    // Shade the expand column
OT_OPTIONS_SHADEROOTITEMS        // Shade the root items
Validating Tree Items
// Use COptionTreeItem::GetItemType() to get item type. Different item 
// definitions include.


API Reference

This is a list of the most common used functions of COptionTree's classes. There many more functions than this, but these give the average user enough to use the control.

BOOL COptionTree::Create(DWORD dwStyle, RECT rcRect, CWnd* pParentWnd, 
                         DWORD dwTreeOptions, UINT nID)
//Create the tree control and window.

void COptionTree::DeleteAllItems()
//Delete all items in the tree.

void COptionTree::DeleteItem(COptionTreeItem *otiItem)
//Delete an item from the tree.

void COptionTree::DisableInput(BOOL bDisable)
//Disable user input, use this instead of EnableWindow

COptionTreeItem * COptionTree::InsertItem(COptionTreeItem *otiItem, 
                                          COptionTreeItem *otiParent)
//Insert a new item into the tree. If otiParent is 
//NULL then the item becomes the root. InsertItem returns a pointer
//to the item.

COptionTreeItem is a class used to handle items in a tree. Each options/preference is a different item. Depending on what type of item control is used, these functions are acquired by all control types.
void COptionTreeItem::SetLabelText(CString strLabel)
//Set the label text of an item.

CString COptionTreeItem::GetLabelText()
//Get the label text.

void COptionTreeItem::SetInfoText(CString strText)
//Set the information text that is displayed in the information window. 
//This can give the user a description of the item/option, and what it does.

CString COptionTreeItem::GetInfoText()
//Get the information text that is displayed in the information window. 

void COptionTreeItem::ReadOnly(BOOL bReadOnly)
//Set item to read only state.

BOOL COptionTreeItem::IsReadOnly()
//Returns TRUE if the item is read only.

void COptionTreeItem::OnSelect()
//Select the item.

BOOL COptionTreeItem::IsReadOnly()
//Returns TRUE if the item is selected.

COptionTreeItemStatic is a simple static control. The following are custom functions used to set the edit the static text.
void COptionTreeItemStatic::SetStaticText(CString strStaticText)
//Set the text for the static item.

CString COptionTreeItemStatic::GetStaticText()
//Get the text for the static item.

COptionTreeItemEdit handles like a regular edit control. You can also use all of the standard functions that you would normally use with a CEdit control.
BOOL COptionTreeItemEdit::CreateEditItem(BOOL bMultiline, BOOL bPassword, 
                                         BOOL bNumerical, DWORD dwAddStyle)
//Creates the edit window, returns TRUE if the window is created successful.

BOOL COptionTreeItemEdit::GetMultiline()
//Returns TRUE if edit is multiline.

BOOL COptionTreeItemEdit::GetNumerical()
//Returns TRUE if edit is numerical.

BOOL COptionTreeItemEdit::GetPassword()
//Returns TRUE if edit is password.

void COptionTreeItemEdit::SetMultiline(BOOL bMultiline)
//Set the edit multiline option.

void COptionTreeItemEdit::SetEditDouble(double dValue)
void COptionTreeItemEdit::SetEditDword(DWORD dwValue)
void COptionTreeItemEdit::SetEditFloat(float fValue)
void COptionTreeItemEdit::SetEditInt(int nValue)
void COptionTreeItemEdit::SetEditLong(long lValue)
//Set the edit text as a numerical value.

BOOL COptionTreeItemEdit::GetEditDouble(double &dReturn)
BOOL COptionTreeItemEdit::GetEditDword(DWORD &dwReturn)
BOOL COptionTreeItemEdit::GetEditFloat(float &fReturn)
BOOL COptionTreeItemEdit::GetEditInt(int &nReturn)
BOOL COptionTreeItemEdit::GetEditLong(long &lReturn)
//Get the edit text as a numerical value. If function returns FALSE the 
//text is not numerical.

COptionTreeItemComboBox handles like a regular combo box control. You can also use all of the standard functions that you would normally use with a CComboBox control.
BOOL COptionTreeItemComboBox::CreateComboItem(DWORD dwAddStyle)
//Creates the edit window, returns TRUE if the window is created successful.

void COptionTreeItemComboBox::SetDropDownHeight(long lHeight)
//Set the height for the drop down window.

COptionTreeItemCheckBox is a check box control.
BOOL COptionTreeItemCheckBox::CreateCheckBoxItem(BOOL bChecked, BOOL bShowCheck, 
                                                 BOOL bShowText)
//Creates the check box window, returns TRUE if the window is created successful.

BOOL COptionTreeCheckButton::GetCheck()
//Returns TRUE if check box is checked.

void COptionTreeCheckButton::SetCheckText(CString strChecked, CString strUnChecked)
//Sets the checked text to be displayed when checked and unchecked.

COptionTreeItemRadio is a radio box control.
BOOL COptionTreeItemRadio::CreateRadioItem()
//Creates the radio box window. 

void COptionTreeItemRadio::InsertNewRadio(CString strText, BOOL bChecked)
//Insert a new radio item, this should be done in the order you wish the radio 
//items to be in.

int COptionTreeItemRadio::GetCheckedRadio()
//Gets the checked radio item in a 0 index form. Function returns -1 if error.

COptionTreeItemSpinner is a spinner control that allows users to select numerical values..
BOOL COptionTreeItemSpinner::CreateSpinnerItem(BOOL bWrapAround, BOOL bUserEdit,
                          double dValue, double dRangeBottom, double dRangeTop)
//Creates the spinner window, returns TRUE if the window is created successful.

void COptionTreeSpinnerButton::SetEditDouble(double dValue)
void COptionTreeSpinnerButton::SetEditDword(DWORD dwValue)
void COptionTreeSpinnerButton::SetEditFloat(float fValue)
void COptionTreeSpinnerButton::SetEditInt(int nValue)
void COptionTreeSpinnerButton::SetEditLong(long lValue)
//Set the spinner value as a numerical value.

BOOL COptionTreeSpinnerButton::GetEditDouble(double &dReturn)
BOOL COptionTreeSpinnerButton::GetEditDword(DWORD &dwReturn)
BOOL COptionTreeSpinnerButton::GetEditFloat(float &fReturn)
BOOL COptionTreeSpinnerButton::GetEditInt(int &nReturn)
BOOL COptionTreeSpinnerButton::GetEditLong(long &lReturn)
//Get the spinner value as a numerical value. If function returns FALSE an error 

void COptionTreeSpinnerButton::GetRange(double &dBottom, double &dTop)
//Gets the range for the spinner.

void COptionTreeSpinnerButton::SetRange(double dBottom, double dTop)
//Sets the range for the spinner.

COptionTreeItemColor is a control to allow the user to select or set a custom color.
BOOL COptionTreeItemColor::CreateColorItem(COLORREF rcColor, 
                                           COLORREF rcAutomatic, BOOL bShowHex, 
                                           BOOL bLiveUpdate)
//Creates the color window, returns TRUE if the window is created successful.

COLORREF COptionTreeItemColor::GetColor()
//Gets the selected color.

void COptionTreeItemColor::SetColor(COLORREF rcColor)
//Sets the selected color.

void COptionTreeItemColor::SetShowHex(BOOL bShow)
//Sets the option to show hexadecimal or RGB values.

void COptionTreeItemColor::SetLiveUpdate(BOOL bLive)
//Sets the option to show live update colors.

COptionTreeItemDate is a control to allow the user to select or set a date or time. You can also use all of the standard functions that you would normally use with a CDateTimeCtrl control.
BOOL COptionTreeItemDate::CreateDateItem(CString strFormat, DWORD dwDateStyle)
//Creates the date window, returns TRUE if the window is created successful.

COptionTreeItemIcon is a control to allow the user to select an icon.
BOOL COptionTreeItemImage::CreateImageItem(DWORD dwOptions, CSize sImageSizes, 
                                           int nNumberColumns)
//Creates the icon window, returns TRUE if the window is created successful.

int COptionTreeItemImage::GetSelection()
//Gets the selected image in a 0 based index.

void COptionTreeItemImage::AddBitmap(CString strBitmap, COLORREF crMask, CString strText)
void COptionTreeItemImage::AddBitmap(UINT uBitmap, COLORREF crMask, CString strText)
void COptionTreeItemImage::AddBitmap(CBitmap &bBitmap, COLORREF crMask, CString strText)
void COptionTreeItemImage::AddIcon(UINT uIcon, CString strText)
void COptionTreeItemImage::AddIcon(HICON hIcon, CString strText)
//Insert a new image.
COptionTreeItemFont is a control to allow the user to select an font.
BOOL COptionTreeItemFont::CreateFontItem(LOGFONT lfFont, COLORREF crFontColor, 
             LOGFONT lfDefaultFont, COLORREF crDefaultFontColor, DWORD dwOptions)
BOOL COptionTreeItemFont::CreateFontItem(LOGFONT lfFont, COLORREF crFontColor, 
             DWORD dwOptions)
BOOL COptionTreeItemFont::CreateFontItem(CHARFORMAT cfFont, COLORREF crFontColor, 
             CHARFORMAT cfDefaultFont, COLORREF crDefaultFontColor, DWORD dwOptions)
BOOL COptionTreeItemFont::CreateFontItem(CHARFORMAT cfFont, COLORREF crFontColor, 
             DWORD dwOptions)
//Creates the font window, returns TRUE if the window is created successful.

void COptionTreeItemIcon::SetCurFont(CHARFORMAT cfFont)
void COptionTreeItemIcon::SetCurFont(LOGFONT lf)
//Sets the font currently displayed.

void COptionTreeItemIcon::SetDefaultFont(CHARFORMAT cfFont)
void COptionTreeItemIcon::SetDefaultFont(LOGFONT lf)
//Sets the default font, that will be set when the default button is pushed.

void COptionTreeItemIcon::SetTextColor(COLORREF crColor)
//Sets the text color.

void COptionTreeItemIcon::SetDefaultTextColor(COLORREF crColor)
//Sets the text color for the default font.

void COptionTreeItemIcon::SetApplyWindow(CWnd *pWnd)
//Sets the window to be notified when the apply button is pressed.
COptionTreeItemFile is a control to allow the user to select a file or folder.
//Creates the file window, returns TRUE if the window is created successful.
BOOL COptionTreeItemFile::CreateFileItem(CString strFile, CString strDefExt, 
                                         CString strFilter, DWORD dwOptions, 
                                         DWORD dwDlgFlags)

// gets information about the selected file(s).
CString COptionTreeItemFile::GetSelectedFolder()
CString COptionTreeItemFile::GetFileDrive()
CString COptionTreeItemFile::GetFileDir()
CString COptionTreeItemFile::GetFileExt()
CString COptionTreeItemFile::GetFileTitle()
CString COptionTreeItemFile::GetFileName()
CString COptionTreeItemFile::GetPathName()
CString COptionTreeItemFile::GetNextPathName(POSITION& pos)
POSITION GetStartPosition()
COptionTreeItemIPAddress is a control to allow the user to select a IP Address.
//Creates the ip address window, returns TRUE if the window is created successful.
BOOL COptionTreeItemIPAddress::CreateIPAddressItem(DWORD dwAddStyle)
COptionTreeItemHyperLink is a control to allow the user to click on a hyperlink.
// Creates the hyperlink window, returns TRUE if the window is created successful.
BOOL COptionTreeItemIPAddress::CreateHyperlinkItem(DWORD dwOptions, 
                   CString strLink, COLORREF crLink, COLORREF crHover = NULL, 
                   COLORREF crVisited = NULL)


You can have your application be notified of certain events that happen in the tree control. Below is an example of how to be notified when an event happens, and all the notifications you can have.

void CYourDialog::OnTreeItemChanged(NMHDR* pNotifyStruct, LRESULT* plResult)
    // Declare variables

    // Validate
    if (pNMOptionTree->pItem != NULL)
        // -- Use item
        return 1;

    *plResult = 0;
Available Notifications
OT_NOTIFY_INSERTITEM        // Insert item
OT_NOTIFY_DELETEITEM        // Delete item
OT_NOTIFY_DELETEALLITEMS    // Delete all items
OT_NOTIFY_ITEMCHANGED       // Item changed
OT_NOTIFY_ITEMBUTTONCLICK   // Item button click
OT_NOTIFY_SELCHANGE         // Selection changed
OT_NOTIFY_ITEMEXPANDING     // Item expanding
OT_NOTIFY_COLUMNCLICK       // Column click
OT_NOTIFY_PROPCLICK         // Property click

Creating Custom OptionTreeItem's

Creating custom tree controls is a difficult and drawn out process, but I do not want this to deter you from taking on the task. If you are an beginner program and have ideas for new controls, please let me know and I will see what I can do. If you are and advanced programmer and have created customized controls, please let me also know and I will include them in the next release. Some overrides you made need to know for OptionTreeItem are below, you can look at some of the code for the controls I have created to get an idea of how they are managed. Each control type, requires a different attack angle to implement it. A good place to start is to take a look at OptionTreeItemStatic, this is a simple control. OptionTreeItemEdit is a good place to go after you look at the static item.

void OptionTreeItem::DrawAttribute(CDC *pDC, const RECT &rcRect)
//Called when item needs to be painted.

void OptionTreeItem::OnActivate()
//Called when the item is clicked by mouse or enter key is pressed. This may 
//be where your control displays a window, or a menu.

void OptionTreeItem::OnCommit()
//Called when data has been committed, a confirmation that options have been
//changed. CommitChanges() is then called to handle the selection of data.

void OptionTreeItem::OnMove()
//Called when the item is moved.

void OptionTreeItem::OnMove()
//Called when item is refreshed.

void OptionTreeItem::OnSelect()
//Called when item is selected.

void OptionTreeItem::OnDeSelect()
//Called when item is deselected.

void OptionTreeItem::CleanDestroyWindow()
//Called when the Tree control is destroyed or when the item is deleted. This is 
//incase your item needs to destroy a window.


The COptionTree is inspired by code, ideas, and submissions from the following:

Version History

Below is the version history for COptionTree.

5/7/2002 Initial implementation.

5/10/2002 Fix problems with icon and color items. Also fixed problems with expanding columns and column size. Added TAB support, hit TAB to activate next item, and SHIFT TAB to activate previous item. NOTE: You must commit current item with the ENTER key before tabbing, this is because some controls use TAB i.e.) edit, control box, radio, and so on.

5/11/2002 Fixed IsWindow() issues, which are the causes for a lot of Win98 problems. Fixed IDC_HAND problem for non Win 2K or XP users. Fixed some resource and overhead problems. Also added expand all feature. Huge thanks go out to all bug reporters, especially YoSilver.

5/14/2002 Fixed icon and color bug. Also added GetItemType() to determine different item types.

9/1/2002 Beta release, beta is not stable by any means.

9/8/2002 The long awaited 2.0 version is here. Fixed a lot of bugs, created more bugs, added several more items, and a lot of other stuff that is way too much to list here. Oh plus I added fancy new version numbers, this I think was the biggest update.

Bug Reports

If you have a bug report, or a bug fix you can contact me through email or with the forums below. I would appreciate a notification of any bugs discovered or improvements that could be made to help the control grow for everyone.


This code is provided "as is" with no expressed or implied warranty.

You may use this code in a commercial product with or without acknowledgement. However you may not sell this code or any modification of this code, this includes commercial libraries and anything else for profit.


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


About the Author

Matthew R. Miller
Web Developer
United States United States
No Biography provided

Comments and Discussions

GeneralMultiline Edit Pin
denczek20-Mar-03 11:58
Memberdenczek20-Mar-03 11:58 
GeneralPasting text into a digit/only/editbox Pin
Jonas A5-Mar-03 12:54
MemberJonas A5-Mar-03 12:54 
Generaloutstanding ! Pin
ZhuoGuangSheng3-Mar-03 20:46
MemberZhuoGuangSheng3-Mar-03 20:46 
GeneralMaybe a bug... Pin
masterfox26-Feb-03 12:51
Membermasterfox26-Feb-03 12:51 
GeneralRe: Maybe a bug... Pin
Thilo-Alexander Ginkel3-Mar-03 4:33
MemberThilo-Alexander Ginkel3-Mar-03 4:33 
GeneralRe: Maybe a bug... Pin
Pavlo_K9-Apr-03 6:51
MemberPavlo_K9-Apr-03 6:51 
GeneralRe: Maybe a bug... Pin
bad_fish19-May-03 0:28
Memberbad_fish19-May-03 0:28 
GeneralRepainting Pin
aroman20-Feb-03 0:20
Memberaroman20-Feb-03 0:20 

I started to use your code. I noticed that the first time I click inside tree, to select something, painting takes a lot of time. The program just locks for several seconds...
I looked over the code and I noticed that you call UpdateWindow a lot. Even from WM_PAINT handlers.
This isn't exactly a good practice, because of two reasons.

One is that this way you don't let Windows merge several WM_PAINTs into a single one. Several invalidated regions could be merged into a single one before the window would receive a WM_PAINT.

Second, this can result in paint handler being called again, when the code is still in the paint handler (UpdateWindow doesn't return untill the paint handler is executed). It can result a deadlock. It would exhauste the stack pretty easy.

This might give the behaviour I noticed. Also this might be the reason of the resources exhoustion noticed in the message "serious bug found".

I removed all UpdateWindow in your code, and it works very well, and without that lock behaviour. Even without UpdateWindow, if you call Invalidate, Windows will eventually send WM_PAINT to every invalidated window, but it will be able to merge a lot of Invalidate calls, which translate in faster response. Not only that, but this way you can ensure that you won't call OnPaint from OnPaint recursively.

Adrian Roman
GeneralRe: Repainting Pin
milix13-Mar-03 2:35
Membermilix13-Mar-03 2:35 
GeneralRe: Repainting Pin
milix13-Mar-03 3:17
Membermilix13-Mar-03 3:17 
GeneralFont Pin
denczek17-Feb-03 7:49
Memberdenczek17-Feb-03 7:49 
GeneralNeed for Windows CE. Pin
VAIOnian Anold11-Feb-03 1:01
MemberVAIOnian Anold11-Feb-03 1:01 
GeneralBigBig PROBLEM in AddBitmap Pin
Gozhhu8-Feb-03 23:48
MemberGozhhu8-Feb-03 23:48 
QuestionNumeric doesn't support decimal? Pin
clintsinger23-Jan-03 14:31
Memberclintsinger23-Jan-03 14:31 
GeneralLooks good so far (and a question). Pin
clintsinger23-Jan-03 10:06
Memberclintsinger23-Jan-03 10:06 
GeneralSlider control Pin
Joshua Jensen16-Jan-03 16:48
MemberJoshua Jensen16-Jan-03 16:48 
GeneralRe: Slider control Pin
Patrik Mueller27-Jan-03 20:37
MemberPatrik Mueller27-Jan-03 20:37 
GeneralRe: Slider control Pin
denczek12-Feb-03 3:27
Memberdenczek12-Feb-03 3:27 
GeneralCan't compile in vc7, need help!! Pin
Stefan Dahlin14-Jan-03 6:14
MemberStefan Dahlin14-Jan-03 6:14 
GeneralRe: Can't compile in vc7, need help!! Pin
PNW15-Jan-03 12:45
MemberPNW15-Jan-03 12:45 
GeneralCOptionTreeItemComboBox Validation Pin
Joel Holdsworth30-Dec-02 4:45
MemberJoel Holdsworth30-Dec-02 4:45 
GeneralRe: COptionTreeItemComboBox Validation Pin
bobo12313-Feb-03 22:45
Memberbobo12313-Feb-03 22:45 
GeneralRe: COptionTreeItemComboBox Validation Pin
MAXS72U4-Apr-03 3:24
MemberMAXS72U4-Apr-03 3:24 
GeneralRe: COptionTreeItemComboBox Validation Pin
Joel Holdsworth4-Apr-03 11:49
MemberJoel Holdsworth4-Apr-03 11:49 
GeneralRe: COptionTreeItemComboBox Validation Pin
MAXS72U6-Apr-03 21:38
MemberMAXS72U6-Apr-03 21:38 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.