abandon attempts to make wxAnyStrPtr behave as bool: user-defined logical operators...

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

diff --git a/interface/wx/propgrid/property.h b/interface/wx/propgrid/property.h
index fbd27ec03303a479aba17279825cd10c7803d936..2c4b99c16f320ba5063f501c3727bd15f525d59e 100644 (file)
--- a/interface/wx/propgrid/property.h
+++ b/interface/wx/propgrid/property.h
@@ -46,6 +46,11 @@
 */
 #define wxPG_ATTR_INLINE_HELP               wxS("InlineHelp")
 
 */
 #define wxPG_ATTR_INLINE_HELP               wxS("InlineHelp")
 

+/** Universal, wxArrayString. Set to enable auto-completion in any
+    wxTextCtrl-based property editor.
+*/
+#define wxPG_ATTR_AUTOCOMPLETE              wxS("AutoComplete")
+

 /** wxBoolProperty specific, int, default 0. When 1 sets bool property to
     use checkbox instead of choice.
 */
 /** wxBoolProperty specific, int, default 0. When 1 sets bool property to
     use checkbox instead of choice.
 */


@@ -115,7 +120,8 @@
 #define wxPG_DATE_FORMAT                    wxS("DateFormat")
 
 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
 #define wxPG_DATE_FORMAT                    wxS("DateFormat")
 
 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default

-    is wxDP_DEFAULT | wxDP_SHOWCENTURY.
+    is wxDP_DEFAULT | wxDP_SHOWCENTURY. Using wxDP_ALLOWNONE will enable
+    better unspecified value support in the editor.

 */
 #define wxPG_DATE_PICKER_STYLE              wxS("PickerStyle")
 
 */
 #define wxPG_DATE_PICKER_STYLE              wxS("PickerStyle")
 


@@ -128,6 +134,11 @@
 */
 #define wxPG_ATTR_SPINCTRL_WRAP             wxS("Wrap")
 
 */
 #define wxPG_ATTR_SPINCTRL_WRAP             wxS("Wrap")
 

+/** SpinCtrl editor, bool. If @true, value can also by changed by moving
+    mouse when left mouse button is being pressed.
+*/
+#define wxPG_ATTR_SPINCTRL_MOTIONSPIN       wxS("MotionSpin")
+

 /** wxMultiChoiceProperty, int. If 0, no user strings allowed. If 1, user strings
     appear before list strings. If 2, user strings appear after list string.
 */
 /** wxMultiChoiceProperty, int. If 0, no user strings allowed. If 1, user strings
     appear before list strings. If 2, user strings appear after list string.
 */


@@ -187,6 +198,9 @@
 
     Simple string property. wxPG_STRING_PASSWORD attribute may be used
     to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl.
 
     Simple string property. wxPG_STRING_PASSWORD attribute may be used
     to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl.

+    wxPG_ATTR_AUTOCOMPLETE attribute may be used to enable auto-completion
+    (use a wxArrayString value), and is also supported by any property that
+    happens to use a wxTextCtrl-based editor.

 
     @remarks wxStringProperty has a special trait: if it has value of
             "<composed>", and also has child properties, then its displayed
 
     @remarks wxStringProperty has a special trait: if it has value of
             "<composed>", and also has child properties, then its displayed


@@ -305,6 +319,7 @@
     string wxDateTime::Format uses (altough default is recommended as it is
     locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window
     style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY).
     string wxDateTime::Format uses (altough default is recommended as it is
     locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window
     style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY).

+    Using wxDP_ALLOWNONE will enable better unspecified value support.

 
     @subsection wxEditEnumProperty
 
 
     @subsection wxEditEnumProperty
 


@@ -489,8 +504,11 @@ public:
             variant << value;
             SetValue(variant);
 
             variant << value;
             SetValue(variant);
 

-            // If has private child properties then create them here. For example:
-            //     AddChild( new wxStringProperty( "Subprop 1", wxPG_LABEL, value.GetSubProp1() ) );
+            // If has private child properties then create them here.
+            // For example:
+            //     AddPrivateChild( new wxStringProperty("Subprop 1",
+            //                                           wxPG_LABEL,
+            //                                           value.GetSubProp1()));

         }
 
         @endcode
         }
 
         @endcode


@@ -847,6 +865,15 @@ public:
     */
     virtual wxPGEditorDialogAdapter* GetEditorDialog() const;
 
     */
     virtual wxPGEditorDialogAdapter* GetEditorDialog() const;
 

+    /**
+        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.
+    */
+    virtual void OnValidationFailure( wxVariant& pendingValue );
+

     /**
         Append a new choice to property's list of choices.
 
     /**
         Append a new choice to property's list of choices.
 


@@ -863,23 +890,22 @@ public:
     int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE );
 
     /**
     int AddChoice( const wxString& label, int 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:
+        Adds a private child property.

 
 

-        @code
-            wxPGProperty* prop = new wxStringProperty(wxS("Property"));
-            prop->SetParentalType(wxPG_PROP_MISC_PARENT);
-            wxPGProperty* prop2 = new wxStringProperty(wxS("Property2"));
-            prop->AddChild(prop2);
-        @endcode
+        @deprecated Use AddPrivateChild() instead.
+
+        @see AddPrivateChild()
+    */
+    wxDEPRECATED( void AddChild( wxPGProperty* prop ) );
+
+    /**
+        Adds a private child property. If you use this instead of
+        wxPropertyGridInterface::Insert() or
+        wxPropertyGridInterface::AppendIn(), then property's parental
+        type will automatically be set up to wxPG_PROP_AGGREGATE. In other
+        words, all properties of this property will become private.

     */
     */

