Updated documentation for several wxPG components.

Updated documentation and removed doxygen-style comments from property.h header file.

wxPGPaintData
wxPGProperty
wxPGCell
wxPGAttributeStorage
wxPGChoices
wxPGChoiceEntry
wxPGRootProperty
wxPropertyCategory

interface/wx/propgrid/property.h

@@ -8,6 +8,30 @@
 
 #define wxNullProperty  ((wxPGProperty*)NULL)
 
+/** @class wxPGPaintData
+
+    Contains information related to property's OnCustomPaint.
+*/
+struct wxPGPaintData
+{
+    /** wxPropertyGrid */
+    const wxPropertyGrid*   m_parent;
+
+    /**
+        Normally -1, otherwise index to drop-down list item that has to be
+        drawn.
+     */
+    int                     m_choiceItem;
+
+    /** Set to drawn width in OnCustomPaint (optional). */
+    int                     m_drawnWidth;
+
+    /**
+        In a measure item call, set this to the height of item at m_choiceItem
+        index.
+     */
+    int                     m_drawnHeight;
+};
 
 /**
     @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers
@@ -45,11 +69,6 @@
 */
 #define wxPG_ATTR_HINT                      wxS("Hint")
 
-/**
-    @deprecated Use "Hint" (wxPG_ATTR_HINT) instead.
-*/
-#define wxPG_ATTR_INLINE_HELP               wxS("InlineHelp")
-
 /** Universal, wxArrayString. Set to enable auto-completion in any
     wxTextCtrl-based property editor.
 */
@@ -81,7 +100,8 @@
 */
 #define wxPG_FLOAT_PRECISION                wxS("Precision")
 
-/** The text will be echoed as asterisks (wxTE_PASSWORD will be passed to textctrl etc).
+/** The text will be echoed as asterisks (wxTE_PASSWORD will be passed
+    to textctrl etc.).
 */
 #define wxPG_STRING_PASSWORD                wxS("Password")
 
@@ -126,8 +146,6 @@
 
 /** Specific to wxFileProperty and derivatives, long, default is 0.
     Sets a specific wxFileDialog style for the file dialog, e.g. ::wxFD_SAVE.
-
-    @since 2.9.4
 */
 #define wxPG_FILE_DIALOG_STYLE              wxS("DialogStyle")
 
@@ -167,7 +185,7 @@
 /** SpinCtrl editor, bool. If @true, value can also by changed by moving
     mouse when left mouse button is being pressed.
 */
-#define wxPG_ATTR_SPINCTRL_MOTIONSPIN       wxS("MotionSpin")
+#define wxPG_ATTR_SPINCTRL_MOTION           wxS("MotionSpin")
 
 /** wxMultiChoiceProperty, int. If 0, no user strings allowed. If 1, user strings
     appear before list strings. If 2, user strings appear after list string.
@@ -197,29 +215,35 @@ enum wxPGPropertyFlags
 {
 
 /** Indicates bold font.
+    @hideinitializer
 */
 wxPG_PROP_MODIFIED                  = 0x0001,
 
 /** Disables ('greyed' text and editor does not activate) property.
+    @hideinitializer
 */
 wxPG_PROP_DISABLED                  = 0x0002,
 
 /** Hider button will hide this property.
+    @hideinitializer
 */
 wxPG_PROP_HIDDEN                    = 0x0004,
 
 /** This property has custom paint image just in front of its value.
     If property only draws custom images into a popup list, then this
     flag should not be set.
+    @hideinitializer
 */
 wxPG_PROP_CUSTOMIMAGE               = 0x0008,
 
 /** Do not create text based editor for this property (but button-triggered
     dialog and choice are ok).
+    @hideinitializer
 */
 wxPG_PROP_NOEDITOR                  = 0x0010,
 
 /** Property is collapsed, ie. it's children are hidden.
+    @hideinitializer
 */
 wxPG_PROP_COLLAPSED                 = 0x0020,
 
