CListOptionsCtrl v1.24

Welcome to CListOptionsCtrl, a control which implements a properties browser control similar to the properties browser in Visual Basic. In addition to Boolean values, it also allows edit boxes, combo boxes, file browser, folder browsers, font browsers, font name combo boxes, general opaque objects, date controls, time controls and IP address controls. Included below is a snapshot showing the demo application and what the control looks like.

Features

• Derived from the MFC class CListCtrl so if you have used this class before, then you should get up to speed using the CListOptionsCtrl pretty easily.
• Items supported included Booleans, edit boxes, combo boxes (drop list and editable), Edit boxes with spin control, File browser, Folder browser, Color selector, Font selector, Font Name selector and Boolean selector <g>!.
• Code is UNICODE enabled and build configurations are provided.
• All widget classes (e.g. Combo boxes and edit boxes) that are created can be customized without affected the base code.
• All code compiles cleanly at level 4.
• Small footprint, total size amounts to just c. 1800 lines of code, for such a large amount of functionality.
• The font and text and background colors can be customized for both the first (prompt) and second (value) columns in the control.

Copyright

• You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
• You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
• If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.

Usage

• To use the class in your code simply include ListOptionsCtrl.cpp in your project and #include "ListOptionsCtrl.h" in which ever of your modules needs to make calls to the class.
• You also need to copy over the strings from the sample apps string table (IDS_LISTOPTIONS_...)
• As of v1.22, the classes are now designed for VC 2005 or later. They will not compile on earlier releases of VC.
• Your code will need to include MFC either statically or dynamically.
• To see the class in action, have a look at the usage of the code in the module "appDlg.cpp".
• Once you have hooked up the control, you can setup the image list as per a normal CListCtrl. To change the depth of each item (to accommodate large edit boxes / combo boxes) just make the height of the bitmap you want to use for the image list greater than the normal 16 pixels. This is the case with the sample code provided.

History

V1.0 (5 December 2001)

• Initial public release.

V1.1 (13 January 2002)

• Made _ListOptionsItemData structure globally available and renamed it to CListOptionsItemData.
• Each child control class now is initialized with the index of the list view control at which it is created. This allows added flexibility in what a child control can do.
• Added a method to add an "Opaque Browser" to the list options control. An Opaque Browser is where the list options control allows a end user specified structure to be edited by the list options control without it explicitly knowing what it is editing. A standard "..." browse button is used and virtual functions are used to allow end user code to implement the required "browsing" functionality at the right time.
• Added a WM_SIZE handler to allow the class to work correctly where the containing view or dialog resizes it for layout reasons.
• Fixed a problem in CListOptionsCtrl::OnKillFocus which was not checking the value of GetSelectedItem before using it
• Updated copyright messages in code and in documentation

V1.11 (23 January 2002)

• Improved the "Opaque Browser" support to allow the two runtime classes to be specified e.g. you can have a combo box in addition to a button.

V1.12 (31 May 2002)

• Color is now optionally drawn in the icon for color browser items

V1.13 (1 June 2002)

• Moved application and code to VC 6.
• Now fully supports the CDateTimeCtrl for editing of dates and times

V1.14 (2 June 2002)

• Now fully supports the CIPAddressCtrl for editing of IP addresses.

V1.15 (17 October 2002)

• Changed function "BrowserForOpaque" to "BrowseForOpaque"

V1.16 (5 May 2004)

• Fixed some compiler warnings when the code is compiled using VC 7.x. Please note that to implement these fixes, the code will now require the Platform SDK to be installed if you compile the code on VC 6.

V1.17 (26 November 2004)

• Fixed a bug where in place editing would fail on a multiple monitor setup when the listoptions control was on a monitor which had negative coordinates relative to the primary display

V1.18 (3 May 2006)

• Updated the copyright details.
• Control now allows the per item text to be Bold, italic or underlined or any combination of the three.
• Optimized the construction of member variables in all classes
• Inlined the virtual destructors.
• Provided a set of macros which allow the code to be easily added to an extension DLL.
• Control now uses WM_USER instead of WM_APP for private messages
• Prompt and value text color and background color can also be customized.
• Updated documentation to use the same style as the web site.
• Did a spell check of the documentation.

