A lot of documentation revision. Updated doctest code in propgrid sample to reflect sample code on overview page.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@55766 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/doxygen/groups/class_propgrid.h

@@ -12,9 +12,9 @@
 @ingroup group_class
 
 wxPropertyGrid is a specialized grid for editing properties (that is,
-name=value pairs).
+name=value pairs). This style of control has also been known as
+property sheet or object grid.
 
 Related Overviews: @ref overview_propgrid
 
 */
-

docs/doxygen/overviews/propgrid.h

@@ -17,18 +17,19 @@ Key Classes:
 @li wxPropertyGridManager
 @li wxPropertyGridPage
 
-  wxPropertyGrid is a specialized grid for editing properties such as strings,
+  wxPropertyGrid is a specialized grid for editing properties - in other
-numbers, flagsets, fonts, and colours. It is possible, for example, to categorize
+words name = value pairs. List of ready-to-use property classes include
-properties, set up a complete tree-hierarchy, add multiple columns, and set
+strings, numbers, flag sets, fonts, colours and many others. It is possible,
-arbitrary per-property attributes.
+for example, to categorize properties, set up a complete tree-hierarchy,
+add more than two columns, and set arbitrary per-property attributes.
 
 @li @ref propgrid_basics
 @li @ref propgrid_categories
 @li @ref propgrid_parentprops
 @li @ref propgrid_enumandflags
 @li @ref propgrid_advprops
+@li @ref propgrid_processingvalues
 @li @ref propgrid_iterating
-@li @ref propgrid_operations
 @li @ref propgrid_events
 @li @ref propgrid_validating
 @li @ref propgrid_populating
@@ -38,10 +39,6 @@ arbitrary per-property attributes.
 @li @ref propgrid_subclassing
 @li @ref propgrid_misc
 @li @ref propgrid_proplist
-@li @ref propgrid_userhelp
-@li @ref propgrid_notes
-@li @ref propgrid_newprops
-@li @ref propgrid_neweditors
 
 @section propgrid_basics Creating and Populating wxPropertyGrid
 
@@ -72,7 +69,7 @@ other wxWidgets controls:
     // 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 tooltips.
+    // allows displaying help strings as tool tips.
     pg->SetExtraStyle( wxPG_EX_HELP_AS_TOOLTIPS );
 
 @endcode
@@ -121,97 +118,62 @@ To demonstrate other common property classes, here's another code snippet:
     // A file selector property.
     pg->Append( new wxFileProperty(wxT("FileProperty"), wxPG_LABEL, wxEmptyString) );
 
-    // Extra: set wildcard for file property (format same as in wxFileDialog).
+    // Extra: set wild card for file property (format same as in wxFileDialog).
     pg->SetPropertyAttribute( wxT("FileProperty"),
                               wxPG_FILE_WILDCARD,
                               wxT("All files (*.*)|*.*") );
 
 @endcode
 
