adding a app-defined event seems to quit inner eventloops like eg the popup of the...

[wxWidgets.git] / interface / wx / propgrid / propgridiface.h

diff --git a/interface/wx/propgrid/propgridiface.h b/interface/wx/propgrid/propgridiface.h
index 37afffe4974eded0de02121f2e20ec41d9e8e712..dba072c5e50bbce97eebfa5fa9e3d723bfa4018f 100644 (file)
--- 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$
 // Purpose:     interface of wxPGProperty
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 // -----------------------------------------------------------------------
 /////////////////////////////////////////////////////////////////////////////
 
 // -----------------------------------------------------------------------


@@ -46,6 +46,9 @@ public:
         - Does not automatically redraw the control, so you may need to call
           Refresh() when calling this function after control has been shown for
           the first time.
         - Does not automatically redraw the control, so you may need to call
           Refresh() when calling this function after control has been shown for
           the first time.

+        - 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.

     */
     wxPGProperty* Append( wxPGProperty* property );
 
     */
     wxPGProperty* Append( wxPGProperty* property );
 


@@ -71,15 +74,31 @@ public:
 
     /**
         Deletes all properties.
 
     /**
         Deletes all properties.

+
+        @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.

     */
     virtual void Clear() = 0;
 
     /**
     */
     virtual void Clear() = 0;
 
     /**

-        Deselect current selection, if any.
+        Clears current selection, if any.
+
+        @param validation
+            If set to @false, deselecting the property will always work,
+            even if its editor had invalid value in it.
+
+        @return Returns @true if successful or if there was no selection. May
+               fail if validation was enabled and active editor had invalid
+               value.

 
 

-        @return Returns @true if success (ie. validator did not intercept).
+        @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 ClearSelection( bool validation = false);

 
     /**
         Resets modified status of all properties.
 
     /**
         Resets modified status of all properties.


@@ -90,14 +109,19 @@ public:
         Collapses given category or property with children.
 
         @return Returns @true if actually collapsed.
         Collapses given category or property with children.
 
         @return Returns @true if actually collapsed.

+
+        @remarks This function may deselect 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.

     */
     bool Collapse( wxPGPropArg id );
 
     /**
         Collapses all items that can be collapsed.
 
     */
     bool Collapse( wxPGPropArg id );
 
     /**
         Collapses all items that can be collapsed.
 

-        @return Returns @false if failed (may fail if value in active
-               editor cannot be validated).
+        @remarks This functions clears selection. Validation failure option
+                wxPG_VFB_STAY_IN_PROPERTY is not respected, ie. selection
+                is cleared even if editor had invalid value.

     */
     bool CollapseAll();
 
     */
     bool CollapseAll();
 


@@ -111,12 +135,26 @@ public:
     bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
 
     /**
     bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
 
     /**

-        Deletes a property.
+        Removes and deletes a property and any children.
+
+        @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.
     */
     void DeleteProperty( wxPGPropArg id );
 
     /**
         Disables a property.

+
+        @see EnableProperty(), wxPGProperty::Enable()

     */
     bool DisableProperty( wxPGPropArg id );
 
     */
     bool DisableProperty( wxPGPropArg id );
 


@@ -128,12 +166,15 @@ public:
     bool EditorValidate();
 
     /**
     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.
 
         @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 );
 
     */
     bool EnableProperty( wxPGPropArg id, bool enable = true );
 


@@ -148,14 +189,29 @@ public:
         Expands given category or property with children.
 
         @return Returns @true if actually expanded.
         Expands given category or property with children.
 
         @return Returns @true if actually expanded.

+
+        @remarks This function may deselect 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.

     */
     bool Expand( wxPGPropArg id );
 
     /**
         Expands all items that can be expanded.
     */
     bool Expand( wxPGPropArg id );
 
     /**
         Expands all items that can be expanded.

+
+        @remarks This functions clears selection. Validation failure option
+                wxPG_VFB_STAY_IN_PROPERTY is not respected, ie. selection
+                is cleared even if editor had invalid value.

     */
     bool ExpandAll( bool expand = true );
 
     */
     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.
 
     /**
         Returns id of first child of given property.
 


@@ -175,8 +231,12 @@ public:
             is used.
 
         @beginWxPythonOnly
             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,
         @endWxPythonOnly
     */
     wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT,


@@ -198,8 +258,12 @@ public:
             iteration will instead begin from bottommost valid item.
 
         @beginWxPythonOnly
             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 );
         @endWxPythonOnly
     */
     wxPropertyGridIterator GetIterator( int flags, int startPos );


@@ -215,7 +279,12 @@ public:
     wxPGProperty* GetFirst( int flags = wxPG_ITERATE_ALL );
 
     /**
     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;
 
     */
     wxPGProperty* GetProperty( const wxString& name ) const;
 


@@ -244,6 +313,11 @@ public:
     */
     wxVariant GetPropertyAttribute( wxPGPropArg id, const wxString& attrName ) const;
 
     */
     wxVariant GetPropertyAttribute( wxPGPropArg id, const wxString& attrName ) const;
 

