Fixed and refactored wxPropertyGridManager decsription text box painting

[wxWidgets.git] / include / wx / propgrid / property.h

diff --git a/include/wx/propgrid/property.h b/include/wx/propgrid/property.h
index 593de4b4678d21abe91a3057afc30350dc881940..15e520ee61f3b8a779ee3703266ae7eb0c42184a 100644 (file)
--- a/include/wx/propgrid/property.h
+++ b/include/wx/propgrid/property.h
@@ -4,7 +4,7 @@
 // Author:      Jaakko Salli
 // Modified by:
 // Created:     2008-08-23
 // Author:      Jaakko Salli
 // Modified by:
 // Created:     2008-08-23

-// RCS-ID:      $Id:
+// RCS-ID:      $Id$

 // Copyright:   (c) Jaakko Salli
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 // Copyright:   (c) Jaakko Salli
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////


@@ -47,13 +47,6 @@ struct wxPGPaintData
 };
 
 
 };
 
 

-// Structure for relaying choice/list info.
-struct wxPGChoiceInfo
-{
-    wxPGChoices*    m_choices;
-};
-
-

 #ifndef SWIG
 
 
 #ifndef SWIG
 
 


@@ -82,8 +75,27 @@ public:
     // Render flags
     enum
     {
     // Render flags
     enum
     {

+        // We are painting selected item

         Selected        = 0x00010000,
         Selected        = 0x00010000,

-        Control         = 0x00020000
+
+        // We are painting item in choice popup
+        ChoicePopup     = 0x00020000,
+
+        // We are rendering wxOwnerDrawnComboBox control
+        // (or other owner drawn control, but that is only
+        // officially supported one ATM).
+        Control         = 0x00040000,
+
+        // We are painting a disable property
+        Disabled        = 0x00080000,
+
+        // We are painting selected, disabled, or similar
+        // item that dictates fore- and background colours,
+        // overriding any cell values.
+        DontUseCellFgCol    = 0x00100000,
+        DontUseCellBgCol    = 0x00200000,
+        DontUseCellColours  = DontUseCellFgCol |
+                              DontUseCellBgCol

     };
 
     virtual void Render( wxDC& dc,
     };
 
     virtual void Render( wxDC& dc,


@@ -152,14 +164,46 @@ private:
 };
 
 
 };
 
 

+class WXDLLIMPEXP_PROPGRID wxPGCellData : public wxObjectRefData
+{
+    friend class wxPGCell;
+public:
+    wxPGCellData();
+
+    void SetText( const wxString& text )
+    {
+        m_text = text;
+        m_hasValidText = true;
+    }
+    void SetBitmap( const wxBitmap& bitmap ) { m_bitmap = bitmap; }
+    void SetFgCol( const wxColour& col ) { m_fgCol = col; }
+    void SetBgCol( const wxColour& col ) { m_bgCol = col; }
+
+protected:
+    virtual ~wxPGCellData() { }
+
+    wxString    m_text;
+    wxBitmap    m_bitmap;
+    wxColour    m_fgCol;
+    wxColour    m_bgCol;
+
+    // True if m_text is valid and specified
+    bool        m_hasValidText;
+};
+

 /** @class wxPGCell
 
     Base class for simple wxPropertyGrid cell information.
 */
 /** @class wxPGCell
 
     Base class for simple wxPropertyGrid cell information.
 */