@@ -230,24 +254,26 @@ wxPG_PROP_COLLAPSED                 = 0x0020,
     If property is not selected, then indicates that the actual property
     value has failed validation (NB: this behaviour is not currently supported,
     but may be used in the future).
+    @hideinitializer
 */
 wxPG_PROP_INVALID_VALUE             = 0x0040,
 
-// 0x0080,
-
 /** Switched via SetWasModified(). Temporary flag - only used when
     setting/changing property value.
+    @hideinitializer
 */
 wxPG_PROP_WAS_MODIFIED              = 0x0200,
 
 /**
     If set, then child properties (if any) are private, and should be
     "invisible" to the application.
+    @hideinitializer
 */
 wxPG_PROP_AGGREGATE                 = 0x0400,
 
 /** If set, then child properties (if any) are copies and should not
     be deleted in dtor.
+    @hideinitializer
 */
 wxPG_PROP_CHILDREN_ARE_COPIES       = 0x0800,
 
@@ -255,6 +281,7 @@ wxPG_PROP_CHILDREN_ARE_COPIES       = 0x0800,
     Classifies this item as a non-category.
 
     Used for faster item type identification.
+    @hideinitializer
 */
 wxPG_PROP_PROPERTY                  = 0x1000,
 
@@ -262,17 +289,20 @@ wxPG_PROP_PROPERTY                  = 0x1000,
     Classifies this item as a category.
 
     Used for faster item type identification.
+    @hideinitializer
 */
 wxPG_PROP_CATEGORY                  = 0x2000,
 
 /** Classifies this item as a property that has children, but is not aggregate
-    (ie children are not private).
+    (i.e. children are not private).
+    @hideinitializer
 */
 wxPG_PROP_MISC_PARENT               = 0x4000,
 
 /** Property is read-only. Editor is still created for wxTextCtrl-based
     property editors. For others, editor is not usually created because
     they do implement wxTE_READONLY style or equivalent.
+    @hideinitializer
 */
 wxPG_PROP_READONLY                  = 0x8000,
 
@@ -283,12 +313,14 @@ wxPG_PROP_READONLY                  = 0x8000,
 /** Property's value is composed from values of child properties.
     @remarks
     This flag cannot be used with property iterators.
+    @hideinitializer
 */
 wxPG_PROP_COMPOSED_VALUE            = 0x00010000,
 
 /** Common value of property is selectable in editor.
     @remarks
     This flag cannot be used with property iterators.
+    @hideinitializer
 */
 wxPG_PROP_USES_COMMON_VALUE         = 0x00020000,
 
@@ -301,21 +333,30 @@ wxPG_PROP_USES_COMMON_VALUE         = 0x00020000,
     This flag cannot be used with property iterators.
 
     @see wxPGProperty::SetAutoUnspecified()
+    @hideinitializer
 */
 wxPG_PROP_AUTO_UNSPECIFIED          = 0x00040000,
 
 /** Indicates the bit usable by derived properties.
+    @hideinitializer
 */
 wxPG_PROP_CLASS_SPECIFIC_1          = 0x00080000,
 
 /** Indicates the bit usable by derived properties.
+    @hideinitializer
 */
 wxPG_PROP_CLASS_SPECIFIC_2          = 0x00100000,
 
 /** Indicates that the property is being deleted and should be ignored.
+    @hideinitializer
 */
 wxPG_PROP_BEING_DELETED             = 0x00200000
 
+/** Indicates the bit useable by derived properties.
+    @hideinitializer
+*/
+wxPG_PROP_CLASS_SPECIFIC_3          = 0x00400000
+
 };
 
 /** Topmost flag.
@@ -331,9 +372,15 @@ wxPG_PROP_BEING_DELETED             = 0x00200000
                          wxPG_PROP_CATEGORY | \
                          wxPG_PROP_MISC_PARENT))
 
+/** Combination of flags that can be stored by GetFlagsAsString().
+*/
+#define wxPG_STRING_STORED_FLAGS \
+    (wxPG_PROP_DISABLED|wxPG_PROP_HIDDEN|wxPG_PROP_NOEDITOR|wxPG_PROP_COLLAPSED)
+
 /** @}
 */
 
