| Version: 3.3.1

wxPropertyGrid Overview

wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs.

List of ready-to-use property classes include strings, numbers, flag sets, fonts, colours and many others. It is possible, for example, to categorize properties, set up a complete tree-hierarchy, add more than two columns, and set arbitrary per-property attributes.

See also
  wxPropertyGrid, wxPropertyGridEvent, wxPropertyGridManager, wxPropertyGridPage, wxPGProperty

# Creating and Populating wxPropertyGrid

As seen here, wxPropertyGrid is constructed in the same way as other wxWidgets controls:

// Necessary header file
#include <wx/propgrid/propgrid.h>
...
// Assumes code is in frame/dialog constructor
// Construct wxPropertyGrid control
wxPropertyGrid* pg = new wxPropertyGrid(
this, // parent
PGID, // id
wxDefaultPosition, // position
wxDefaultSize, // size
// Here are just some of the supported window styles
wxPG_AUTO_SORT | // Automatic sorting after items added
wxPG_SPLITTER_AUTO_CENTER | // Automatically center splitter until user manually adjusts it
// Default style
wxPG_DEFAULT_STYLE );
// Window style flags are at premium, so some less often needed ones are
// available as extra window styles (wxPG_EX_xxx) which must be set using
// SetExtraStyle member function. wxPG_EX_HELP_AS_TOOLTIPS, for instance,
// allows displaying help strings as tool tips.
pg->SetExtraStyle( wxPG_EX_HELP_AS_TOOLTIPS );
wxPropertyGrid
wxPropertyGrid is a specialized grid for editing properties - in other words name = value pairs.
Definition: propgrid.h:491
wxWindow::SetExtraStyle
virtual void SetExtraStyle(long exStyle)
Sets the extra style bits for the window.
wxDefaultSize
const wxSize wxDefaultSize
Global instance of a wxSize object initialized to (-1,-1).
Definition: gdicmn.h:1223
wxDefaultPosition
const wxPoint wxDefaultPosition
Global instance of a wxPoint initialized with values (-1,-1).
Definition: gdicmn.h:814
propgrid.h
wxPG_DEFAULT_STYLE
constexpr long wxPG_DEFAULT_STYLE
Combines various styles.
Definition: propgrid.h:260
wxPG_AUTO_SORT
@ wxPG_AUTO_SORT
This will cause Sort() automatically after an item is added.
Definition: propgrid.h:25
wxPG_SPLITTER_AUTO_CENTER
@ wxPG_SPLITTER_AUTO_CENTER
When wxPropertyGrid is resized, splitter moves to the center.
Definition: propgrid.h:54
wxPG_EX_HELP_AS_TOOLTIPS
@ wxPG_EX_HELP_AS_TOOLTIPS
Show property help strings as tool tips instead as text on the status bar.
Definition: propgrid.h:159

(for complete list of new window styles, see wxPropertyGrid Window Styles)

wxPropertyGrid is usually populated with lines like this:

pg->Append( new wxStringProperty("Label", "Name", "Initial Value") );
wxPropertyGridInterface::Append
wxPGProperty * Append(wxPGProperty *property)
Appends property to the list.
wxStringProperty
Basic property with string value.
Definition: props.h:44

Naturally, wxStringProperty is a property class. Only the first function argument (label) is mandatory. Second one, name, defaults to label and, third, the initial value, to default value. If constant wxPG_LABEL is used as the name argument, then the label is automatically used as a name as well (this is more efficient than manually defining both as the same). Use of empty name is discouraged and will sometimes result in run-time error. Note that all property class constructors have quite similar constructor argument list.

To demonstrate other common property classes, here's another code snippet:

// Add int property
pg->Append( new wxIntProperty("IntProperty", wxPG_LABEL, 12345678) );
// Add float property (value type is actually double)
pg->Append( new wxFloatProperty("FloatProperty", wxPG_LABEL, 12345.678) );
// Add a bool property
pg->Append( new wxBoolProperty("BoolProperty", wxPG_LABEL, false) );
// A string property that can be edited in a separate editor dialog.
pg->Append( new wxLongStringProperty("LongStringProperty",
wxPG_LABEL,
"This is much longer string than the "
"first one. Edit it by clicking the button."));
// String editor with dir selector button.
pg->Append( new wxDirProperty("DirProperty", wxPG_LABEL, ::wxGetUserHome()) );
// wxArrayStringProperty embeds a wxArrayString.
pg->Append( new wxArrayStringProperty("Label of ArrayStringProperty",
"NameOfArrayStringProp"));
// A file selector property.
pg->Append( new wxFileProperty("FileProperty", wxPG_LABEL, wxEmptyString) );
// Extra: set wild card for file property (format same as in wxFileDialog).
pg->SetPropertyAttribute( "FileProperty",
wxPG_FILE_WILDCARD,
"All files (*.*)|*.*" );
wxArrayStringProperty
Property that manages a list of strings.
Definition: props.h:692
wxBoolProperty
Basic property with boolean value.
Definition: props.h:329
wxDirProperty
Like wxLongStringProperty, but the button triggers directory selector instead.
Definition: props.h:665
wxFileProperty
Like wxLongStringProperty, but the button triggers file selector instead.
Definition: props.h:596
wxFloatProperty
Basic property with double-precision floating point value.
Definition: props.h:293
wxIntProperty
Basic property with integer value.
Definition: props.h:208
wxLongStringProperty
Like wxStringProperty, but has a button that triggers a small text editor dialog.
Definition: props.h:638
wxPropertyGridInterface::SetPropertyAttribute
void SetPropertyAttribute(wxPGPropArg id, const wxString &attrName, wxVariant value, wxPGPropertyValuesFlags flags=wxPGPropertyValuesFlags::DontRecurse)
Sets an attribute for this property.
wxGetUserHome
wxString wxGetUserHome(const wxString &user=wxEmptyString)
Returns the home directory for the given user.
wxEmptyString
wxString wxEmptyString
The global wxString instance of an empty string.
Definition: string.h:2064
wxPG_FILE_WILDCARD
#define wxPG_FILE_WILDCARD
wxFileProperty and wxImageFileProperty specific built-in attribute, wxChar*, default is detected/vari...
Definition: property.h:144
wxPG_LABEL
#define wxPG_LABEL
Used to tell wxPGProperty to use label as name as well.
Definition: propgriddefs.h:14

