document all currently defined image options and their values

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

diff --git a/interface/wx/propgrid/propgridiface.h b/interface/wx/propgrid/propgridiface.h
index 2781d5410dc19e12575478e80c802d1350654c25..36f1bfc1a9a74bb6c61abcb46e251f0a3b3379d1 100644 (file)
--- a/interface/wx/propgrid/propgridiface.h
+++ b/interface/wx/propgrid/propgridiface.h
@@ -2,7 +2,7 @@
 // Name:        property.h
 // Purpose:     interface of wxPGProperty
 // Author:      wxWidgets team
 // Name:        property.h
 // Purpose:     interface of wxPGProperty
 // Author:      wxWidgets team

-// RCS-ID:      $Id:
+// RCS-ID:      $Id$

 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 


@@ -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 );
 


@@ -62,8 +65,8 @@ public:
 
     /**
         In order to add new items into a property with private children (for
 
     /**
         In order to add new items into a property with private children (for

-        instance, wxFlagsProperty), you need to call this method. After
-        populating has been finished, you need to call EndAddChildren().
+        instance, wxFlagsProperty), you need to call this method.
+        After populating has been finished, you need to call EndAddChildren().

 
         @see EndAddChildren()
     */
 
         @see EndAddChildren()
     */


@@ -71,15 +74,25 @@ 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 success (ie. validator did not intercept).
+        @return Returns @true if successful or if there was no selection. May
+               fail if validation was enabled and active editor had invalid
+               value.

     */
     */

-    bool ClearSelection();
+    bool ClearSelection( bool validation = false);

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


@@ -90,14 +103,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();
 


@@ -110,13 +128,12 @@ public:
     */
     bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
 
     */
     bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
 

-    /**
-        Resets value of a property to its default.
-    */
-    bool ClearPropertyValue( wxPGPropArg id );
-

     /**
         Deletes a property.
     /**
         Deletes a property.

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

     */
     void DeleteProperty( wxPGPropArg id );
 
     */
     void DeleteProperty( wxPGPropArg id );
 


@@ -126,8 +143,8 @@ public:
     bool DisableProperty( wxPGPropArg id );
 
     /**
     bool DisableProperty( wxPGPropArg id );
 
     /**

-        Returns true if all property grid data changes have been committed. Usually
-        only returns false if value in active editor has been invalidated by a
+        Returns @true if all property grid data changes have been committed. Usually
+        only returns @false if value in active editor has been invalidated by a

         wxValidator.
     */
     bool EditorValidate();
         wxValidator.
     */
     bool EditorValidate();


@@ -137,7 +154,6 @@ public:
 
         @param id
             Name or pointer to a property.
 
         @param id
             Name or pointer to a property.

-

         @param enable
             If @false, property is disabled instead.
     */
         @param enable
             If @false, property is disabled instead.
     */


@@ -154,18 +170,21 @@ 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.

-    */
-    bool ExpandAll( bool expand = true );

 
 

-    /**
-        Returns list of expanded properties.
+        @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.

     */
     */

-    wxArrayPGProperty GetExpandedProperties() const;
+    bool ExpandAll( bool expand = true );

 
     /**
         Returns id of first child of given property.
 
     /**
         Returns id of first child of given property.


@@ -175,28 +194,44 @@ public:
     wxPGProperty* GetFirstChild( wxPGPropArg id );
 
     //@{
     wxPGProperty* GetFirstChild( wxPGPropArg id );
 
     //@{

-    /** Returns iterator class instance.
+    /**
+        Returns iterator class instance.

 
         @param flags
             See @ref propgrid_iterator_flags. Value wxPG_ITERATE_DEFAULT causes
             iteration over everything except private child properties.
 
         @param flags
             See @ref propgrid_iterator_flags. Value wxPG_ITERATE_DEFAULT causes
             iteration over everything except private child properties.

-

         @param firstProp
         @param firstProp

-            Property to start iteration from. If NULL, then first child of root
+            Property to start iteration from. If @NULL, then first child of root

             is used.
 
             is used.
 

+        @beginWxPythonOnly
+        <b>wxPython Note:</b> Instead of ++ operator, use Next() method, and
+        instead of * operator, use GetProperty() method.
+        @endWxPythonOnly
+    */
+    wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT,
+                                        wxPGProperty* firstProp = NULL );
+    wxPropertyGridConstIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT,
+                                             wxPGProperty* firstProp = NULL ) const;
+    //@}
+
+    //@{
+    /**
+        Returns iterator class instance.
+
+        @param flags
+            See @ref propgrid_iterator_flags. Value wxPG_ITERATE_DEFAULT causes
+            iteration over everything except private child properties.

         @param startPos
             Either wxTOP or wxBOTTOM. wxTOP will indicate that iterations start
             from the first property from the top, and wxBOTTOM means that the
             iteration will instead begin from bottommost valid item.
 
         @param startPos
             Either wxTOP or wxBOTTOM. wxTOP will indicate that iterations start
             from the first property from the top, and wxBOTTOM means that the
             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.
         <b>wxPython Note:</b> Instead of ++ operator, use Next() method, and
         instead of * operator, use GetProperty() method.

+        @endWxPythonOnly

     */
     */

