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

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

interface/wx/propgrid/manager.h

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

interface/wx/propgrid/propgrid.h

@@ -251,10 +251,11 @@ enum wxPG_KEYBOARD_ACTIONS
 
 /** @class wxPropertyGrid
 
-    wxPropertyGrid is a specialized grid for editing properties
-    such as strings, numbers, flagsets, fonts, and colours. wxPropertySheet
-    used to do the very same thing, but it hasn't been updated for a while
-    and it is currently deprecated.
+      wxPropertyGrid is a specialized grid for editing properties - in other
+    words name = value pairs. List of ready-to-use property classes include
+    strings, numbers, flagsets, 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.
 
     Please note that most member functions are inherited and as such not documented on
     this page. This means you will probably also want to read wxPropertyGridInterface

interface/wx/propgrid/propgridiface.h

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