]>
git.saurik.com Git - wxWidgets.git/blob - docs/doxygen/overviews/propgrid.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: topic overview
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
11 @page overview_propgrid wxPropertyGrid Overview
16 @li wxPropertyGridEvent
17 @li wxPropertyGridManager
18 @li wxPropertyGridPage
20 wxPropertyGrid is a specialized grid for editing properties - in other
21 words name = value pairs. List of ready-to-use property classes include
22 strings, numbers, flag sets, fonts, colours and many others. It is possible,
23 for example, to categorize properties, set up a complete tree-hierarchy,
24 add more than two columns, and set arbitrary per-property attributes.
26 As this version of wxPropertyGrid has some backward-incompatible changes
27 from version 1.4, everybody who need to maintain custom property classes
28 should carefully read final section in @ref propgrid_compat.
30 @li @ref propgrid_basics
31 @li @ref propgrid_categories
32 @li @ref propgrid_parentprops
33 @li @ref propgrid_enumandflags
34 @li @ref propgrid_advprops
35 @li @ref propgrid_processingvalues
36 @li @ref propgrid_iterating
37 @li @ref propgrid_events
38 @li @ref propgrid_tooltipandhint
39 @li @ref propgrid_validating
40 @li @ref propgrid_populating
41 @li @ref propgrid_cellrender
42 @li @ref propgrid_keyhandling
43 @li @ref propgrid_customizing
44 @li @ref propgrid_usage2
45 @li @ref propgrid_subclassing
46 @li @ref propgrid_misc
47 @li @ref propgrid_proplist
48 @li @ref propgrid_compat
50 @section propgrid_basics Creating and Populating wxPropertyGrid
52 As seen here, wxPropertyGrid is constructed in the same way as
53 other wxWidgets controls:
57 // Necessary header file
58 #include <wx/propgrid/propgrid.h>
62 // Assumes code is in frame/dialog constructor
64 // Construct wxPropertyGrid control
65 wxPropertyGrid* pg = new wxPropertyGrid(
68 wxDefaultPosition, // position
69 wxDefaultSize, // size
70 // Here are just some of the supported window styles
71 wxPG_AUTO_SORT | // Automatic sorting after items added
72 wxPG_SPLITTER_AUTO_CENTER | // Automatically center splitter until user manually adjusts it
76 // Window style flags are at premium, so some less often needed ones are
77 // available as extra window styles (wxPG_EX_xxx) which must be set using
78 // SetExtraStyle member function. wxPG_EX_HELP_AS_TOOLTIPS, for instance,
79 // allows displaying help strings as tool tips.
80 pg->SetExtraStyle( wxPG_EX_HELP_AS_TOOLTIPS );
84 (for complete list of new window styles, see @ref propgrid_window_styles)
86 wxPropertyGrid is usually populated with lines like this:
89 pg->Append( new wxStringProperty("Label", "Name", "Initial Value") );
92 Naturally, wxStringProperty is a property class. Only the first function argument (label)
93 is mandatory. Second one, name, defaults to label and, third, the initial value, to
94 default value. If constant wxPG_LABEL is used as the name argument, then the label is
95 automatically used as a name as well (this is more efficient than manually defining both
96 as the same). Use of empty name is discouraged and will sometimes result in run-time error.
97 Note that all property class constructors have quite similar constructor argument list.
99 To demonstrate other common property classes, here's another code snippet:
104 pg->Append( new wxIntProperty("IntProperty", wxPG_LABEL, 12345678) );
106 // Add float property (value type is actually double)
107 pg->Append( new wxFloatProperty("FloatProperty", wxPG_LABEL, 12345.678) );
109 // Add a bool property
110 pg->Append( new wxBoolProperty("BoolProperty", wxPG_LABEL, false) );
112 // A string property that can be edited in a separate editor dialog.
113 pg->Append( new wxLongStringProperty("LongStringProperty",
115 "This is much longer string than the "
116 "first one. Edit it by clicking the button."));
118 // String editor with dir selector button.
119 pg->Append( new wxDirProperty("DirProperty", wxPG_LABEL, ::wxGetUserHome()) );
121 // wxArrayStringProperty embeds a wxArrayString.
122 pg->Append( new wxArrayStringProperty("Label of ArrayStringProperty",
123 "NameOfArrayStringProp"));
125 // A file selector property.
126 pg->Append( new wxFileProperty("FileProperty", wxPG_LABEL, wxEmptyString) );
128 // Extra: set wild card for file property (format same as in wxFileDialog).
129 pg->SetPropertyAttribute( "FileProperty",
131 "All files (*.*)|*.*" );
135 Operations on properties are usually done by directly calling wxPGProperty's
136 or wxPropertyGridInterface's member functions. wxPropertyGridInterface is an
137 abstract base class for property containers such as wxPropertyGrid,
138 wxPropertyGridManager, and wxPropertyGridPage. Note however that wxPGProperty's
139 member functions generally do not refresh the grid.
141 wxPropertyGridInterface's property operation member functions , such as
142 SetPropertyValue() and DisableProperty(), all accept a special wxPGPropArg id
143 argument, using which you can refer to properties either by their pointer
144 (for performance) or by their name (for convenience). For instance:
147 // Add a file selector property.
148 wxPGProperty* prop = pg->Append( new wxFileProperty("FileProperty",
152 // Valid: Set wild card by name
153 pg->SetPropertyAttribute( "FileProperty",
155 "All files (*.*)|*.*" );
157 // Also Valid: Set wild card by property pointer
158 pg->SetPropertyAttribute( prop,
160 "All files (*.*)|*.*" );
163 Using pointer is faster, since it doesn't require hash map lookup. Anyway,
164 you can always get property pointer (wxPGProperty*) as return value from Append()
165 or Insert(), or by calling wxPropertyGridInterface::GetPropertyByName() or
166 just plain GetProperty().
168 @section propgrid_categories Categories
170 wxPropertyGrid has a hierarchic property storage and display model, which
171 allows property categories to hold child properties and even other
172 categories. Other than that, from the programmer's point of view, categories
173 can be treated exactly the same as "other" properties. For example, despite
174 its name, GetPropertyByName() also returns a category by name. Note however
175 that sometimes the label of a property category may be referred as caption
176 (for example, there is wxPropertyGrid::SetCaptionTextColour() method
177 that sets text colour of property category labels).
179 When category is added at the top (i.e. root) level of the hierarchy,
180 it becomes a *current category*. This means that all other (non-category)
181 properties after it are automatically appended to it. You may add
182 properties to specific categories by using wxPropertyGridInterface::Insert
183 or wxPropertyGridInterface::AppendIn.
185 Category code sample:
189 // One way to add category (similar to how other properties are added)
190 pg->Append( new wxPropertyCategory("Main") );
192 // All these are added to "Main" category
193 pg->Append( new wxStringProperty("Name") );
194 pg->Append( new wxIntProperty("Age",wxPG_LABEL,25) );
195 pg->Append( new wxIntProperty("Height",wxPG_LABEL,180) );
196 pg->Append( new wxIntProperty("Weight") );
199 pg->Append( new wxPropertyCategory("Attributes") );
201 // All these are added to "Attributes" category
202 pg->Append( new wxIntProperty("Intelligence") );
203 pg->Append( new wxIntProperty("Agility") );
204 pg->Append( new wxIntProperty("Strength") );
209 @section propgrid_parentprops Tree-like Property Structure
211 Basically any property can have children. There are few limitations, however.
214 - Names of properties with non-category, non-root parents are not stored in global
215 hash map. Instead, they can be accessed with strings like "Parent.Child".
216 For instance, in the sample below, child property named "Max. Speed (mph)"
217 can be accessed by global name "Car.Speeds.Max Speed (mph)".
218 - If you want to property's value to be a string composed of the child property values,
219 you must use wxStringProperty as parent and use magic string "<composed>" as its
221 - Events (eg. change of value) that occur in parent do not propagate to children. Events
222 that occur in children will propagate to parents, but only if they are wxStringProperties
223 with "<composed>" value.
228 wxPGProperty* carProp = pg->Append(new wxStringProperty("Car",
232 pg->AppendIn(carProp, new wxStringProperty("Model",
234 "Lamborghini Diablo SV"));
236 pg->AppendIn(carProp, new wxIntProperty("Engine Size (cc)",
240 wxPGProperty* speedsProp = pg->AppendIn(carProp,
241 new wxStringProperty("Speeds",
245 pg->AppendIn( speedsProp, new wxIntProperty("Max. Speed (mph)",
247 pg->AppendIn( speedsProp, new wxFloatProperty("0-100 mph (sec)",
249 pg->AppendIn( speedsProp, new wxFloatProperty("1/4 mile (sec)",
252 // This is how child property can be referred to by name
253 pg->SetPropertyValue( "Car.Speeds.Max. Speed (mph)", 300 );
255 pg->AppendIn(carProp, new wxIntProperty("Price ($)",
259 // Displayed value of "Car" property is now very close to this:
260 // "Lamborghini Diablo SV; 5707 [300; 3.9; 8.6] 300000"
264 @section propgrid_enumandflags wxEnumProperty and wxFlagsProperty
266 wxEnumProperty is used when you want property's (integer or string) value
267 to be selected from a popup list of choices.
269 Creating wxEnumProperty is slightly more complex than those described
270 earlier. You have to provide list of constant labels, and optionally relevant
271 values (if label indexes are not sufficient).
275 - Value wxPG_INVALID_VALUE (equals INT_MAX) is not allowed as list
278 A very simple example:
283 // Using wxArrayString
285 wxArrayString arrDiet;
286 arr.Add("Herbivore");
287 arr.Add("Carnivore");
290 pg->Append( new wxEnumProperty("Diet",
295 // Using wxChar* array
297 const wxChar* arrayDiet[] =
298 { wxT("Herbivore"), wxT("Carnivore"), wxT("Omnivore"), NULL };
300 pg->Append( new wxEnumProperty("Diet",
306 Here's extended example using values as well:
311 // Using wxArrayString and wxArrayInt
313 wxArrayString arrDiet;
314 arr.Add("Herbivore");
315 arr.Add("Carnivore");
323 // Note that the initial value (the last argument) is the actual value,
324 // not index or anything like that. Thus, our value selects "Omnivore".
325 pg->Append( new wxEnumProperty("Diet",
333 wxPGChoices is a class where wxEnumProperty, and other properties which
334 require storage for list of items, actually stores strings and values. It is
335 used to facilitate reference counting, and therefore recommended way of
336 adding items when multiple properties share the same set.
338 You can use wxPGChoices directly as well, filling it and then passing it
339 to the constructor. In fact, if you wish to display bitmaps next to labels,
340 your best choice is to use this approach.
345 chs.Add("Herbivore", 40);
346 chs.Add("Carnivore", 45);
347 chs.Add("Omnivore", 50);
349 // Let's add an item with bitmap, too
350 chs.Add("None of the above", wxBitmap(), 60);
352 pg->Append( new wxEnumProperty("Primary Diet",
356 // Add same choices to another property as well - this is efficient due
357 // to reference counting
358 pg->Append( new wxEnumProperty("Secondary Diet",
363 You can later change choices of property by using wxPGProperty::AddChoice(),
364 wxPGProperty::InsertChoice(), wxPGProperty::DeleteChoice(), and
365 wxPGProperty::SetChoices().
367 <b>wxEditEnumProperty</b> works exactly like wxEnumProperty, except
368 is uses non-read-only combo box as default editor, and value is stored as
369 string when it is not any of the choices.
371 wxFlagsProperty has similar construction:
375 const wxChar* flags_prop_labels[] = { wxT("wxICONIZE"),
376 wxT("wxCAPTION"), wxT("wxMINIMIZE_BOX"), wxT("wxMAXIMIZE_BOX"), NULL };
378 // this value array would be optional if values matched string indexes
379 long flags_prop_values[] = { wxICONIZE, wxCAPTION, wxMINIMIZE_BOX,
382 pg->Append( new wxFlagsProperty("Window Style",
386 wxDEFAULT_FRAME_STYLE) );
390 wxFlagsProperty can use wxPGChoices just the same way as wxEnumProperty
391 <b>Note:</b> When changing "choices" (ie. flag labels) of wxFlagsProperty,
392 you will need to use wxPGProperty::SetChoices() to replace all choices
393 at once - otherwise implicit child properties will not get updated properly.
395 @section propgrid_advprops Specialized Properties
397 This section describes the use of less often needed property classes.
398 To use them, you have to include <wx/propgrid/advprops.h>.
402 // Necessary extra header file
403 #include <wx/propgrid/advprops.h>
408 pg->Append( new wxDateProperty("MyDateProperty",
410 wxDateTime::Now()) );
412 // Image file property. Wild card is auto-generated from available
413 // image handlers, so it is not set this time.
414 pg->Append( new wxImageFileProperty("Label of ImageFileProperty",
415 "NameOfImageFileProp") );
417 // Font property has sub-properties. Note that we give window's font as
419 pg->Append( new wxFontProperty("Font",
423 // Colour property with arbitrary colour.
424 pg->Append( new wxColourProperty("My Colour 1",
426 wxColour(242,109,0) ) );
428 // System colour property.
429 pg->Append( new wxSystemColourProperty("My SysColour 1",
431 wxSystemSettings::GetColour(wxSYS_COLOUR_WINDOW)) );
433 // System colour property with custom colour.
434 pg->Append( new wxSystemColourProperty("My SysColour 2",
436 wxColour(0,200,160) ) );
439 pg->Append( new wxCursorProperty("My Cursor",
446 @section propgrid_processingvalues Processing Property Values
448 Properties store their values internally as wxVariant, but is also possible to
449 obtain them as wxAny, using implicit conversion. You can get property
450 values with wxPGProperty::GetValue() and
451 wxPropertyGridInterface::GetPropertyValue().
453 Below is a code example which handles wxEVT_PG_CHANGED event:
457 void MyWindowClass::OnPropertyGridChanged(wxPropertyGridEvent& event)
459 wxPGProperty* property = event.GetProperty();
461 // Do nothing if event did not have associated property
465 // GetValue() returns wxVariant, but it is converted transparently to
467 wxAny value = property->GetValue();
469 // Also, handle the case where property value is unspecified
470 if ( value.IsNull() )
473 // Handle changes in values, as needed
474 if ( property->GetName() == "MyStringProperty" )
475 OnMyStringPropertyChanged(value.As<wxString>());
476 else if ( property->GetName() == "MyColourProperty" )
477 OnMyColourPropertyChanged(value.As<wxColour>());
482 You can get a string-representation of property's value using
483 wxPGProperty::GetValueAsString() or
484 wxPropertyGridInterface::GetPropertyValueAsString(). This particular function
485 is very safe to use with any kind of property.
487 @note There is a one case in which you may want to take extra care when
488 dealing with raw wxVariant values. That is, integer-type properties,
489 such as wxIntProperty and wxUIntProperty, store value internally as
490 wx(U)LongLong when number doesn't fit into standard long type. Using
491 << operator to get wx(U)LongLong from wxVariant is customized to work
492 quite safely with various types of variant data. However, you can also
493 bypass this problem by using wxAny in your code instead of wxVariant.
495 Note that in some cases property value can be Null variant, which means
496 that property value is unspecified. This usually occurs only when
497 wxPG_EX_AUTO_UNSPECIFIED_VALUES extra window style is defined or when you
498 manually set property value to Null (or unspecified).
501 @section propgrid_iterating Iterating through a property container
503 You can use somewhat STL'ish iterator classes to iterate through the grid.
504 Here is a simple example of forward iterating through all individual
505 properties (not categories nor private child properties that are normally
506 'transparent' to application code):
510 wxPropertyGridIterator it;
512 for ( it = pg->GetIterator();
516 wxPGProperty* p = *it;
517 // Do something with the property
522 As expected there is also a const iterator:
526 wxPropertyGridConstIterator it;
528 for ( it = pg->GetIterator();
532 const wxPGProperty* p = *it;
533 // Do something with the property
538 You can give some arguments to GetIterator to determine which properties
539 get automatically filtered out. For complete list of options, see
540 @ref propgrid_iterator_flags. GetIterator() also accepts other arguments.
541 See wxPropertyGridInterface::GetIterator() for details.
543 This example reverse-iterates through all visible items:
547 wxPropertyGridIterator it;
549 for ( it = pg->GetIterator(wxPG_ITERATE_VISIBLE, wxBOTTOM);
553 wxPGProperty* p = *it;
554 // Do something with the property
559 GetIterator() only works with wxPropertyGrid and the individual pages
560 of wxPropertyGridManager. In order to iterate through an arbitrary
561 property container (such as entire wxPropertyGridManager), you need to use
562 wxPropertyGridInterface::GetVIterator(). Note however that this virtual
563 iterator is limited to forward iteration.
569 for ( it = manager->GetVIterator(wxPG_ITERATE_ALL);
573 wxPGProperty* p = it.GetProperty();
574 // Do something with the property
579 @section propgrid_populating Populating wxPropertyGrid Automatically
581 @subsection propgrid_fromvariants Populating from List of wxVariants
583 Example of populating an empty wxPropertyGrid from a values stored
584 in an arbitrary list of wxVariants.
588 // This is a static method that initializes *all* built-in type handlers
589 // available, including those for wxColour and wxFont. Refers to *all*
590 // included properties, so when compiling with static library, this
591 // method may increase the executable size noticeably.
592 pg->InitAllTypeHandlers();
594 // Get contents of the grid as a wxVariant list
595 wxVariant all_values = pg->GetPropertyValues();
597 // Populate the list with values. If a property with appropriate
598 // name is not found, it is created according to the type of variant.
599 pg->SetPropertyValues( my_list_variant );
603 @subsection propgrid_fromfile Loading Population from a Text-based Storage
605 Class wxPropertyGridPopulator may be helpful when writing code that
606 loads properties from a text-source. In fact, the wxPropertyGrid xrc-handler
607 (which may not be currently included in wxWidgets, but probably will be in
608 near future) uses it.
610 @subsection editablestate Saving and Restoring User-Editable State
612 You can use wxPropertyGridInterface::SaveEditableState() and
613 wxPropertyGridInterface::RestoreEditableState() to save and restore
614 user-editable state (selected property, expanded/collapsed properties,
615 selected page, scrolled position, and splitter positions).
617 @section propgrid_events Event Handling
619 Probably the most important event is the Changed event which occurs when
620 value of any property is changed by the user. Use EVT_PG_CHANGED(id,func)
621 in your event table to use it.
623 For complete list of event types, see wxPropertyGrid class reference.
625 However, one type of event that might need focused attention is EVT_PG_CHANGING,
626 which occurs just prior property value is being changed by user. You can
627 acquire pending value using wxPropertyGridEvent::GetValue(), and if it is
628 not acceptable, call wxPropertyGridEvent::Veto() to prevent the value change
633 void MyForm::OnPropertyGridChanging( wxPropertyGridEvent& event )
635 wxPGProperty* property = event.GetProperty();
637 if ( property == m_pWatchThisProperty )
639 // GetValue() returns the pending value, but is only
640 // supported by wxEVT_PG_CHANGING.
641 if ( event.GetValue().GetString() == g_pThisTextIsNotAllowed )
651 @remarks On Child Property Event Handling
652 - For properties which have private, implicit children (wxFontProperty and
653 wxFlagsProperty), events occur for the main parent property only.
654 For other properties events occur for the children themselves. See
655 @ref propgrid_parentprops.
657 - When property's child gets changed, you can use wxPropertyGridEvent::GetMainParent()
658 to obtain its topmost non-category parent (useful, if you have deeply nested
661 @section propgrid_tooltipandhint Help String, Hint and Tool Tips
663 For each property you can specify two different types of help text. First,
664 you can use wxPropertyGridInterface::SetPropertyHelpString() or
665 wxPGProperty::SetHelpString() to set property's help text. Second, you
666 can use wxPGProperty::SetAttribute() to set property's "Hint" attribute.
668 Difference between hint and help string is that the hint is shown in an empty
669 property value cell, while help string is shown either in the description text
670 box, as a tool tip, or on the status bar, whichever of these is available.
672 To enable display of help string as tool tips, you must explicitly use
673 the wxPG_EX_HELP_AS_TOOLTIPS extra window style.
675 @section propgrid_validating Validating Property Values
677 There are various ways to make sure user enters only correct values. First, you
678 can use wxValidators similar to as you would with ordinary controls. Use
679 wxPropertyGridInterface::SetPropertyValidator() to assign wxValidator to
682 Second, you can subclass a property and override wxPGProperty::ValidateValue(),
683 or handle wxEVT_PG_CHANGING for the same effect. Both of these ways do not
684 actually prevent user from temporarily entering invalid text, but they do give
685 you an opportunity to warn the user and block changed value from being committed
688 Various validation failure options can be controlled globally with
689 wxPropertyGrid::SetValidationFailureBehavior(), or on an event basis by
690 calling wxEvent::SetValidationFailureBehavior(). Here's a code snippet of
691 how to handle wxEVT_PG_CHANGING, and to set custom failure behaviour and
695 void MyFrame::OnPropertyGridChanging(wxPropertyGridEvent& event)
697 wxPGProperty* property = event.GetProperty();
699 // You must use wxPropertyGridEvent::GetValue() to access
700 // the value to be validated.
701 wxVariant pendingValue = event.GetValue();
703 if ( property->GetName() == "Font" )
705 // Make sure value is not unspecified
706 if ( !pendingValue.IsNull() )
709 font << pendingValue;
711 // Let's just allow Arial font
712 if ( font.GetFaceName() != "Arial" )
715 event.SetValidationFailureBehavior(wxPG_VFB_STAY_IN_PROPERTY |
717 wxPG_VFB_SHOW_MESSAGEBOX);
725 @section propgrid_cellrender Customizing Individual Cell Appearance
727 You can control text colour, background colour, and attached image of
728 each cell in the property grid. Use wxPropertyGridInterface::SetPropertyCell() or
729 wxPGProperty::SetCell() for this purpose.
731 In addition, it is possible to control these characteristics for
732 wxPGChoices list items. See wxPGChoices class reference for more info.
734 @section propgrid_keyhandling Customizing Keyboard Handling
736 There is probably one preference for keyboard handling for every developer
737 out there, and as a conveniency control wxPropertyGrid tries to cater for
738 that. By the default arrow keys are used for navigating between properties,
739 and TAB key is used to move focus between the property editor and the
740 first column. When the focus is in the editor, arrow keys usually no longer
741 work for navigation since they are consumed by the editor.
743 There are mainly two functions which you can use this customize things,
744 wxPropertyGrid::AddActionTrigger() and wxPropertyGrid::DedicateKey().
745 First one can be used to set a navigation event to occur on a specific key
746 press and the second is used to divert a key from property editors, making it
747 possible for the grid to use keys normally consumed by the focused editors.
749 For example, let's say you want to have an ENTER-based editing scheme. That
750 is, editor is focused on ENTER press and the next property is selected when
751 the user finishes editing and presses ENTER again. Code like this would
755 // Have property editor focus on Enter
756 propgrid->AddActionTrigger( wxPG_ACTION_EDIT, WXK_RETURN );
758 // Have Enter work as action trigger even when editor is focused
759 propgrid->DedicateKey( WXK_RETURN );
761 // Let Enter also navigate to the next property
762 propgrid->AddActionTrigger( wxPG_ACTION_NEXT_PROPERTY, WXK_RETURN );
766 wxPG_ACTION_EDIT is prioritized above wxPG_ACTION_NEXT_PROPERTY so that the
767 above code can work without conflicts. For a complete list of available
768 actions, see @ref propgrid_keyboard_actions.
770 Here's another trick. Normally the up and down cursor keys are consumed by
771 the focused wxTextCtrl editor and as such can't be used for navigating between
772 properties when that editor is focused. However, using DedicateKey() we can
773 change this so that instead of the cursor keys moving the caret inside the
774 wxTextCtrl, they navigate between adjacent properties. As such:
777 propgrid->DedicateKey(WXK_UP);
778 propgrid->DedicateKey(WXK_DOWN);
782 @section propgrid_customizing Customizing Properties (without sub-classing)
784 In this section are presented miscellaneous ways to have custom appearance
785 and behaviour for your properties without all the necessary hassle
786 of sub-classing a property class etc.
788 @subsection propgrid_customimage Setting Value Image
790 Every property can have a small value image placed in front of the
791 actual value text. Built-in example of this can be seen with
792 wxColourProperty and wxImageFileProperty, but for others it can
793 be set using wxPropertyGrid::SetPropertyImage method.
795 @subsection propgrid_customeditor Setting Property's Editor Control(s)
797 You can set editor control (or controls, in case of a control and button),
798 of any property using wxPropertyGrid::SetPropertyEditor. Editors are passed
799 as wxPGEditor_EditorName, and valid built-in EditorNames are
800 TextCtrl, Choice, ComboBox, CheckBox, TextCtrlAndButton, ChoiceAndButton,
801 SpinCtrl, and DatePickerCtrl. Two last mentioned ones require call to
802 static member function wxPropertyGrid::RegisterAdditionalEditors().
804 Following example changes wxColourProperty's editor from default Choice
805 to TextCtrlAndButton. wxColourProperty has its internal event handling set
806 up so that button click events of the button will be used to trigger
807 colour selection dialog.
811 wxPGProperty* colProp = new wxColourProperty("Text Colour");
813 pg->SetPropertyEditor(colProp, wxPGEditor_TextCtrlAndButton);
817 Naturally, creating and setting custom editor classes is a possibility as
818 well. For more information, see wxPGEditor class reference.
820 @subsection propgrid_editorattrs Property Attributes Recognized by Editors
822 <b>SpinCtrl</b> editor can make use of property's "Min", "Max", "Step" and
825 @subsection propgrid_multiplebuttons Adding Multiple Buttons Next to an Editor
827 See wxPGMultiButton class reference.
829 @subsection propgrid_customeventhandling Handling Events Passed from Properties
831 <b>wxEVT_COMMAND_BUTTON_CLICKED </b>(corresponds to event table macro EVT_BUTTON):
832 Occurs when editor button click is not handled by the property itself
833 (as is the case, for example, if you set property's editor to TextCtrlAndButton
834 from the original TextCtrl).
836 @subsection propgrid_attributes Property Attributes
838 Miscellaneous values, often specific to a property type, can be set
839 using wxPropertyGridInterface::SetPropertyAttribute() and
840 wxPropertyGridInterface::SetPropertyAttributeAll() methods.
842 Attribute names are strings and values wxVariant. Arbitrary names are allowed
843 in order to store values that are relevant to application only and not
844 property grid. Constant equivalents of all attribute string names are
845 provided. Some of them are defined as cached strings, so using these constants
846 can provide for smaller binary size.
848 For complete list of attributes, see @ref propgrid_property_attributes.
851 @section propgrid_usage2 Using wxPropertyGridManager
853 wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
854 which can optionally have tool bar for mode and page selection, and a help text
855 box. For more information, see wxPropertyGridManager class reference.
857 @subsection propgrid_propgridpage wxPropertyGridPage
859 wxPropertyGridPage is holder of properties for one page in manager. It is derived from
860 wxEvtHandler, so you can subclass it to process page-specific property grid events. Hand
861 over your page instance in wxPropertyGridManager::AddPage().
863 Please note that the wxPropertyGridPage itself only sports subset of wxPropertyGrid API
864 (but unlike manager, this include item iteration). Naturally it inherits from
865 wxPropertyGridInterface.
867 For more information, see wxPropertyGridPage class reference.
870 @section propgrid_subclassing Sub-classing wxPropertyGrid and wxPropertyGridManager
874 - Only a small percentage of member functions are virtual. If you need more,
875 just e-mail to wx-dev mailing list.
877 - Data manipulation is done in wxPropertyGridPageState class. So, instead of
878 overriding wxPropertyGrid::Insert(), you'll probably want to override
879 wxPropertyGridPageState::DoInsert(). See header file for details.
881 - Override wxPropertyGrid::CreateState() to instantiate your derivate
882 wxPropertyGridPageState. For wxPropertyGridManager, you'll need to subclass
883 wxPropertyGridPage instead (since it is derived from wxPropertyGridPageState),
884 and hand over instances in wxPropertyGridManager::AddPage() calls.
886 - You can use a derivate wxPropertyGrid with manager by overriding
887 wxPropertyGridManager::CreatePropertyGrid() member function.
890 @section propgrid_misc Miscellaneous Topics
892 @subsection propgrid_namescope Property Name Scope
894 All properties which parent is category or root can be accessed
895 directly by their base name (ie. name given for property in its constructor).
896 Other properties can be accessed via "ParentsName.BaseName" notation,
897 Naturally, all property names should be unique.
899 @subsection propgrid_nonuniquelabels Non-unique Labels
901 It is possible to have properties with identical label under same parent.
902 However, care must be taken to ensure that each property still has
905 @subsection propgrid_boolproperty wxBoolProperty
907 There are few points about wxBoolProperty that require further discussion:
908 - wxBoolProperty can be shown as either normal combo box or as a check box.
909 Property attribute wxPG_BOOL_USE_CHECKBOX is used to change this.
910 For example, if you have a wxFlagsProperty, you can
911 set its all items to use check box using the following:
913 pg->SetPropertyAttribute("MyFlagsProperty", wxPG_BOOL_USE_CHECKBOX, true, wxPG_RECURSE);
916 Following will set all individual bool properties in your control to
920 pg->SetPropertyAttributeAll(wxPG_BOOL_USE_CHECKBOX, true);
923 - Default item names for wxBoolProperty are ["False", "True"]. This can be
924 changed using static function wxPropertyGrid::SetBoolChoices(trueChoice,
927 @subsection propgrid_textctrlupdates Updates from wxTextCtrl Based Editor
929 Changes from wxTextCtrl based property editors are committed (ie.
930 wxEVT_PG_CHANGED is sent etc.) *only* when (1) user presser enter, (2)
931 user moves to edit another property, or (3) when focus leaves
934 Because of this, you may find it useful, in some apps, to call
935 wxPropertyGrid::CommitChangesFromEditor() just before you need to do any
936 computations based on property grid values. Note that CommitChangesFromEditor()
937 will dispatch wxEVT_PG_CHANGED with ProcessEvent, so any of your event handlers
938 will be called immediately.
940 @subsection propgrid_splittercentering Centering the Splitter
942 If you need to center the splitter, but only once when the program starts,
943 then do <b>not</b> use the wxPG_SPLITTER_AUTO_CENTER window style, but the
944 wxPropertyGrid::CenterSplitter() method. <b>However, be sure to call it after
945 the sizer setup and SetSize calls!</b> (ie. usually at the end of the
946 frame/dialog constructor)
948 Splitter centering behaviour can be customized using
949 wxPropertyGridInterface::SetColumnProportion(). Usually it is used to set
950 non-equal column proportions, which in essence stops the splitter(s) from
951 being 'centered' as such, and instead just auto-resized.
953 @subsection propgrid_splittersetting Setting Splitter Position When Creating Property Grid
955 Splitter position cannot exceed grid size, and therefore setting it during
956 form creation may fail as initial grid size is often smaller than desired
957 splitter position, especially when sizers are being used.
959 @subsection propgrid_colourproperty wxColourProperty and wxSystemColourProperty
961 Through sub-classing, these two property classes provide substantial customization
962 features. Subclass wxSystemColourProperty if you want to use wxColourPropertyValue
963 (which features colour type in addition to wxColour), and wxColourProperty if plain
966 Override wxSystemColourProperty::ColourToString() to redefine how colours are
969 Override wxSystemColourProperty::GetCustomColourIndex() to redefine location of
970 the item that triggers colour picker dialog (default is last).
972 Override wxSystemColourProperty::GetColour() to determine which colour matches
975 @section propgrid_proplist Property Class Descriptions
977 See @ref pgproperty_properties
979 @section propgrid_compat Changes from wxPropertyGrid 1.4
981 Version of wxPropertyGrid bundled with wxWidgets 2.9+ has various backward-
982 incompatible changes from version 1.4, which had a stable API and will remain
983 as the last separate branch.
985 Note that in general any behaviour-breaking changes should not compile or run
986 without warnings or errors.
988 @subsection propgrid_compat_general General Changes
990 - Tab-traversal can no longer be used to travel between properties. Now
991 it only causes focus to move from main grid to editor of selected property.
992 Arrow keys are now your primary means of navigating between properties,
993 with keyboard. This change allowed fixing broken tab traversal on wxGTK
994 (which is open issue in wxPropertyGrid 1.4).
996 - wxPG_EX_UNFOCUS_ON_ENTER style is removed and is now default behaviour.
997 That is, when enter is pressed, editing is considered done and focus
998 moves back to the property grid from the editor control.
1000 - A few member functions were removed from wxPropertyGridInterface.
1001 Please use wxPGProperty's counterparts from now on.
1003 - wxPGChoices now has proper Copy-On-Write behaviour.
1005 - wxPGChoices::SetExclusive() was renamed to AllocExclusive().
1007 - wxPGProperty::SetPropertyChoicesExclusive() was removed. Instead, use
1008 GetChoices().AllocExclusive().
1010 - wxPGProperty::ClearModifiedStatus() is removed. Please use
1011 SetModifiedStatus() instead.
1013 - wxPropertyGridInterface::GetExpandedProperties() is removed. You should
1014 now use wxPropertyGridInterface::GetEditableState() instead.
1016 - wxPG_EX_DISABLE_TLP_TRACKING is now enabled by default. To get the old
1017 behaviour (recommended if you don't use a system that reparents the grid
1018 on its own), use the wxPG_EX_ENABLE_TLP_TRACKING extra style.
1020 - Extended window style wxPG_EX_LEGACY_VALIDATORS was removed.
1022 - Default property validation failure behaviour has been changed to
1023 (wxPG_VFB_MARK_CELL | wxPG_VFB_SHOW_MESSAGEBOX), which means that the
1024 cell is marked red and wxMessageBox is shown. This is more user-friendly
1025 than the old behaviour, which simply beeped and prevented leaving the
1026 property editor until a valid value was entered.
1028 - wxPropertyGridManager now has same Get/SetSelection() semantics as
1031 - Various wxPropertyGridManager page-related functions now return pointer
1032 to the page object instead of index.
1034 - wxArrayEditorDialog used by wxArrayStringProperty and some sample
1035 properties has been renamed to wxPGArrayEditorDialog. Also, it now uses
1036 wxEditableListBox for editing.
1038 - Instead of calling wxPropertyGrid::SetButtonShortcut(), use
1039 wxPropertyGrid::SetActionTrigger(wxPG_ACTION_PRESS_BUTTON).
1041 - wxPGProperty::GetCell() now returns a reference. AcquireCell() was removed.
1043 - wxPGMultiButton::FinalizePosition() has been renamed to Finalize(),
1044 and it has slightly different argument list.
1046 - wxPropertyGridEvent::HasProperty() is removed. You can use GetProperty()
1047 as immediate replacement when checking if event has a property.
1049 - "InlineHelp" property has been replaced with "Hint".
1051 - wxPropertyGrid::CanClose() has been removed. Call
1052 wxPropertyGridInterface::EditorValidate() instead.
1054 - wxPGProperty::SetFlag() has been moved to private API. This was done to
1055 underline the fact that it was not the preferred method to change a
1056 property's state since it never had any desired side-effects. ChangeFlag()
1057 still exists for those who really need to achieve the same effect.
1059 - wxArrayStringProperty default delimiter is now comma (','), and it can
1060 be changed by setting the new "Delimiter" attribute.
1062 @subsection propgrid_compat_propdev Property and Editor Sub-classing Changes
1064 - Confusing custom property macros have been eliminated.
1066 - Implement wxPGProperty::ValueToString() instead of GetValueAsString().
1068 - wxPGProperty::ChildChanged() must now return the modified value of
1069 whole property instead of writing it back into 'thisValue' argument.
1071 - Removed wxPropertyGrid::PrepareValueForDialogEditing(). Use
1072 wxPropertyGrid::GetPendingEditedValue() instead.
1074 - wxPGProperty::GetChoiceInfo() is removed, as all properties now carry
1075 wxPGChoices instance (protected wxPGProperty::m_choices).
1077 - Connect() should no longer be called in implementations of
1078 wxPGEditor::CreateControls(). wxPropertyGrid automatically passes all
1079 events from editor to wxPGEditor::OnEvent() and wxPGProperty::OnEvent(),
1082 - wxPython: Previously some of the reimplemented member functions needed a
1083 'Py' prefix. This is no longer necessary. For instance, if you previously
1084 implemented PyStringToValue() for your custom property, you should now
1085 just implement StringToValue().