]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/propgrid/property.h
abandon attempts to make wxAnyStrPtr behave as bool: user-defined logical operators...
[wxWidgets.git] / interface / wx / propgrid / property.h
index 057154a0a62e759b37260cd701bb7663b7065c00..2c4b99c16f320ba5063f501c3727bd15f525d59e 100644 (file)
 #define wxNullProperty  ((wxPGProperty*)NULL)
 
 
-/** @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers
+/**
+    @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers
 
-    wxPGProperty::SetAttribute() and
-    wxPropertyGridInterface::SetPropertyAttribute()
-    accept one of these as attribute name argument .
+    wxPGProperty::SetAttribute() and wxPropertyGridInterface::SetPropertyAttribute()
+    accept one of these as attribute name argument.
 
-    You can use strings instead of constants. However, some of these
-    constants are redefined to use cached strings which may reduce
-    your binary size by some amount.
+    You can use strings instead of constants.
+    However, some of these constants are redefined to use cached strings which
+    may reduce your binary size by some amount.
 
     @{
 */
 */
 #define wxPG_ATTR_INLINE_HELP               wxS("InlineHelp")
 
+/** Universal, wxArrayString. Set to enable auto-completion in any
+    wxTextCtrl-based property editor.
+*/
+#define wxPG_ATTR_AUTOCOMPLETE              wxS("AutoComplete")
+
 /** wxBoolProperty specific, int, default 0. When 1 sets bool property to
     use checkbox instead of choice.
 */
 #define wxPG_DATE_FORMAT                    wxS("DateFormat")
 
 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
-    is wxDP_DEFAULT | wxDP_SHOWCENTURY.
+    is wxDP_DEFAULT | wxDP_SHOWCENTURY. Using wxDP_ALLOWNONE will enable
+    better unspecified value support in the editor.
 */
 #define wxPG_DATE_PICKER_STYLE              wxS("PickerStyle")
 
 */
 #define wxPG_ATTR_SPINCTRL_STEP             wxS("Step")
 
-/** SpinCtrl editor, bool. If true, value wraps at Min/Max.
+/** SpinCtrl editor, bool. If @true, value wraps at Min/Max.
 */
 #define wxPG_ATTR_SPINCTRL_WRAP             wxS("Wrap")
 
+/** 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")
+
 /** wxMultiChoiceProperty, int. If 0, no user strings allowed. If 1, user strings
     appear before list strings. If 2, user strings appear after list string.
 */
 /** @}
 */
 
-// -----------------------------------------------------------------------
 
-/** @class wxPGProperty
+
+/**
+    @class wxPGProperty
 
     wxPGProperty is base class for all wxPropertyGrid properties. In
     sections below we cover few related topics.
 
     Simple string property. wxPG_STRING_PASSWORD attribute may be used
     to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl.
+    wxPG_ATTR_AUTOCOMPLETE attribute may be used to enable auto-completion
+    (use a wxArrayString value), and is also supported by any property that
+    happens to use a wxTextCtrl-based editor.
 
     @remarks wxStringProperty has a special trait: if it has value of
             "<composed>", and also has child properties, then its displayed
     Like wxLongStringProperty, but the button triggers file selector instead.
     Default wildcard is "All files..." but this can be changed by setting
     wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details).
-    Attribute wxPG_FILE_SHOW_FULL_PATH can be set to false inorder to show
+    Attribute wxPG_FILE_SHOW_FULL_PATH can be set to @false inorder to show
     only the filename, not the entire path.
 
     @subsection wxEnumProperty
     string wxDateTime::Format uses (altough default is recommended as it is
     locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window
     style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY).
+    Using wxDP_ALLOWNONE will enable better unspecified value support.
 
     @subsection wxEditEnumProperty
 
             wxColour    m_colour;
         };
     @endcode
-    
+
     in wxSystemColourProperty, and its derived class wxColourProperty, there
     are various sub-classing features. To set basic list list of colour
     names, call wxPGProperty::SetChoices().
                 return wxPGEditor_TextCtrl;
             }
 
-            virtual wxString GetValueAsString( int argFlags ) const
+            virtual wxString ValueToString( wxVariant& value,
+                                            int argFlags ) const
             {
-                // TODO: Return property value in string format
+                // TODO: Convert given property value to a string
             }
 
             virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags )
@@ -487,8 +504,11 @@ public:
             variant << value;
             SetValue(variant);
 
-            // If has private child properties then create them here. For example:
-            //     AddChild( new wxStringProperty( "Subprop 1", wxPG_LABEL, value.GetSubProp1() ) );
+            // If has private child properties then create them here.
+            // For example:
+            //     AddPrivateChild( new wxStringProperty("Subprop 1",
+            //                                           wxPG_LABEL,
+            //                                           value.GetSubProp1()));
         }
 
         @endcode
@@ -516,15 +536,15 @@ public:
     /**
         Override this to return something else than m_value as the value.
     */