Operations on properties are usually done by directly calling wxPGProperty's or wxPropertyGridInterface's member functions. wxPropertyGridInterface is an abstract base class for property containers such as wxPropertyGrid, wxPropertyGridManager, and wxPropertyGridPage. Note however that wxPGProperty's member functions generally do not refresh the grid.

wxPropertyGridInterface's property operation member functions , such as SetPropertyValue() and DisableProperty(), all accept a special wxPGPropArg id argument, using which you can refer to properties either by their pointer (for performance) or by their name (for convenience). For instance:

// Add a file selector property.
wxPGProperty* prop = pg->Append( new wxFileProperty("FileProperty",
wxPG_LABEL,
wxEmptyString) );
// Valid: Set wild card by name
pg->SetPropertyAttribute( "FileProperty",
wxPG_FILE_WILDCARD,
"All files (*.*)|*.*" );
// Also Valid: Set wild card by property pointer
pg->SetPropertyAttribute( prop,
wxPG_FILE_WILDCARD,
"All files (*.*)|*.*" );
wxPGProperty
wxPGProperty is base class for all wxPropertyGrid properties and as such it is not intended to be ins...
Definition: property.h:877

Using pointer is faster, since it doesn't require hash map lookup. Anyway, you can always get property pointer (wxPGProperty*) as return value from Append() or Insert(), or by calling wxPropertyGridInterface::GetPropertyByName() or just plain GetProperty().

# Categories

wxPropertyGrid has a hierarchic property storage and display model, which allows property categories to hold child properties and even other categories. Other than that, from the programmer's point of view, categories can be treated exactly the same as "other" properties. For example, despite its name, GetPropertyByName() also returns a category by name. Note however that sometimes the label of a property category may be referred as caption (for example, there is wxPropertyGrid::SetCaptionTextColour() method that sets text colour of property category labels).

When category is added at the top (i.e. root) level of the hierarchy, it becomes a current category. This means that all other (non-category) properties after it are automatically appended to it. You may add properties to specific categories by using wxPropertyGridInterface::Insert or wxPropertyGridInterface::AppendIn.

Category code sample:

// One way to add category (similar to how other properties are added)
pg->Append( new wxPropertyCategory("Main") );
// All these are added to "Main" category
pg->Append( new wxStringProperty("Name") );
pg->Append( new wxIntProperty("Age",wxPG_LABEL,25) );
pg->Append( new wxIntProperty("Height",wxPG_LABEL,180) );
pg->Append( new wxIntProperty("Weight") );
// Another one
pg->Append( new wxPropertyCategory("Attributes") );
// All these are added to "Attributes" category
pg->Append( new wxIntProperty("Intelligence") );
pg->Append( new wxIntProperty("Agility") );
pg->Append( new wxIntProperty("Strength") );
wxPropertyCategory
Category (caption) property.
Definition: property.h:2935

# Tree-like Property Structure

Basically any property can have children. There are few limitations, however.

Remarks
  - Names of properties with non-category, non-root parents are not stored in global hash map. Instead, they can be accessed with strings like "Parent.Child". For instance, in the sample below, child property named "Max. Speed (mph)" can be accessed by global name "Car.Speeds.Max Speed (mph)".
  - If you want to property's value to be a string composed of the child property values, you must use wxStringProperty as parent and use magic string "<composed>" as its value.
  - Events (eg. change of value) that occur in parent do not propagate to children. Events that occur in children will propagate to parents, but only if they are wxStringProperties with "<composed>" value.

Sample:

wxPGProperty* carProp = pg->Append(new wxStringProperty("Car",
wxPG_LABEL,
"<composed>"));
pg->AppendIn(carProp, new wxStringProperty("Model",
wxPG_LABEL,
"Lamborghini Diablo SV"));
pg->AppendIn(carProp, new wxIntProperty("Engine Size (cc)",
wxPG_LABEL,
5707) );
wxPGProperty* speedsProp = pg->AppendIn(carProp,
new wxStringProperty("Speeds",
wxPG_LABEL,
"<composed>"));
pg->AppendIn( speedsProp, new wxIntProperty("Max. Speed (mph)",
wxPG_LABEL,290) );
pg->AppendIn( speedsProp, new wxFloatProperty("0-100 mph (sec)",
wxPG_LABEL,3.9) );
pg->AppendIn( speedsProp, new wxFloatProperty("1/4 mile (sec)",
wxPG_LABEL,8.6) );
// This is how child property can be referred to by name
pg->SetPropertyValue( "Car.Speeds.Max. Speed (mph)", 300 );
pg->AppendIn(carProp, new wxIntProperty("Price ($)",
wxPG_LABEL,
300000) );
// Displayed value of "Car" property is now very close to this:
// "Lamborghini Diablo SV; 5707 [300; 3.9; 8.6] 300000"
wxPropertyGridInterface::AppendIn
wxPGProperty * AppendIn(wxPGPropArg id, wxPGProperty *newProperty)
Same as Append(), but appends under given parent property.
wxPropertyGridInterface::SetPropertyValue
void SetPropertyValue(wxPGPropArg id, long value)
Sets value (long integer) of a property.

# wxEnumProperty and wxFlagsProperty

wxEnumProperty is used when you want property's (integer or string) value to be selected from a popup list of choices.

Creating wxEnumProperty is slightly more complex than those described earlier. You have to provide list of constant labels, and optionally relevant values (if label indexes are not sufficient).

Remarks

- Value wxPG_INVALID_VALUE (equals INT_MAX) is not allowed as list item value.

A very simple example:

//
// Using wxArrayString
//
wxArrayString arrDiet;
arrDiet.Add("Herbivore");
arrDiet.Add("Carnivore");
arrDiet.Add("Omnivore");
pg->Append( new wxEnumProperty("Diet",
wxPG_LABEL,
arrDiet) );
//
// Using wxChar* array
//
const wxChar* arrayDiet[] =
{ wxT("Herbivore"), wxT("Carnivore"), wxT("Omnivore"), nullptr };
pg->Append( new wxEnumProperty("Diet",
wxPG_LABEL,
arrayDiet) );
wxArrayString
wxArrayString is a legacy class similar to std::vector<wxString>.
Definition: arrstr.h:67
wxArrayString::Add
size_t Add(const wxString &str, size_t copies=1)
Appends the given number of copies of the new item str to the array and returns the index of the firs...
wxEnumProperty
You can derive custom properties with choices from this class.
Definition: props.h:358
wxT
#define wxT(string)
Macro taking a literal string and expanding into a wide string.
Definition: chartype.h:31
wxChar
wchar_t wxChar
wxChar is a compatibility typedef always defined as wchar_t now.
Definition: chartype.h:90

Here's extended example using values as well:

//
// Using wxArrayString and wxArrayInt
//
wxArrayString arrDiet;
arrDiet.Add("Herbivore");
arrDiet.Add("Carnivore");
arrDiet.Add("Omnivore");
wxArrayInt arrIds;
arrIds.Add(40);
arrIds.Add(45);
arrIds.Add(50);
// Note that the initial value (the last argument) is the actual value,
// not index or anything like that. Thus, our value selects "Omnivore".
pg->Append( new wxEnumProperty("Diet",
wxPG_LABEL,
arrDiet,
arrIds,
50));
wxArrayInt
wxArray< int > wxArrayInt
Predefined specialization of wxArray<T> for standard types.
Definition: dynarray.h:821

wxPGChoices is a class where wxEnumProperty, and other properties which require storage for list of items, actually stores strings and values. It is used to facilitate reference counting, and therefore recommended way of adding items when multiple properties share the same set.

You can use wxPGChoices directly as well, filling it and then passing it to the constructor. In fact, if you wish to display bitmaps next to labels, your best choice is to use this approach.

wxPGChoices chs;
chs.Add("Herbivore", 40);
chs.Add("Carnivore", 45);
chs.Add("Omnivore", 50);
// Let's add an item with bitmap, too
chs.Add("None of the above", wxBitmap(), 60);
pg->Append( new wxEnumProperty("Primary Diet",
wxPG_LABEL,
chs) );
// Add same choices to another property as well - this is efficient due
// to reference counting
pg->Append( new wxEnumProperty("Secondary Diet",
wxPG_LABEL,
chs) );
wxBitmap
This class encapsulates the concept of a platform-dependent bitmap, either monochrome or colour or co...
Definition: bitmap.h:212
wxPGChoices
Helper class for managing choices of wxPropertyGrid properties.
Definition: property.h:2630
wxPGChoices::Add
void Add(size_t count, const wxString *labels, const long *values=nullptr)
Adds to current.

