don't use GetParent() in GetParentForModalDialog() itself as it can be called before...

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

diff --git a/include/wx/propgrid/property.h b/include/wx/propgrid/property.h
index 7c329b7d1c4fca1d7980a27f773f37431cc0d586..d8dcf5363f1fe2f62d95bb34e6649ed10c855fe2 100644 (file)
--- a/include/wx/propgrid/property.h
+++ b/include/wx/propgrid/property.h
@@ -515,13 +515,28 @@ wxPG_PROP_CLASS_SPECIFIC_2          = 0x00100000
 */
 #define wxPG_ATTR_INLINE_HELP               wxS("InlineHelp")
 
 */
 #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")
 
 */
 #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_BOOL_USE_DOUBLE_CLICK_CYCLING  wxS("UseDClickCycling")
 


@@ -737,6 +752,11 @@ private:
     Helper class for managing choices of wxPropertyGrid properties.
     Each entry can have label, value, bitmap, text colour, and background
     colour.
     Helper class for managing choices of wxPropertyGrid properties.
     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.
 
 
     @remarks If you do not specify value for entry, index is used.
 


@@ -754,7 +774,10 @@ public:
         Init();
     }
 
         Init();
     }
 

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

     wxPGChoices( const wxPGChoices& a )
     {
         if ( a.m_data != wxPGChoicesEmptyData )
     wxPGChoices( const wxPGChoices& a )
     {
         if ( a.m_data != wxPGChoicesEmptyData )


@@ -853,6 +876,10 @@ public:
     wxPGChoiceEntry& AddAsSorted( const wxString& label,
                                   int value = wxPG_INVALID_VALUE );
 
     wxPGChoiceEntry& AddAsSorted( const wxString& label,
                                   int value = wxPG_INVALID_VALUE );
 

+    /**
+        Assigns choices data, using reference counting. To create a real copy,
+        use Copy() member function instead.
+    */

     void Assign( const wxPGChoices& a )
     {
         AssignData(a.m_data);
     void Assign( const wxPGChoices& a )
     {
         AssignData(a.m_data);


@@ -861,10 +888,17 @@ public:
     void AssignData( wxPGChoicesData* data );
 
     /** Delete all choices. */
     void AssignData( wxPGChoicesData* data );
 
     /** Delete all choices. */

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

     {
     {

-        if ( m_data != wxPGChoicesEmptyData )
-            m_data->Clear();
+        wxPGChoices dst;
+        dst.EnsureData();
+        dst.m_data->CopyDataFrom(m_data);
+        return dst;

     }
 
     void EnsureData()
     }
 
     void EnsureData()


@@ -957,16 +991,7 @@ public:
     }
 
     // Creates exclusive copy of current choices
     }
 
     // Creates exclusive copy of current choices

-    void SetExclusive()
-    {
-        if ( m_data->m_refCount != 1 )
-        {
-            wxPGChoicesData* data = new wxPGChoicesData();
-            data->CopyDataFrom(m_data);
-            Free();
-            m_data = data;
-        }
-    }
+    void AllocExclusive();

 
     // Returns data, increases refcount.
     wxPGChoicesData* GetData()
 
     // Returns data, increases refcount.
     wxPGChoicesData* GetData()


@@ -1062,11 +1087,9 @@ public:
             // If has private child properties then create them here. Also
             // set flag that indicates presence of private children. E.g.:
             //
             // If has private child properties then create them here. Also
             // set flag that indicates presence of private children. E.g.:
             //

-            //     SetParentalType(wxPG_PROP_AGGREGATE);
-            //
-            //     AddChild( new wxStringProperty( "Subprop 1",
-            //                                     wxPG_LABEL,
-            //                                     value.GetSubProp1() ) );
+            //     AddPrivateChild( new wxStringProperty("Subprop 1",
+            //                                           wxPG_LABEL,
+            //                                           value.GetSubProp1() ) );

         }
 
         @endcode
         }
 
         @endcode


@@ -1423,6 +1446,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.
     */
     int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE )
     /** Append a new choice to property's list of choices.
     */
     int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE )


@@ -1443,6 +1475,11 @@ public:
         return false;
     }
 
         return false;
     }
 

+    /**
+        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).


@@ -1545,8 +1582,6 @@ public:
     */
     wxDEPRECATED( wxString GetValueString( int argFlags = 0 ) const );
 
     */
     wxDEPRECATED( wxString GetValueString( int argFlags = 0 ) const );
 

-    void UpdateControl( wxWindow* primary );
-

     /**
         Returns wxPGCell of given column.
     */
     /**
         Returns wxPGCell of given column.
     */


@@ -1644,6 +1679,19 @@ public:
     */
     bool HasVisibleChildren() const;
 
     */
     bool HasVisibleChildren() 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 AddPrivateChild()
+    */
+    wxPGProperty* InsertChild( int index, wxPGProperty* childProperty );
+

     /** Inserts a new choice to property's list of choices.
     */
     int InsertChoice( const wxString& label, int index, int value = wxPG_INVALID_VALUE );
     /** Inserts a new choice to property's list of choices.
     */
     int InsertChoice( const wxString& label, int index, int value = wxPG_INVALID_VALUE );


@@ -1875,26 +1923,21 @@ public:
         SetValueInEvent() instead.
 
         @param pList
         SetValueInEvent() instead.
 
         @param pList

-        Pointer to list variant that contains child values. Used to indicate
-        which children should be marked as modified.
+            Pointer to list variant that contains child values. Used to
+            indicate which children should be marked as modified.
+

         @param flags
         @param flags

-        Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR).
+            Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR, which is
+            enabled by default).

     */
     */

-    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
         by custom cell renderers.
     */
     void SetValueImage( wxBitmap& bmp );
 
 
     /** Set wxBitmap in front of the value. This bitmap may be ignored
         by custom cell renderers.
     */
     void SetValueImage( wxBitmap& bmp );
 

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

     /** Sets selected choice and changes property value.
 
         Tries to retain value type, although currently if it is not string,
     /** Sets selected choice and changes property value.
 
         Tries to retain value type, although currently if it is not string,


@@ -1908,8 +1951,22 @@ public:
         else m_flags &= ~wxPG_PROP_COLLAPSED;
     }
 
         else m_flags &= ~wxPG_PROP_COLLAPSED;
     }
 

+    /**
+        Sets given property flag(s).
+    */

     void SetFlag( FlagType flag ) { m_flags |= flag; }
 
     void SetFlag( FlagType flag ) { m_flags |= flag; }
 

+    /**
+        Sets or clears given property flag(s).
+    */
+    void ChangeFlag( FlagType flag, bool set )
+    {
+        if ( set )
+            m_flags |= flag;
+        else
+            m_flags &= ~flag;
+    }
+

     void SetFlagRecursively( FlagType flag, bool set );
 
     void SetHelpString( const wxString& helpString )
     void SetFlagRecursively( FlagType flag, bool set );
 
     void SetHelpString( const wxString& helpString )


@@ -1925,16 +1982,12 @@ public:
         Changes what sort of parent this property is for its children.
 
         @param flag
         Changes what sort of parent this property is for its children.
 
         @param flag