-    virtual wxVariant DoGetValue() const { return m_value; }
+    virtual wxVariant DoGetValue() const;
 
     /**
         Implement this function in derived class to check the value.
-        Return true if it is ok. Returning false prevents property change events
+        Return @true if it is ok. Returning @false prevents property change events
         from occurring.
 
         @remarks
-        - Default implementation always returns true.
+        - Default implementation always returns @true.
     */
     virtual bool ValidateValue( wxVariant& value, wxPGValidationInfo& validationInfo ) const;
 
@@ -542,7 +562,7 @@ public:
             If wxPG_FULL_VALUE is set, returns complete, storable value instead
             of displayable one (they may be different).
             If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
-            composite property string value (as generated by GetValueAsString()
+            composite property string value (as generated by ValueToString()
             called with this same flag).
 
         @return Returns @true if resulting wxVariant value was different.
@@ -563,10 +583,8 @@ public:
         @param variant
             On function entry this is the old value (should not be wxNullVariant
             in normal cases). Translated value must be assigned back to it.
-
         @param number
             Integer to be translated into variant.
-
         @param argFlags
             If wxPG_FULL_VALUE is set, returns complete, storable value instead
             of displayable one.
@@ -580,46 +598,52 @@ public:
         - If property uses choice control, and displays a dialog on some choice
           items, then it is preferred to display that dialog in IntToValue
           instead of OnEvent.
-        - You might want to take into account that m_value is Null variant if
+        - You might want to take into account that m_value is Mull variant if
           property value is unspecified (which is usually only case if you
           explicitly enabled that sort behavior).
     */
-    virtual bool IntToValue( wxVariant& value, int number, int argFlags = 0 ) const;
+    virtual bool IntToValue( wxVariant& variant, int number, int argFlags = 0 ) const;
 
     /**
-        Returns text representation of property's value.
+        Converts property value into a text representation.
 
+        @param value
+            Value to be converted.
         @param argFlags
-        If wxPG_FULL_VALUE is set, returns complete, storable string value instead of displayable.
-        If wxPG_EDITABLE_VALUE is set, returns string value that must be editable in textctrl.
-        If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to display
-        as a part of composite property string value.
+            If 0 (default value), then displayed string is returned.
+            If wxPG_FULL_VALUE is set, returns complete, storable string value
+            instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
+            string value that must be editable in textctrl.
+            If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
+            display as a part of string property's composite text representation.
 
-        @remarks
-        Default implementation returns string composed from text representations of
-        child properties.
+        @remarks Default implementation calls GenerateComposedValue().
     */
-    virtual wxString GetValueAsString( int argFlags = 0 ) const;
+    virtual wxString ValueToString( wxVariant& value, int argFlags = 0 ) const;
 
     /**
         Converts string to a value, and if successful, calls SetValue() on it.
         Default behavior is to do nothing.
+
         @param text
-        String to get the value from.
-        @retval
-        true if value was changed.
+            String to get the value from.
+        @param flags
+            @todo docme
+
+        @return @true if value was changed.
     */
     bool SetValueFromString( const wxString& text, int flags = 0 );
 
     /**
         Converts integer to a value, and if succesful, calls SetValue() on it.
         Default behavior is to do nothing.
+
         @param value
-        Int to get the value from.
+            Int to get the value from.
         @param flags
-        If has wxPG_FULL_VALUE, then the value given is a actual value and not an index.
-        @retval
-        True if value was changed.
+            If has wxPG_FULL_VALUE, then the value given is a actual value and not an index.
+
+        @return @true if value was changed.
     */
     bool SetValueFromInt( long value, int flags = 0 );
 
@@ -627,8 +651,10 @@ public:
         Returns size of the custom painted image in front of property. This method
         must be overridden to return non-default value if OnCustomPaint is to be
         called.
+
         @param item
-        Normally -1, but can be an index to the property's list of items.
+            Normally -1, but can be an index to the property's list of items.
+
         @remarks
         - Default behavior is to return wxSize(0,0), which means no image.
         - Default image width or height is indicated with dimension -1.
@@ -644,13 +670,14 @@ public:
         wxSystemColourProperty custom handles wxEVT_COMMAND_CHOICE_SELECTED
         to display colour picker dialog when 'custom' selection is made).
 
