X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/47ea393a24b7781f2a15264d30f4ebe32aa6e9bb..b545684e13530b21082bc2fc5c64c1c14b852994:/include/wx/propgrid/property.h diff --git a/include/wx/propgrid/property.h b/include/wx/propgrid/property.h index 45ba8c6504..2d8b69c1d0 100644 --- a/include/wx/propgrid/property.h +++ b/include/wx/propgrid/property.h @@ -4,7 +4,7 @@ // Author: Jaakko Salli // Modified by: // Created: 2008-08-23 -// RCS-ID: $Id: +// RCS-ID: $Id$ // Copyright: (c) Jaakko Salli // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// @@ -64,19 +64,38 @@ struct wxPGPaintData Base class for wxPropertyGrid cell renderers. */ -class WXDLLIMPEXP_PROPGRID wxPGCellRenderer +class WXDLLIMPEXP_PROPGRID wxPGCellRenderer : public wxObjectRefData { public: - wxPGCellRenderer( unsigned int refCount = 1 ) - : m_refCount(refCount) { } + wxPGCellRenderer() + : wxObjectRefData() { } virtual ~wxPGCellRenderer() { } // Render flags enum { + // We are painting selected item Selected = 0x00010000, - Control = 0x00020000 + + // We are painting item in choice popup + ChoicePopup = 0x00020000, + + // We are rendering wxOwnerDrawnComboBox control + // (or other owner drawn control, but that is only + // officially supported one ATM). + Control = 0x00040000, + + // We are painting a disable property + Disabled = 0x00080000, + + // We are painting selected, disabled, or similar + // item that dictates fore- and background colours, + // overriding any cell values. + DontUseCellFgCol = 0x00100000, + DontUseCellBgCol = 0x00200000, + DontUseCellColours = DontUseCellFgCol | + DontUseCellBgCol }; virtual void Render( wxDC& dc, @@ -118,91 +137,179 @@ public: wxPGProperty* property, const wxPGEditor* editor ) const; - /** Utility to render cell bitmap and set text colour plus bg brush colour. + /** Utility to render cell bitmap and set text colour plus bg brush + colour. - Returns image width that, for instance, can be passed to DrawText. + @return Returns image width, which, for instance, can be passed to + DrawText. */ int PreDrawCell( wxDC& dc, const wxRect& rect, const wxPGCell& cell, int flags ) const; - void IncRef() - { - m_refCount++; - } - - void DecRef() - { - m_refCount--; - if ( !m_refCount ) - delete this; - } -protected: + /** + Utility to be called after drawing is done, to revert whatever + changes PreDrawCell() did. -private: - unsigned int m_refCount; + @param flags + Same as those passed to PreDrawCell(). + */ + void PostDrawCell( wxDC& dc, + const wxPropertyGrid* propGrid, + const wxPGCell& cell, + int flags ) const; }; -/** @class wxPGCell +/** + @class wxPGDefaultRenderer - Base class for simple wxPropertyGrid cell information. + Default cell renderer, that can handles the common + scenarios. */ -class WXDLLIMPEXP_PROPGRID wxPGCell +class WXDLLIMPEXP_PROPGRID wxPGDefaultRenderer : public wxPGCellRenderer { public: - wxPGCell(); - wxPGCell( const wxString& text, - const wxBitmap& bitmap = wxNullBitmap, - const wxColour& fgCol = wxNullColour, - const wxColour& bgCol = wxNullColour ); + virtual void Render( wxDC& dc, + const wxRect& rect, + const wxPropertyGrid* propertyGrid, + wxPGProperty* property, + int column, + int item, + int flags ) const; - virtual ~wxPGCell() { } + virtual wxSize GetImageSize( const wxPGProperty* property, + int column, + int item ) const; - void SetText( const wxString& text ) { m_text = text; } +protected: +}; + + +class WXDLLIMPEXP_PROPGRID wxPGCellData : public wxObjectRefData +{ + friend class wxPGCell; +public: + wxPGCellData(); + + void SetText( const wxString& text ) + { + m_text = text; + m_hasValidText = true; + } void SetBitmap( const wxBitmap& bitmap ) { m_bitmap = bitmap; } void SetFgCol( const wxColour& col ) { m_fgCol = col; } void SetBgCol( const wxColour& col ) { m_bgCol = col; } - - const wxString& GetText() const { return m_text; } - const wxBitmap& GetBitmap() const { return m_bitmap; } - const wxColour& GetFgCol() const { return m_fgCol; } - const wxColour& GetBgCol() const { return m_bgCol; } + void SetFont( const wxFont& font ) { m_font = font; } protected: + virtual ~wxPGCellData() { } + wxString m_text; wxBitmap m_bitmap; wxColour m_fgCol; wxColour m_bgCol; + wxFont m_font; + + // True if m_text is valid and specified + bool m_hasValidText; }; +#endif // !SWIG -/** @class wxPGDefaultRenderer +/** + @class wxPGCell - Default cell renderer, that can handles the common - scenarios. + Base class for wxPropertyGrid cell information. */ -class WXDLLIMPEXP_PROPGRID wxPGDefaultRenderer : public wxPGCellRenderer +class WXDLLIMPEXP_PROPGRID wxPGCell : public wxObject { public: - virtual void Render( wxDC& dc, - const wxRect& rect, - const wxPropertyGrid* propertyGrid, - wxPGProperty* property, - int column, - int item, - int flags ) const; + wxPGCell(); + wxPGCell(const wxPGCell& other) + : wxObject(other) + { + } - virtual wxSize GetImageSize( const wxPGProperty* property, - int column, - int item ) const; + wxPGCell( const wxString& text, + const wxBitmap& bitmap = wxNullBitmap, + const wxColour& fgCol = wxNullColour, + const wxColour& bgCol = wxNullColour ); -protected: + virtual ~wxPGCell() { } + + wxPGCellData* GetData() + { + return (wxPGCellData*) m_refData; + } + + const wxPGCellData* GetData() const + { + return (const wxPGCellData*) m_refData; + } + + bool HasText() const + { + return (m_refData && GetData()->m_hasValidText); + } + + /** + 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 { return GetData()->m_text; } + const wxBitmap& GetBitmap() const { return GetData()->m_bitmap; } + const wxColour& GetFgCol() const { return GetData()->m_fgCol; } + + /** + Returns font of the cell. If no specific font is set for this + cell, then the font will be invalid. + */ + const wxFont& GetFont() const { return GetData()->m_font; } + + const wxColour& GetBgCol() const { return GetData()->m_bgCol; } + + wxPGCell& operator=( const wxPGCell& other ) + { + if ( this != &other ) + { + Ref(other); + } + return *this; + } + +private: + virtual wxObjectRefData *CreateRefData() const + { return new wxPGCellData(); } + + virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const; }; // ----------------------------------------------------------------------- +#ifndef SWIG + /** @class wxPGAttributeStorage wxPGAttributeStorage is somewhat optimized storage for @@ -215,7 +322,7 @@ public: ~wxPGAttributeStorage(); void Set( const wxString& name, const wxVariant& value ); - size_t GetCount() const { return m_map.size(); } + unsigned int GetCount() const { return (unsigned int) m_map.size(); } wxVariant FindValue( const wxString& name ) const { wxPGHashMapS2P::const_iterator it = m_map.find(name); @@ -242,7 +349,7 @@ public: data->IncRef(); variant.SetData(data); variant.SetName(it->first); - it++; + ++it; return true; } @@ -371,7 +478,11 @@ wxPG_PROP_CLASS_SPECIFIC_1 = 0x00080000, /** Indicates the bit useable by derived properties. */ -wxPG_PROP_CLASS_SPECIFIC_2 = 0x00100000 +wxPG_PROP_CLASS_SPECIFIC_2 = 0x00100000, + +/** Indicates that the property is being deleted and should be ignored. +*/ +wxPG_PROP_BEING_DELETED = 0x00200000 }; @@ -389,9 +500,6 @@ wxPG_PROP_CLASS_SPECIFIC_2 = 0x00100000 /** @} */ -// Amalgam of flags that should be inherited by sub-properties -#define wxPG_INHERITED_PROPFLAGS (wxPG_PROP_HIDDEN|wxPG_PROP_NOEDITOR) - // Combination of flags that can be stored by GetFlagsAsString #define wxPG_STRING_STORED_FLAGS \ (wxPG_PROP_DISABLED|wxPG_PROP_HIDDEN|wxPG_PROP_NOEDITOR|wxPG_PROP_COLLAPSED) @@ -438,13 +546,28 @@ wxPG_PROP_CLASS_SPECIFIC_2 = 0x00100000 */ #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp") -/** wxBoolProperty specific, int, default 0. When 1 sets bool property to - use checkbox instead of choice. +/** Universal, wxArrayString. Set to enable auto-completion in any + wxTextCtrl-based property editor. +*/ +#define wxPG_ATTR_AUTOCOMPLETE wxS("AutoComplete") + +/** wxBoolProperty and wxFlagsProperty specific. Value type is bool. + Default value is False. + + When set to True, bool property will use check box instead of a + combo box as its editor control. If you set this attribute + for a wxFlagsProperty, it is automatically applied to child + bool properties. */ #define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox") -/** wxBoolProperty specific, int, default 0. When 1 sets bool property value - to cycle on double click (instead of showing the popup listbox). +/** wxBoolProperty and wxFlagsProperty specific. Value type is bool. + Default value is False. + + Set to True for the bool property to cycle value on double click + (instead of showing the popup listbox). If you set this attribute + for a wxFlagsProperty, it is automatically applied to child + bool properties. */ #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING wxS("UseDClickCycling") @@ -547,6 +670,8 @@ wxPG_PROP_CLASS_SPECIFIC_2 = 0x00100000 */ // Redefine attribute macros to use cached strings +#undef wxPG_ATTR_DEFAULT_VALUE +#define wxPG_ATTR_DEFAULT_VALUE wxPGGlobalVars->m_strDefaultValue #undef wxPG_ATTR_MIN #define wxPG_ATTR_MIN wxPGGlobalVars->m_strMin #undef wxPG_ATTR_MAX @@ -569,32 +694,32 @@ class WXDLLIMPEXP_PROPGRID wxPGChoiceEntry : public wxPGCell { public: wxPGChoiceEntry(); - wxPGChoiceEntry( const wxPGChoiceEntry& entry ); - wxPGChoiceEntry( const wxString& label, - int value = wxPG_INVALID_VALUE ) - : wxPGCell(), m_value(value) + wxPGChoiceEntry(const wxPGChoiceEntry& other) + : wxPGCell(other) { - m_text = label; + m_value = other.m_value; } - wxPGChoiceEntry( const wxString& label, - int value, - const wxBitmap& bitmap, - const wxColour& fgCol = wxNullColour, - const wxColour& bgCol = wxNullColour ) - : wxPGCell(label, bitmap, fgCol, bgCol), m_value(value) + int value = wxPG_INVALID_VALUE ) + : wxPGCell(), m_value(value) { + SetText(label); } - virtual ~wxPGChoiceEntry() - { - } + virtual ~wxPGChoiceEntry() { } void SetValue( int value ) { m_value = value; } - int GetValue() const { return m_value; } - bool HasValue() const { return (m_value != wxPG_INVALID_VALUE); } + wxPGChoiceEntry& operator=( const wxPGChoiceEntry& other ) + { + if ( this != &other ) + { + Ref(other); + } + m_value = other.m_value; + return *this; + } protected: int m_value; @@ -603,7 +728,7 @@ protected: typedef void* wxPGChoicesId; -class WXDLLIMPEXP_PROPGRID wxPGChoicesData +class WXDLLIMPEXP_PROPGRID wxPGChoicesData : public wxObjectRefData { friend class wxPGChoices; public: @@ -612,52 +737,30 @@ public: void CopyDataFrom( wxPGChoicesData* data ); - // Takes ownership of 'item' - void Insert( int index, wxPGChoiceEntry* item ) - { - wxArrayPtrVoid::iterator it; - if ( index == -1 ) - { - it = m_items.end(); - index = m_items.size(); - } - else - { - it = m_items.begin() + index; - } - - // Need to fix value? - if ( item->GetValue() == wxPG_INVALID_VALUE ) - item->SetValue(index); - - m_items.insert(it, item); - } + wxPGChoiceEntry& Insert( int index, const wxPGChoiceEntry& item ); // Delete all entries void Clear(); - size_t GetCount() const { return m_items.size(); } - - wxPGChoiceEntry* Item( unsigned int i ) const + unsigned int GetCount() const { - wxCHECK_MSG( i < GetCount(), NULL, "invalid index" ); + return (unsigned int) m_items.size(); + } - return (wxPGChoiceEntry*) m_items[i]; + const wxPGChoiceEntry& Item( unsigned int i ) const + { + wxASSERT_MSG( i < GetCount(), "invalid index" ); + return m_items[i]; } - void DecRef() + wxPGChoiceEntry& Item( unsigned int i ) { - m_refCount--; - wxASSERT( m_refCount >= 0 ); - if ( m_refCount == 0 ) - delete this; + wxASSERT_MSG( i < GetCount(), "invalid index" ); + return m_items[i]; } private: - wxArrayPtrVoid m_items; - - // So that multiple properties can use the same set - int m_refCount; + wxVector m_items; virtual ~wxPGChoicesData(); }; @@ -672,6 +775,13 @@ private: Each entry can have label, value, bitmap, text colour, and background colour. + wxPGChoices uses reference counting, similar to other wxWidgets classes. + This means that assignment operator and copy constructor only copy the + reference and not the actual data. Use Copy() member function to create a + real copy. + + @remarks If you do not specify value for entry, index is used. + @library{wxpropgrid} @category{propgrid} */ @@ -686,24 +796,43 @@ public: Init(); } - /** Copy constructor. */ + /** + Copy constructor, uses reference counting. To create a real copy, + use Copy() member function instead. + */ wxPGChoices( const wxPGChoices& a ) { if ( a.m_data != wxPGChoicesEmptyData ) { m_data = a.m_data; - m_data->m_refCount++; + m_data->IncRef(); } } - /** Constructor. */ - wxPGChoices( const wxChar** labels, const long* values = NULL ) + /** + Constructor. + + @param labels + Labels for choices + + @param values + Values for choices. If NULL, indexes are used. + */ + wxPGChoices( const wxChar* const* labels, const long* values = NULL ) { Init(); Set(labels,values); } - /** Constructor. */ + /** + Constructor. + + @param labels + Labels for choices + + @param values + Values for choices. If empty, indexes are used. + */ wxPGChoices( const wxArrayString& labels, const wxArrayInt& values = wxArrayInt() ) { @@ -716,7 +845,7 @@ public: { wxASSERT(data); m_data = data; - data->m_refCount++; + data->IncRef(); } /** Destructor. */ @@ -730,16 +859,27 @@ public: If did not have own copies, creates them now. If was empty, identical to set except that creates copies. - */ - void Add( const wxChar** labels, const ValArrItem* values = NULL ); - /** Version that works with wxArrayString. */ - void Add( const wxArrayString& arr, const ValArrItem* values = NULL ); + @param labels + Labels for added choices. + + @param values + Values for added choices. If empty, relevant entry indexes are used. + */ + void Add( const wxChar* const* labels, const ValArrItem* values = NULL ); /** Version that works with wxArrayString and wxArrayInt. */ - void Add( const wxArrayString& arr, const wxArrayInt& arrint ); + void Add( const wxArrayString& arr, const wxArrayInt& arrint = wxArrayInt() ); - /** Adds single item. */ + /** + Adds a single choice. + + @param label + Label for added choice. + + @param value + Value for added choice. If unspecified, index is used. + */ wxPGChoiceEntry& Add( const wxString& label, int value = wxPG_INVALID_VALUE ); @@ -758,6 +898,10 @@ public: wxPGChoiceEntry& AddAsSorted( const wxString& label, int value = wxPG_INVALID_VALUE ); + /** + Assigns choices data, using reference counting. To create a real copy, + use Copy() member function instead. + */ void Assign( const wxPGChoices& a ) { AssignData(a.m_data); @@ -766,10 +910,17 @@ public: void AssignData( wxPGChoicesData* data ); /** Delete all choices. */ - void Clear() + void Clear(); + + /** + Returns a real copy of the choices. + */ + wxPGChoices Copy() const { - if ( m_data != wxPGChoicesEmptyData ) - m_data->Clear(); + wxPGChoices dst; + dst.EnsureData(); + dst.m_data->CopyDataFrom(m_data); + return dst; } void EnsureData() @@ -781,12 +932,12 @@ public: /** Gets a unsigned number identifying this list. */ wxPGChoicesId GetId() const { return (wxPGChoicesId) m_data; }; - const wxString& GetLabel( size_t ind ) const + const wxString& GetLabel( unsigned int ind ) const { return Item(ind).GetText(); } - size_t GetCount () const + unsigned int GetCount () const { if ( !m_data ) return 0; @@ -794,7 +945,7 @@ public: return m_data->GetCount(); } - int GetValue( size_t ind ) const { return Item(ind).GetValue(); } + int GetValue( unsigned int ind ) const { return Item(ind).GetValue(); } /** Returns array of values matching the given strings. Unmatching strings result in wxPG_INVALID_VALUE entry in array. @@ -807,14 +958,6 @@ public: wxArrayInt GetIndicesForStrings( const wxArrayString& strings, wxArrayString* unmatched = NULL ) const; - /** Returns true if choices in general are likely to have values - (depens on that all entries have values or none has) - */ - bool HasValues() const; - - bool HasValue( unsigned int i ) const - { return (i < m_data->GetCount()) && m_data->Item(i)->HasValue(); } - int Index( const wxString& str ) const; int Index( int val ) const; @@ -837,13 +980,13 @@ public: const wxPGChoiceEntry& Item( unsigned int i ) const { wxASSERT( IsOk() ); - return *m_data->Item(i); + return m_data->Item(i); } wxPGChoiceEntry& Item( unsigned int i ) { wxASSERT( IsOk() ); - return *m_data->Item(i); + return m_data->Item(i); } /** Removes count items starting at position nIndex. */ @@ -851,20 +994,11 @@ public: #ifndef SWIG /** Does not create copies for itself. */ - void Set( const wxChar** labels, const long* values = NULL ) + void Set( const wxChar* const* labels, const long* values = NULL ) { Free(); Add(labels,values); } - - /** Version that works with wxArrayString. - TODO: Deprecate this. - */ - void Set( wxArrayString& arr, const long* values = (const long*) NULL ) - { - Free(); - Add(arr,values); - } #endif // SWIG /** Version that works with wxArrayString and wxArrayInt. */ @@ -879,22 +1013,13 @@ public: } // Creates exclusive copy of current choices - void SetExclusive() - { - if ( m_data->m_refCount != 1 ) - { - wxPGChoicesData* data = new wxPGChoicesData(); - data->CopyDataFrom(m_data); - Free(); - m_data = data; - } - } + void AllocExclusive(); // Returns data, increases refcount. wxPGChoicesData* GetData() { - wxASSERT( m_data->m_refCount != 0xFFFFFFF ); - m_data->m_refCount++; + wxASSERT( m_data->GetRefCount() != -1 ); + m_data->IncRef(); return m_data; } @@ -914,7 +1039,8 @@ public: #ifndef SWIG void operator= (const wxPGChoices& a) { - AssignData(a.m_data); + if (this != &a) + AssignData(a.m_data); } wxPGChoiceEntry& operator[](unsigned int i) @@ -954,39 +1080,21 @@ class WXDLLIMPEXP_PROPGRID wxPGProperty : public wxObject friend class wxPropertyGridPageState; friend class wxPropertyGridPopulator; friend class wxStringProperty; // Proper "" support requires this -#ifndef SWIG + DECLARE_ABSTRACT_CLASS(wxPGProperty) -#endif public: typedef wxUint32 FlagType; - /** Basic constructor. + /** + Default constructor. */ wxPGProperty(); - /** Constructor. - Non-abstract property classes should have constructor of this style: - - @code - - // If T is a class, then it should be a constant reference - // (e.g. const T& ) instead. - MyProperty( const wxString& label, const wxString& name, T value ) - : wxPGProperty() - { - // Generally recommended way to set the initial value - // (as it should work in pretty much 100% of cases). - wxVariant variant; - variant << value; - SetValue(variant); - - // If has private child properties then create them here, e.g.: - // AddChild( new wxStringProperty( "Subprop 1", - // wxPG_LABEL, - // value.GetSubProp1() ) ); - } + /** + Constructor. - @endcode + All non-abstract property classes should have a constructor with + the same first two arguments as this one. */ wxPGProperty( const wxString& label, const wxString& name ); @@ -1025,35 +1133,52 @@ public: wxPGValidationInfo& validationInfo ) const; /** - Converts 'text' into proper value 'variant'. - Returns true if new (different than m_value) value could be interpreted - from the text. + Converts text into wxVariant value appropriate for this property. + + @param variant + On function entry this is the old value (should not be wxNullVariant + in normal cases). Translated value must be assigned back to it. + + @param text + Text to be translated into variant. + @param argFlags If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable one (they may be different). If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of - composite property string value (as generated by GetValueAsString() + composite property string value (as generated by ValueToString() called with this same flag). - @remarks - Default implementation converts semicolon delimited tokens into child - values. Only works for properties with children. + @return Returns @true if resulting wxVariant value was different. + + @remarks Default implementation converts semicolon delimited tokens into + child values. Only works for properties with children. + + You might want to take into account that m_value is Null variant + if property value is unspecified (which is usually only case if + you explicitly enabled that sort behavior). */ virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags = 0 ) const; /** - Converts 'number' (including choice selection) into proper value - 'variant'. + Converts integer (possibly a choice selection) into wxVariant value + appropriate for this property. + + @param variant + On function entry this is the old value (should not be wxNullVariant + in normal cases). Translated value must be assigned back to it. - Returns true if new (different than m_value) value could be interpreted - from the integer. + @param number + Integer to be translated into variant. @param argFlags If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable one. + @return Returns @true if resulting wxVariant value was different. + @remarks - If property is not supposed to use choice or spinctrl or other editor with int-based value, it is not necessary to implement this method. @@ -1061,27 +1186,32 @@ public: - If property uses choice control, and displays a dialog on some choice items, then it is preferred to display that dialog in IntToValue instead of OnEvent. + - You might want to take into account that m_value is Null variant if + property value is unspecified (which is usually only case if you + explicitly enabled that sort behavior). */ virtual bool IntToValue( wxVariant& value, int number, int argFlags = 0 ) const; #endif // !defined(SWIG) || defined(CREATE_VCW) + /** + Converts property value into a text representation. -public: - /** Returns text representation of property's value. + @param value + Value to be converted. @param argFlags + If 0 (default value), then displayed string is returned. If wxPG_FULL_VALUE is set, returns complete, storable string value instead of displayable. If wxPG_EDITABLE_VALUE is set, returns string value that must be editable in textctrl. If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to - display as a part of composite property string value. + display as a part of string property's composite text + representation. - @remarks - Default implementation returns string composed from text - representations of child properties. + @remarks Default implementation calls GenerateComposedValue(). */ - virtual wxString GetValueAsString( int argFlags = 0 ) const; + virtual wxString ValueToString( wxVariant& value, int argFlags = 0 ) const; /** Converts string to a value, and if successful, calls SetValue() on it. Default behavior is to do nothing. @@ -1090,7 +1220,7 @@ public: @return true if value was changed. */ - bool SetValueFromString( const wxString& text, int flags = 0 ); + bool SetValueFromString( const wxString& text, int flags = wxPG_PROGRAMMATIC_VALUE ); /** Converts integer to a value, and if succesful, calls SetValue() on it. Default behavior is to do nothing. @@ -1145,17 +1275,21 @@ public: wxEvent& event ); /** - Called after value of a child property has been altered. + 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. + 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 @@ -1173,19 +1307,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. */ @@ -1264,7 +1407,7 @@ public: colour) pen for drawing framing rectangle. It can be changed as well. - @see GetValueAsString() + @see ValueToString() */ virtual void OnCustomPaint( wxDC& dc, const wxRect& rect, @@ -1318,18 +1461,14 @@ public: */ virtual wxPGEditorDialogAdapter* GetEditorDialog() const; - /** Returns wxPGCell of given column, NULL if none. If valid - object is returned, caller will gain its ownership. - */ - wxPGCell* AcquireCell( unsigned int column ) - { - if ( column >= m_cells.size() ) - return NULL; + /** + Called whenever validation has failed with given pending value. - wxPGCell* cell = (wxPGCell*) m_cells[column]; - m_cells[column] = NULL; - return cell; - } + @remarks If you implement this in your custom property class, please + remember to call the baser implementation as well, since they + may use it to revert property into pre-change state. + */ + virtual void OnValidationFailure( wxVariant& pendingValue ); /** Append a new choice to property's list of choices. */ @@ -1351,6 +1490,11 @@ public: return false; } + /** + Deletes children of the property. + */ + void DeleteChildren(); + /** Removes entry from property's wxPGChoices and editor control (if it is active). @@ -1372,8 +1516,15 @@ public: else ClearFlag( wxPG_PROP_USES_COMMON_VALUE ); } - /** Composes text from values of child properties. */ - void GenerateComposedValue( wxString& text, int argFlags = 0 ) const; + /** + Composes text from values of child properties. + */ + wxString GenerateComposedValue() const + { + wxString s; + DoGenerateComposedValue(s); + return s; + } /** Returns property's label. */ const wxString& GetLabel() const { return m_label; } @@ -1404,7 +1555,6 @@ public: return DoGetValue(); } -#ifndef SWIG /** Returns reference to the internal stored value. GetValue is preferred way to get the actual value, since GetValueRef ignores DoGetValue, which may override stored value. @@ -1418,34 +1568,69 @@ public: { return m_value; } -#endif - /** To acquire property's value as string, you should use this - function (instead of GetValueAsString()), as it may produce - more accurate value in future versions. + // Helper function (for wxPython bindings and such) for settings protected + // m_value. + wxVariant GetValuePlain() const + { + return m_value; + } + + /** Returns text representation of property's value. + + @param argFlags + If 0 (default value), then displayed string is returned. + If wxPG_FULL_VALUE is set, returns complete, storable string value + instead of displayable. If wxPG_EDITABLE_VALUE is set, returns + string value that must be editable in textctrl. If + wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to + display as a part of string property's composite text + representation. + + @remarks In older versions, this function used to be overridden to convert + property's value into a string representation. This function is + now handled by ValueToString(), and overriding this function now + will result in run-time assertion failure. */ - wxString GetValueString( int argFlags = 0 ) const; + virtual wxString GetValueAsString( int argFlags = 0 ) const; + + /** Synonymous to GetValueAsString(). - void UpdateControl( wxWindow* primary ); + @deprecated Use GetValueAsString() instead. - /** Returns wxPGCell of given column, NULL if none. wxPGProperty - will retain ownership of the cell object. + @see GetValueAsString() */ - wxPGCell* GetCell( unsigned int column ) const - { - if ( column >= m_cells.size() ) - return NULL; + wxDEPRECATED( wxString GetValueString( int argFlags = 0 ) const ); + + /** + Returns wxPGCell of given column. - return (wxPGCell*) m_cells[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 ) + { + return GetOrCreateCell(column); } + /** + Returns wxPGCell of given column, creating one if necessary. + */ + wxPGCell& GetOrCreateCell( unsigned int column ); + /** Return number of displayed common values for this property. */ int GetDisplayedCommonValueCount() const; wxString GetDisplayedString() const { - return GetValueString(0); + return GetValueAsString(0); } /** Returns property grid where property lies. */ @@ -1529,6 +1714,19 @@ public: */ bool HasVisibleChildren() const; + /** + Use this member function to add independent (ie. regular) children to + a property. + + @return Inserted childProperty. + + @remarks wxPropertyGrid is not automatically refreshed by this + function. + + @see AddPrivateChild() + */ + wxPGProperty* InsertChild( int index, wxPGProperty* childProperty ); + /** Inserts a new choice to property's list of choices. */ int InsertChoice( const wxString& label, int index, int value = wxPG_INVALID_VALUE ); @@ -1614,8 +1812,6 @@ public: */ double GetAttributeAsDouble( const wxString& name, double defVal ) const; - unsigned int GetArrIndex() const { return m_arrIndex; } - unsigned int GetDepth() const { return (unsigned int)m_depth; } /** Gets flags as a'|' delimited string. Note that flag names are not @@ -1668,6 +1864,42 @@ public: void SetAttributes( const wxPGAttributeStorage& attributes ); + /** + Sets property's background colour. + + @param colour + Background colour to use. + + @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, + int flags = wxPG_RECURSE ); + + /** + Sets property's text colour. + + @param colour + Text colour to use. + + @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, + int flags = wxPG_RECURSE ); + + /** Set default value of a property. Synonymous to + + @code + SetAttribute("DefaultValue", value); + @endcode + */ + void SetDefaultValue( wxVariant& value ); + #ifndef SWIG /** Sets editor for a property. @@ -1689,11 +1921,10 @@ public: */ inline void SetEditor( const wxString& editorName ); - /** Sets cell information for given column. - - Note that the property takes ownership of given wxPGCell instance. + /** + Sets cell information for given column. */ - void SetCell( int column, wxPGCell* cellObj ); + void SetCell( int column, const wxPGCell& cell ); /** Sets common value selected for this property. -1 for none. */ @@ -1737,26 +1968,21 @@ public: SetValueInEvent() instead. @param pList - Pointer to list variant that contains child values. Used to indicate - which children should be marked as modified. + Pointer to list variant that contains child values. Used to + indicate which children should be marked as modified. + @param flags - Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR). + Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR, which is + enabled by default). */ - void SetValue( wxVariant value, wxVariant* pList = NULL, int flags = 0 ); + void SetValue( wxVariant value, wxVariant* pList = NULL, + int flags = wxPG_SETVAL_REFRESH_EDITOR ); /** Set wxBitmap in front of the value. This bitmap may be ignored by custom cell renderers. */ void SetValueImage( wxBitmap& bmp ); - /** If property has choices and they are not yet exclusive, new such copy - of them will be created. - */ - void SetChoicesExclusive() - { - m_choices.SetExclusive(); - } - /** Sets selected choice and changes property value. Tries to retain value type, although currently if it is not string, @@ -1770,8 +1996,22 @@ public: else m_flags &= ~wxPG_PROP_COLLAPSED; } + /** + Sets given property flag(s). + */ void SetFlag( FlagType flag ) { m_flags |= flag; } + /** + Sets or clears given property flag(s). + */ + void ChangeFlag( FlagType flag, bool set ) + { + if ( set ) + m_flags |= flag; + else + m_flags &= ~flag; + } + void SetFlagRecursively( FlagType flag, bool set ); void SetHelpString( const wxString& helpString ) @@ -1781,7 +2021,24 @@ public: void SetLabel( const wxString& label ) { m_label = label; } - inline void SetName( const wxString& newName ); + void SetName( const wxString& newName ); + + /** + Changes what sort of parent this property is for its children. + + @param flag + Use one of the following values: wxPG_PROP_MISC_PARENT (for + generic parents), wxPG_PROP_CATEGORY (for categories), or + wxPG_PROP_AGGREGATE (for derived property classes with private + children). + + @remarks You generally do not need to call this function. + */ + void SetParentalType( int flag ) + { + m_flags &= ~(wxPG_PROP_PROPERTY|wxPG_PROP_PARENTAL_FLAGS); + m_flags |= flag; + } void SetValueToUnspecified() { @@ -1789,6 +2046,13 @@ public: SetValue(val); } + // Helper function (for wxPython bindings and such) for settings protected + // m_value. + void SetValuePlain( wxVariant value ) + { + m_value = value; + } + #if wxUSE_VALIDATORS /** Sets wxValidator for a property*/ void SetValidator( const wxValidator& validator ) @@ -1803,24 +2067,7 @@ public: return m_validator; return DoGetValidator(); } -#endif // #if wxUSE_VALIDATORS - - /** Updates property value in case there were last minute - changes. If value was unspecified, it will be set to default. - Use only for properties that have TextCtrl-based editor. - @remarks - If you have code similar to - @code - // Update the value in case of last minute changes - if ( primary && propgrid->IsEditorsValueModified() ) - GetEditorClass()->CopyValueFromControl( this, primary ); - @endcode - in wxPGProperty::OnEvent wxEVT_COMMAND_BUTTON_CLICKED handler, - then replace it with call to this method. - @return - True if value changed. - */ - bool PrepareValueForDialogEditing( wxPropertyGrid* propgrid ); +#endif // wxUSE_VALIDATORS #ifndef SWIG /** Returns client data (void*) of a property. @@ -1888,8 +2135,33 @@ public: */ void AdaptListToValue( wxVariant& list, wxVariant* value ) const; - /** This is used by properties that have fixed sub-properties. */ - void AddChild( wxPGProperty* prop ); +#if wxPG_COMPATIBILITY_1_4 + /** + Adds a private child property. + + @deprecated Use AddPrivateChild() instead. + + @see AddPrivateChild() + */ + wxDEPRECATED( void AddChild( wxPGProperty* prop ) ); +#endif + + /** + Adds a private child property. If you use this instead of + wxPropertyGridInterface::Insert() or + wxPropertyGridInterface::AppendIn(), then property's parental + type will automatically be set up to wxPG_PROP_AGGREGATE. In other + words, all properties of this property will become private. + */ + void AddPrivateChild( wxPGProperty* prop ); + + /** + Appends a new child property. + */ + wxPGProperty* AppendChild( wxPGProperty* prop ) + { + return InsertChild(-1, prop); + } /** Returns height of children, recursively, and by taking expanded/collapsed status into account. @@ -1899,69 +2171,58 @@ public: int GetChildrenHeight( int lh, int iMax = -1 ) const; /** Returns number of child properties */ - unsigned int GetChildCount() const { return m_children.GetCount(); } + unsigned int GetChildCount() const + { + return (unsigned int) m_children.size(); + } /** Returns sub-property at index i. */ - wxPGProperty* Item( size_t i ) const - { return (wxPGProperty*)m_children.Item(i); } + wxPGProperty* Item( unsigned int i ) const + { return m_children[i]; } /** Returns last sub-property. */ - wxPGProperty* Last() const { return (wxPGProperty*)m_children.Last(); } - - /** Returns index of given sub-property. */ - int Index( const wxPGProperty* p ) const - { return m_children.Index((wxPGProperty*)p); } + wxPGProperty* Last() const { return m_children.back(); } - /** Deletes all sub-properties. */ - void Empty(); + /** Returns index of given child property. */ + int Index( const wxPGProperty* p ) const; // Puts correct indexes to children - void FixIndexesOfChildren( size_t starthere = 0 ); + void FixIndicesOfChildren( unsigned int starthere = 0 ); + + /** + Converts image width into full image offset, with margins. + */ + int GetImageOffset( int imageWidth ) const; #ifndef SWIG // Returns wxPropertyGridPageState in which this property resides. wxPropertyGridPageState* GetParentState() const { return m_parentState; } #endif +#ifndef SWIG wxPGProperty* GetItemAtY( unsigned int y, unsigned int lh, unsigned int* nextItemY ) const; +#endif + + /** Returns property at given virtual y coordinate. + */ + wxPGProperty* GetItemAtY( unsigned int y ) const; /** Returns (direct) child property with given name (or NULL if not found). */ wxPGProperty* GetPropertyByName( const wxString& name ) const; -#ifdef SWIG - %extend { - DocStr(GetClientData, - "Returns the client data object for a property", ""); - PyObject* GetClientData() { - wxPyClientData* data = (wxPyClientData*)self->GetClientObject(); - if (data) { - Py_INCREF(data->m_obj); - return data->m_obj; - } else { - Py_INCREF(Py_None); - return Py_None; - } - } - - DocStr(SetClientData, - "Associate the given client data.", ""); - void SetClientData(PyObject* clientData) { - wxPyClientData* data = new wxPyClientData(clientData); - self->SetClientObject(data); - } - } - %pythoncode { - GetClientObject = GetClientData - SetClientObject = SetClientData - } -#endif - #ifndef SWIG + // Returns various display-related information for given column + void GetDisplayInfo( unsigned int column, + int choiceIndex, + int flags, + wxString* pString, + const wxPGCell** pCell ); + static wxString* sm_wxPG_LABEL; /** This member is public so scripting language bindings @@ -1970,9 +2231,49 @@ public: void* m_clientData; protected: - /** Returns text for given column. + + /** + Sets property cell in fashion that reduces number of exclusive + copies of cell data. Used when setting, for instance, same + background colour for a number of properties. + + @param firstCol + First column to affect. + + @param lastCol + Last column to affect. + + @param preparedCell + Pre-prepared cell that is used for those which cell data + before this matched unmodCellData. + + @param srcData + If unmodCellData did not match, valid cell data from this + is merged into cell (usually generating new exclusive copy + of cell's data). + + @param unmodCellData + If cell's cell data matches this, its cell is now set to + preparedCell. + + @param ignoreWithFlags + Properties with any one of these flags are skipped. + + @param recursively + If @true, apply this operation recursively in child properties. */ - wxString GetColumnText( unsigned int col ) const; + void AdaptiveSetCell( unsigned int firstCol, + unsigned int lastCol, + const wxPGCell& preparedCell, + const wxPGCell& srcData, + wxPGCellData* unmodCellData, + FlagType ignoreWithFlags, + bool recursively ); + + /** + Makes sure m_cells has size of column+1 (or more). + */ + void EnsureCells( unsigned int column ); /** Returns (direct) child property with given name (or NULL if not found), with hint index. @@ -1987,21 +2288,35 @@ protected: unsigned int hintIndex ) const; /** This is used by Insert etc. */ - void AddChild2( wxPGProperty* prop, - int index = -1, - bool correct_mode = true ); + void DoAddChild( wxPGProperty* prop, + int index = -1, + bool correct_mode = true ); + + void DoGenerateComposedValue( wxString& text, + int argFlags = wxPG_VALUE_IS_CURRENT, + const wxVariantList* valueOverrides = NULL, + wxPGHashMapS2S* childResults = NULL ) const; void DoSetName(const wxString& str) { m_name = str; } - // Call for after sub-properties added with AddChild - void PrepareSubProperties(); + /** Deletes all sub-properties. */ + void Empty(); - void SetParentalType( int flag ) + bool HasCell( unsigned int column ) const { - m_flags &= ~(wxPG_PROP_PROPERTY|wxPG_PROP_PARENTAL_FLAGS); - m_flags |= flag; + if ( m_cells.size() > column ) + return true; + return false; } + void InitAfterAdded( wxPropertyGridPageState* pageState, + wxPropertyGrid* propgrid ); + + // Removes child property with given pointer. Does not delete it. + void RemoveChild( wxPGProperty* p ); + + void DoPreAddChild( int index, wxPGProperty* prop ); + void SetParentState( wxPropertyGridPageState* pstate ) { m_parentState = pstate; } @@ -2015,7 +2330,7 @@ protected: wxString m_label; wxString m_name; wxPGProperty* m_parent; - wxPropertyGridPageState* m_parentState; + wxPropertyGridPageState* m_parentState; wxClientData* m_clientObject; @@ -2032,10 +2347,10 @@ protected: wxVariant m_value; wxPGAttributeStorage m_attributes; - wxArrayPtrVoid m_children; + wxArrayPGProperty m_children; // Extended cell information - wxArrayPtrVoid m_cells; + wxVector m_cells; // Choices shown in drop-down list of editor control. wxPGChoices m_choices; @@ -2064,9 +2379,6 @@ protected: // (essentially this is category's depth, if none then equals m_depth). unsigned char m_depthBgCol; - unsigned char m_bgColIndex; // Background brush index. - unsigned char m_fgColIndex; // Foreground colour index. - private: // Called in constructors. void Init(); @@ -2117,7 +2429,7 @@ public: public: /** Constructor. */ - wxPGRootProperty(); + wxPGRootProperty( const wxString& name = wxS("") ); virtual ~wxPGRootProperty(); virtual bool StringToValue( wxVariant&, const wxString&, int ) const @@ -2150,9 +2462,9 @@ public: int GetTextExtent( const wxWindow* wnd, const wxFont& font ) const; -protected: - virtual wxString GetValueAsString( int argFlags ) const; + virtual wxString ValueToString( wxVariant& value, int argFlags ) const; +protected: void SetTextColIndex( unsigned int colInd ) { m_capFgColIndex = (wxByte) colInd; } unsigned int GetTextColIndex() const