-    void AddChild( wxPGProperty* property );
+    void AddPrivateChild( wxPGProperty* prop );

 
     /**
         Adapts list variant into proper value using consecutive
 
     /**
         Adapts list variant into proper value using consecutive


@@ -887,6 +913,19 @@ public:
     */
     void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
 
     */
     void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
 

+    /**
+        Use this member function to add independent (ie. regular) children to
+        a property.
+
+        @return Appended childProperty.
+
+        @remarks wxPropertyGrid is not automatically refreshed by this
+                function.
+
+        @see InsertChild(), AddPrivateChild()
+    */
+    wxPGProperty* AppendChild( wxPGProperty* childProperty );
+

     /**
         Determines, recursively, if all children are not unspecified.
 
     /**
         Determines, recursively, if all children are not unspecified.
 


@@ -902,6 +941,11 @@ public:
     */
     bool AreChildrenComponents() const;
 
     */
     bool AreChildrenComponents() const;
 

+    /**
+        Deletes children of the property.
+    */
+    void DeleteChildren();
+

     /**
         Removes entry from property's wxPGChoices and editor control (if it is active).
 
     /**
         Removes entry from property's wxPGChoices and editor control (if it is active).
 


@@ -1127,6 +1171,19 @@ public:
     */
     int Index( const wxPGProperty* p ) const;
 
     */
     int Index( const wxPGProperty* p ) const;
 

+    /**
+        Use this member function to add independent (ie. regular) children to
+        a property.
+
+        @return Inserted childProperty.
+
+        @remarks wxPropertyGrid is not automatically refreshed by this
+                function.
+
+        @see AppendChild(), AddPrivateChild()
+    */
+    wxPGProperty* InsertChild( int index, wxPGProperty* childProperty );
+

     /**
         Inserts a new choice to property's list of choices.
 
     /**
         Inserts a new choice to property's list of choices.
 


@@ -1252,12 +1309,6 @@ public:
     */
     bool SetChoices( wxPGChoices& choices );
 
     */
     bool SetChoices( wxPGChoices& choices );
 

-    /**
-        If property has choices and they are not yet exclusive, new such copy
-        of them will be created.
-    */
-    void SetChoicesExclusive();
-

     /**
         Sets client data (void*) of a property.
 
     /**
         Sets client data (void*) of a property.
 


@@ -1315,11 +1366,7 @@ public:
             wxPG_PROP_AGGREGATE (for derived property classes with private
             children).
 
             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.
+        @remarks You generally do not need to call this function.

     */
     void SetParentalType( int flag );
 
     */
     void SetParentalType( int flag );
 


@@ -1356,10 +1403,11 @@ public:
             Pointer to list variant that contains child values. Used to indicate
             which children should be marked as modified. Usually you just use @NULL.
         @param flags
             Pointer to list variant that contains child values. Used to indicate
             which children should be marked as modified. Usually you just use @NULL.
         @param flags

-            Use wxPG_SETVAL_REFRESH_EDITOR to update editor control, if it
-            was selected.
+            wxPG_SETVAL_REFRESH_EDITOR is set by default, to refresh editor
+            and redraw properties.

     */
     */

-    void SetValue( wxVariant value, wxVariant* pList = NULL, int flags = 0 );
+    void SetValue( wxVariant value, wxVariant* pList = NULL,
+                   int flags = wxPG_SETVAL_REFRESH_EDITOR );

 
     /**
         Set wxBitmap in front of the value. This bitmap may be ignored
 
     /**
         Set wxBitmap in front of the value. This bitmap may be ignored


@@ -1404,7 +1452,15 @@ public:
     @class wxPGChoices
 
     Helper class for managing choices of wxPropertyGrid properties.
     @class wxPGChoices
 
     Helper class for managing choices of wxPropertyGrid properties.

-    Each entry can have label, value, bitmap, text colour, and background colour.
+    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.
+
+    @remarks If you do not specify value for entry, index is used.

 
     @library{wxpropgrid}
     @category{propgrid}
 
     @library{wxpropgrid}
     @category{propgrid}


@@ -1419,7 +1475,10 @@ public:
     */
     wxPGChoices();
 
     */
     wxPGChoices();
 

-    /** Copy constructor. */
+    /**
+        Copy constructor, uses reference counting. To create a real copy,
+        use Copy() member function instead.
+    */

     wxPGChoices( const wxPGChoices& a );
 
     /** Constructor. */
     wxPGChoices( const wxPGChoices& a );
 
     /** Constructor. */


@@ -1460,7 +1519,8 @@ public:
     wxPGChoiceEntry& AddAsSorted( const wxString& label, int value = wxPG_INVALID_VALUE );
 
     /**
     wxPGChoiceEntry& AddAsSorted( const wxString& label, int value = wxPG_INVALID_VALUE );
 
     /**

-        Assigns data from another set of choices.
+        Assigns choices data, using reference counting. To create a real copy,
+        use Copy() member function instead.

     */
     void Assign( const wxPGChoices& a );
 
     */
     void Assign( const wxPGChoices& a );
 


@@ -1474,6 +1534,11 @@ public:
     */
     void Clear();
 
     */
     void Clear();
 

+    /**
+        Returns a real copy of the choices.
+    */
+    wxPGChoices Copy() const;
+

     /**
         Returns labe of item.
     */
     /**
         Returns labe of item.
     */


@@ -1561,7 +1626,7 @@ public:
     /**
         Creates exclusive copy of current choices.
     */
     /**
         Creates exclusive copy of current choices.
     */

-    void SetExclusive();
+    void AllocExclusive();

 
     /**
         Returns array of choice labels.
 
     /**
         Returns array of choice labels.