-class WXDLLIMPEXP_PROPGRID wxPGCell
+class WXDLLIMPEXP_PROPGRID wxPGCell : public wxObject

 {
 public:
     wxPGCell();
 {
 public:
     wxPGCell();

+    wxPGCell(const wxPGCell& other)
+        : wxObject(other)
+    {
+    }
+

     wxPGCell( const wxString& text,
               const wxBitmap& bitmap = wxNullBitmap,
               const wxColour& fgCol = wxNullColour,
     wxPGCell( const wxString& text,
               const wxBitmap& bitmap = wxNullBitmap,
               const wxColour& fgCol = wxNullColour,


@@ -167,21 +211,50 @@ public:
 
     virtual ~wxPGCell() { }
 
 
     virtual ~wxPGCell() { }
 

-    void SetText( const wxString& text ) { m_text = text; }
-    void SetBitmap( const wxBitmap& bitmap ) { m_bitmap = bitmap; }
-    void SetFgCol( const wxColour& col ) { m_fgCol = col; }
-    void SetBgCol( const wxColour& col ) { m_bgCol = col; }
+    wxPGCellData* GetData()
+    {
+        return (wxPGCellData*) m_refData;
+    }
+
+    const wxPGCellData* GetData() const
+    {
+        return (const wxPGCellData*) m_refData;
+    }
+
+    bool HasText() const
+    {
+        return (m_refData && GetData()->m_hasValidText);
+    }

 
 

-    const wxString& GetText() const { return m_text; }
-    const wxBitmap& GetBitmap() const { return m_bitmap; }
-    const wxColour& GetFgCol() const { return m_fgCol; }
-    const wxColour& GetBgCol() const { return m_bgCol; }
+    /**
+        Merges valid data from srcCell into this.
+    */
+    void MergeFrom( const wxPGCell& srcCell );
+
+    void SetText( const wxString& text );
+    void SetBitmap( const wxBitmap& bitmap );
+    void SetFgCol( const wxColour& col );
+    void SetBgCol( const wxColour& col );
+
+    const wxString& GetText() const { return GetData()->m_text; }
+    const wxBitmap& GetBitmap() const { return GetData()->m_bitmap; }
+    const wxColour& GetFgCol() const { return GetData()->m_fgCol; }
+    const wxColour& GetBgCol() const { return GetData()->m_bgCol; }
+
+    wxPGCell& operator=( const wxPGCell& other )
+    {
+        if ( this != &other )
+        {
+            Ref(other);
+        }
+        return *this;
+    }

 
 protected:
 
 protected:

-    wxString    m_text;
-    wxBitmap    m_bitmap;
-    wxColour    m_fgCol;
-    wxColour    m_bgCol;
+    virtual wxObjectRefData *CreateRefData() const
+        { return new wxPGCellData(); }
+
+    virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const;

 };
 
 
 };
 
 


@@ -222,7 +295,7 @@ public:
     ~wxPGAttributeStorage();
 
     void Set( const wxString& name, const wxVariant& value );
     ~wxPGAttributeStorage();
 
     void Set( const wxString& name, const wxVariant& value );

-    size_t GetCount() const { return m_map.size(); }
+    unsigned int GetCount() const { return (unsigned int) m_map.size(); }

     wxVariant FindValue( const wxString& name ) const
     {
         wxPGHashMapS2P::const_iterator it = m_map.find(name);
     wxVariant FindValue( const wxString& name ) const
     {
         wxPGHashMapS2P::const_iterator it = m_map.find(name);


@@ -249,7 +322,7 @@ public:
         data->IncRef();
         variant.SetData(data);
         variant.SetName(it->first);
         data->IncRef();
         variant.SetData(data);
         variant.SetName(it->first);

-        it++;
+        ++it;

         return true;
     }
 
         return true;
     }
 


@@ -396,9 +469,6 @@ wxPG_PROP_CLASS_SPECIFIC_2          = 0x00100000
 /** @}
 */
 
 /** @}
 */
 

-// Amalgam of flags that should be inherited by sub-properties
-#define wxPG_INHERITED_PROPFLAGS        (wxPG_PROP_HIDDEN|wxPG_PROP_NOEDITOR)
-

 // 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)
 // 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)


@@ -567,1633 +637,1757 @@ wxPG_PROP_CLASS_SPECIFIC_2          = 0x00100000
 
 // -----------------------------------------------------------------------
 
 
 // -----------------------------------------------------------------------
 

-/** @class wxPGProperty
-
-    wxPGProperty is base class for all wxPropertyGrid properties.
-
-    NB: Full class overview is now only present in
-        interface/wx/propgrid/property.h.
+#ifndef SWIG

 
 

-    @library{wxpropgrid}
-    @category{propgrid}
+/** @class wxPGChoiceEntry
+    Data of a single wxPGChoices choice.

 */
 */

-class WXDLLIMPEXP_PROPGRID wxPGProperty : public wxObject
+class WXDLLIMPEXP_PROPGRID wxPGChoiceEntry : public wxPGCell

 {
 {

-    friend class wxPropertyGrid;
-    friend class wxPropertyGridInterface;
-    friend class wxPropertyGridPageState;
-    friend class wxPropertyGridPopulator;
-    friend class wxStringProperty;  // Proper "<composed>" support requires this
-#ifndef SWIG
-    DECLARE_ABSTRACT_CLASS(wxPGProperty)
-#endif

 public:
 public:

-    typedef wxUint32 FlagType;
-
-    /** Basic constructor.
-    */
-    wxPGProperty();
+    wxPGChoiceEntry();
+    wxPGChoiceEntry(const wxPGChoiceEntry& other)
+        : wxPGCell(other)
+    {
+        m_value = other.m_value;
+    }
+    wxPGChoiceEntry( const wxString& label,
+                     int value = wxPG_INVALID_VALUE )
+        : wxPGCell(), m_value(value)
+    {
+        SetText(label);
+    }

 
 

-    /** Constructor.
-        Non-abstract property classes should have constructor of this style:
+    virtual ~wxPGChoiceEntry() { }

 
 

-        @code
+    void SetValue( int value ) { m_value = value; }
+    int GetValue() const { return m_value; }

 
 

-        // If T is a class, then it should be a constant reference
-        // (e.g. const T& ) instead.
-        MyProperty( const wxString& label, const wxString& name, T value )
-            : wxPGProperty()
+    wxPGChoiceEntry& operator=( const wxPGChoiceEntry& other )
+    {
+        if ( this != &other )

         {
         {

-            // Generally recommended way to set the initial value
-            // (as it should work in pretty much 100% of cases).
-            wxVariant variant;
-            variant << value;
-            SetValue(variant);
-
-            // If has private child properties then create them here, e.g.:
-            //     AddChild( new wxStringProperty( "Subprop 1",
-            //                                     wxPG_LABEL,
-            //                                     value.GetSubProp1() ) );
+            Ref(other);

         }
         }

+        m_value = other.m_value;
+        return *this;
+    }

 
 

-        @endcode
-    */
-    wxPGProperty( const wxString& label, const wxString& name );
-
-    /**
-        Virtual destructor.
-        It is customary for derived properties to implement this.
-    */
-    virtual ~wxPGProperty();
+protected:
+    int m_value;
+};

 
 

-    /** This virtual function is called after m_value has been set.

 
 

-        @remarks
-        - If m_value was set to Null variant (ie. 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
-          supported values into internal type.
-        - Default implementation does nothing.
-    */
-    virtual void OnSetValue();
+typedef void* wxPGChoicesId;

 
 

-    /** Override this to return something else than m_value as the value.
-    */
-    virtual wxVariant DoGetValue() const { return m_value; }
+class WXDLLIMPEXP_PROPGRID wxPGChoicesData
+{
+    friend class wxPGChoices;
+public:
+    // Constructor sets m_refCount to 1.
+    wxPGChoicesData();

 
 

-#if !defined(SWIG) || defined(CREATE_VCW)
-    /** Implement this function in derived class to check the value.
-        Return true if it is ok. Returning false prevents property change events
-        from occurring.
+    void CopyDataFrom( wxPGChoicesData* data );

 
 

-        @remarks
-        - Default implementation always returns true.
-    */
-    virtual bool ValidateValue( wxVariant& value,
-                                wxPGValidationInfo& validationInfo ) const;
+    wxPGChoiceEntry& Insert( int index, const wxPGChoiceEntry& item );

 
 

-    /**
-        Converts 'text' into proper value 'variant'.
-        Returns true if new (different than m_value) value could be interpreted
-        from the text.
-        @param argFlags
-            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()
-            called with this same flag).
+    // Delete all entries
+    void Clear();

 
 

-        @remarks
-        Default implementation converts semicolon delimited tokens into child
-        values. Only works for properties with children.
-    */
-    virtual bool StringToValue( wxVariant& variant,
-                                const wxString& text,
-                                int argFlags = 0 ) const;
+    unsigned int GetCount() const
+    {
+        return (unsigned int) m_items.size();
+    }

 
 

-    /**
-        Converts 'number' (including choice selection) into proper value
-        'variant'.
+    const wxPGChoiceEntry& Item( unsigned int i ) const
+    {
+        wxASSERT_MSG( i < GetCount(), "invalid index" );
+        return m_items[i];
+    }

 
 

-        Returns true if new (different than m_value) value could be interpreted
-        from the integer.
+    wxPGChoiceEntry& Item( unsigned int i )
+    {
+        wxASSERT_MSG( i < GetCount(), "invalid index" );
+        return m_items[i];
+    }

 
 

-        @param argFlags
-            If wxPG_FULL_VALUE is set, returns complete, storable value instead
-            of displayable one.
+    void DecRef()
+    {
+        m_refCount--;
+        wxASSERT( m_refCount >= 0 );
+        if ( m_refCount == 0 )
+            delete this;
+    }

 
 

-        @remarks
-        - If property is not supposed to use choice or spinctrl or other editor
-          with int-based value, it is not necessary to implement this method.
-        - Default implementation simply assign given int to m_value.
-        - 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.
-    */
-    virtual bool IntToValue( wxVariant& value,
-                             int number,
-                             int argFlags = 0 ) const;
-#endif  // !defined(SWIG) || defined(CREATE_VCW)
+private:
+    wxVector<wxPGChoiceEntry>   m_items;

 
 

-public:
-    /** Returns text representation of property's value.
+    // So that multiple properties can use the same set
+    int             m_refCount;

 
 

-        @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.
+    virtual ~wxPGChoicesData();
+};

 
 

-        @remarks
-        Default implementation returns string composed from text
-        representations of child properties.
-    */
-    virtual wxString GetValueAsString( int argFlags = 0 ) const;
+#define wxPGChoicesEmptyData    ((wxPGChoicesData*)NULL)

 
 

-    /** 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.
-        @return
-        true if value was changed.
-    */
-    bool SetValueFromString( const wxString& text, int flags = 0 );
+#endif // SWIG

 
 

-    /** 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.
-        @param flags
-            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 );
+/** @class wxPGChoices

 
 

-    /**
-        Returns size of the custom painted image in front of property.
+    Helper class for managing choices of wxPropertyGrid properties.
+    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.

 
 

-        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.
-        @remarks
-        - Default behavior 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, i.e. wxSize(-1, -1).
-    */
-    virtual wxSize OnMeasureImage( int item = -1 ) const;
+    @remarks If you do not specify value for entry, index is used.

 
 

-    /**
-        Events received by editor widgets are processed here.
+    @library{wxpropgrid}
+    @category{propgrid}
+*/
+class WXDLLIMPEXP_PROPGRID wxPGChoices
+{
+public:
+    typedef long ValArrItem;

 
 

-        Note that editor class usually processes most events. Some, such as
-        button press events of TextCtrlAndButton class, can be handled here.
-        Also, if custom handling for regular events is desired, then that can
-        also be done (for example, 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.
-
-        @param event
-        Associated wxEvent.
-        @return
-        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.
-    */
-    virtual bool OnEvent( wxPropertyGrid* propgrid,
-                          wxWindow* wnd_primary,
-                          wxEvent& event );
+    /** Default constructor. */
+    wxPGChoices()
+    {
+        Init();
+    }

 
     /**
 
     /**

-        Called after value of a child property has been altered.
-
-        Note that this function is usually called at the time that value of
-        this property, or given child property, is still pending for change.
-
-        Sample pseudo-code implementation:
-
-        @code
-        void MyProperty::ChildChanged( wxVariant& thisValue,
-                                       int childIndex,
-                                       wxVariant& childValue ) const
-        {
-            // Acquire reference to actual type of data stored in variant
-            // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros
-            // were used to create the variant class).
-            T& data = TFromVariant(thisValue);
-
-            // Copy childValue into data.
-            switch ( childIndex )
-            {
-                case 0:
-                    data.SetSubProp1( childvalue.GetLong() );
-                    break;
-                case 1:
-                    data.SetSubProp2( childvalue.GetString() );
-                    break;
-                ...
-            }
-        }
-        @endcode
-
-        @param thisValue
-            Value of this property, that should be altered.
-        @param childIndex
-            Index of child changed (you can use Item(childIndex) to get).
-        @param childValue
-            Value of the child property.
+        Copy constructor, uses reference counting. To create a real copy,
+        use Copy() member function instead.

     */
     */

-    virtual void ChildChanged( wxVariant& thisValue,
-                               int childIndex,
-                               wxVariant& childValue ) const;
-
-    /** Returns pointer to an instance of used editor.
-    */
-    virtual const wxPGEditor* DoGetEditorClass() const;
-
-    /** Returns pointer to the wxValidator that should be used
-        with the editor of this property (NULL for no validator).
-        Setting validator explicitly via SetPropertyValidator
-        will override this.
-
-        In most situations, code like this should work well
-        (macros are used to maintain one actual validator instance,
-        so on the second call the function exits within the first
-        macro):
-
-        @code
-
-        wxValidator* wxMyPropertyClass::DoGetValidator () const
+    wxPGChoices( const wxPGChoices& a )
+    {
+        if ( a.m_data != wxPGChoicesEmptyData )

         {
         {

-            WX_PG_DOGETVALIDATOR_ENTRY()
-
-            wxMyValidator* validator = new wxMyValidator(...);
-
-            ... prepare validator...
-
-            WX_PG_DOGETVALIDATOR_EXIT(validator)
+            m_data = a.m_data;
+            m_data->m_refCount++;

         }
         }

-
-        @endcode
-
-        @remarks
-        You can get common filename validator by returning
-        wxFileProperty::GetClassValidator(). wxDirProperty,
-        for example, uses it.
-    */
-    virtual wxValidator* DoGetValidator () const;
+    }

 
     /**
 
     /**

-        Returns current value's index to the choice control.
+        Constructor.

 
 

-        May also return, through pointer arguments, strings that should be
-        inserted to that control. Irrelevant to classes which do not employ
-        wxPGEditor_Choice or similar.
+        @param labels
+            Labels for choices

 
 

-        @remarks
-        - If returns NULL in choiceinfo.m_choices, then this class must be
-          derived from wxBaseEnumProperty.
-        - Must be able to cope situation where property's set of choices is
-          uninitialized.
+        @param values
+            Values for choices. If NULL, indexes are used.

     */
     */

-    virtual int GetChoiceInfo( wxPGChoiceInfo* choiceinfo );
+    wxPGChoices( const wxChar** labels, const long* values = NULL )
+    {
+        Init();
+        Set(labels,values);
+    }

 
     /**
 
     /**

-        Override to paint an image in front of the property value text or
-        drop-down list item (but only if wxPGProperty::OnMeasureImage is
-        overridden as well).
-
-        If property's OnMeasureImage() returns size that has height != 0 but
-        less than row height ( < 0 has special meanings), wxPropertyGrid calls
-        this method to draw a custom image in a limited area in front of the
-        editor control or value text/graphics, and if control has drop-down
-        list, then the image is drawn there as well (even in the case
-        OnMeasureImage() returned higher height than row height).
+        Constructor.

 
 

-        NOTE: Following applies when OnMeasureImage() returns a "flexible"
-        height ( using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable
-        height items: If rect.x is < 0, then this is a measure item call, which
-        means that dc is invalid and only thing that should be done is to set
-        paintdata.m_drawnHeight to the height of the image of item at index
-        paintdata.m_choiceItem. This call may be done even as often as once
-        every drop-down popup show.
+        @param labels
+            Labels for choices

 
 

-        @param dc
-            wxDC to paint on.
-        @param rect
-            Box reserved for custom graphics. Includes surrounding rectangle,
-            if any. If x is < 0, then this is a measure item call (see above).
-        @param paintdata
-            wxPGPaintData structure with much useful data.
+        @param values
+            Values for choices. If empty, indexes are used.
+    */
+    wxPGChoices( const wxArrayString& labels,
+                 const wxArrayInt& values = wxArrayInt() )
+    {
+        Init();
+        Set(labels,values);
+    }

 
 

-        @remarks
-            - You can actually exceed rect width, but if you do so then
-              paintdata.m_drawnWidth must be set to the full width drawn in
-              pixels.
-            - Due to technical reasons, rect's height will be default even if
-              custom height was reported during measure call.
-            - Brush is guaranteed to be default background colour. It has been
-              already used to clear the background of area being painted. It
-              can be modified.
-            - 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.
+    /** Simple interface constructor. */
+    wxPGChoices( wxPGChoicesData* data )
+    {
+        wxASSERT(data);
+        m_data = data;
+        data->m_refCount++;
+    }

 
 

-        @see GetValueAsString()
-    */
-    virtual void OnCustomPaint( wxDC& dc,
-                                const wxRect& rect,
-                                wxPGPaintData& paintdata );
+    /** Destructor. */
+    ~wxPGChoices()
+    {
+        Free();
+    }

 
     /**
 
     /**

-        Returns used wxPGCellRenderer instance for given property column
-        (label=0, value=1).
+        Adds to current.

 
 

-        Default implementation returns editor's renderer for all columns.
-    */
-    virtual wxPGCellRenderer* GetCellRenderer( int column ) const;
+        If did not have own copies, creates them now. If was empty, identical
+        to set except that creates copies.

 
 

-    /**
-        Refresh values of child properties.
+        @param labels
+            Labels for added choices.

 
 

-        Automatically called after value is set.
+        @param values
+            Values for added choices. If empty, relevant entry indexes are used.

     */
     */

-    virtual void RefreshChildren();
+    void Add( const wxChar** labels, const ValArrItem* values = NULL );

 
 

-    /** Special handling for attributes of this property.
+    /** Version that works with wxArrayString and wxArrayInt. */
+    void Add( const wxArrayString& arr, const wxArrayInt& arrint = wxArrayInt() );

 
 

-        If returns false, then the attribute will be automatically stored in
-        m_attributes.
+    /**
+        Adds a single choice.

 
 

-        Default implementation simply returns false.
+        @param label
+            Label for added choice.
+
+        @param value
+            Value for added choice. If unspecified, index is used.

     */
     */

-    virtual bool DoSetAttribute( const wxString& name, wxVariant& value );
+    wxPGChoiceEntry& Add( const wxString& label,
+                          int value = wxPG_INVALID_VALUE );

 
 

-    /** Returns value of an attribute.
+    /** Adds a single item, with bitmap. */
+    wxPGChoiceEntry& Add( const wxString& label,
+                          const wxBitmap& bitmap,
+                          int value = wxPG_INVALID_VALUE );

 
 

-        Override if custom handling of attributes is needed.
+    /** Adds a single item with full entry information. */
+    wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry )
+    {
+        return Insert(entry, -1);
+    }

 
 

-        Default implementation simply return NULL variant.
+    /** Adds single item. */
+    wxPGChoiceEntry& AddAsSorted( const wxString& label,
+                                  int value = wxPG_INVALID_VALUE );
+
+    /**
+        Assigns choices data, using reference counting. To create a real copy,
+        use Copy() member function instead.

     */
     */

-    virtual wxVariant DoGetAttribute( const wxString& name ) const;
+    void Assign( const wxPGChoices& a )
+    {
+        AssignData(a.m_data);
+    }

 
 

-    /** Returns instance of a new wxPGEditorDialogAdapter instance, which is
-        used when user presses the (optional) button next to the editor control;
+    void AssignData( wxPGChoicesData* data );

 
 

-        Default implementation returns NULL (ie. no action is generated when
-        button is pressed).
-    */
-    virtual wxPGEditorDialogAdapter* GetEditorDialog() const;
+    /** Delete all choices. */
+    void Clear();

 
     /**
 
     /**

-        Adds entry to property's wxPGChoices and editor control (if it is
-        active).
-
-        Returns index of item added.
+        Returns a real copy of the choices.

     */
     */

-    int AppendChoice( const wxString& label, int value = wxPG_INVALID_VALUE )
+    wxPGChoices Copy() const

     {
     {

-        return InsertChoice(label,-1,value);
+        wxPGChoices dst;
+        dst.EnsureData();
+        dst.m_data->CopyDataFrom(m_data);
+        return dst;

     }
 
     }
 

-    /** Returns wxPGCell of given column, NULL if none. If valid
-        object is returned, caller will gain its ownership.
-    */
-    wxPGCell* AcquireCell( unsigned int column )
+    void EnsureData()

     {
     {

-        if ( column >= m_cells.size() )
-            return NULL;
+        if ( m_data == wxPGChoicesEmptyData )
+            m_data = new wxPGChoicesData();
+    }
+
+    /** Gets a unsigned number identifying this list. */
+    wxPGChoicesId GetId() const { return (wxPGChoicesId) m_data; };

 
 

-        wxPGCell* cell = (wxPGCell*) m_cells[column];
-        m_cells[column] = NULL;
-        return cell;
+    const wxString& GetLabel( unsigned int ind ) const
+    {
+        return Item(ind).GetText();

     }
 
     }
 

-    /**
-        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
+    unsigned int GetCount () const

     {
     {

-        if ( m_flags & (wxPG_PROP_COMPOSED_VALUE|wxPG_PROP_AGGREGATE) )
-            return true;
+        if ( !m_data )
+            return 0;

 
 

-        return false;
+        return m_data->GetCount();

     }
 
     }
 

-    /**
-        Removes entry from property's wxPGChoices and editor control (if it is
-        active).
+    int GetValue( unsigned int ind ) const { return Item(ind).GetValue(); }

 
 

-        If selected item is deleted, then the value is set to unspecified.
+    /** Returns array of values matching the given strings. Unmatching strings
+        result in wxPG_INVALID_VALUE entry in array.

     */
     */

-    void DeleteChoice( int index );
-
-    /**
-        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.
+    wxArrayInt GetValuesForStrings( const wxArrayString& strings ) const;

 
 

-        Common values are disabled by the default for all properties.
+    /** Returns array of indices matching given strings. Unmatching strings
+        are added to 'unmatched', if not NULL.

     */
     */

-    void EnableCommonValue( bool enable = true )
-    {
-        if ( enable ) SetFlag( wxPG_PROP_USES_COMMON_VALUE );
-        else ClearFlag( wxPG_PROP_USES_COMMON_VALUE );
-    }
-
-    /** Composes text from values of child properties. */
-    void GenerateComposedValue( wxString& text, int argFlags = 0 ) const;
-
-    /** Returns property's label. */
-    const wxString& GetLabel() const { return m_label; }
-
-    /** Returns property's name with all (non-category, non-root) parents. */
-    wxString GetName() const;
-
-    /**
-        Returns property's base name (ie parent's name is not added in any
-        case)
-     */
-    const wxString& GetBaseName() const { return m_name; }
+    wxArrayInt GetIndicesForStrings( const wxArrayString& strings,
+                                     wxArrayString* unmatched = NULL ) const;

 
 

-    wxPGChoices& GetChoices();
+    int Index( const wxString& str ) const;
+    int Index( int val ) const;

 
 

-    const wxPGChoices& GetChoices() const;
+    /** Inserts single item. */
+    wxPGChoiceEntry& Insert( const wxString& label,
+                             int index,
+                             int value = wxPG_INVALID_VALUE );

 
 

-    const wxPGChoiceEntry* GetCurrentChoice() const;
+    /** Inserts a single item with full entry information. */
+    wxPGChoiceEntry& Insert( const wxPGChoiceEntry& entry, int index );

 
 

-    /** Returns coordinate to the top y of the property. Note that the
-        position of scrollbars is not taken into account.
+    /** Returns false if this is a constant empty set of choices,
+        which should not be modified.

     */
     */

-    int GetY() const;
-
-    wxVariant GetValue() const
+    bool IsOk() const

     {
     {

-        return DoGetValue();
+        return ( m_data != wxPGChoicesEmptyData );

     }
 
     }
 

-#ifndef SWIG
-    /** Returns reference to the internal stored value. GetValue is preferred
-        way to get the actual value, since GetValueRef ignores DoGetValue,
-        which may override stored value.
-    */
-    wxVariant& GetValueRef()
+    const wxPGChoiceEntry& Item( unsigned int i ) const

     {
     {

-        return m_value;
+        wxASSERT( IsOk() );
+        return m_data->Item(i);

     }
 
     }
 

-    const wxVariant& GetValueRef() const
+    wxPGChoiceEntry& Item( unsigned int i )

     {
     {

-        return m_value;
+        wxASSERT( IsOk() );
+        return m_data->Item(i);

     }
     }

-#endif
-
-    /** Same as GetValueAsString, except takes common value into account.
-    */
-    wxString GetValueString( int argFlags = 0 ) const;

 
 

-    void UpdateControl( wxWindow* primary );
+    /** Removes count items starting at position nIndex. */
+    void RemoveAt(size_t nIndex, size_t count = 1);

 
 

-    /** Returns wxPGCell of given column, NULL if none. wxPGProperty
-        will retain ownership of the cell object.
-    */
-    wxPGCell* GetCell( unsigned int column ) const
+#ifndef SWIG
+    /** Does not create copies for itself. */
+    void Set( const wxChar** labels, const long* values = NULL )

     {
     {

-        if ( column >= m_cells.size() )
-            return NULL;
-
-        return (wxPGCell*) m_cells[column];
+        Free();
+        Add(labels,values);

     }
     }

+#endif // SWIG

 
 

-    unsigned int GetChoiceCount() const;
-
-    wxString GetChoiceString( unsigned int index );
-
-    /** Return number of displayed common values for this property.
-    */
-    int GetDisplayedCommonValueCount() const;
-
-    wxString GetDisplayedString() const
+    /** Version that works with wxArrayString and wxArrayInt. */
+    void Set( const wxArrayString& labels,
+              const wxArrayInt& values = wxArrayInt() )

     {
     {

-        return GetValueString(0);
+        Free();
+        if ( &values )
+            Add(labels,values);
+        else
+            Add(labels);

     }
 
     }
 

-    /** Returns property grid where property lies. */
-    wxPropertyGrid* GetGrid() const;
-
-    /** Returns owner wxPropertyGrid, but only if one is currently on a page
-        displaying this property. */
-    wxPropertyGrid* GetGridIfDisplayed() const;
-
-    /** Returns highest level non-category, non-root parent. Useful when you
-        have nested wxCustomProperties/wxParentProperties.
-        @remarks
-        Thus, if immediate parent is root or category, this will return the
-        property itself.
-    */
-    wxPGProperty* GetMainParent() const;
-
-    /** Return parent of property */
-    wxPGProperty* GetParent() const { return m_parent; }
-
-    /** Returns true if property has editable wxTextCtrl when selected.
-
-        @remarks
-        Altough disabled properties do not displayed editor, they still
-        return True here as being disabled is considered a temporary
-        condition (unlike being read-only or having limited editing enabled).
-    */
-    bool IsTextEditable() const;
+    // Creates exclusive copy of current choices
+    void AllocExclusive();

 
 

-    bool IsValueUnspecified() const
+    // Returns data, increases refcount.
+    wxPGChoicesData* GetData()

     {
     {

-        return m_value.IsNull();
+        wxASSERT( m_data->m_refCount != 0xFFFFFFF );
+        m_data->m_refCount++;
+        return m_data;

     }
 
     }
 

-    FlagType HasFlag( FlagType flag ) const
-    {
-        return ( m_flags & flag );
-    }
+    // Returns plain data ptr - no refcounting stuff is done.
+    wxPGChoicesData* GetDataPtr() const { return m_data; }

 
 

-    /** Returns comma-delimited string of property attributes.
-    */
-    const wxPGAttributeStorage& GetAttributes() const
+    // Changes ownership of data to you.
+    wxPGChoicesData* ExtractData()

     {
     {

-        return m_attributes;
+        wxPGChoicesData* data = m_data;
+        m_data = wxPGChoicesEmptyData;
+        return data;

     }
 
     }
 

-    /** Returns m_attributes as list wxVariant.
-    */
-    wxVariant GetAttributesAsList() const;
+    wxArrayString GetLabels() const;

 
 

-    FlagType GetFlags() const
+#ifndef SWIG
+    void operator= (const wxPGChoices& a)

     {
     {

-        return m_flags;
+        if (this != &a)
+            AssignData(a.m_data);

     }
 
     }
 

-    const wxPGEditor* GetEditorClass() const;
-
-    wxString GetValueType() const
+    wxPGChoiceEntry& operator[](unsigned int i)

     {
     {

-        return m_value.GetType();
+        return Item(i);

     }
 
     }
 

-    /** Returns editor used for given column. NULL for no editor.
-    */
-    const wxPGEditor* GetColumnEditor( int column ) const
+    const wxPGChoiceEntry& operator[](unsigned int i) const

     {
     {

-        if ( column == 1 )
-            return GetEditorClass();
-
-        return NULL;
+        return Item(i);

     }
 
     }
 

-    /** Returns common value selected for this property. -1 for none.
-    */
-    int GetCommonValue() const
-    {
-        return m_commonValue;
-    }
+protected:
+    wxPGChoicesData*    m_data;

 
 

-    /** Returns true if property has even one visible child.
-    */
-    bool HasVisibleChildren() const;
+    void Init();
+    void Free();
+#endif  // !SWIG
+};

 
 

-    /**
-        Adds entry to property's wxPGChoices and editor control (if it is
-        active).
+// -----------------------------------------------------------------------

 
 

-        Returns index of item added.
-    */
-    int InsertChoice( const wxString& label,
-                      int index,
-                      int value = wxPG_INVALID_VALUE );
+/** @class wxPGProperty

 
 

-    /**
-        Returns true if this property is actually a wxPropertyCategory.
-    */
-    bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY)?true:false; }
+    wxPGProperty is base class for all wxPropertyGrid properties.

 
 

-    /** Returns true if this property is actually a wxRootProperty.
-    */
-    bool IsRoot() const { return (m_parent == NULL); }
+    NB: Full class overview is now only present in
+        interface/wx/propgrid/property.h.

 
 

-    /** Returns true if this is a sub-property. */
-    bool IsSubProperty() const
-    {
-        wxPGProperty* parent = (wxPGProperty*)m_parent;
-        if ( parent && !parent->IsCategory() )
-            return true;
-        return false;
-    }
+    @library{wxpropgrid}
+    @category{propgrid}
+*/
+class WXDLLIMPEXP_PROPGRID wxPGProperty : public wxObject
+{
+    friend class wxPropertyGrid;
+    friend class wxPropertyGridInterface;
+    friend class wxPropertyGridPageState;
+    friend class wxPropertyGridPopulator;
+    friend class wxStringProperty;  // Proper "<composed>" support requires this
+#ifndef SWIG
+    DECLARE_ABSTRACT_CLASS(wxPGProperty)
+#endif
+public:
+    typedef wxUint32 FlagType;

 
 

-    /** Returns last visible sub-property, recursively.
+    /** Basic constructor.

     */
     */

-    const wxPGProperty* GetLastVisibleSubItem() const;
-
-    wxVariant GetDefaultValue() const;
+    wxPGProperty();

 
 

-    int GetMaxLength() const
-    {
-        return (int) m_maxLen;
-    }
+    /** Constructor.
+        Non-abstract property classes should have constructor of this style:

 
 

-    /**
-        Determines, recursively, if all children are not unspecified.
+        @code

 
 

-        Takes values in given list into account.
-    */
-    bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const;
+        // If T is a class, then it should be a constant reference
+        // (e.g. const T& ) instead.
+        MyProperty( const wxString& label, const wxString& name, T value )
+            : wxPGProperty()
+        {
+            // Generally recommended way to set the initial value
+            // (as it should work in pretty much 100% of cases).
+            wxVariant variant;
+            variant << value;
+            SetValue(variant);

 
 

-    /** Updates composed values of parent non-category properties, recursively.
-        Returns topmost property updated.
+            // If has private child properties then create them here. Also
+            // set flag that indicates presence of private children. E.g.:
+            //
+            //     SetParentalType(wxPG_PROP_AGGREGATE);
+            //
+            //     AddChild( new wxStringProperty( "Subprop 1",
+            //                                     wxPG_LABEL,
+            //                                     value.GetSubProp1() ) );
+        }

 
 

-        @remarks
-        - Must not call SetValue() (as can be called in it).
+        @endcode

     */
     */

-    wxPGProperty* UpdateParentValues();
+    wxPGProperty( const wxString& label, const wxString& name );

 
 

-    /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
+    /**
+        Virtual destructor.
+        It is customary for derived properties to implement this.

     */
     */

-    FlagType UsesAutoUnspecified() const
-    {
-        return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED);
-    }
-
-    wxBitmap* GetValueImage() const
-    {
-        return m_valueBitmap;
-    }
+    virtual ~wxPGProperty();

 
 

-    wxVariant GetAttribute( const wxString& name ) const;
+    /** This virtual function is called after m_value has been set.

 
 

-    /**
-        Returns named attribute, as string, if found.
+        @remarks
+        - If m_value was set to Null variant (ie. 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
+          supported values into internal type.
+        - Default implementation does nothing.
+    */
+    virtual void OnSetValue();

 
 

-        Otherwise defVal is returned.
+    /** Override this to return something else than m_value as the value.

     */
     */

-    wxString GetAttribute( const wxString& name, const wxString& defVal ) const;
+    virtual wxVariant DoGetValue() const { return m_value; }

 
 

-    /**
-        Returns named attribute, as long, if found.
+#if !defined(SWIG) || defined(CREATE_VCW)
+    /** Implement this function in derived class to check the value.
+        Return true if it is ok. Returning false prevents property change events
+        from occurring.

 
 

-        Otherwise defVal is returned.
+        @remarks
+        - Default implementation always returns true.

     */
     */

-    long GetAttributeAsLong( const wxString& name, long defVal ) const;
+    virtual bool ValidateValue( wxVariant& value,
+                                wxPGValidationInfo& validationInfo ) const;

 
     /**
 
     /**

-        Returns named attribute, as double, if found.
+        Converts text into wxVariant value appropriate for this property.

 
 

-        Otherwise defVal is returned.
-    */
-    double GetAttributeAsDouble( const wxString& name, double defVal ) const;
+        @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.

 
 

-    unsigned int GetArrIndex() const { return m_arrIndex; }
+        @param text
+            Text to be translated into variant.

 
 

-    unsigned int GetDepth() const { return (unsigned int)m_depth; }
+        @param argFlags
+            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 ValueToString()
+            called with this same flag).

 
 

-    /** 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;
+        @return Returns @true if resulting wxVariant value was different.

 
 

-    /** Returns position in parent's array. */
-    unsigned int GetIndexInParent() const
-    {
-        return (unsigned int)m_arrIndex;
-    }
+        @remarks Default implementation converts semicolon delimited tokens into
+                child values. Only works for properties with children.

 
 

-    /** Hides or reveals the property.
-        @param hide
-            true for hide, false for reveal.
-        @param flags
-            By default changes are applied recursively. Set this paramter
-            wxPG_DONT_RECURSE to prevent this.
+                You might want to take into account that m_value is Null variant
+                if property value is unspecified (which is usually only case if
+                you explicitly enabled that sort behavior).

     */
     */

-    inline bool Hide( bool hide, int flags = wxPG_RECURSE );
+    virtual bool StringToValue( wxVariant& variant,
+                                const wxString& text,
+                                int argFlags = 0 ) const;

 
 

-    bool IsExpanded() const
-        { return (!(m_flags & wxPG_PROP_COLLAPSED) && GetChildCount()); }
+    /**
+        Converts integer (possibly a choice selection) into wxVariant value
+        appropriate for this property.

 
 

-    /** Returns true if all parents expanded.
-    */
-    bool IsVisible() const;
+        @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.

 
 

-    bool IsEnabled() const { return !(m_flags & wxPG_PROP_DISABLED); }
+        @param number
+            Integer to be translated into variant.

 
 

-    /** If property's editor is created this forces its recreation.
-        Useful in SetAttribute etc. Returns true if actually did anything.
-    */
-    bool RecreateEditor();
+        @param argFlags
+            If wxPG_FULL_VALUE is set, returns complete, storable value instead
+            of displayable one.

 
 

-    /** If property's editor is active, then update it's value.
-    */
-    void RefreshEditor();
+        @return Returns @true if resulting wxVariant value was different.

 
 

-    /** Sets an attribute for this property.
-        @param name
-        Text identifier of attribute. See @ref propgrid_property_attributes.
-        @param value
-        Value of attribute.
+        @remarks
+        - If property is not supposed to use choice or spinctrl or other editor
+          with int-based value, it is not necessary to implement this method.
+        - Default implementation simply assign given int to m_value.
+        - 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
+          property value is unspecified (which is usually only case if you
+          explicitly enabled that sort behavior).

     */
     */

-    void SetAttribute( const wxString& name, wxVariant value );
-
-    void SetAttributes( const wxPGAttributeStorage& attributes );
+    virtual bool IntToValue( wxVariant& value,
+                             int number,
+                             int argFlags = 0 ) const;
+#endif  // !defined(SWIG) || defined(CREATE_VCW)
+    /**
+        Converts property value into a text representation.

 
 

-#ifndef SWIG
-    /** Sets editor for a property.
+        @param value
+            Value to be converted.

 
 

-        @param editor
-            For builtin editors, use wxPGEditor_X, where X is builtin editor's
-            name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
-            list).
+        @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.

 
 

-        For custom editors, use pointer you received from
-        wxPropertyGrid::RegisterEditorClass().
+        @remarks Default implementation calls GenerateComposedValue().

     */
     */

-    void SetEditor( const wxPGEditor* editor )
-    {
-        m_customEditor = editor;
-    }
-#endif
+    virtual wxString ValueToString( wxVariant& value, int argFlags = 0 ) const;

 
 

-    /** Sets editor for a property.
+    /** 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.
+        @return
+        true if value was changed.

     */
     */

-    inline void SetEditor( const wxString& editorName );
+    bool SetValueFromString( const wxString& text, int flags = wxPG_PROGRAMMATIC_VALUE );

 
 

-    /** Sets cell information for given column.
-
-        Note that the property takes ownership of given wxPGCell instance.
+    /** 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.
+        @param flags
+            If has wxPG_FULL_VALUE, then the value given is a actual value and
+            not an index.
+        @return
+            True if value was changed.

     */
     */

-    void SetCell( int column, wxPGCell* cellObj );
+    bool SetValueFromInt( long value, int flags = 0 );

 
 

-    /** Changes value of a property with choices, but only
-        works if the value type is long or string. */
-    void SetChoiceSelection( int newValue, const wxPGChoiceInfo& choiceInfo );
+    /**
+        Returns size of the custom painted image in front of property.

 
 

-    /** Sets common value selected for this property. -1 for none.
+        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.
+        @remarks
+        - Default behavior 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, i.e. wxSize(-1, -1).

     */
     */

-    void SetCommonValue( int commonValue )
-    {
-        m_commonValue = commonValue;
-    }
+    virtual wxSize OnMeasureImage( int item = -1 ) const;

 
 

-    /** Sets flags from a '|' delimited string. Note that flag names are not
-        prepended with 'wxPG_PROP_'.
-    */
-    void SetFlagsFromString( const wxString& str );
+    /**
+        Events received by editor widgets are processed here.

 
 

-    /** Sets property's "is it modified?" flag. Affects children recursively.
-    */
-    void SetModifiedStatus( bool modified )
-    {
-        SetFlagRecursively(wxPG_PROP_MODIFIED, modified);
-    }
+        Note that editor class usually processes most events. Some, such as
+        button press events of TextCtrlAndButton class, can be handled here.
+        Also, if custom handling for regular events is desired, then that can
+        also be done (for example, wxSystemColourProperty custom handles
+        wxEVT_COMMAND_CHOICE_SELECTED to display colour picker dialog when
+        'custom' selection is made).

 
 

-    /** Call in OnEvent(), OnButtonClick() etc. to change the property value
-        based on user input.
+        If the event causes value to be changed, SetValueInEvent()
+        should be called to set the new value.

 
 

+        @param event
+        Associated wxEvent.
+        @return
+        Should return true if any changes in value should be reported.

         @remarks
         @remarks

-        This method is const since it doesn't actually modify value, but posts
-        given variant as pending value, stored in wxPropertyGrid.
+        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.

     */
     */

-    void SetValueInEvent( wxVariant value ) const;
+    virtual bool OnEvent( wxPropertyGrid* propgrid,
+                          wxWindow* wnd_primary,
+                          wxEvent& event );

 
     /**
 
     /**

-        Call this to set value of the property.
+        Called after value of a child property has been altered.

 
 

-        Unlike methods in wxPropertyGrid, this does not automatically update
-        the display.
+        Note that this function is usually called at the time that value of
+        this property, or given child property, is still pending for change.

 
 

-        @remarks
-        Use wxPropertyGrid::ChangePropertyValue() instead if you need to run
-        through validation process and send property change event.
+        Sample pseudo-code implementation:

 
 

-        If you need to change property value in event, based on user input, use
-        SetValueInEvent() instead.
+        @code
+        void MyProperty::ChildChanged( wxVariant& thisValue,
+                                       int childIndex,
+                                       wxVariant& childValue ) const
+        {
+            // Acquire reference to actual type of data stored in variant
+            // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros
+            // were used to create the variant class).
+            T& data = TFromVariant(thisValue);

 
 

-        @param pList
-        Pointer to list variant that contains child values. Used to indicate
-        which children should be marked as modified.
-        @param flags
-        Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR).
-    */
-    void SetValue( wxVariant value, wxVariant* pList = NULL, int flags = 0 );
+            // Copy childValue into data.
+            switch ( childIndex )
+            {
+                case 0:
+                    data.SetSubProp1( childvalue.GetLong() );
+                    break;
+                case 1:
+                    data.SetSubProp2( childvalue.GetString() );
+                    break;
+                ...
+            }
+        }
+        @endcode

 
 