V1.19 (8 May 2006)

• Removed unnecessary message map for CListOptionsSpinCtrl WM_CHAR
• Removed unnecessary message map for CListOptionsBrowseButton WM_CHAR
• Reworked CListOptionsDateCtrl::GetDisplayText to handle variable length data
• Reworked CListOptionsTimeCtrl::GetDisplayText to handle variable length data
• Removed unnecessary message map for CListOptionsTimeCtrl WM_CREATE
• CListOptionsEdit::GetBrowseForFolderCaption(), CListOptionsEdit::GetBrowseForFileCaption() and CListOptionsEdit::GetFileExtensionFilter() now use string resources instead of string literals.

V1.20 (7 July 2006)

• Code now uses newer C++ style casts instead of C style casts.
• Removed various unused constructors and destructors in the sample app's code.
• Updated code to compile cleanly using VC 2005.

V1.21 (23 December 2007)

• Updated copyright details.
• Removed VC 6 style AppWizard comments from the code.
• Optimized CListOptionsItemData constructor code
• Boolean member variables of CListOptionsItemData have now been made "bool" instead of "BOOL"
• Fixed an issue where if you create a combo box with a style of CBS_DROPDOWN instead of CBS_DROPDOWNLIST, then the combo box would not be properly deactivated when it loses focus to a control outside of the ListOptionsCtrl while the cursor is in the combo box edit field. Thanks to Tobias Wolf for reporting this issue.
• Fixed a crash where you select a combo box item, select something in it and then hit tab.
• Focus is now correctly transferred to a list options button if you hit tab on a list options combo box.

V1.22 (15 June 2008)

• Updated copyright details
• Code now compiles cleanly using Code Analysis (/analyze)
• Updated code to compile correctly using _ATL_CSTRING_EXPLICIT_CONSTRUCTORS define
• The code now only supports VC 2005 or later.
• Replaced all calls to CopyMemory with memcpy

V1.23 (21 May 2012)

• Updated copyright details.
• Updated the sample app to clean compile on VC 2010.
• Added support for enabling / disabling items. Thanks to Damir Valiulin for this nice addition.
• Updated sample project settings to more modern defaults
• Code now compiles cleanly using Code Analysis (/analyze)

V1.24 (16 March 2015)

• Updated copyright details.
• Updated the code to clean compile on VC 2013

API Reference

The API consists of the following class members and global functions

CListOptionsCtrl::AddBoolean
CListOptionsCtrl::AddComboBox
CListOptionsCtrl::AddEditBox
CListOptionsCtrl::AddFileEditBox
CListOptionsCtrl::AddFolderEditBox
CListOptionsCtrl::AddColorSelector
CListOptionsCtrl::AddFontSelector
CListOptionsCtrl::IsBoolean
CListOptionsCtrl::IsEditBox
CListOptionsCtrl::IsFileItem
CListOptionsCtrl::IsFolderItem
CListOptionsCtrl::IsColorItem
CListOptionsCtrl::IsFontItem
CListOptionsCtrl::GetBoolean
CListOptionsCtrl::GetComboText
CListOptionsCtrl::GetEditText
CListOptionsCtrl::GetFileEditText
CListOptionsCtrl::GetFolderEditText
CListOptionsCtrl::GetColor
CListOptionsCtrl::GetFontItem
CListOptionsCtrl::SetBoolean
CListOptionsCtrl::SetComboText
CListOptionsCtrl::SetEditText
CListOptionsCtrl::SetFileEditText
CListOptionsCtrl::SetFolderEditText
CListOptionsCtrl::SetColor
CListOptionsCtrl::SetFontItem
DDX_ListBoolean
DDX_ListEdit
DDX_ListCombo
DDX_ListFileEdit
DDX_ListFolderEdit
DDX_ListColor
DDX_ListFont

BOOL IsCheckBox(int nIndex);

TRUE if the specified item is a check box item otherwise FALSE.

nIndex index of the item to check the type of.

Checks to see if the specified item is a boolean combo box item.

BOOL IsEditBox(int nIndex);

TRUE if the specified item is a edit box item otherwise FALSE.

nIndex Index of the item to check the type of.

Checks to see if the specified item is a edit box item.

BOOL IsFileItem(int nIndex);