+// -----------------------------------------------------------------------
 
 /**
     @class wxPGProperty
@@ -725,7 +772,7 @@ public:
         This virtual function is called after m_value has been set.
 
         @remarks
-        - If m_value was set to Null variant (ie. unspecified value), OnSetValue()
+        - If m_value was set to Null variant (i.e. unspecified value), OnSetValue()
           will not be called.
         - m_value may be of any variant type. Typically properties internally support only
           one variant type, and as such OnSetValue() provides a good opportunity to convert
@@ -833,7 +880,7 @@ public:
 
         @return @true if value was changed.
     */
-    bool SetValueFromString( const wxString& text, int flags = 0 );
+    bool SetValueFromString( const wxString& text, int flags = wxPG_PROGRAMMATIC_VALUE );
 
     /**
         Converts integer to a value, and if successful, calls SetValue() on it.
@@ -859,7 +906,7 @@ public:
         @remarks
         - Default behaviour is to return wxSize(0,0), which means no image.
         - Default image width or height is indicated with dimension -1.
-        - You can also return wxPG_DEFAULT_IMAGE_SIZE which equals wxSize(-1, -1).
+        - You can also return wxPG_DEFAULT_IMAGE_SIZE which equals wxDefaultSize.
     */
     virtual wxSize OnMeasureImage( int item = -1 ) const;
 
@@ -1082,7 +1129,7 @@ public:
         Returns instance of a new wxPGEditorDialogAdapter instance, which is
         used when user presses the (optional) button next to the editor control;
 
-        Default implementation returns @NULL (ie. no action is generated when
+        Default implementation returns @NULL (i.e. no action is generated when
         button is pressed).
     */
     virtual wxPGEditorDialogAdapter* GetEditorDialog() const;
@@ -1111,15 +1158,6 @@ public:
     */
     int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE );
 
-    /**
-        Adds a private child property.
-
-        @deprecated Use AddPrivateChild() instead.
-
-        @see AddPrivateChild()
-    */
-    wxDEPRECATED( void AddChild( wxPGProperty* prop ) );
-
     /**
         Adds a private child property. If you use this instead of
         wxPropertyGridInterface::Insert() or
@@ -1136,7 +1174,7 @@ public:
     void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
 
     /**
-        Use this member function to add independent (ie. regular) children to
+        Use this member function to add independent (i.e. regular) children to
         a property.
 
         @return Appended childProperty.
@@ -1198,11 +1236,25 @@ public:
     */
     void Enable( bool enable = true );
 
+    /**
+        Call to enable or disable usage of common value (integer value that can
+        be selected for properties instead of their normal values) for this
+        property.
+
+        Common values are disabled by the default for all properties.
+    */
+    void EnableCommonValue( bool enable = true );
+
     /**
         Composes text from values of child properties.
     */
     wxString GenerateComposedValue() const;
 
+    /**
+        Returns property's label.
+    */
+    const wxString& GetLabel() const;
+
     /**
         Returns property attribute value, null variant if not found.
     */
@@ -1220,6 +1272,11 @@ public:
     */
     double GetAttributeAsDouble( const wxString& name, double defVal ) const;
 
+    /**
+        Returns comma-delimited string of property attributes.
+    */
+    const wxPGAttributeStorage& GetAttributes() const;
+
     /**
         Returns attributes as list wxVariant.
     */
@@ -1230,7 +1287,9 @@ public:
     */
     const wxPGEditor* GetColumnEditor( int column ) const;
 
-    /** Returns property's base name (ie. parent's name is not added in any case) */
+    /** Returns property's base name (ie. parent's name is not added
+        in any case).
+    */
     const wxString& GetBaseName() const;
 
     /**
@@ -1279,7 +1338,7 @@ public:
     */
     void* GetClientData() const;
 
