X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1621f192d95b44c5909a788b8f1fe9e9c381df72..c29c95fe24973b94fd724db767193171ca7c513d:/interface/wx/propgrid/propgridiface.h

diff --git a/interface/wx/propgrid/propgridiface.h b/interface/wx/propgrid/propgridiface.h
index 5d350892f5..dba072c5e5 100644
--- a/interface/wx/propgrid/propgridiface.h
+++ b/interface/wx/propgrid/propgridiface.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxPGProperty
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 // -----------------------------------------------------------------------
@@ -91,6 +91,12 @@ public:
         @return Returns @true if successful or if there was no selection. May
                fail if validation was enabled and active editor had invalid
                value.
+
+        @remarks In wxPropertyGrid 1.4, this member function used to send
+                 wxPG_EVT_SELECTED. In wxWidgets 2.9 and later, it no longer
+                 does that.
+
+        @see wxPropertyGrid::SelectProperty()
     */
     bool ClearSelection( bool validation = false);
 
@@ -129,16 +135,26 @@ public:
     bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
 
     /**
-        Deletes a property.
+        Removes and deletes a property and any children.
 
-        @remarks This functions deselects selected property, if any. Validation
-                failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie.
-                selection is cleared even if editor had invalid value.
+        @param id
+            Pointer or name of a property.
+
+        @remarks If you delete a property in a wxPropertyGrid event
+                 handler, the actual deletion is postponed until the next
+                 idle event.
+
+                 This functions deselects selected property, if any.
+                 Validation failure option wxPG_VFB_STAY_IN_PROPERTY is not
+                 respected, ie. selection is cleared even if editor had
+                 invalid value.
     */
     void DeleteProperty( wxPGPropArg id );
 
     /**
         Disables a property.
+
+        @see EnableProperty(), wxPGProperty::Enable()
     */
     bool DisableProperty( wxPGPropArg id );
 
@@ -150,12 +166,15 @@ public:
     bool EditorValidate();
 
     /**
-        Enables or disables property.
+        Enables or disables property. Disabled property usually appears as
+        having grey text.
 
         @param id
             Name or pointer to a property.
         @param enable
             If @false, property is disabled instead.
+
+        @see wxPGProperty::Enable()
     */
     bool EnableProperty( wxPGPropArg id, bool enable = true );
 
@@ -186,6 +205,13 @@ public:
     */
     bool ExpandAll( bool expand = true );
 
+    /**
+        Returns auto-resize proportion of the given column.
+
+        @see SetColumnProportion()
+    */
+    int GetColumnProportion( unsigned int column ) const;
+
     /**
         Returns id of first child of given property.
 
@@ -205,8 +231,12 @@ public:
             is used.
 
         @beginWxPythonOnly
-        <b>wxPython Note:</b> Instead of ++ operator, use Next() method, and
-        instead of * operator, use GetProperty() method.
+        Instead of ++ operator, use Next() method, and instead of * operator,
+        use GetProperty() method. There is also GetPyIterator() method (which
+        takes the same arguments but instead returns a pythonic iterator),
+        @c Properties attribute which is an iterator over all non-category,
+        non-private properties, and finally @c Items attribute which is an
+        iterator over all items except private child properties.
         @endWxPythonOnly
     */
     wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT,
@@ -228,8 +258,12 @@ public:
             iteration will instead begin from bottommost valid item.
 
         @beginWxPythonOnly
-        <b>wxPython Note:</b> Instead of ++ operator, use Next() method, and
-        instead of * operator, use GetProperty() method.
+        Instead of ++ operator, use Next() method, and instead of * operator,
+        use GetProperty() method. There is also GetPyIterator() method (which
+        takes the same arguments but instead returns a pythonic iterator),
+        @c Properties attribute which is an iterator over all non-category,
+        non-private properties, and finally @c Items attribute which is an
+        iterator over all items except private child properties.
         @endWxPythonOnly
     */
     wxPropertyGridIterator GetIterator( int flags, int startPos );