-  Operations on properties should be done either via wxPropertyGrid's
+  Operations on properties are usually done by directly calling wxPGProperty's
-(or wxPropertyGridManager's) methods, or by acquiring pointer to a property
+or wxPropertyGridInterface's member functions. wxPropertyGridInterface is an
-(Append returns a wxPGProperty* or wxPGId, which is typedef for same), and then
+abstract base class for property containers such as wxPropertyGrid,
-calling its method. Note however that property's methods generally do not
+wxPropertyGridManager, and wxPropertyGridPage. Note however that wxPGProperty's
-automatically update grid graphics.
+member functions generally do not refresh the grid.
 
-  Property container functions operating on properties, such as SetPropertyValue or
+  wxPropertyGridInterface's property operation member functions , such as
-DisableProperty, all accept a special wxPGPropArg, argument which can automatically
+SetPropertyValue() and DisableProperty(), all accept a special wxPGPropArg id
-convert name of a property to a pointer. For instance:
+argument, using which you can refer to properties either by their pointer
+(for performance) or by their name (for convenience). For instance:
 
 @code
-    // A file selector property.
+    // Add a file selector property.
-    wxPGPropety* p = pg->Append( new wxFileProperty(wxT("FileProperty"), wxPG_LABEL, wxEmptyString) );
+    wxPGPropety* prop = pg->Append( new wxFileProperty(wxT("FileProperty"),
+                                    wxPG_LABEL,
+                                    wxEmptyString) );
 
-    // Valid: Set wildcard by name
+    // Valid: Set wild card by name
     pg->SetPropertyAttribute( wxT("FileProperty"),
                               wxPG_FILE_WILDCARD,
                               wxT("All files (*.*)|*.*") );
 
-    // Also Valid: Set wildcard by ptr
+    // Also Valid: Set wild card by property pointer
-    pg->SetPropertyAttribute( p,
+    pg->SetPropertyAttribute( prop,
                               wxPG_FILE_WILDCARD,
                               wxT("All files (*.*)|*.*") );
 @endcode
 
-Using pointer is faster, since it doesn't require hash map lookup. Anyway, you can allways
+  Using pointer is faster, since it doesn't require hash map lookup. Anyway,
-get property pointer (wxPGProperty*) as Append/Insert return value, or by calling
+you can always get property pointer (wxPGProperty*) as return value from Append()
-GetPropertyByName.
+or Insert(), or by calling wxPropertyGridInterface::GetPropertyByName() or
-
+just plain GetProperty().
-  Below are samples for using some of the more commong operations. See 
-wxPropertyGridInterface and wxPropertyGrid class references for complete list.
-
-@code
-
-    // wxPGId is a short-hand for wxPGProperty*. Let's use it this time.
-    wxPGId id = pg->GetPropertyByName( wxT("MyProperty") );
-
-    // There are many overloaded versions of this method, of which each accept
-    // different type of value.
-    pg->SetPropertyValue( wxT("MyProperty"), 200 );
-
-    // Setting a string works for all properties - conversion is done
-    // automatically.
-    pg->SetPropertyValue( id, wxT("400") );
-
-    // Getting property value as wxVariant.
-    wxVariant value = pg->GetPropertyValue( wxT("MyProperty") );
-
-    // Getting property value as String (again, works for all typs).
-    wxString value = pg->GetPropertyValueAsString( id );
-
-    // Getting property value as int. Provokes a run-time error
-    // if used with property which value type is not "long".
-    long value = pg->GetPropertyValueAsLong( wxT("MyProperty") );
-
-    // Set new name.
-    pg->SetPropertyName( wxT("MyProperty"), wxT("X") );
-
-    // Set new label - we need to use the new name.
-    pg->SetPropertyLabel( wxT("X"), wxT("New Label") );
-
-    // Disable the property. It's text will appear greyed.
-    // This is probably the closest you can get if you want
-    // a "read-only" property.
-    pg->DisableProperty( id );
-
-@endcode
-
 
 @section propgrid_categories Categories
 
-  wxPropertyGrid has a hierarchial property storage and display model, which
+  wxPropertyGrid has a hierarchic property storage and display model, which
 allows property categories to hold child properties and even other
 categories. Other than that, from the programmer's point of view, categories
 can be treated exactly the same as "other" properties. For example, despite
-its name, GetPropertyByName also returns a category by name, and SetPropertyLabel
+its name, GetPropertyByName() also returns a category by name. Note however
-also sets label of a category. Note however that sometimes the label of a
+that sometimes the label of a property category may be referred as caption
-property category may be referred as caption (for example, there is
+(for example, there is wxPropertyGrid::SetCaptionTextColour() method
-SetCaptionForegroundColour method that sets text colour of a property category's label).
+that sets text colour of property category labels).
 
   When category is added at the top (i.e. root) level of the hierarchy,
 it becomes a *current category*. This means that all other (non-category)
-properties after it are automatically added to it. You may add
+properties after it are automatically appended to it. You may add
-properties to specific categories by using wxPropertyGrid::Insert or wxPropertyGrid::AppendIn.
+properties to specific categories by using wxPropertyGridInterface::Insert
+or wxPropertyGridInterface::AppendIn.
 
   Category code sample:
 
@@ -227,7 +189,7 @@ properties to specific categories by using wxPropertyGrid::Insert or wxPropertyG
     pg->Append( new wxIntProperty(wxT("Weight")) );
 
     // Another one
-    pg->Append( new wxPropertyCategory(wxT("Attrikbutes")) );
+    pg->Append( new wxPropertyCategory(wxT("Attributes")) );
 
     // All these are added to "Attributes" category
     pg->Append( new wxIntProperty(wxT("Intelligence")) );
@@ -239,49 +201,56 @@ properties to specific categories by using wxPropertyGrid::Insert or wxPropertyG
 
 @section propgrid_parentprops Tree-like Property Structure
 
-  As a new feature in version 1.3.1, basicly any property can have children. There
+  Basically any property can have children. There are few limitations, however.
-are few limitations, however.
 
 @remarks
-- Names of properties with non-category, non-root parents are not stored in hash map.
+- Names of properties with non-category, non-root parents are not stored in global
-  Instead, they can be accessed with strings like "Parent.Child". For instance, in
+  hash map. Instead, they can be accessed with strings like "Parent.Child".
-  the sample below, child property named "Max. Speed (mph)" can be accessed by global
+  For instance, in the sample below, child property named "Max. Speed (mph)"
-  name "Car.Speeds.Max Speed (mph)".
+  can be accessed by global name "Car.Speeds.Max Speed (mph)".
-- If you want to property's value to be a string composed based on the values of
+- If you want to property's value to be a string composed of the child property values,
-  child properties, you must use wxStringProperty as parent and use value "<composed>".
+  you must use wxStringProperty as parent and use magic string "<composed>" as its
+  value.
 - Events (eg. change of value) that occur in parent do not propagate to children. Events
   that occur in children will propagate to parents, but only if they are wxStringProperties
   with "<composed>" value.
-- Old wxParentProperty class is deprecated, and remains as a typedef of wxStringProperty.
-  If you want old value behavior, you must specify "<composed>" as wxStringProperty's
-  value.
 
 Sample:
 
 @code
-    wxPGId pid = pg->Append( new wxStringProperty(wxT("Car"),wxPG_LABEL,wxT("<composed>")) );
+    wxPGProperty* carProp = pg->Append(new wxStringProperty(wxT("Car"),
-
-    pg->AppendIn( pid, new wxStringProperty(wxT("Model"),
-                                            wxPG_LABEL,
-                                            wxT("Lamborghini Diablo SV")) );
-
-    pg->AppendIn( pid, new wxIntProperty(wxT("Engine Size (cc)"),
                                          wxPG_LABEL,
-                                         5707) );
+                                         wxT("<composed>")));
 
-    wxPGId speedId = pg->AppendIn( pid, new wxStringProperty(wxT("Speeds"),wxPG_LABEL,wxT("<composed>")) );
+    pg->AppendIn(carProp, new wxStringProperty(wxT("Model"),
-    pg->AppendIn( speedId, new wxIntProperty(wxT("Max. Speed (mph)"),wxPG_LABEL,290) );
+                                                wxPG_LABEL,
-    pg->AppendIn( speedId, new wxFloatProperty(wxT("0-100 mph (sec)"),wxPG_LABEL,3.9) );
+                                                wxT("Lamborghini Diablo SV")));
-    pg->AppendIn( speedId, new wxFloatProperty(wxT("1/4 mile (sec)"),wxPG_LABEL,8.6) );
 
-    // Make sure the child properties can be accessed correctly
+    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( pid, new wxIntProperty(wxT("Price ($)"),
+    pg->AppendIn(carProp, new wxIntProperty(wxT("Price ($)"),
-                                         wxPG_LABEL,
+                                            wxPG_LABEL,
-                                         300000) );
+                                            300000) );
-    // Displayed value of "Car" property is now:
+
-    // "Lamborghini Diablo SV; [300; 3.9; 8.6]; 300000"
+    // Displayed value of "Car" property is now very close to this:
+    // "Lamborghini Diablo SV; 5707 [300; 3.9; 8.6] 300000"
 
 @endcode
 
@@ -290,9 +259,9 @@ Sample:
   wxEnumProperty is used when you want property's (integer or string) value
 to be selected from a popup list of choices.
 
-  Creating wxEnumProperty is more complex than those described earlier.
+  Creating wxEnumProperty is slightly more complex than those described
-You have to provide list of constant labels, and optionally relevant values
+earlier. You have to provide list of constant labels, and optionally relevant
-(if label indexes are not sufficient).
+values (if label indexes are not sufficient).
 
 @remarks
 
@@ -315,8 +284,6 @@ A very simple example:
                                    wxPG_LABEL,
                                    arrDiet) );
 
-
-
     //
     // Using wxChar* array
     //
@@ -327,7 +294,6 @@ A very simple example:
                                    wxPG_LABEL,
                                    arrayDiet) );
 