-        If the event causes value to be changed, SetValueInEvent()
-        should be called to set the new value.
+        If the event causes value to be changed, SetValueInEvent() should be called
+        to set the new value.
+
+        The parameter @a event is the associated wxEvent.
 
-        @param event
-        Associated wxEvent.
         @retval
-        Should return true if any changes in value should be reported.
+            Should return @true if any changes in value should be reported.
+
         @remarks
         - If property uses choice control, and displays a dialog on some choice items,
           then it is preferred to display that dialog in IntToValue instead of OnEvent.
@@ -687,11 +714,11 @@ public:
         @endcode
 
         @param thisValue
-        Value of this property, that should be altered.
+            Value of this property, that should be altered.
         @param childIndex
-        Index of child changed (you can use Item(childIndex) to get).
+            Index of child changed (you can use Item(childIndex) to get).
         @param childValue
-        Value of the child property.
+            Value of the child property.
     */
     virtual void ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const;
 
@@ -702,7 +729,7 @@ public:
 
     /**
         Returns pointer to the wxValidator that should be used
-        with the editor of this property (NULL for no validator).
+        with the editor of this property (@NULL for no validator).
         Setting validator explicitly via SetPropertyValidator
         will override this.
 
@@ -785,7 +812,7 @@ public:
             - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper colour) pen for
               drawing framing rectangle. It can be changed as well.
 
-        @see GetValueAsString()
+        @see ValueToString()
     */
     virtual void OnCustomPaint( wxDC& dc, const wxRect& rect, wxPGPaintData& paintdata );
 
@@ -813,10 +840,10 @@ public:
     /**
         Special handling for attributes of this property.
 
-        If returns false, then the attribute will be automatically stored in
+        If returns @false, then the attribute will be automatically stored in
         m_attributes.
 
-        Default implementation simply returns false.
+        Default implementation simply returns @false.
     */
     virtual bool DoSetAttribute( const wxString& name, wxVariant& value );
 
@@ -825,7 +852,7 @@ public:
 
         Override if custom handling of attributes is needed.
 
-        Default implementation simply return NULL variant.
+        Default implementation simply return @NULL variant.
     */
     virtual wxVariant DoGetAttribute( const wxString& name ) const;
 
