Merge in from trunk r67662 to r64801

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

diff --git a/docs/doxygen/overviews/propgrid.h b/docs/doxygen/overviews/propgrid.h
index 4da34e5ba70d3aefc4573056e1d6634774cb8d09..e27fac15c5806921cc2906d12dbe150d267f69b6 100644 (file)
--- a/docs/doxygen/overviews/propgrid.h
+++ b/docs/doxygen/overviews/propgrid.h
@@ -2,8 +2,8 @@
 // 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

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -23,6 +23,10 @@ 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.
 
 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.
+

 @li @ref propgrid_basics
 @li @ref propgrid_categories
 @li @ref propgrid_parentprops
 @li @ref propgrid_basics
 @li @ref propgrid_categories
 @li @ref propgrid_parentprops


@@ -31,14 +35,17 @@ add more than two columns, and set arbitrary per-property attributes.
 @li @ref propgrid_processingvalues
 @li @ref propgrid_iterating
 @li @ref propgrid_events
 @li @ref propgrid_processingvalues
 @li @ref propgrid_iterating
 @li @ref propgrid_events

+@li @ref propgrid_tooltipandhint

 @li @ref propgrid_validating
 @li @ref propgrid_populating
 @li @ref propgrid_cellrender
 @li @ref propgrid_validating
 @li @ref propgrid_populating
 @li @ref propgrid_cellrender

+@li @ref propgrid_keyhandling

 @li @ref propgrid_customizing
 @li @ref propgrid_usage2
 @li @ref propgrid_subclassing
 @li @ref propgrid_misc
 @li @ref propgrid_proplist
 @li @ref propgrid_customizing
 @li @ref propgrid_usage2
 @li @ref propgrid_subclassing
 @li @ref propgrid_misc
 @li @ref propgrid_proplist

+@li @ref propgrid_compat

 
 @section propgrid_basics Creating and Populating wxPropertyGrid
 
 
 @section propgrid_basics Creating and Populating wxPropertyGrid
 


@@ -79,7 +86,7 @@ other wxWidgets controls:
   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)


@@ -94,34 +101,34 @@ 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 wild card for file property (format same as in wxFileDialog).
 
     // Extra: set wild card for file property (format same as in wxFileDialog).

