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 372e6d401e33df9e119938ee594ef99886cb2c3f..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.
 */


@@ -193,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


@@ -496,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


@@ -879,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


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


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


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


@@ -1336,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 );
 


@@ -1377,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


@@ -1425,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}


@@ -1440,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. */


@@ -1481,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 );
 


@@ -1495,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.
     */


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