@@ -833,24 +860,19 @@ 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 (ie. no action is generated when
         button is pressed).
     */
     virtual wxPGEditorDialogAdapter* GetEditorDialog() const;
 
     /**
-        Returns wxPGCell of given column, NULL if none. If valid
-        object is returned, caller will gain its ownership.
-    */
-    wxPGCell* AcquireCell( unsigned int column )
-    {
-        if ( column >= m_cells.size() )
-            return NULL;
+        Called whenever validation has failed with given pending value.
 
-        wxPGCell* cell = (wxPGCell*) m_cells[column];
-        m_cells[column] = NULL;
-        return cell;
-    }
+        @remarks If you implement this in your custom property class, please
+                 remember to call the baser implementation as well, since they
+                 may use it to revert property into pre-change state.
+    */
+    virtual void OnValidationFailure( wxVariant& pendingValue );
 
     /**
         Append a new choice to property's list of choices.
@@ -868,23 +890,22 @@ public:
     int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE );
 
     /**
-        Adds a child property. If you use this instead of
-        wxPropertyGridInterface::Insert() or
-        wxPropertyGridInterface::AppendIn(), then you must set up
-        property's parental type before making the call. To do this,
-        call property's SetParentalType() function with either
-        wxPG_PROP_MISC_PARENT (normal, public children) or with
-        wxPG_PROP_AGGREGATE (private children for subclassed property).
-        For instance:
+        Adds a private child property.
 
-        @code
-            wxPGProperty* prop = new wxStringProperty(wxS("Property"));
-            prop->SetParentalType(wxPG_PROP_MISC_PARENT);
-            wxPGProperty* prop2 = new wxStringProperty(wxS("Property2"));
-            prop->AddChild(prop2);
-        @endcode
+        @deprecated Use AddPrivateChild() instead.
+
+        @see AddPrivateChild()
     */
-    void AddChild( wxPGProperty* property );
+    wxDEPRECATED( void AddChild( wxPGProperty* prop ) );
+
+    /**
+        Adds a private child property. If you use this instead of
+        wxPropertyGridInterface::Insert() or
+        wxPropertyGridInterface::AppendIn(), then property's parental
+        type will automatically be set up to wxPG_PROP_AGGREGATE. In other
+        words, all properties of this property will become private.
+    */
+    void AddPrivateChild( wxPGProperty* prop );
 
     /**
         Adapts list variant into proper value using consecutive
@@ -892,6 +913,19 @@ public:
     */
     void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
 
+    /**
+        Use this member function to add independent (ie. regular) children to
+        a property.
+
+        @return Appended childProperty.
+
+        @remarks wxPropertyGrid is not automatically refreshed by this
+                function.
+
+        @see InsertChild(), AddPrivateChild()
+    */
+    wxPGProperty* AppendChild( wxPGProperty* childProperty );
+
     /**
         Determines, recursively, if all children are not unspecified.
 
@@ -902,16 +936,15 @@ public:
     bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const;
 
     /**
-        Returns true if children of this property are component values (for instance,
+        Returns @true if children of this property are component values (for instance,
         points size, face name, and is_underlined are component values of a font).
     */
-    bool AreChildrenComponents() const
-    {
-        if ( m_flags & (wxPG_PROP_COMPOSED_VALUE|wxPG_PROP_AGGREGATE) )
-            return true;
+    bool AreChildrenComponents() const;
 
-        return false;
-    }
+    /**
+        Deletes children of the property.
+    */
+    void DeleteChildren();
 
     /**
         Removes entry from property's wxPGChoices and editor control (if it is active).
@@ -923,8 +956,10 @@ public:
     /** Deletes all child properties. */
     void Empty();
 
-    /** Composes text from values of child properties. */
-    void GenerateComposedValue( wxString& text, int argFlags = 0 ) const;
+    /**
+        Composes text from values of child properties.
+    */
+    wxString GenerateComposedValue() const;
 
     /**
         Returns property attribute value, null variant if not found.
@@ -949,30 +984,17 @@ public:
     wxVariant GetAttributesAsList() const;
 
     /**
-        Returns editor used for given column. NULL for no editor.
+        Returns editor used for given column. @NULL for no editor.
     */
-    const wxPGEditor* GetColumnEditor( int column ) const
-    {
-        if ( column == 1 )
-            return GetEditorClass();
-
-        return NULL;
-    }
+    const wxPGEditor* GetColumnEditor( int column ) const;
 
     /** Returns property's base name (ie. parent's name is not added in any case) */
-    const wxString& GetBaseName() const { return m_name; }
+    const wxString& GetBaseName() const;
 
     /**
-        Returns wxPGCell of given column, NULL if none. wxPGProperty
-        will retain ownership of the cell object.
+        Returns wxPGCell of given column.
     */
