viksoe.dk

PropertyList control

PropertyList control


This article was submitted .


I found time to modify my WTL PropertyView control to function as a real Property List control, just like the one known from the Visual Basic IDE. It has been fitted with several in-place editors, such as dropdown lists and filename browsers.

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 a LISTBOX 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.0
Microsoft WTL 3.1 Library

See Also

My Property Tree control
My Property Grid control
A simple Property View control

Download Files

DownloadSource Code and sample (31 Kb)

To the top