-
 @endcode
 
 Here's extended example using values as well:
@@ -355,44 +321,27 @@ Here's extended example using values as well:
                                    arrIds,
                                    50));
 
-
-    //
-    // Using wxChar* and long arrays
-    //
-    const wxChar* array_diet[] =
-    { wxT("Herbivore"), wxT("Carnivore"), wxT("Omnivore"), NULL };
-
-    long array_diet_ids[] =
-    { 40, 45, 50 };
-
-    pg->Append( new wxEnumProperty(wxT("Diet"),
-                                   wxPG_LABEL,
-                                   array_diet,
-                                   array_diet_ids);
-
 @endcode
 
   wxPGChoices is a class where wxEnumProperty, and other properties which
-  require label storage, actually stores strings and values. It is used
+  require storage for list of items, actually stores strings and values. It is
-  to facilitiate reference counting, and therefore recommended way of
+  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. Infact, if you wish to display bitmaps next to labels,
+  to the constructor. In fact, if you wish to display bitmaps next to labels,
   your best choice is to use this approach.
 
 @code
 
     wxPGChoices chs;
-    chs.Add(wxT("Herbivore"),40);
+    chs.Add(wxT("Herbivore"), 40);
-    chs.Add(wxT("Carnivore"),45);
+    chs.Add(wxT("Carnivore"), 45);
-    chs.Add(wxT("Omnivore"),50);
+    chs.Add(wxT("Omnivore"), 50);
 
     // Let's add an item with bitmap, too
     chs.Add(wxT("None of the above"), wxBitmap(), 60);
 
-    // Note: you can add even whole arrays to wxPGChoices
-
     pg->Append( new wxEnumProperty(wxT("Primary Diet"),
                                    wxPG_LABEL,
                                    chs) );
@@ -408,8 +357,8 @@ You can later change choices of property by using wxPGProperty::AddChoice(),
 wxPGProperty::InsertChoice(), wxPGProperty::DeleteChoice(), and
 wxPGProperty::SetChoices().
 
-<b>wxEditEnumProperty</b> is works exactly like wxEnumProperty, except
+<b>wxEditEnumProperty</b> works exactly like wxEnumProperty, except
-is uses non-readonly combobox as default editor, and value is stored as
+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:
@@ -432,10 +381,9 @@ wxFlagsProperty has similar construction:
 @endcode
 
 wxFlagsProperty can use wxPGChoices just the same way as wxEnumProperty
-(and also custom property classes can be created with similar macro pairs).
+<b>Note:</b> When changing "choices" (ie. flag labels) of wxFlagsProperty,
-<b>Note: </b> When changing "choices" (ie. flag labels) of wxFlagsProperty,
 you will need to use wxPGProperty::SetChoices() to replace all choices
-at once - otherwise they will not get updated properly.
+at once - otherwise implicit child properties will not get updated properly.
 
 @section propgrid_advprops Specialized Properties
 
@@ -454,7 +402,7 @@ To use them, you have to include <wx/propgrid/advprops.h>.
                                    wxPG_LABEL,
                                    wxDateTime::Now()) );
 
-    // Image file property. Wildcard is auto-generated from available
+    // 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")) );
@@ -488,12 +436,44 @@ To use them, you have to include <wx/propgrid/advprops.h>.
 @endcode
 
 
+@section propgrid_processingvalues Processing Property Values
+
+Properties store their values internally in wxVariant. You can obtain
+this value using wxPGProperty::GetValue() or wxPropertyGridInterface::
+GetPropertyValue().
+
+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.
+
+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).
+
+
 @section propgrid_iterating Iterating through a property container
 
 You can use somewhat STL'ish iterator classes to iterate through the grid.
 Here is a simple example of forward iterating through all individual
-properties (not categories or sub-propeties that are normally 'transparent'
+properties (not categories nor private child properties that are normally
-to application code):
+'transparent' to application code):
 
 @code
 
@@ -551,8 +531,9 @@ This example reverse-iterates through all visible items:
 
 GetIterator() only works with wxPropertyGrid and the individual pages
 of wxPropertyGridManager. In order to iterate through an arbitrary
