X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/16372f0d97cdd46f2bec3844877827ee9f8b2415..4d68a949dff65b8f40e4d372364e7ff8feba152a:/interface/wx/propgrid/property.h?ds=sidebyside diff --git a/interface/wx/propgrid/property.h b/interface/wx/propgrid/property.h index f553085577..95493ad7b4 100644 --- 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 @@ -428,11 +436,15 @@ class MyProperty : public wxPGProperty { public: - // All arguments of ctor must have a default value - + // Default constructor + MyProperty() { } + + // All arguments of this ctor must have a default value - // use wxPG_LABEL for label and name MyProperty( const wxString& label = wxPG_LABEL, const wxString& name = wxPG_LABEL, const wxString& value = wxEmptyString ) + : wxPGProperty(label, name) { // m_value is wxVariant m_value = value; @@ -509,7 +521,7 @@ public: @code MyProperty( const wxString& label, const wxString& name, const T& value ) - : wxPGProperty() + : wxPGProperty(label, name) { // Generally recommended way to set the initial value // (as it should work in pretty much 100% of cases). @@ -698,18 +710,25 @@ public: virtual bool OnEvent( wxPropertyGrid* propgrid, wxWindow* wnd_primary, wxEvent& event ); /** - Called after value of a child property has been altered. Note that this function is - usually called at the time that value of this property, or given child property, is - still pending for change. + Called after value of a child property has been altered. Must return + new value of the whole property (after any alterations warrented by + child's new value). + + Note that this function is usually called at the time that value of + this property, or given child property, is still pending for change, + and as such, result of GetValue() or m_value should not be relied + on. Sample pseudo-code implementation: @code - void MyProperty::ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const + wxVariant MyProperty::ChildChanged( wxVariant& thisValue, + int childIndex, + wxVariant& childValue ) const { // Acquire reference to actual type of data stored in variant - // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros were used to create - // the variant class). + // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros + // were used to create the variant class). T& data = TFromVariant(thisValue); // Copy childValue into data. @@ -723,17 +742,28 @@ public: break; ... } + + // Return altered data + return data; } @endcode @param thisValue - Value of this property, that should be altered. + Value of this property. Changed value should be returned (in + previous versions of wxPropertyGrid it was only necessary to + write value back to this argument). @param childIndex - Index of child changed (you can use Item(childIndex) to get). + Index of child changed (you can use Item(childIndex) to get + child property). @param childValue - Value of the child property. + (Pending) value of the child property. + + @return + Modified value of the whole property. */ - virtual void ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const; + virtual wxVariant ChildChanged( wxVariant& thisValue, + int childIndex, + wxVariant& childValue ) const; /** Returns pointer to an instance of used editor. @@ -851,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 ); @@ -1006,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. */ @@ -1287,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. @@ -1341,6 +1389,14 @@ public: */ void SetChoiceSelection( int newValue ); + /** Set default value of a property. Synonymous to + + @code + SetAttribute("DefaultValue", value); + @endcode + */ + void SetDefaultValue( wxVariant& value ); + /** Sets property's help string, which is shown, for example, in wxPropertyGridManager's description text box. @@ -1389,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 ); @@ -1461,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 @@ -1478,7 +1602,7 @@ public: @library{wxpropgrid} @category{propgrid} */ -class WXDLLIMPEXP_PROPGRID wxPGChoices +class wxPGChoices { public: typedef long ValArrItem; @@ -1580,6 +1704,10 @@ public: wxArrayInt GetIndicesForStrings( const wxArrayString& strings, wxArrayString* unmatched = NULL ) const; + /** Returns property at given virtual y coordinate. + */ + wxPGProperty* GetItemAtY( unsigned int y ) const; + /** Returns @true if item at given index has a valid value; */