TRUE if the specified item is a file browser item otherwise FALSE.

nIndex Index of the item to check the type of.

Checks to see if the specified item is a file browser item.

BOOL IsFolderItem(int nIndex);

TRUE if the specified item is a folder browser item otherwise FALSE.

nIndex Index of the item to check the type of.

Checks to see if the specified item is a folder browser item.

BOOL IsColorItem(int nIndex);

TRUE if the specified item is a color browser item otherwise FALSE.

nIndex Index of the item to check the type of.

Checks to see if the specified item is a color browser item.

BOOL IsFontItem(int nIndex);

TRUE if the specified item is a font browser item otherwise FALSE.

nIndex Index of the item to check the type of.

Checks to see if the specified item is a font browser item.

BOOL SetBoolean(int nIndex, BOOL bValue);

TRUE if the state of the item was successfully changed otherwise FALSE.

nIndex Index of the item to change the boolean state of.

bValue The state of the boolean combo box to be set.

Changes the boolean state of a boolean combo box item.

BOOL GetBoolean(int nIndex, BOOL& bValue);

Return Value

TRUE if the state of the item was successfully retrieved otherwise FALSE.

nIndex Index of the item to retrieve the boolean state of.

bCheck Upon successful return, this will contain the state of the boolean check box.

Retrieves the boolean state of a boolean combo box item.

BOOL AddBoolean(int nIndex , DWORD_PTR dwItemData = 0);

TRUE if the boolean combo box item was successfully added otherwise FALSE.

nIndex Index of the item to add the combo box at.

dwItemData The custom item data you want to use with this list item. This can be used for whathever you want e.g. to maintain a pointer to a custom structure.

Adds a boolean combo box item to the list control. 

BOOL AddComboBox(int nIndex, CRuntimeClass* pRuntimeClass, DWORD_PTR dwItemData = 0);

TRUE if the combo box item was successfully added otherwise FALSE.

nIndex Index of the item to add the combo box at.

pRuntimeClass The runtime class pointer on a class derived from "CListOptionsCombo" which is to be added to the list options control.

dwItemData The custom item data you want to use with this list item. This can be used for whathever you want e.g. to maintain a pointer to a custom structure.

Adds a combo box item to the list control. The combo box by default provides a choice of multiple strings from which to pick. You are free to derive your own class from "CListOptionsCombo" to implement customized behavior

BOOL AddEditBox(int nIndex, CRuntimeClass* pRuntimeClassEditCtrl, DWORD_PTR dwItemData = 0);

BOOL AddEditBox(int nIndex, CRuntimeClass* pRuntimeClassEditCtrl, CRuntimeClass* pRuntimeClassSpinCtrl, DWORD_PTR dwItemData = 0);

TRUE if the edit box item was successfully added otherwise FALSE.

nIndex Index of the item to add the edit box at.

pRuntimeClassEditCtrl The runtime class pointer on a class derived from "CListOptionsEdit" which is to be added to the list options control.

pRuntimeClassSpinCtrl The runtime class pointer on a class derived from "CListOptionsSpinCtrl" which is to be attached to the edit box to allow the edit box value to be changed using a standard spin control.

dwItemData The custom item data you want to use with this list item. This can be used for whathever you want e.g. to maintain a pointer to a custom structure.

Adds a edit box item to the list control. The edit box by default allows any text to be set. You are free to derive your own class from "CListOptionsEdit" to implement customized behavior. You can use the second version of the function to add an edit box along with a standard spin control with it.

BOOL AddFileEditBox(int nIndex, CRuntimeClass* pRuntimeClassEditCtrl, CRuntimeClass* pRuntimeClassBrowseButton, DWORD_PTR dwItemData = 0);

TRUE if the edit box item was successfully added otherwise FALSE.

nIndex Index of the item to add the File Browser edit box at.

pRuntimeClassEditCtrl The runtime class pointer on a class derived from "CListOptionsEdit" which is to be added to the list options control.

pRuntimeClassBrowseButton The runtime class pointer on a class derived from "CListOptionsBrowseButton" which is to be attached to the edit box to allow the edit box value to be changed using a standard file dialog control.

dwItemData The custom item data you want to use with this list item. This can be used for whathever you want e.g. to maintain a pointer to a custom structure.