-    /** Set wxBitmap in front of the value. This bitmap may be ignored
-        by custom cell renderers.
+        @param thisValue
+            Value of this property, that should be altered.
+        @param childIndex
+            Index of child changed (you can use Item(childIndex) to get).
+        @param childValue
+            Value of the child property.

     */
     */

-    void SetValueImage( wxBitmap& bmp );
+    virtual void ChildChanged( wxVariant& thisValue,
+                               int childIndex,
+                               wxVariant& childValue ) const;

 
 

-    /** If property has choices and they are not yet exclusive, new such copy
-        of them will be created.
+    /** Returns pointer to an instance of used editor.

     */
     */

-    void SetChoicesExclusive();
+    virtual const wxPGEditor* DoGetEditorClass() const;

 
 

-    void SetExpanded( bool expanded )
-    {
-        if ( !expanded ) m_flags |= wxPG_PROP_COLLAPSED;
-        else m_flags &= ~wxPG_PROP_COLLAPSED;
-    }
+    /** Returns pointer to the wxValidator that should be used
+        with the editor of this property (NULL for no validator).
+        Setting validator explicitly via SetPropertyValidator
+        will override this.

 
 

-    void SetFlag( FlagType flag ) { m_flags |= flag; }
+        In most situations, code like this should work well
+        (macros are used to maintain one actual validator instance,
+        so on the second call the function exits within the first
+        macro):

 
 

-    void SetFlagRecursively( FlagType flag, bool set );
+        @code

 
 

-    void SetHelpString( const wxString& helpString )
-    {
-        m_helpString = helpString;
-    }
+        wxValidator* wxMyPropertyClass::DoGetValidator () const
+        {
+            WX_PG_DOGETVALIDATOR_ENTRY()

 
 

-    void SetLabel( const wxString& label ) { m_label = label; }
+            wxMyValidator* validator = new wxMyValidator(...);

 
 

-    inline void SetName( const wxString& newName );
+            ... prepare validator...

 
 

-    void SetValueToUnspecified()
-    {
-        wxVariant val;  // Create NULL variant
-        SetValue(val);
-    }
+            WX_PG_DOGETVALIDATOR_EXIT(validator)
+        }

 
 

-#if wxUSE_VALIDATORS
-    /** Sets wxValidator for a property*/
-    void SetValidator( const wxValidator& validator )
-    {
-        m_validator = wxDynamicCast(validator.Clone(),wxValidator);
-    }
+        @endcode

 
 

