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.
As this version of wxPropertyGrid has some backward-incompatible changes from version 1.4, everybody who need to maintain custom property classes should carefully read final section in Changes from wxPropertyGrid 1.4.
// 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 );
(for complete list of new window styles, see wxPropertyGrid Window Styles)
wxPropertyGrid is usually populated with lines like this:
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(wxT("IntProperty"), wxPG_LABEL, 12345678) ); // Add float property (value type is actually double) pg->Append( new wxFloatProperty(wxT("FloatProperty"), wxPG_LABEL, 12345.678) ); // Add a bool property pg->Append( new wxBoolProperty(wxT("BoolProperty"), wxPG_LABEL, false) ); // A string property that can be edited in a separate editor dialog. pg->Append( new wxLongStringProperty(wxT("LongStringProperty"), wxPG_LABEL, wxT("This is much longer string than the ") wxT("first one. Edit it by clicking the button."))); // String editor with dir selector button. pg->Append( new wxDirProperty(wxT("DirProperty"), wxPG_LABEL, ::wxGetUserHome()) ); // wxArrayStringProperty embeds a wxArrayString. pg->Append( new wxArrayStringProperty(wxT("Label of ArrayStringProperty"), wxT("NameOfArrayStringProp"))); // A file selector property. pg->Append( new wxFileProperty(wxT("FileProperty"), wxPG_LABEL, wxEmptyString) ); // Extra: set wild card for file property (format same as in wxFileDialog). pg->SetPropertyAttribute( wxT("FileProperty"), wxPG_FILE_WILDCARD, wxT("All files (*.*)|*.*") );
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. wxPGPropety* prop = pg->Append( new wxFileProperty(wxT("FileProperty"), wxPG_LABEL, wxEmptyString) ); // Valid: Set wild card by name pg->SetPropertyAttribute( wxT("FileProperty"), wxPG_FILE_WILDCARD, wxT("All files (*.*)|*.*") ); // Also Valid: Set wild card by property pointer pg->SetPropertyAttribute( prop, wxPG_FILE_WILDCARD, wxT("All files (*.*)|*.*") );
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().
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(wxT("Main")) ); // All these are added to "Main" category pg->Append( new wxStringProperty(wxT("Name")) ); pg->Append( new wxIntProperty(wxT("Age"),wxPG_LABEL,25) ); pg->Append( new wxIntProperty(wxT("Height"),wxPG_LABEL,180) ); pg->Append( new wxIntProperty(wxT("Weight")) ); // Another one pg->Append( new wxPropertyCategory(wxT("Attributes")) ); // All these are added to "Attributes" category pg->Append( new wxIntProperty(wxT("Intelligence")) ); pg->Append( new wxIntProperty(wxT("Agility")) ); pg->Append( new wxIntProperty(wxT("Strength")) );
wxPGProperty* carProp = pg->Append(new wxStringProperty(wxT("Car"), wxPG_LABEL, wxT("<composed>"))); pg->AppendIn(carProp, new wxStringProperty(wxT("Model"), wxPG_LABEL, wxT("Lamborghini Diablo SV"))); pg->AppendIn(carProp, new wxIntProperty(wxT("Engine Size (cc)"), wxPG_LABEL, 5707) ); wxPGProperty* speedsProp = pg->AppendIn(carProp, new wxStringProperty(wxT("Speeds"), wxPG_LABEL, wxT("<composed>"))); pg->AppendIn( speedsProp, new wxIntProperty(wxT("Max. Speed (mph)"), wxPG_LABEL,290) ); pg->AppendIn( speedsProp, new wxFloatProperty(wxT("0-100 mph (sec)"), wxPG_LABEL,3.9) ); pg->AppendIn( speedsProp, new wxFloatProperty(wxT("1/4 mile (sec)"), wxPG_LABEL,8.6) ); // This is how child property can be referred to by name pg->SetPropertyValue( wxT("Car.Speeds.Max. Speed (mph)"), 300 ); pg->AppendIn(carProp, new wxIntProperty(wxT("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"
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).
A very simple example:
// // Using wxArrayString // wxArrayString arrDiet; arr.Add(wxT("Herbivore")); arr.Add(wxT("Carnivore")); arr.Add(wxT("Omnivore")); pg->Append( new wxEnumProperty(wxT("Diet"), wxPG_LABEL, arrDiet) ); // // Using wxChar* array // const wxChar* arrayDiet[] = { wxT("Herbivore"), wxT("Carnivore"), wxT("Omnivore"), NULL }; pg->Append( new wxEnumProperty(wxT("Diet"), wxPG_LABEL, arrayDiet) );
Here's extended example using values as well:
// // Using wxArrayString and wxArrayInt // wxArrayString arrDiet; arr.Add(wxT("Herbivore")); arr.Add(wxT("Carnivore")); arr.Add(wxT("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(wxT("Diet"), wxPG_LABEL, arrDiet, arrIds, 50));
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(wxT("Herbivore"), 40); chs.Add(wxT("Carnivore"), 45); chs.Add(wxT("Omnivore"), 50); // Let's add an item with bitmap, too chs.Add(wxT("None of the above"), wxBitmap(), 60); pg->Append( new wxEnumProperty(wxT("Primary Diet"), wxPG_LABEL, chs) ); // Add same choices to another property as well - this is efficient due // to reference counting pg->Append( new wxEnumProperty(wxT("Secondary Diet"), wxPG_LABEL, chs) );
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"), NULL }; // 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(wxT("Window Style"), wxPG_LABEL, flags_prop_labels, flags_prop_values, wxDEFAULT_FRAME_STYLE) );
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.
// Necessary extra header file #include <wx/propgrid/advprops.h> ... // Date property. pg->Append( new wxDateProperty(wxT("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(wxT("Label of ImageFileProperty"), wxT("NameOfImageFileProp")) ); // Font property has sub-properties. Note that we give window's font as // initial value. pg->Append( new wxFontProperty(wxT("Font"), wxPG_LABEL, GetFont()) ); // Colour property with arbitrary colour. pg->Append( new wxColourProperty(wxT("My Colour 1"), wxPG_LABEL, wxColour(242,109,0) ) ); // System colour property. pg->Append( new wxSystemColourProperty(wxT("My SysColour 1"), wxPG_LABEL, wxSystemSettings::GetColour(wxSYS_COLOUR_WINDOW)) ); // System colour property with custom colour. pg->Append( new wxSystemColourProperty(wxT("My SysColour 2"), wxPG_LABEL, wxColour(0,200,160) ) ); // Cursor property pg->Append( new wxCursorProperty(wxT("My Cursor"), wxPG_LABEL, wxCURSOR_ARROW));
If you wish to obtain property value in specific data type, you can call various getter functions, such as wxPropertyGridInterface:: GetPropertyValueAsString(), which, as name might say, returns property value's string representation. While this particular function is very safe to use for any kind of property, some might display error message if property value is not in compatible enough format. For instance, wxPropertyGridInterface::GetPropertyValueAsLongLong() will support long as well as wxLongLong, but GetPropertyValueAsArrayString() only supports wxArrayString and nothing else.
In any case, you will need to take extra care when dealing with raw wxVariant values. For instance, 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.
You may have noticed that properties store, in wxVariant, values of many types which are not natively supported by it. Custom wxVariantDatas are therefore implemented and << and >> operators implemented to convert data from and to 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).
wxPropertyGridIterator it; for ( it = pg->GetIterator(); !it.AtEnd(); it++ ) { wxPGProperty* p = *it; // Do something with the property }
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 }
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 }
wxPython Note: Instead of ++ operator, use Next() method, and instead of operator, use GetProperty() method.
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(); !it.AtEnd(); it.Next() ) { wxPGProperty* p = it.GetProperty(); // Do something with the property }
// 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 );
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; } } }
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() == wxT("Font") ) { // Make sure value is not unspecified if ( !pendingValue.IsNull() ) { wxFont font; font << pendingValue; // Let's just allow Arial font if ( font.GetFaceName() != wxT("Arial") ) { event.Veto(); event.SetValidationFailureBehavior(wxPG_VFB_STAY_IN_PROPERTY | wxPG_VFB_BEEP | wxPG_VFB_SHOW_MESSAGE); } } } }
In addition, it is possible to control these characteristics for wxPGChoices list items. See wxPGChoices class reference for more info.
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(wxT("Text Colour")); pg->Append(colProp); pg->SetPropertyEditor(colProp, wxPGEditor_TextCtrlAndButton);
Naturally, creating and setting custom editor classes is a possibility as well. For more information, see wxPGEditor class reference.
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.
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.
pg->SetPropertyAttribute(wxT("MyFlagsProperty"),wxPG_BOOL_USE_CHECKBOX,true,wxPG_RECURSE);
Following will set all individual bool properties in your control to use check box:
pg->SetPropertyAttributeAll(wxPG_BOOL_USE_CHECKBOX, true);
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.
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.
Note that in general any behavior-breaking changes should not compile or run without warnings or errors.
![]() |
[ top ] |