-    pg->SetPropertyAttribute( wxT("FileProperty"),
+    pg->SetPropertyAttribute( "FileProperty",

                               wxPG_FILE_WILDCARD,
                               wxPG_FILE_WILDCARD,

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

 
 @endcode
 
 
 @endcode
 


@@ -138,19 +145,19 @@ argument, using which you can refer to properties either by their pointer
 
 @code
     // Add a file selector property.
 
 @code
     // Add a file selector property.

-    wxPGPropety* prop = pg->Append( new wxFileProperty(wxT("FileProperty"),
+    wxPGPropety* prop = pg->Append( new wxFileProperty("FileProperty",

                                     wxPG_LABEL,
                                     wxEmptyString) );
 
     // Valid: Set wild card by name
                                     wxPG_LABEL,
                                     wxEmptyString) );
 
     // Valid: Set wild card by name

-    pg->SetPropertyAttribute( wxT("FileProperty"),
+    pg->SetPropertyAttribute( "FileProperty",

                               wxPG_FILE_WILDCARD,
                               wxPG_FILE_WILDCARD,

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

 
     // Also Valid: Set wild card by property pointer
     pg->SetPropertyAttribute( prop,
                               wxPG_FILE_WILDCARD,
 
     // Also Valid: Set wild card by property pointer
     pg->SetPropertyAttribute( prop,
                               wxPG_FILE_WILDCARD,

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

 @endcode
 
   Using pointer is faster, since it doesn't require hash map lookup. Anyway,
 @endcode
 
   Using pointer is faster, since it doesn't require hash map lookup. Anyway,


@@ -180,21 +187,21 @@ or wxPropertyGridInterface::AppendIn.
 @code
 
     // One way to add category (similar to how other properties are added)
 @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("Attributes")) );
+    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
 


@@ -218,34 +225,34 @@ or wxPropertyGridInterface::AppendIn.
 Sample:
 
 @code
 Sample:
 
 @code

-    wxPGProperty* carProp = pg->Append(new wxStringProperty(wxT("Car"),
+    wxPGProperty* carProp = pg->Append(new wxStringProperty("Car",

                                          wxPG_LABEL,
                                          wxPG_LABEL,

-                                         wxT("<composed>")));
+                                         "<composed>"));

 
 

-    pg->AppendIn(carProp, new wxStringProperty(wxT("Model"),
+    pg->AppendIn(carProp, new wxStringProperty("Model",

                                                 wxPG_LABEL,
                                                 wxPG_LABEL,

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

 
 

-    pg->AppendIn(carProp, new wxIntProperty(wxT("Engine Size (cc)"),
+    pg->AppendIn(carProp, new wxIntProperty("Engine Size (cc)",

                                             wxPG_LABEL,
                                             5707) );
 
     wxPGProperty* speedsProp = pg->AppendIn(carProp,
                                             wxPG_LABEL,
                                             5707) );
 
     wxPGProperty* speedsProp = pg->AppendIn(carProp,

-                                            new wxStringProperty(wxT("Speeds"),
+                                            new wxStringProperty("Speeds",

                                               wxPG_LABEL,
                                               wxPG_LABEL,

-                                              wxT("<composed>")));
+                                              "<composed>"));

 
 

-    pg->AppendIn( speedsProp, new wxIntProperty(wxT("Max. Speed (mph)"),
+    pg->AppendIn( speedsProp, new wxIntProperty("Max. Speed (mph)",

                                                 wxPG_LABEL,290) );
                                                 wxPG_LABEL,290) );

-    pg->AppendIn( speedsProp, new wxFloatProperty(wxT("0-100 mph (sec)"),
+    pg->AppendIn( speedsProp, new wxFloatProperty("0-100 mph (sec)",

                                                   wxPG_LABEL,3.9) );
                                                   wxPG_LABEL,3.9) );

-    pg->AppendIn( speedsProp, new wxFloatProperty(wxT("1/4 mile (sec)"),
+    pg->AppendIn( speedsProp, new wxFloatProperty("1/4 mile (sec)",

                                                   wxPG_LABEL,8.6) );
 
     // This is how child property can be referred to by name
                                                   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->SetPropertyValue( "Car.Speeds.Max. Speed (mph)", 300 );

 
 

-    pg->AppendIn(carProp, new wxIntProperty(wxT("Price ($)"),
+    pg->AppendIn(carProp, new wxIntProperty("Price ($)",

                                             wxPG_LABEL,
                                             300000) );
 
                                             wxPG_LABEL,
                                             300000) );
 


@@ -276,11 +283,11 @@ 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) );
 


@@ -290,7 +297,7 @@ A very simple example:
     const wxChar* arrayDiet[] =
     { wxT("Herbivore"), wxT("Carnivore"), wxT("Omnivore"), NULL };
 
     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) );
 


@@ -304,9 +311,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);


@@ -315,7 +322,7 @@ 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,
                                    wxPG_LABEL,
                                    arrDiet,
                                    arrIds,


@@ -335,20 +342,20 @@ Here's extended example using values as well:
 @code
 
     wxPGChoices chs;
 @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);

 
 

-    pg->Append( new wxEnumProperty(wxT("Primary 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("Secondary Diet"),
+    pg->Append( new wxEnumProperty("Secondary Diet",

                                    wxPG_LABEL,
                                    chs) );
 @endcode
                                    wxPG_LABEL,
                                    chs) );
 @endcode


@@ -372,7 +379,7 @@ wxFlagsProperty has similar construction:
     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,


@@ -398,38 +405,38 @@ 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()) );
 
     // Image file property. Wild card is auto-generated from available
     // image handlers, so it is not set this time.
                                    wxPG_LABEL,
                                    wxDateTime::Now()) );
 
     // Image file property. Wild card is auto-generated from available
     // image handlers, so it is not set this time.

-    pg->Append( new wxImageFileProperty(wxT("Label of ImageFileProperty"),
-                                        wxT("NameOfImageFileProp")) );
+    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));
 
                                      wxPG_LABEL,
                                      wxCURSOR_ARROW));
 


