Fixed typo in wxDataViewIconTextRenderer docs.

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

diff --git a/interface/wx/propgrid/property.h b/interface/wx/propgrid/property.h
index 82f34fa08facf44a477ab27fec7da0aa8c54023e..95493ad7b4b44f7cb1a77f712afe1dff3ad3a989 100644 (file)
--- a/interface/wx/propgrid/property.h
+++ b/interface/wx/propgrid/property.h
@@ -41,8 +41,13 @@
 */
 #define wxPG_ATTR_UNITS                     wxS("Units")
 
-/** Universal, string. When set, will be shown in property's value cell
-    when displayed value string is empty, or value is unspecified.
+/** When set, will be shown as 'greyed' text in property's value cell when
+    the actual displayed value is blank.
+*/
+#define wxPG_ATTR_HINT                      wxS("Hint")
+
+/**
+    @deprecated Use "Hint" (wxPG_ATTR_HINT) instead.
 */
 #define wxPG_ATTR_INLINE_HELP               wxS("InlineHelp")
 
@@ -202,7 +207,10 @@
     @subsection wxPropertyCategory
 
     Not an actual property per se, but a header for a group of properties.
-    Regardless inherits from wxPGProperty.
+    Regardless inherits from wxPGProperty, and supports displaying 'labels'
+    for columns other than the first one. Easiest way to set category's
+    label for second column is to call wxPGProperty::SetValue() with string
+    argument.
 
     @subsection wxStringProperty
 
@@ -873,12 +881,15 @@ public:
     virtual void RefreshChildren();
 
     /**
-        Special handling for attributes of this property.
+        Reimplement this member function to add special handling for
+        attributes of this property.
 
-        If returns @false, then the attribute will be automatically stored in
-        m_attributes.
+        @return Return @false to have the attribute automatically stored in
+                m_attributes. Default implementation simply does that and
+                nothing else.
 
-        Default implementation simply returns @false.
+        @remarks To actually set property attribute values from the
+                 application, use wxPGProperty::SetAttribute() instead.
     */
     virtual bool DoSetAttribute( const wxString& name, wxVariant& value );
 
@@ -1028,9 +1039,23 @@ public:
 
     /**
         Returns wxPGCell of given column.
+
+        @remarks const version of this member function returns 'default'
+                 wxPGCell object if the property itself didn't hold
+                 cell data.
     */
     const wxPGCell& GetCell( unsigned int column ) const;
 
+    /**
+        Returns wxPGCell of given column, creating one if necessary.
+    */
+    wxPGCell& GetCell( unsigned int column );
+
+    /**
+        Returns wxPGCell of given column, creating one if necessary.
+    */
+    wxPGCell& GetOrCreateCell( unsigned int column );
+
     /**
         Returns number of child properties.
     */
@@ -1309,12 +1334,13 @@ public:
         @param colour
             Background colour to use.
 
-        @param recursively
-            If @true, children are affected recursively, and any categories
-            are not.
+        @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 SetBackgroundColour( const wxColour& colour,
-                              bool recursively = false );
+                              int flags = wxPG_RECURSE );
 
     /**
         Sets editor for a property.
@@ -1419,12 +1445,13 @@ public:
         @param colour
             Text colour to use.
 
-        @param recursively
-            If @true, children are affected recursively, and any categories
-            are not.
+        @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 SetTextColour( const wxColour& colour,
-                        bool recursively = false );
+                        int flags = wxPG_RECURSE );
 
     /** Sets wxValidator for a property */
     void SetValidator( const wxValidator& validator );
@@ -1491,6 +1518,73 @@ public:
 };
 
 
+/**
+    @class wxPGCell
+
+    Base class for wxPropertyGrid cell information.
+
+    @library{wxpropgrid}
+    @category{propgrid}
+*/
+class wxPGCell : public wxObject
+{
+public:
+    wxPGCell();
+    wxPGCell(const wxPGCell& other);
+    wxPGCell( const wxString& text,
+              const wxBitmap& bitmap = wxNullBitmap,
+              const wxColour& fgCol = wxNullColour,
+              const wxColour& bgCol = wxNullColour );
+
+    virtual ~wxPGCell();
+
+    const wxPGCellData* GetData() const;
+
+    /**
+        Returns @true if this cell has custom text stored within.
+    */
+    bool HasText() const;
+
+    /**
+        Merges valid data from srcCell into this.
+    */
+    void MergeFrom( const wxPGCell& srcCell );
+
+    void SetText( const wxString& text );
+    void SetBitmap( const wxBitmap& bitmap );
+    void SetFgCol( const wxColour& col );
+
+    /**
+        Sets font of the cell.
+
+        @remarks Because wxPropertyGrid does not support rows of
+                 different height, it makes little sense to change
+                 size of the font. Therefore it is recommended
+                 to use return value of wxPropertyGrid::GetFont()
+                 or wxPropertyGrid::GetCaptionFont() as a basis
+                 for the font that, after modifications, is passed
+                 to this member function.
+    */
+    void SetFont( const wxFont& font );
+
+    void SetBgCol( const wxColour& col );
+
+    const wxString& GetText() const;
+    const wxBitmap& GetBitmap() const;
+    const wxColour& GetFgCol() const;
+
+    /**
+        Returns font of the cell. If no specific font is set for this
+        cell, then the font will be invalid.
+    */
+    const wxFont& GetFont() const;
+
+    const wxColour& GetBgCol() const;
+
+    wxPGCell& operator=( const wxPGCell& other );
+};
+
+
 /**
     @class wxPGChoices
 
@@ -1508,7 +1602,7 @@ public:
     @library{wxpropgrid}
     @category{propgrid}
 */
-class WXDLLIMPEXP_PROPGRID wxPGChoices
+class wxPGChoices
 {
 public:
     typedef long ValArrItem;