-    /** Gets assignable version of property's validator. */
-    wxValidator* GetValidator() const
-    {
-        if ( m_validator )
-            return m_validator;
-        return DoGetValidator();
-    }
-#endif // #if wxUSE_VALIDATORS
+        @remarks
+        You can get common filename validator by returning
+        wxFileProperty::GetClassValidator(). wxDirProperty,
+        for example, uses it.
+    */
+    virtual wxValidator* DoGetValidator () const;
+
+    /**
+        Override to paint an image in front of the property value text or
+        drop-down list item (but only if wxPGProperty::OnMeasureImage is
+        overridden as well).
+
+        If property's OnMeasureImage() returns size that has height != 0 but
+        less than row height ( < 0 has special meanings), wxPropertyGrid calls
+        this method to draw a custom image in a limited area in front of the
+        editor control or value text/graphics, and if control has drop-down
+        list, then the image is drawn there as well (even in the case
+        OnMeasureImage() returned higher height than row height).
+
+        NOTE: Following applies when OnMeasureImage() returns a "flexible"
+        height ( using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable
+        height items: If rect.x is < 0, then this is a measure item call, which
+        means that dc is invalid and only thing that should be done is to set
+        paintdata.m_drawnHeight to the height of the image of item at index
+        paintdata.m_choiceItem. This call may be done even as often as once
+        every drop-down popup show.
+
+        @param dc
+            wxDC to paint on.
+        @param rect
+            Box reserved for custom graphics. Includes surrounding rectangle,
+            if any. If x is < 0, then this is a measure item call (see above).
+        @param paintdata
+            wxPGPaintData structure with much useful data.

 
 

-    /** Updates property value in case there were last minute
-        changes. If value was unspecified, it will be set to default.
-        Use only for properties that have TextCtrl-based editor.

         @remarks
         @remarks

-        If you have code similar to
-        @code
-            // Update the value in case of last minute changes
-            if ( primary && propgrid->IsEditorsValueModified() )
-                 GetEditorClass()->CopyValueFromControl( this, primary );
-        @endcode
-        in wxPGProperty::OnEvent wxEVT_COMMAND_BUTTON_CLICKED handler,
-        then replace it with call to this method.
-        @return
-        True if value changed.
+            - You can actually exceed rect width, but if you do so then
+              paintdata.m_drawnWidth must be set to the full width drawn in
+              pixels.
+            - Due to technical reasons, rect's height will be default even if
+              custom height was reported during measure call.
+            - Brush is guaranteed to be default background colour. It has been
+              already used to clear the background of area being painted. It
+              can be modified.
+            - 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 ValueToString()

     */
     */

