X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1802a91dec8bf45fbcfc89332c97dd63461aa4c6..b2bd89e35c8ef81331727b1a88ef43bd42d59efb:/interface/wx/propgrid/property.h

diff --git a/interface/wx/propgrid/property.h b/interface/wx/propgrid/property.h
index cd267eb3fd..a0639cb8dd 100644
--- a/interface/wx/propgrid/property.h
+++ b/interface/wx/propgrid/property.h
@@ -2,7 +2,7 @@
 // Name:        property.h
 // Purpose:     interface of wxPGProperty
 // Author:      wxWidgets team
-// RCS-ID:      $Id:
+// RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
@@ -473,33 +473,60 @@ public:
     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
-        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;
 
     /**
-        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
-        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.
-        - 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;
 
@@ -961,7 +988,7 @@ public:
 
     /**
         Returns highest level non-category, non-root parent. Useful when you
-        have nested wxCustomProperties/wxParentProperties.
+        have nested properties with children.
 
         @remarks If immediate parent is root or category, this will return the
                 property itself.