-    /** Sets managed client object of a property.
+    /** Gets managed client object of a property.
     */
     wxClientData *GetClientObject() const;
 
@@ -1290,6 +1349,18 @@ public:
     */
     wxVariant GetDefaultValue() const;
 
+    /**
+        Returns common value selected for this property. -1 for none.
+    */
+    int GetCommonValue() const;
+
+    unsigned int GetDepth() const;
+
+    /**
+        Return number of displayed common values for this property.
+    */
+    int GetDisplayedCommonValueCount() const;
+
     /** Returns property's displayed text.
     */
     wxString GetDisplayedString() const;
@@ -1302,9 +1373,9 @@ public:
     const wxPGEditor* GetEditorClass() const;
 
     /**
-        Returns property flags.
+        Returns property's hint text (shown in empty value cell).
     */
-    FlagType GetFlags() const;
+    inline wxString GetHintText() const;
 
     /** Returns property grid where property lies. */
     wxPropertyGrid* GetGrid() const;
@@ -1322,14 +1393,19 @@ public:
     */
     const wxString& GetHelpString() const;
 
+    /** Gets flags as a'|' delimited string. Note that flag names are not
+        prepended with 'wxPG_PROP_'.
+
+        @param flagsMask
+        String will only be made to include flags combined by this parameter.
+    */
+    wxString GetFlagsAsString( FlagType flagsMask ) const;
+
     /**
         Returns position in parent's array.
     */
     unsigned int GetIndexInParent() const;
 
-    /** Returns property's label. */
-    const wxString& GetLabel() const;
-
     /**
         Returns last visible child property, recursively.
     */
@@ -1391,14 +1467,6 @@ public:
     */
     virtual wxString GetValueAsString( int argFlags = 0 ) const;
 
-    /** Synonymous to GetValueAsString().
-
-        @deprecated Use GetValueAsString() instead.
-
-        @see GetValueAsString()
-    */
-    wxDEPRECATED( wxString GetValueString( int argFlags = 0 ) const );
-
     /**
         Returns value type used by this property.
     */
@@ -1411,11 +1479,30 @@ public:
     int GetY() const;
 
     /**
-        Returns non-zero if property has given flag set.
+        Converts image width into full image offset, with margins.
+    */
+    int GetImageOffset( int imageWidth ) const;
+
+    /** Returns property at given virtual y coordinate.
+    */
+    wxPGProperty* GetItemAtY( unsigned int y ) const;
+
+    /**
+        Returns true if property has given flag set.
 
         @see propgrid_propflags
     */
-    FlagType HasFlag( wxPGPropertyFlags flag ) const;
+    bool HasFlag(wxPGPropertyFlags flag) const;
+
+    /**
+        Returns true if property has given flag set.
+    */
+    bool HasFlag(FlagType flag) const;
+
+    /**
+        Returns true if property has all given flags set.
+    */
+    bool HasFlagsExact(FlagType flags) const;
 
     /**
         Returns @true if property has even one visible child.
@@ -1440,7 +1527,7 @@ public:
     int Index( const wxPGProperty* p ) const;
 
     /**
-        Use this member function to add independent (ie. regular) children to
+        Use this member function to add independent (i.e. regular) children to
         a property.
 
         @return Inserted childProperty.
@@ -1487,8 +1574,14 @@ public:
     */
     bool IsRoot() const;
 
+    /**
+        Returns true if this is a sub-property.
+    */
+    bool IsSubProperty() const;
+
     /**
         Returns @true if candidateParent is some parent of this property.
+        Use, for example, to detect if item is inside collapsed section.
     */
     bool IsSomeParent( wxPGProperty* candidateParent ) const;
 
@@ -1517,6 +1610,17 @@ public:
     */
     wxPGProperty* Item( unsigned int i ) const;
 
