COptionTree

• 下载演示应用程序 - 108 Kb
• 下载源代码 - 284 Kb

 

2.0 版本有什么新变化？

备受期待的 2.0 版本终于来了。好消息是您将获得新功能、新选项、新项目和新 bug。坏消息是，很多东西都发生了变化，您可能需要更改现有代码才能实现新版本。（感谢 **Tom** 和 **Irfan** 修复了那些在我关灯睡觉时困扰我的 bug。他们理应获得加粗的姓名。）

目录

• 特点
• 用法
• API 参考
• Notifications
• 创建自定义 OptionTreeItem
• 致谢
• 版本历史
• Bug 报告
• 许可证

特点

以下是 COptionTree 的众多功能中的一部分。

• 静态控件。
• 编辑控件。
• 组合框控件。
• 复选框控件。
• 单选按钮控件。
• 微调器控件。
• 颜色控件。
• 日期和时间控件。
• 图像控件。
• 字体控件。
• 文件和文件夹控件。
• IP 地址控件。
• 超链接控件。
• 自动列调整限制。
• 不同 GUI 风格的易于定制的选项。
• 每个控件项的易于定制的选项。
• 以及更多...

用法

您有两种选项可以使用 COptionTree，您可以将其用作静态控件或 DLL。

将以下文件添加到您的项目中

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

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

创建控件

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

可用树选项

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

验证树项

// 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 参考

这是 COptionTree 类最常用函数列表。还有更多函数，但这些足以让普通用户使用该控件。

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 是一个用于处理树中项的类。每个选项/首选项都是一个不同的项。根据使用哪种类型的控件项，所有控件类型都可以获得这些函数。

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 是一个简单的静态控件。以下是用于设置编辑静态文本的自定义函数。

void COptionTreeItemStatic::SetStaticText(CString strStaticText)
//Set the text for the static item.

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

COptionTreeItemEdit
COptionTreeItemEdit 的行为类似于常规编辑控件。您还可以使用通常与 CEdit 控件一起使用的所有标准函数。

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 的行为类似于常规组合框控件。您还可以使用通常与 CComboBox 控件一起使用的所有标准函数。

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 是一个复选框控件。

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 是一个单选按钮控件。

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 是一个微调器控件，允许用户选择数值。

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 是一个控件，允许用户选择或设置自定义颜色。

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 是一个控件，允许用户选择或设置日期或时间。您还可以使用通常与 CDateTimeCtrl 控件一起使用的所有标准函数。

BOOL COptionTreeItemDate::CreateDateItem(CString strFormat, DWORD dwDateStyle)
//Creates the date window, returns TRUE if the window is created successful.

COptionTreeItemImage
COptionTreeItemIcon 是一个控件，允许用户选择一个图标。

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 是一个控件，允许用户选择一个字体。

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 是一个控件，允许用户选择一个文件或文件夹。

//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 是一个控件，允许用户选择一个 IP 地址。

//Creates the ip address window, returns TRUE if the window is created successful.
BOOL COptionTreeItemIPAddress::CreateIPAddressItem(DWORD dwAddStyle)

COptionTreeItemHyperLink
COptionTreeItemHyperLink 是一个控件，允许用户点击超链接。

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

您可以让您的应用程序收到树控件中发生的某些事件的通知。下面是如何接收事件发生通知的示例，以及您可以收到的所有通知。

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;
}

可用通知

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

创建自定义 OptionTreeItem

创建自定义树控件是一个复杂且耗时的过程，但我不想因此阻止您承担这项任务。如果您是初学者程序员并且有新控件的想法，请告诉我，我会尽力而为。如果您是高级程序员并且创建了自定义控件，也请告诉我，我将在下一个版本中包含它们。您可能需要了解 OptionTreeItem 的一些重写，下面是一些示例，您可以查看我创建的一些控件的代码，以了解它们是如何管理的。每种控件类型都需要不同的方法来实现。一个好的起点是查看 OptionTreeItemStatic，这是一个简单的控件。在查看了静态项之后，OptionTreeItemEdit 是一个不错的选择。

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.

致谢

COptionTree 的灵感来自于以下代码、想法和投稿

• CPropTree v1.0 - Property Tree Control - 作者：Scott Ramsay
• A color picker button - 作者：James White
• 明星 bug 修复者：YoSilver、Tom、Irfan

版本历史

以下是 COptionTree 的版本历史记录。

Bug 报告

如果您有 bug 报告或 bug 修复，可以通过电子邮件或下方的论坛联系我。如果您发现任何 bug 或有任何改进建议，我将不胜感激，这将有助于该控件为所有人成长。

许可证

本代码按“原样”提供，不附带任何明示或暗示的保证。

您可以将此代码用于商业产品，无论是否注明出处。但是，您不得销售此代码或任何修改后的代码，这包括商业库和任何其他用于盈利的目的。