-    wxPGCell* GetCell( unsigned int column ) const
-    {
-        if ( column >= m_cells.size() )
-            return NULL;
-
-        return (wxPGCell*) m_cells[column];
-    }
+    const wxPGCell& GetCell( unsigned int column ) const;
 
     /**
         Returns number of child properties.
@@ -1014,10 +1036,7 @@ public:
 
     /** Returns property's displayed text.
     */
-    wxString GetDisplayedString() const
-    {
-        return GetValueString(0);
-    }
+    wxString GetDisplayedString() const;
 
     /**
         Returns wxPGEditor that will be used and created when
@@ -1048,7 +1067,7 @@ public:
     unsigned int GetIndexInParent() const;
 
     /** Returns property's label. */
-    const wxString& GetLabel() const { return m_label; }
+    const wxString& GetLabel() const;
 
     /**
         Returns last visible child property, recursively.
@@ -1066,19 +1085,16 @@ public:
 
     /** Returns maximum allowed length of property's text value.
     */
-    int GetMaxLength() const
-    {
-        return (int) m_maxLen;
-    }
+    int GetMaxLength() const;
 
     /** Returns property's name with all (non-category, non-root) parents. */
     wxString GetName() const;
 
     /** Return parent of property */
-    wxPGProperty* GetParent() const { return m_parent; }
+    wxPGProperty* GetParent() const;
 
     /**
-        Returns (direct) child property with given name (or NULL if not found).
+        Returns (direct) child property with given name (or @NULL if not found).
     */
     wxPGProperty* GetPropertyByName( const wxString& name ) const;
 
@@ -1088,33 +1104,44 @@ public:
     /**
         Returns property's value.
     */
-    wxVariant GetValue() const
-    {
-        return DoGetValue();
-    }
+    wxVariant GetValue() const;
 
     /**
-        Returns bitmap that appears next to value text. Only returns non-NULL
+        Returns bitmap that appears next to value text. Only returns non-@NULL
         bitmap if one was set with SetValueImage().
     */
     wxBitmap* GetValueImage() const;
 
-    /**
-        To acquire property's value as string, you should use this
-        function (instead of GetValueAsString()), as it may produce
-        more accurate value in future versions.
+    /** Returns text representation of property's value.
+
+        @param argFlags
+            If 0 (default value), then displayed string is returned.
+            If wxPG_FULL_VALUE is set, returns complete, storable string value
+            instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
+            string value that must be editable in textctrl. If
+            wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
+            display as a part of string property's composite text
+            representation.
+
+        @remarks In older versions, this function used to be overridden to convert
+                 property's value into a string representation. This function is
+                 now handled by ValueToString(), and overriding this function now
+                 will result in run-time assertion failure.
+    */
+    virtual wxString GetValueAsString( int argFlags = 0 ) const;
+
+    /** Synonymous to GetValueAsString().
+
+        @deprecated Use GetValueAsString() instead.
 
         @see GetValueAsString()
     */
-    wxString GetValueString( int argFlags = 0 ) const;
+    wxDEPRECATED( wxString GetValueString( int argFlags = 0 ) const );
 
     /**
         Returns value type used by this property.
     */
-    wxString GetValueType() const
-    {
-        return m_value.GetType();
-    }
+    wxString GetValueType() const;
 
     /**
         Returns coordinate to the top y of the property. Note that the
@@ -1123,7 +1150,7 @@ public:
     int GetY() const;
 
     /**
-        Returns true if property has even one visible child.
+        Returns @true if property has even one visible child.
     */
     bool HasVisibleChildren() const;
 
@@ -1144,6 +1171,19 @@ public:
     */
     int Index( const wxPGProperty* p ) const;
 
+    /**
+        Use this member function to add independent (ie. regular) children to
+        a property.
+
+        @return Inserted childProperty.
+
+        @remarks wxPropertyGrid is not automatically refreshed by this
+                function.
+
+        @see AppendChild(), AddPrivateChild()
+    */
+    wxPGProperty* InsertChild( int index, wxPGProperty* childProperty );
+
     /**
         Inserts a new choice to property's list of choices.
 
@@ -1177,7 +1217,7 @@ public:
     /**
         Returns @true if this property is actually a wxRootProperty.
     */
