Tweaked wxPGProperty::StringToValue() and IntToValue() docs

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56062 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/include/wx/propgrid/property.h b/include/wx/propgrid/property.h
index d394098c82bb56af10c855299448a2c07911def2..dc4947eded833e27c1e5deb0c566617768ec9347 100644 (file)
--- a/include/wx/propgrid/property.h
+++ b/include/wx/propgrid/property.h
@@ -1016,9 +1016,15 @@ public:
                                 wxPGValidationInfo& validationInfo ) const;
 
     /**
                                 wxPGValidationInfo& validationInfo ) const;
 
     /**

-        Converts 'text' into proper value 'variant'.
-        Returns true if new (different than m_value) value could be interpreted
-        from the text.
+        Converts text into wxVariant value appropriate for this property.
+
+        @param variant
+            On function entry this is the old value (should not be wxNullVariant
+            in normal cases). Translated value must be assigned back to it.
+
+        @param text
+            Text to be translated into variant.
+

         @param argFlags
             If wxPG_FULL_VALUE is set, returns complete, storable value instead
             of displayable one (they may be different).
         @param argFlags
             If wxPG_FULL_VALUE is set, returns complete, storable value instead
             of displayable one (they may be different).


@@ -1026,25 +1032,36 @@ public:
             composite property string value (as generated by GetValueAsString()
             called with this same flag).
 
             composite property string value (as generated by GetValueAsString()
             called with this same flag).
 

-        @remarks
-        Default implementation converts semicolon delimited tokens into child
-        values. Only works for properties with children.
+        @return Returns @true if resulting wxVariant value was different.
+
+        @remarks Default implementation converts semicolon delimited tokens into
+                child values. Only works for properties with children.
+
+                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).

     */
     virtual bool StringToValue( wxVariant& variant,
                                 const wxString& text,
                                 int argFlags = 0 ) const;
 
     /**
     */
     virtual bool StringToValue( wxVariant& variant,
                                 const wxString& text,
                                 int argFlags = 0 ) const;
 
     /**

-        Converts 'number' (including choice selection) into proper value
-        'variant'.
+        Converts integer (possibly a choice selection) into wxVariant value
+        appropriate for this property.

 
 

-        Returns true if new (different than m_value) value could be interpreted
-        from the integer.
+        @param variant
+            On function entry this is the old value (should not be wxNullVariant
+            in normal cases). Translated value must be assigned back to it.
+
+        @param number
+            Integer to be translated into variant.

 
         @param argFlags
             If wxPG_FULL_VALUE is set, returns complete, storable value instead
             of displayable one.
 
 
         @param argFlags
             If wxPG_FULL_VALUE is set, returns complete, storable value instead
             of displayable one.
 

+        @return Returns @true if resulting wxVariant value was different.
+

         @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.
         @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.


@@ -1052,6 +1069,9 @@ public:
         - If property uses choice control, and displays a dialog on some choice
           items, then it is preferred to display that dialog in IntToValue
           instead of OnEvent.
         - 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).

     */
     virtual bool IntToValue( wxVariant& value,
                              int number,
     */
     virtual bool IntToValue( wxVariant& value,
                              int number,

diff --git a/interface/wx/propgrid/property.h b/interface/wx/propgrid/property.h
index 2f58ba9e76a34f3a0cf0849a577c05cd12fd7b00..d02fe49fe7f4066412b5987888169b5f6fa7c417 100644 (file)
--- a/interface/wx/propgrid/property.h
+++ b/interface/wx/propgrid/property.h
@@ -473,33 +473,60 @@ public:
     virtual bool ValidateValue( wxVariant& value, wxPGValidationInfo& validationInfo ) const;
 
     /**
     virtual bool ValidateValue( wxVariant& value, wxPGValidationInfo& validationInfo ) const;
 
     /**

-        Converts 'text' into proper value 'variant'. Returns true if new (different than
-        m_value) value could be interpreted from the text.
+        Converts text into wxVariant value appropriate for this property.
+
+        @param variant
+            On function entry this is the old value (should not be wxNullVariant
+            in normal cases). Translated value must be assigned back to it.
+
+        @param text
+            Text to be translated into variant.
+

         @param argFlags
         @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).
+            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).

 
 

-        @remarks
-        Default implementation converts semicolon delimited tokens into child values. Only
-        works for properties with children.
+        @return Returns @true if resulting wxVariant value was different.
+
+        @remarks Default implementation converts semicolon delimited tokens into
+                child values. Only works for properties with children.
+
+                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).

     */
     virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags = 0 ) const;
 
     /**
     */
     virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags = 0 ) const;
 
     /**

-        Converts 'number' (including choice selection) into proper value 'variant'.
-        Returns true if new (different than m_value) value could be interpreted from the integer.
+        Converts integer (possibly a choice selection) into wxVariant value
+        appropriate for this property.
+
+        @param variant
+            On function entry this is the old value (should not be wxNullVariant
+            in normal cases). Translated value must be assigned back to it.
+
+        @param number
+            Integer to be translated into variant.
+

         @param argFlags
         @param argFlags

-        If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable one.
+            If wxPG_FULL_VALUE is set, returns complete, storable value instead
+            of displayable one.
+
+        @return Returns @true if resulting wxVariant value was different.

 
         @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.
 
         @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.
+        - 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).

     */
     virtual bool IntToValue( wxVariant& value, int number, int argFlags = 0 ) const;
 
     */
     virtual bool IntToValue( wxVariant& value, int number, int argFlags = 0 ) const;