Fix broken and missing DataView interface items for Phoenix

[wxWidgets.git] / docs / doxygen / overviews / propgrid.h

diff --git a/docs/doxygen/overviews/propgrid.h b/docs/doxygen/overviews/propgrid.h
index 6875586de35db2f66637e025cf4cd0f1a85e6cb8..fd442844911a2a00617495e86d4368dd474ad3a8 100644 (file)
--- a/docs/doxygen/overviews/propgrid.h
+++ b/docs/doxygen/overviews/propgrid.h
@@ -2,48 +2,32 @@
 // Name:        propgrid.h
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // Name:        propgrid.h
 // Purpose:     topic overview
 // Author:      wxWidgets team

-// RCS-ID:      $Id:
-// Licence:     wxWindows license
+// RCS-ID:      $Id$
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 
 @page overview_propgrid wxPropertyGrid Overview
 
 /////////////////////////////////////////////////////////////////////////////
 
 /**
 
 @page overview_propgrid wxPropertyGrid Overview
 

-Key Classes:
-@li wxPGProperty
-@li wxPropertyGrid
-@li wxPropertyGridEvent
-@li wxPropertyGridManager
-@li wxPropertyGridPage
-
-  wxPropertyGrid is a specialized grid for editing properties such as strings,
-numbers, flagsets, fonts, and colours. It is possible, for example, to categorize
-properties, set up a complete tree-hierarchy, add multiple columns, and set
-arbitrary per-property attributes.
-
-@li @ref basics
-@li @ref categories
-@li @ref parentprops
-@li @ref enumandflags
-@li @ref advprops
-@li @ref iterating
-@li @ref operations
-@li @ref events
-@li @ref validating
-@li @ref populating
-@li @ref cellrender
-@li @ref customizing
-@li @ref usage2
-@li @ref subclassing
-@li @ref misc
-@li @ref proplist
-@li @ref userhelp
-@li @ref notes
-@li @ref newprops
-@li @ref neweditors
-
-@section basics Creating and Populating wxPropertyGrid
+@tableofcontents
+
+wxPropertyGrid is a specialized grid for editing properties - in other words
+name = value pairs. List of ready-to-use property classes include strings,
+numbers, flag sets, fonts, colours and many others. It is possible, for
+example, to categorize properties, set up a complete tree-hierarchy, add more
+than two columns, and set arbitrary per-property attributes.
+
+As this version of wxPropertyGrid has some backward-incompatible changes from
+version 1.4, everybody who need to maintain custom property classes should
+carefully read final section in @ref propgrid_compat.
+
+@see wxPropertyGrid, wxPropertyGridEvent, wxPropertyGridManager,
+     wxPropertyGridPage, wxPGProperty
+
+
+
+@section propgrid_basics Creating and Populating wxPropertyGrid

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


@@ -72,17 +56,17 @@ 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,
     // 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
 
     pg->SetExtraStyle( wxPG_EX_HELP_AS_TOOLTIPS );
 
 @endcode
 

-  (for complete list of new window styles: @link wndflags Additional Window Styles@endlink)
+  (for complete list of new window styles, see @ref propgrid_window_styles)

 
   wxPropertyGrid is usually populated with lines like this:
 
 @code
 
   wxPropertyGrid is usually populated with lines like this:
 
 @code

-    pg->Append( new wxStringProperty(wxT("Label"),wxT("Name"),wxT("Initial Value")) );
+    pg->Append( new wxStringProperty("Label", "Name", "Initial Value") );

 @endcode
 
 Naturally, wxStringProperty is a property class. Only the first function argument (label)
 @endcode
 
 Naturally, wxStringProperty is a property class. Only the first function argument (label)


@@ -97,207 +81,179 @@ To demonstrate other common property classes, here's another code snippet:
 @code
 
     // Add int property
 @code
 
     // Add int property

-    pg->Append( new wxIntProperty(wxT("IntProperty"), wxPG_LABEL, 12345678) );
+    pg->Append( new wxIntProperty("IntProperty", wxPG_LABEL, 12345678) );

 
     // Add float property (value type is actually double)
 
     // Add float property (value type is actually double)

-    pg->Append( new wxFloatProperty(wxT("FloatProperty"), wxPG_LABEL, 12345.678) );
+    pg->Append( new wxFloatProperty("FloatProperty", wxPG_LABEL, 12345.678) );

 
     // Add a bool property
 
     // Add a bool property

-    pg->Append( new wxBoolProperty(wxT("BoolProperty"), wxPG_LABEL, false) );
+    pg->Append( new wxBoolProperty("BoolProperty", wxPG_LABEL, false) );

 
     // A string property that can be edited in a separate editor dialog.
 
     // A string property that can be edited in a separate editor dialog.

-    pg->Append( new wxLongStringProperty(wxT("LongStringProperty"),
+    pg->Append( new wxLongStringProperty("LongStringProperty",

                                          wxPG_LABEL,
                                          wxPG_LABEL,

-                                         wxT("This is much longer string than the ")
-                                         wxT("first one. Edit it by clicking the button.")));
+                                         "This is much longer string than the "
+                                         "first one. Edit it by clicking the button."));

 
     // String editor with dir selector button.
 
     // String editor with dir selector button.

-    pg->Append( new wxDirProperty(wxT("DirProperty"), wxPG_LABEL, ::wxGetUserHome()) );
+    pg->Append( new wxDirProperty("DirProperty", wxPG_LABEL, ::wxGetUserHome()) );

 
     // wxArrayStringProperty embeds a wxArrayString.
 
     // wxArrayStringProperty embeds a wxArrayString.

-    pg->Append( new wxArrayStringProperty(wxT("Label of ArrayStringProperty"),
-                                          wxT("NameOfArrayStringProp")));
+    pg->Append( new wxArrayStringProperty("Label of ArrayStringProperty",
+                                          "NameOfArrayStringProp"));

 
     // A file selector property.
 
     // A file selector property.

-    pg->Append( new wxFileProperty(wxT("FileProperty"), wxPG_LABEL, wxEmptyString) );
+    pg->Append( new wxFileProperty("FileProperty", wxPG_LABEL, wxEmptyString) );

 
 

-    // Extra: set wildcard for file property (format same as in wxFileDialog).
-    pg->SetPropertyAttribute( wxT("FileProperty"),
+    // Extra: set wild card for file property (format same as in wxFileDialog).
+    pg->SetPropertyAttribute( "FileProperty",

                               wxPG_FILE_WILDCARD,
                               wxPG_FILE_WILDCARD,

-                              wxT("All files (*.*)|*.*") );
+                              "All files (*.*)|*.*" );

 
 @endcode
 
 
 @endcode
 

-  Operations on properties should be done either via wxPropertyGrid's
-(or wxPropertyGridManager's) methods, or by acquiring pointer to a property
-(Append returns a wxPGProperty* or wxPGId, which is typedef for same), and then
-calling its method. Note however that property's methods generally do not
-automatically update grid graphics.
+  Operations on properties are usually done by directly calling wxPGProperty's
+or wxPropertyGridInterface's member functions. wxPropertyGridInterface is an
+abstract base class for property containers such as wxPropertyGrid,
+wxPropertyGridManager, and wxPropertyGridPage. Note however that wxPGProperty's
+member functions generally do not refresh the grid.

 
 

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

 
 @code
 
 @code

-    // A file selector property.
-    wxPGPropety* p = pg->Append( new wxFileProperty(wxT("FileProperty"), wxPG_LABEL, wxEmptyString) );
+    // Add a file selector property.
+    wxPGProperty* prop = pg->Append( new wxFileProperty("FileProperty",
+                                     wxPG_LABEL,
+                                     wxEmptyString) );

 
 

-    // Valid: Set wildcard by name
-    pg->SetPropertyAttribute( wxT("FileProperty"),
+    // Valid: Set wild card by name
+    pg->SetPropertyAttribute( "FileProperty",

                               wxPG_FILE_WILDCARD,
                               wxPG_FILE_WILDCARD,

-                              wxT("All files (*.*)|*.*") );
+                              "All files (*.*)|*.*" );

 
 

-    // Also Valid: Set wildcard by ptr
-    pg->SetPropertyAttribute( p,
+    // Also Valid: Set wild card by property pointer
+    pg->SetPropertyAttribute( prop,

                               wxPG_FILE_WILDCARD,
                               wxPG_FILE_WILDCARD,

-                              wxT("All files (*.*)|*.*") );
-@endcode
-
-Using pointer is faster, since it doesn't require hash map lookup. Anyway, you can allways
-get property pointer (wxPGProperty*) as Append/Insert return value, or by calling
-GetPropertyByName.
-
-  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 );
-
+                              "All files (*.*)|*.*" );

 @endcode
 
 @endcode
 

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

 
 

-@section categories Categories
+@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
 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
-also sets label of a category. Note however that sometimes the label of a
-property category may be referred as caption (for example, there is
-SetCaptionForegroundColour method that sets text colour of a property category's label).
+its name, GetPropertyByName() also returns a category by name. Note however
+that sometimes the label of a property category may be referred as caption
+(for example, there is wxPropertyGrid::SetCaptionTextColour() method
+that sets text colour of property category labels).

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

 
   Category code sample:
 
 @code
 
     // One way to add category (similar to how other properties are added)
 
   Category code sample:
 
 @code
 
     // One way to add category (similar to how other properties are added)

-    pg->Append( new wxPropertyCategory(wxT("Main")) );
+    pg->Append( new wxPropertyCategory("Main") );

 
     // All these are added to "Main" category
 
     // All these are added to "Main" category

-    pg->Append( new wxStringProperty(wxT("Name")) );
-    pg->Append( new wxIntProperty(wxT("Age"),wxPG_LABEL,25) );
-    pg->Append( new wxIntProperty(wxT("Height"),wxPG_LABEL,180) );
-    pg->Append( new wxIntProperty(wxT("Weight")) );
+    pg->Append( new wxStringProperty("Name") );
+    pg->Append( new wxIntProperty("Age",wxPG_LABEL,25) );
+    pg->Append( new wxIntProperty("Height",wxPG_LABEL,180) );
+    pg->Append( new wxIntProperty("Weight") );

 
     // Another one
 
     // Another one

-    pg->Append( new wxPropertyCategory(wxT("Attrikbutes")) );
+    pg->Append( new wxPropertyCategory("Attributes") );

 
     // All these are added to "Attributes" category
 
     // All these are added to "Attributes" category

-    pg->Append( new wxIntProperty(wxT("Intelligence")) );
-    pg->Append( new wxIntProperty(wxT("Agility")) );
-    pg->Append( new wxIntProperty(wxT("Strength")) );
+    pg->Append( new wxIntProperty("Intelligence") );
+    pg->Append( new wxIntProperty("Agility") );
+    pg->Append( new wxIntProperty("Strength") );

 
 @endcode
 
 
 
 @endcode
 
 

-@section parentprops Tree-like Property Structure
+@section propgrid_parentprops Tree-like Property Structure

 
 

-  As a new feature in version 1.3.1, basicly any property can have children. There
-are few limitations, however.
+  Basically any property can have children. There are few limitations, however.

 
 @remarks
 
 @remarks

-- Names of properties with non-category, non-root parents are not stored in hash map.
-  Instead, they can be accessed with strings like "Parent.Child". For instance, in
-  the sample below, child property named "Max. Speed (mph)" can be accessed by global
-  name "Car.Speeds.Max Speed (mph)".
-- If you want to property's value to be a string composed based on the values of
-  child properties, you must use wxStringProperty as parent and use value "<composed>".
+- Names of properties with non-category, non-root parents are not stored in global
+  hash map. Instead, they can be accessed with strings like "Parent.Child".
+  For instance, in the sample below, child property named "Max. Speed (mph)"
+  can be accessed by global name "Car.Speeds.Max Speed (mph)".
+- If you want to property's value to be a string composed of the child property values,
+  you must use wxStringProperty as parent and use magic string "<composed>" as its
+  value.

 - Events (eg. change of value) that occur in parent do not propagate to children. Events
   that occur in children will propagate to parents, but only if they are wxStringProperties
   with "<composed>" value.
 - 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
 
 Sample:
 
 @code

-    wxPGId pid = pg->Append( new wxStringProperty(wxT("Car"),wxPG_LABEL,wxT("<composed>")) );
+    wxPGProperty* carProp = pg->Append(new wxStringProperty("Car",
+                                         wxPG_LABEL,
+                                         "<composed>"));

 
 

-    pg->AppendIn( pid, new wxStringProperty(wxT("Model"),
+    pg->AppendIn(carProp, new wxStringProperty("Model",
+                                                wxPG_LABEL,
+                                                "Lamborghini Diablo SV"));
+
+    pg->AppendIn(carProp, new wxIntProperty("Engine Size (cc)",

                                             wxPG_LABEL,
                                             wxPG_LABEL,

-                                            wxT("Lamborghini Diablo SV")) );
+                                            5707) );

 
 

-    pg->AppendIn( pid, new wxIntProperty(wxT("Engine Size (cc)"),
-                                         wxPG_LABEL,
-                                         5707) );
+    wxPGProperty* speedsProp = pg->AppendIn(carProp,
+                                            new wxStringProperty("Speeds",
+                                              wxPG_LABEL,
+                                              "<composed>"));

 
 

-    wxPGId speedId = pg->AppendIn( pid, new wxStringProperty(wxT("Speeds"),wxPG_LABEL,wxT("<composed>")) );
-    pg->AppendIn( speedId, new wxIntProperty(wxT("Max. Speed (mph)"),wxPG_LABEL,290) );
-    pg->AppendIn( speedId, new wxFloatProperty(wxT("0-100 mph (sec)"),wxPG_LABEL,3.9) );
-    pg->AppendIn( speedId, new wxFloatProperty(wxT("1/4 mile (sec)"),wxPG_LABEL,8.6) );
+    pg->AppendIn( speedsProp, new wxIntProperty("Max. Speed (mph)",
+                                                wxPG_LABEL,290) );
+    pg->AppendIn( speedsProp, new wxFloatProperty("0-100 mph (sec)",
+                                                  wxPG_LABEL,3.9) );
+    pg->AppendIn( speedsProp, new wxFloatProperty("1/4 mile (sec)",
+                                                  wxPG_LABEL,8.6) );

 
 

-    // Make sure the child properties can be accessed correctly
-    pg->SetPropertyValue( wxT("Car.Speeds.Max. Speed (mph)"), 300 );
+    // This is how child property can be referred to by name
+    pg->SetPropertyValue( "Car.Speeds.Max. Speed (mph)", 300 );

 
 

-    pg->AppendIn( pid, new wxIntProperty(wxT("Price ($)"),
-                                         wxPG_LABEL,
-                                         300000) );
-    // Displayed value of "Car" property is now:
-    // "Lamborghini Diablo SV; [300; 3.9; 8.6]; 300000"
+    pg->AppendIn(carProp, new wxIntProperty("Price ($)",
+                                            wxPG_LABEL,
+                                            300000) );
+
+    // Displayed value of "Car" property is now very close to this:
+    // "Lamborghini Diablo SV; 5707 [300; 3.9; 8.6] 300000"

 
 @endcode
 
 
 @endcode
 

-@section enumandflags wxEnumProperty and wxFlagsProperty
+@section propgrid_enumandflags wxEnumProperty and wxFlagsProperty

 
   wxEnumProperty is used when you want property's (integer or string) value
 to be selected from a popup list of choices.
 
 
   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.
-You have to provide list of constant labels, and optionally relevant values
-(if label indexes are not sufficient).
+  Creating wxEnumProperty is slightly more complex than those described
+earlier. You have to provide list of constant labels, and optionally relevant
+values (if label indexes are not sufficient).

 
 @remarks
 
 
 @remarks
 

-- Value wxPG_INVALID_VALUE (equals 2147483647 which usually equals INT_MAX) is not
-  allowed as value.
+- Value wxPG_INVALID_VALUE (equals INT_MAX) is not allowed as list
+  item value.

 
 A very simple example:
 
 
 A very simple example:
 


@@ -307,27 +263,24 @@ A very simple example:
     // Using wxArrayString
     //
     wxArrayString arrDiet;
     // Using wxArrayString
     //
     wxArrayString arrDiet;

-    arr.Add(wxT("Herbivore"));
-    arr.Add(wxT("Carnivore"));
-    arr.Add(wxT("Omnivore"));
+    arr.Add("Herbivore");
+    arr.Add("Carnivore");
+    arr.Add("Omnivore");

 
 

-    pg->Append( new wxEnumProperty(wxT("Diet"),
+    pg->Append( new wxEnumProperty("Diet",

                                    wxPG_LABEL,
                                    arrDiet) );
 
                                    wxPG_LABEL,
                                    arrDiet) );
 

-
-

     //
     // Using wxChar* array
     //
     const wxChar* arrayDiet[] =
     { wxT("Herbivore"), wxT("Carnivore"), wxT("Omnivore"), NULL };
 
     //
     // Using wxChar* array
     //
     const wxChar* arrayDiet[] =
     { wxT("Herbivore"), wxT("Carnivore"), wxT("Omnivore"), NULL };
 

-    pg->Append( new wxEnumProperty(wxT("Diet"),
+    pg->Append( new wxEnumProperty("Diet",

                                    wxPG_LABEL,
                                    arrayDiet) );
 
                                    wxPG_LABEL,
                                    arrayDiet) );
 

-

 @endcode
 
 Here's extended example using values as well:
 @endcode
 
 Here's extended example using values as well:


@@ -338,9 +291,9 @@ Here's extended example using values as well:
     // Using wxArrayString and wxArrayInt
     //
     wxArrayString arrDiet;
     // Using wxArrayString and wxArrayInt
     //
     wxArrayString arrDiet;

-    arr.Add(wxT("Herbivore"));
-    arr.Add(wxT("Carnivore"));
-    arr.Add(wxT("Omnivore"));
+    arr.Add("Herbivore");
+    arr.Add("Carnivore");
+    arr.Add("Omnivore");

 
     wxArrayInt arrIds;
     arrIds.Add(40);
 
     wxArrayInt arrIds;
     arrIds.Add(40);


@@ -349,90 +302,53 @@ Here's extended example using values as well:
 
     // Note that the initial value (the last argument) is the actual value,
     // not index or anything like that. Thus, our value selects "Omnivore".
 
     // Note that the initial value (the last argument) is the actual value,
     // not index or anything like that. Thus, our value selects "Omnivore".

-    pg->Append( new wxEnumProperty(wxT("Diet"),
+    pg->Append( new wxEnumProperty("Diet",

                                    wxPG_LABEL,
                                    arrDiet,
                                    arrIds,
                                    50));
 
                                    wxPG_LABEL,
                                    arrDiet,
                                    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 };
-
-    // Value can be set from string as well
-    pg->Append( new wxEnumProperty(wxT("Diet"),
-                                   wxPG_LABEL,
-                                   array_diet,
-                                   array_diet_ids);
-

 @endcode
 
   wxPGChoices is a class where wxEnumProperty, and other properties which
 @endcode
 
   wxPGChoices is a class where wxEnumProperty, and other properties which

-  require label storage, actually stores strings and values. It is used
-  to facilitiate reference counting, and therefore recommended way of
+  require storage for list of items, actually stores strings and values. It is
+  used to facilitate reference counting, and therefore recommended way of

   adding items when multiple properties share the same set.
 
   You can use wxPGChoices directly as well, filling it and then passing it
   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;
   your best choice is to use this approach.
 
 @code
 
     wxPGChoices chs;

-    chs.Add(wxT("Herbivore"),40);
-    chs.Add(wxT("Carnivore"),45);
-    chs.Add(wxT("Omnivore"),50);
+    chs.Add("Herbivore", 40);
+    chs.Add("Carnivore", 45);
+    chs.Add("Omnivore", 50);

 
     // Let's add an item with bitmap, too
 
     // Let's add an item with bitmap, too

-    chs.Add(wxT("None of the above"), wxBitmap(), 60);
+    chs.Add("None of the above", wxBitmap(), 60);

 
 

-    // Note: you can add even whole arrays to wxPGChoices
-
-    pg->Append( new wxEnumProperty(wxT("Diet"),
+    pg->Append( new wxEnumProperty("Primary Diet",

                                    wxPG_LABEL,
                                    chs) );
 
     // Add same choices to another property as well - this is efficient due
     // to reference counting
                                    wxPG_LABEL,
                                    chs) );
 
     // Add same choices to another property as well - this is efficient due
     // to reference counting

-    pg->Append( new wxEnumProperty(wxT("Diet 2"),
+    pg->Append( new wxEnumProperty("Secondary Diet",

                                    wxPG_LABEL,
                                    chs) );
                                    wxPG_LABEL,
                                    chs) );

-
- @endcode
-
-If you later need to change choices used by a property, there is function
-for that as well.
-
-@code
-
-    //
-    // Example 1: Add one extra item
-    wxPGChoices& choices = pg->GetPropertyChoices(wxT("Diet"));
-    choices.Add(wxT("Custom"),55);
-
-    //
-    // Example 2: Replace all the choices
-    wxPGChoices chs;
-    chs.Add(wxT("<No valid items yet>"),0);
-    pg->SetPropertyChoices(wxT("Diet"),chs);
-

 @endcode
 
 @endcode
 

-If you want to create your enum properties with simple (label,name,value)
-constructor, then you need to create a new property class using one of the
-supplied macro pairs. See @ref newprops for details.
+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
-is uses non-readonly combobox as default editor, and value is stored as
+<b>wxEditEnumProperty</b> works exactly like wxEnumProperty, except
+is uses non-read-only combo box as default editor, and value is stored as

 string when it is not any of the choices.
 
 string when it is not any of the choices.
 

-wxFlagsProperty is similar:
+wxFlagsProperty has similar construction:

 
 @code
 
 
 @code
 


@@ -443,7 +359,7 @@ wxFlagsProperty is similar:
     long flags_prop_values[] = { wxICONIZE, wxCAPTION, wxMINIMIZE_BOX,
         wxMAXIMIZE_BOX };
 
     long flags_prop_values[] = { wxICONIZE, wxCAPTION, wxMINIMIZE_BOX,
         wxMAXIMIZE_BOX };
 

-    pg->Append( new wxFlagsProperty(wxT("Window Style"),
+    pg->Append( new wxFlagsProperty("Window Style",

                                     wxPG_LABEL,
                                     flags_prop_labels,
                                     flags_prop_values,
                                     wxPG_LABEL,
                                     flags_prop_labels,
                                     flags_prop_values,


@@ -452,12 +368,11 @@ wxFlagsProperty is similar:
 @endcode
 
 wxFlagsProperty can use wxPGChoices just the same way as wxEnumProperty
 @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,
-you will need to use SetPropertyChoices - otherwise they will not get updated
-properly.
+<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 implicit child properties will not get updated properly.

 
 

-@section advprops Specialized Properties
+@section propgrid_advprops Specialized Properties

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


@@ -470,50 +385,105 @@ To use them, you have to include <wx/propgrid/advprops.h>.
 ...
 
     // Date property.
 ...
 
     // Date property.

-    pg->Append( new wxDateProperty(wxT("MyDateProperty"),
+    pg->Append( new wxDateProperty("MyDateProperty",

                                    wxPG_LABEL,
                                    wxDateTime::Now()) );
 
                                    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.
     // image handlers, so it is not set this time.

-    pg->Append( new wxImageFileProperty(wxT("Label of ImageFileProperty"),
-                                        wxT("NameOfImageFileProp")) );
+    pg->Append( new wxImageFileProperty("Label of ImageFileProperty",
+                                        "NameOfImageFileProp") );

 
     // Font property has sub-properties. Note that we give window's font as
     // initial value.
 
     // Font property has sub-properties. Note that we give window's font as
     // initial value.

-    pg->Append( new wxFontProperty(wxT("Font"),
+    pg->Append( new wxFontProperty("Font",

                                    wxPG_LABEL,
                                    GetFont()) );
 
     // Colour property with arbitrary colour.
                                    wxPG_LABEL,
                                    GetFont()) );
 
     // Colour property with arbitrary colour.

-    pg->Append( new wxColourProperty(wxT("My Colour 1"),
+    pg->Append( new wxColourProperty("My Colour 1",

                                      wxPG_LABEL,
                                      wxColour(242,109,0) ) );
 
     // System colour property.
                                      wxPG_LABEL,
                                      wxColour(242,109,0) ) );
 
     // System colour property.

-    pg->Append( new wxSystemColourProperty(wxT("My SysColour 1"),
+    pg->Append( new wxSystemColourProperty("My SysColour 1",

                                            wxPG_LABEL,
                                            wxSystemSettings::GetColour(wxSYS_COLOUR_WINDOW)) );
 
     // System colour property with custom colour.
                                            wxPG_LABEL,
                                            wxSystemSettings::GetColour(wxSYS_COLOUR_WINDOW)) );
 
     // System colour property with custom colour.

-    pg->Append( new wxSystemColourProperty(wxT("My SysColour 2"),
+    pg->Append( new wxSystemColourProperty("My SysColour 2",

                                            wxPG_LABEL,
                                            wxColour(0,200,160) ) );
 
     // Cursor property
                                            wxPG_LABEL,
                                            wxColour(0,200,160) ) );
 
     // Cursor property

-    pg->Append( new wxCursorProperty(wxT("My Cursor"),
+    pg->Append( new wxCursorProperty("My Cursor",

                                      wxPG_LABEL,
                                      wxCURSOR_ARROW));
 
 @endcode
 
 
                                      wxPG_LABEL,
                                      wxCURSOR_ARROW));
 
 @endcode
 
 

-@section iterating Iterating through a property container
+@section propgrid_processingvalues Processing Property Values
+
+Properties store their values internally as wxVariant, but is also possible to
+obtain them as wxAny, using implicit conversion. You can get property
+values with wxPGProperty::GetValue() and
+wxPropertyGridInterface::GetPropertyValue().
+
+Below is a code example which handles wxEVT_PG_CHANGED event:
+
+@code
+
+void MyWindowClass::OnPropertyGridChanged(wxPropertyGridEvent& event)
+{
+    wxPGProperty* property = event.GetProperty();
+
+    // Do nothing if event did not have associated property
+    if ( !property )
+        return;
+
+    // GetValue() returns wxVariant, but it is converted transparently to
+    // wxAny
+    wxAny value = property->GetValue();
+
+    // Also, handle the case where property value is unspecified
+    if ( value.IsNull() )
+        return;
+
+    // Handle changes in values, as needed
+    if ( property->GetName() == "MyStringProperty" )
+        OnMyStringPropertyChanged(value.As<wxString>());
+    else if ( property->GetName() == "MyColourProperty" )
+        OnMyColourPropertyChanged(value.As<wxColour>());
+}
+
+@endcode
+
+You can get a string-representation of property's value using
+wxPGProperty::GetValueAsString() or
+wxPropertyGridInterface::GetPropertyValueAsString(). This particular function
+is very safe to use with any kind of property.
+
+@note There is a one case in which you may want to take extra care when
+      dealing with raw wxVariant values. That is, integer-type properties,
+      such as wxIntProperty and wxUIntProperty, store value internally as
+      wx(U)LongLong when number doesn't fit into standard long type. Using
+      << operator to get wx(U)LongLong from wxVariant is customized to work
+      quite safely with various types of variant data. However, you can also
+      bypass this problem by using wxAny in your code instead of wxVariant.
+
+Note that in some cases property value can be Null variant, which means
+that property value is unspecified. This usually occurs only when
+wxPG_EX_AUTO_UNSPECIFIED_VALUES extra window style is defined or when you
+manually set property value to Null (or unspecified).
+
+
+@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
 
 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'
-to application code):
+properties (not categories nor private child properties that are normally
+'transparent' to application code):

 
 @code
 
 
 @code
 


@@ -547,9 +517,8 @@ As expected there is also a const iterator:
 
 You can give some arguments to GetIterator to determine which properties
 get automatically filtered out. For complete list of options, see
 
 You can give some arguments to GetIterator to determine which properties
 get automatically filtered out. For complete list of options, see

-@link iteratorflags List of Property Iterator Flags@endlink. GetIterator()
-also accepts other arguments. See wxPropertyGridInterface::GetIterator()
-for details.
+@ref propgrid_iterator_flags. GetIterator() also accepts other arguments.
+See wxPropertyGridInterface::GetIterator() for details.

 
 This example reverse-iterates through all visible items:
 
 
 This example reverse-iterates through all visible items:
 


@@ -567,19 +536,17 @@ This example reverse-iterates through all visible items:
 
 @endcode
 
 
 @endcode
 

-<b>wxPython Note:</b> Instead of ++ operator, use Next() method, and instead of
-* operator, use GetProperty() method.
-

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

 
 @code
 
     wxPGVIterator it;
 
 
 @code
 
     wxPGVIterator it;
 

-    for ( it = manager->GetVIterator();
+    for ( it = manager->GetVIterator(wxPG_ITERATE_ALL);

           !it.AtEnd();
           it.Next() )
     {
           !it.AtEnd();
           it.Next() )
     {


@@ -589,61 +556,19 @@ Note however that this virtual iterater is limited to forward iteration.
 
 @endcode
 
 
 @endcode
 

+@section propgrid_populating Populating wxPropertyGrid Automatically

 
 

-@section 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 populating Populating wxPropertyGrid Automatically
-
-@subsection fromvariants Populating from List of wxVariants
+@subsection propgrid_fromvariants Populating from List of wxVariants

 
 Example of populating an empty wxPropertyGrid from a values stored
 in an arbitrary list of wxVariants.
 
 @code
 
 
 Example of populating an empty wxPropertyGrid from a values stored
 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
     // 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
     pg->InitAllTypeHandlers();
 
     // Get contents of the grid as a wxVariant list


@@ -653,46 +578,23 @@ in an arbitrary list of wxVariants.
     // name is not found, it is created according to the type of variant.
     pg->SetPropertyValues( my_list_variant );
 
     // 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
 
 @endcode
 

-@subsection fromfile Loading Population from a Text-based Storage
+@subsection propgrid_fromfile Loading Population from a Text-based Storage

 
 Class wxPropertyGridPopulator may be helpful when writing code that
 
 Class wxPropertyGridPopulator may be helpful when writing code that

-loads properties from a text-source. In fact, the supplied xrc handler
-(src/xh_propgrid.cpp) uses it. See that code for more info.
-NOTE: src/xh_propgrid.cpp is not included in the library by default,
-to avoid dependency to wxXRC. You will need to add it to your application
-separately.
+loads properties from a text-source. In fact, the wxPropertyGrid xrc-handler
+(which may not be currently included in wxWidgets, but probably will be in
+near future) uses it.

 
 @subsection 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 events Event Handling
+@section propgrid_events Event Handling

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


@@ -700,62 +602,14 @@ in your event table to use it.
 
 For complete list of event types, see wxPropertyGrid class reference.
 
 
 For complete list of event types, see wxPropertyGrid class reference.
 

-The custom event class, wxPropertyGridEvent, has methods to directly
-access the property that triggered the event.
-
-Here's a small sample:
+However, one type of event that might need focused attention is EVT_PG_CHANGING,
+which occurs just prior property value is being changed by user. You can
+acquire pending value using wxPropertyGridEvent::GetValue(), and if it is
+not acceptable, call wxPropertyGridEvent::Veto() to prevent the value change
+from taking place.

 
 @code
 
 
 @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();
 void MyForm::OnPropertyGridChanging( wxPropertyGridEvent& event )
 {
     wxPGProperty* property = event.GetProperty();


@@ -774,25 +628,39 @@ void MyForm::OnPropertyGridChanging( wxPropertyGridEvent& event )
 
 @endcode
 
 
 @endcode
 

-@remarks On Sub-property Event Handling
-- For aggregate type properties (wxFontProperty, wxFlagsProperty, etc), events
-  occur for the main parent property only. For other properties events occur
-  for the children themselves..
+@remarks On Child Property Event Handling
+- For properties which have private, implicit children (wxFontProperty and
+  wxFlagsProperty), events occur for the main parent property only.
+  For other properties events occur for the children themselves. See
+  @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).
 
   to obtain its topmost non-category parent (useful, if you have deeply nested
   properties).
 

+@section propgrid_tooltipandhint Help String, Hint and Tool Tips
+
+For each property you can specify two different types of help text. First,
+you can use wxPropertyGridInterface::SetPropertyHelpString() or
+wxPGProperty::SetHelpString() to set property's help text. Second, you
+can use wxPGProperty::SetAttribute() to set property's "Hint" attribute.
+
+Difference between hint and help string is that the hint is shown in an empty
+property value cell, while help string is shown either in the description text
+box, as a tool tip, or on the status bar, whichever of these is available.
+
+To enable display of help string as tool tips, you must explicitly use
+the wxPG_EX_HELP_AS_TOOLTIPS extra window style.

 
 

-@section validating Validating Property Values
+@section propgrid_validating Validating Property Values

 
 There are various ways to make sure user enters only correct values. First, you
 can use wxValidators similar to as you would with ordinary controls. Use
 
 There are various ways to make sure user enters only correct values. First, you
 can use wxValidators similar to as you would with ordinary controls. Use

-wxPropertyGridInterface::SetPropertyValidator() to assign wxValidator to 
+wxPropertyGridInterface::SetPropertyValidator() to assign wxValidator to

 property.
 
 Second, you can subclass a property and override wxPGProperty::ValidateValue(),
 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.
 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.


@@ -812,20 +680,21 @@ message.
         // the value to be validated.
         wxVariant pendingValue = event.GetValue();
 
         // the value to be validated.
         wxVariant pendingValue = event.GetValue();
 

-        if ( property->GetName() == wxT("Font") )
+        if ( property->GetName() == "Font" )

         {
             // Make sure value is not unspecified
             if ( !pendingValue.IsNull() )
             {
         {
             // Make sure value is not unspecified
             if ( !pendingValue.IsNull() )
             {

-                wxFont font << pendingValue;
+                wxFont font;
+                font << pendingValue;

 
                 // Let's just allow Arial font
 
                 // Let's just allow Arial font

-                if ( font.GetFaceName() != wxT("Arial") )
+                if ( font.GetFaceName() != "Arial" )

                 {
                     event.Veto();
                     event.SetValidationFailureBehavior(wxPG_VFB_STAY_IN_PROPERTY |
                                                        wxPG_VFB_BEEP |
                 {
                     event.Veto();
                     event.SetValidationFailureBehavior(wxPG_VFB_STAY_IN_PROPERTY |
                                                        wxPG_VFB_BEEP |

-                                                       wxPG_VFB_SHOW_MESSAGE);
+                                                       wxPG_VFB_SHOW_MESSAGEBOX);

                 }
             }
         }
                 }
             }
         }


@@ -833,42 +702,81 @@ message.
 @endcode
 
 
 @endcode
 
 

-@section cellrender Customizing Individual Cell Appearance
+@section propgrid_cellrender Customizing Individual Cell Appearance

 
 You can control text colour, background colour, and attached image of
 each cell in the property grid. Use wxPropertyGridInterface::SetPropertyCell() or
 wxPGProperty::SetCell() for this purpose.
 
 In addition, it is possible to control these characteristics for
 
 You can control text colour, background colour, and attached image of
 each cell in the property grid. Use wxPropertyGridInterface::SetPropertyCell() or
 wxPGProperty::SetCell() for this purpose.
 
 In addition, it is possible to control these characteristics for

-wxPGChoices list items. See wxPGChoices::Item() and wxPGChoiceEntry class
-reference for more info.
+wxPGChoices list items. See wxPGChoices class reference for more info.

 
 

+@section propgrid_keyhandling Customizing Keyboard Handling

 
 

-@section customizing Customizing Properties (without sub-classing)
+There is probably one preference for keyboard handling for every developer
+out there, and as a conveniency control wxPropertyGrid tries to cater for
+that. By the default arrow keys are used for navigating between properties,
+and TAB key is used to move focus between the property editor and the
+first column. When the focus is in the editor, arrow keys usually no longer
+work for navigation since they are consumed by the editor.
+
+There are mainly two functions which you can use this customize things,
+wxPropertyGrid::AddActionTrigger() and wxPropertyGrid::DedicateKey().
+First one can be used to set a navigation event to occur on a specific key
+press and the second is used to divert a key from property editors, making it
+possible for the grid to use keys normally consumed by the focused editors.
+
+For example, let's say you want to have an ENTER-based editing scheme. That
+is, editor is focused on ENTER press and the next property is selected when
+the user finishes editing and presses ENTER again. Code like this would
+accomplish the task:
+
+@code
+    // Have property editor focus on Enter
+    propgrid->AddActionTrigger( wxPG_ACTION_EDIT, WXK_RETURN );
+    
+    // Have Enter work as action trigger even when editor is focused
+    propgrid->DedicateKey( WXK_RETURN );
+    
+    // Let Enter also navigate to the next property
+    propgrid->AddActionTrigger( wxPG_ACTION_NEXT_PROPERTY, WXK_RETURN );
+
+@endcode
+
+wxPG_ACTION_EDIT is prioritized above wxPG_ACTION_NEXT_PROPERTY so that the
+above code can work without conflicts. For a complete list of available
+actions, see @ref propgrid_keyboard_actions.
+
+Here's another trick. Normally the up and down cursor keys are consumed by
+the focused wxTextCtrl editor and as such can't be used for navigating between
+properties when that editor is focused. However, using DedicateKey() we can
+change this so that instead of the cursor keys moving the caret inside the
+wxTextCtrl, they navigate between adjacent properties. As such:
+
+@code
+    propgrid->DedicateKey(WXK_UP);
+    propgrid->DedicateKey(WXK_DOWN);
+@endcode
+
+
+@section propgrid_customizing Customizing Properties (without sub-classing)

 
 In this section are presented miscellaneous ways to have custom appearance
 
 In this section are presented miscellaneous ways to have custom appearance

-and behavior for your properties without all the necessary hassle
+and behaviour for your properties without all the necessary hassle

 of sub-classing a property class etc.
 
 of sub-classing a property class etc.
 

-@subsection customimage Setting Value Image
+@subsection propgrid_customimage Setting Value Image

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

-@subsection 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 customeditor Setting Property's Editor Control(s)
+@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
 
 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().
 TextCtrl, Choice, ComboBox, CheckBox, TextCtrlAndButton, ChoiceAndButton,
 SpinCtrl, and DatePickerCtrl. Two last mentioned ones require call to
 static member function wxPropertyGrid::RegisterAdditionalEditors().


@@ -880,132 +788,66 @@ colour selection dialog.
 
 @code
 
 
 @code
 

-    wxPGId colProp = pg->Append(wxColourProperty(wxT("Text Colour")));
-
-    pg->SetPropertyEditor(colProp,wxPG_EDITOR(TextCtrlAndButton));
+    wxPGProperty* colProp = new wxColourProperty("Text Colour");
+    pg->Append(colProp);
+    pg->SetPropertyEditor(colProp, wxPGEditor_TextCtrlAndButton);

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

-@subsection editorattrs Property Attributes Recognized by Editors
+@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 multiplebuttons Adding Multiple Buttons Next to an Editor
+@subsection propgrid_multiplebuttons Adding Multiple Buttons Next to an Editor

 
 See wxPGMultiButton class reference.
 
 
 See wxPGMultiButton class reference.
 

-@subsection customeventhandling Handling Events Passed from Properties
+@subsection propgrid_customeventhandling Handling Events Passed from Properties

 
 <b>wxEVT_COMMAND_BUTTON_CLICKED </b>(corresponds to event table macro EVT_BUTTON):
 Occurs when editor button click is not handled by the property itself
 (as is the case, for example, if you set property's editor to TextCtrlAndButton
 from the original TextCtrl).
 
 
 <b>wxEVT_COMMAND_BUTTON_CLICKED </b>(corresponds to event table macro EVT_BUTTON):
 Occurs when editor button click is not handled by the property itself
 (as is the case, for example, if you set property's editor to TextCtrlAndButton
 from the original TextCtrl).
 

-@subsection attributes Property Attributes
+@subsection propgrid_attributes Property Attributes

 
 Miscellaneous values, often specific to a property type, can be set
 
 Miscellaneous values, often specific to a property type, can be set

-using wxPropertyGrid::SetPropertyAttribute and wxPropertyGrid::SetPropertyAttributeAll
-methods.
+using wxPropertyGridInterface::SetPropertyAttribute() and
+wxPropertyGridInterface::SetPropertyAttributeAll() methods.

 
 Attribute names are strings and values wxVariant. Arbitrary names are allowed
 
 Attribute names are strings and values wxVariant. Arbitrary names are allowed

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

 
 

-For complete list of attributes, see @link attrids Property Attributes@endlink.
+For complete list of attributes, see @ref propgrid_property_attributes.

 
 

-@subsection 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 usage2 Using wxPropertyGridManager
+@section propgrid_usage2 Using wxPropertyGridManager

 
 wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,
 
 wxPropertyGridManager is an efficient multi-page version of wxPropertyGrid,

-which can optionally have toolbar for mode and page selection, and a help text
-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 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
-       );
+which can optionally have tool bar for mode and page selection, and a help text
+box. For more information, see wxPropertyGridManager class reference.

 
 

-    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 propgridpage wxPropertyGridPage
+@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
 
 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
 
 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 subclassing Subclassing wxPropertyGrid and wxPropertyGridManager
+
+@section propgrid_subclassing Sub-classing wxPropertyGrid and wxPropertyGridManager

 
 Few things to note:
 
 
 Few things to note:
 


@@ -1013,47 +855,56 @@ Few things to note:
   just e-mail to wx-dev mailing list.
 
 - Data manipulation is done in wxPropertyGridPageState class. So, instead of
   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.
-  For wxPropertyGridManager, you'll need to subclass wxPropertyGridPage instead (since it
-  is derived from wxPropertyGridPageState), and hand over instances in wxPropertyGridManager::AddPage
-  calls.
+- Override wxPropertyGrid::CreateState() to instantiate your derivate
+  wxPropertyGridPageState. For wxPropertyGridManager, you'll need to subclass
+  wxPropertyGridPage instead (since it is derived from wxPropertyGridPageState),
+  and hand over instances in wxPropertyGridManager::AddPage() calls.

 
 

-- You can use a derivate wxPropertyGrid with manager by overriding wxPropertyGridManager::CreatePropertyGrid
-  member function.
+- You can use a derivate wxPropertyGrid with manager by overriding
+  wxPropertyGridManager::CreatePropertyGrid() member function.

 
 
 
 

-@section misc Miscellaneous Topics
+@section propgrid_misc Miscellaneous Topics

 
 

-@subsection namescope Property Name Scope
+@subsection propgrid_namescope Property Name Scope

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

-@subsection nonuniquelabels Non-unique Labels
+@subsection propgrid_nonuniquelabels Non-unique Labels

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

-@subsection boolproperty wxBoolProperty
+@subsection propgrid_boolproperty wxBoolProperty

 
 

-  There are few points about wxBoolProperty that require futher discussion:
-  - wxBoolProperty can be shown as either normal combobox or as a checkbox.
+  There are few points about wxBoolProperty that require further discussion:
+  - wxBoolProperty can be shown as either normal combo box or as a check box.

     Property attribute wxPG_BOOL_USE_CHECKBOX is used to change this.
     For example, if you have a wxFlagsProperty, you can
     set its all items to use check box using the following:
     @code
     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);
+        pg->SetPropertyAttribute("MyFlagsProperty", wxPG_BOOL_USE_CHECKBOX, true, wxPG_RECURSE);

     @endcode
 
     @endcode
 

-  - Default item names for wxBoolProperty are [wxT("False"),wxT("True")]. This can be
-    changed using wxPropertyGrid::SetBoolChoices(trueChoice,falseChoice).
+    Following will set all individual bool properties in your control to
+    use check box:

 
 

-@subsection textctrlupdates Updates from wxTextCtrl Based Editor
+    @code
+        pg->SetPropertyAttributeAll(wxPG_BOOL_USE_CHECKBOX, true);
+    @endcode
+
+  - Default item names for wxBoolProperty are ["False", "True"]. This can be
+    changed using static function wxPropertyGrid::SetBoolChoices(trueChoice,
+    falseChoice).
+
+@subsection propgrid_textctrlupdates Updates from wxTextCtrl Based Editor

 
   Changes from wxTextCtrl based property editors are committed (ie.
 wxEVT_PG_CHANGED is sent etc.) *only* when (1) user presser enter, (2)
 
   Changes from wxTextCtrl based property editors are committed (ie.
 wxEVT_PG_CHANGED is sent etc.) *only* when (1) user presser enter, (2)


@@ -1066,7 +917,7 @@ computations based on property grid values. Note that CommitChangesFromEditor()
 will dispatch wxEVT_PG_CHANGED with ProcessEvent, so any of your event handlers
 will be called immediately.
 
 will dispatch wxEVT_PG_CHANGED with ProcessEvent, so any of your event handlers
 will be called immediately.
 

-@subsection splittercentering Centering the Splitter
+@subsection propgrid_splittercentering Centering the Splitter

 
   If you need to center the splitter, but only once when the program starts,
 then do <b>not</b> use the wxPG_SPLITTER_AUTO_CENTER window style, but the
 
   If you need to center the splitter, but only once when the program starts,
 then do <b>not</b> use the wxPG_SPLITTER_AUTO_CENTER window style, but the


@@ -1074,15 +925,20 @@ wxPropertyGrid::CenterSplitter() method. <b>However, be sure to call it after
 the sizer setup and SetSize calls!</b> (ie. usually at the end of the
 frame/dialog constructor)
 
 the sizer setup and SetSize calls!</b> (ie. usually at the end of the
 frame/dialog constructor)
 

-@subsection splittersetting Setting Splitter Position When Creating Property Grid
+  Splitter centering behaviour can be customized using
+wxPropertyGridInterface::SetColumnProportion(). Usually it is used to set
+non-equal column proportions, which in essence stops the splitter(s) from
+being 'centered' as such, and instead just auto-resized.
+
+@subsection propgrid_splittersetting Setting Splitter Position When Creating Property Grid

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

-@subsection colourproperty wxColourProperty and wxSystemColourProperty
+@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.
 features. Subclass wxSystemColourProperty if you want to use wxColourPropertyValue
 (which features colour type in addition to wxColour), and wxColourProperty if plain
 wxColour is enough.


@@ -1096,9 +952,115 @@ the item that triggers colour picker dialog (default is last).
 Override wxSystemColourProperty::GetColour() to determine which colour matches
 which choice entry.
 
 Override wxSystemColourProperty::GetColour() to determine which colour matches
 which choice entry.
 

-@section proplist Property Class Descriptions
+@section propgrid_proplist Property Class Descriptions

 
 See @ref pgproperty_properties
 
 
 See @ref pgproperty_properties
 

-*/
+@section propgrid_compat Changes from wxPropertyGrid 1.4
+
+Version of wxPropertyGrid bundled with wxWidgets 2.9+ has various backward-
+incompatible changes from version 1.4, which had a stable API and will remain
+as the last separate branch.
+
+Note that in general any behaviour-breaking changes should not compile or run
+without warnings or errors.
+
+@subsection propgrid_compat_general General Changes
+
+  - Tab-traversal can no longer be used to travel between properties. Now
+    it only causes focus to move from main grid to editor of selected property.
+    Arrow keys are now your primary means of navigating between properties,
+    with keyboard. This change allowed fixing broken tab traversal on wxGTK
+    (which is open issue in wxPropertyGrid 1.4).
+
+  - wxPG_EX_UNFOCUS_ON_ENTER style is removed and is now default behaviour.
+    That is, when enter is pressed, editing is considered done and focus
+    moves back to the property grid from the editor control.
+
+  - A few member functions were removed from wxPropertyGridInterface.
+    Please use wxPGProperty's counterparts from now on.
+
+  - wxPGChoices now has proper Copy-On-Write behaviour.
+
+  - wxPGChoices::SetExclusive() was renamed to AllocExclusive().

 
 