+    /**
+        Returns last sub-property.
+    */
+    wxPGProperty* Last() const;
+
+    /**
+        If property's editor is created this forces its recreation.
+        Useful in SetAttribute etc. Returns true if actually did anything.
+    */
+    bool RecreateEditor();
+
     /**
         If property's editor is active, then update it's value.
     */
@@ -1536,6 +1640,8 @@ public:
     */
     void SetAttribute( const wxString& name, wxVariant value );
 
+    void SetAttributes( const wxPGAttributeStorage& attributes );
+
     /**
         Set if user can change the property's value to unspecified by
         modifying the value of the editor control (usually by clearing
@@ -1583,6 +1689,11 @@ public:
     */
     void SetCell( int column, const wxPGCell& cell );
 
+    /**
+        Sets common value selected for this property. -1 for none.
+    */
+    void SetCommonValue( int commonValue );
+
     /**
         Sets new set of choices for the property.
 
@@ -1598,7 +1709,7 @@ public:
     */
     void SetClientData( void* clientData );
 
-    /** Returns client object of a property.
+    /** Sets client object of a property.
     */
     void SetClientObject(wxClientData* clientObject);
 
@@ -1618,6 +1729,13 @@ public:
     */
     void SetDefaultValue( wxVariant& value );
 
+    void SetExpanded( bool expanded );
+
+    /** Sets flags from a '|' delimited string. Note that flag names are not
+        prepended with 'wxPG_PROP_'.
+    */
+    void SetFlagsFromString( const wxString& str );
+
     /**
         Sets or clears given property flag, recursively. This function is
         primarily intended for internal use.
@@ -1682,6 +1800,16 @@ public:
     void SetTextColour( const wxColour& colour,
                         int flags = wxPG_RECURSE );
 
+    /**
+        Sets property's default text and background colours.
+
+        @param flags
+            Default is wxPG_RECURSE which causes colours to be set recursively.
+            Omit this flag to only set colours for the property in question
+            and not any of its children.
+    */
+    void SetDefaultColours(int flags = wxPG_RECURSE);
+
     /** Sets wxValidator for a property */
     void SetValidator( const wxValidator& validator );
 
@@ -1724,19 +1852,22 @@ public:
     void SetValueInEvent( wxVariant value ) const;
 
     /**
-        Sets property's value to unspecified (ie. Null variant).
+        Sets property's value to unspecified (i.e. Null variant).
     */
     void SetValueToUnspecified();
 
     /**
         Call with @false in OnSetValue() to cancel value changes after all
-        (ie. cancel @true returned by StringToValue() or IntToValue()).
+        (i.e. cancel @true returned by StringToValue() or IntToValue()).
     */
     void SetWasModified( bool set = true );
 
     /**
         Updates composed values of parent non-category properties, recursively.
         Returns topmost property updated.
+
+        @remarks
+        Must not call SetValue() (as can be called in it).
     */
     wxPGProperty* UpdateParentValues();
 
@@ -1745,11 +1876,91 @@ public:
     */
     bool UsesAutoUnspecified() const;
 
+    /** This member is public so scripting language bindings
+        wrapper code can access it freely.
+    */
+    void*                       m_clientData;
+
 protected:
+    /**
+        Sets property cell in fashion that reduces number of exclusive
+        copies of cell data. Used when setting, for instance, same
+        background colour for a number of properties.
+
+        @param firstCol
+            First column to affect.
+
+        @param lastCol
+            Last column to affect.
+
+        @param preparedCell
+            Pre-prepared cell that is used for those which cell data
+            before this matched unmodCellData.
+
+        @param srcData
+            If unmodCellData did not match, valid cell data from this
+            is merged into cell (usually generating new exclusive copy
+            of cell's data).
+
+        @param unmodCellData
+            If cell's cell data matches this, its cell is now set to
+            preparedCell.
+
+        @param ignoreWithFlags
+            Properties with any one of these flags are skipped.
+
+        @param recursively
+            If @true, apply this operation recursively in child properties.
+    */
+    void AdaptiveSetCell( unsigned int firstCol,
+                          unsigned int lastCol,
+                          const wxPGCell& preparedCell,
+                          const wxPGCell& srcData,
+                          wxPGCellData* unmodCellData,
+                          FlagType ignoreWithFlags,
+                          bool recursively );
+
+    /**
+        Clear cells associated with property.
+
+        @param recursively
+            If @true, apply this operation recursively in child properties.
+    */
+    void ClearCells(FlagType ignoreWithFlags, bool recursively);
+
+    /**
+        Makes sure m_cells has size of column+1 (or more).
+    */
+    void EnsureCells( unsigned int column );
+
+    /** Returns (direct) child property with given name (or @NULL if not found),
+        with hint index.
+
+        @param hintIndex
+        Start looking for the child at this index.
+
+        @remarks
+        Does not support scope (i.e. Parent.Child notation).
+    */
+    wxPGProperty* GetPropertyByNameWH( const wxString& name,
+                                       unsigned int hintIndex ) const;
+
+    /** This is used by Insert etc. */
+    void DoAddChild( wxPGProperty* prop,
+                     int index = -1,
+                     bool correct_mode = true );
+
     /** Deletes all child properties. */
     void Empty();
+
+    /**
+        Returns true if child property is selected.
+    */
+    bool IsChildSelected( bool recursive = false ) const;
 };
 
+// -----------------------------------------------------------------------
+
 /** @class wxPGCellRenderer
 
     Base class for wxPropertyGrid cell renderers.
@@ -1757,7 +1968,7 @@ protected:
     @library{wxpropgrid}
     @category{propgrid}
 */
-class WXDLLIMPEXP_PROPGRID wxPGCellRenderer : public wxObjectRefData
+class wxPGCellRenderer : public wxObjectRefData
 {
 public:
     wxPGCellRenderer();
@@ -1766,16 +1977,17 @@ public:
     /**
         @anchor pgcellrenderer_render_flags
 
-        Flags for wxPGCellRenderer::Render(), wxPGCellRenderer::PreDrawCell()
+        Flags for Render(), PreDrawCell() and PostDrawCell().
-        and wxPGCellRenderer::PostDrawCell().
     */
     enum
     {
         /** We are painting selected item.
+            @hideinitializer
         */
         Selected        = 0x00010000,
 
         /** We are painting item in choice popup.
+            @hideinitializer
         */
         ChoicePopup     = 0x00020000,
 
@@ -1783,10 +1995,12 @@ public:
             We are rendering wxOwnerDrawnComboBox control
             or other owner drawn control, but that is only
             officially supported one ATM).
+            @hideinitializer
         */
         Control         = 0x00040000,
 
         /** We are painting a disable property.
+            @hideinitializer
         */
         Disabled        = 0x00080000,
 
@@ -1794,9 +2008,16 @@ public:
             We are painting selected, disabled, or similar
             item that dictates fore- and background colours,
             overriding any cell values.
+            @hideinitializer
         */
         DontUseCellFgCol    = 0x00100000,
+        /**
+            @hideinitializer
+        */
         DontUseCellBgCol    = 0x00200000,
+        /**
+            @hideinitializer
+        */
         DontUseCellColours  = DontUseCellFgCol |
                               DontUseCellBgCol
     };
@@ -1819,7 +2040,7 @@ public:
     /** Returns size of the image in front of the editable area.
 
         @remarks
-        If property is NULL, then this call is for a custom value. In that case
+        If property is @NULL, then this call is for a custom value. In that case
         the item is index to wxPropertyGrid's custom values.
     */
     virtual wxSize GetImageSize( const wxPGProperty* property,
@@ -1840,7 +2061,7 @@ public:
 
     /**
         Utility to draw editor's value, or vertically aligned text if editor is
-        NULL.
+        @NULL.
     */
     void DrawEditorValue( wxDC& dc, const wxRect& rect,
                           int xOffset, const wxString& text,
@@ -1875,6 +2096,7 @@ public:
                        int flags ) const;
 };
 