Adds a File Browser edit box item to the list control. The edit box by default allows any text to be set. You are free to derive your own class from "CListOptionsEdit" to implement customized behavior.

BOOL AddFolderEditBox(int nIndex, CRuntimeClass* pRuntimeClassEditCtrl, CRuntimeClass* pRuntimeClassBrowseButton, DWORD_PTR dwItemData = 0);

TRUE if the edit box item was successfully added otherwise FALSE.

nIndex Index of the item to add the Folder Browser edit box at.

pRuntimeClassEditCtrl The runtime class pointer on a class derived from "CListOptionsEdit" which is to be added to the list options control.

pRuntimeClassBrowseButton The runtime class pointer on a class derived from "CListOptionsBrowseButton" which is to be attached to the edit box to allow the edit box value to be changed using a standard folder selection dialog control.

dwItemData The custom item data you want to use with this list item. This can be used for whathever you want e.g. to maintain a pointer to a custom structure.

Adds a Folder Browser edit box item to the list control. The edit box by default allows any text to be set. You are free to derive your own class from "CListOptionsEdit" to implement customized behavior.

CString GetComboText(int nIndex);

The text associated with this combo box item.

nIndex Index of the item to retrieve the combo box text of.

Retrieves the combo text of a combo box item.

CString GetEditText(int nIndex);

The text associated with this edit box item.

nIndex Index of the item to retrieve the edit box text of.

Retrieves the edit box text of a edit box item.

CString GetEditText(int nIndex);

The text associated with this edit box item.

nIndex Index of the item to retrieve the edit box text of.

Retrieves the edit box text of a File Browser edit box item.

CString GetEditText(int nIndex);

The text associated with this edit box item.

nIndex Index of the item to retrieve the edit box text of.

Retrieves the edit box text of a Foldere Browser edit box item.

void SetComboText(int nIndex, const CString& sComboText);

nIndex Index of the item to change the combo box text of.

sComboText The text to set in the combo box.

Changes the combo box text of a combo box item.

void SetEditText(int nIndex, const CString& sEditText);

nIndex Index of the item to change the edit box text of.

sEditText The text to set in the edit box.

Changes the edit box text of a edit box item.

void SetFileText(int nIndex, const CString& sEditText);

nIndex Index of the item to change the edit box text of.

sEditText The text to set in the edit box.

Changes the edit box text of a File Browser edit box item.

void SetFolderText(int nIndex, const CString& sEditText);

nIndex Index of the item to change the edit box text of.

sEditText The text to set in the edit box.

Changes the edit box text of a Folder Browser edit box item.

BOOL AddColorSelector(int nIndex, CRuntimeClass* pRuntimeClassButton, DWORD_PTR dwItemData = 0, BOOL bDrawColorForIcon = TRUE);

TRUE if the color browser item was successfully added otherwise FALSE.

nIndex Index of the item to add the color browser at.

pRuntimeClassButton The runtime class pointer on a class derived from "CListOptionsBrowseButton" which is to be added to the list options control.

dwItemData The custom item data you want to use with this list item. This can be used for whathever you want e.g. to maintain a pointer to a custom structure.

bDrawColorForIcon If TRUE then the current color is drawn in the items icon otherwise the normal icon is drawn.

Adds a Color Browser item to the list control. The color browser displays a standard CColorDialog when you hit the browse button. You are free to derive your own class from "CListOptionsBrowseButton" to implement customized behavior.

COLORREF GetColor(int nIndex);

The COLORREF value associated with this color browser item.

nIndex Index of the item to retrieve the COLORREF of.

Retrieves the color of a color browser item.

void SetColor(int nIndex, COLORREF color);

nIndex Index of the item to change the color of.

color The color to set in the color browser item.

Changes the edit box text of a edit box item.

BOOL AddFontSelector(int nIndex, CRuntimeClass* pRuntimeClassButton, DWORD_PTR dwItemData = 0);

TRUE if the font browser item was successfully added otherwise FALSE.

nIndex Index of the item to add the color browser at.

pRuntimeClassButton The runtime class pointer on a class derived from "CListOptionsBrowseButton" which is to be added to the list options control.