-    bool PrepareValueForDialogEditing( wxPropertyGrid* propgrid );
+    virtual void OnCustomPaint( wxDC& dc,
+                                const wxRect& rect,
+                                wxPGPaintData& paintdata );

 
 

-#ifndef SWIG
-    /** Returns client data (void*) of a property.
+    /**
+        Returns used wxPGCellRenderer instance for given property column
+        (label=0, value=1).
+
+        Default implementation returns editor's renderer for all columns.

     */
     */

-    void* GetClientData() const
-    {
-        return m_clientData;
-    }
+    virtual wxPGCellRenderer* GetCellRenderer( int column ) const;

 
 

-    /** Sets client data (void*) of a property.
-        @remarks
-        This untyped client data has to be deleted manually.
+    /** Returns which choice is currently selected. Only applies to properties
+        which have choices.
+
+        Needs to reimplemented in derived class if property value does not
+        map directly to a choice. Integer as index, bool, and string usually do.

     */
     */

-    void SetClientData( void* clientData )
-    {
-        m_clientData = clientData;
-    }
+    virtual int GetChoiceSelection() const;

 
 

-    /** Returns client object of a property.
+    /**
+        Refresh values of child properties.
+
+        Automatically called after value is set.

     */
     */

-    void SetClientObject(wxClientData* clientObject)
-    {
-        delete m_clientObject;
-        m_clientObject = clientObject;
-    }
+    virtual void RefreshChildren();

 
 

-    /** Sets managed client object of a property.
+    /** Special handling for attributes of this property.
+
+        If returns false, then the attribute will be automatically stored in
+        m_attributes.
+
+        Default implementation simply returns false.

     */
     */

-    wxClientData *GetClientObject() const { return m_clientObject; }
-#endif
+    virtual bool DoSetAttribute( const wxString& name, wxVariant& value );

 
 

-    /** Sets new set of choices for property.
+    /** Returns value of an attribute.

 
 

-        @remarks
-        This operation clears the property value.
+        Override if custom handling of attributes is needed.
+
+        Default implementation simply return NULL variant.

     */
     */

-    bool SetChoices( wxPGChoices& choices );
+    virtual wxVariant DoGetAttribute( const wxString& name ) const;

 
 

-    /** Sets new set of choices for property.
+    /** 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
+        button is pressed).

     */
     */

-    inline bool SetChoices( const wxArrayString& labels,
-                            const wxArrayInt& values = wxArrayInt() );
+    virtual wxPGEditorDialogAdapter* GetEditorDialog() const;

 
 

-    /** Set max length of text in text editor.
+    /**
+        Called whenever validation has failed with given pending value.
+
+        @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.

     */
     */

-    inline bool SetMaxLength( int maxLen );
+    virtual void OnValidationFailure( wxVariant& pendingValue );

 
 

-    /** Call with 'false' in OnSetValue to cancel value changes after all
-        (ie. cancel 'true' returned by StringToValue() or IntToValue()).
+    /** Append a new choice to property's list of choices.

     */
     */

-    void SetWasModified( bool set = true )
+    int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE )

     {
     {

-        if ( set ) m_flags |= wxPG_PROP_WAS_MODIFIED;
-        else m_flags &= ~wxPG_PROP_WAS_MODIFIED;
+        return InsertChoice(label, wxNOT_FOUND, value);

     }
 
     }
 

-    const wxString& GetHelpString() const
+    /**
+        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

     {
     {

-        return m_helpString;
-    }
+        if ( m_flags & (wxPG_PROP_COMPOSED_VALUE|wxPG_PROP_AGGREGATE) )
+            return true;

 
 

-    void ClearFlag( FlagType flag ) { m_flags &= ~(flag); }
+        return false;
+    }

 
 

-    // Use, for example, to detect if item is inside collapsed section.
-    bool IsSomeParent( wxPGProperty* candidate_parent ) const;
+    /**
+        Deletes children of the property.
+    */
+    void DeleteChildren();

 
     /**
 
     /**

-        Adapts list variant into proper value using consecutive
-        ChildChanged-calls.
+        Removes entry from property's wxPGChoices and editor control (if it is
+        active).
+
+        If selected item is deleted, then the value is set to unspecified.

     */
     */

-    void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
+    void DeleteChoice( int index );

 
 

-    /** This is used by properties that have fixed sub-properties. */
-    void AddChild( wxPGProperty* prop );
+    /**
+        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.

 
 

-    /** Returns height of children, recursively, and
-        by taking expanded/collapsed status into account.
+        Common values are disabled by the default for all properties.
+    */
+    void EnableCommonValue( bool enable = true )
+    {
+        if ( enable ) SetFlag( wxPG_PROP_USES_COMMON_VALUE );
+        else ClearFlag( wxPG_PROP_USES_COMMON_VALUE );
+    }

 
 

-        iMax is used when finding property y-positions.
+    /**
+        Composes text from values of child properties.

     */
     */

-    int GetChildrenHeight( int lh, int iMax = -1 ) const;
+    wxString GenerateComposedValue() const
+    {
+        wxString s;
+        DoGenerateComposedValue(s);
+        return s;
+    }

 
 

-    /** Returns number of child properties */
-    unsigned int GetChildCount() const { return m_children.GetCount(); }
+    /** Returns property's label. */
+    const wxString& GetLabel() const { return m_label; }

 
 

-    /** Returns sub-property at index i. */
-    wxPGProperty* Item( size_t i ) const
-        { return (wxPGProperty*)m_children.Item(i); }
+    /** Returns property's name with all (non-category, non-root) parents. */
+    wxString GetName() const;

 
 

-    /** Returns last sub-property.
-    */
-    wxPGProperty* Last() const { return (wxPGProperty*)m_children.Last(); }
+    /**
+        Returns property's base name (ie parent's name is not added in any
+        case)
+     */
+    const wxString& GetBaseName() const { return m_name; }

 
 

-    /** Returns index of given sub-property. */
-    int Index( const wxPGProperty* p ) const
-        { return m_children.Index((wxPGProperty*)p); }
+    /** Returns read-only reference to property's list of choices.
+    */
+    const wxPGChoices& GetChoices() const
+    {
+        return m_choices;
+    }

 
 

-    /** Deletes all sub-properties. */
-    void Empty();
+    /** Returns coordinate to the top y of the property. Note that the
+        position of scrollbars is not taken into account.
+    */
+    int GetY() const;

 
 

-    // Puts correct indexes to children
-    void FixIndexesOfChildren( size_t starthere = 0 );
+    wxVariant GetValue() const
+    {
+        return DoGetValue();
+    }

 
 #ifndef SWIG
 
 #ifndef SWIG

-    // Returns wxPropertyGridPageState in which this property resides.
-    wxPropertyGridPageState* GetParentState() const { return m_parentState; }
+    /** Returns reference to the internal stored value. GetValue is preferred
+        way to get the actual value, since GetValueRef ignores DoGetValue,
+        which may override stored value.
+    */
+    wxVariant& GetValueRef()
+    {
+        return m_value;
+    }
+
+    const wxVariant& GetValueRef() const
+    {
+        return m_value;
+    }

 #endif
 
 #endif
 

-    wxPGProperty* GetItemAtY( unsigned int y,
-                              unsigned int lh,
-                              unsigned int* nextItemY ) const;
+    /** Returns text representation of property's value.

 
 

-    /** Returns (direct) child property with given name (or NULL if not found).
-    */
-    wxPGProperty* GetPropertyByName( const wxString& name ) const;
+        @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.

 
 

-#ifdef SWIG
-     %extend {
-        DocStr(GetClientData,
-               "Returns the client data object for a property", "");
-        PyObject* GetClientData() {
-            wxPyClientData* data = (wxPyClientData*)self->GetClientObject();
-            if (data) {
-                Py_INCREF(data->m_obj);
-                return data->m_obj;
-            } else {
-                Py_INCREF(Py_None);
-                return Py_None;
-            }
-        }
+        @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;

 
 

-        DocStr(SetClientData,
-               "Associate the given client data.", "");
-        void SetClientData(PyObject* clientData) {
-            wxPyClientData* data = new wxPyClientData(clientData);
-            self->SetClientObject(data);
-        }
+    /** Synonymous to GetValueAsString().
+
+        @deprecated Use GetValueAsString() instead.
+
+        @see GetValueAsString()
+    */
+    wxDEPRECATED( wxString GetValueString( int argFlags = 0 ) const );
+
+    /**
+        Returns wxPGCell of given column.
+    */
+    const wxPGCell& GetCell( unsigned int column ) const;
+
+    wxPGCell& GetCell( unsigned int column );
+
+    /** Return number of displayed common values for this property.
+    */
+    int GetDisplayedCommonValueCount() const;
+
+    wxString GetDisplayedString() const
+    {
+        return GetValueAsString(0);

     }
     }

-    %pythoncode {
-         GetClientObject = GetClientData
-         SetClientObject = SetClientData
+
+    /** Returns property grid where property lies. */
+    wxPropertyGrid* GetGrid() const;
+
+    /** Returns owner wxPropertyGrid, but only if one is currently on a page
+        displaying this property. */
+    wxPropertyGrid* GetGridIfDisplayed() const;
+
+    /** Returns highest level non-category, non-root parent. Useful when you
+        have nested wxCustomProperties/wxParentProperties.
+        @remarks
+        Thus, if immediate parent is root or category, this will return the
+        property itself.
+    */
+    wxPGProperty* GetMainParent() const;
+
+    /** Return parent of property */
+    wxPGProperty* GetParent() const { return m_parent; }
+
+    /** Returns true if property has editable wxTextCtrl when selected.
+
+        @remarks
+        Altough disabled properties do not displayed editor, they still
+        return True here as being disabled is considered a temporary
+        condition (unlike being read-only or having limited editing enabled).
+    */
+    bool IsTextEditable() const;
+
+    bool IsValueUnspecified() const
+    {
+        return m_value.IsNull();

     }
     }

-#endif

 
 

-#ifndef SWIG
+    FlagType HasFlag( FlagType flag ) const
+    {
+        return ( m_flags & flag );
+    }

 
 

-    static wxString*            sm_wxPG_LABEL;
+    /** Returns comma-delimited string of property attributes.
+    */
+    const wxPGAttributeStorage& GetAttributes() const
+    {
+        return m_attributes;
+    }

 
 