+// -----------------------------------------------------------------------
 
 /**
     @class wxPGDefaultRenderer
@@ -1885,7 +2107,7 @@ public:
     @library{wxpropgrid}
     @category{propgrid}
 */
-class WXDLLIMPEXP_PROPGRID wxPGDefaultRenderer : public wxPGCellRenderer
+class wxPGDefaultRenderer : public wxPGCellRenderer
 {
 public:
     /**
@@ -1908,6 +2130,8 @@ public:
                                  int item ) const;
 };
 
+// -----------------------------------------------------------------------
+
 /**
     @class wxPGCellData
 
@@ -1961,6 +2185,7 @@ public:
 
     virtual ~wxPGCell();
 
+    wxPGCellData* GetData();
     const wxPGCellData* GetData() const;
 
     /**
@@ -1968,6 +2193,11 @@ public:
     */
     bool HasText() const;
 
+    /**
+        Sets empty but valid data to this cell object.
+    */
+    void SetEmptyData();
+
     /**
         Merges valid data from srcCell into this.
     */
@@ -2007,6 +2237,29 @@ public:
     wxPGCell& operator=( const wxPGCell& other );
 };
 
+// -----------------------------------------------------------------------
+
+/** @class wxPGAttributeStorage
+
+    wxPGAttributeStorage is somewhat optimized storage for
+    key=variant pairs (i.e. a map).
+*/
+class wxPGAttributeStorage
+{
+public:
+    wxPGAttributeStorage();
+    ~wxPGAttributeStorage();
+
+    void Set( const wxString& name, const wxVariant& value );
+    unsigned int GetCount() const;
+    wxVariant FindValue( const wxString& name ) const;
+
+    typedef wxPGHashMapS2P::const_iterator const_iterator;
+    const_iterator StartIteration() const;
+    bool GetNext( const_iterator& it, wxVariant& variant ) const;
+};
+
+// -----------------------------------------------------------------------
 
 /**
     @class wxPGChoices
@@ -2041,38 +2294,80 @@ public:
     */
     wxPGChoices( const wxPGChoices& a );
 
-    /** Constructor. */
+    /**
+        Constructor.
+
+        @param labels
+            Labels for choices.
+
+        @param values
+            Values for choices. If @NULL, indexes are used.
+    */
     wxPGChoices( const wxChar** labels, const long* values = NULL );
 
-    /** Constructor. */
+    /**
+        Constructor.
+
+        @param labels
+            Labels for choices.
+
+        @param values
+            Values for choices. If empty, indexes are used.
+    */
     wxPGChoices( const wxArrayString& labels, const wxArrayInt& values = wxArrayInt() );
 
-    /** Constructor. */
+    /**
+        Simple interface constructor.
+    */
     wxPGChoices( wxPGChoicesData* data );
 
-    /** Destructor. */
+    /**
+        Destructor.
+    */
     ~wxPGChoices();
 
     /**
         Adds to current. If did not have own copies, creates them now. If was empty,
         identical to set except that creates copies.
+
+        @param labels
+            Labels for added choices.
+
+        @param values
+            Values for added choices. If empty, relevant entry indexes are used.
     */
     void Add( const wxChar** labels, const ValArrItem* values = NULL );
 
-    /** Version that works with wxArrayString and wxArrayInt. */
+    /**
+        Adds to current. Version that works with wxArrayString and wxArrayInt.
+    */
     void Add( const wxArrayString& arr, const wxArrayInt& arrint );
 
-    /** Adds single item. */
+    /**
+        Adds a single choice item.
+
+        @param label
+            Label for added choice.
+
+        @param value
+            Value for added choice. If unspecified, index is used.
+    */
     wxPGChoiceEntry& Add( const wxString& label, int value = wxPG_INVALID_VALUE );
 
-    /** Adds a single item, with bitmap. */
+    /**
+        Adds a single item, with bitmap.
+    */
     wxPGChoiceEntry& Add( const wxString& label, const wxBitmap& bitmap,
                           int value = wxPG_INVALID_VALUE );
 
