X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/258ccb95f58bd7a9f4d56db50b3f948b76911706..bc35c728671d1220e38ddd02d4bc77cf63b6c437:/interface/wx/propgrid/property.h?ds=inline

diff --git a/interface/wx/propgrid/property.h b/interface/wx/propgrid/property.h
index 65e494b41b..59f37bdc1b 100644
--- a/interface/wx/propgrid/property.h
+++ b/interface/wx/propgrid/property.h
@@ -10,36 +10,10 @@
 #define wxNullProperty  ((wxPGProperty*)NULL)
 
 
-/** wxPGPaintData
-
-    Contains information relayed to property's OnCustomPaint.
-*/
-struct wxPGPaintData
-{
-    /** wxPropertyGrid. */
-    const wxPropertyGrid*   m_parent;
-
-    /** Normally -1, otherwise index to drop-down list item that has to be drawn. */
-    int                     m_choiceItem;
-
-    /** Set to drawn width in OnCustomPaint (optional). */
-    int                     m_drawnWidth;
-
-    /** In a measure item call, set this to the height of item at m_choiceItem index. */
-    int                     m_drawnHeight;   
-};
-
-
-// Structure for relaying choice/list info.
-struct wxPGChoiceInfo
-{
-    wxPGChoices*    m_choices;
-};
-
-
 /** @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers
 
-    wxPGProperty::SetAttribute() and wxPropertyGridInterfaces::SetPropertyAttribute()
+    wxPGProperty::SetAttribute() and
+    wxPropertyGridInterface::SetPropertyAttribute()
     accept one of these as attribute name argument .
 
     You can use strings instead of constants. However, some of these
@@ -164,11 +138,6 @@ struct wxPGChoiceInfo
 */
 #define wxPG_COLOUR_ALLOW_CUSTOM            wxS("AllowCustom")
 
-/** First attribute id that is guaranteed not to be used built-in
-    properties.
-*/
-//#define wxPG_USER_ATTRIBUTE                 192
-
 /** @}
 */
 
@@ -281,7 +250,8 @@ struct wxPGChoiceInfo
     the flags as a text; a continous sequence of spaces, commas and semicolons
     is considered as a flag id separator.
     <b>Note: </b> When changing "choices" (ie. flag labels) of wxFlagsProperty, you
-    will need to use SetPropertyChoices - otherwise they will not get updated properly.
+    will need to use wxPGProperty::SetChoices() - otherwise they will not get updated
+    properly.
 
     @subsection wxArrayStringProperty
 
@@ -406,18 +376,22 @@ struct wxPGChoiceInfo
     they are only really needed if you need to use wxRTTI with your
     property class.
 
-    You can change the 'value type' of a property by simply assigning different type
-    of variant with SetValue. <b>It is mandatory to implement wxVariantData class
-    for all data types used as property values.</b> Also, it is further recommended
-    to derive your class from wxPGVariantData, like this:
+    You can change the 'value type' of a property by simply assigning different
+    type of variant with SetValue. <b>It is mandatory to implement
+    wxVariantData class for all data types used as property values.</b>
+    You can use macros declared in wxPropertyGrid headers. For instance:
 
     @code
         // In header file:
-        // (replace DECL with required data declaration, wxEMPTY_PARAMETER_VALUE if none)
-        WX_PG_DECLARE_VARIANT_DATA(wxPGVariantMyDataClass, MyDataClass, DECL)
+        // (If you need to have export declaration, use version of macros
+        // with _EXPORTED postfix)
+        WX_PG_DECLARE_VARIANT_DATA(MyDataClass)
 
         // In sources file:
-        WX_PG_IMPLEMENT_VARIANT_DATA(wxPGVariantMyDataClass, MyDataClass)
+        WX_PG_IMPLEMENT_VARIANT_DATA(MyDataClass)
+
+        // Or, if you don't have valid == operator:
+        WX_PG_IMPLEMENT_VARIANT_DATA_DUMMY_EQ(MyDataClass)
     @endcode
 
     @library{wxpropgrid}
@@ -654,17 +628,6 @@ public:
     */
     virtual wxValidator* DoGetValidator () const;
 