-    bool IsRoot() const { return (m_parent == NULL); }
+    bool IsRoot() const;
 
     /**
         Returns @true if candidateParent is some parent of this property.
@@ -1228,6 +1268,19 @@ public:
     */
     void SetAttribute( const wxString& name, wxVariant value );
 
+    /**
+        Sets property's background colour.
+
+        @param colour
+            Background colour to use.
+
+        @param recursively
+            If @true, children are affected recursively, and any categories
+            are not.
+    */
+    void SetBackgroundColour( const wxColour& colour,
+                              bool recursively = false );
+
     /**
         Sets editor for a property.
 
@@ -1246,10 +1299,8 @@ public:
 
     /**
         Sets cell information for given column.
-
-        Note that the property takes ownership of given wxPGCell instance.
     */
-    void SetCell( int column, wxPGCell* cellObj );
+    void SetCell( int column, const wxPGCell& cell );
 
     /**
         Sets new set of choices for property.
@@ -1258,12 +1309,6 @@ public:
     */
     bool SetChoices( wxPGChoices& choices );
 
-    /**
-        If property has choices and they are not yet exclusive, new such copy
-        of them will be created.
-    */
-    void SetChoicesExclusive();
-
     /**
         Sets client data (void*) of a property.
 
@@ -1295,7 +1340,7 @@ public:
         @remarks Properties under same parent may have same labels. However,
                 property names must still remain unique.
     */
-    void SetLabel( const wxString& label ) { m_label = label; }
+    void SetLabel( const wxString& label );
 
     /**
         Set max length of text in text editor.
@@ -1321,14 +1366,23 @@ public:
             wxPG_PROP_AGGREGATE (for derived property classes with private
             children).
 
-        @remarks You only need to call this if you use AddChild() to add
-                 child properties. Adding properties with
-                 wxPropertyGridInterface::Insert() or
-                 wxPropertyGridInterface::AppendIn() will automatically set
-                 property to use wxPG_PROP_MISC_PARENT style.
+        @remarks You generally do not need to call this function.
     */
     void SetParentalType( int flag );
 
+    /**
+        Sets property's text colour.
+
+        @param colour
+            Text colour to use.
+
+        @param recursively
+            If @true, children are affected recursively, and any categories
+            are not.
+    */
+    void SetTextColour( const wxColour& colour,
+                        bool recursively = false );
+
     /** Sets wxValidator for a property */
     void SetValidator( const wxValidator& validator );
 
@@ -1343,15 +1397,17 @@ public:
             If you need to change property value in event, based on user input, use
             SetValueInEvent() instead.
 
+        @param value
+            The value to set.
         @param pList
             Pointer to list variant that contains child values. Used to indicate
-            which children should be marked as modified. Usually you just use NULL.
-
+            which children should be marked as modified. Usually you just use @NULL.
         @param flags
-            Use wxPG_SETVAL_REFRESH_EDITOR to update editor control, if it
-            was selected.
+            wxPG_SETVAL_REFRESH_EDITOR is set by default, to refresh editor
+            and redraw properties.
     */
-    void SetValue( wxVariant value, wxVariant* pList = NULL, int flags = 0 );
+    void SetValue( wxVariant value, wxVariant* pList = NULL,
+                   int flags = wxPG_SETVAL_REFRESH_EDITOR );
 
     /**
         Set wxBitmap in front of the value. This bitmap may be ignored
@@ -1386,16 +1442,25 @@ public:
     wxPGProperty* UpdateParentValues();
 
     /**
-        Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
+        Returns @true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
     */
     bool UsesAutoUnspecified() const;
 };
 
 
