COptionTree

invalid-file

invalid-file

 

What's New with 2.0

The long awaited 2.0 version is here. Good news is you get newfeatures, new options, new items, and new bugs. Bad news is, a lot haschanged so you may need to change around your current code to implementthe new version.(Thanks to Tom and Irfan for there fixes for bugs that haunted me at night when the lights areoff. 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 oras 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'sclasses. There many more functions than this, but these give theaverage 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 ofitem control is used, these functions areacquired 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 normallyuse 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 boxcontrol. You can also use all of the standard functions that you wouldnormally 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 toselect or set a date or time. You can also use all of the standardfunctions 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 fromtaking on the task. If you are an beginner programand have ideas for new controls, please let me know and I will see whatI can do. If you are and advanced programmer and have createdcustomized controls, please letme also know and I will include them in the next release. Someoverrides you made need to know for OptionTreeItemare below, you can look at some of the code for the controls I havecreated to get an idea of how they are managed. Each control type,requires a different attack angle to implement it. A good place tostart is totake 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.