+    /**
+        Returns background colour of first cell of a property.
+    */
+    wxColour GetPropertyBackgroundColour( wxPGPropArg id ) const;
+

     /**
         Returns pointer of property's nearest parent category. If no category
         found, returns @NULL.
     /**
         Returns pointer of property's nearest parent category. If no category
         found, returns @NULL.


@@ -261,7 +335,12 @@ public:
     wxPGProperty* GetPropertyByLabel( const wxString& label ) const;
 
     /**
     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;
 
     */
     wxPGProperty* GetPropertyByName( const wxString& name ) const;
 


@@ -293,6 +372,11 @@ public:
     /** Returns property's name, by which it is globally accessible. */
     wxString GetPropertyName( wxPGProperty* property );
 
     /** Returns property's name, by which it is globally accessible. */
     wxString GetPropertyName( wxPGProperty* property );
 

+    /**
+        Returns text colour of first cell of a property.
+    */
+    wxColour GetPropertyTextColour( wxPGPropArg id ) const;
+

     /**
         Returns validator of a property as a reference, which you
         can pass to any number of SetPropertyValidator.
     /**
         Returns validator of a property as a reference, which you
         can pass to any number of SetPropertyValidator.


@@ -362,7 +446,20 @@ public:
     wxVariant GetPropertyValues( const wxString& listname = wxEmptyString,
                                  wxPGProperty* baseparent = NULL, long flags = 0 ) const;
 
     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;
 
     /**
     wxPGProperty* GetSelection() const;
 
     /**


@@ -373,8 +470,14 @@ public:
         @param flags
             See @ref propgrid_iterator_flags.
 
         @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;
 
     */
     virtual wxPGVIterator GetVIterator( int flags ) const;
 


@@ -421,6 +524,10 @@ public:
           non-categoric) are active, Insert becomes even more slow. This is
           especially true if current mode is non-categoric.
 
           non-categoric) are active, Insert becomes even more slow. This is
           especially true if current mode is non-categoric.
 

+        - 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.
+

         Example of use:
 
         @code
         Example of use:
 
         @code


@@ -478,6 +585,11 @@ public:
     */
     bool IsPropertyModified( wxPGPropArg id ) const;
 
     */
     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).
     /**
         Returns @true if property is shown (ie. HideProperty() with @true not
         called for it).


@@ -503,6 +615,21 @@ public:
     */
     static void RegisterAdditionalEditors();
 
     */
     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
     /**
         Replaces property with id with newly created one. For example,
         this code replaces existing property named "Flags" with one that


@@ -590,6 +717,20 @@ public:
     static void SetBoolChoices( const wxString& trueChoice,
                                 const wxString& falseChoice );
 
     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.
 
     /**
         Sets an attribute for this property.
 


@@ -616,6 +757,24 @@ public:
     */
     void SetPropertyAttributeAll( const wxString& attrName, wxVariant value );
 
     */
     void SetPropertyAttributeAll( const wxString& attrName, wxVariant value );
 

+    /**
+        Sets background colour of a property.
+
+        @param id
+            Property name or pointer.
+
+        @param colour
+            New background colour.
+
+        @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,
+                                      int flags = wxPG_RECURSE );
+

     /**
         Sets text, bitmap, and colours for given column's cell.
 
     /**
         Sets text, bitmap, and colours for given column's cell.
 


@@ -638,6 +797,11 @@ public:
     */
     void SetPropertyClientData( wxPGPropArg id, void* clientData );
 
     */
     void SetPropertyClientData( wxPGPropArg id, void* clientData );
 

+    /**
+        Resets text and background colours of given property.
+    */
+    void SetPropertyColoursToDefault( wxPGPropArg id );
+

     /**
         Sets editor for a property.
 
     /**
         Sets editor for a property.
 


@@ -683,9 +847,6 @@ public:
         In other words, user cannot change the value in the editor, but they can
         still copy it.
 
         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.
 
         @param id
             Property name or pointer.
 


@@ -695,6 +856,9 @@ public:
         @param flags
             By default changes are applied recursively. Set this parameter
             wxPG_DONT_RECURSE to prevent this.
         @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 );
     */
     void SetPropertyReadOnly( wxPGPropArg id, bool set = true,
                               int flags = wxPG_RECURSE );


@@ -706,13 +870,14 @@ public:
     void SetPropertyValueUnspecified( wxPGPropArg id );
 
     /**
     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 );
 
     */
     void SetPropertyValues( const wxVariantList& list,
                             wxPGPropArg defaultCategory = wxNullProperty );
 

+    /**
+        Sets property values from a list of wxVariants.
+    */

     void SetPropertyValues( const wxVariant& list,
                             wxPGPropArg defaultCategory = wxNullProperty );
 
     void SetPropertyValues( const wxVariant& list,
                             wxPGPropArg defaultCategory = wxNullProperty );
 


@@ -739,6 +904,25 @@ public:
     */
     bool SetPropertyMaxLength( wxPGPropArg id, int maxLen );
 
     */
     bool SetPropertyMaxLength( wxPGPropArg id, int maxLen );
 

+
+    /**
+        Sets text colour of a property.
+
+        @param id
+            Property name or pointer.
+
+        @param colour
+            New background colour.
+
+        @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& colour,
+                                int flags = wxPG_RECURSE );
+

     /**
         Sets validator of a property.
     */
     /**
         Sets validator of a property.
     */


@@ -807,6 +991,33 @@ public:
     */
     void SetValidationFailureBehavior( int vfbFlags );
 
     */
     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;
     */
     /**
         Returns editor pointer of editor with given name;
     */