-property container, you need to use wxPropertyGridInterface::GetVIterator().
+property container (such as entire wxPropertyGridManager), you need to use
-Note however that this virtual iterater is limited to forward iteration.
+wxPropertyGridInterface::GetVIterator(). Note however that this virtual
+iterator is limited to forward iteration.
 
 @code
 
@@ -568,48 +549,6 @@ Note however that this virtual iterater is limited to forward iteration.
 
 @endcode
 
-
-@section propgrid_operations More About Operating with Properties
-
-Getting value of selected wxSystemColourProperty (which value type is derived
-from wxObject):
-
-@code
-
-    wxPGId id = pg->GetSelection();
-
-    if ( id )
-    {
-        // Get name of property
-        const wxString& name = pg->GetPropertyName( id );
-
-        // If type is not correct, GetColour() method will produce run-time error
-        if ( pg->GetPropertyValueType() == wxT("wxColourPropertyValue") ) )
-        {
-            wxColourPropertyValue* pcolval =
-                wxDynamicCast(pg->GetPropertyValueAsWxObjectPtr(id),
-                              wxColourPropertyValue);
-
-            // Report value
-            wxString text;
-            if ( pcolval->m_type == wxPG_CUSTOM_COLOUR )
-                text.Printf( wxT("It is custom colour: (%i,%i,%i)"),
-                    (int)pcolval->m_colour.Red(),
-                    (int)pcolval->m_colour.Green(),
-                    (int)pcolval->m_colour.Blue());
-            else
-                text.Printf( wxT("It is wx system colour (number=%i): (%i,%i,%i)"),
-                    (int)pcolval->m_type,
-                    (int)pcolval->m_colour.Red(),
-                    (int)pcolval->m_colour.Green(),
-                    (int)pcolval->m_colour.Blue());
-
-            wxMessageBox( text );
-        }
-    }
-
-@endcode
-
 @section propgrid_populating Populating wxPropertyGrid Automatically
 
 @subsection propgrid_fromvariants Populating from List of wxVariants
@@ -619,10 +558,10 @@ in an arbitrary list of wxVariants.
 
 @code
 
-    // This is a static method that initializes *all* builtin type handlers
+    // 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 significantly.
+    // method may increase the executable size noticeably.
     pg->InitAllTypeHandlers();
 
     // Get contents of the grid as a wxVariant list
@@ -632,44 +571,21 @@ in an arbitrary list of wxVariants.
     // name is not found, it is created according to the type of variant.
     pg->SetPropertyValues( my_list_variant );
 
-    // In order to get wxObject ptr from a variant value,
-    // wxGetVariantCast(VARIANT,CLASSNAME) macro has to be called.
-    // Like this:
-    wxVariant v_txcol = pg->GetPropertyValue(wxT("Text Colour"));
-    const wxColour& txcol = wxGetVariantCast(v_txcol,wxColour);
-
 @endcode
 
 @subsection propgrid_fromfile Loading Population from a Text-based Storage
 
 Class wxPropertyGridPopulator may be helpful when writing code that
-loads properties from a text-source. In fact, the supplied xrc handler
+loads properties from a text-source. In fact, the wxPropertyGrid xrc-handler
-(src/xh_propgrid.cpp) uses it. See that code for more info.
+(which may not be currently included in wxWidgets, but probably will be in
-NOTE: src/xh_propgrid.cpp is not included in the library by default,
+near future) uses it.
-to avoid dependency to wxXRC. You will need to add it to your application
-separately.
 
-@subsection propgrid_editablestate Saving and Restoring User-Editable State
+@subsection editablestate Saving and Restoring User-Editable State
-
-You can use wxPGEditableState and wxPGMEditableState classes, and
-wxPropertyGrid::SaveEditableState() and wxPropertyGrid::RestoreEditableState()
-to save and restore user-editable state (selected property, expanded/
-collapsed properties, and scrolled position). For convience with
-program configuration, wxPGEditableState has functions to save/load
-its value in wxString. For instance:
-
-@code
-    // Save state into config
-    wxPGEditableState edState;
-    pg->SaveEditableState(&edState);
-    programConfig->Store(wxT("PropertyGridState"), edState.GetAsString());
-
-    // Restore state from config
-    wxPGEditableState edState;
-    edState.SetFromString(programConfig->Load(wxT("PropertyGridState")));
-    pg->RestoreEditableState(edState);
-@endcode
 
+You can use wxPropertyGridInterface::SaveEditableState() and
+wxPropertyGridInterface::RestoreEditableState() to save and restore
+user-editable state (selected property, expanded/collapsed properties,
+selected page, scrolled position, and splitter positions).
 
 @section propgrid_events Event Handling
 
@@ -679,62 +595,14 @@ in your event table to use it.
 
 For complete list of event types, see wxPropertyGrid class reference.
 
-The custom event class, wxPropertyGridEvent, has methods to directly
+However, one type of event that might need focused attention is EVT_PG_CHANGING,
-access the property that triggered the event.
+which occurs just prior property value is being changed by user. You can
-
+acquire pending value using wxPropertyGridEvent::GetValue(), and if it is
-Here's a small sample:
+not acceptable, call wxPropertyGridEvent::Veto() to prevent the value change
+from taking place.
 
 @code
 
