Make this header SWIG-safe

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

diff --git a/include/wx/propgrid/property.h b/include/wx/propgrid/property.h
index 28535bb6445768c83a752bf33298726378ed12da..864227349de2df97c5ff7229e3e9dedff064023e 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")
 


@@ -624,6 +639,8 @@ wxPG_PROP_CLASS_SPECIFIC_2          = 0x00100000
 */
 
 // Redefine attribute macros to use cached strings
 */
 
 // Redefine attribute macros to use cached strings

+#undef wxPG_ATTR_DEFAULT_VALUE
+#define wxPG_ATTR_DEFAULT_VALUE           wxPGGlobalVars->m_strDefaultValue

 #undef wxPG_ATTR_MIN
 #define wxPG_ATTR_MIN                     wxPGGlobalVars->m_strMin
 #undef wxPG_ATTR_MAX
 #undef wxPG_ATTR_MIN
 #define wxPG_ATTR_MIN                     wxPGGlobalVars->m_strMin
 #undef wxPG_ATTR_MAX


@@ -737,6 +754,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 +776,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 +878,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 +890,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 +993,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()


@@ -1033,9 +1060,8 @@ class WXDLLIMPEXP_PROPGRID wxPGProperty : public wxObject
     friend class wxPropertyGridPageState;
     friend class wxPropertyGridPopulator;
     friend class wxStringProperty;  // Proper "<composed>" support requires this
     friend class wxPropertyGridPageState;
     friend class wxPropertyGridPopulator;
     friend class wxStringProperty;  // Proper "<composed>" support requires this

-#ifndef SWIG
+

     DECLARE_ABSTRACT_CLASS(wxPGProperty)
     DECLARE_ABSTRACT_CLASS(wxPGProperty)

-#endif

 public:
     typedef wxUint32 FlagType;
 
 public:
     typedef wxUint32 FlagType;
 


@@ -1062,11 +1088,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 +1447,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 )


@@ -1647,6 +1680,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 );


@@ -1810,6 +1856,14 @@ public:
     void SetTextColour( const wxColour& colour,
                         bool recursively = false );
 
     void SetTextColour( const wxColour& colour,
                         bool recursively = false );
 

+    /** Set default value of a property. Synonymous to
+
+        @code
+            SetAttribute("DefaultValue", value);
+        @endcode
+    */
+    void SetDefaultValue( wxVariant& value );
+

 #ifndef SWIG
     /** Sets editor for a property.
 
 #ifndef SWIG
     /** Sets editor for a property.
 


@@ -1878,26 +1932,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,


@@ -1911,8 +1960,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 )


@@ -1928,16 +1991,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 )
     {


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

+#if wxPG_COMPATIBILITY_1_4

     /**
     /**

-        Adds a child property. If you use this instead of
+        Adds a private child property.
+
+        @deprecated Use AddPrivateChild() instead.
+
+        @see AddPrivateChild()
+    */
+    wxDEPRECATED( void AddChild( wxPGProperty* prop ) );
+#endif
+
+    /**
+        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.


@@ -2079,47 +2147,30 @@ public:
     // 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; }
 #endif
 
 #ifndef SWIG
     // Returns wxPropertyGridPageState in which this property resides.
     wxPropertyGridPageState* GetParentState() const { return m_parentState; }
 #endif
 

+#ifndef SWIG

     wxPGProperty* GetItemAtY( unsigned int y,
                               unsigned int lh,
                               unsigned int* nextItemY ) const;
     wxPGProperty* GetItemAtY( unsigned int y,
                               unsigned int lh,
                               unsigned int* nextItemY ) const;

+#endif
+
+    /** Returns property at given virtual y coordinate.
+    */
+    wxPGProperty* GetItemAtY( unsigned int y ) const;

 
     /** Returns (direct) child property with given name (or NULL if not found).
     */
     wxPGProperty* GetPropertyByName( const wxString& name ) const;
 
 
     /** Returns (direct) child property with given name (or NULL if not found).
     */
     wxPGProperty* GetPropertyByName( const wxString& name ) const;
 

-#ifdef SWIG
-     %extend {
-        DocStr(GetClientData,
-               "Returns the client data object for a property", "");
-        PyObject* GetClientData() {
-            wxPyClientData* data = (wxPyClientData*)self->GetClientObject();
-            if (data) {
-                Py_INCREF(data->m_obj);
-                return data->m_obj;
-            } else {
-                Py_INCREF(Py_None);
-                return Py_None;
-            }
-        }
-
-        DocStr(SetClientData,
-               "Associate the given client data.", "");
-        void SetClientData(PyObject* clientData) {
-            wxPyClientData* data = new wxPyClientData(clientData);
-            self->SetClientObject(data);
-        }
-    }
-    %pythoncode {
-         GetClientObject = GetClientData
-         SetClientObject = SetClientData
-    }
-#endif
-

 #ifndef SWIG
 
     // Returns various display-related information for given column
 #ifndef SWIG
 
     // Returns various display-related information for given column


@@ -2194,9 +2245,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,


@@ -2214,6 +2265,8 @@ protected:
     // Removes child property with given pointer. Does not delete it.
     void RemoveChild( wxPGProperty* p );
 
     // 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; }
 


@@ -2222,8 +2275,6 @@ protected:
     // moved to it.
     void SubPropsChanged( int oldSelInd = -1 );
 
     // moved to it.
     void SubPropsChanged( int oldSelInd = -1 );
 

-    void UpdateControl( wxWindow* editorWnd );
-

     int GetY2( int lh ) const;
 
     wxString                    m_label;
     int GetY2( int lh ) const;
 
     wxString                    m_label;


@@ -2328,7 +2379,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