-    wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT,
-                                        wxPGProperty* firstProp = NULL );
-    wxPropertyGridConstIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT,
-                                             wxPGProperty* firstProp = NULL ) const;

     wxPropertyGridIterator GetIterator( int flags, int startPos );
     wxPropertyGridConstIterator GetIterator( int flags, int startPos ) const;
     //@}
     wxPropertyGridIterator GetIterator( int flags, int startPos );
     wxPropertyGridConstIterator GetIterator( int flags, int startPos ) const;
     //@}


@@ -212,19 +247,19 @@ public:
     /**
         Returns id of property with given name (case-sensitive).
     */
     /**
         Returns id of property with given name (case-sensitive).
     */

-    wxPGProperty* GetProperty( const wxString& name ) const
-    {
-        return GetPropertyByName(name);
-    }
+    wxPGProperty* GetProperty( const wxString& name ) const;

 
     /**
 
     /**

-        Adds to 'targetArr' pointers to properties that have given
-        flags 'flags' set. However, if 'inverse' is set to true, then
-        only properties without given flags are stored.
+        Adds to 'targetArr' pointers to properties that have given flags 'flags' set.
+        However, if @a 'inverse' is set to @true, then only properties without
+        given flags are stored.

 
 

+        @param targetArr
+            @todo docme

         @param flags
             Property flags to use.
         @param flags
             Property flags to use.

-
+        @param inverse
+            @todo docme

         @param iterFlags
             Iterator flags to use. Default is everything expect private children.
             See @ref propgrid_iterator_flags.
         @param iterFlags
             Iterator flags to use. Default is everything expect private children.
             See @ref propgrid_iterator_flags.


@@ -239,9 +274,14 @@ 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
     /**
         Returns pointer of property's nearest parent category. If no category

-        found, returns NULL.
+        found, returns @NULL.

     */
     wxPropertyCategory* GetPropertyCategory( wxPGPropArg id ) const;
 
     */
     wxPropertyCategory* GetPropertyCategory( wxPGPropArg id ) const;
 


@@ -249,14 +289,14 @@ public:
     void* GetPropertyClientData( wxPGPropArg id ) const;
 
     /**
     void* GetPropertyClientData( wxPGPropArg id ) const;
 
     /**

-        Returns first property which label matches given string. NULL if none
+        Returns first property which label matches given string. @NULL if none

         found. Note that this operation is very slow when compared to
         GetPropertyByName().
     */
     wxPGProperty* GetPropertyByLabel( const wxString& label ) const;
 
     /**
         found. Note that this operation is very slow when compared to
         GetPropertyByName().
     */
     wxPGProperty* GetPropertyByLabel( const wxString& label ) const;
 
     /**

-        Returns property with given name. NULL if none found.
+        Returns property with given name. @NULL if none found.

     */
     wxPGProperty* GetPropertyByName( const wxString& name ) const;
 
     */
     wxPGProperty* GetPropertyByName( const wxString& name ) const;
 


@@ -278,7 +318,7 @@ public:
     wxString GetPropertyHelpString( wxPGPropArg id ) const;
 
     /**
     wxString GetPropertyHelpString( wxPGPropArg id ) const;
 
     /**

-        Returns property's custom value image (NULL of none).
+        Returns property's custom value image (@NULL of none).

     */
     wxBitmap* GetPropertyImage( wxPGPropArg id ) const;
 
     */
     wxBitmap* GetPropertyImage( wxPGPropArg id ) const;
 