-/** @class wxPGChoices
+/**
+    @class wxPGChoices
 
     Helper class for managing choices of wxPropertyGrid properties.
-    Each entry can have label, value, bitmap, text colour, and background colour.
+    Each entry can have label, value, bitmap, text colour, and background
+    colour.
+    wxPGChoices uses reference counting, similar to other wxWidgets classes.
+    This means that assignment operator and copy constructor only copy the
+    reference and not the actual data. Use Copy() member function to create a
+    real copy.
+
+    @remarks If you do not specify value for entry, index is used.
 
     @library{wxpropgrid}
     @category{propgrid}
@@ -1410,7 +1475,10 @@ public:
     */
     wxPGChoices();
 
-    /** Copy constructor. */
+    /**
+        Copy constructor, uses reference counting. To create a real copy,
+        use Copy() member function instead.
+    */
     wxPGChoices( const wxPGChoices& a );
 
     /** Constructor. */
@@ -1445,21 +1513,16 @@ public:
                           int value = wxPG_INVALID_VALUE );
 
     /** Adds a single item with full entry information. */
-    wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry )
-    {
-        return Insert(entry, -1);
-    }
+    wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry );
 
     /** Adds single item, sorted. */
     wxPGChoiceEntry& AddAsSorted( const wxString& label, int value = wxPG_INVALID_VALUE );
 
     /**
-        Assigns data from another set of choices.
+        Assigns choices data, using reference counting. To create a real copy,
+        use Copy() member function instead.
     */
-    void Assign( const wxPGChoices& a )
-    {
-        AssignData(a.m_data);
-    }
+    void Assign( const wxPGChoices& a );
 
     /**
         Assigns data from another set of choices.
@@ -1469,11 +1532,12 @@ public:
     /**
         Deletes all items.
     */
-    void Clear()
-    {
-        if ( m_data != wxPGChoicesEmptyData )
-            m_data->Clear();
-    }
+    void Clear();
+
+    /**
+        Returns a real copy of the choices.
+    */
+    wxPGChoices Copy() const;
 
     /**
         Returns labe of item.
@@ -1498,7 +1562,7 @@ public:
 
     /**
         Returns array of indices matching given strings. Unmatching strings
-        are added to 'unmatched', if not NULL.
+        are added to 'unmatched', if not @NULL.
     */
     wxArrayInt GetIndicesForStrings( const wxArrayString& strings,
                                      wxArrayString* unmatched = NULL ) const;
@@ -1529,31 +1593,20 @@ public:
     wxPGChoiceEntry& Insert( const wxPGChoiceEntry& entry, int index );
 
     /**
-        Returns false if this is a constant empty set of choices,
+        Returns @false if this is a constant empty set of choices,
         which should not be modified.
     */
-    bool IsOk() const
-    {
-        return ( m_data != wxPGChoicesEmptyData );
-    }
+    bool IsOk() const;
 
     /**
         Returns item at given index.
     */
-    const wxPGChoiceEntry& Item( unsigned int i ) const
-    {
-        wxASSERT( IsOk() );
-        return *m_data->Item(i);
-    }
+    const wxPGChoiceEntry& Item( unsigned int i ) const;
 
     /**
         Returns item at given index.
     */
-    wxPGChoiceEntry& Item( unsigned int i )
-    {
-        wxASSERT( IsOk() );
-        return *m_data->Item(i);
-    }
+    wxPGChoiceEntry& Item( unsigned int i );
 
     /**
         Removes count items starting at position nIndex.
@@ -1573,27 +1626,17 @@ public:
     /**
         Creates exclusive copy of current choices.
     */
-    void SetExclusive();
+    void AllocExclusive();
 
     /**
         Returns array of choice labels.
     */
     wxArrayString GetLabels() const;
 
-    void operator= (const wxPGChoices& a)
-    {
-        AssignData(a.m_data);
-    }
-
-    wxPGChoiceEntry& operator[](unsigned int i)
-    {
-        return Item(i);
-    }
+    void operator= (const wxPGChoices& a);
 
-    const wxPGChoiceEntry& operator[](unsigned int i) const
-    {
-        return Item(i);
-    }
+    wxPGChoiceEntry& operator[](unsigned int i);
+    const wxPGChoiceEntry& operator[](unsigned int i) const;
 };
 
 // -----------------------------------------------------------------------