fix default argument values

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

diff --git a/interface/wx/propgrid/property.h b/interface/wx/propgrid/property.h
index 65e494b41b9954b3306d42498b036536d931c95a..59f37bdc1b5b092442743acd94a845e021466c1f 100644 (file)
--- a/interface/wx/propgrid/property.h
+++ b/interface/wx/propgrid/property.h
@@ -10,36 +10,10 @@
 #define wxNullProperty  ((wxPGProperty*)NULL)
 
 
 #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
 
 /** @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
     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")
 
 */
 #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
     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
 
 
     @subsection wxArrayStringProperty
 


@@ -406,18 +376,22 @@ struct wxPGChoiceInfo
     they are only really needed if you need to use wxRTTI with your
     property class.
 
     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:
 
     @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:
 
         // 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}
     @endcode
 
     @library{wxpropgrid}


@@ -654,17 +628,6 @@ public:
     */
     virtual wxValidator* DoGetValidator () const;
 
     */
     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).
 
     /** 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
         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
 
         @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;
 
     */
     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();
     /** Refresh values of child properties. Automatically called after value is set.
     */
     virtual void RefreshChildren();


@@ -739,14 +726,6 @@ public:
     */
     virtual wxPGEditorDialogAdapter* GetEditorDialog() const;
 
     */
     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.
     */
     /** 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;
     }
 
         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).
     */
     /** 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; }
 
     /** 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 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.
     */
     /** 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];
     }
 
         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;
     /** Return number of displayed common values for this property.
     */
     int GetDisplayedCommonValueCount() const;


@@ -941,8 +928,17 @@ public:
     */
     bool HasVisibleChildren() const;
 
     */
     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 );
 
     */
     int InsertChoice( const wxString& label, int index, int value = wxPG_INVALID_VALUE );
 


@@ -1090,9 +1086,17 @@ public:
     */
     void SetCell( int column, wxPGCell* cellObj );
 
     */
     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.
     */
 
     /** Sets common value selected for this property. -1 for none.
     */


@@ -1145,11 +1149,6 @@ public:
     */
     void SetValueImage( wxBitmap& bmp );
 
     */
     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;
     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.
 
     /** 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;
         iMax is used when finding property y-positions.
     */
     int GetChildrenHeight( int lh, int iMax = -1 ) const;