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 37afffe4974eded0de02121f2e20ec41d9e8e712..36f1bfc1a9a74bb6c61abcb46e251f0a3b3379d1 100644 (file)
--- a/interface/wx/propgrid/propgridiface.h
+++ b/interface/wx/propgrid/propgridiface.h
@@ -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.
+        - 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 );
 
@@ -71,15 +74,25 @@ public:
 
     /**
         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;
 
     /**
-        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.
@@ -90,14 +103,19 @@ public:
         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.
 
-        @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();
 
@@ -112,6 +130,10 @@ public:
 
     /**
         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 );
 
@@ -148,11 +170,19 @@ public:
         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.
+
+        @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 );
 
@@ -244,6 +274,11 @@ public:
     */
     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.
@@ -293,6 +328,11 @@ public:
     /** 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.
@@ -421,6 +461,10 @@ public:
           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
@@ -616,6 +660,23 @@ public:
     */
     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.
 
@@ -638,6 +699,11 @@ public:
     */
     void SetPropertyClientData( wxPGPropArg id, void* clientData );
 
+    /**
+        Resets text and background colours of given property.
+    */
+    void SetPropertyColoursToDefault( wxPGPropArg id );
+
     /**
         Sets editor for a property.
 
@@ -739,6 +805,24 @@ public:
     */
     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.
     */