dwItemData The custom item data you want to use with this list item. This can be used for whathever you want e.g. to maintain a pointer to a custom structure.

Adds a font browser item to the list control. The font browser displays a standard CFontDialog when you hit the browse button. You are free to derive your own class from "CListOptionsBrowseButton" to implement customized behavior.

void GetFontItem(int nIndex, LOGFONT* pLogFont);

nIndex Index of the item to retrieve the COLORREF of.

pLogFont Upon return this will contain the update LOGFONT structure.

Retrieves the font characteristics of a font browser item.

void SetFontItem(int nIndex, const LOGFONT* pLogFont);

nIndex Index of the item to change the color of.

pLogFont pointer to the LOGFONT structure to set in the font browser item.

Changes the edit font characteristics of a font browser item.

void DDX_ListEdit(CDataExchange* pDX, int nIDC, int nIndex, CString& sText);

void DDX_ListEdit(CDataExchange* pDX, int nIDC, int nIndex, int& nValue);

pDX A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

nIDC The resource ID of the list control associated with the control property.

nIndex Index of the item which contains the edit control item.

sText A reference to a CString which is the text to display or retrieve from the list options control.

The DDX_ListEdit function manages the transfer of CString or integer data between a edit box in the CListOptionsCtrl in a dialog box, form view, or control view object and a CString or integer value.

void DDX_ListCombo(CDataExchange* pDX, int nIDC, int nIndex, CString& sText);

pDX A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

nIDC The resource ID of the list control associated with the control property.

nIndex Index of the item which contains the combo box item.

sText A reference to a CString which is the text to display or retrieve from the list options control.

The DDX_ListCombo function manages the transfer of CString data between a combo box in the CListOptionsCtrl in a dialog box, form view, or control view object and a CString data member.

void DDX_ListFileEdit(CDataExchange* pDX, int nIDC, int nIndex, CString& sText);

pDX A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

nIDC The resource ID of the list control associated with the control property.

nIndex Index of the item which contains the File Browser edit item.

sText A reference to a CString which is the text to display or retrieve from the list options control.

The DDX_ListFileEdit function manages the transfer of CString data between a File Browser edit box in the CListOptionsCtrl in a dialog box, form view, or control view object and a CString value.

void DDX_ListFolderEdit(CDataExchange* pDX, int nIDC, int nIndex, CString& sText);

pDX A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

nIDC The resource ID of the list control associated with the control property.

nIndex Index of the item which contains the Folder Browser edit item.

sText A reference to a CString which is the text to display or retrieve from the list options control.

The DDX_ListFolderEdit function manages the transfer of CString data between a Folder Browser edit box in the CListOptionsCtrl in a dialog box, form view, or control view object and a CString value.

void DDX_ListColor(CDataExchange* pDX, int nIDC, int nIndex, COLORREF& color);

pDX A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

nIDC The resource ID of the list control associated with the control property.

nIndex Index of the item which contains the color browser item.

color A reference to a COLORREF which is the color to display or retrieve from the list options control.

The DDX_ListColor function manages the transfer of COLORREF data between a color browser item in the CListOptionsCtrl in a dialog box, form view, or control view object and a COLORREF value.

void DDX_ListFont(CDataExchange* pDX, int nIDC, int nIndex, LOGFONT* pLogFont);

pDX A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

nIDC The resource ID of the list control associated with the control property.

nIndex Index of the item which contains the font browser item.

color A pointer to a LOGFONT strucutre which is the font to display or retrieve from the list options control.

The DDX_ListFont function manages the transfer of LOGFONT structure data between a font browser item in the CListOptionsCtrl in a dialog box, form view, or control view object and a LOGFONT structure value.

void DDX_ListBoolean(CDataExchange* pDX, int nIDC, int nIndex, BOOL& bValue);

pDX A pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

nIDC The resource ID of the list control associated with the control property.

hParent Index of the item which contains the boolean combo box item.

color A reference to a BOOL which is the boolean value to display or retrieve from the list options control.

The DDX_ListBoolean function manages the transfer of BOOL value between a boolean combo box item in the CListOptionsCtrl in a dialog box, form view, or control view object and a BOOL value.

Planned Enhancements

• If you have any other suggested improvements, please let me know so that I can incorporate them into the next release.

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
16 March 2015