-    /** This member is public so scripting language bindings
-        wrapper code can access it freely.
+    /** Returns m_attributes as list wxVariant.

     */
     */

-    void*                       m_clientData;
+    wxVariant GetAttributesAsList() const;

 
 

-protected:
-    /** Returns text for given column.
+    FlagType GetFlags() const
+    {
+        return m_flags;
+    }
+
+    const wxPGEditor* GetEditorClass() const;
+
+    wxString GetValueType() const
+    {
+        return m_value.GetType();
+    }
+
+    /** Returns editor used for given column. NULL for no editor.

     */
     */

-    wxString GetColumnText( unsigned int col ) const;
+    const wxPGEditor* GetColumnEditor( int column ) const
+    {
+        if ( column == 1 )
+            return GetEditorClass();

 
 

-    /** Returns (direct) child property with given name (or NULL if not found),
-        with hint index.
+        return NULL;
+    }

 
 

-        @param hintIndex
-        Start looking for the child at this index.
+    /** Returns common value selected for this property. -1 for none.
+    */
+    int GetCommonValue() const
+    {
+        return m_commonValue;
+    }

 
 

-        @remarks
-        Does not support scope (ie. Parent.Child notation).
+    /** Returns true if property has even one visible child.

     */
     */

-    wxPGProperty* GetPropertyByNameWH( const wxString& name,
-                                       unsigned int hintIndex ) const;
+    bool HasVisibleChildren() const;

 
 

-    /** This is used by Insert etc. */
-    void AddChild2( wxPGProperty* prop,
-                    int index = -1,
-                    bool correct_mode = true );
+    /** Inserts a new choice to property's list of choices.
+    */
+    int InsertChoice( const wxString& label, int index, int value = wxPG_INVALID_VALUE );

 
 

-    void DoSetName(const wxString& str) { m_name = str; }
+    /**
+        Returns true if this property is actually a wxPropertyCategory.
+    */
+    bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY)?true:false; }

 
 

-    // Call for after sub-properties added with AddChild
-    void PrepareSubProperties();
+    /** Returns true if this property is actually a wxRootProperty.
+    */
+    bool IsRoot() const { return (m_parent == NULL); }

 
 

-    void SetParentalType( int flag )
+    /** Returns true if this is a sub-property. */
+    bool IsSubProperty() const

     {
     {

-        m_flags &= ~(wxPG_PROP_PROPERTY|wxPG_PROP_PARENTAL_FLAGS);
-        m_flags |= flag;
+        wxPGProperty* parent = (wxPGProperty*)m_parent;
+        if ( parent && !parent->IsCategory() )
+            return true;
+        return false;

     }
 
     }
 

-    void SetParentState( wxPropertyGridPageState* pstate )
-        { m_parentState = pstate; }
+    /** Returns last visible sub-property, recursively.
+    */
+    const wxPGProperty* GetLastVisibleSubItem() const;

 
 

-    // Call after fixed sub-properties added/removed after creation.
-    // if oldSelInd >= 0 and < new max items, then selection is
-    // moved to it.
-    void SubPropsChanged( int oldSelInd = -1 );
+    wxVariant GetDefaultValue() const;

 
 

-    int GetY2( int lh ) const;
+    int GetMaxLength() const
+    {
+        return (int) m_maxLen;
+    }

 
 

-    wxString                    m_label;
-    wxString                    m_name;
-    wxPGProperty*               m_parent;
-    wxPropertyGridPageState*        m_parentState;
+    /**
+        Determines, recursively, if all children are not unspecified.

 
 

-    wxClientData*               m_clientObject;
+        @param pendingList
+            Assumes members in this wxVariant list as pending
+            replacement values.
+    */
+    bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const;

 
 

-    // Overrides editor returned by property class
-    const wxPGEditor*           m_customEditor;
-#if wxUSE_VALIDATORS
-    // Editor is going to get this validator
-    wxValidator*                m_validator;
-#endif
-    // Show this in front of the value
-    //
-    // TODO: Can bitmap be implemented with wxPGCell?
-    wxBitmap*                   m_valueBitmap;
+    /** Updates composed values of parent non-category properties, recursively.
+        Returns topmost property updated.

 
 

-    wxVariant                   m_value;
-    wxPGAttributeStorage        m_attributes;
-    wxArrayPtrVoid              m_children;
+        @remarks
+        - Must not call SetValue() (as can be called in it).
+    */
+    wxPGProperty* UpdateParentValues();

 
 

-    // Extended cell information
-    wxArrayPtrVoid              m_cells;
+    /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
+    */
+    bool UsesAutoUnspecified() const
+    {
+        return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED)?true:false;
+    }

 
 

-    // Help shown in statusbar or help box.
-    wxString                    m_helpString;
+    wxBitmap* GetValueImage() const
+    {
+        return m_valueBitmap;
+    }

 
 

-    // Index in parent's property array.
-    unsigned int                m_arrIndex;
+    wxVariant GetAttribute( const wxString& name ) const;

 
 

-    // If not -1, then overrides m_value
-    int                         m_commonValue;
+    /**
+        Returns named attribute, as string, if found.

 
 

-    FlagType                    m_flags;
+        Otherwise defVal is returned.
+    */
+    wxString GetAttribute( const wxString& name, const wxString& defVal ) const;

 
 

-    // Maximum length (mainly for string properties). Could be in some sort of
-    // wxBaseStringProperty, but currently, for maximum flexibility and
-    // compatibility, we'll stick it here. Anyway, we had 3 excess bytes to use
-    // so short int will fit in just fine.
-    short                       m_maxLen;
+    /**
+        Returns named attribute, as long, if found.

 
 

-    // Root has 0, categories etc. at that level 1, etc.
-    unsigned char               m_depth;
+        Otherwise defVal is returned.
+    */
+    long GetAttributeAsLong( const wxString& name, long defVal ) const;

 
 

-    // m_depthBgCol indicates width of background colour between margin and item
-    // (essentially this is category's depth, if none then equals m_depth).
-    unsigned char               m_depthBgCol;
+    /**
+        Returns named attribute, as double, if found.

 
 

-    unsigned char               m_bgColIndex; // Background brush index.
-    unsigned char               m_fgColIndex; // Foreground colour index.
+        Otherwise defVal is returned.
+    */
+    double GetAttributeAsDouble( const wxString& name, double defVal ) const;

 
 

-private:
-    // Called in constructors.
-    void Init();
-    void Init( const wxString& label, const wxString& name );
-#endif // #ifndef SWIG
-};
+    unsigned int GetDepth() const { return (unsigned int)m_depth; }

 
 

-// -----------------------------------------------------------------------
+    /** 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;

 
 

-//
-// Property class declaration helper macros
-// (wxPGRootPropertyClass and wxPropertyCategory require this).
-//
+    /** Returns position in parent's array. */
+    unsigned int GetIndexInParent() const
+    {
+        return (unsigned int)m_arrIndex;
+    }

 
 

-#define WX_PG_DECLARE_DOGETEDITORCLASS \
-    virtual const wxPGEditor* DoGetEditorClass() const;
+    /** Hides or reveals the property.
+        @param hide
+            true for hide, false for reveal.
+        @param flags
+            By default changes are applied recursively. Set this paramter
+            wxPG_DONT_RECURSE to prevent this.
+    */
+    inline bool Hide( bool hide, int flags = wxPG_RECURSE );
+
+    bool IsExpanded() const
+        { return (!(m_flags & wxPG_PROP_COLLAPSED) && GetChildCount()); }
+
+    /** Returns true if all parents expanded.
+    */
+    bool IsVisible() const;
+
+    bool IsEnabled() const { return !(m_flags & wxPG_PROP_DISABLED); }
+
+    /** 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.
+    */
+    void RefreshEditor();
+
+    /** Sets an attribute for this property.
+        @param name
+        Text identifier of attribute. See @ref propgrid_property_attributes.
+        @param value
+        Value of attribute.
+    */
+    void SetAttribute( const wxString& name, wxVariant value );
+
+    void SetAttributes( const wxPGAttributeStorage& attributes );
+
+    /**
+        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 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 );

 
 #ifndef SWIG
 
 #ifndef SWIG

-    #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME) \
-        public: \
-            DECLARE_DYNAMIC_CLASS(CLASSNAME) \
-            WX_PG_DECLARE_DOGETEDITORCLASS \
-        private:
-#else
-    #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME)
+    /** Sets editor for a property.
+
+        @param editor
+            For builtin editors, use wxPGEditor_X, where X is builtin editor's
+            name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
+            list).
+
+        For custom editors, use pointer you received from
+        wxPropertyGrid::RegisterEditorClass().
+    */
+    void SetEditor( const wxPGEditor* editor )
+    {
+        m_customEditor = editor;
+    }

 #endif
 
 #endif
 

-// Implements sans constructor function. Also, first arg is class name, not
-// property name.
-#define WX_PG_IMPLEMENT_PROPERTY_CLASS_PLAIN(PROPNAME,T,EDITOR) \
-const wxPGEditor* PROPNAME::DoGetEditorClass() const \
-{ \
-    return wxPGEditor_##EDITOR; \
-}
+    /** Sets editor for a property.
+    */
+    inline void SetEditor( const wxString& editorName );

 
 

-// -----------------------------------------------------------------------
+    /**
+        Sets cell information for given column.
+    */
+    void SetCell( int column, const wxPGCell& cell );

 
 

-#ifndef SWIG
+    /** Sets common value selected for this property. -1 for none.
+    */
+    void SetCommonValue( int commonValue )
+    {
+        m_commonValue = commonValue;
+    }

 
 

-/** @class wxPGRootProperty
-    @ingroup classes
-    Root parent property.
-*/
-class WXDLLIMPEXP_PROPGRID wxPGRootProperty : public wxPGProperty
-{
-public:
-    WX_PG_DECLARE_PROPERTY_CLASS(wxPGRootProperty)
-public:
+    /** Sets flags from a '|' delimited string. Note that flag names are not
+        prepended with 'wxPG_PROP_'.
+    */
+    void SetFlagsFromString( const wxString& str );

 
 

-    /** Constructor. */
-    wxPGRootProperty();
-    virtual ~wxPGRootProperty();
+    /** Sets property's "is it modified?" flag. Affects children recursively.
+    */
+    void SetModifiedStatus( bool modified )
+    {
+        SetFlagRecursively(wxPG_PROP_MODIFIED, modified);
+    }

 
 

-    virtual bool StringToValue( wxVariant&, const wxString&, int ) const
+    /** Call in OnEvent(), OnButtonClick() etc. to change the property value
+        based on user input.
+
+        @remarks
+        This method is const since it doesn't actually modify value, but posts
+        given variant as pending value, stored in wxPropertyGrid.
+    */
+    void SetValueInEvent( wxVariant value ) const;
+
+    /**
+        Call this to set value of the property.
+
+        Unlike methods in wxPropertyGrid, this does not automatically update
+        the display.
+
+        @remarks
+        Use wxPropertyGrid::ChangePropertyValue() instead if you need to run
+        through validation process and send property change event.
+
+        If you need to change property value in event, based on user input, use
+        SetValueInEvent() instead.
+
+        @param pList
+        Pointer to list variant that contains child values. Used to indicate
+        which children should be marked as modified.
+        @param flags
+        Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR).
+    */
+    void SetValue( wxVariant value, wxVariant* pList = NULL, int flags = 0 );
+
+    /** Set wxBitmap in front of the value. This bitmap may be ignored
+        by custom cell renderers.
+    */
+    void SetValueImage( wxBitmap& bmp );
+
+    /** Sets selected choice and changes property value.
+
+        Tries to retain value type, although currently if it is not string,
+        then it is forced to integer.
+    */
+    void SetChoiceSelection( int newValue );
+
+    void SetExpanded( bool expanded )

     {
     {

-        return false;
+        if ( !expanded ) m_flags |= wxPG_PROP_COLLAPSED;
+        else m_flags &= ~wxPG_PROP_COLLAPSED;

     }
 
     }
 

-protected:
-};
+    void SetFlag( FlagType flag ) { m_flags |= flag; }

 
 

-// -----------------------------------------------------------------------
+    void SetFlagRecursively( FlagType flag, bool set );

 
 