-            Use one of the following values: wxPG_PROP_MISC_PARENT (for generic
-            parents), wxPG_PROP_CATEGORY (for categories), or
+            Use one of the following values: wxPG_PROP_MISC_PARENT (for
+            generic parents), wxPG_PROP_CATEGORY (for categories), or

             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 )
     {


@@ -2030,24 +2083,33 @@ public:
     */
     void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
 
     */
     void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
 

+#if wxPG_COMPATIBILITY_1_4
+    /**
+        Adds a private child property.
+
+        @deprecated Use AddPrivateChild() instead.
+
+        @see AddPrivateChild()
+    */
+    wxDEPRECATED( void AddChild( wxPGProperty* prop ) );
+#endif
+

     /**
     /**

-        Adds a child property. If you use this instead of
+        Adds a private child property. If you use this instead of

         wxPropertyGridInterface::Insert() or
         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:
+        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 AddPrivateChild( wxPGProperty* prop );

 
 

-        @code
-            wxPGProperty* prop = new wxStringProperty(wxS("Property"));
-            prop->SetParentalType(wxPG_PROP_MISC_PARENT);
-            wxPGProperty* prop2 = new wxStringProperty(wxS("Property2"));
-            prop->AddChild(prop2);
-        @endcode
+    /**
+        Appends a new child property.

     */
     */

-    void AddChild( wxPGProperty* prop );
+    wxPGProperty* AppendChild( wxPGProperty* prop )
+    {
+        return InsertChild(-1, prop);
+    }

 
     /** Returns height of children, recursively, and
         by taking expanded/collapsed status into account.
 
     /** Returns height of children, recursively, and
         by taking expanded/collapsed status into account.


@@ -2073,12 +2135,14 @@ public:
     /** Returns index of given child property. */
     int Index( const wxPGProperty* p ) const;
 
     /** Returns index of given child property. */
     int Index( const wxPGProperty* p ) const;
 

-    /** Deletes all sub-properties. */
-    void Empty();
-

     // Puts correct indexes to children
     void FixIndicesOfChildren( unsigned int starthere = 0 );
 
     // Puts correct indexes to children
     void FixIndicesOfChildren( unsigned int starthere = 0 );
 

+    /**
+        Converts image width into full image offset, with margins.
+    */
+    int GetImageOffset( int imageWidth ) const;
+

 #ifndef SWIG
     // Returns wxPropertyGridPageState in which this property resides.
     wxPropertyGridPageState* GetParentState() const { return m_parentState; }
 #ifndef SWIG
     // Returns wxPropertyGridPageState in which this property resides.
     wxPropertyGridPageState* GetParentState() const { return m_parentState; }


@@ -2194,9 +2258,9 @@ protected:
                                        unsigned int hintIndex ) const;
 
     /** This is used by Insert etc. */
                                        unsigned int hintIndex ) const;
 
     /** This is used by Insert etc. */

-    void AddChild2( wxPGProperty* prop,
-                    int index = -1,
-                    bool correct_mode = true );
+    void DoAddChild( wxPGProperty* prop,
+                     int index = -1,
+                     bool correct_mode = true );

 
     void DoGenerateComposedValue( wxString& text,
                                   int argFlags = wxPG_VALUE_IS_CURRENT,
 
     void DoGenerateComposedValue( wxString& text,
                                   int argFlags = wxPG_VALUE_IS_CURRENT,


@@ -2205,12 +2269,17 @@ protected:
 
     void DoSetName(const wxString& str) { m_name = str; }
 
 
     void DoSetName(const wxString& str) { m_name = str; }
 

+    /** Deletes all sub-properties. */
+    void Empty();
+

     void InitAfterAdded( wxPropertyGridPageState* pageState,
                          wxPropertyGrid* propgrid );
 
     // Removes child property with given pointer. Does not delete it.
     void RemoveChild( wxPGProperty* p );
 
     void InitAfterAdded( wxPropertyGridPageState* pageState,
                          wxPropertyGrid* propgrid );
 
     // Removes child property with given pointer. Does not delete it.
     void RemoveChild( wxPGProperty* p );
 

+    void DoPreAddChild( int index, wxPGProperty* prop );
+

     void SetParentState( wxPropertyGridPageState* pstate )
         { m_parentState = pstate; }
 
     void SetParentState( wxPropertyGridPageState* pstate )
         { m_parentState = pstate; }
 


@@ -2323,7 +2392,7 @@ public:
 public:
 
     /** Constructor. */
 public:
 
     /** Constructor. */

-    wxPGRootProperty();
+    wxPGRootProperty( const wxString& name = wxS("<Root>") );

     virtual ~wxPGRootProperty();
 
     virtual bool StringToValue( wxVariant&, const wxString&, int ) const
     virtual ~wxPGRootProperty();
 
     virtual bool StringToValue( wxVariant&, const wxString&, int ) const