@@ -245,7 +279,12 @@ public:
     wxPGProperty* GetFirst( int flags = wxPG_ITERATE_ALL );
 
     /**
-        Returns id of property with given name (case-sensitive).
+        Returns pointer to a property with given name (case-sensitive).
+        If there is no property with such name, @NULL pointer is returned.
+
+        @remarks Properties which have non-category, non-root parent
+                 cannot be accessed globally by their name. Instead, use
+                 "<property>.<subproperty>" instead of "<subproperty>".
     */
     wxPGProperty* GetProperty( const wxString& name ) const;
 
@@ -296,7 +335,12 @@ public:
     wxPGProperty* GetPropertyByLabel( const wxString& label ) const;
 
     /**
-        Returns property with given name. @NULL if none found.
+        Returns pointer to a property with given name (case-sensitive).
+        If there is no property with such name, @NULL pointer is returned.
+
+        @remarks Properties which have non-category, non-root parent
+                 cannot be accessed globally by their name. Instead, use
+                 "<property>.<subproperty>" instead of "<subproperty>".
     */
     wxPGProperty* GetPropertyByName( const wxString& name ) const;
 
@@ -402,7 +446,20 @@ public:
     wxVariant GetPropertyValues( const wxString& listname = wxEmptyString,
                                  wxPGProperty* baseparent = NULL, long flags = 0 ) const;
 
-    /** Returns currently selected property. */
+    /**
+        Returns list of currently selected properties.
+
+        @remarks wxArrayPGProperty should be compatible with std::vector API.
+    */
+    const wxArrayPGProperty& GetSelectedProperties() const;
+
+    /**
+        Returns currently selected property. NULL if none.
+
+        @remarks When wxPG_EX_MULTIPLE_SELECTION extra style is used, this
+                 member function returns the focused property, that is the
+                 one which can have active editor.
+    */
     wxPGProperty* GetSelection() const;
 
     /**
@@ -413,8 +470,14 @@ public:
         @param flags
             See @ref propgrid_iterator_flags.
 
-        <b>wxPython Note:</b> Instead of ++ operator, use Next() method, and
-            instead of * operator, use GetProperty() method.
+        @beginWxPythonOnly
+        Instead of ++ operator, use Next() method, and instead of * operator,
+        use GetProperty() method. There is also GetPyVIterator() method (which
+        takes the same arguments but instead returns a pythonic iterator),
+        @c Properties attribute which is an iterator over all non-category,
+        non-private properties, and finally @c Items attribute which is an
+        iterator over all items except private child properties.
+        @endWxPythonOnly
     */
     virtual wxPGVIterator GetVIterator( int flags ) const;
 
@@ -522,6 +585,11 @@ public:
     */
     bool IsPropertyModified( wxPGPropArg id ) const;
 
+    /**
+        Returns true if property is selected.
+    */
+    virtual bool IsPropertySelected( wxPGPropArg id ) const;
+
     /**
         Returns @true if property is shown (ie. HideProperty() with @true not
         called for it).
@@ -547,6 +615,21 @@ public:
     */
     static void RegisterAdditionalEditors();
 