-/** @class wxPropertyCategory
-    @ingroup classes
-    Category (caption) property.
-*/
-class WXDLLIMPEXP_PROPGRID wxPropertyCategory : public wxPGProperty
-{
-    friend class wxPropertyGrid;
-    friend class wxPropertyGridPageState;
-    WX_PG_DECLARE_PROPERTY_CLASS(wxPropertyCategory)
-public:
+    void SetHelpString( const wxString& helpString )
+    {
+        m_helpString = helpString;
+    }

 
 

-    /** Default constructor is only used in special cases. */
-    wxPropertyCategory();
+    void SetLabel( const wxString& label ) { m_label = label; }

 
 

-    wxPropertyCategory( const wxString& label,
-                        const wxString& name = wxPG_LABEL );
-    ~wxPropertyCategory();
+    inline void SetName( const wxString& newName );
+
+    /**
+        Changes what sort of parent this property is for its children.
+
+        @param flag
+            Use one of the following values: wxPG_PROP_MISC_PARENT (for generic
+            parents), wxPG_PROP_CATEGORY (for categories), or
+            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.
+    */
+    void SetParentalType( int flag )
+    {
+        m_flags &= ~(wxPG_PROP_PROPERTY|wxPG_PROP_PARENTAL_FLAGS);
+        m_flags |= flag;
+    }
+
+    void SetValueToUnspecified()
+    {
+        wxVariant val;  // Create NULL variant
+        SetValue(val);
+    }

 
 

-    int GetTextExtent( const wxWindow* wnd, const wxFont& font ) const;
+#if wxUSE_VALIDATORS
+    /** Sets wxValidator for a property*/
+    void SetValidator( const wxValidator& validator )
+    {
+        m_validator = wxDynamicCast(validator.Clone(),wxValidator);
+    }

 
 

-protected:
-    virtual wxString GetValueAsString( int argFlags ) const;
+    /** Gets assignable version of property's validator. */
+    wxValidator* GetValidator() const
+    {
+        if ( m_validator )
+            return m_validator;
+        return DoGetValidator();
+    }
+#endif // #if wxUSE_VALIDATORS

 
 

-    void SetTextColIndex( unsigned int colInd )
-        { m_capFgColIndex = (wxByte) colInd; }
-    unsigned int GetTextColIndex() const
-        { return (unsigned int) m_capFgColIndex; }
+#ifndef SWIG
+    /** Returns client data (void*) of a property.
+    */
+    void* GetClientData() const
+    {
+        return m_clientData;
+    }

 
 

-    void CalculateTextExtent( wxWindow* wnd, const wxFont& font );
+    /** Sets client data (void*) of a property.
+        @remarks
+        This untyped client data has to be deleted manually.
+    */
+    void SetClientData( void* clientData )
+    {
+        m_clientData = clientData;
+    }

 
 

-    int     m_textExtent;  // pre-calculated length of text
-    wxByte  m_capFgColIndex;  // caption text colour index
+    /** Returns client object of a property.
+    */
+    void SetClientObject(wxClientData* clientObject)
+    {
+        delete m_clientObject;
+        m_clientObject = clientObject;
+    }

 
 

-private:
-    void Init();
-};
+    /** Sets managed client object of a property.
+    */
+    wxClientData *GetClientObject() const { return m_clientObject; }
+#endif

 
 

-#endif  // !SWIG
+    /** Sets new set of choices for property.

 
 

-// -----------------------------------------------------------------------
+        @remarks
+        This operation clears the property value.
+    */
+    bool SetChoices( wxPGChoices& choices );

 
 

-#ifndef SWIG
+    /** Set max length of text in text editor.
+    */
+    inline bool SetMaxLength( int maxLen );

 
 

-/** @class wxPGChoiceEntry
-    Data of a single wxPGChoices choice.
-*/
-class WXDLLIMPEXP_PROPGRID wxPGChoiceEntry : public wxPGCell
-{
-public:
-    wxPGChoiceEntry();
-    wxPGChoiceEntry( const wxPGChoiceEntry& entry );
-    wxPGChoiceEntry( const wxString& label,
-                     int value = wxPG_INVALID_VALUE )
-        : wxPGCell(), m_value(value)
+    /** Call with 'false' in OnSetValue to cancel value changes after all
+        (ie. cancel 'true' returned by StringToValue() or IntToValue()).
+    */
+    void SetWasModified( bool set = true )

     {
     {

-        m_text = label;
+        if ( set ) m_flags |= wxPG_PROP_WAS_MODIFIED;
+        else m_flags &= ~wxPG_PROP_WAS_MODIFIED;

     }
 
     }
 

-    wxPGChoiceEntry( const wxString& label,
-                     int value,
-                     const wxBitmap& bitmap,
-                     const wxColour& fgCol = wxNullColour,
-                     const wxColour& bgCol = wxNullColour )
-        : wxPGCell(label, bitmap, fgCol, bgCol), m_value(value)
+    const wxString& GetHelpString() const

     {
     {

+        return m_helpString;

     }
 
     }
 

-    virtual ~wxPGChoiceEntry()
-    {
-    }
+    void ClearFlag( FlagType flag ) { m_flags &= ~(flag); }

 
 

-    void SetValue( int value ) { m_value = value; }
+    // Use, for example, to detect if item is inside collapsed section.
+    bool IsSomeParent( wxPGProperty* candidate_parent ) const;

 
 

-    int GetValue() const { return m_value; }
+    /**
+        Adapts list variant into proper value using consecutive
+        ChildChanged-calls.
+    */
+    void AdaptListToValue( wxVariant& list, wxVariant* value ) const;

 
 

-    bool HasValue() const { return (m_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:

 
 

-protected:
-    int m_value;
-};
+        @code
+            wxPGProperty* prop = new wxStringProperty(wxS("Property"));
+            prop->SetParentalType(wxPG_PROP_MISC_PARENT);
+            wxPGProperty* prop2 = new wxStringProperty(wxS("Property2"));
+            prop->AddChild(prop2);
+        @endcode
+    */
+    void AddChild( wxPGProperty* prop );

 
 

+    /** Returns height of children, recursively, and
+        by taking expanded/collapsed status into account.

 
 

-typedef void* wxPGChoicesId;
+        iMax is used when finding property y-positions.
+    */
+    int GetChildrenHeight( int lh, int iMax = -1 ) const;

 
 

-class WXDLLIMPEXP_PROPGRID wxPGChoicesData
-{
-    friend class wxPGChoices;
-public:
-    // Constructor sets m_refCount to 1.
-    wxPGChoicesData();
+    /** Returns number of child properties */
+    unsigned int GetChildCount() const
+    {
+        return (unsigned int) m_children.size();
+    }

 
 

-    void CopyDataFrom( wxPGChoicesData* data );
+    /** Returns sub-property at index i. */
+    wxPGProperty* Item( unsigned int i ) const
+        { return m_children[i]; }

 
 

-    // Takes ownership of 'item'
-    void Insert( int index, wxPGChoiceEntry* item )
-    {
-        wxArrayPtrVoid::iterator it;
-        if ( index == -1 )
-        {
-            it = m_items.end();
-            index = m_items.size();
-        }
-        else
-        {
-            it = m_items.begin() + index;
-        }
+    /** Returns last sub-property.
+    */
+    wxPGProperty* Last() const { return m_children.back(); }

 
 

-        // Need to fix value?
-        if ( item->GetValue() == wxPG_INVALID_VALUE )
-            item->SetValue(index);
+    /** Returns index of given child property. */
+    int Index( const wxPGProperty* p ) const;

 
 

-        m_items.insert(it, item);
-    }
+    // Puts correct indexes to children
+    void FixIndicesOfChildren( unsigned int starthere = 0 );

 
 

-    // Delete all entries
-    void Clear();
+#ifndef SWIG
+    // Returns wxPropertyGridPageState in which this property resides.
+    wxPropertyGridPageState* GetParentState() const { return m_parentState; }
+#endif

 
 

-    size_t GetCount() const { return m_items.size(); }
+    wxPGProperty* GetItemAtY( unsigned int y,
+                              unsigned int lh,
+                              unsigned int* nextItemY ) const;

 
 

-    wxPGChoiceEntry* Item( unsigned int i ) const
-    {
-        wxCHECK_MSG( i < GetCount(), NULL, "invalid index" );
+    /** Returns (direct) child property with given name (or NULL if not found).
+    */
+    wxPGProperty* GetPropertyByName( const wxString& name ) const;

 
 

-        return (wxPGChoiceEntry*) m_items[i];
-    }
+#ifdef SWIG
+     %extend {
+        DocStr(GetClientData,
+               "Returns the client data object for a property", "");
+        PyObject* GetClientData() {
+            wxPyClientData* data = (wxPyClientData*)self->GetClientObject();
+            if (data) {
+                Py_INCREF(data->m_obj);
+                return data->m_obj;
+            } else {
+                Py_INCREF(Py_None);
+                return Py_None;
+            }
+        }

 
 

-    void DecRef()
-    {
-        m_refCount--;
-        wxASSERT( m_refCount >= 0 );
-        if ( m_refCount == 0 )
-            delete this;
+        DocStr(SetClientData,
+               "Associate the given client data.", "");
+        void SetClientData(PyObject* clientData) {
+            wxPyClientData* data = new wxPyClientData(clientData);
+            self->SetClientObject(data);
+        }
+    }
+    %pythoncode {
+         GetClientObject = GetClientData
+         SetClientObject = SetClientData

     }
     }

+#endif

 
 

-private:
-    wxArrayPtrVoid  m_items;
+#ifndef SWIG

 
 

-    // So that multiple properties can use the same set
-    int             m_refCount;
+    // Returns various display-related information for given column
+    void GetDisplayInfo( unsigned int column,
+                         int choiceIndex,
+                         int flags,
+                         wxString* pString,
+                         const wxPGCell** pCell );

 
 

-    virtual ~wxPGChoicesData();
-};
+    static wxString*            sm_wxPG_LABEL;

 
 

-#define wxPGChoicesEmptyData    ((wxPGChoicesData*)NULL)
+    /** This member is public so scripting language bindings
+        wrapper code can access it freely.
+    */
+    void*                       m_clientData;

 
 

-#endif // SWIG
+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.

 
 

-/** @class wxPGChoices
+        @param firstCol
+            First column to affect.

 
 

-    Helper class for managing choices of wxPropertyGrid properties.
-    Each entry can have label, value, bitmap, text colour, and background
-    colour.
+        @param lastCol
+            Last column to affect.

 
 

-    @library{wxpropgrid}
-    @category{propgrid}
-*/
-class WXDLLIMPEXP_PROPGRID wxPGChoices
-{
-public:
-    typedef long ValArrItem;
+        @param preparedCell
+            Pre-prepared cell that is used for those which cell data
+            before this matched unmodCellData.

 
 

-    /** Default constructor. */
-    wxPGChoices()
-    {
-        Init();
-    }
+        @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).

 
 

-    /** Copy constructor. */
-    wxPGChoices( const wxPGChoices& a )
-    {
-        if ( a.m_data != wxPGChoicesEmptyData )
-        {
-            m_data = a.m_data;
-            m_data->m_refCount++;
-        }
-    }
+        @param unmodCellData
+            If cell's cell data matches this, its cell is now set to
+            preparedCell.

 
 

-    /** Constructor. */
-    wxPGChoices( const wxChar** labels, const long* values = NULL )
-    {
-        Init();
-        Set(labels,values);
-    }
+        @param ignoreWithFlags
+            Properties with any one of these flags are skipped.

 
 

-    /** Constructor. */
-    wxPGChoices( const wxArrayString& labels,
-                 const wxArrayInt& values = wxArrayInt() )
-    {
-        Init();
-        Set(labels,values);
-    }
+        @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 );

 
 

-    /** Simple interface constructor. */
-    wxPGChoices( wxPGChoicesData* data )
-    {
-        wxASSERT(data);
-        m_data = data;
-        data->m_refCount++;
-    }
+    /**
+        Makes sure m_cells has size of column+1 (or more).
+    */
+    void EnsureCells( unsigned int column );

 
 

-    /** Destructor. */
-    ~wxPGChoices()
-    {
-        Free();
-    }
+    /** 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 (ie. Parent.Child notation).
+    */
+    wxPGProperty* GetPropertyByNameWH( const wxString& name,
+                                       unsigned int hintIndex ) const;
+
+    /** This is used by Insert etc. */
+    void AddChild2( wxPGProperty* prop,
+                    int index = -1,
+                    bool correct_mode = true );

 
 

-    /**
-        Adds to current.
+    void DoGenerateComposedValue( wxString& text,
+                                  int argFlags = wxPG_VALUE_IS_CURRENT,
+                                  const wxVariantList* valueOverrides = NULL,
+                                  wxPGHashMapS2S* childResults = NULL ) const;

 
 

-        If did not have own copies, creates them now. If was empty, identical
-        to set except that creates copies.
-    */
-    void Add( const wxChar** labels, const ValArrItem* values = NULL );
+    void DoSetName(const wxString& str) { m_name = str; }

 
 

-    /** Version that works with wxArrayString. */
-    void Add( const wxArrayString& arr, const ValArrItem* values = NULL );
+    /** Deletes all sub-properties. */
+    void Empty();

 
 

-    /** Version that works with wxArrayString and wxArrayInt. */
-    void Add( const wxArrayString& arr, const wxArrayInt& arrint );
+    void InitAfterAdded( wxPropertyGridPageState* pageState,
+                         wxPropertyGrid* propgrid );

 
 

-    /** Adds single item. */
-    wxPGChoiceEntry& Add( const wxString& label,
-                          int value = wxPG_INVALID_VALUE );
+    // Removes child property with given pointer. Does not delete it.
+    void RemoveChild( wxPGProperty* p );

 
 

-    /** Adds a single item, with bitmap. */
-    wxPGChoiceEntry& Add( const wxString& label,
-                          const wxBitmap& bitmap,
-                          int value = wxPG_INVALID_VALUE );
+    void SetParentState( wxPropertyGridPageState* pstate )
+        { m_parentState = pstate; }

 
 

-    /** Adds a single item with full entry information. */
-    wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry )
-    {
-        return Insert(entry, -1);
-    }
+    // Call after fixed sub-properties added/removed after creation.
+    // if oldSelInd >= 0 and < new max items, then selection is
+    // moved to it.
+    void SubPropsChanged( int oldSelInd = -1 );

 
 