-// Portion of an imaginary event table
-BEGIN_EVENT_TABLE(MyForm, wxFrame)
-
-    ...
-
-    // This occurs when a property value changes
-    EVT_PG_CHANGED( PGID, MyForm::OnPropertyGridChange )
-
-    ...
-
-END_EVENT_TABLE()
-
-void MyForm::OnPropertyGridChange( wxPropertyGridEvent& event )
-{
-    wxPGProperty *property = event.GetProperty();
-
-    // It may be NULL
-    if ( !property )
-        return;
-
-    // Get name of changed property
-    const wxString& name = property->GetName();
-
-    // Get resulting value
-    wxVariant value = property->GetValue();
-}
-
-@endcode
-
-Another event type you might find useful 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.
-
-@code
-
-// Portion of an imaginary event table
-BEGIN_EVENT_TABLE(MyForm, wxFrame)
-
-    ...
-
-    // This occurs when a property value changes
-    EVT_PG_CHANGING( PGID, MyForm::OnPropertyGridChanging )
-
-    ...
-
-END_EVENT_TABLE()
-
 void MyForm::OnPropertyGridChanging( wxPropertyGridEvent& event )
 {
     wxPGProperty* property = event.GetProperty();
@@ -753,12 +621,13 @@ void MyForm::OnPropertyGridChanging( wxPropertyGridEvent& event )
 
 @endcode
 
-@remarks On Sub-property Event Handling
+@remarks On Child Property Event Handling
-- For aggregate type properties (wxFontProperty, wxFlagsProperty, etc), events
+- For properties which have private, implicit children (wxFontProperty and
-  occur for the main parent property only. For other properties events occur
+  wxFlagsProperty), events occur for the main parent property only.
-  for the children themselves..
+  For other properties events occur for the children themselves. See
+  @ref propgrid_parentprops.
 
-- When property's child gets changed, you can use wxPropertyGridEvent::GetMainParent
+- When property's child gets changed, you can use wxPropertyGridEvent::GetMainParent()
   to obtain its topmost non-category parent (useful, if you have deeply nested
   properties).
 
@@ -771,7 +640,7 @@ wxPropertyGridInterface::SetPropertyValidator() to assign wxValidator to
 property.
 
 Second, you can subclass a property and override wxPGProperty::ValidateValue(),
-or handle wxEVT_PG_CHANGING for the same effect. Both of these methods do not
+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.
@@ -796,7 +665,8 @@ message.
             // Make sure value is not unspecified
             if ( !pendingValue.IsNull() )
             {
-                wxFont font << pendingValue;
+                wxFont font;
+                font << pendingValue;
 
                 // Let's just allow Arial font
                 if ( font.GetFaceName() != wxT("Arial") )
@@ -819,8 +689,7 @@ each cell in the property grid. Use wxPropertyGridInterface::SetPropertyCell() o
 wxPGProperty::SetCell() for this purpose.
 
 In addition, it is possible to control these characteristics for
-wxPGChoices list items. See wxPGChoices class
+wxPGChoices list items. See wxPGChoices class reference for more info.
-reference for more info.
 
 
 @section propgrid_customizing Customizing Properties (without sub-classing)
@@ -836,18 +705,11 @@ actual value text. Built-in example of this can be seen with
 wxColourProperty and wxImageFileProperty, but for others it can
 be set using wxPropertyGrid::SetPropertyImage method.
 
-@subsection propgrid_customvalidator Setting Validator
-
-You can set wxValidator for a property using wxPropertyGrid::SetPropertyValidator.
-
-Validator will work just like in wxWidgets (ie. editorControl->SetValidator(validator)
-is called).
-
 @subsection propgrid_customeditor Setting Property's Editor Control(s)
 
 You can set editor control (or controls, in case of a control and button),
 of any property using wxPropertyGrid::SetPropertyEditor. Editors are passed
-using wxPG_EDITOR(EditorName) macro, and valid built-in EditorNames are
+as wxPGEditor_EditorName, and valid built-in EditorNames are
 TextCtrl, Choice, ComboBox, CheckBox, TextCtrlAndButton, ChoiceAndButton,
 SpinCtrl, and DatePickerCtrl. Two last mentioned ones require call to
 static member function wxPropertyGrid::RegisterAdditionalEditors().
@@ -859,9 +721,9 @@ colour selection dialog.
 
 @code
 
-    wxPGId colProp = pg->Append(wxColourProperty(wxT("Text Colour")));
+    wxPGProperty* colProp = new wxColourProperty(wxT("Text Colour"));
-
+    pg->Append(colProp);
-    pg->SetPropertyEditor(colProp,wxPG_EDITOR(TextCtrlAndButton));
+    pg->SetPropertyEditor(colProp, wxPGEditor_TextCtrlAndButton);
 
 @endcode
 
@@ -870,7 +732,8 @@ well. For more information, see wxPGEditor class reference.
 
 @subsection propgrid_editorattrs Property Attributes Recognized by Editors
 
-<b>SpinCtrl</b> editor can make use of property's "Min", "Max", "Step" and "Wrap" attributes.
+<b>SpinCtrl</b> editor can make use of property's "Min", "Max", "Step" and
+"Wrap" attributes.
 
 @subsection propgrid_multiplebuttons Adding Multiple Buttons Next to an Editor
 
@@ -886,105 +749,38 @@ from the original TextCtrl).
 @subsection propgrid_attributes Property Attributes
 
 Miscellaneous values, often specific to a property type, can be set
-using wxPropertyGrid::SetPropertyAttribute and wxPropertyGrid::SetPropertyAttributeAll
+using wxPropertyGridInterface::SetPropertyAttribute() and
-methods.
+wxPropertyGridInterface::SetPropertyAttributeAll() methods.
 
 Attribute names are strings and values wxVariant. Arbitrary names are allowed
-inorder to store user values. Constant equivalents of all attribute string names are
+in order to store values that are relevant to application only and not
-provided. Some of them are defined as cached strings, so using constants can provide
+property grid. Constant equivalents of all attribute string names are
-for smaller binary size.
+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 @ref propgrid_property_attributes.
 
-@subsection propgrid_boolcheckbox Setting wxBoolProperties to Use Check Box
-
-To have all wxBoolProperties to use CheckBox editor instead of Choice, use
-following (call after bool properties have been added):
-
-@code
-    pg->SetPropertyAttributeAll(wxPG_BOOL_USE_CHECKBOX,true);
-@endcode
-
 
 @section propgrid_usage2 Using wxPropertyGridManager
 
 wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
-which can optionally have toolbar for mode and page selection, and a help text
+which can optionally have tool bar for mode and page selection, and a help text
-box.
+box. For more information, see wxPropertyGridManager class reference.
-
-wxPropertyGridManager inherits from wxPropertyGridInterface, and as such
-it has most property manipulation functions. However, only some of them affect
-properties on all pages (eg. GetPropertyByName() and ExpandAll()), while some
-(eg. Append()) only apply to the currently selected page.
-
-To operate explicitly on properties on specific page, use wxPropertyGridManager::GetPage()
-to obtain pointer to page's wxPropertyGridPage object.
-
-Visual methods, such as SetCellBackgroundColour and GetNextVisible are only
-available in wxPropertyGrid. Use wxPropertyGridManager::GetGrid() to obtain
-pointer to it.
-
-Iteration methods will not work in wxPropertyGridManager. Instead, you must acquire
-the internal grid (GetGrid()) or wxPropertyGridPage object (GetPage()).
-
-wxPropertyGridManager constructor has exact same format as wxPropertyGrid
-constructor, and basicly accepts same extra window style flags (albeit also
-has some extra ones).
-
-Here's some example code for creating and populating a wxPropertyGridManager:
-
-@code
-
-    wxPropertyGridManager* pgMan = new wxPropertyGridManager(this, PGID,
-        wxDefaultPosition, wxDefaultSize,
-        // These and other similar styles are automatically
-        // passed to the embedded wxPropertyGrid.
-        wxPG_BOLD_MODIFIED|wxPG_SPLITTER_AUTO_CENTER|
-        // Include toolbar.
-        wxPG_TOOLBAR |
-        // Include description box.
-        wxPG_DESCRIPTION |
-        // Include compactor.
-        wxPG_COMPACTOR |
-        // Plus defaults.
-        wxPGMAN_DEFAULT_STYLE
-       );
-
-    wxPropertyGridPage* page;
-
-    // Adding a page sets target page to the one added, so
-    // we don't have to call SetTargetPage if we are filling
-    // it right after adding.
-    pgMan->AddPage(wxT("First Page"));
-    page = pgMan->GetLastPage();
-
-    page->Append( new wxPropertyCategory(wxT("Category A1")) );
-
-    page->Append( new wxIntProperty(wxT("Number"),wxPG_LABEL,1) );
-
-    page->Append( new wxColourProperty(wxT("Colour"),wxPG_LABEL,*wxWHITE) );
-
-    pgMan->AddPage(wxT("Second Page"));
-    page = pgMan->GetLastPage();
-
-    page->Append( wxT("Text"),wxPG_LABEL,wxT("(no text)") );
-
-    page->Append( new wxFontProperty(wxT("Font"),wxPG_LABEL) );
-
-@endcode
 
 @subsection propgrid_propgridpage wxPropertyGridPage
 
 wxPropertyGridPage is holder of properties for one page in manager. It is derived from
 wxEvtHandler, so you can subclass it to process page-specific property grid events. Hand
-over your page instance in wxPropertyGridManager::AddPage.
+over your page instance in wxPropertyGridManager::AddPage().
 
 Please note that the wxPropertyGridPage itself only sports subset of wxPropertyGrid API
 (but unlike manager, this include item iteration). Naturally it inherits from
-wxPropertyGridMethods and wxPropertyGridPageState.
+wxPropertyGridInterface.
+
+For more information, see wxPropertyGridPage class reference.
 
 
-@section propgrid_subclassing Subclassing wxPropertyGrid and wxPropertyGridManager
+@section propgrid_subclassing Sub-classing wxPropertyGrid and wxPropertyGridManager
 
 Few things to note:
 
@@ -992,15 +788,16 @@ Few things to note:
   just e-mail to wx-dev mailing list.
 
 - Data manipulation is done in wxPropertyGridPageState class. So, instead of
-  overriding wxPropertyGrid::Insert, you'll probably want to override wxPropertyGridPageState::DoInsert.
+  overriding wxPropertyGrid::Insert(), you'll probably want to override
+  wxPropertyGridPageState::DoInsert(). See header file for details.
 
-- Override wxPropertyGrid::CreateState to instantiate your derivate wxPropertyGridPageState.
+- Override wxPropertyGrid::CreateState() to instantiate your derivate
-  For wxPropertyGridManager, you'll need to subclass wxPropertyGridPage instead (since it
+  wxPropertyGridPageState. For wxPropertyGridManager, you'll need to subclass
-  is derived from wxPropertyGridPageState), and hand over instances in wxPropertyGridManager::AddPage
+  wxPropertyGridPage instead (since it is derived from wxPropertyGridPageState),
-  calls.
+  and hand over instances in wxPropertyGridManager::AddPage() calls.
 
