]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/propgrid/property.h
wxSocket::Initialize() and Shutdown() are for main thread only.
[wxWidgets.git] / interface / wx / propgrid / property.h
index 5cd1d564a1ac8eb40982e55d029bbf8afd040d34..fb4c7bb7b843138f17a9e2df1f093dea7b20c49e 100644 (file)
 */
 #define wxPG_ATTR_INLINE_HELP               wxS("InlineHelp")
 
-/** wxBoolProperty specific, int, default 0. When 1 sets bool property to
-    use checkbox instead of choice.
+/** Universal, wxArrayString. Set to enable auto-completion in any
+    wxTextCtrl-based property editor.
+*/
+#define wxPG_ATTR_AUTOCOMPLETE              wxS("AutoComplete")
+
+/** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
+    Default value is False.
+
+    When set to True, bool property will use check box instead of a
+    combo box as its editor control. If you set this attribute
+    for a wxFlagsProperty, it is automatically applied to child
+    bool properties.
 */
 #define wxPG_BOOL_USE_CHECKBOX              wxS("UseCheckbox")
 
-/** wxBoolProperty specific, int, default 0. When 1 sets bool property value
-    to cycle on double click (instead of showing the popup listbox).
+/** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
+    Default value is False.
+
+    Set to True for the bool property to cycle value on double click
+    (instead of showing the popup listbox). If you set this attribute
+    for a wxFlagsProperty, it is automatically applied to child
+    bool properties.
 */
 #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING  wxS("UseDClickCycling")
 
 #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")
 
 
     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
 
     @subsection wxFlagsProperty
 