@@ -288,6 +328,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.


@@ -342,6 +387,10 @@ public:
         Returns a wxVariant list containing wxVariant versions of all
         property values. Order is not guaranteed.
 
         Returns a wxVariant list containing wxVariant versions of all
         property values. Order is not guaranteed.
 

+        @param listname
+            @todo docme
+        @param baseparent
+            @todo docme

         @param flags
             Use wxPG_KEEP_STRUCTURE to retain category structure; each sub
             category will be its own wxVariantList of wxVariant.
         @param flags
             Use wxPG_KEEP_STRUCTURE to retain category structure; each sub
             category will be its own wxVariantList of wxVariant.


@@ -351,7 +400,7 @@ public:
             "@@<propname>@@attr."
     */
     wxVariant GetPropertyValues( const wxString& listname = wxEmptyString,
             "@@<propname>@@attr."
     */
     wxVariant GetPropertyValues( const wxString& listname = wxEmptyString,

-        wxPGProperty* baseparent = NULL, long flags = 0 ) const;
+                                 wxPGProperty* baseparent = NULL, long flags = 0 ) const;

 
     /** Returns currently selected property. */
     wxPGProperty* GetSelection() const;
 
     /** Returns currently selected property. */
     wxPGProperty* GetSelection() const;


@@ -372,9 +421,10 @@ public:
     /**
         Hides or reveals a property.
 
     /**
         Hides or reveals a property.
 

+        @param id
+            @todo docme

         @param hide
             If @true, hides property, otherwise reveals it.
         @param hide
             If @true, hides property, otherwise reveals it.

-

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


@@ -388,29 +438,18 @@ public:
     */
     static void InitAllTypeHandlers();
 
     */
     static void InitAllTypeHandlers();
 

-    //@{
-    /** Inserts property to the property container.
+    /**
+        Inserts property to the property container.

 
         @param priorThis
             New property is inserted just prior to this. Available only
             in the first variant. There are two versions of this function
             to allow this parameter to be either an id or name to
             a property.
 
         @param priorThis
             New property is inserted just prior to this. Available only
             in the first variant. There are two versions of this function
             to allow this parameter to be either an id or name to
             a property.

-

         @param newProperty
             Pointer to the inserted property. wxPropertyGrid will take
             ownership of this object.
 
         @param newProperty
             Pointer to the inserted property. wxPropertyGrid will take
             ownership of this object.
 

-        @param parent
-            New property is inserted under this category. Available only
-            in the second variant. There are two versions of this function
-            to allow this parameter to be either an id or name to
-            a property.
-
-        @param index
-            Index under category. Available only in the second variant.
-            If index is < 0, property is appended in category.
-

         @return Returns newProperty.
 
         @remarks
         @return Returns newProperty.
 
         @remarks


@@ -422,6 +461,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


@@ -438,11 +481,28 @@ public:
             wxPGProperty* my_item_id_2 = propertygrid->Insert( my_item_id, new wxStringProperty("My String 2") );
 
         @endcode
             wxPGProperty* my_item_id_2 = propertygrid->Insert( my_item_id, new wxStringProperty("My String 2") );
 
         @endcode

-

     */
     wxPGProperty* Insert( wxPGPropArg priorThis, wxPGProperty* newProperty );
     */
     wxPGProperty* Insert( wxPGPropArg priorThis, wxPGProperty* newProperty );

+
+    /**
+        Inserts property to the property container.
+        See the other overload for more details.
+
+        @param parent
+            New property is inserted under this category. Available only
+            in the second variant. There are two versions of this function
+            to allow this parameter to be either an id or name to
+            a property.
+        @param index
+            Index under category. Available only in the second variant.
+            If index is < 0, property is appended in category.
+        @param newProperty
+            Pointer to the inserted property. wxPropertyGrid will take
+            ownership of this object.
+
+        @return Returns newProperty.
+    */

     wxPGProperty* Insert( wxPGPropArg parent, int index, wxPGProperty* newProperty );
     wxPGProperty* Insert( wxPGPropArg parent, int index, wxPGProperty* newProperty );

