The control is a subclassed LISTBOX
control.
A good number of IProperty
derived classes define how each property type
is handled and rendered. Each property class is responsible for its own editor look
and manages its own rendering, click behavior, validation and attached popup dialogs.
Because of this, you may extend the control with your own property types.
They can be owner-drawn or contain your own popup dialogs.
It can operate in two modes: With and without categories. If categories are enabled, then items are grouped in expandable lists. Category lists can be expanded/collapsed by clicking on the little plus/minus icon.
There are actually several fine Property List control implementations to be found on the internet - both commercial and free-ware. I have even found a few ATL based implementations, so before you decide to use this control, it might be worth it to scour the web first.
How to use it
Place aLISTBOX
control on a dialog.
Add a member variable to your dialog class...
CPropertyListCtrl m_list
In the OnInitDialog()
event handler, add the following line:
LRESULT OnInitDialog(UINT /*uMsg*/, WPARAM /*wParam*/, LPA...
{
...
m_list.SubclassWindow(GetDlgItem(IDC_MYLISTBOX));
...
}
Then add the following reflection macro to your main message map:
BEGIN_MSG_MAP(CMainDlg)
...
REFLECT_NOTIFICATIONS()
END_MSG_MAP()
Once the control is created you can add properties. Properties are abstracted into
the HPROPERTY
handle, but in reality, there is a IProperty
derived
class behind it.
Here are some of the control methods available:
AddItem
ResetContent
GetItemName
GetItemValue
SetItemValue
ExpandItem
CollapseItem
and many of the original CListBox
methods still work too.
So set the control flags...
m_list.SetExtendedListStyle(PLS_EX_CATEGORIZED);
Adding a property requires using a "creation helper" method...
m_list.AddItem( PropCreateCategory("Appearance") );
m_list.AddItem( PropCreateSimple("Name", "Form1") );
m_list.AddItem( PropCreateSimple("X", 123L) );
m_list.AddItem( PropCreateSimple("Y", 456L) );
You can associate some item-data to each property, so it can later be identified.
Several notifications are sent back to the owner window.
They contain information about the property changing using
WM_NOTIFY
notification structure: NMPROPERTYITEM
.
The list of notifications currently include:
PIN_SELCHANGED
PIN_ITEMCHANGING
PIN_ITEMCHANGED
PIN_COLLAPSING
PIN_EXPANDING
PIN_DBLCLICK
PIN_BROWSE
PIN_CLICK
The control needs the LBS_OWNERDRAWVARIABLE
flag so it can draw its own items.
You may only enable the LBS_SORT
and LBS_HASSTRINGS
flags
to have sorted items if you're not using categories.
Available Editors
I have included a few common in-place editors so you can see the general idea.Here is a list of most of them...
PropCreateSimple (text)
A simple string with an in-place edit control to modify the value.
PropCreateSimple (boolean)
A boolean property shown as a
dropdown list with two entries: true and false.
PropCreateSimple (long)
An integer. Unsigned integers are
automatically filtered for numeric characters only.
The integer property uses the edit control as its in-place editor.
PropCreateVariant (VARIANT)
Other data types, which are also
modified using the in-place edit control. You can pass any type that the VARIANT
type supports. This includes decimal values.
PropCreateFileName
A filename and a browse button. Launches the
Windows File Dialog.
PropCreateList
Creates a property with a dropdown list. The list
items are supplied as an argument. The selected list index is returned as value.
PropCreateCheckButton
A simple property, which only displays a checkmark
button. Acts as a boolean switch.
PropCreateComboControl
Creates a property with a dropdown list. The caller must supply an ownerdrawn ListBox control
to the property, which will be shown.
PropCreateReadOnlyItem
A read-only property.
This particular list control also defines a PropCreateCategory
property type, which is used to add a collapsible grouping of properties.
Other of my property controls (see links below) may define custom properties that
are needed for their specific use.
A property class (or HPROPERTY
handle) is constructed when you call one
of these creation methods. Once the property is returned, it must be passed to the
control because it is the control that manages its lifespan and makes sure to
destroy the handle appropriately. The application may hold on to the handle and
use it only as long as the item is availabe in the control or the control window
has not been destroyed.
Source Code Dependencies
Microsoft Visual C++ 6.0Microsoft WTL 3.1 Library
See Also
My Property Tree controlMy Property Grid control
A simple Property View control
Download Files
![]() | Source Code and sample (31 Kb) |