-    Represents a bit set that fits in a long integer. wxBoolProperty sub-properties
-    are created for editing individual bits. Textctrl is created to manually edit
-    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 wxPGProperty::SetChoices() - otherwise they will not get updated
-    properly.
+    Represents a bit set that fits in a long integer. wxBoolProperty sub-
+    properties are created for editing individual bits. Textctrl is created to
+    manually edit the flags as a text; a continous sequence of spaces, commas
+    and semicolons are considered as a flag id separator.
+
+    <b>Note:</b> When changing "choices" (ie. flag labels) of wxFlagsProperty,
+    you will need to use wxPGProperty::SetChoices() - otherwise they will not
+    get updated properly.
+
+    wxFlagsProperty supports the same attributes as wxBoolProperty.
 
     @subsection wxArrayStringProperty
 
     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
 
         class MyProperty : public wxPGProperty
         {
         public:
-            // All arguments of ctor must have a default value -
+            // Default constructor
+            MyProperty() { }
+
+            // All arguments of this ctor must have a default value -
             // use wxPG_LABEL for label and name
             MyProperty( const wxString& label = wxPG_LABEL,
                         const wxString& name = wxPG_LABEL,
                         const wxString& value = wxEmptyString )
+                : wxPGProperty(label, name)
             {
                 // m_value is wxVariant
                 m_value = value;
@@ -486,7 +513,7 @@ public:
         @code
 
         MyProperty( const wxString& label, const wxString& name, const T& value )
-            : wxPGProperty()
+            : wxPGProperty(label, name)
         {
             // Generally recommended way to set the initial value
             // (as it should work in pretty much 100% of cases).
@@ -494,8 +521,11 @@ public:
             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
@@ -672,18 +702,25 @@ public:
     virtual bool OnEvent( wxPropertyGrid* propgrid, wxWindow* wnd_primary, wxEvent& event );
 
     /**
-        Called after value of a child property has been altered. Note that this function is
-        usually called at the time that value of this property, or given child property, is
-        still pending for change.
+        Called after value of a child property has been altered. Must return
+        new value of the whole property (after any alterations warrented by
+        child's new value).
+
+        Note that this function is usually called at the time that value of
+        this property, or given child property, is still pending for change,
+        and as such, result of GetValue() or m_value should not be relied
+        on.
 
         Sample pseudo-code implementation:
 
         @code
-        void MyProperty::ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const
+        wxVariant MyProperty::ChildChanged( wxVariant& thisValue,
+                                            int childIndex,
+                                            wxVariant& childValue ) const
         {
             // Acquire reference to actual type of data stored in variant
-            // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros were used to create
-            // the variant class).
+            // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros
+            // were used to create the variant class).
             T& data = TFromVariant(thisValue);
 
             // Copy childValue into data.
@@ -697,17 +734,28 @@ public:
                     break;
                 ...
             }
+
+            // Return altered data
+            return data;
         }
         @endcode
 
         @param thisValue
-            Value of this property, that should be altered.
+            Value of this property. Changed value should be returned (in
+            previous versions of wxPropertyGrid it was only necessary to
+            write value back to this argument).
         @param childIndex
-            Index of child changed (you can use Item(childIndex) to get).
+            Index of child changed (you can use Item(childIndex) to get
+            child property).
         @param childValue
-            Value of the child property.
+            (Pending) value of the child property.
+
+        @return
+            Modified value of the whole property.
     */
-    virtual void ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const;
+    virtual wxVariant ChildChanged( wxVariant& thisValue,
+                                    int childIndex,
+                                    wxVariant& childValue ) const;
 
     /**
         Returns pointer to an instance of used editor.
@@ -852,6 +900,15 @@ public:
     */
     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.
 
@@ -868,23 +925,22 @@ public:
     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
@@ -892,6 +948,19 @@ public:
     */
     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.
 
@@ -959,9 +1028,23 @@ public:
 
     /**
         Returns wxPGCell of given column.
+
+        @remarks const version of this member function returns 'default'
+                 wxPGCell object if the property itself didn't hold
+                 cell data.
     */
     const wxPGCell& GetCell( unsigned int column ) const;
 
+    /**
+        Returns wxPGCell of given column, creating one if necessary.
+    */
+    wxPGCell& GetCell( unsigned int column );
+
+    /**
+        Returns wxPGCell of given column, creating one if necessary.
+    */
+    wxPGCell& GetOrCreateCell( unsigned int column );
+
     /**
         Returns number of child properties.
     */
@@ -1137,6 +1220,19 @@ public:
     */
     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.
 
@@ -1262,12 +1358,6 @@ public:
     */
     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.
 
@@ -1287,6 +1377,14 @@ public:
     */
     void SetChoiceSelection( int newValue );
 
+    /** Set default value of a property. Synonymous to
+
+        @code
+            SetAttribute("DefaultValue", value);
+        @endcode
+    */
+    void SetDefaultValue( wxVariant& value );
+
     /**
         Sets property's help string, which is shown, for example, in
         wxPropertyGridManager's description text box.
@@ -1325,11 +1423,7 @@ public:
             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 );
 
@@ -1366,10 +1460,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
-            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
@@ -1414,7 +1509,15 @@ public:
     @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}
@@ -1429,7 +1532,10 @@ public:
     */
     wxPGChoices();
 
-    /** Copy constructor. */
+    /**
+        Copy constructor, uses reference counting. To create a real copy,
+        use Copy() member function instead.
+    */
     wxPGChoices( const wxPGChoices& a );
 
     /** Constructor. */
@@ -1470,7 +1576,8 @@ public:
     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 );
 
@@ -1484,6 +1591,11 @@ public:
     */
     void Clear();
 
+    /**
+        Returns a real copy of the choices.
+    */
+    wxPGChoices Copy() const;
+
     /**
         Returns labe of item.
     */
@@ -1512,6 +1624,10 @@ public:
     wxArrayInt GetIndicesForStrings( const wxArrayString& strings,
                                      wxArrayString* unmatched = NULL ) const;
 
+    /** Returns property at given virtual y coordinate.
+    */
+    wxPGProperty* GetItemAtY( unsigned int y ) const;
+
     /**
         Returns @true if item at given index has a valid value;
     */
@@ -1571,7 +1687,7 @@ public:
     /**
         Creates exclusive copy of current choices.
     */
-    void SetExclusive();
+    void AllocExclusive();
 
     /**
         Returns array of choice labels.