X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a09307abba7f837d8bdd8879fe2457efd32e01a8..9869c26285dc51d13607cddaa04f65ce983653a5:/include/wx/propgrid/property.h?ds=inline diff --git a/include/wx/propgrid/property.h b/include/wx/propgrid/property.h index 7c329b7d1c..36356ddd63 100644 --- a/include/wx/propgrid/property.h +++ b/include/wx/propgrid/property.h @@ -4,14 +4,15 @@ // Author: Jaakko Salli // Modified by: // Created: 2008-08-23 -// RCS-ID: $Id$ // Copyright: (c) Jaakko Salli -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// #ifndef _WX_PROPGRID_PROPERTY_H_ #define _WX_PROPGRID_PROPERTY_H_ +#include "wx/defs.h" + #if wxUSE_PROPGRID #include "wx/propgrid/propgriddefs.h" @@ -47,9 +48,6 @@ struct wxPGPaintData }; -#ifndef SWIG - - // space between vertical sides of a custom image #define wxPG_CUSTOM_IMAGE_SPACINGY 1 @@ -64,12 +62,12 @@ 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 @@ -98,7 +96,11 @@ public: DontUseCellBgCol }; - virtual void Render( wxDC& dc, + /** + Returns @true if rendered something in the foreground (text or + bitmap. + */ + virtual bool Render( wxDC& dc, const wxRect& rect, const wxPropertyGrid* propertyGrid, wxPGProperty* property, @@ -137,30 +139,53 @@ 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++; - } + /** + Utility to be called after drawing is done, to revert whatever + changes PreDrawCell() did. - void DecRef() - { - m_refCount--; - if ( !m_refCount ) - delete this; - } -protected: + @param flags + Same as those passed to PreDrawCell(). + */ + void PostDrawCell( wxDC& dc, + const wxPropertyGrid* propGrid, + const wxPGCell& cell, + int flags ) const; +}; -private: - unsigned int m_refCount; + +/** + @class wxPGDefaultRenderer + + Default cell renderer, that can handles the common + scenarios. +*/ +class WXDLLIMPEXP_PROPGRID wxPGDefaultRenderer : public wxPGCellRenderer +{ +public: + virtual bool Render( wxDC& dc, + const wxRect& rect, + const wxPropertyGrid* propertyGrid, + wxPGProperty* property, + int column, + int item, + int flags ) const; + + virtual wxSize GetImageSize( const wxPGProperty* property, + int column, + int item ) const; + +protected: }; @@ -178,6 +203,7 @@ public: void SetBitmap( const wxBitmap& bitmap ) { m_bitmap = bitmap; } void SetFgCol( const wxColour& col ) { m_fgCol = col; } void SetBgCol( const wxColour& col ) { m_bgCol = col; } + void SetFont( const wxFont& font ) { m_font = font; } protected: virtual ~wxPGCellData() { } @@ -186,14 +212,17 @@ protected: wxBitmap m_bitmap; wxColour m_fgCol; wxColour m_bgCol; + wxFont m_font; // True if m_text is valid and specified bool m_hasValidText; }; -/** @class wxPGCell - Base class for simple wxPropertyGrid cell information. +/** + @class wxPGCell + + Base class for wxPropertyGrid cell information. */ class WXDLLIMPEXP_PROPGRID wxPGCell : public wxObject { @@ -226,6 +255,11 @@ public: return (m_refData && GetData()->m_hasValidText); } + /** + Sets empty but valid data to this cell object. + */ + void SetEmptyData(); + /** Merges valid data from srcCell into this. */ @@ -234,11 +268,32 @@ public: 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 ) @@ -250,37 +305,20 @@ public: return *this; } -protected: + // Used mostly internally to figure out if this cell is supposed + // to have default values when attached to a grid. + bool IsInvalid() const + { + return ( m_refData == NULL ); + } + +private: virtual wxObjectRefData *CreateRefData() const { return new wxPGCellData(); } virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const; }; - -/** @class wxPGDefaultRenderer - - Default cell renderer, that can handles the common - scenarios. -*/ -class WXDLLIMPEXP_PROPGRID wxPGDefaultRenderer : public wxPGCellRenderer -{ -public: - virtual void Render( wxDC& dc, - const wxRect& rect, - const wxPropertyGrid* propertyGrid, - wxPGProperty* property, - int column, - int item, - int flags ) const; - - virtual wxSize GetImageSize( const wxPGProperty* property, - int column, - int item ) const; - -protected: -}; - // ----------------------------------------------------------------------- /** @class wxPGAttributeStorage @@ -330,7 +368,6 @@ protected: wxPGHashMapS2P m_map; }; -#endif // !SWIG // ----------------------------------------------------------------------- @@ -338,7 +375,7 @@ protected: @{ */ -enum wxPG_PROPERTY_FLAGS +enum wxPGPropertyFlags { /** Indicates bold font. @@ -372,8 +409,8 @@ wxPG_PROP_COLLAPSED = 0x0020, If property is selected, then indicates that validation failed for pending value. - If property is not selected, then indicates that the the actual property - value has failed validation (NB: this behavior is not currently supported, + If property is not selected, that indicates that the actual property + value has failed validation (NB: this behaviour is not currently supported, but may be used in future). */ wxPG_PROP_INVALID_VALUE = 0x0040, @@ -415,7 +452,9 @@ wxPG_PROP_CATEGORY = 0x2000, */ wxPG_PROP_MISC_PARENT = 0x4000, -/** Property is read-only. Editor is still created. +/** Property is read-only. Editor is still created for wxTextCtrl-based + property editors. For others, editor is not usually created because + they do implement wxTE_READONLY style or equivalent. */ wxPG_PROP_READONLY = 0x8000, @@ -442,6 +481,8 @@ wxPG_PROP_USES_COMMON_VALUE = 0x00020000, @remarks This flag cannot be used with property iterators. + + @see wxPGProperty::SetAutoUnspecified() */ wxPG_PROP_AUTO_UNSPECIFIED = 0x00040000, @@ -451,7 +492,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 }; @@ -464,7 +509,9 @@ wxPG_PROP_CLASS_SPECIFIC_2 = 0x00100000 Code should automatically take care of this, however. */ #define wxPG_PROP_PARENTAL_FLAGS \ - (wxPG_PROP_AGGREGATE|wxPG_PROP_CATEGORY|wxPG_PROP_MISC_PARENT) + ((wxPGPropertyFlags)(wxPG_PROP_AGGREGATE | \ + wxPG_PROP_CATEGORY | \ + wxPG_PROP_MISC_PARENT)) /** @} */ @@ -475,8 +522,6 @@ wxPG_PROP_CLASS_SPECIFIC_2 = 0x00100000 // ----------------------------------------------------------------------- -#ifndef SWIG - /** @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers. @@ -510,18 +555,40 @@ wxPG_PROP_CLASS_SPECIFIC_2 = 0x00100000 */ #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") + +#if wxPG_COMPATIBILITY_1_4 +/** + @deprecated Use "Hint" (wxPG_ATTR_HINT) instead. */ #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp") +#endif -/** 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") @@ -582,11 +649,25 @@ wxPG_PROP_CLASS_SPECIFIC_2 = 0x00100000 */ #define wxPG_FILE_DIALOG_TITLE wxS("DialogTitle") +/** Specific to wxFileProperty and derivatives, long, default is 0. + Sets a specific wxFileDialog style for the file dialog. +*/ +#define wxPG_FILE_DIALOG_STYLE wxS("DialogStyle") + /** Specific to wxDirProperty, wxString, default is empty. Sets a specific message for the dir dialog. */ #define wxPG_DIR_DIALOG_MESSAGE wxS("DialogMessage") +/** + wxArrayStringProperty's string delimiter character. If this is a quotation + mark or hyphen, then strings will be quoted instead (with given + character). + + Default delimiter is quotation mark. +*/ +#define wxPG_ARRAY_DELIMITER wxS("Delimiter") + /** Sets displayed date format for wxDateProperty. */ #define wxPG_DATE_FORMAT wxS("DateFormat") @@ -597,7 +678,7 @@ wxPG_PROP_CLASS_SPECIFIC_2 = 0x00100000 #define wxPG_DATE_PICKER_STYLE wxS("PickerStyle") /** SpinCtrl editor, int or double. How much number changes when button is - pressed (or up/down on keybard). + pressed (or up/down on keyboard). */ #define wxPG_ATTR_SPINCTRL_STEP wxS("Step") @@ -620,25 +701,33 @@ wxPG_PROP_CLASS_SPECIFIC_2 = 0x00100000 */ #define wxPG_COLOUR_ALLOW_CUSTOM wxS("AllowCustom") +/** + wxColourProperty and its kind: Set to True in order to support editing + alpha colour component. +*/ +#define wxPG_COLOUR_HAS_ALPHA wxS("HasAlpha") + /** @} */ // 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 #define wxPG_ATTR_MAX wxPGGlobalVars->m_strMax #undef wxPG_ATTR_UNITS #define wxPG_ATTR_UNITS wxPGGlobalVars->m_strUnits +#undef wxPG_ATTR_HINT +#define wxPG_ATTR_HINT wxPGGlobalVars->m_strHint +#if wxPG_COMPATIBILITY_1_4 #undef wxPG_ATTR_INLINE_HELP #define wxPG_ATTR_INLINE_HELP wxPGGlobalVars->m_strInlineHelp - -#endif // !SWIG +#endif // ----------------------------------------------------------------------- -#ifndef SWIG - /** @class wxPGChoiceEntry Data of a single wxPGChoices choice. */ @@ -680,7 +769,7 @@ protected: typedef void* wxPGChoicesId; -class WXDLLIMPEXP_PROPGRID wxPGChoicesData +class WXDLLIMPEXP_PROPGRID wxPGChoicesData : public wxObjectRefData { friend class wxPGChoices; public: @@ -711,26 +800,14 @@ public: return m_items[i]; } - void DecRef() - { - m_refCount--; - wxASSERT( m_refCount >= 0 ); - if ( m_refCount == 0 ) - delete this; - } - private: wxVector m_items; - // So that multiple properties can use the same set - int m_refCount; - virtual ~wxPGChoicesData(); }; #define wxPGChoicesEmptyData ((wxPGChoicesData*)NULL) -#endif // SWIG /** @class wxPGChoices @@ -738,6 +815,11 @@ 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} @@ -754,13 +836,16 @@ 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(); } } @@ -773,7 +858,7 @@ public: @param values Values for choices. If NULL, indexes are used. */ - wxPGChoices( const wxChar** labels, const long* values = NULL ) + wxPGChoices( const wxChar* const* labels, const long* values = NULL ) { Init(); Set(labels,values); @@ -800,7 +885,7 @@ public: { wxASSERT(data); m_data = data; - data->m_refCount++; + data->IncRef(); } /** Destructor. */ @@ -821,7 +906,7 @@ public: @param values Values for added choices. If empty, relevant entry indexes are used. */ - void Add( const wxChar** labels, const ValArrItem* values = NULL ); + 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 = wxArrayInt() ); @@ -853,6 +938,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); @@ -861,10 +950,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() @@ -874,7 +970,7 @@ public: } /** Gets a unsigned number identifying this list. */ - wxPGChoicesId GetId() const { return (wxPGChoicesId) m_data; }; + wxPGChoicesId GetId() const { return (wxPGChoicesId) m_data; } const wxString& GetLabel( unsigned int ind ) const { @@ -936,14 +1032,14 @@ public: /** Removes count items starting at position nIndex. */ void RemoveAt(size_t nIndex, size_t count = 1); -#ifndef SWIG - /** Does not create copies for itself. */ - void Set( const wxChar** labels, const long* values = NULL ) + /** Does not create copies for itself. + TODO: Deprecate. + */ + void Set( const wxChar* const* labels, const long* values = NULL ) { Free(); Add(labels,values); } -#endif // SWIG /** Version that works with wxArrayString and wxArrayInt. */ void Set( const wxArrayString& labels, @@ -957,22 +1053,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; } @@ -989,7 +1076,6 @@ public: wxArrayString GetLabels() const; -#ifndef SWIG void operator= (const wxPGChoices& a) { if (this != &a) @@ -1011,7 +1097,6 @@ protected: void Init(); void Free(); -#endif // !SWIG }; // ----------------------------------------------------------------------- @@ -1033,43 +1118,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. Also - // set flag that indicates presence of private children. E.g.: - // - // SetParentalType(wxPG_PROP_AGGREGATE); - // - // 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 ); @@ -1096,7 +1159,6 @@ public: */ virtual wxVariant DoGetValue() const { return m_value; } -#if !defined(SWIG) || defined(CREATE_VCW) /** Implement this function in derived class to check the value. Return true if it is ok. Returning false prevents property change events from occurring. @@ -1131,7 +1193,7 @@ public: 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). + you explicitly enabled that sort behaviour). */ virtual bool StringToValue( wxVariant& variant, const wxString& text, @@ -1163,12 +1225,12 @@ public: 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). + explicitly enabled that sort behaviour). */ virtual bool IntToValue( wxVariant& value, int number, int argFlags = 0 ) const; -#endif // !defined(SWIG) || defined(CREATE_VCW) + /** Converts property value into a text representation. @@ -1189,7 +1251,7 @@ public: 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. + Default behaviour is to do nothing. @param text String to get the value from. @return @@ -1197,8 +1259,8 @@ public: */ 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. + /** Converts integer to a value, and if successful, calls SetValue() on it. + Default behaviour is to do nothing. @param value Int to get the value from. @param flags @@ -1217,7 +1279,7 @@ public: @param item Normally -1, but can be an index to the property's list of items. @remarks - - Default behavior is to return wxSize(0,0), which means no image. + - Default behaviour is to return wxSize(0,0), which means no image. - Default image width or height is indicated with dimension -1. - You can also return wxPG_DEFAULT_IMAGE_SIZE, i.e. wxSize(-1, -1). */ @@ -1230,7 +1292,7 @@ public: button press events of TextCtrlAndButton class, can be handled here. Also, if custom handling for regular events is desired, then that can also be done (for example, wxSystemColourProperty custom handles - wxEVT_COMMAND_CHOICE_SELECTED to display colour picker dialog when + wxEVT_CHOICE to display colour picker dialog when 'custom' selection is made). If the event causes value to be changed, SetValueInEvent() @@ -1250,17 +1312,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 warranted 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 @@ -1278,19 +1344,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. */ @@ -1398,12 +1473,16 @@ 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 ); @@ -1423,6 +1502,15 @@ public: */ virtual wxPGEditorDialogAdapter* GetEditorDialog() const; + /** + Called whenever validation has failed with given pending value. + + @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. */ int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE ) @@ -1443,6 +1531,11 @@ public: return false; } + /** + Deletes children of the property. + */ + void DeleteChildren(); + /** Removes entry from property's wxPGChoices and editor control (if it is active). @@ -1451,6 +1544,17 @@ public: */ void DeleteChoice( int index ); + /** + Enables or disables the property. Disabled property usually appears + as having grey text. + + @param enable + If @false, property is disabled instead. + + @see wxPropertyGridInterface::EnableProperty() + */ + void Enable( bool enable = true ); + /** Call to enable or disable usage of common value (integer value that can be selected for properties instead of their normal values) for this @@ -1503,7 +1607,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. @@ -1517,7 +1620,13 @@ public: { return m_value; } -#endif + + // 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. @@ -1545,14 +1654,27 @@ public: */ wxDEPRECATED( wxString GetValueString( int argFlags = 0 ) const ); - void UpdateControl( wxWindow* primary ); - /** 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; - wxPGCell& GetCell( unsigned int column ); + /** + 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. */ @@ -1563,6 +1685,11 @@ public: return GetValueAsString(0); } + /** + Returns property's hint text (shown in empty value cell). + */ + inline wxString GetHintText() const; + /** Returns property grid where property lies. */ wxPropertyGrid* GetGrid() const; @@ -1584,7 +1711,7 @@ public: /** Returns true if property has editable wxTextCtrl when selected. @remarks - Altough disabled properties do not displayed editor, they still + Although disabled properties do not displayed editor, they still return True here as being disabled is considered a temporary condition (unlike being read-only or having limited editing enabled). */ @@ -1595,7 +1722,12 @@ public: return m_value.IsNull(); } - FlagType HasFlag( FlagType flag ) const + /** + Returns non-zero if property has given flag set. + + @see propgrid_propflags + */ + FlagType HasFlag( wxPGPropertyFlags flag ) const { return ( m_flags & flag ); } @@ -1611,6 +1743,9 @@ public: */ wxVariant GetAttributesAsList() const; + /** + Returns property flags. + */ FlagType GetFlags() const { return m_flags; @@ -1644,6 +1779,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 ); @@ -1751,7 +1899,7 @@ public: By default changes are applied recursively. Set this paramter wxPG_DONT_RECURSE to prevent this. */ - inline bool Hide( bool hide, int flags = wxPG_RECURSE ); + bool Hide( bool hide, int flags = wxPG_RECURSE ); bool IsExpanded() const { return (!(m_flags & wxPG_PROP_COLLAPSED) && GetChildCount()); } @@ -1781,18 +1929,34 @@ public: void SetAttributes( const wxPGAttributeStorage& attributes ); + /** + Set if user can change the property's value to unspecified by + modifying the value of the editor control (usually by clearing + it). Currently, this can work with following properties: + wxIntProperty, wxUIntProperty, wxFloatProperty, wxEditEnumProperty. + + @param enable + Whether to enable or disable this behaviour (it is disabled by + default). + */ + void SetAutoUnspecified( bool enable = true ) + { + ChangeFlag(wxPG_PROP_AUTO_UNSPECIFIED, enable); + } + /** Sets property's background colour. @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 property's text colour. @@ -1800,14 +1964,22 @@ 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 ); + + /** Set default value of a property. Synonymous to + + @code + SetAttribute("DefaultValue", value); + @endcode + */ + void SetDefaultValue( wxVariant& value ); -#ifndef SWIG /** Sets editor for a property. @param editor @@ -1822,7 +1994,6 @@ public: { m_customEditor = editor; } -#endif /** Sets editor for a property. */ @@ -1875,26 +2046,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, @@ -1908,9 +2074,31 @@ public: else m_flags &= ~wxPG_PROP_COLLAPSED; } - void SetFlag( FlagType flag ) { m_flags |= flag; } + /** + Sets or clears given property flag. Mainly for internal use. + + @remarks Setting a property flag never has any side-effect, and is + intended almost exclusively for internal use. So, for + example, if you want to disable a property, call + Enable(false) instead of setting wxPG_PROP_DISABLED flag. + + @see HasFlag(), GetFlags() + */ + void ChangeFlag( wxPGPropertyFlags flag, bool set ) + { + if ( set ) + m_flags |= flag; + else + m_flags &= ~flag; + } + + /** + Sets or clears given property flag, recursively. This function is + primarily intended for internal use. - void SetFlagRecursively( FlagType flag, bool set ); + @see ChangeFlag() + */ + void SetFlagRecursively( wxPGPropertyFlags flag, bool set ); void SetHelpString( const wxString& helpString ) { @@ -1919,22 +2107,18 @@ 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 + 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 only need to call this if you use AddChild() to add - child properties. Adding properties with - wxPropertyGridInterface::Insert() or - wxPropertyGridInterface::AppendIn() will automatically set - property to use wxPG_PROP_MISC_PARENT style. + @remarks You generally do not need to call this function. */ void SetParentalType( int flag ) { @@ -1945,7 +2129,14 @@ public: void SetValueToUnspecified() { wxVariant val; // Create NULL variant - SetValue(val); + SetValue(val, NULL, wxPG_SETVAL_REFRESH_EDITOR); + } + + // Helper function (for wxPython bindings and such) for settings protected + // m_value. + void SetValuePlain( wxVariant value ) + { + m_value = value; } #if wxUSE_VALIDATORS @@ -1962,9 +2153,8 @@ public: return m_validator; return DoGetValidator(); } -#endif // #if wxUSE_VALIDATORS +#endif // wxUSE_VALIDATORS -#ifndef SWIG /** Returns client data (void*) of a property. */ void* GetClientData() const @@ -1992,14 +2182,14 @@ public: /** Sets managed client object of a property. */ wxClientData *GetClientObject() const { return m_clientObject; } -#endif - /** Sets new set of choices for property. + /** + Sets new set of choices for the property. - @remarks - This operation clears the property value. + @remarks This operation deselects the property and clears its + value. */ - bool SetChoices( wxPGChoices& choices ); + bool SetChoices( const wxPGChoices& choices ); /** Set max length of text in text editor. */ @@ -2019,8 +2209,6 @@ public: return m_helpString; } - void ClearFlag( FlagType flag ) { m_flags &= ~(flag); } - // Use, for example, to detect if item is inside collapsed section. bool IsSomeParent( wxPGProperty* candidate_parent ) const; @@ -2030,24 +2218,33 @@ public: */ void AdaptListToValue( wxVariant& list, wxVariant* value ) const; +#if wxPG_COMPATIBILITY_1_4 + /** + Adds a private child property. + + @deprecated Use AddPrivateChild() instead. + + @see AddPrivateChild() + */ + wxDEPRECATED( void AddChild( wxPGProperty* prop ) ); +#endif + /** - Adds a child property. If you use this instead of + Adds a private child property. If you use this instead of wxPropertyGridInterface::Insert() or - wxPropertyGridInterface::AppendIn(), then you must set up - property's parental type before making the call. To do this, - call property's SetParentalType() function with either - wxPG_PROP_MISC_PARENT (normal, public children) or with - wxPG_PROP_AGGREGATE (private children for subclassed property). - For instance: + 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 ); - @code - wxPGProperty* prop = new wxStringProperty(wxS("Property")); - prop->SetParentalType(wxPG_PROP_MISC_PARENT); - wxPGProperty* prop2 = new wxStringProperty(wxS("Property2")); - prop->AddChild(prop2); - @endcode + /** + Appends a new child property. */ - void AddChild( wxPGProperty* prop ); + wxPGProperty* AppendChild( wxPGProperty* prop ) + { + return InsertChild(-1, prop); + } /** Returns height of children, recursively, and by taking expanded/collapsed status into account. @@ -2073,55 +2270,29 @@ public: /** Returns index of given child property. */ int Index( const wxPGProperty* p ) const; - /** Deletes all sub-properties. */ - void Empty(); - // Puts correct indexes to children void FixIndicesOfChildren( unsigned int starthere = 0 ); -#ifndef SWIG + /** + Converts image width into full image offset, with margins. + */ + int GetImageOffset( int imageWidth ) const; + // Returns wxPropertyGridPageState in which this property resides. wxPropertyGridPageState* GetParentState() const { return m_parentState; } -#endif wxPGProperty* GetItemAtY( unsigned int y, unsigned int lh, unsigned int* nextItemY ) const; + /** 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, @@ -2194,26 +2365,63 @@ 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; + bool DoHide( bool hide, int flags ); + void DoSetName(const wxString& str) { m_name = str; } + /** Deletes all sub-properties. */ + void Empty(); + + bool HasCell( unsigned int column ) const + { + if ( m_cells.size() > column ) + return true; + return false; + } + void InitAfterAdded( wxPropertyGridPageState* pageState, wxPropertyGrid* propgrid ); + /** + Returns true if child property is selected. + */ + bool IsChildSelected( bool recursive = false ) const; + // Removes child property with given pointer. Does not delete it. void RemoveChild( wxPGProperty* p ); + void DoEnable( bool enable ); + + void DoPreAddChild( int index, wxPGProperty* prop ); + void SetParentState( wxPropertyGridPageState* pstate ) { m_parentState = pstate; } + void SetFlag( wxPGPropertyFlags flag ) + { + // + // NB: While using wxPGPropertyFlags here makes it difficult to + // combine different flags, it usefully prevents user from + // using incorrect flags (say, wxWindow styles). + m_flags |= flag; + } + + void ClearFlag( FlagType flag ) { m_flags &= ~(flag); } + + // Called when the property is being removed from the grid and/or + // page state (but *not* when it is also deleted). + void OnDetached(wxPropertyGridPageState* state, + wxPropertyGrid* propgrid); + // Call after fixed sub-properties added/removed after creation. // if oldSelInd >= 0 and < new max items, then selection is // moved to it. @@ -2277,7 +2485,6 @@ private: // Called in constructors. void Init(); void Init( const wxString& label, const wxString& name ); -#endif // #ifndef SWIG }; // ----------------------------------------------------------------------- @@ -2290,14 +2497,12 @@ private: #define WX_PG_DECLARE_DOGETEDITORCLASS \ virtual const wxPGEditor* DoGetEditorClass() const; -#ifndef SWIG +#ifndef WX_PG_DECLARE_PROPERTY_CLASS #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME) \ public: \ DECLARE_DYNAMIC_CLASS(CLASSNAME) \ WX_PG_DECLARE_DOGETEDITORCLASS \ private: -#else - #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME) #endif // Implements sans constructor function. Also, first arg is class name, not @@ -2310,8 +2515,6 @@ const wxPGEditor* PROPNAME::DoGetEditorClass() const \ // ----------------------------------------------------------------------- -#ifndef SWIG - /** @class wxPGRootProperty @ingroup classes Root parent property. @@ -2323,7 +2526,7 @@ public: public: /** Constructor. */ - wxPGRootProperty(); + wxPGRootProperty( const wxString& name = wxS("") ); virtual ~wxPGRootProperty(); virtual bool StringToValue( wxVariant&, const wxString&, int ) const @@ -2357,6 +2560,7 @@ public: int GetTextExtent( const wxWindow* wnd, const wxFont& font ) const; virtual wxString ValueToString( wxVariant& value, int argFlags ) const; + virtual wxString GetValueAsString( int argFlags = 0 ) const; protected: void SetTextColIndex( unsigned int colInd ) @@ -2373,8 +2577,6 @@ private: void Init(); }; -#endif // !SWIG - // ----------------------------------------------------------------------- #endif // wxUSE_PROPGRID