+    /**
+        Removes a property. Does not delete the property object, but
+        instead returns it.
+
+        @param id
+            Pointer or name of a property.
+
+        @remarks Removed property cannot have any children.
+
+                 Also, if you remove property in a wxPropertyGrid event
+                 handler, the actual removal is postponed until the next
+                 idle event.
+    */
+    wxPGProperty* RemoveProperty( wxPGPropArg id );
+
     /**
         Replaces property with id with newly created one. For example,
         this code replaces existing property named "Flags" with one that
@@ -634,6 +717,20 @@ public:
     static void SetBoolChoices( const wxString& trueChoice,
                                 const wxString& falseChoice );
 
+    /**
+        Set proportion of a auto-stretchable column. wxPG_SPLITTER_AUTO_CENTER
+        window style needs to be used to indicate that columns are auto-
+        resizable.
+
+        @returns Returns @false on failure.
+
+        @remarks You should call this for individual pages of
+                 wxPropertyGridManager (if used).
+
+        @see GetColumnProportion()
+    */
+    bool SetColumnProportion( unsigned int column, int proportion );
+
     /**
         Sets an attribute for this property.
 
@@ -669,13 +766,14 @@ public:
         @param colour
             New background colour.
 
-        @param recursively
-            If True, child properties are affected recursively. Property
-            categories are skipped if this flag is used.
+        @param flags
+            Default is wxPG_RECURSE which causes colour to be set recursively.
+            Omit this flag to only set colour for the property in question
+            and not any of its children.
     */
     void SetPropertyBackgroundColour( wxPGPropArg id,
                                       const wxColour& colour,
-                                      bool recursively = true );
+                                      int flags = wxPG_RECURSE );
 
     /**
         Sets text, bitmap, and colours for given column's cell.
@@ -749,9 +847,6 @@ public:
         In other words, user cannot change the value in the editor, but they can
         still copy it.
 
-        @remarks This is mainly for use with textctrl editor. Only some other
-                editors fully support it.
-
         @param id
             Property name or pointer.
 
@@ -761,6 +856,9 @@ public:
         @param flags
             By default changes are applied recursively. Set this parameter
             wxPG_DONT_RECURSE to prevent this.
+
+        @remarks This is mainly for use with textctrl editor. Only some other
+                 editors fully support it.
     */
     void SetPropertyReadOnly( wxPGPropArg id, bool set = true,
                               int flags = wxPG_RECURSE );
@@ -772,13 +870,14 @@ public:
     void SetPropertyValueUnspecified( wxPGPropArg id );
 
     /**
-        Sets various property values from a list of wxVariants. If property with
-        name is missing from the grid, new property is created under given
-        default category (or root if omitted).
+        Sets property values from a list of wxVariants.
     */
     void SetPropertyValues( const wxVariantList& list,
                             wxPGPropArg defaultCategory = wxNullProperty );
 
+    /**
+        Sets property values from a list of wxVariants.
+    */
     void SetPropertyValues( const wxVariant& list,
                             wxPGPropArg defaultCategory = wxNullProperty );
 
@@ -815,13 +914,14 @@ public:
         @param colour
             New background colour.
 
-        @param recursively
-            If True, child properties are affected recursively. Property
-            categories are skipped if this flag is used.
+        @param flags
+            Default is wxPG_RECURSE which causes colour to be set recursively.
+            Omit this flag to only set colour for the property in question
+            and not any of its children.
     */
     void SetPropertyTextColour( wxPGPropArg id,
-                                const wxColour& col,
-                                bool recursively = true );
+                                const wxColour& colour,
+                                int flags = wxPG_RECURSE );
 
     /**
         Sets validator of a property.
@@ -891,6 +991,33 @@ public:
     */
     void SetValidationFailureBehavior( int vfbFlags );
 
+    /**
+        Sorts all properties recursively.
+
+        @param flags
+            This can contain any of the following options:
+              wxPG_SORT_TOP_LEVEL_ONLY: Only sort categories and their
+                immediate children. Sorting done by wxPG_AUTO_SORT option
+                uses this.
+
+        @see SortChildren, wxPropertyGrid::SetSortFunction
+    */
+    void Sort( int flags = 0 );
+
+    /**
+        Sorts children of a property.
+
+        @param id
+            Name or pointer to a property.
+
+        @param flags
+            This can contain any of the following options:
+              wxPG_RECURSE: Sorts recursively.
+
+        @see Sort, wxPropertyGrid::SetSortFunction
+    */
+    void SortChildren( wxPGPropArg id, int flags = 0 );
+
     /**
         Returns editor pointer of editor with given name;
     */