-- You can use a derivate wxPropertyGrid with manager by overriding wxPropertyGridManager::CreatePropertyGrid
+- You can use a derivate wxPropertyGrid with manager by overriding
-  member function.
+  wxPropertyGridManager::CreatePropertyGrid() member function.
 
 
 @section propgrid_misc Miscellaneous Topics
@@ -1020,17 +817,25 @@ unique (base) name.
 
 @subsection propgrid_boolproperty wxBoolProperty
 
-  There are few points about wxBoolProperty that require futher discussion:
+  There are few points about wxBoolProperty that require further discussion:
-  - wxBoolProperty can be shown as either normal combobox or as a checkbox.
+  - wxBoolProperty can be shown as either normal combo box or as a check box.
     Property attribute wxPG_BOOL_USE_CHECKBOX is used to change this.
     For example, if you have a wxFlagsProperty, you can
     set its all items to use check box using the following:
     @code
         pg->SetPropertyAttribute(wxT("MyFlagsProperty"),wxPG_BOOL_USE_CHECKBOX,true,wxPG_RECURSE);
     @endcode
+    
+    Following will set all individual bool properties in your control to
+    use check box:
+    
+    @code
+        pg->SetPropertyAttributeAll(wxPG_BOOL_USE_CHECKBOX, true);
+    @endcode
 
   - Default item names for wxBoolProperty are ["False", "True"]. This can be
