 |
||||||||||
| ||||||||||
| ||||||||||
Desktop Development »
Tree Controls »
Custom Tree Controls
Advanced
COptionTreeBy Matthew R. MillerAn article on an easy and neat way to include options, preferences, or settings into your applications |
VC6, VC7, C++Windows, Win2K, WinXP, MFC, VS6, Visual Studio, Dev Posted: 7 May 2002 Updated: 19 Sep 2002 Views: 423,543 Bookmarked: 215 times |
||
|
|
|||
Announcements
Chapters
Services
Feature Zones
|
Advanced Search Sitemap |
|
|
|
||||||||||||||||
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 itemsValidating 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.
COptionTreeItemFontCOptionTreeItemFont 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.
COptionTreeItemFileCOptionTreeItemFile 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.
| 5/7/2002 |
1.0.0.0 | Initial implementation. |
|
|
||
| 5/10/2002 | 1.1.0.0 | 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 | 1.1.1.0 | 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 | 1.1.2.0 | Fixed icon and color bug. Also added GetItemType() to determine different item types. |
|
|
||
| 9/1/2002 | 1.1.2.1 | Beta release, beta is not stable by any means. |
|
|
||
| 9/8/2002 | 2.0.0.0 | 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.
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.