-    /** Adds single item. */
-    wxPGChoiceEntry& AddAsSorted( const wxString& label,
-                                  int value = wxPG_INVALID_VALUE );
+    int GetY2( int lh ) const;

 
 

-    void Assign( const wxPGChoices& a )
-    {
-        AssignData(a.m_data);
-    }
+    wxString                    m_label;
+    wxString                    m_name;
+    wxPGProperty*               m_parent;
+    wxPropertyGridPageState*    m_parentState;

 
 

-    void AssignData( wxPGChoicesData* data );
+    wxClientData*               m_clientObject;

 
 

-    /** Delete all choices. */
-    void Clear()
-    {
-        if ( m_data != wxPGChoicesEmptyData )
-            m_data->Clear();
-    }
+    // Overrides editor returned by property class
+    const wxPGEditor*           m_customEditor;
+#if wxUSE_VALIDATORS
+    // Editor is going to get this validator
+    wxValidator*                m_validator;
+#endif
+    // Show this in front of the value
+    //
+    // TODO: Can bitmap be implemented with wxPGCell?
+    wxBitmap*                   m_valueBitmap;

 
 

-    void EnsureData()
-    {
-        if ( m_data == wxPGChoicesEmptyData )
-            m_data = new wxPGChoicesData();
-    }
+    wxVariant                   m_value;
+    wxPGAttributeStorage        m_attributes;
+    wxArrayPGProperty           m_children;

 
 

-    /** Gets a unsigned number identifying this list. */
-    wxPGChoicesId GetId() const { return (wxPGChoicesId) m_data; };
+    // Extended cell information
+    wxVector<wxPGCell>          m_cells;

 
 

-    const wxString& GetLabel( size_t ind ) const
-    {
-        return Item(ind).GetText();
-    }
+    // Choices shown in drop-down list of editor control.
+    wxPGChoices                 m_choices;

 
 

-    size_t GetCount () const
-    {
-        wxASSERT_MSG( m_data, "When checking if wxPGChoices is valid, "
-                              "use IsOk() instead of GetCount()" );
-        return m_data->GetCount();
-    }
+    // Help shown in statusbar or help box.
+    wxString                    m_helpString;

 
 

-    int GetValue( size_t ind ) const { return Item(ind).GetValue(); }
+    // Index in parent's property array.
+    unsigned int                m_arrIndex;

 
 

-    /** Returns array of values matching the given strings. Unmatching strings
-        result in wxPG_INVALID_VALUE entry in array.
-    */
-    wxArrayInt GetValuesForStrings( const wxArrayString& strings ) const;
+    // If not -1, then overrides m_value
+    int                         m_commonValue;

 
 

-    /** Returns array of indices matching given strings. Unmatching strings
-        are added to 'unmatched', if not NULL.
-    */
-    wxArrayInt GetIndicesForStrings( const wxArrayString& strings,
-                                     wxArrayString* unmatched = NULL ) const;
+    FlagType                    m_flags;

 
 

-    /** Returns true if choices in general are likely to have values
-        (depens on that all entries have values or none has)
-    */
-    bool HasValues() const;
+    // Maximum length (mainly for string properties). Could be in some sort of
+    // wxBaseStringProperty, but currently, for maximum flexibility and
+    // compatibility, we'll stick it here. Anyway, we had 3 excess bytes to use
+    // so short int will fit in just fine.
+    short                       m_maxLen;

 
 

-    bool HasValue( unsigned int i ) const
-        { return (i < m_data->GetCount()) && m_data->Item(i)->HasValue(); }
+    // Root has 0, categories etc. at that level 1, etc.
+    unsigned char               m_depth;

 
 

-    int Index( const wxString& str ) const;
-    int Index( int val ) const;
+    // m_depthBgCol indicates width of background colour between margin and item
+    // (essentially this is category's depth, if none then equals m_depth).
+    unsigned char               m_depthBgCol;

 
 

-    /** Inserts single item. */
-    wxPGChoiceEntry& Insert( const wxString& label,
-                             int index,
-                             int value = wxPG_INVALID_VALUE );
+private:
+    // Called in constructors.
+    void Init();
+    void Init( const wxString& label, const wxString& name );
+#endif // #ifndef SWIG
+};

 
 

-    /** Inserts a single item with full entry information. */
-    wxPGChoiceEntry& Insert( const wxPGChoiceEntry& entry, int index );
+// -----------------------------------------------------------------------

 
 

-    /** Returns false if this is a constant empty set of choices,
-        which should not be modified.
-    */
-    bool IsOk() const
-    {
-        return ( m_data != wxPGChoicesEmptyData );
-    }
+//
+// Property class declaration helper macros
+// (wxPGRootPropertyClass and wxPropertyCategory require this).
+//

 
 

-    const wxPGChoiceEntry& Item( unsigned int i ) const
-    {
-        wxASSERT( IsOk() );
-        return *m_data->Item(i);
-    }
+#define WX_PG_DECLARE_DOGETEDITORCLASS \
+    virtual const wxPGEditor* DoGetEditorClass() const;

 
 

-    wxPGChoiceEntry& Item( unsigned int i )
-    {
-        wxASSERT( IsOk() );
-        return *m_data->Item(i);
-    }
+#ifndef SWIG
+    #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME) \
+        public: \
+            DECLARE_DYNAMIC_CLASS(CLASSNAME) \
+            WX_PG_DECLARE_DOGETEDITORCLASS \
+        private:
+#else
+    #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME)
+#endif

 
 

-    /** Removes count items starting at position nIndex. */
-    void RemoveAt(size_t nIndex, size_t count = 1);
+// Implements sans constructor function. Also, first arg is class name, not
+// property name.
+#define WX_PG_IMPLEMENT_PROPERTY_CLASS_PLAIN(PROPNAME,T,EDITOR) \
+const wxPGEditor* PROPNAME::DoGetEditorClass() const \
+{ \
+    return wxPGEditor_##EDITOR; \
+}
+
+// -----------------------------------------------------------------------

 
 #ifndef SWIG
 
 #ifndef SWIG

-    /** Does not create copies for itself. */
-    void Set( const wxChar** labels, const long* values = NULL )
-    {
-        Free();
-        Add(labels,values);
-    }

 
 

-    /** Version that works with wxArrayString.
-        TODO: Deprecate this.
-    */
-    void Set( wxArrayString& arr, const long* values = (const long*) NULL )
-    {
-        Free();
-        Add(arr,values);
-    }
-#endif // SWIG
+/** @class wxPGRootProperty
+    @ingroup classes
+    Root parent property.
+*/
+class WXDLLIMPEXP_PROPGRID wxPGRootProperty : public wxPGProperty
+{
+public:
+    WX_PG_DECLARE_PROPERTY_CLASS(wxPGRootProperty)
+public:

 
 

-    /** Version that works with wxArrayString and wxArrayInt. */
-    void Set( const wxArrayString& labels,
-              const wxArrayInt& values = wxArrayInt() )
-    {
-        Free();
-        if ( &values )
-            Add(labels,values);
-        else
-            Add(labels);
-    }
+    /** Constructor. */
+    wxPGRootProperty( const wxString& name = wxS("<Root>") );
+    virtual ~wxPGRootProperty();

 
 

-    // Creates exclusive copy of current choices
-    void SetExclusive()
+    virtual bool StringToValue( wxVariant&, const wxString&, int ) const

     {
     {

-        if ( m_data->m_refCount != 1 )
-        {
-            wxPGChoicesData* data = new wxPGChoicesData();
-            data->CopyDataFrom(m_data);
-            Free();
-            m_data = data;
-        }
+        return false;

     }
 
     }
 

-    // Returns data, increases refcount.
-    wxPGChoicesData* GetData()
-    {
-        wxASSERT( m_data->m_refCount != 0xFFFFFFF );
-        m_data->m_refCount++;
-        return m_data;
-    }
+protected:
+};

 
 

-    // Returns plain data ptr - no refcounting stuff is done.
-    wxPGChoicesData* GetDataPtr() const { return m_data; }
+// -----------------------------------------------------------------------

 
 

-    // Changes ownership of data to you.
-    wxPGChoicesData* ExtractData()
-    {
-        wxPGChoicesData* data = m_data;
-        m_data = wxPGChoicesEmptyData;
-        return data;
-    }
+/** @class wxPropertyCategory
+    @ingroup classes
+    Category (caption) property.
+*/
+class WXDLLIMPEXP_PROPGRID wxPropertyCategory : public wxPGProperty
+{
+    friend class wxPropertyGrid;
+    friend class wxPropertyGridPageState;
+    WX_PG_DECLARE_PROPERTY_CLASS(wxPropertyCategory)
+public:

 
 

-    wxArrayString GetLabels() const;
+    /** Default constructor is only used in special cases. */
+    wxPropertyCategory();

 
 

-#ifndef SWIG
-    void operator= (const wxPGChoices& a)
-    {
-        AssignData(a.m_data);
-    }
+    wxPropertyCategory( const wxString& label,
+                        const wxString& name = wxPG_LABEL );
+    ~wxPropertyCategory();

 
 

-    wxPGChoiceEntry& operator[](unsigned int i)
-    {
-        return Item(i);
-    }
+    int GetTextExtent( const wxWindow* wnd, const wxFont& font ) const;

 
 

-    const wxPGChoiceEntry& operator[](unsigned int i) const
-    {
-        return Item(i);
-    }
+    virtual wxString ValueToString( wxVariant& value, int argFlags ) const;

 
 protected:
 
 protected:

-    wxPGChoicesData*    m_data;
+    void SetTextColIndex( unsigned int colInd )
+        { m_capFgColIndex = (wxByte) colInd; }
+    unsigned int GetTextColIndex() const
+        { return (unsigned int) m_capFgColIndex; }
+
+    void CalculateTextExtent( wxWindow* wnd, const wxFont& font );
+
+    int     m_textExtent;  // pre-calculated length of text
+    wxByte  m_capFgColIndex;  // caption text colour index

 
 

+private:

     void Init();
     void Init();

-    void Free();
-#endif  // !SWIG

 };
 
 };
 

-inline bool wxPGProperty::SetChoices( const wxArrayString& labels,
-                                      const wxArrayInt& values )
-{
-    wxPGChoices chs(labels, values);
-    return SetChoices(chs);
-}
+#endif  // !SWIG

 
 // -----------------------------------------------------------------------
 
 
 // -----------------------------------------------------------------------