-    changed using wxPropertyGrid::SetBoolChoices(trueChoice, falseChoice).
+    changed using static function wxPropertyGrid::SetBoolChoices(trueChoice,
+    falseChoice).
 
 @subsection propgrid_textctrlupdates Updates from wxTextCtrl Based Editor
 
@@ -1061,7 +866,7 @@ splitter position, especially when sizers are being used.
 
 @subsection propgrid_colourproperty wxColourProperty and wxSystemColourProperty
 
-Through subclassing, these two property classes provide substantial customization
+Through sub-classing, these two property classes provide substantial customization
 features. Subclass wxSystemColourProperty if you want to use wxColourPropertyValue
 (which features colour type in addition to wxColour), and wxColourProperty if plain
 wxColour is enough.

interface/wx/propgrid/manager.h

@@ -115,8 +115,69 @@ public:
 /** @class wxPropertyGridManager
 
     wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
-    which can optionally have toolbar for mode and page selection, and help text box.
+    which can optionally have toolbar for mode and page selection, and a help text
-    Use window flags to select components to include.
+    box.
+
+    wxPropertyGridManager inherits from wxPropertyGridInterface, and as such
+    it has most property manipulation functions. However, only some of them affect
+    properties on all pages (eg. GetPropertyByName() and ExpandAll()), while some
+    (eg. Append()) only apply to the currently selected page.
+
+    To operate explicitly on properties on specific page, use wxPropertyGridManager::GetPage()
+    to obtain pointer to page's wxPropertyGridPage object.
+
+    Visual methods, such as SetCellBackgroundColour() are only available in
+    wxPropertyGrid. Use wxPropertyGridManager::GetGrid() to obtain pointer to it.
+
+    Non-virtual iterators will not work in wxPropertyGridManager. Instead, you must
+    acquire the internal grid (GetGrid()) or wxPropertyGridPage object (GetPage()).
+
+    wxPropertyGridManager constructor has exact same format as wxPropertyGrid
+    constructor, and basicly accepts same extra window style flags (albeit also
+    has some extra ones).
+
+    Here's some example code for creating and populating a wxPropertyGridManager:
+
+    @code
+
+        wxPropertyGridManager* pgMan = new wxPropertyGridManager(this, PGID,
+            wxDefaultPosition, wxDefaultSize,
+            // These and other similar styles are automatically
+            // passed to the embedded wxPropertyGrid.
+            wxPG_BOLD_MODIFIED|wxPG_SPLITTER_AUTO_CENTER|
+            // Include toolbar.
+            wxPG_TOOLBAR |
+            // Include description box.
+            wxPG_DESCRIPTION |
+            // Include compactor.
+            wxPG_COMPACTOR |
+            // Plus defaults.
+            wxPGMAN_DEFAULT_STYLE
+           );
+
+        wxPropertyGridPage* page;
+
+        // Adding a page sets target page to the one added, so
+        // we don't have to call SetTargetPage if we are filling
+        // it right after adding.
+        pgMan->AddPage(wxT("First Page"));
+        page = pgMan->GetLastPage();
+
+        page->Append( new wxPropertyCategory(wxT("Category A1")) );
+
+        page->Append( new wxIntProperty(wxT("Number"),wxPG_LABEL,1) );
+
+        page->Append( new wxColourProperty(wxT("Colour"),wxPG_LABEL,*wxWHITE) );
+
+        pgMan->AddPage(wxT("Second Page"));
+        page = pgMan->GetLastPage();
+
+        page->Append( wxT("Text"),wxPG_LABEL,wxT("(no text)") );
+
+        page->Append( new wxFontProperty(wxT("Font"),wxPG_LABEL) );
+
+    @endcode
+
 
     @section propgridmanager_window_styles_ Window Styles
 

interface/wx/propgrid/propgrid.h

@@ -251,10 +251,11 @@ enum wxPG_KEYBOARD_ACTIONS
 
 /** @class wxPropertyGrid
 
-    wxPropertyGrid is a specialized grid for editing properties
+      wxPropertyGrid is a specialized grid for editing properties - in other
-    such as strings, numbers, flagsets, fonts, and colours. wxPropertySheet
+    words name = value pairs. List of ready-to-use property classes include
-    used to do the very same thing, but it hasn't been updated for a while
+    strings, numbers, flagsets, fonts, colours and many others. It is possible,
-    and it is currently deprecated.
+    for example, to categorize properties, set up a complete tree-hierarchy,
+    add more than two columns, and set arbitrary per-property attributes.
 
     Please note that most member functions are inherited and as such not documented on
     this page. This means you will probably also want to read wxPropertyGridInterface

interface/wx/propgrid/propgridiface.h

@@ -16,6 +16,10 @@
     @remarks
     - In separate wxPropertyGrid component this class was known as wxPropertyContainerMethods.
 
+    - wxPropertyGridInterface's property operation member functions 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 conveniency).
+
     @library{wxpropgrid}
     @category{propgrid}
 */
