]>
git.saurik.com Git - wxWidgets.git/blob - docs/doxygen/overviews/propgrid.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: topic overview
4 // Author: wxWidgets team
6 // Licence: wxWindows license
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_customizing
43 @li @ref propgrid_usage2
44 @li @ref propgrid_subclassing
45 @li @ref propgrid_misc
46 @li @ref propgrid_proplist
47 @li @ref propgrid_compat
49 @section propgrid_basics Creating and Populating wxPropertyGrid
51 As seen here, wxPropertyGrid is constructed in the same way as
52 other wxWidgets controls:
56 // Necessary header file
57 #include <wx/propgrid/propgrid.h>
61 // Assumes code is in frame/dialog constructor
63 // Construct wxPropertyGrid control
64 wxPropertyGrid* pg = new wxPropertyGrid(
67 wxDefaultPosition, // position
68 wxDefaultSize, // size
69 // Here are just some of the supported window styles
70 wxPG_AUTO_SORT | // Automatic sorting after items added
71 wxPG_SPLITTER_AUTO_CENTER | // Automatically center splitter until user manually adjusts it
75 // Window style flags are at premium, so some less often needed ones are
76 // available as extra window styles (wxPG_EX_xxx) which must be set using
77 // SetExtraStyle member function. wxPG_EX_HELP_AS_TOOLTIPS, for instance,
78 // allows displaying help strings as tool tips.
79 pg->SetExtraStyle( wxPG_EX_HELP_AS_TOOLTIPS );
83 (for complete list of new window styles, see @ref propgrid_window_styles)
85 wxPropertyGrid is usually populated with lines like this:
88 pg->Append( new wxStringProperty("Label", "Name", "Initial Value") );
91 Naturally, wxStringProperty is a property class. Only the first function argument (label)
92 is mandatory. Second one, name, defaults to label and, third, the initial value, to
93 default value. If constant wxPG_LABEL is used as the name argument, then the label is
94 automatically used as a name as well (this is more efficient than manually defining both
95 as the same). Use of empty name is discouraged and will sometimes result in run-time error.
96 Note that all property class constructors have quite similar constructor argument list.
98 To demonstrate other common property classes, here's another code snippet:
103 pg->Append( new wxIntProperty("IntProperty", wxPG_LABEL, 12345678) );
105 // Add float property (value type is actually double)
106 pg->Append( new wxFloatProperty("FloatProperty", wxPG_LABEL, 12345.678) );
108 // Add a bool property
109 pg->Append( new wxBoolProperty("BoolProperty", wxPG_LABEL, false) );
111 // A string property that can be edited in a separate editor dialog.
112 pg->Append( new wxLongStringProperty("LongStringProperty",
114 "This is much longer string than the "
115 "first one. Edit it by clicking the button."));
117 // String editor with dir selector button.
118 pg->Append( new wxDirProperty("DirProperty", wxPG_LABEL, ::wxGetUserHome()) );
120 // wxArrayStringProperty embeds a wxArrayString.
121 pg->Append( new wxArrayStringProperty("Label of ArrayStringProperty",
122 "NameOfArrayStringProp"));
124 // A file selector property.
125 pg->Append( new wxFileProperty("FileProperty", wxPG_LABEL, wxEmptyString) );
127 // Extra: set wild card for file property (format same as in wxFileDialog).
128 pg->SetPropertyAttribute( "FileProperty",
130 "All files (*.*)|*.*" );
134 Operations on properties are usually done by directly calling wxPGProperty's
135 or wxPropertyGridInterface's member functions. wxPropertyGridInterface is an
136 abstract base class for property containers such as wxPropertyGrid,
137 wxPropertyGridManager, and wxPropertyGridPage. Note however that wxPGProperty's
138 member functions generally do not refresh the grid.
140 wxPropertyGridInterface's property operation member functions , such as
141 SetPropertyValue() and DisableProperty(), all accept a special wxPGPropArg id
142 argument, using which you can refer to properties either by their pointer
143 (for performance) or by their name (for convenience). For instance:
146 // Add a file selector property.
147 wxPGPropety* prop = pg->Append( new wxFileProperty("FileProperty",
151 // Valid: Set wild card by name
152 pg->SetPropertyAttribute( "FileProperty",
154 "All files (*.*)|*.*" );
156 // Also Valid: Set wild card by property pointer
157 pg->SetPropertyAttribute( prop,
159 "All files (*.*)|*.*" );
162 Using pointer is faster, since it doesn't require hash map lookup. Anyway,
163 you can always get property pointer (wxPGProperty*) as return value from Append()
164 or Insert(), or by calling wxPropertyGridInterface::GetPropertyByName() or
165 just plain GetProperty().
167 @section propgrid_categories Categories
169 wxPropertyGrid has a hierarchic property storage and display model, which
170 allows property categories to hold child properties and even other
171 categories. Other than that, from the programmer's point of view, categories
172 can be treated exactly the same as "other" properties. For example, despite
173 its name, GetPropertyByName() also returns a category by name. Note however
174 that sometimes the label of a property category may be referred as caption
175 (for example, there is wxPropertyGrid::SetCaptionTextColour() method
176 that sets text colour of property category labels).
178 When category is added at the top (i.e. root) level of the hierarchy,
179 it becomes a *current category*. This means that all other (non-category)
180 properties after it are automatically appended to it. You may add
181 properties to specific categories by using wxPropertyGridInterface::Insert
182 or wxPropertyGridInterface::AppendIn.
184 Category code sample:
188 // One way to add category (similar to how other properties are added)
189 pg->Append( new wxPropertyCategory("Main") );
191 // All these are added to "Main" category
192 pg->Append( new wxStringProperty("Name") );
193 pg->Append( new wxIntProperty("Age",wxPG_LABEL,25) );
194 pg->Append( new wxIntProperty("Height",wxPG_LABEL,180) );
195 pg->Append( new wxIntProperty("Weight") );
198 pg->Append( new wxPropertyCategory("Attributes") );
200 // All these are added to "Attributes" category
201 pg->Append( new wxIntProperty("Intelligence") );
202 pg->Append( new wxIntProperty("Agility") );
203 pg->Append( new wxIntProperty("Strength") );
208 @section propgrid_parentprops Tree-like Property Structure
210 Basically any property can have children. There are few limitations, however.
213 - Names of properties with non-category, non-root parents are not stored in global
214 hash map. Instead, they can be accessed with strings like "Parent.Child".
215 For instance, in the sample below, child property named "Max. Speed (mph)"
216 can be accessed by global name "Car.Speeds.Max Speed (mph)".
217 - If you want to property's value to be a string composed of the child property values,
218 you must use wxStringProperty as parent and use magic string "<composed>" as its
220 - Events (eg. change of value) that occur in parent do not propagate to children. Events
221 that occur in children will propagate to parents, but only if they are wxStringProperties
222 with "<composed>" value.
227 wxPGProperty* carProp = pg->Append(new wxStringProperty("Car",
231 pg->AppendIn(carProp, new wxStringProperty("Model",
233 "Lamborghini Diablo SV"));
235 pg->AppendIn(carProp, new wxIntProperty("Engine Size (cc)",
239 wxPGProperty* speedsProp = pg->AppendIn(carProp,
240 new wxStringProperty("Speeds",
244 pg->AppendIn( speedsProp, new wxIntProperty("Max. Speed (mph)",
246 pg->AppendIn( speedsProp, new wxFloatProperty("0-100 mph (sec)",
248 pg->AppendIn( speedsProp, new wxFloatProperty("1/4 mile (sec)",
251 // This is how child property can be referred to by name
252 pg->SetPropertyValue( "Car.Speeds.Max. Speed (mph)", 300 );
254 pg->AppendIn(carProp, new wxIntProperty("Price ($)",
258 // Displayed value of "Car" property is now very close to this:
259 // "Lamborghini Diablo SV; 5707 [300; 3.9; 8.6] 300000"
263 @section propgrid_enumandflags wxEnumProperty and wxFlagsProperty
265 wxEnumProperty is used when you want property's (integer or string) value
266 to be selected from a popup list of choices.
268 Creating wxEnumProperty is slightly more complex than those described
269 earlier. You have to provide list of constant labels, and optionally relevant
270 values (if label indexes are not sufficient).
274 - Value wxPG_INVALID_VALUE (equals INT_MAX) is not allowed as list
277 A very simple example:
282 // Using wxArrayString
284 wxArrayString arrDiet;
285 arr.Add("Herbivore");
286 arr.Add("Carnivore");
289 pg->Append( new wxEnumProperty("Diet",
294 // Using wxChar* array
296 const wxChar* arrayDiet[] =
297 { wxT("Herbivore"), wxT("Carnivore"), wxT("Omnivore"), NULL };
299 pg->Append( new wxEnumProperty("Diet",
305 Here's extended example using values as well:
310 // Using wxArrayString and wxArrayInt
312 wxArrayString arrDiet;
313 arr.Add("Herbivore");
314 arr.Add("Carnivore");
322 // Note that the initial value (the last argument) is the actual value,
323 // not index or anything like that. Thus, our value selects "Omnivore".
324 pg->Append( new wxEnumProperty("Diet",
332 wxPGChoices is a class where wxEnumProperty, and other properties which
333 require storage for list of items, actually stores strings and values. It is
334 used to facilitate reference counting, and therefore recommended way of
335 adding items when multiple properties share the same set.
337 You can use wxPGChoices directly as well, filling it and then passing it
338 to the constructor. In fact, if you wish to display bitmaps next to labels,
339 your best choice is to use this approach.
344 chs.Add("Herbivore", 40);
345 chs.Add("Carnivore", 45);
346 chs.Add("Omnivore", 50);
348 // Let's add an item with bitmap, too
349 chs.Add("None of the above", wxBitmap(), 60);
351 pg->Append( new wxEnumProperty("Primary Diet",
355 // Add same choices to another property as well - this is efficient due
356 // to reference counting
357 pg->Append( new wxEnumProperty("Secondary Diet",
362 You can later change choices of property by using wxPGProperty::AddChoice(),
363 wxPGProperty::InsertChoice(), wxPGProperty::DeleteChoice(), and
364 wxPGProperty::SetChoices().
366 <b>wxEditEnumProperty</b> works exactly like wxEnumProperty, except
367 is uses non-read-only combo box as default editor, and value is stored as
368 string when it is not any of the choices.
370 wxFlagsProperty has similar construction:
374 const wxChar* flags_prop_labels[] = { wxT("wxICONIZE"),
375 wxT("wxCAPTION"), wxT("wxMINIMIZE_BOX"), wxT("wxMAXIMIZE_BOX"), NULL };
377 // this value array would be optional if values matched string indexes
378 long flags_prop_values[] = { wxICONIZE, wxCAPTION, wxMINIMIZE_BOX,
381 pg->Append( new wxFlagsProperty("Window Style",
385 wxDEFAULT_FRAME_STYLE) );
389 wxFlagsProperty can use wxPGChoices just the same way as wxEnumProperty
390 <b>Note:</b> When changing "choices" (ie. flag labels) of wxFlagsProperty,
391 you will need to use wxPGProperty::SetChoices() to replace all choices
392 at once - otherwise implicit child properties will not get updated properly.
394 @section propgrid_advprops Specialized Properties
396 This section describes the use of less often needed property classes.
397 To use them, you have to include <wx/propgrid/advprops.h>.
401 // Necessary extra header file
402 #include <wx/propgrid/advprops.h>
407 pg->Append( new wxDateProperty("MyDateProperty",
409 wxDateTime::Now()) );
411 // Image file property. Wild card is auto-generated from available
412 // image handlers, so it is not set this time.
413 pg->Append( new wxImageFileProperty("Label of ImageFileProperty",
414 "NameOfImageFileProp") );
416 // Font property has sub-properties. Note that we give window's font as
418 pg->Append( new wxFontProperty("Font",
422 // Colour property with arbitrary colour.
423 pg->Append( new wxColourProperty("My Colour 1",
425 wxColour(242,109,0) ) );
427 // System colour property.
428 pg->Append( new wxSystemColourProperty("My SysColour 1",
430 wxSystemSettings::GetColour(wxSYS_COLOUR_WINDOW)) );
432 // System colour property with custom colour.
433 pg->Append( new wxSystemColourProperty("My SysColour 2",
435 wxColour(0,200,160) ) );
438 pg->Append( new wxCursorProperty("My Cursor",
445 @section propgrid_processingvalues Processing Property Values
447 Properties store their values internally as wxVariant, but is also possible to
448 obtain them as wxAny, using implicit conversion. You can get property
449 values with wxPGProperty::GetValue() and
450 wxPropertyGridInterface::GetPropertyValue().
452 Below is a code example which handles wxEVT_PG_CHANGED event:
456 void MyWindowClass::OnPropertyGridChanged(wxPropertyGridEvent& event)
458 wxPGProperty* property = event.GetProperty();
460 // Do nothing if event did not have associated property
464 // GetValue() returns wxVariant, but it is converted transparently to
466 wxAny value = property->GetValue();
468 // Also, handle the case where property value is unspecified
469 if ( value.IsNull() )
472 // Handle changes in values, as needed
473 if ( property.GetName() == "MyStringProperty" )
474 OnMyStringPropertyChanged(value.As<wxString>());
475 else if ( property.GetName() == "MyColourProperty" )
476 OnMyColourPropertyChanged(value.As<wxColour>());
481 You can get a string-representation of property's value using
482 wxPGProperty::GetValueAsString() or
483 wxPropertyGridInterface::GetPropertyValueAsString(). This particular function
484 is very safe to use with any kind of property.
486 @note There is a one case in which you may want to take extra care when
487 dealing with raw wxVariant values. That is, integer-type properties,
488 such as wxIntProperty and wxUIntProperty, store value internally as
489 wx(U)LongLong when number doesn't fit into standard long type. Using
490 << operator to get wx(U)LongLong from wxVariant is customized to work
491 quite safely with various types of variant data. However, you can also
492 bypass this problem by using wxAny in your code instead of wxVariant.
494 Note that in some cases property value can be Null variant, which means
495 that property value is unspecified. This usually occurs only when
496 wxPG_EX_AUTO_UNSPECIFIED_VALUES extra window style is defined or when you
497 manually set property value to Null (or unspecified).
500 @section propgrid_iterating Iterating through a property container
502 You can use somewhat STL'ish iterator classes to iterate through the grid.
503 Here is a simple example of forward iterating through all individual
504 properties (not categories nor private child properties that are normally
505 'transparent' to application code):
509 wxPropertyGridIterator it;
511 for ( it = pg->GetIterator();
515 wxPGProperty* p = *it;
516 // Do something with the property
521 As expected there is also a const iterator:
525 wxPropertyGridConstIterator it;
527 for ( it = pg->GetIterator();
531 const wxPGProperty* p = *it;
532 // Do something with the property
537 You can give some arguments to GetIterator to determine which properties
538 get automatically filtered out. For complete list of options, see
539 @ref propgrid_iterator_flags. GetIterator() also accepts other arguments.
540 See wxPropertyGridInterface::GetIterator() for details.
542 This example reverse-iterates through all visible items:
546 wxPropertyGridIterator it;
548 for ( it = pg->GetIterator(wxPG_ITERATE_VISIBLE, wxBOTTOM);
552 wxPGProperty* p = *it;
553 // Do something with the property
559 PropertyGridInterface has some useful pythonic iterators as attributes.
560 @c Properties lets you iterate through all items that are not category
561 captions or private children. @c Items lets you iterate through everything
562 except private children. Also, there are GetPyIterator() and GetPyVIterator(),
563 which return pythonic iterators instead of normal wxPropertyGridIterator.
565 If you need to use C++ style iterators in wxPython code, note that
566 Instead of ++ operator, use Next() method, and instead of
567 * operator, use GetProperty() method.
570 GetIterator() only works with wxPropertyGrid and the individual pages
571 of wxPropertyGridManager. In order to iterate through an arbitrary
572 property container (such as entire wxPropertyGridManager), you need to use
573 wxPropertyGridInterface::GetVIterator(). Note however that this virtual
574 iterator is limited to forward iteration.
580 for ( it = manager->GetVIterator();
584 wxPGProperty* p = it.GetProperty();
585 // Do something with the property
590 @section propgrid_populating Populating wxPropertyGrid Automatically
592 @subsection propgrid_fromvariants Populating from List of wxVariants
594 Example of populating an empty wxPropertyGrid from a values stored
595 in an arbitrary list of wxVariants.
599 // This is a static method that initializes *all* built-in type handlers
600 // available, including those for wxColour and wxFont. Refers to *all*
601 // included properties, so when compiling with static library, this
602 // method may increase the executable size noticeably.
603 pg->InitAllTypeHandlers();
605 // Get contents of the grid as a wxVariant list
606 wxVariant all_values = pg->GetPropertyValues();
608 // Populate the list with values. If a property with appropriate
609 // name is not found, it is created according to the type of variant.
610 pg->SetPropertyValues( my_list_variant );
614 @subsection propgrid_fromfile Loading Population from a Text-based Storage
616 Class wxPropertyGridPopulator may be helpful when writing code that
617 loads properties from a text-source. In fact, the wxPropertyGrid xrc-handler
618 (which may not be currently included in wxWidgets, but probably will be in
619 near future) uses it.
621 @subsection editablestate Saving and Restoring User-Editable State
623 You can use wxPropertyGridInterface::SaveEditableState() and
624 wxPropertyGridInterface::RestoreEditableState() to save and restore
625 user-editable state (selected property, expanded/collapsed properties,
626 selected page, scrolled position, and splitter positions).
628 @section propgrid_events Event Handling
630 Probably the most important event is the Changed event which occurs when
631 value of any property is changed by the user. Use EVT_PG_CHANGED(id,func)
632 in your event table to use it.
634 For complete list of event types, see wxPropertyGrid class reference.
636 However, one type of event that might need focused attention is EVT_PG_CHANGING,
637 which occurs just prior property value is being changed by user. You can
638 acquire pending value using wxPropertyGridEvent::GetValue(), and if it is
639 not acceptable, call wxPropertyGridEvent::Veto() to prevent the value change
644 void MyForm::OnPropertyGridChanging( wxPropertyGridEvent& event )
646 wxPGProperty* property = event.GetProperty();
648 if ( property == m_pWatchThisProperty )
650 // GetValue() returns the pending value, but is only
651 // supported by wxEVT_PG_CHANGING.
652 if ( event.GetValue().GetString() == g_pThisTextIsNotAllowed )
662 @remarks On Child Property Event Handling
663 - For properties which have private, implicit children (wxFontProperty and
664 wxFlagsProperty), events occur for the main parent property only.
665 For other properties events occur for the children themselves. See
666 @ref propgrid_parentprops.
668 - When property's child gets changed, you can use wxPropertyGridEvent::GetMainParent()
669 to obtain its topmost non-category parent (useful, if you have deeply nested
672 @section propgrid_tooltipandhint Help String, Hint and Tool Tips
674 For each property you can specify two different types of help text. First,
675 you can use wxPropertyGridInterface::SetPropertyHelpString() or
676 wxPGProperty::SetHelpString() to set property's help text. Second, you
677 can use wxPGProperty::SetAttribute() to set property's "Hint" attribute.
679 Difference between hint and help string is that the hint is shown in an empty
680 property value cell, while help string is shown either in the description text
681 box, as a tool tip, or on the status bar, whichever of these is available.
683 To enable display of help string as tool tips, you must explicitly use
684 the wxPG_EX_HELP_AS_TOOLTIPS extra window style.
686 @section propgrid_validating Validating Property Values
688 There are various ways to make sure user enters only correct values. First, you
689 can use wxValidators similar to as you would with ordinary controls. Use
690 wxPropertyGridInterface::SetPropertyValidator() to assign wxValidator to
693 Second, you can subclass a property and override wxPGProperty::ValidateValue(),
694 or handle wxEVT_PG_CHANGING for the same effect. Both of these ways do not
695 actually prevent user from temporarily entering invalid text, but they do give
696 you an opportunity to warn the user and block changed value from being committed
699 Various validation failure options can be controlled globally with
700 wxPropertyGrid::SetValidationFailureBehavior(), or on an event basis by
701 calling wxEvent::SetValidationFailureBehavior(). Here's a code snippet of
702 how to handle wxEVT_PG_CHANGING, and to set custom failure behaviour and
706 void MyFrame::OnPropertyGridChanging(wxPropertyGridEvent& event)
708 wxPGProperty* property = event.GetProperty();
710 // You must use wxPropertyGridEvent::GetValue() to access
711 // the value to be validated.
712 wxVariant pendingValue = event.GetValue();
714 if ( property->GetName() == "Font" )
716 // Make sure value is not unspecified
717 if ( !pendingValue.IsNull() )
720 font << pendingValue;
722 // Let's just allow Arial font
723 if ( font.GetFaceName() != "Arial" )
726 event.SetValidationFailureBehavior(wxPG_VFB_STAY_IN_PROPERTY |
728 wxPG_VFB_SHOW_MESSAGEBOX);
736 @section propgrid_cellrender Customizing Individual Cell Appearance
738 You can control text colour, background colour, and attached image of
739 each cell in the property grid. Use wxPropertyGridInterface::SetPropertyCell() or
740 wxPGProperty::SetCell() for this purpose.
742 In addition, it is possible to control these characteristics for
743 wxPGChoices list items. See wxPGChoices class reference for more info.
746 @section propgrid_customizing Customizing Properties (without sub-classing)
748 In this section are presented miscellaneous ways to have custom appearance
749 and behavior for your properties without all the necessary hassle
750 of sub-classing a property class etc.
752 @subsection propgrid_customimage Setting Value Image
754 Every property can have a small value image placed in front of the
755 actual value text. Built-in example of this can be seen with
756 wxColourProperty and wxImageFileProperty, but for others it can
757 be set using wxPropertyGrid::SetPropertyImage method.
759 @subsection propgrid_customeditor Setting Property's Editor Control(s)
761 You can set editor control (or controls, in case of a control and button),
762 of any property using wxPropertyGrid::SetPropertyEditor. Editors are passed
763 as wxPGEditor_EditorName, and valid built-in EditorNames are
764 TextCtrl, Choice, ComboBox, CheckBox, TextCtrlAndButton, ChoiceAndButton,
765 SpinCtrl, and DatePickerCtrl. Two last mentioned ones require call to
766 static member function wxPropertyGrid::RegisterAdditionalEditors().
768 Following example changes wxColourProperty's editor from default Choice
769 to TextCtrlAndButton. wxColourProperty has its internal event handling set
770 up so that button click events of the button will be used to trigger
771 colour selection dialog.
775 wxPGProperty* colProp = new wxColourProperty("Text Colour");
777 pg->SetPropertyEditor(colProp, wxPGEditor_TextCtrlAndButton);
781 Naturally, creating and setting custom editor classes is a possibility as
782 well. For more information, see wxPGEditor class reference.
784 @subsection propgrid_editorattrs Property Attributes Recognized by Editors
786 <b>SpinCtrl</b> editor can make use of property's "Min", "Max", "Step" and
789 @subsection propgrid_multiplebuttons Adding Multiple Buttons Next to an Editor
791 See wxPGMultiButton class reference.
793 @subsection propgrid_customeventhandling Handling Events Passed from Properties
795 <b>wxEVT_COMMAND_BUTTON_CLICKED </b>(corresponds to event table macro EVT_BUTTON):
796 Occurs when editor button click is not handled by the property itself
797 (as is the case, for example, if you set property's editor to TextCtrlAndButton
798 from the original TextCtrl).
800 @subsection propgrid_attributes Property Attributes
802 Miscellaneous values, often specific to a property type, can be set
803 using wxPropertyGridInterface::SetPropertyAttribute() and
804 wxPropertyGridInterface::SetPropertyAttributeAll() methods.
806 Attribute names are strings and values wxVariant. Arbitrary names are allowed
807 in order to store values that are relevant to application only and not
808 property grid. Constant equivalents of all attribute string names are
809 provided. Some of them are defined as cached strings, so using these constants
810 can provide for smaller binary size.
812 For complete list of attributes, see @ref propgrid_property_attributes.
815 @section propgrid_usage2 Using wxPropertyGridManager
817 wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
818 which can optionally have tool bar for mode and page selection, and a help text
819 box. For more information, see wxPropertyGridManager class reference.
821 @subsection propgrid_propgridpage wxPropertyGridPage
823 wxPropertyGridPage is holder of properties for one page in manager. It is derived from
824 wxEvtHandler, so you can subclass it to process page-specific property grid events. Hand
825 over your page instance in wxPropertyGridManager::AddPage().
827 Please note that the wxPropertyGridPage itself only sports subset of wxPropertyGrid API
828 (but unlike manager, this include item iteration). Naturally it inherits from
829 wxPropertyGridInterface.
831 For more information, see wxPropertyGridPage class reference.
834 @section propgrid_subclassing Sub-classing wxPropertyGrid and wxPropertyGridManager
838 - Only a small percentage of member functions are virtual. If you need more,
839 just e-mail to wx-dev mailing list.
841 - Data manipulation is done in wxPropertyGridPageState class. So, instead of
842 overriding wxPropertyGrid::Insert(), you'll probably want to override
843 wxPropertyGridPageState::DoInsert(). See header file for details.
845 - Override wxPropertyGrid::CreateState() to instantiate your derivate
846 wxPropertyGridPageState. For wxPropertyGridManager, you'll need to subclass
847 wxPropertyGridPage instead (since it is derived from wxPropertyGridPageState),
848 and hand over instances in wxPropertyGridManager::AddPage() calls.
850 - You can use a derivate wxPropertyGrid with manager by overriding
851 wxPropertyGridManager::CreatePropertyGrid() member function.
854 @section propgrid_misc Miscellaneous Topics
856 @subsection propgrid_namescope Property Name Scope
858 All properties which parent is category or root can be accessed
859 directly by their base name (ie. name given for property in its constructor).
860 Other properties can be accessed via "ParentsName.BaseName" notation,
861 Naturally, all property names should be unique.
863 @subsection propgrid_nonuniquelabels Non-unique Labels
865 It is possible to have properties with identical label under same parent.
866 However, care must be taken to ensure that each property still has
869 @subsection propgrid_boolproperty wxBoolProperty
871 There are few points about wxBoolProperty that require further discussion:
872 - wxBoolProperty can be shown as either normal combo box or as a check box.
873 Property attribute wxPG_BOOL_USE_CHECKBOX is used to change this.
874 For example, if you have a wxFlagsProperty, you can
875 set its all items to use check box using the following:
877 pg->SetPropertyAttribute("MyFlagsProperty", wxPG_BOOL_USE_CHECKBOX, true, wxPG_RECURSE);
880 Following will set all individual bool properties in your control to
884 pg->SetPropertyAttributeAll(wxPG_BOOL_USE_CHECKBOX, true);
887 - Default item names for wxBoolProperty are ["False", "True"]. This can be
888 changed using static function wxPropertyGrid::SetBoolChoices(trueChoice,
891 @subsection propgrid_textctrlupdates Updates from wxTextCtrl Based Editor
893 Changes from wxTextCtrl based property editors are committed (ie.
894 wxEVT_PG_CHANGED is sent etc.) *only* when (1) user presser enter, (2)
895 user moves to edit another property, or (3) when focus leaves
898 Because of this, you may find it useful, in some apps, to call
899 wxPropertyGrid::CommitChangesFromEditor() just before you need to do any
900 computations based on property grid values. Note that CommitChangesFromEditor()
901 will dispatch wxEVT_PG_CHANGED with ProcessEvent, so any of your event handlers
902 will be called immediately.
904 @subsection propgrid_splittercentering Centering the Splitter
906 If you need to center the splitter, but only once when the program starts,
907 then do <b>not</b> use the wxPG_SPLITTER_AUTO_CENTER window style, but the
908 wxPropertyGrid::CenterSplitter() method. <b>However, be sure to call it after
909 the sizer setup and SetSize calls!</b> (ie. usually at the end of the
910 frame/dialog constructor)
912 Splitter centering behavior can be customized using
913 wxPropertyGridInterface::SetColumnProportion(). Usually it is used to set
914 non-equal column proportions, which in essence stops the splitter(s) from
915 being 'centered' as such, and instead just auto-resized.
917 @subsection propgrid_splittersetting Setting Splitter Position When Creating Property Grid
919 Splitter position cannot exceed grid size, and therefore setting it during
920 form creation may fail as initial grid size is often smaller than desired
921 splitter position, especially when sizers are being used.
923 @subsection propgrid_colourproperty wxColourProperty and wxSystemColourProperty
925 Through sub-classing, these two property classes provide substantial customization
926 features. Subclass wxSystemColourProperty if you want to use wxColourPropertyValue
927 (which features colour type in addition to wxColour), and wxColourProperty if plain
930 Override wxSystemColourProperty::ColourToString() to redefine how colours are
933 Override wxSystemColourProperty::GetCustomColourIndex() to redefine location of
934 the item that triggers colour picker dialog (default is last).
936 Override wxSystemColourProperty::GetColour() to determine which colour matches
939 @section propgrid_proplist Property Class Descriptions
941 See @ref pgproperty_properties
943 @section propgrid_compat Changes from wxPropertyGrid 1.4
945 Version of wxPropertyGrid bundled with wxWidgets 2.9+ has various backward-
946 incompatible changes from version 1.4, which had a stable API and will remain
947 as the last separate branch.
949 Note that in general any behavior-breaking changes should not compile or run
950 without warnings or errors.
952 @subsection propgrid_compat_general General Changes
954 - Tab-traversal can no longer be used to travel between properties. Now
955 it only causes focus to move from main grid to editor of selected property.
956 Arrow keys are now your primary means of navigating between properties,
957 with keyboard. This change allowed fixing broken tab traversal on wxGTK
958 (which is open issue in wxPropertyGrid 1.4).
960 - wxPG_EX_UNFOCUS_ON_ENTER style is removed and is now default behavior.
961 That is, when enter is pressed, editing is considered done and focus
962 moves back to the property grid from the editor control.
964 - A few member functions were removed from wxPropertyGridInterface.
965 Please use wxPGProperty's counterparts from now on.
967 - wxPGChoices now has proper Copy-On-Write behavior.
969 - wxPGChoices::SetExclusive() was renamed to AllocExclusive().
971 - wxPGProperty::SetPropertyChoicesExclusive() was removed. Instead, use
972 GetChoices().AllocExclusive().
974 - wxPGProperty::ClearModifiedStatus() is removed. Please use
975 SetModifiedStatus() instead.
977 - wxPropertyGridInterface::GetExpandedProperties() is removed. You should
978 now use wxPropertyGridInterface::GetEditableState() instead.
980 - wxPG_EX_DISABLE_TLP_TRACKING is now enabled by default. To get the old
981 behavior (recommended if you don't use a system that reparents the grid
982 on its own), use the wxPG_EX_ENABLE_TLP_TRACKING extra style.
984 - Extended window style wxPG_EX_LEGACY_VALIDATORS was removed.
986 - Default property validation failure behavior has been changed to
987 (wxPG_VFB_MARK_CELL | wxPG_VFB_SHOW_MESSAGEBOX), which means that the
988 cell is marked red and wxMessageBox is shown. This is more user-friendly
989 than the old behavior, which simply beeped and prevented leaving the
990 property editor until a valid value was entered.
992 - wxPropertyGridManager now has same Get/SetSelection() semantics as
995 - Various wxPropertyGridManager page-related functions now return pointer
996 to the page object instead of index.
998 - Instead of calling wxPropertyGrid::SetButtonShortcut(), use
999 wxPropertyGrid::SetActionTrigger(wxPG_ACTION_PRESS_BUTTON).
1001 - wxPGProperty::GetCell() now returns a reference. AcquireCell() was removed.
1003 - wxPGMultiButton::FinalizePosition() has been renamed to Finalize(),
1004 and it has slightly different argument list.
1006 - wxPropertyGridEvent::HasProperty() is removed. You can use GetProperty()
1007 as immediate replacement when checking if event has a property.
1009 - "InlineHelp" property has been replaced with "Hint".
1011 - wxPropertyGrid::CanClose() has been removed. Call
1012 wxPropertyGridInterface::EditorValidate() instead.
1014 @subsection propgrid_compat_propdev Property and Editor Sub-classing Changes
1016 - Confusing custom property macros have been eliminated.
1018 - Implement wxPGProperty::ValueToString() instead of GetValueAsString().
1020 - wxPGProperty::ChildChanged() must now return the modified value of
1021 whole property instead of writing it back into 'thisValue' argument.
1023 - Removed wxPropertyGrid::PrepareValueForDialogEditing(). Use
1024 wxPropertyGrid::GetPendingEditedValue() instead.
1026 - wxPGProperty::GetChoiceInfo() is removed, as all properties now carry
1027 wxPGChoices instance (protected wxPGProperty::m_choices).
1029 - Connect() should no longer be called in implementations of
1030 wxPGEditor::CreateControls(). wxPropertyGrid automatically passes all
1031 events from editor to wxPGEditor::OnEvent() and wxPGProperty::OnEvent(),
1034 - wxPython: Previously some of the reimplemented member functions needed a
1035 'Py' prefix. This is no longer necessary. For instance, if you previously
1036 implemented PyStringToValue() for your custom property, you should now
1037 just implement StringToValue().