COptionTree

• Download demo application - 108 Kb
• Download source - 284 Kb

 

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

Contents

• Features
• Usage
• API Reference
• Notifications
• Creating Custom OptionTreeItem's
• Acknowledgements
• Version History
• Bug Reports
• License

Features

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

Usage

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
GetClientRect(rcClient);

// Setup the window style
dwStyle = WS_CHILD | WS_VISIBLE;

// Setup the tree options
dwOptions =  OT_OPTIONS_SHADEEXPANDCOLUMN | OT_OPTIONS_SHADEROOTITEMS;

// Create tree options
if (m_otTree.Create(dwStyle, rcClient, this, dwOptions,
    IDC_OPTIONSTREE_OPTIONS) == FALSE)
{
    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.

OT_ITEM_STATIC
OT_ITEM_CHECKBOX
OT_ITEM_COLOR
OT_ITEM_COMBOBOX
OT_ITEM_DATE
OT_ITEM_EDIT
OT_ITEM_IMAGE
OT_ITEM_RADIO
OT_ITEM_SPINNER
OT_ITEM_FONT
OT_ITEM_FILE
OT_ITEM_IPADDRESS

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.

COptionTree

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
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
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
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
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
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
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
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 
//occured.

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

COptionTreeItemImage
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
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
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
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
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)

Notifications

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.

YourDialog.h

//...
    //}}AFX_MSG_MAP
    ON_NOTIFY(OT_NOTIFY_ITEMCHANGED, IDC_OPTIONSTREE_OPTIONS, OnTreeItemChanged)
END_MESSAGE_MAP()

YourDialog.cpp

void CYourDialog::OnTreeItemChanged(NMHDR* pNotifyStruct, LRESULT* plResult)
{
    // Declare variables
    LPNMOPTIONTREE pNMOptionTree = (LPNMOPTIONTREE)pNotifyStruct;

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

Acknowledgements

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

• CPropTree v1.0 - Property Tree Control - By Scott Ramsay
• A color picker button - By James White
• Star bug fixers: YoSilver, Tom, Irfan

Version History

Below is the version history for COptionTree.

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.

License

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.