+  - wxPGProperty::SetPropertyChoicesExclusive() was removed. Instead, use
+    GetChoices().AllocExclusive().
+
+  - wxPGProperty::ClearModifiedStatus() is removed. Please use
+    SetModifiedStatus() instead.
+
+  - wxPropertyGridInterface::GetExpandedProperties() is removed. You should
+    now use wxPropertyGridInterface::GetEditableState() instead.
+
+  - wxPG_EX_DISABLE_TLP_TRACKING is now enabled by default. To get the old
+    behaviour (recommended if you don't use a system that reparents the grid
+    on its own), use the wxPG_EX_ENABLE_TLP_TRACKING extra style.
+
+  - Extended window style wxPG_EX_LEGACY_VALIDATORS was removed.
+
+  - Default property validation failure behaviour has been changed to
+    (wxPG_VFB_MARK_CELL | wxPG_VFB_SHOW_MESSAGEBOX), which means that the
+    cell is marked red and wxMessageBox is shown. This is more user-friendly
+    than the old behaviour, which simply beeped and prevented leaving the
+    property editor until a valid value was entered.
+
+  - wxPropertyGridManager now has same Get/SetSelection() semantics as
+    wxPropertyGrid.
+
+  - Various wxPropertyGridManager page-related functions now return pointer
+    to the page object instead of index.
+
+  - wxArrayEditorDialog used by wxArrayStringProperty and some sample
+    properties has been renamed to wxPGArrayEditorDialog. Also, it now uses
+    wxEditableListBox for editing.
+
+  - Instead of calling wxPropertyGrid::SetButtonShortcut(), use
+    wxPropertyGrid::SetActionTrigger(wxPG_ACTION_PRESS_BUTTON).
+
+  - wxPGProperty::GetCell() now returns a reference. AcquireCell() was removed.
+
+  - wxPGMultiButton::FinalizePosition() has been renamed to Finalize(),
+    and it has slightly different argument list.
+
+  - wxPropertyGridEvent::HasProperty() is removed. You can use GetProperty()
+    as immediate replacement when checking if event has a property.
+
+  - "InlineHelp" property has been replaced with "Hint".
+
+  - wxPropertyGrid::CanClose() has been removed. Call
+    wxPropertyGridInterface::EditorValidate() instead.
+
+  - wxPGProperty::SetFlag() has been moved to private API. This was done to
+    underline the fact that it was not the preferred method to change a
+    property's state since it never had any desired side-effects. ChangeFlag()
+    still exists for those who really need to achieve the same effect.
+
+  - wxArrayStringProperty default delimiter is now comma (','), and it can
+    be changed by setting the new "Delimiter" attribute.
+
+@subsection propgrid_compat_propdev Property and Editor Sub-classing Changes
+
+  - Confusing custom property macros have been eliminated.
+
+  - Implement wxPGProperty::ValueToString() instead of GetValueAsString().
+
+  - wxPGProperty::ChildChanged() must now return the modified value of
+    whole property instead of writing it back into 'thisValue' argument.
+
+  - Removed wxPropertyGrid::PrepareValueForDialogEditing(). Use
+    wxPropertyGrid::GetPendingEditedValue() instead.
+
+  - wxPGProperty::GetChoiceInfo() is removed, as all properties now carry
+    wxPGChoices instance (protected wxPGProperty::m_choices).
+
+  - Connect() should no longer be called in implementations of
+    wxPGEditor::CreateControls(). wxPropertyGrid automatically passes all
+    events from editor to wxPGEditor::OnEvent() and wxPGProperty::OnEvent(),
+    as appropriate.
+
+  - wxPython: Previously some of the reimplemented member functions needed a
+    'Py' prefix. This is no longer necessary. For instance, if you previously
+    implemented PyStringToValue() for your custom property, you should now
+    just implement StringToValue().
+*/