@@ -438,30 +445,52 @@ To use them, you have to include <wx/propgrid/advprops.h>.
 
 @section propgrid_processingvalues Processing Property Values
 
 
 @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. Using << operator to get wx(U)LongLong from wxVariant
-is customized to work quite safely with various types of variant data.
-
-You may have noticed that properties store, in wxVariant, values of many
-types which are not natively supported by it. Custom wxVariantDatas
-are therefore implemented and << and >> operators implemented to
-convert data from and to wxVariant.
+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
 
 Note that in some cases property value can be Null variant, which means
 that property value is unspecified. This usually occurs only when


@@ -527,8 +556,17 @@ This example reverse-iterates through all visible items:
 
 @endcode
 
 
 @endcode
 

-<b>wxPython Note:</b> Instead of ++ operator, use Next() method, and instead of
+@beginWxPythonOnly
+PropertyGridInterface has some useful pythonic iterators as attributes.
+@c Properties lets you iterate through all items that are not category
+captions or private children. @c Items lets you iterate through everything
+except private children. Also, there are GetPyIterator() and GetPyVIterator(),
+which return pythonic iterators instead of normal wxPropertyGridIterator.
+
+If you need to use C++ style iterators in wxPython code, note that
+Instead of ++ operator, use Next() method, and instead of

 * operator, use GetProperty() method.
 * operator, use GetProperty() method.

+@endWxPythonOnly

 
 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


@@ -632,12 +670,25 @@ void MyForm::OnPropertyGridChanging( wxPropertyGridEvent& event )
   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 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
 
 @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

-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(),


@@ -661,7 +712,7 @@ 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() )


@@ -670,12 +721,12 @@ message.
                 font << pendingValue;
 
                 // Let's just allow Arial font
                 font << pendingValue;
 
                 // 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);

                 }
             }
         }
                 }
             }
         }


@@ -692,11 +743,58 @@ wxPGProperty::SetCell() for this purpose.
 In addition, it is possible to control these characteristics for
 wxPGChoices list items. See wxPGChoices class reference for more info.
 
 In addition, it is possible to control these characteristics for
 wxPGChoices list items. See wxPGChoices class reference for more info.
 

+@section propgrid_keyhandling Customizing Keyboard Handling
+
+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
 
 @section propgrid_customizing Customizing Properties (without sub-classing)
 
 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.
 
 @subsection propgrid_customimage Setting Value Image
 of sub-classing a property class etc.
 
 @subsection propgrid_customimage Setting Value Image


@@ -722,7 +820,7 @@ colour selection dialog.
 
 @code
 
 
 @code
 

-    wxPGProperty* colProp = new wxColourProperty(wxT("Text Colour"));
+    wxPGProperty* colProp = new wxColourProperty("Text Colour");

     pg->Append(colProp);
     pg->SetPropertyEditor(colProp, wxPGEditor_TextCtrlAndButton);
 
     pg->Append(colProp);
     pg->SetPropertyEditor(colProp, wxPGEditor_TextCtrlAndButton);
 


@@ -824,12 +922,12 @@ unique (base) name.
     For example, if you have a wxFlagsProperty, you can
     set its all items to use check box using the following:
     @code
     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

-    
+

     Following will set all individual bool properties in your control to
     use check box:
     Following will set all individual bool properties in your control to
     use check box:

-    
+

     @code
         pg->SetPropertyAttributeAll(wxPG_BOOL_USE_CHECKBOX, true);
     @endcode
     @code
         pg->SetPropertyAttributeAll(wxPG_BOOL_USE_CHECKBOX, true);
     @endcode


@@ -859,6 +957,11 @@ 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)
 

+  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
 @subsection propgrid_splittersetting Setting Splitter Position When Creating Property Grid
 
 Splitter position cannot exceed grid size, and therefore setting it during


@@ -885,5 +988,111 @@ which choice entry.
 
 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().
+*/