-    //@}

 
     /** Returns @true if property is a category. */
     bool IsPropertyCategory( wxPGPropArg id ) const;
 
     /** Returns @true if property is a category. */
     bool IsPropertyCategory( wxPGPropArg id ) const;


@@ -451,7 +511,7 @@ public:
     bool IsPropertyEnabled( wxPGPropArg id ) const;
 
     /**
     bool IsPropertyEnabled( wxPGPropArg id ) const;
 
     /**

-        Returns true if given property is expanded. Naturally, always returns
+        Returns @true if given property is expanded. Naturally, always returns

         @false for properties that cannot be expanded.
     */
     bool IsPropertyExpanded( wxPGPropArg id ) const;
         @false for properties that cannot be expanded.
     */
     bool IsPropertyExpanded( wxPGPropArg id ) const;


@@ -463,13 +523,13 @@ public:
     bool IsPropertyModified( wxPGPropArg id ) const;
 
     /**
     bool IsPropertyModified( wxPGPropArg id ) const;
 
     /**

-        Returns true if property is shown (ie. HideProperty() with @true not
+        Returns @true if property is shown (ie. HideProperty() with @true not

         called for it).
     */
     bool IsPropertyShown( wxPGPropArg id ) const;
 
     /**
         called for it).
     */
     bool IsPropertyShown( wxPGPropArg id ) const;
 
     /**

-        Returns true if property value is set to unspecified.
+        Returns @true if property value is set to unspecified.

     */
     bool IsPropertyValueUnspecified( wxPGPropArg id ) const;
 
     */
     bool IsPropertyValueUnspecified( wxPGPropArg id ) const;
 


@@ -574,33 +634,21 @@ public:
     static void SetBoolChoices( const wxString& trueChoice,
                                 const wxString& falseChoice );
 
     static void SetBoolChoices( const wxString& trueChoice,
                                 const wxString& falseChoice );
 

-    /**
-        Sets or clears flag(s) of all properties in given array.
-
-        @param flags
-            Property flags to set or clear.
-
-        @param inverse
-            Set to true if you want to clear flag instead of setting them.
-    */
-    void SetPropertiesFlag( const wxArrayPGProperty& srcArr, wxPGProperty::FlagType flags,
-                            bool inverse = false );
-

     /**
         Sets an attribute for this property.
 
     /**
         Sets an attribute for this property.
 

-        @param name
+        @param id
+            @todo docme
+        @param attrName

             Text identifier of attribute. See @ref propgrid_property_attributes.
             Text identifier of attribute. See @ref propgrid_property_attributes.

-

         @param value
             Value of attribute.
         @param value
             Value of attribute.

-

         @param argFlags
         @param argFlags

-            Optional. Use wxPG_RECURSE to set the attribute to child properties
-            recursively.
+            Optional.
+            Use wxPG_RECURSE to set the attribute to child properties recursively.

 
         @remarks Setting attribute's value to Null variant will simply remove it
 
         @remarks Setting attribute's value to Null variant will simply remove it

-                from property's set of attributes.
+                 from property's set of attributes.

     */
     void SetPropertyAttribute( wxPGPropArg id, const wxString& attrName,
                                wxVariant value, long argFlags = 0 );
     */
     void SetPropertyAttribute( wxPGPropArg id, const wxString& attrName,
                                wxVariant value, long argFlags = 0 );


@@ -612,6 +660,23 @@ 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 recursively
+            If True, child properties are affected recursively. Property
+            categories are skipped if this flag is used.
+    */
+    void SetPropertyBackgroundColour( wxPGPropArg id,
+                                      const wxColour& colour,
+                                      bool recursively = true );
+

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


@@ -634,9 +699,16 @@ 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.
 

+        @param id
+            @todo docme

         @param editor
             For builtin editors, use wxPGEditor_X, where X is builtin editor's
             name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
         @param editor
             For builtin editors, use wxPGEditor_X, where X is builtin editor's
             name (TextCtrl, Choice, etc. see wxPGEditor documentation for full


@@ -733,6 +805,24 @@ 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 recursively
+            If True, child properties are affected recursively. Property
+            categories are skipped if this flag is used.
+    */
+    void SetPropertyTextColour( wxPGPropArg id,
+                                const wxColour& colour,
+                                bool recursively = true );
+

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