-    /** Returns current value's index to the choice control. 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.
-        @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.
-    */
-    virtual int GetChoiceInfo( wxPGChoiceInfo* choiceinfo );
-
     /** 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).
 
@@ -688,7 +651,23 @@ public:
         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.
+        wxPGPaintData structure with much useful data about painted item.
+        @code
+        struct wxPGPaintData
+        {
+            // wxPropertyGrid.
+            const wxPropertyGrid*   m_parent;
+
+            // Normally -1, otherwise index to drop-down list item that has to be drawn.
+            int                     m_choiceItem;
+
+            // Set to drawn width in OnCustomPaint (optional).
+            int                     m_drawnWidth;
+
+            // In a measure item call, set this to the height of item at m_choiceItem index
+            int                     m_drawnHeight;
+        };
+        @endcode
 
         @remarks
             - You can actually exceed rect width, but if you do so then paintdata.m_drawnWidth
@@ -710,6 +689,14 @@ public:
     */
     virtual wxPGCellRenderer* GetCellRenderer( int column ) const;
 
+    /** 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.
+    */
+    virtual int GetChoiceSelection() const;
+
     /** Refresh values of child properties. Automatically called after value is set.
     */
     virtual void RefreshChildren();
@@ -739,14 +726,6 @@ public:
     */
     virtual wxPGEditorDialogAdapter* GetEditorDialog() const;
 
-    /** Adds entry to property's wxPGChoices and editor control (if it is active).
-        Returns index of item added.
-    */
-    int AppendChoice( const wxString& label, int value = wxPG_INVALID_VALUE )
-    {
-        return InsertChoice(label,-1,value);
-    }
-
     /** Returns wxPGCell of given column, NULL if none. If valid
         object is returned, caller will gain its ownership.
     */
@@ -760,6 +739,20 @@ public:
         return cell;
     }
 
+    /** Append a new choice to property's list of choices.
+
+        @param label
+            Label for added choice.
+
+        @param value
+            Value for new choice. Do not specify if you wish this
+            to equal choice index.
+
+        @return
+            Index to added choice.
+    */
+    int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE );
+
     /** 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).
     */
@@ -800,12 +793,10 @@ public:
     /** Returns property's base name (ie. parent's name is not added in any case) */
     const wxString& GetBaseName() const { return m_name; }
 
-    wxPGChoices& GetChoices();
-
+    /** Returns read-only reference to property's list of choices.
+    */
     const wxPGChoices& GetChoices() const;
 
-    const wxPGChoiceEntry* GetCurrentChoice() const;
-
     /** Returns coordinate to the top y of the property. Note that the
         position of scrollbars is not taken into account.
     */
@@ -847,10 +838,6 @@ public:
         return (wxPGCell*) m_cells[column];
     }
 
-    unsigned int GetChoiceCount() const;
-
-    wxString GetChoiceString( unsigned int index );
-
     /** Return number of displayed common values for this property.
     */
     int GetDisplayedCommonValueCount() const;
@@ -941,8 +928,17 @@ public:
     */
     bool HasVisibleChildren() const;
 
-    /** Adds entry to property's wxPGChoices and editor control (if it is active).
-        Returns index of item added.
+    /** Inserts a new choice to property's list of choices.
+
+        @param label
+            Text for new choice
+
+        @param index
+            Insertion position. Use wxNOT_FOUND to append.
+
+        @param value
+            Value for new choice. Do not specify if you wish this
+            to equal choice index.
     */
     int InsertChoice( const wxString& label, int index, int value = wxPG_INVALID_VALUE );
 
@@ -1090,9 +1086,17 @@ public:
     */
     void SetCell( int column, wxPGCell* cellObj );
 
-    /** 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 );
+    /** If property has choices and they are not yet exclusive, new such copy
+        of them will be created.
+    */
+    void SetChoicesExclusive();
+
+    /** 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 );
 
     /** Sets common value selected for this property. -1 for none.
     */
@@ -1145,11 +1149,6 @@ public:
     */
     void SetValueImage( wxBitmap& bmp );
 
-    /** If property has choices and they are not yet exclusive, new such copy
-        of them will be created.
-    */
-    void SetChoicesExclusive();
-
     void SetExpanded( bool expanded )
     {
         if ( !expanded ) m_flags |= wxPG_PROP_COLLAPSED;
@@ -1284,7 +1283,7 @@ public:
 
     /** Returns height of children, recursively, and
         by taking expanded/collapsed status into account.
-        
+
         iMax is used when finding property y-positions.
     */
     int GetChildrenHeight( int lh, int iMax = -1 ) const;