You can later change choices of property by using wxPGProperty::AddChoice(), wxPGProperty::InsertChoice(), wxPGProperty::DeleteChoice(), and wxPGProperty::SetChoices().

wxEditEnumProperty works exactly like wxEnumProperty, except is uses non-read-only combo box as default editor, and value is stored as string when it is not any of the choices.

wxFlagsProperty has similar construction:

const wxChar* flags_prop_labels[] = { wxT("wxICONIZE"),
wxT("wxCAPTION"), wxT("wxMINIMIZE_BOX"), wxT("wxMAXIMIZE_BOX"), nullptr };
// this value array would be optional if values matched string indexes
long flags_prop_values[] = { wxICONIZE, wxCAPTION, wxMINIMIZE_BOX,
wxMAXIMIZE_BOX };
pg->Append( new wxFlagsProperty("Window Style",
wxPG_LABEL,
flags_prop_labels,
flags_prop_values,
wxDEFAULT_FRAME_STYLE) );
wxFlagsProperty
Represents a bit set that fits in a long integer.
Definition: props.h:486
wxMINIMIZE_BOX
#define wxMINIMIZE_BOX
Definition: defs.h:1356
wxMAXIMIZE_BOX
#define wxMAXIMIZE_BOX
Definition: defs.h:1357
wxICONIZE
#define wxICONIZE
Definition: defs.h:1350
wxCAPTION
#define wxCAPTION
Definition: defs.h:218
wxDEFAULT_FRAME_STYLE
#define wxDEFAULT_FRAME_STYLE
Definition: toplevel.h:43

wxFlagsProperty can use wxPGChoices just the same way as wxEnumProperty Note: When changing "choices" (ie. flag labels) of wxFlagsProperty, you will need to use wxPGProperty::SetChoices() to replace all choices at once - otherwise implicit child properties will not get updated properly.

# Specialized Properties

This section describes the use of less often needed property classes. To use them, you have to include <wx/propgrid/advprops.h>.

// Necessary extra header file
#include <wx/propgrid/advprops.h>
...
// Date property.
pg->Append( new wxDateProperty("MyDateProperty",
wxPG_LABEL,
wxDateTime::Now()) );
// Image file property. Wild card is auto-generated from available
// image handlers, so it is not set this time.
pg->Append( new wxImageFileProperty("Label of ImageFileProperty",
"NameOfImageFileProp") );
// Font property has sub-properties. Note that we give window's font as
// initial value.
pg->Append( new wxFontProperty("Font",
wxPG_LABEL,
GetFont()) );
// Colour property with arbitrary colour.
pg->Append( new wxColourProperty("My Colour 1",
wxPG_LABEL,
wxColour(242,109,0) ) );
// System colour property.
pg->Append( new wxSystemColourProperty("My SysColour 1",
wxPG_LABEL,
wxSystemSettings::GetColour(wxSYS_COLOUR_WINDOW)) );
// System colour property with custom colour.
pg->Append( new wxSystemColourProperty("My SysColour 2",
wxPG_LABEL,
wxColour(0,200,160) ) );
// Cursor property
pg->Append( new wxCursorProperty("My Cursor",
wxPG_LABEL,
wxCURSOR_ARROW));
advprops.h
wxColour
A colour is an object representing a combination of Red, Green, and Blue (RGB) intensity values and a...
Definition: colour.h:69
wxColourProperty
Allows to select a colour from the list or with colour dialog.
Definition: advprops.h:180
wxCursorProperty
Property representing wxCursor.
Definition: advprops.h:202
wxDateProperty
Property representing wxDateTime.
Definition: advprops.h:319
wxDateTime::Now
static wxDateTime Now()
Returns the object corresponding to the current time in local time zone.
wxFontProperty
Property representing wxFont.
Definition: advprops.h:73
wxImageFileProperty
Property representing image file(name).
Definition: advprops.h:235
wxSystemColourProperty
Has dropdown list of wxWidgets system colours.
Definition: advprops.h:101
wxSystemSettings::GetColour
static wxColour GetColour(wxSystemColour index)
Returns a system colour.
wxCURSOR_ARROW
@ wxCURSOR_ARROW
A standard arrow cursor.
Definition: gdicmn.h:76
wxSYS_COLOUR_WINDOW
@ wxSYS_COLOUR_WINDOW
Window background colour.
Definition: settings.h:57

# Processing Property Values

Properties store their values internally as wxVariant, but is also possible to obtain them as wxAny, using implicit conversion. You can get property values with wxPGProperty::GetValue() and wxPropertyGridInterface::GetPropertyValue().

Below is a code example which handles wxEVT_PG_CHANGED event:

void MyWindowClass::OnPropertyGridChanged(wxPropertyGridEvent& event)
{
wxPGProperty* property = event.GetProperty();
// Do nothing if event did not have associated property
if ( !property )
return;
// GetValue() returns wxVariant, but it is converted transparently to
// wxAny
wxAny value = property->GetValue();
// Also, handle the case where property value is unspecified
if ( value.IsNull() )
return;
// Handle changes in values, as needed
if ( property->GetName() == "MyStringProperty" )
OnMyStringPropertyChanged(value.As<wxString>());
else if ( property->GetName() == "MyColourProperty" )
OnMyColourPropertyChanged(value.As<wxColour>());
}
wxAny
The wxAny class represents a container for any type.
Definition: any.h:61
wxAny::IsNull
bool IsNull() const
Tests if wxAny is null (that is, whether there is no data).
wxAny::As
T As() const
This template function converts wxAny into given type.
wxPropertyGridEvent
A property grid event holds information about events associated with wxPropertyGrid objects.
Definition: propgrid.h:1347
wxString
String class for passing textual data to or receiving it from wxWidgets.
Definition: string.h:372

You can get a string-representation of property's value using wxPGProperty::GetValueAsString() or wxPropertyGridInterface::GetPropertyValueAsString(). This particular function is very safe to use with any kind of property.

Note
  There is a one case in which you may want to take extra care when dealing with raw wxVariant values. That is, integer-type properties, such as wxIntProperty and wxUIntProperty, store value internally as wx(U)LongLong when number doesn't fit into standard long type. Using << operator to get wx(U)LongLong from wxVariant is customized to work quite safely with various types of variant data. However, you can also bypass this problem by using wxAny in your code instead of wxVariant.

Note that in some cases property value can be Null variant, which means that property value is unspecified. This usually occurs only when wxPG_EX_AUTO_UNSPECIFIED_VALUES extra window style is defined or when you manually set property value to Null (or unspecified).

# Iterating through a property container

You can use somewhat STL'ish iterator classes to iterate through the grid. Here is a simple example of forward iterating through all individual properties (not categories nor private child properties that are normally 'transparent' to application code):

wxPropertyGridIterator it;
for ( it = pg->GetIterator();
!it.AtEnd();
it++ )
{
wxPGProperty* p = *it;
// Do something with the property
}
wxPropertyGridInterface::GetIterator
wxPropertyGridIterator GetIterator(int flags=wxPG_ITERATE_DEFAULT, wxPGProperty *firstProp=nullptr)
Returns iterator class instance.
wxPropertyGridIteratorBase::AtEnd
bool AtEnd() const
wxPropertyGridIterator
Definition: propgridpagestate.h:311

As expected there is also a const iterator:

wxPropertyGridConstIterator it;
for ( it = pg->GetIterator();
!it.AtEnd();
it++ )
{
const wxPGProperty* p = *it;
// Do something with the property
}
wxPropertyGridConstIterator
Const version of wxPropertyGridIterator.
Definition: propgridpagestate.h:327

You can give some arguments to GetIterator to determine which properties get automatically filtered out. For complete list of options, see wxPropertyGridIterator Flags. GetIterator() also accepts other arguments. See wxPropertyGridInterface::GetIterator() for details.

This example reverse-iterates through all visible items:

wxPropertyGridIterator it;
for ( it = pg->GetIterator(wxPG_ITERATE_VISIBLE, wxBOTTOM);
!it.AtEnd();
it-- )
{
wxPGProperty* p = *it;
// Do something with the property
}
wxBOTTOM
@ wxBOTTOM
Definition: defs.h:50
wxPG_ITERATE_VISIBLE
@ wxPG_ITERATE_VISIBLE
Combines all flags needed to iterate through visible properties (i.e.
Definition: propgridpagestate.h:219

GetIterator() only works with wxPropertyGrid and the individual pages of wxPropertyGridManager. In order to iterate through an arbitrary property container (such as entire wxPropertyGridManager), you need to use wxPropertyGridInterface::GetVIterator(). Note however that this virtual iterator is limited to forward iteration.

wxPGVIterator it;
for ( it = manager->GetVIterator(wxPG_ITERATE_ALL);
!it.AtEnd();
it.Next() )
{
wxPGProperty* p = it.GetProperty();
// Do something with the property
}
wxPGVIterator
Definition: propgridpagestate.h:363
wxPGVIterator::Next
void Next()
wxPGVIterator::GetProperty
wxPGProperty * GetProperty() const
wxPGVIterator::AtEnd
bool AtEnd() const
wxPG_ITERATE_ALL
@ wxPG_ITERATE_ALL
Iterate all items.
Definition: propgridpagestate.h:227

# Populating wxPropertyGrid Automatically

## Populating from List of wxVariants

Example of populating an empty wxPropertyGrid from a values stored in an arbitrary list of wxVariants.

// This is a static method that initializes *all* built-in type handlers
// available, including those for wxColour and wxFont. Refers to *all*
// included properties, so when compiling with static library, this
// method may increase the executable size noticeably.
pg->InitAllTypeHandlers();
// Get contents of the grid as a wxVariant list
wxVariant all_values = pg->GetPropertyValues();
// Populate the list with values. If a property with appropriate
// name is not found, it is created according to the type of variant.
pg->SetPropertyValues( my_list_variant );
wxPropertyGridInterface::InitAllTypeHandlers
static void InitAllTypeHandlers()
Initializes all property types.
wxPropertyGridInterface::GetPropertyValues
wxVariant GetPropertyValues(const wxString &listname=wxString(), wxPGProperty *baseparent=nullptr, wxPGPropertyValuesFlags flags=wxPGPropertyValuesFlags::DontRecurse) const
Returns a wxVariant list containing wxVariant versions of all property values.
wxPropertyGridInterface::SetPropertyValues
void SetPropertyValues(const wxVariantList &list, wxPGPropArg defaultCategory=wxNullProperty)
Sets property values from a list of wxVariants.
wxVariant
The wxVariant class represents a container for any type.
Definition: variant.h:170

## Loading Population from a Text-based Storage

Class wxPropertyGridPopulator may be helpful when writing code that loads properties from a text-source. It is used by wxPropertyGrid XRC handler, for example.

## Saving and Restoring User-Editable State

You can use wxPropertyGridInterface::SaveEditableState() and wxPropertyGridInterface::RestoreEditableState() to save and restore user-editable state (selected property, expanded/collapsed properties, selected page, scrolled position, and splitter positions).

# Event Handling

Probably the most important event is the Changed event which occurs when value of any property is changed by the user. Use EVT_PG_CHANGED(id,func) in your event table to use it.

For complete list of event types, see wxPropertyGrid class reference.

However, one type of event that might need focused attention is EVT_PG_CHANGING, which occurs just prior property value is being changed by user. You can acquire pending value using wxPropertyGridEvent::GetValue(), and if it is not acceptable, call wxPropertyGridEvent::Veto() to prevent the value change from taking place.

void MyForm::OnPropertyGridChanging( wxPropertyGridEvent& event )
{
wxPGProperty* property = event.GetProperty();
if ( property == m_pWatchThisProperty )
{
// GetValue() returns the pending value, but is only
// supported by wxEVT_PG_CHANGING.
if ( event.GetValue().GetString() == g_pThisTextIsNotAllowed )
{
event.Veto();
return;
}
}
}
wxPropertyGridEvent::GetValue
wxVariant GetValue() const
Returns value of the associated property.
wxVariant::GetString
wxString GetString() const
Gets the string value.

Remarks
  On Child Property Event Handling
  - For properties which have private, implicit children (wxFontProperty and wxFlagsProperty), events occur for the main parent property only. For other properties events occur for the children themselves. See Tree-like Property Structure.
  - When property's child gets changed, you can use wxPropertyGridEvent::GetMainParent() to obtain its topmost non-category parent (useful, if you have deeply nested properties).

# Help String, Hint and Tool Tips

For each property you can specify two different types of help text. First, you can use wxPropertyGridInterface::SetPropertyHelpString() or wxPGProperty::SetHelpString() to set property's help text. Second, you can use wxPGProperty::SetAttribute() to set property's "Hint" attribute.

Difference between hint and help string is that the hint is shown in an empty property value cell, while help string is shown either in the description text box, as a tool tip, or on the status bar, whichever of these is available.

To enable display of help string as tool tips, you must explicitly use the wxPG_EX_HELP_AS_TOOLTIPS extra window style.

# Validating Property Values

There are various ways to make sure user enters only correct values. First, you can use wxValidators similar to as you would with ordinary controls. Use wxPropertyGridInterface::SetPropertyValidator() to assign wxValidator to property.

Second, you can subclass a property and override wxPGProperty::ValidateValue(), or handle wxEVT_PG_CHANGING for the same effect. Both of these ways do not actually prevent user from temporarily entering invalid text, but they do give you an opportunity to warn the user and block changed value from being committed in a property.

Various validation failure options can be controlled globally with wxPropertyGrid::SetValidationFailureBehavior(), or on an event basis by calling wxEvent::SetValidationFailureBehavior(). Here's a code snippet of how to handle wxEVT_PG_CHANGING, and to set custom failure behaviour and message.

void MyFrame::OnPropertyGridChanging(wxPropertyGridEvent& event)
{
wxPGProperty* property = event.GetProperty();
// You must use wxPropertyGridEvent::GetValue() to access
// the value to be validated.
wxVariant pendingValue = event.GetValue();
if ( property->GetName() == "Font" )
{
// Make sure value is not unspecified
if ( !pendingValue.IsNull() )
{
wxFont font;
font << pendingValue;
// Let's just allow Arial font
if ( font.GetFaceName() != "Arial" )
{
event.Veto();
event.SetValidationFailureBehavior(wxPG_VFB_STAY_IN_PROPERTY |
wxPG_VFB_BEEP |
wxPG_VFB_SHOW_MESSAGEBOX);
}
}
}
}
wxFont
A font is an object which determines the appearance of text.
Definition: font.h:510
wxFont::GetFaceName
virtual wxString GetFaceName() const
Returns the face name associated with the font, or the empty string if there is no face information.
wxVariant::IsNull
bool IsNull() const
Returns true if there is no data associated with this variant, false if there is data.

# Customizing Individual Cell Appearance

You can control text colour, background colour, and attached image of each cell in the property grid. Use wxPropertyGridInterface::SetPropertyCell() or wxPGProperty::SetCell() for this purpose.

In addition, it is possible to control these characteristics for wxPGChoices list items. See wxPGChoices class reference for more info.

# Customizing Keyboard Handling

There is probably one preference for keyboard handling for every developer out there, and as a conveniency control wxPropertyGrid tries to cater for that. By the default arrow keys are used for navigating between properties, and TAB key is used to move focus between the property editor and the first column. When the focus is in the editor, arrow keys usually no longer work for navigation since they are consumed by the editor.

There are mainly two functions which you can use this customize things, wxPropertyGrid::AddActionTrigger() and wxPropertyGrid::DedicateKey(). First one can be used to set a navigation event to occur on a specific key press and the second is used to divert a key from property editors, making it possible for the grid to use keys normally consumed by the focused editors.

For example, let's say you want to have an ENTER-based editing scheme. That is, editor is focused on ENTER press and the next property is selected when the user finishes editing and presses ENTER again. Code like this would accomplish the task:

// Have property editor focus on Enter
propgrid->AddActionTrigger( wxPG_ACTION_EDIT, WXK_RETURN );
// Have Enter work as action trigger even when editor is focused
propgrid->DedicateKey( WXK_RETURN );
// Let Enter also navigate to the next property
propgrid->AddActionTrigger( wxPG_ACTION_NEXT_PROPERTY, WXK_RETURN );
WXK_RETURN
@ WXK_RETURN
Definition: defs.h:910

wxPG_ACTION_EDIT is prioritized above wxPG_ACTION_NEXT_PROPERTY so that the above code can work without conflicts. For a complete list of available actions, see wxPropertyGrid Action Identifiers.

Here's another trick. Normally the up and down cursor keys are consumed by the focused wxTextCtrl editor and as such can't be used for navigating between properties when that editor is focused. However, using DedicateKey() we can change this so that instead of the cursor keys moving the caret inside the wxTextCtrl, they navigate between adjacent properties. As such:

propgrid->DedicateKey(WXK_UP);
propgrid->DedicateKey(WXK_DOWN);
WXK_DOWN
@ WXK_DOWN
Definition: defs.h:953
WXK_UP
@ WXK_UP
Definition: defs.h:951

# Customizing Properties (without sub-classing)

In this section are presented miscellaneous ways to have custom appearance and behaviour for your properties without all the necessary hassle of sub-classing a property class etc.

## Setting Value Image

Every property can have a small value image placed in front of the actual value text. Built-in example of this can be seen with wxColourProperty and wxImageFileProperty, but for others it can be set using wxPropertyGrid::SetPropertyImage method.

## Setting Property's Editor Control(s)

You can set editor control (or controls, in case of a control and button), of any property using wxPropertyGrid::SetPropertyEditor. Editors are passed as wxPGEditor_EditorName, and valid built-in EditorNames are TextCtrl, Choice, ComboBox, CheckBox, TextCtrlAndButton, ChoiceAndButton, SpinCtrl, and DatePickerCtrl. Two last mentioned ones require call to static member function wxPropertyGrid::RegisterAdditionalEditors().

Following example changes wxColourProperty's editor from default Choice to TextCtrlAndButton. wxColourProperty has its internal event handling set up so that button click events of the button will be used to trigger colour selection dialog.

wxPGProperty* colProp = new wxColourProperty("Text Colour");
pg->Append(colProp);
pg->SetPropertyEditor(colProp, wxPGEditor_TextCtrlAndButton);
wxPropertyGridInterface::SetPropertyEditor
void SetPropertyEditor(wxPGPropArg id, const wxPGEditor *editor)
Sets editor for a property.
wxPGEditor_TextCtrlAndButton
wxPGEditor * wxPGEditor_TextCtrlAndButton

Naturally, creating and setting custom editor classes is a possibility as well. For more information, see wxPGEditor class reference.

## Property Attributes Recognized by Editors

SpinCtrl editor can make use of property's "Min", "Max", "Step" and "Wrap" attributes.

## Adding Multiple Buttons Next to an Editor

See wxPGMultiButton class reference.

## Handling Events Passed from Properties

`wxEVT_BUTTON:` Occurs when editor button click is not handled by the property itself (as is the case, for example, if you set property's editor to TextCtrlAndButton from the original TextCtrl).

## Property Attributes

Miscellaneous values, often specific to a property type, can be set using wxPropertyGridInterface::SetPropertyAttribute() and wxPropertyGridInterface::SetPropertyAttributeAll() methods.

Attribute names are strings and values wxVariant. Arbitrary names are allowed in order to store values that are relevant to application only and not property grid. Constant equivalents of all attribute string names are provided. Some of them are defined as cached strings, so using these constants can provide for smaller binary size.

For complete list of attributes, see wxPropertyGrid Property Attribute Identifiers.

# Using wxPropertyGridManager

wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid, which can optionally have tool bar for mode and page selection, and a help text box. For more information, see wxPropertyGridManager class reference.

## wxPropertyGridPage

wxPropertyGridPage is holder of properties for one page in manager. It is derived from wxEvtHandler, so you can subclass it to process page-specific property grid events. Hand over your page instance in wxPropertyGridManager::AddPage().

Please note that the wxPropertyGridPage itself only sports subset of wxPropertyGrid API (but unlike manager, this include item iteration). Naturally it inherits from wxPropertyGridInterface.

For more information, see wxPropertyGridPage class reference.

# Sub-classing wxPropertyGrid and wxPropertyGridManager

Few things to note:

- Only a small percentage of member functions are virtual. If you need more, just e-mail to wx-dev mailing list.
- Data manipulation is done in wxPropertyGridPageState class. So, instead of overriding wxPropertyGrid::Insert(), you'll probably want to override wxPropertyGridPageState::DoInsert(). See header file for details.
- Override wxPropertyGrid::CreateState() to instantiate your derivate wxPropertyGridPageState. For wxPropertyGridManager, you'll need to subclass wxPropertyGridPage instead (since it is derived from wxPropertyGridPageState), and hand over instances in wxPropertyGridManager::AddPage() calls.
- You can use a derivate wxPropertyGrid with manager by overriding wxPropertyGridManager::CreatePropertyGrid() member function.

# Miscellaneous Topics

## Property Name Scope

All properties which parent is category or root can be accessed directly by their base name (ie. name given for property in its constructor). Other properties can be accessed via "ParentsName.BaseName" notation, Naturally, all property names should be unique.

## Non-unique Labels

It is possible to have properties with identical label under same parent. However, care must be taken to ensure that each property still has unique (base) name.

## wxBoolProperty

There are few points about wxBoolProperty that require further discussion:

- wxBoolProperty can be shown as either normal combo box or as a check box. Property attribute wxPG_BOOL_USE_CHECKBOX is used to change this. For example, if you have a wxFlagsProperty, you can set its all items to use check box using the following:

  pg->SetPropertyAttribute("MyFlagsProperty", wxPG_BOOL_USE_CHECKBOX, true, wxPG_RECURSE);
  wxPG_BOOL_USE_CHECKBOX
  #define wxPG_BOOL_USE_CHECKBOX
  wxBoolProperty and wxFlagsProperty specific built-in attribute.
  Definition: property.h:94
  wxPG_RECURSE
  @ wxPG_RECURSE
  Flag for wxPropertyGridInterface::SetProperty* functions, wxPropertyGridInterface::HideProperty(),...
  Definition: propgridiface.h:42

  Following will set all individual bool properties in your control to use check box:

pg->SetPropertyAttributeAll(wxPG_BOOL_USE_CHECKBOX, true);
wxPropertyGridInterface::SetPropertyAttributeAll
void SetPropertyAttributeAll(const wxString &attrName, wxVariant value)
Sets property attribute for all applicable properties.

- Default item names for wxBoolProperty are ["False", "True"]. This can be changed using static function wxPropertyGrid::SetBoolChoices(trueChoice, falseChoice).

## Updates from wxTextCtrl Based Editor

Changes from wxTextCtrl based property editors are committed (ie. wxEVT_PG_CHANGED is sent etc.) only when (1) user presser enter, (2) user moves to edit another property, or (3) when focus leaves the grid.

Because of this, you may find it useful, in some apps, to call wxPropertyGrid::CommitChangesFromEditor() just before you need to do any computations based on property grid values. Note that CommitChangesFromEditor() will dispatch wxEVT_PG_CHANGED with ProcessEvent, so any of your event handlers will be called immediately.

## Centering the Splitter

If you need to center the splitter, but only once when the program starts, then do not use the wxPG_SPLITTER_AUTO_CENTER window style, but the wxPropertyGrid::CenterSplitter() method. However, be sure to call it after the sizer setup and SetSize calls! (ie. usually at the end of the frame/dialog constructor)

Splitter centering behaviour can be customized using wxPropertyGridInterface::SetColumnProportion(). Usually it is used to set non-equal column proportions, which in essence stops the splitter(s) from being 'centered' as such, and instead just auto-resized.

## Setting Splitter Position When Creating Property Grid

Splitter position cannot exceed grid size, and therefore setting it during form creation may fail as initial grid size is often smaller than desired splitter position, especially when sizers are being used.

## wxColourProperty and wxSystemColourProperty

Through sub-classing, these two property classes provide substantial customization features. Subclass wxSystemColourProperty if you want to use wxColourPropertyValue (which features colour type in addition to wxColour), and wxColourProperty if plain wxColour is enough.

Override wxSystemColourProperty::ColourToString() to redefine how colours are printed as strings.

Override wxSystemColourProperty::GetCustomColourIndex() to redefine location of the item that triggers colour picker dialog (default is last).

Override wxSystemColourProperty::GetColour() to determine which colour matches which choice entry.

# Property Class Descriptions

See Supplied Ready-to-use Property Classes