@@ -147,15 +151,21 @@ public:
 
     //@{
     /** Returns iterator class instance.
+
         @param flags
-        See @ref propgrid_iterator_flags. Value wxPG_ITERATE_DEFAULT causes
+            See @ref propgrid_iterator_flags. Value wxPG_ITERATE_DEFAULT causes
-        iteration over everything except private child properties.
+            iteration over everything except private child properties.
+
         @param firstProp
-        Property to start iteration from. If NULL, then first child of root is used.
+            Property to start iteration from. If NULL, then first child of root is used.
+
         @param startPos
-        Either wxTOP or wxBOTTOM. wxTOP will indicate that iterations start from
+            Either wxTOP or wxBOTTOM. wxTOP will indicate that iterations start from
-        the first property from the top, and wxBOTTOM means that the iteration will
+            the first property from the top, and wxBOTTOM means that the iteration will
-        instead begin from bottommost valid item.
+            instead begin from bottommost valid item.
+
+        <b>wxPython Note:</b> Instead of ++ operator, use Next() method, and instead of
+        * operator, use GetProperty() method.
     */
     wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT, wxPGProperty* firstProp = NULL )
     {
@@ -428,7 +438,10 @@ public:
         containers.
 
         @param flags
-        See @ref propgrid_iterator_flags.
+            See @ref propgrid_iterator_flags.
+
+        <b>wxPython Note:</b> Instead of ++ operator, use Next() method, and instead of
+        * operator, use GetProperty() method.            
     */
     virtual wxPGVIterator GetVIterator( int flags ) const;
 
@@ -913,7 +926,7 @@ public:
     void SetPropertyValueString( wxPGPropArg id, const wxString& value );
 
     /** Sets value (wxVariant&) of a property.
-    
+
         @remarks
         Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through
         validation process and send property change event.
@@ -934,7 +947,7 @@ public:
     wxPGProperty* GetPropertyByNameA( const wxString& name ) const;
 
     static wxPGEditor* GetEditorByName( const wxString& editorName );
-    
+
     virtual void RefreshProperty( wxPGProperty* p ) = 0;
 };
 

samples/propgrid/propgrid.cpp

@@ -1619,30 +1619,39 @@ void FormMain::PopulateWithExamples ()
     //
     // This snippet is a doc sample test
     //
-    pid = pg->Append( new wxStringProperty(wxT("Car"),wxPG_LABEL,wxT("<composed>")) );
+    wxPGProperty* carProp = pg->Append(new wxStringProperty(wxT("Car"),
+                                         wxPG_LABEL,
+                                         wxT("<composed>")));
 
-    pg->AppendIn( pid, new wxStringProperty(wxT("Model"),
+    pg->AppendIn(carProp, new wxStringProperty(wxT("Model"),
+                                                wxPG_LABEL,
+                                                wxT("Lamborghini Diablo SV")));
+
+    pg->AppendIn(carProp, new wxIntProperty(wxT("Engine Size (cc)"),
                                             wxPG_LABEL,
-                                            wxT("Lamborghini Diablo SV")) );
+                                            5707) );
 
-    pg->AppendIn( pid, new wxIntProperty(wxT("Engine Size (cc)"),
+    wxPGProperty* speedsProp = pg->AppendIn(carProp,
-                                         wxPG_LABEL,
+                                            new wxStringProperty(wxT("Speeds"),
-                                         5707) );
+                                              wxPG_LABEL,
+                                              wxT("<composed>")));
 
-    wxPGProperty* speedId = pg->AppendIn( pid, new wxStringProperty(wxT("Speeds"),wxPG_LABEL,wxT("<composed>")) );
+    pg->AppendIn( speedsProp, new wxIntProperty(wxT("Max. Speed (mph)"),
-    pg->AppendIn( speedId, new wxIntProperty(wxT("Max. Speed (mph)"),wxPG_LABEL,290) );
+                                                wxPG_LABEL,290) );
-    pg->AppendIn( speedId, new wxFloatProperty(wxT("0-100 mph (sec)"),wxPG_LABEL,3.9) );
+    pg->AppendIn( speedsProp, new wxFloatProperty(wxT("0-100 mph (sec)"),
-    pg->AppendIn( speedId, new wxFloatProperty(wxT("1/4 mile (sec)"),wxPG_LABEL,8.6) );
+                                                  wxPG_LABEL,3.9) );
+    pg->AppendIn( speedsProp, new wxFloatProperty(wxT("1/4 mile (sec)"),
+                                                  wxPG_LABEL,8.6) );
 
-    pg->AppendIn( pid, new wxIntProperty(wxT("Price ($)"),
+    // This is how child property can be referred to by name
-                                         wxPG_LABEL,
-                                         300000) );
-
-    // Make sure the child properties can be accessed correctly
     pg->SetPropertyValue( wxT("Car.Speeds.Max. Speed (mph)"), 300 );
 
-    // Displayed value of "Car" property is now:
+    pg->AppendIn(carProp, new wxIntProperty(wxT("Price ($)"),
-    // "Lamborghini Diablo SV; [300; 3.9; 8.6]; 300000"
+                                            wxPG_LABEL,
+                                            300000) );
+
+    // Displayed value of "Car" property is now very close to this:
+    // "Lamborghini Diablo SV; 5707 [300; 3.9; 8.6] 300000"
 
     //
     // Test wxSampleMultiButtonEditor