-    /** Adds a single item with full entry information. */
+    /**
+        Adds a single item with full entry information.
+    */
     wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry );
 
-    /** Adds single item, sorted. */
+    /**
+        Adds a single item, sorted.
+    */
     wxPGChoiceEntry& AddAsSorted( const wxString& label, int value = wxPG_INVALID_VALUE );
 
     /**
@@ -2096,6 +2391,13 @@ public:
     */
     wxPGChoices Copy() const;
 
+    void EnsureData();
+
+    /**
+        Gets a unsigned number identifying this list.
+    */
+    wxPGChoicesId GetId() const;
+
     /**
         Returns label of item.
     */
@@ -2107,7 +2409,7 @@ public:
     unsigned int GetCount() const;
 
     /**
-        Returns value of item;
+        Returns value of item.
     */
     int GetValue( unsigned int ind ) const;
 
@@ -2135,7 +2437,7 @@ public:
     int Index( int val ) const;
 
     /**
-        Inserts single item.
+        Inserts a single item.
     */
     wxPGChoiceEntry& Insert( const wxString& label, int index, int value = wxPG_INVALID_VALUE );
 
@@ -2180,6 +2482,21 @@ public:
     */
     void AllocExclusive();
 
+    /**
+        Returns data, increases refcount.
+    */
+    wxPGChoicesData* GetData();
+
+    /**
+        Returns plain data ptr - no refcounting stuff is done.
+    */
+    wxPGChoicesData* GetDataPtr() const;
+
+    /**
+        Changes ownership of data to you.
+    */
+    wxPGChoicesData* ExtractData();
+
     /**
         Returns array of choice labels.
     */
@@ -2189,6 +2506,74 @@ public:
 
     wxPGChoiceEntry& operator[](unsigned int i);
     const wxPGChoiceEntry& operator[](unsigned int i) const;
+
+protected:
+    wxPGChoicesData*    m_data;
+
+    void Init();
+    void Free();
 };
 
 // -----------------------------------------------------------------------
+
+/** @class wxPGChoiceEntry
+
+    Data of a single wxPGChoices choice.
+*/
+class wxPGChoiceEntry : public wxPGCell
+{
+public:
+    wxPGChoiceEntry();
+    wxPGChoiceEntry(const wxPGChoiceEntry& other);
+    wxPGChoiceEntry( const wxString& label,
+                     int value = wxPG_INVALID_VALUE );
+
+    virtual ~wxPGChoiceEntry();
+
+    void SetValue( int value );
+    int GetValue() const;
+
+    wxPGChoiceEntry& operator=( const wxPGChoiceEntry& other );
+};
+
+// -----------------------------------------------------------------------
+
+/** @class wxPGRootProperty
+
+    Root parent property.
+*/
+class wxPGRootProperty : public wxPGProperty
+{
+public:
+
+    /** Constructor. */
+    wxPGRootProperty( const wxString& name = wxS("<Root>") );
+    virtual ~wxPGRootProperty();
+
+    virtual bool StringToValue( wxVariant&, const wxString&, int ) const;
+};
+
+// -----------------------------------------------------------------------
+
+/** @class wxPropertyCategory
+
+    Category (caption) property.
+*/
+class wxPropertyCategory : public wxPGProperty
+{
+    friend class wxPropertyGrid;
+    friend class wxPropertyGridPageState;
+public:
+
+    /** Default constructor is only used in special cases. */
+    wxPropertyCategory();
+
+    wxPropertyCategory( const wxString& label,
+                        const wxString& name = wxPG_LABEL );
+    ~wxPropertyCategory();
+
+    int GetTextExtent( const wxWindow* wnd, const wxFont& font ) const;
+
+    virtual wxString ValueToString( wxVariant& value, int argFlags ) const;
+    virtual wxString GetValueAsString( int argFlags = 0 ) const;
+};