X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/573cdf43af3ca0ad034974a1bd4fb33fcafac21c..c39058f631b3a53682f00807a60bfff6c5aa2b7c:/include/wx/propgrid/property.h diff --git a/include/wx/propgrid/property.h b/include/wx/propgrid/property.h index 593de4b467..ff2d2d5377 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 ///////////////////////////////////////////////////////////////////////////// @@ -47,13 +47,6 @@ struct wxPGPaintData }; -// Structure for relaying choice/list info. -struct wxPGChoiceInfo -{ - wxPGChoices* m_choices; -}; - - #ifndef SWIG @@ -222,7 +215,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); @@ -567,1633 +560,1649 @@ wxPG_PROP_CLASS_SPECIFIC_2 = 0x00100000 // ----------------------------------------------------------------------- -/** @class wxPGProperty - - wxPGProperty is base class for all wxPropertyGrid properties. - - NB: Full class overview is now only present in - interface/wx/propgrid/property.h. +#ifndef SWIG - @library{wxpropgrid} - @category{propgrid} +/** @class wxPGChoiceEntry + Data of a single wxPGChoices choice. */ -class WXDLLIMPEXP_PROPGRID wxPGProperty : public wxObject +class WXDLLIMPEXP_PROPGRID wxPGChoiceEntry : public wxPGCell { - friend class wxPropertyGrid; - friend class wxPropertyGridInterface; - friend class wxPropertyGridPageState; - friend class wxPropertyGridPopulator; - friend class wxStringProperty; // Proper "" support requires this -#ifndef SWIG - DECLARE_ABSTRACT_CLASS(wxPGProperty) -#endif public: - typedef wxUint32 FlagType; + wxPGChoiceEntry(); + wxPGChoiceEntry( const wxPGChoiceEntry& entry ); + wxPGChoiceEntry( const wxString& label, + int value = wxPG_INVALID_VALUE ) + : wxPGCell(), m_value(value) + { + m_text = label; + } - /** Basic constructor. - */ - wxPGProperty(); + 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) + { + } - /** Constructor. - Non-abstract property classes should have constructor of this style: + virtual ~wxPGChoiceEntry() + { + } - @code + void SetValue( int value ) { m_value = value; } - // 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); + int GetValue() const { return m_value; } - // If has private child properties then create them here, e.g.: - // AddChild( new wxStringProperty( "Subprop 1", - // wxPG_LABEL, - // value.GetSubProp1() ) ); - } + bool HasValue() const { return (m_value != wxPG_INVALID_VALUE); } - @endcode - */ - wxPGProperty( const wxString& label, const wxString& name ); +protected: + int m_value; +}; - /** - Virtual destructor. - It is customary for derived properties to implement this. - */ - virtual ~wxPGProperty(); - /** This virtual function is called after m_value has been set. +typedef void* wxPGChoicesId; - @remarks - - If m_value was set to Null variant (ie. unspecified value), - OnSetValue() will not be called. - - m_value may be of any variant type. Typically properties internally - support only one variant type, and as such OnSetValue() provides a - good opportunity to convert - supported values into internal type. - - Default implementation does nothing. - */ - virtual void OnSetValue(); +class WXDLLIMPEXP_PROPGRID wxPGChoicesData +{ + friend class wxPGChoices; +public: + // Constructor sets m_refCount to 1. + wxPGChoicesData(); - /** Override this to return something else than m_value as the value. - */ - virtual wxVariant DoGetValue() const { return m_value; } + void CopyDataFrom( wxPGChoicesData* data ); -#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. + // Takes ownership of 'item' + void Insert( int index, wxPGChoiceEntry* item ) + { + wxVector::iterator it; + if ( index == -1 ) + { + it = m_items.end(); + index = (int) m_items.size(); + } + else + { + it = m_items.begin() + index; + } - @remarks - - Default implementation always returns true. - */ - virtual bool ValidateValue( wxVariant& value, - wxPGValidationInfo& validationInfo ) const; + // Need to fix value? + if ( item->GetValue() == wxPG_INVALID_VALUE ) + item->SetValue(index); - /** - Converts 'text' into proper value 'variant'. - Returns true if new (different than m_value) value could be interpreted - from the text. - @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() - called with this same flag). + m_items.insert(it, item); + } - @remarks - Default implementation converts semicolon delimited tokens into child - values. Only works for properties with children. - */ - virtual bool StringToValue( wxVariant& variant, - const wxString& text, - int argFlags = 0 ) const; + // Delete all entries + void Clear(); - /** - Converts 'number' (including choice selection) into proper value - 'variant'. + unsigned int GetCount() const + { + return (unsigned int) m_items.size(); + } - Returns true if new (different than m_value) value could be interpreted - from the integer. + wxPGChoiceEntry* Item( unsigned int i ) const + { + wxCHECK_MSG( i < GetCount(), NULL, "invalid index" ); - @param argFlags - If wxPG_FULL_VALUE is set, returns complete, storable value instead - of displayable one. + return m_items[i]; + } - @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. - - Default implementation simply assign given int to m_value. - - 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. - */ - virtual bool IntToValue( wxVariant& value, - int number, - int argFlags = 0 ) const; -#endif // !defined(SWIG) || defined(CREATE_VCW) + void DecRef() + { + m_refCount--; + wxASSERT( m_refCount >= 0 ); + if ( m_refCount == 0 ) + delete this; + } -public: - /** Returns text representation of property's value. +private: + wxVector m_items; - @param argFlags - 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. + // So that multiple properties can use the same set + int m_refCount; - @remarks - Default implementation returns string composed from text - representations of child properties. - */ - virtual wxString GetValueAsString( int argFlags = 0 ) const; + virtual ~wxPGChoicesData(); +}; - /** Converts string to a value, and if successful, calls SetValue() on it. - Default behavior is to do nothing. - @param text - String to get the value from. - @return - true if value was changed. - */ - bool SetValueFromString( const wxString& text, int flags = 0 ); +#define wxPGChoicesEmptyData ((wxPGChoicesData*)NULL) - /** Converts integer to a value, and if succesful, calls SetValue() on it. - Default behavior is to do nothing. - @param value - Int to get the value from. - @param flags - If has wxPG_FULL_VALUE, then the value given is a actual value and - not an index. - @return - True if value was changed. - */ - bool SetValueFromInt( long value, int flags = 0 ); +#endif // SWIG - /** - Returns size of the custom painted image in front of property. +/** @class wxPGChoices - This method must be overridden to return non-default value if - OnCustomPaint is to be called. - @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 image width or height is indicated with dimension -1. - - You can also return wxPG_DEFAULT_IMAGE_SIZE, i.e. wxSize(-1, -1). - */ - virtual wxSize OnMeasureImage( int item = -1 ) const; + Helper class for managing choices of wxPropertyGrid properties. + Each entry can have label, value, bitmap, text colour, and background + colour. - /** - Events received by editor widgets are processed here. + @library{wxpropgrid} + @category{propgrid} +*/ +class WXDLLIMPEXP_PROPGRID wxPGChoices +{ +public: + typedef long ValArrItem; - Note that editor class usually processes most events. Some, such as - 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 - 'custom' selection is made). + /** Default constructor. */ + wxPGChoices() + { + Init(); + } - If the event causes value to be changed, SetValueInEvent() - should be called to set the new value. + /** Copy constructor. */ + wxPGChoices( const wxPGChoices& a ) + { + if ( a.m_data != wxPGChoicesEmptyData ) + { + m_data = a.m_data; + m_data->m_refCount++; + } + } - @param event - Associated wxEvent. - @return - Should return true if any changes in value should be reported. - @remarks - 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. - */ - 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. + /** Constructor. */ + wxPGChoices( const wxChar** labels, const long* values = NULL ) + { + Init(); + Set(labels,values); + } - Sample pseudo-code implementation: + /** Constructor. */ + wxPGChoices( const wxArrayString& labels, + const wxArrayInt& values = wxArrayInt() ) + { + Init(); + Set(labels,values); + } - @code - void 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). - T& data = TFromVariant(thisValue); + /** Simple interface constructor. */ + wxPGChoices( wxPGChoicesData* data ) + { + wxASSERT(data); + m_data = data; + data->m_refCount++; + } - // Copy childValue into data. - switch ( childIndex ) - { - case 0: - data.SetSubProp1( childvalue.GetLong() ); - break; - case 1: - data.SetSubProp2( childvalue.GetString() ); - break; - ... - } - } - @endcode + /** Destructor. */ + ~wxPGChoices() + { + Free(); + } - @param thisValue - Value of this property, that should be altered. - @param childIndex - Index of child changed (you can use Item(childIndex) to get). - @param childValue - Value of the child property. - */ - virtual void ChildChanged( wxVariant& thisValue, - int childIndex, - wxVariant& childValue ) const; + /** + Adds to current. - /** Returns pointer to an instance of used editor. + If did not have own copies, creates them now. If was empty, identical + to set except that creates copies. */ - virtual const wxPGEditor* DoGetEditorClass() const; - - /** Returns pointer to the wxValidator that should be used - with the editor of this property (NULL for no validator). - Setting validator explicitly via SetPropertyValidator - will override this. - - In most situations, code like this should work well - (macros are used to maintain one actual validator instance, - so on the second call the function exits within the first - macro): + void Add( const wxChar** labels, const ValArrItem* values = NULL ); - @code + /** Version that works with wxArrayString. */ + void Add( const wxArrayString& arr, const ValArrItem* values = NULL ); - wxValidator* wxMyPropertyClass::DoGetValidator () const - { - WX_PG_DOGETVALIDATOR_ENTRY() + /** Version that works with wxArrayString and wxArrayInt. */ + void Add( const wxArrayString& arr, const wxArrayInt& arrint ); - wxMyValidator* validator = new wxMyValidator(...); + /** Adds single item. */ + wxPGChoiceEntry& Add( const wxString& label, + int value = wxPG_INVALID_VALUE ); - ... prepare validator... + /** Adds a single item, with bitmap. */ + wxPGChoiceEntry& Add( const wxString& label, + const wxBitmap& bitmap, + int value = wxPG_INVALID_VALUE ); - WX_PG_DOGETVALIDATOR_EXIT(validator) - } + /** Adds a single item with full entry information. */ + wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry ) + { + return Insert(entry, -1); + } - @endcode + /** Adds single item. */ + wxPGChoiceEntry& AddAsSorted( const wxString& label, + int value = wxPG_INVALID_VALUE ); - @remarks - You can get common filename validator by returning - wxFileProperty::GetClassValidator(). wxDirProperty, - for example, uses it. - */ - virtual wxValidator* DoGetValidator () const; + void Assign( const wxPGChoices& a ) + { + AssignData(a.m_data); + } - /** - Returns current value's index to the choice control. + void AssignData( wxPGChoicesData* data ); - May also return, through pointer arguments, strings that should be - inserted to that control. Irrelevant to classes which do not employ - wxPGEditor_Choice or similar. + /** Delete all choices. */ + void Clear() + { + if ( m_data != wxPGChoicesEmptyData ) + m_data->Clear(); + } - @remarks - - If returns NULL in choiceinfo.m_choices, then this class must be - derived from wxBaseEnumProperty. - - Must be able to cope situation where property's set of choices is - uninitialized. - */ - virtual int GetChoiceInfo( wxPGChoiceInfo* choiceinfo ); + void EnsureData() + { + if ( m_data == wxPGChoicesEmptyData ) + m_data = new wxPGChoicesData(); + } - /** - Override to paint an image in front of the property value text or - drop-down list item (but only if wxPGProperty::OnMeasureImage is - overridden as well). + /** Gets a unsigned number identifying this list. */ + wxPGChoicesId GetId() const { return (wxPGChoicesId) m_data; }; - If property's OnMeasureImage() returns size that has height != 0 but - less than row height ( < 0 has special meanings), wxPropertyGrid calls - this method to draw a custom image in a limited area in front of the - editor control or value text/graphics, and if control has drop-down - list, then the image is drawn there as well (even in the case - OnMeasureImage() returned higher height than row height). + const wxString& GetLabel( unsigned int ind ) const + { + return Item(ind).GetText(); + } - NOTE: Following applies when OnMeasureImage() returns a "flexible" - height ( using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable - height items: If rect.x is < 0, then this is a measure item call, which - means that dc is invalid and only thing that should be done is to set - paintdata.m_drawnHeight to the height of the image of item at index - paintdata.m_choiceItem. This call may be done even as often as once - every drop-down popup show. + unsigned int GetCount () const + { + if ( !m_data ) + return 0; - @param dc - wxDC to paint on. - @param rect - Box reserved for custom graphics. Includes surrounding rectangle, - if any. If x is < 0, then this is a measure item call (see above). - @param paintdata - wxPGPaintData structure with much useful data. + return m_data->GetCount(); + } - @remarks - - You can actually exceed rect width, but if you do so then - paintdata.m_drawnWidth must be set to the full width drawn in - pixels. - - Due to technical reasons, rect's height will be default even if - custom height was reported during measure call. - - Brush is guaranteed to be default background colour. It has been - already used to clear the background of area being painted. It - can be modified. - - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper - colour) pen for drawing framing rectangle. It can be changed as - well. + int GetValue( unsigned int ind ) const { return Item(ind).GetValue(); } - @see GetValueAsString() + /** Returns array of values matching the given strings. Unmatching strings + result in wxPG_INVALID_VALUE entry in array. */ - virtual void OnCustomPaint( wxDC& dc, - const wxRect& rect, - wxPGPaintData& paintdata ); + wxArrayInt GetValuesForStrings( const wxArrayString& strings ) const; - /** - Returns used wxPGCellRenderer instance for given property column - (label=0, value=1). + /** Returns array of indices matching given strings. Unmatching strings + are added to 'unmatched', if not NULL. + */ + wxArrayInt GetIndicesForStrings( const wxArrayString& strings, + wxArrayString* unmatched = NULL ) const; - Default implementation returns editor's renderer for all columns. + /** Returns true if choices in general are likely to have values + (depens on that all entries have values or none has) */ - virtual wxPGCellRenderer* GetCellRenderer( int column ) const; + bool HasValues() const; - /** - Refresh values of child properties. + bool HasValue( unsigned int i ) const + { return (i < m_data->GetCount()) && m_data->Item(i)->HasValue(); } - Automatically called after value is set. - */ - virtual void RefreshChildren(); + int Index( const wxString& str ) const; + int Index( int val ) const; - /** Special handling for attributes of this property. + /** Inserts single item. */ + wxPGChoiceEntry& Insert( const wxString& label, + int index, + int value = wxPG_INVALID_VALUE ); - If returns false, then the attribute will be automatically stored in - m_attributes. + /** Inserts a single item with full entry information. */ + wxPGChoiceEntry& Insert( const wxPGChoiceEntry& entry, int index ); - Default implementation simply returns false. + /** Returns false if this is a constant empty set of choices, + which should not be modified. */ - virtual bool DoSetAttribute( const wxString& name, wxVariant& value ); + bool IsOk() const + { + return ( m_data != wxPGChoicesEmptyData ); + } - /** Returns value of an attribute. + const wxPGChoiceEntry& Item( unsigned int i ) const + { + wxASSERT( IsOk() ); + return *m_data->Item(i); + } - Override if custom handling of attributes is needed. + wxPGChoiceEntry& Item( unsigned int i ) + { + wxASSERT( IsOk() ); + return *m_data->Item(i); + } - Default implementation simply return NULL variant. - */ - virtual wxVariant DoGetAttribute( const wxString& name ) const; + /** Removes count items starting at position nIndex. */ + void RemoveAt(size_t nIndex, size_t count = 1); - /** Returns instance of a new wxPGEditorDialogAdapter instance, which is - used when user presses the (optional) button next to the editor control; +#ifndef SWIG + /** Does not create copies for itself. */ + void Set( const wxChar** labels, const long* values = NULL ) + { + Free(); + Add(labels,values); + } +#endif // SWIG - Default implementation returns NULL (ie. no action is generated when - button is pressed). - */ - virtual wxPGEditorDialogAdapter* GetEditorDialog() const; + /** Version that works with wxArrayString and wxArrayInt. */ + void Set( const wxArrayString& labels, + const wxArrayInt& values = wxArrayInt() ) + { + Free(); + if ( &values ) + Add(labels,values); + else + Add(labels); + } - /** - Adds entry to property's wxPGChoices and editor control (if it is - active). + // 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; + } + } - Returns index of item added. - */ - int AppendChoice( const wxString& label, int value = wxPG_INVALID_VALUE ) + // Returns data, increases refcount. + wxPGChoicesData* GetData() { - return InsertChoice(label,-1,value); + wxASSERT( m_data->m_refCount != 0xFFFFFFF ); + m_data->m_refCount++; + return m_data; } - /** Returns wxPGCell of given column, NULL if none. If valid - object is returned, caller will gain its ownership. - */ - wxPGCell* AcquireCell( unsigned int column ) + // Returns plain data ptr - no refcounting stuff is done. + wxPGChoicesData* GetDataPtr() const { return m_data; } + + // Changes ownership of data to you. + wxPGChoicesData* ExtractData() { - if ( column >= m_cells.size() ) - return NULL; + wxPGChoicesData* data = m_data; + m_data = wxPGChoicesEmptyData; + return data; + } - wxPGCell* cell = (wxPGCell*) m_cells[column]; - m_cells[column] = NULL; - return cell; + wxArrayString GetLabels() const; + +#ifndef SWIG + void operator= (const wxPGChoices& a) + { + AssignData(a.m_data); } - /** - Returns true if children of this property are component values (for - instance, points size, face name, and is_underlined are component - values of a font). - */ - bool AreChildrenComponents() const + wxPGChoiceEntry& operator[](unsigned int i) { - if ( m_flags & (wxPG_PROP_COMPOSED_VALUE|wxPG_PROP_AGGREGATE) ) - return true; + return Item(i); + } - return false; + const wxPGChoiceEntry& operator[](unsigned int i) const + { + return Item(i); } - /** - Removes entry from property's wxPGChoices and editor control (if it is - active). +protected: + wxPGChoicesData* m_data; - If selected item is deleted, then the value is set to unspecified. + void Init(); + void Free(); +#endif // !SWIG +}; + +// ----------------------------------------------------------------------- + +/** @class wxPGProperty + + wxPGProperty is base class for all wxPropertyGrid properties. + + NB: Full class overview is now only present in + interface/wx/propgrid/property.h. + + @library{wxpropgrid} + @category{propgrid} +*/ +class WXDLLIMPEXP_PROPGRID wxPGProperty : public wxObject +{ + friend class wxPropertyGrid; + friend class wxPropertyGridInterface; + 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. */ - void DeleteChoice( int index ); + 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() ) ); + } + + @endcode + */ + wxPGProperty( const wxString& label, const wxString& name ); /** - Call to enable or disable usage of common value (integer value that can - be selected for properties instead of their normal values) for this - property. + Virtual destructor. + It is customary for derived properties to implement this. + */ + virtual ~wxPGProperty(); - Common values are disabled by the default for all properties. + /** This virtual function is called after m_value has been set. + + @remarks + - If m_value was set to Null variant (ie. unspecified value), + OnSetValue() will not be called. + - m_value may be of any variant type. Typically properties internally + support only one variant type, and as such OnSetValue() provides a + good opportunity to convert + supported values into internal type. + - Default implementation does nothing. */ - void EnableCommonValue( bool enable = true ) - { - if ( enable ) SetFlag( wxPG_PROP_USES_COMMON_VALUE ); - else ClearFlag( wxPG_PROP_USES_COMMON_VALUE ); - } + virtual void OnSetValue(); - /** Composes text from values of child properties. */ - void GenerateComposedValue( wxString& text, int argFlags = 0 ) const; + /** Override this to return something else than m_value as the value. + */ + virtual wxVariant DoGetValue() const { return m_value; } - /** Returns property's label. */ - const wxString& GetLabel() const { return m_label; } +#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. - /** Returns property's name with all (non-category, non-root) parents. */ - wxString GetName() const; + @remarks + - Default implementation always returns true. + */ + virtual bool ValidateValue( wxVariant& value, + wxPGValidationInfo& validationInfo ) const; /** - Returns property's base name (ie parent's name is not added in any - case) - */ - const wxString& GetBaseName() const { return m_name; } + Converts text into wxVariant value appropriate for this property. - wxPGChoices& GetChoices(); + @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. - const wxPGChoices& GetChoices() const; + @param text + Text to be translated into variant. - const wxPGChoiceEntry* GetCurrentChoice() const; + @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() + called with this same flag). - /** Returns coordinate to the top y of the property. Note that the - position of scrollbars is not taken into account. - */ - int GetY() const; + @return Returns @true if resulting wxVariant value was different. - wxVariant GetValue() const - { - return DoGetValue(); - } + @remarks Default implementation converts semicolon delimited tokens into + child values. Only works for properties with children. -#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. + 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). */ - wxVariant& GetValueRef() - { - return m_value; - } + virtual bool StringToValue( wxVariant& variant, + const wxString& text, + int argFlags = 0 ) const; - const wxVariant& GetValueRef() const - { - return m_value; - } -#endif + /** + 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. + + @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. - /** Same as GetValueAsString, except takes common value into account. + @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. + - Default implementation simply assign given int to m_value. + - 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). */ - wxString GetValueString( int argFlags = 0 ) const; + virtual bool IntToValue( wxVariant& value, + int number, + int argFlags = 0 ) const; +#endif // !defined(SWIG) || defined(CREATE_VCW) - void UpdateControl( wxWindow* primary ); +public: + /** Returns text representation of property's value. - /** Returns wxPGCell of given column, NULL if none. wxPGProperty - will retain ownership of the cell object. + @param argFlags + 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. + + @remarks + Default implementation returns string composed from text + representations of child properties. */ - wxPGCell* GetCell( unsigned int column ) const - { - if ( column >= m_cells.size() ) - return NULL; + virtual wxString GetValueAsString( int argFlags = 0 ) const; - return (wxPGCell*) m_cells[column]; - } + /** Converts string to a value, and if successful, calls SetValue() on it. + Default behavior is to do nothing. + @param text + String to get the value from. + @return + true if value was changed. + */ + bool SetValueFromString( const wxString& text, int flags = 0 ); - unsigned int GetChoiceCount() const; + /** Converts integer to a value, and if succesful, calls SetValue() on it. + Default behavior is to do nothing. + @param value + Int to get the value from. + @param flags + If has wxPG_FULL_VALUE, then the value given is a actual value and + not an index. + @return + True if value was changed. + */ + bool SetValueFromInt( long value, int flags = 0 ); - wxString GetChoiceString( unsigned int index ); + /** + Returns size of the custom painted image in front of property. - /** Return number of displayed common values for this property. + This method must be overridden to return non-default value if + OnCustomPaint is to be called. + @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 image width or height is indicated with dimension -1. + - You can also return wxPG_DEFAULT_IMAGE_SIZE, i.e. wxSize(-1, -1). */ - int GetDisplayedCommonValueCount() const; + virtual wxSize OnMeasureImage( int item = -1 ) const; - wxString GetDisplayedString() const - { - return GetValueString(0); - } + /** + Events received by editor widgets are processed here. - /** Returns property grid where property lies. */ - wxPropertyGrid* GetGrid() const; + Note that editor class usually processes most events. Some, such as + 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 + 'custom' selection is made). - /** Returns owner wxPropertyGrid, but only if one is currently on a page - displaying this property. */ - wxPropertyGrid* GetGridIfDisplayed() const; + If the event causes value to be changed, SetValueInEvent() + should be called to set the new value. - /** Returns highest level non-category, non-root parent. Useful when you - have nested wxCustomProperties/wxParentProperties. + @param event + Associated wxEvent. + @return + Should return true if any changes in value should be reported. @remarks - Thus, if immediate parent is root or category, this will return the - property itself. + 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. */ - wxPGProperty* GetMainParent() const; + virtual bool OnEvent( wxPropertyGrid* propgrid, + wxWindow* wnd_primary, + wxEvent& event ); - /** Return parent of property */ - wxPGProperty* GetParent() const { return m_parent; } + /** + Called after value of a child property has been altered. - /** Returns true if property has editable wxTextCtrl when selected. + Note that this function is usually called at the time that value of + this property, or given child property, is still pending for change. - @remarks - Altough 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). - */ - bool IsTextEditable() const; + Sample pseudo-code implementation: - bool IsValueUnspecified() const - { - return m_value.IsNull(); - } + @code + void 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). + T& data = TFromVariant(thisValue); - FlagType HasFlag( FlagType flag ) const - { - return ( m_flags & flag ); - } + // Copy childValue into data. + switch ( childIndex ) + { + case 0: + data.SetSubProp1( childvalue.GetLong() ); + break; + case 1: + data.SetSubProp2( childvalue.GetString() ); + break; + ... + } + } + @endcode - /** Returns comma-delimited string of property attributes. + @param thisValue + Value of this property, that should be altered. + @param childIndex + Index of child changed (you can use Item(childIndex) to get). + @param childValue + Value of the child property. */ - const wxPGAttributeStorage& GetAttributes() const - { - return m_attributes; - } + virtual void ChildChanged( wxVariant& thisValue, + int childIndex, + wxVariant& childValue ) const; - /** Returns m_attributes as list wxVariant. + /** Returns pointer to an instance of used editor. */ - wxVariant GetAttributesAsList() const; + virtual const wxPGEditor* DoGetEditorClass() const; - FlagType GetFlags() const - { - return m_flags; - } + /** Returns pointer to the wxValidator that should be used + with the editor of this property (NULL for no validator). + Setting validator explicitly via SetPropertyValidator + will override this. - const wxPGEditor* GetEditorClass() const; + In most situations, code like this should work well + (macros are used to maintain one actual validator instance, + so on the second call the function exits within the first + macro): - wxString GetValueType() const - { - return m_value.GetType(); - } + @code - /** Returns editor used for given column. NULL for no editor. - */ - const wxPGEditor* GetColumnEditor( int column ) const - { - if ( column == 1 ) - return GetEditorClass(); + wxValidator* wxMyPropertyClass::DoGetValidator () const + { + WX_PG_DOGETVALIDATOR_ENTRY() - return NULL; - } + wxMyValidator* validator = new wxMyValidator(...); - /** Returns common value selected for this property. -1 for none. - */ - int GetCommonValue() const - { - return m_commonValue; - } + ... prepare validator... - /** Returns true if property has even one visible child. - */ - bool HasVisibleChildren() const; + WX_PG_DOGETVALIDATOR_EXIT(validator) + } - /** - Adds entry to property's wxPGChoices and editor control (if it is - active). + @endcode - Returns index of item added. + @remarks + You can get common filename validator by returning + wxFileProperty::GetClassValidator(). wxDirProperty, + for example, uses it. */ - int InsertChoice( const wxString& label, - int index, - int value = wxPG_INVALID_VALUE ); + virtual wxValidator* DoGetValidator () const; /** - Returns true if this property is actually a wxPropertyCategory. - */ - bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY)?true:false; } + Override to paint an image in front of the property value text or + drop-down list item (but only if wxPGProperty::OnMeasureImage is + overridden as well). - /** Returns true if this property is actually a wxRootProperty. - */ - bool IsRoot() const { return (m_parent == NULL); } + If property's OnMeasureImage() returns size that has height != 0 but + less than row height ( < 0 has special meanings), wxPropertyGrid calls + this method to draw a custom image in a limited area in front of the + editor control or value text/graphics, and if control has drop-down + list, then the image is drawn there as well (even in the case + OnMeasureImage() returned higher height than row height). - /** Returns true if this is a sub-property. */ - bool IsSubProperty() const - { - wxPGProperty* parent = (wxPGProperty*)m_parent; - if ( parent && !parent->IsCategory() ) - return true; - return false; - } + NOTE: Following applies when OnMeasureImage() returns a "flexible" + height ( using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable + height items: If rect.x is < 0, then this is a measure item call, which + means that dc is invalid and only thing that should be done is to set + paintdata.m_drawnHeight to the height of the image of item at index + paintdata.m_choiceItem. This call may be done even as often as once + every drop-down popup show. + + @param dc + wxDC to paint on. + @param rect + Box reserved for custom graphics. Includes surrounding rectangle, + if any. If x is < 0, then this is a measure item call (see above). + @param paintdata + wxPGPaintData structure with much useful data. + + @remarks + - You can actually exceed rect width, but if you do so then + paintdata.m_drawnWidth must be set to the full width drawn in + pixels. + - Due to technical reasons, rect's height will be default even if + custom height was reported during measure call. + - Brush is guaranteed to be default background colour. It has been + already used to clear the background of area being painted. It + can be modified. + - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper + colour) pen for drawing framing rectangle. It can be changed as + well. - /** Returns last visible sub-property, recursively. + @see GetValueAsString() */ - const wxPGProperty* GetLastVisibleSubItem() const; - - wxVariant GetDefaultValue() const; - - int GetMaxLength() const - { - return (int) m_maxLen; - } + virtual void OnCustomPaint( wxDC& dc, + const wxRect& rect, + wxPGPaintData& paintdata ); /** - Determines, recursively, if all children are not unspecified. + Returns used wxPGCellRenderer instance for given property column + (label=0, value=1). - Takes values in given list into account. + Default implementation returns editor's renderer for all columns. */ - bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const; - - /** Updates composed values of parent non-category properties, recursively. - Returns topmost property updated. + virtual wxPGCellRenderer* GetCellRenderer( int column ) const; - @remarks - - Must not call SetValue() (as can be called in it). - */ - wxPGProperty* UpdateParentValues(); + /** Returns which choice is currently selected. Only applies to properties + which have choices. - /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES. + Needs to reimplemented in derived class if property value does not + map directly to a choice. Integer as index, bool, and string usually do. */ - FlagType UsesAutoUnspecified() const - { - return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED); - } - - wxBitmap* GetValueImage() const - { - return m_valueBitmap; - } - - wxVariant GetAttribute( const wxString& name ) const; + virtual int GetChoiceSelection() const; /** - Returns named attribute, as string, if found. + Refresh values of child properties. - Otherwise defVal is returned. + Automatically called after value is set. */ - wxString GetAttribute( const wxString& name, const wxString& defVal ) const; - - /** - Returns named attribute, as long, if found. + virtual void RefreshChildren(); - Otherwise defVal is returned. - */ - long GetAttributeAsLong( const wxString& name, long defVal ) const; + /** Special handling for attributes of this property. - /** - Returns named attribute, as double, if found. + If returns false, then the attribute will be automatically stored in + m_attributes. - Otherwise defVal is returned. + Default implementation simply returns false. */ - double GetAttributeAsDouble( const wxString& name, double defVal ) const; + virtual bool DoSetAttribute( const wxString& name, wxVariant& value ); - unsigned int GetArrIndex() const { return m_arrIndex; } + /** Returns value of an attribute. - unsigned int GetDepth() const { return (unsigned int)m_depth; } + Override if custom handling of attributes is needed. - /** Gets flags as a'|' delimited string. Note that flag names are not - prepended with 'wxPG_PROP_'. - @param flagsMask - String will only be made to include flags combined by this parameter. + Default implementation simply return NULL variant. */ - wxString GetFlagsAsString( FlagType flagsMask ) const; + virtual wxVariant DoGetAttribute( const wxString& name ) const; - /** Returns position in parent's array. */ - unsigned int GetIndexInParent() const - { - return (unsigned int)m_arrIndex; - } + /** Returns instance of a new wxPGEditorDialogAdapter instance, which is + used when user presses the (optional) button next to the editor control; - /** Hides or reveals the property. - @param hide - true for hide, false for reveal. - @param flags - By default changes are applied recursively. Set this paramter - wxPG_DONT_RECURSE to prevent this. + Default implementation returns NULL (ie. no action is generated when + button is pressed). */ - inline bool Hide( bool hide, int flags = wxPG_RECURSE ); - - bool IsExpanded() const - { return (!(m_flags & wxPG_PROP_COLLAPSED) && GetChildCount()); } + virtual wxPGEditorDialogAdapter* GetEditorDialog() const; - /** Returns true if all parents expanded. + /** Returns wxPGCell of given column, NULL if none. If valid + object is returned, caller will gain its ownership. */ - bool IsVisible() const; + wxPGCell* AcquireCell( unsigned int column ) + { + if ( column >= m_cells.size() ) + return NULL; - bool IsEnabled() const { return !(m_flags & wxPG_PROP_DISABLED); } + wxPGCell* cell = (wxPGCell*) m_cells[column]; + m_cells[column] = NULL; + return cell; + } - /** If property's editor is created this forces its recreation. - Useful in SetAttribute etc. Returns true if actually did anything. + /** Append a new choice to property's list of choices. */ - bool RecreateEditor(); + int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE ) + { + return InsertChoice(label, wxNOT_FOUND, value); + } - /** If property's editor is active, then update it's value. + /** + Returns true if children of this property are component values (for + instance, points size, face name, and is_underlined are component + values of a font). */ - void RefreshEditor(); + bool AreChildrenComponents() const + { + if ( m_flags & (wxPG_PROP_COMPOSED_VALUE|wxPG_PROP_AGGREGATE) ) + return true; - /** Sets an attribute for this property. - @param name - Text identifier of attribute. See @ref propgrid_property_attributes. - @param value - Value of attribute. - */ - void SetAttribute( const wxString& name, wxVariant value ); + return false; + } - void SetAttributes( const wxPGAttributeStorage& attributes ); + /** + Removes entry from property's wxPGChoices and editor control (if it is + active). -#ifndef SWIG - /** Sets editor for a property. + If selected item is deleted, then the value is set to unspecified. + */ + void DeleteChoice( int index ); - @param editor - For builtin editors, use wxPGEditor_X, where X is builtin editor's - name (TextCtrl, Choice, etc. see wxPGEditor documentation for full - list). + /** + Call to enable or disable usage of common value (integer value that can + be selected for properties instead of their normal values) for this + property. - For custom editors, use pointer you received from - wxPropertyGrid::RegisterEditorClass(). + Common values are disabled by the default for all properties. */ - void SetEditor( const wxPGEditor* editor ) + void EnableCommonValue( bool enable = true ) { - m_customEditor = editor; + if ( enable ) SetFlag( wxPG_PROP_USES_COMMON_VALUE ); + else ClearFlag( wxPG_PROP_USES_COMMON_VALUE ); } -#endif - /** Sets editor for a property. - */ - inline void SetEditor( const wxString& editorName ); + /** Composes text from values of child properties. */ + void GenerateComposedValue( wxString& text, int argFlags = 0 ) const; - /** Sets cell information for given column. + /** Returns property's label. */ + const wxString& GetLabel() const { return m_label; } - Note that the property takes ownership of given wxPGCell instance. - */ - void SetCell( int column, wxPGCell* cellObj ); + /** Returns property's name with all (non-category, non-root) parents. */ + wxString GetName() const; - /** Changes value of a property with choices, but only - works if the value type is long or string. */ - void SetChoiceSelection( int newValue, const wxPGChoiceInfo& choiceInfo ); + /** + Returns property's base name (ie parent's name is not added in any + case) + */ + const wxString& GetBaseName() const { return m_name; } - /** Sets common value selected for this property. -1 for none. + /** Returns read-only reference to property's list of choices. */ - void SetCommonValue( int commonValue ) + const wxPGChoices& GetChoices() const { - m_commonValue = commonValue; + return m_choices; } - /** Sets flags from a '|' delimited string. Note that flag names are not - prepended with 'wxPG_PROP_'. + /** Returns coordinate to the top y of the property. Note that the + position of scrollbars is not taken into account. */ - void SetFlagsFromString( const wxString& str ); + int GetY() const; - /** Sets property's "is it modified?" flag. Affects children recursively. - */ - void SetModifiedStatus( bool modified ) + wxVariant GetValue() const { - SetFlagRecursively(wxPG_PROP_MODIFIED, modified); + return DoGetValue(); } - /** Call in OnEvent(), OnButtonClick() etc. to change the property value - based on user input. - - @remarks - This method is const since it doesn't actually modify value, but posts - given variant as pending value, stored in wxPropertyGrid. +#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. */ - void SetValueInEvent( wxVariant value ) const; - - /** - Call this to set value of the property. + wxVariant& GetValueRef() + { + return m_value; + } - Unlike methods in wxPropertyGrid, this does not automatically update - the display. + const wxVariant& GetValueRef() const + { + return m_value; + } +#endif - @remarks - Use wxPropertyGrid::ChangePropertyValue() instead if you need to run - through validation process and send property change event. + /** 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. + */ + wxString GetValueString( int argFlags = 0 ) const; - If you need to change property value in event, based on user input, use - SetValueInEvent() instead. + void UpdateControl( wxWindow* primary ); - @param pList - 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). + /** Returns wxPGCell of given column, NULL if none. wxPGProperty + will retain ownership of the cell object. */ - void SetValue( wxVariant value, wxVariant* pList = NULL, int flags = 0 ); + wxPGCell* GetCell( unsigned int column ) const + { + if ( column >= m_cells.size() ) + return NULL; - /** Set wxBitmap in front of the value. This bitmap may be ignored - by custom cell renderers. - */ - void SetValueImage( wxBitmap& bmp ); + return (wxPGCell*) m_cells[column]; + } - /** If property has choices and they are not yet exclusive, new such copy - of them will be created. + /** Return number of displayed common values for this property. */ - void SetChoicesExclusive(); + int GetDisplayedCommonValueCount() const; - void SetExpanded( bool expanded ) + wxString GetDisplayedString() const { - if ( !expanded ) m_flags |= wxPG_PROP_COLLAPSED; - else m_flags &= ~wxPG_PROP_COLLAPSED; + return GetValueString(0); } - void SetFlag( FlagType flag ) { m_flags |= flag; } + /** Returns property grid where property lies. */ + wxPropertyGrid* GetGrid() const; + + /** Returns owner wxPropertyGrid, but only if one is currently on a page + displaying this property. */ + wxPropertyGrid* GetGridIfDisplayed() const; + + /** Returns highest level non-category, non-root parent. Useful when you + have nested wxCustomProperties/wxParentProperties. + @remarks + Thus, if immediate parent is root or category, this will return the + property itself. + */ + wxPGProperty* GetMainParent() const; + + /** Return parent of property */ + wxPGProperty* GetParent() const { return m_parent; } - void SetFlagRecursively( FlagType flag, bool set ); + /** Returns true if property has editable wxTextCtrl when selected. - void SetHelpString( const wxString& helpString ) + @remarks + Altough 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). + */ + bool IsTextEditable() const; + + bool IsValueUnspecified() const { - m_helpString = helpString; + return m_value.IsNull(); } - void SetLabel( const wxString& label ) { m_label = label; } - - inline void SetName( const wxString& newName ); - - void SetValueToUnspecified() + FlagType HasFlag( FlagType flag ) const { - wxVariant val; // Create NULL variant - SetValue(val); + return ( m_flags & flag ); } -#if wxUSE_VALIDATORS - /** Sets wxValidator for a property*/ - void SetValidator( const wxValidator& validator ) + /** Returns comma-delimited string of property attributes. + */ + const wxPGAttributeStorage& GetAttributes() const { - m_validator = wxDynamicCast(validator.Clone(),wxValidator); + return m_attributes; } - /** Gets assignable version of property's validator. */ - wxValidator* GetValidator() const + /** Returns m_attributes as list wxVariant. + */ + wxVariant GetAttributesAsList() const; + + FlagType GetFlags() const { - if ( m_validator ) - return m_validator; - return DoGetValidator(); + return m_flags; } -#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 ); + const wxPGEditor* GetEditorClass() const; -#ifndef SWIG - /** Returns client data (void*) of a property. - */ - void* GetClientData() const + wxString GetValueType() const { - return m_clientData; + return m_value.GetType(); } - /** Sets client data (void*) of a property. - @remarks - This untyped client data has to be deleted manually. + /** Returns editor used for given column. NULL for no editor. */ - void SetClientData( void* clientData ) + const wxPGEditor* GetColumnEditor( int column ) const { - m_clientData = clientData; + if ( column == 1 ) + return GetEditorClass(); + + return NULL; } - /** Returns client object of a property. + /** Returns common value selected for this property. -1 for none. */ - void SetClientObject(wxClientData* clientObject) + int GetCommonValue() const { - delete m_clientObject; - m_clientObject = clientObject; + return m_commonValue; } - /** Sets managed client object of a property. + /** Returns true if property has even one visible child. */ - wxClientData *GetClientObject() const { return m_clientObject; } -#endif - - /** Sets new set of choices for property. + bool HasVisibleChildren() const; - @remarks - This operation clears the property value. + /** Inserts a new choice to property's list of choices. */ - bool SetChoices( wxPGChoices& choices ); + int InsertChoice( const wxString& label, int index, int value = wxPG_INVALID_VALUE ); - /** Sets new set of choices for property. + /** + Returns true if this property is actually a wxPropertyCategory. */ - inline bool SetChoices( const wxArrayString& labels, - const wxArrayInt& values = wxArrayInt() ); + bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY)?true:false; } - /** Set max length of text in text editor. + /** Returns true if this property is actually a wxRootProperty. */ - inline bool SetMaxLength( int maxLen ); + bool IsRoot() const { return (m_parent == NULL); } - /** Call with 'false' in OnSetValue to cancel value changes after all - (ie. cancel 'true' returned by StringToValue() or IntToValue()). - */ - void SetWasModified( bool set = true ) + /** Returns true if this is a sub-property. */ + bool IsSubProperty() const { - if ( set ) m_flags |= wxPG_PROP_WAS_MODIFIED; - else m_flags &= ~wxPG_PROP_WAS_MODIFIED; + wxPGProperty* parent = (wxPGProperty*)m_parent; + if ( parent && !parent->IsCategory() ) + return true; + return false; } - const wxString& GetHelpString() const - { - return m_helpString; - } + /** Returns last visible sub-property, recursively. + */ + const wxPGProperty* GetLastVisibleSubItem() const; - void ClearFlag( FlagType flag ) { m_flags &= ~(flag); } + wxVariant GetDefaultValue() const; - // Use, for example, to detect if item is inside collapsed section. - bool IsSomeParent( wxPGProperty* candidate_parent ) const; + int GetMaxLength() const + { + return (int) m_maxLen; + } /** - Adapts list variant into proper value using consecutive - ChildChanged-calls. - */ - void AdaptListToValue( wxVariant& list, wxVariant* value ) const; - - /** This is used by properties that have fixed sub-properties. */ - void AddChild( wxPGProperty* prop ); - - /** Returns height of children, recursively, and - by taking expanded/collapsed status into account. + Determines, recursively, if all children are not unspecified. - iMax is used when finding property y-positions. + @param pendingList + Assumes members in this wxVariant list as pending + replacement values. */ - int GetChildrenHeight( int lh, int iMax = -1 ) const; - - /** Returns number of child properties */ - unsigned int GetChildCount() const { return m_children.GetCount(); } + bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const; - /** Returns sub-property at index i. */ - wxPGProperty* Item( size_t i ) const - { return (wxPGProperty*)m_children.Item(i); } + /** Updates composed values of parent non-category properties, recursively. + Returns topmost property updated. - /** Returns last sub-property. + @remarks + - Must not call SetValue() (as can be called in it). */ - 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); } - - /** Deletes all sub-properties. */ - void Empty(); - - // Puts correct indexes to children - void FixIndexesOfChildren( size_t starthere = 0 ); - -#ifndef SWIG - // 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; + wxPGProperty* UpdateParentValues(); - /** Returns (direct) child property with given name (or NULL if not found). + /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES. */ - 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); - } + bool UsesAutoUnspecified() const + { + return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED)?true:false; } - %pythoncode { - GetClientObject = GetClientData - SetClientObject = SetClientData + + wxBitmap* GetValueImage() const + { + return m_valueBitmap; } -#endif -#ifndef SWIG + wxVariant GetAttribute( const wxString& name ) const; - static wxString* sm_wxPG_LABEL; + /** + Returns named attribute, as string, if found. - /** This member is public so scripting language bindings - wrapper code can access it freely. + Otherwise defVal is returned. */ - void* m_clientData; + wxString GetAttribute( const wxString& name, const wxString& defVal ) const; -protected: - /** Returns text for given column. - */ - wxString GetColumnText( unsigned int col ) const; + /** + Returns named attribute, as long, if found. - /** Returns (direct) child property with given name (or NULL if not found), - with hint index. + Otherwise defVal is returned. + */ + long GetAttributeAsLong( const wxString& name, long defVal ) const; - @param hintIndex - Start looking for the child at this index. + /** + Returns named attribute, as double, if found. - @remarks - Does not support scope (ie. Parent.Child notation). + Otherwise defVal is returned. */ - wxPGProperty* GetPropertyByNameWH( const wxString& name, - unsigned int hintIndex ) const; - - /** This is used by Insert etc. */ - void AddChild2( wxPGProperty* prop, - int index = -1, - bool correct_mode = true ); + double GetAttributeAsDouble( const wxString& name, double defVal ) const; - void DoSetName(const wxString& str) { m_name = str; } + unsigned int GetDepth() const { return (unsigned int)m_depth; } - // Call for after sub-properties added with AddChild - void PrepareSubProperties(); + /** Gets flags as a'|' delimited string. Note that flag names are not + prepended with 'wxPG_PROP_'. + @param flagsMask + String will only be made to include flags combined by this parameter. + */ + wxString GetFlagsAsString( FlagType flagsMask ) const; - void SetParentalType( int flag ) + /** Returns position in parent's array. */ + unsigned int GetIndexInParent() const { - m_flags &= ~(wxPG_PROP_PROPERTY|wxPG_PROP_PARENTAL_FLAGS); - m_flags |= flag; + return (unsigned int)m_arrIndex; } - void SetParentState( wxPropertyGridPageState* pstate ) - { m_parentState = pstate; } - - // Call after fixed sub-properties added/removed after creation. - // if oldSelInd >= 0 and < new max items, then selection is - // moved to it. - void SubPropsChanged( int oldSelInd = -1 ); + /** Hides or reveals the property. + @param hide + true for hide, false for reveal. + @param flags + By default changes are applied recursively. Set this paramter + wxPG_DONT_RECURSE to prevent this. + */ + inline bool Hide( bool hide, int flags = wxPG_RECURSE ); - int GetY2( int lh ) const; + bool IsExpanded() const + { return (!(m_flags & wxPG_PROP_COLLAPSED) && GetChildCount()); } - wxString m_label; - wxString m_name; - wxPGProperty* m_parent; - wxPropertyGridPageState* m_parentState; + /** Returns true if all parents expanded. + */ + bool IsVisible() const; - wxClientData* m_clientObject; + bool IsEnabled() const { return !(m_flags & wxPG_PROP_DISABLED); } - // Overrides editor returned by property class - const wxPGEditor* m_customEditor; -#if wxUSE_VALIDATORS - // Editor is going to get this validator - wxValidator* m_validator; -#endif - // Show this in front of the value - // - // TODO: Can bitmap be implemented with wxPGCell? - wxBitmap* m_valueBitmap; + /** If property's editor is created this forces its recreation. + Useful in SetAttribute etc. Returns true if actually did anything. + */ + bool RecreateEditor(); - wxVariant m_value; - wxPGAttributeStorage m_attributes; - wxArrayPtrVoid m_children; + /** If property's editor is active, then update it's value. + */ + void RefreshEditor(); - // Extended cell information - wxArrayPtrVoid m_cells; + /** Sets an attribute for this property. + @param name + Text identifier of attribute. See @ref propgrid_property_attributes. + @param value + Value of attribute. + */ + void SetAttribute( const wxString& name, wxVariant value ); - // Help shown in statusbar or help box. - wxString m_helpString; + void SetAttributes( const wxPGAttributeStorage& attributes ); - // Index in parent's property array. - unsigned int m_arrIndex; +#ifndef SWIG + /** Sets editor for a property. - // If not -1, then overrides m_value - int m_commonValue; + @param editor + For builtin editors, use wxPGEditor_X, where X is builtin editor's + name (TextCtrl, Choice, etc. see wxPGEditor documentation for full + list). - FlagType m_flags; + For custom editors, use pointer you received from + wxPropertyGrid::RegisterEditorClass(). + */ + void SetEditor( const wxPGEditor* editor ) + { + m_customEditor = editor; + } +#endif - // Maximum length (mainly for string properties). Could be in some sort of - // wxBaseStringProperty, but currently, for maximum flexibility and - // compatibility, we'll stick it here. Anyway, we had 3 excess bytes to use - // so short int will fit in just fine. - short m_maxLen; + /** Sets editor for a property. + */ + inline void SetEditor( const wxString& editorName ); - // Root has 0, categories etc. at that level 1, etc. - unsigned char m_depth; + /** Sets cell information for given column. - // m_depthBgCol indicates width of background colour between margin and item - // (essentially this is category's depth, if none then equals m_depth). - unsigned char m_depthBgCol; + Note that the property takes ownership of given wxPGCell instance. + */ + void SetCell( int column, wxPGCell* cellObj ); - unsigned char m_bgColIndex; // Background brush index. - unsigned char m_fgColIndex; // Foreground colour index. + /** Sets common value selected for this property. -1 for none. + */ + void SetCommonValue( int commonValue ) + { + m_commonValue = commonValue; + } -private: - // Called in constructors. - void Init(); - void Init( const wxString& label, const wxString& name ); -#endif // #ifndef SWIG -}; + /** Sets flags from a '|' delimited string. Note that flag names are not + prepended with 'wxPG_PROP_'. + */ + void SetFlagsFromString( const wxString& str ); -// ----------------------------------------------------------------------- + /** Sets property's "is it modified?" flag. Affects children recursively. + */ + void SetModifiedStatus( bool modified ) + { + SetFlagRecursively(wxPG_PROP_MODIFIED, modified); + } -// -// Property class declaration helper macros -// (wxPGRootPropertyClass and wxPropertyCategory require this). -// + /** Call in OnEvent(), OnButtonClick() etc. to change the property value + based on user input. -#define WX_PG_DECLARE_DOGETEDITORCLASS \ - virtual const wxPGEditor* DoGetEditorClass() const; + @remarks + This method is const since it doesn't actually modify value, but posts + given variant as pending value, stored in wxPropertyGrid. + */ + void SetValueInEvent( wxVariant value ) const; -#ifndef SWIG - #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 + /** + Call this to set value of the property. -// Implements sans constructor function. Also, first arg is class name, not -// property name. -#define WX_PG_IMPLEMENT_PROPERTY_CLASS_PLAIN(PROPNAME,T,EDITOR) \ -const wxPGEditor* PROPNAME::DoGetEditorClass() const \ -{ \ - return wxPGEditor_##EDITOR; \ -} + Unlike methods in wxPropertyGrid, this does not automatically update + the display. -// ----------------------------------------------------------------------- + @remarks + Use wxPropertyGrid::ChangePropertyValue() instead if you need to run + through validation process and send property change event. -#ifndef SWIG + If you need to change property value in event, based on user input, use + SetValueInEvent() instead. -/** @class wxPGRootProperty - @ingroup classes - Root parent property. -*/ -class WXDLLIMPEXP_PROPGRID wxPGRootProperty : public wxPGProperty -{ -public: - WX_PG_DECLARE_PROPERTY_CLASS(wxPGRootProperty) -public: + @param pList + 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). + */ + void SetValue( wxVariant value, wxVariant* pList = NULL, int flags = 0 ); - /** Constructor. */ - wxPGRootProperty(); - virtual ~wxPGRootProperty(); + /** Set wxBitmap in front of the value. This bitmap may be ignored + by custom cell renderers. + */ + void SetValueImage( wxBitmap& bmp ); - virtual bool StringToValue( wxVariant&, const wxString&, int ) const + /** If property has choices and they are not yet exclusive, new such copy + of them will be created. + */ + void SetChoicesExclusive() { - return false; + m_choices.SetExclusive(); } -protected: -}; - -// ----------------------------------------------------------------------- - -/** @class wxPropertyCategory - @ingroup classes - Category (caption) property. -*/ -class WXDLLIMPEXP_PROPGRID wxPropertyCategory : public wxPGProperty -{ - friend class wxPropertyGrid; - friend class wxPropertyGridPageState; - WX_PG_DECLARE_PROPERTY_CLASS(wxPropertyCategory) -public: - - /** Default constructor is only used in special cases. */ - wxPropertyCategory(); + /** Sets selected choice and changes property value. - wxPropertyCategory( const wxString& label, - const wxString& name = wxPG_LABEL ); - ~wxPropertyCategory(); + Tries to retain value type, although currently if it is not string, + then it is forced to integer. + */ + void SetChoiceSelection( int newValue ); - int GetTextExtent( const wxWindow* wnd, const wxFont& font ) const; + void SetExpanded( bool expanded ) + { + if ( !expanded ) m_flags |= wxPG_PROP_COLLAPSED; + else m_flags &= ~wxPG_PROP_COLLAPSED; + } -protected: - virtual wxString GetValueAsString( int argFlags ) const; + void SetFlag( FlagType flag ) { m_flags |= flag; } - void SetTextColIndex( unsigned int colInd ) - { m_capFgColIndex = (wxByte) colInd; } - unsigned int GetTextColIndex() const - { return (unsigned int) m_capFgColIndex; } + void SetFlagRecursively( FlagType flag, bool set ); - void CalculateTextExtent( wxWindow* wnd, const wxFont& font ); + void SetHelpString( const wxString& helpString ) + { + m_helpString = helpString; + } - int m_textExtent; // pre-calculated length of text - wxByte m_capFgColIndex; // caption text colour index + void SetLabel( const wxString& label ) { m_label = label; } -private: - void Init(); -}; + inline void SetName( const wxString& newName ); -#endif // !SWIG + /** + 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). -#ifndef SWIG + @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. + */ + void SetParentalType( int flag ) + { + m_flags &= ~(wxPG_PROP_PROPERTY|wxPG_PROP_PARENTAL_FLAGS); + m_flags |= flag; + } -/** @class wxPGChoiceEntry - Data of a single wxPGChoices choice. -*/ -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) + void SetValueToUnspecified() { - m_text = label; + wxVariant val; // Create NULL variant + SetValue(val); } - 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) +#if wxUSE_VALIDATORS + /** Sets wxValidator for a property*/ + void SetValidator( const wxValidator& validator ) { + m_validator = wxDynamicCast(validator.Clone(),wxValidator); } - virtual ~wxPGChoiceEntry() + /** Gets assignable version of property's validator. */ + wxValidator* GetValidator() const { + if ( m_validator ) + return m_validator; + return DoGetValidator(); } +#endif // #if wxUSE_VALIDATORS - void SetValue( int value ) { m_value = value; } +#ifndef SWIG + /** Returns client data (void*) of a property. + */ + void* GetClientData() const + { + return m_clientData; + } - int GetValue() const { return m_value; } + /** Sets client data (void*) of a property. + @remarks + This untyped client data has to be deleted manually. + */ + void SetClientData( void* clientData ) + { + m_clientData = clientData; + } - bool HasValue() const { return (m_value != wxPG_INVALID_VALUE); } + /** Returns client object of a property. + */ + void SetClientObject(wxClientData* clientObject) + { + delete m_clientObject; + m_clientObject = clientObject; + } -protected: - int m_value; -}; + /** Sets managed client object of a property. + */ + wxClientData *GetClientObject() const { return m_clientObject; } +#endif + /** Sets new set of choices for property. -typedef void* wxPGChoicesId; + @remarks + This operation clears the property value. + */ + bool SetChoices( wxPGChoices& choices ); -class WXDLLIMPEXP_PROPGRID wxPGChoicesData -{ - friend class wxPGChoices; -public: - // Constructor sets m_refCount to 1. - wxPGChoicesData(); + /** Set max length of text in text editor. + */ + inline bool SetMaxLength( int maxLen ); - void CopyDataFrom( wxPGChoicesData* data ); + /** Call with 'false' in OnSetValue to cancel value changes after all + (ie. cancel 'true' returned by StringToValue() or IntToValue()). + */ + void SetWasModified( bool set = true ) + { + if ( set ) m_flags |= wxPG_PROP_WAS_MODIFIED; + else m_flags &= ~wxPG_PROP_WAS_MODIFIED; + } - // Takes ownership of 'item' - void Insert( int index, wxPGChoiceEntry* item ) + const wxString& GetHelpString() const { - wxArrayPtrVoid::iterator it; - if ( index == -1 ) - { - it = m_items.end(); - index = m_items.size(); - } - else - { - it = m_items.begin() + index; - } + return m_helpString; + } - // Need to fix value? - if ( item->GetValue() == wxPG_INVALID_VALUE ) - item->SetValue(index); + void ClearFlag( FlagType flag ) { m_flags &= ~(flag); } - m_items.insert(it, item); - } + // Use, for example, to detect if item is inside collapsed section. + bool IsSomeParent( wxPGProperty* candidate_parent ) const; - // Delete all entries - void Clear(); + /** + Adapts list variant into proper value using consecutive + ChildChanged-calls. + */ + void AdaptListToValue( wxVariant& list, wxVariant* value ) const; - size_t GetCount() const { return m_items.size(); } + /** + Adds a 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: - wxPGChoiceEntry* Item( unsigned int i ) const - { - wxCHECK_MSG( i < GetCount(), NULL, "invalid index" ); + @code + wxPGProperty* prop = new wxStringProperty(wxS("Property")); + prop->SetParentalType(wxPG_PROP_MISC_PARENT); + wxPGProperty* prop2 = new wxStringProperty(wxS("Property2")); + prop->AddChild(prop2); + @endcode + */ + void AddChild( wxPGProperty* prop ); - return (wxPGChoiceEntry*) m_items[i]; - } + /** Returns height of children, recursively, and + by taking expanded/collapsed status into account. - void DecRef() + iMax is used when finding property y-positions. + */ + int GetChildrenHeight( int lh, int iMax = -1 ) const; + + /** Returns number of child properties */ + unsigned int GetChildCount() const { - m_refCount--; - wxASSERT( m_refCount >= 0 ); - if ( m_refCount == 0 ) - delete this; + return (unsigned int) m_children.size(); } -private: - wxArrayPtrVoid m_items; - - // So that multiple properties can use the same set - int m_refCount; + /** Returns sub-property at index i. */ + wxPGProperty* Item( unsigned int i ) const + { return m_children[i]; } - virtual ~wxPGChoicesData(); -}; + /** Returns last sub-property. + */ + wxPGProperty* Last() const { return m_children.back(); } -#define wxPGChoicesEmptyData ((wxPGChoicesData*)NULL) + /** Returns index of given child property. */ + int Index( const wxPGProperty* p ) const; -#endif // SWIG + /** Deletes all sub-properties. */ + void Empty(); + // Puts correct indexes to children + void FixIndicesOfChildren( unsigned int starthere = 0 ); -/** @class wxPGChoices +#ifndef SWIG + // Returns wxPropertyGridPageState in which this property resides. + wxPropertyGridPageState* GetParentState() const { return m_parentState; } +#endif - Helper class for managing choices of wxPropertyGrid properties. - Each entry can have label, value, bitmap, text colour, and background - colour. + wxPGProperty* GetItemAtY( unsigned int y, + unsigned int lh, + unsigned int* nextItemY ) const; - @library{wxpropgrid} - @category{propgrid} -*/ -class WXDLLIMPEXP_PROPGRID wxPGChoices -{ -public: - typedef long ValArrItem; + /** Returns (direct) child property with given name (or NULL if not found). + */ + wxPGProperty* GetPropertyByName( const wxString& name ) const; - /** Default constructor. */ - wxPGChoices() - { - Init(); - } +#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; + } + } - /** Copy constructor. */ - wxPGChoices( const wxPGChoices& a ) - { - if ( a.m_data != wxPGChoicesEmptyData ) - { - m_data = a.m_data; - m_data->m_refCount++; + DocStr(SetClientData, + "Associate the given client data.", ""); + void SetClientData(PyObject* clientData) { + wxPyClientData* data = new wxPyClientData(clientData); + self->SetClientObject(data); } } - - /** Constructor. */ - wxPGChoices( const wxChar** labels, const long* values = NULL ) - { - Init(); - Set(labels,values); + %pythoncode { + GetClientObject = GetClientData + SetClientObject = SetClientData } +#endif - /** Constructor. */ - wxPGChoices( const wxArrayString& labels, - const wxArrayInt& values = wxArrayInt() ) - { - Init(); - Set(labels,values); - } +#ifndef SWIG - /** Simple interface constructor. */ - wxPGChoices( wxPGChoicesData* data ) - { - wxASSERT(data); - m_data = data; - data->m_refCount++; - } + static wxString* sm_wxPG_LABEL; - /** Destructor. */ - ~wxPGChoices() - { - Free(); - } + /** This member is public so scripting language bindings + wrapper code can access it freely. + */ + void* m_clientData; - /** - Adds to current. +protected: + /** Returns text for given column. + */ + wxString GetColumnText( unsigned int col ) const; - If did not have own copies, creates them now. If was empty, identical - to set except that creates copies. + /** Returns (direct) child property with given name (or NULL if not found), + with hint index. + + @param hintIndex + Start looking for the child at this index. + + @remarks + Does not support scope (ie. Parent.Child notation). */ - void Add( const wxChar** labels, const ValArrItem* values = NULL ); + wxPGProperty* GetPropertyByNameWH( const wxString& name, + unsigned int hintIndex ) const; - /** Version that works with wxArrayString. */ - void Add( const wxArrayString& arr, const ValArrItem* values = NULL ); + /** This is used by Insert etc. */ + void AddChild2( wxPGProperty* prop, + int index = -1, + bool correct_mode = true ); - /** Version that works with wxArrayString and wxArrayInt. */ - void Add( const wxArrayString& arr, const wxArrayInt& arrint ); + void DoSetName(const wxString& str) { m_name = str; } - /** Adds single item. */ - wxPGChoiceEntry& Add( const wxString& label, - int value = wxPG_INVALID_VALUE ); + void InitAfterAdded( wxPropertyGridPageState* pageState, + wxPropertyGrid* propgrid ); - /** Adds a single item, with bitmap. */ - wxPGChoiceEntry& Add( const wxString& label, - const wxBitmap& bitmap, - int value = wxPG_INVALID_VALUE ); + // Removes child property with given pointer. Does not delete it. + void RemoveChild( wxPGProperty* p ); - /** Adds a single item with full entry information. */ - wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry ) - { - return Insert(entry, -1); - } + void SetParentState( wxPropertyGridPageState* pstate ) + { m_parentState = pstate; } - /** Adds single item. */ - wxPGChoiceEntry& AddAsSorted( const wxString& label, - int value = wxPG_INVALID_VALUE ); + // Call after fixed sub-properties added/removed after creation. + // if oldSelInd >= 0 and < new max items, then selection is + // moved to it. + void SubPropsChanged( int oldSelInd = -1 ); - void Assign( const wxPGChoices& a ) - { - AssignData(a.m_data); - } + int GetY2( int lh ) const; - void AssignData( wxPGChoicesData* data ); + wxString m_label; + wxString m_name; + wxPGProperty* m_parent; + wxPropertyGridPageState* m_parentState; - /** Delete all choices. */ - void Clear() - { - if ( m_data != wxPGChoicesEmptyData ) - m_data->Clear(); - } + wxClientData* m_clientObject; - void EnsureData() - { - if ( m_data == wxPGChoicesEmptyData ) - m_data = new wxPGChoicesData(); - } + // Overrides editor returned by property class + const wxPGEditor* m_customEditor; +#if wxUSE_VALIDATORS + // Editor is going to get this validator + wxValidator* m_validator; +#endif + // Show this in front of the value + // + // TODO: Can bitmap be implemented with wxPGCell? + wxBitmap* m_valueBitmap; - /** Gets a unsigned number identifying this list. */ - wxPGChoicesId GetId() const { return (wxPGChoicesId) m_data; }; + wxVariant m_value; + wxPGAttributeStorage m_attributes; + wxArrayPGProperty m_children; - const wxString& GetLabel( size_t ind ) const - { - return Item(ind).GetText(); - } + // Extended cell information + wxArrayPtrVoid m_cells; - size_t GetCount () const - { - wxASSERT_MSG( m_data, "When checking if wxPGChoices is valid, " - "use IsOk() instead of GetCount()" ); - return m_data->GetCount(); - } + // Choices shown in drop-down list of editor control. + wxPGChoices m_choices; - int GetValue( size_t ind ) const { return Item(ind).GetValue(); } + // Help shown in statusbar or help box. + wxString m_helpString; - /** Returns array of values matching the given strings. Unmatching strings - result in wxPG_INVALID_VALUE entry in array. - */ - wxArrayInt GetValuesForStrings( const wxArrayString& strings ) const; + // Index in parent's property array. + unsigned int m_arrIndex; - /** Returns array of indices matching given strings. Unmatching strings - are added to 'unmatched', if not NULL. - */ - wxArrayInt GetIndicesForStrings( const wxArrayString& strings, - wxArrayString* unmatched = NULL ) const; + // If not -1, then overrides m_value + int m_commonValue; - /** Returns true if choices in general are likely to have values - (depens on that all entries have values or none has) - */ - bool HasValues() const; + FlagType m_flags; - bool HasValue( unsigned int i ) const - { return (i < m_data->GetCount()) && m_data->Item(i)->HasValue(); } + // Maximum length (mainly for string properties). Could be in some sort of + // wxBaseStringProperty, but currently, for maximum flexibility and + // compatibility, we'll stick it here. Anyway, we had 3 excess bytes to use + // so short int will fit in just fine. + short m_maxLen; - int Index( const wxString& str ) const; - int Index( int val ) const; + // Root has 0, categories etc. at that level 1, etc. + unsigned char m_depth; - /** Inserts single item. */ - wxPGChoiceEntry& Insert( const wxString& label, - int index, - int value = wxPG_INVALID_VALUE ); + // m_depthBgCol indicates width of background colour between margin and item + // (essentially this is category's depth, if none then equals m_depth). + unsigned char m_depthBgCol; - /** Inserts a single item with full entry information. */ - wxPGChoiceEntry& Insert( const wxPGChoiceEntry& entry, int index ); + unsigned char m_bgColIndex; // Background brush index. + unsigned char m_fgColIndex; // Foreground colour index. - /** Returns false if this is a constant empty set of choices, - which should not be modified. - */ - bool IsOk() const - { - return ( m_data != wxPGChoicesEmptyData ); - } +private: + // Called in constructors. + void Init(); + void Init( const wxString& label, const wxString& name ); +#endif // #ifndef SWIG +}; - const wxPGChoiceEntry& Item( unsigned int i ) const - { - wxASSERT( IsOk() ); - return *m_data->Item(i); - } +// ----------------------------------------------------------------------- - wxPGChoiceEntry& Item( unsigned int i ) - { - wxASSERT( IsOk() ); - return *m_data->Item(i); - } +// +// Property class declaration helper macros +// (wxPGRootPropertyClass and wxPropertyCategory require this). +// - /** Removes count items starting at position nIndex. */ - void RemoveAt(size_t nIndex, size_t count = 1); +#define WX_PG_DECLARE_DOGETEDITORCLASS \ + virtual const wxPGEditor* DoGetEditorClass() const; #ifndef SWIG - /** Does not create copies for itself. */ - void Set( const wxChar** labels, const long* values = NULL ) - { - Free(); - Add(labels,values); - } + #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 - /** Version that works with wxArrayString. - TODO: Deprecate this. - */ - void Set( wxArrayString& arr, const long* values = (const long*) NULL ) - { - Free(); - Add(arr,values); - } -#endif // SWIG +// Implements sans constructor function. Also, first arg is class name, not +// property name. +#define WX_PG_IMPLEMENT_PROPERTY_CLASS_PLAIN(PROPNAME,T,EDITOR) \ +const wxPGEditor* PROPNAME::DoGetEditorClass() const \ +{ \ + return wxPGEditor_##EDITOR; \ +} - /** Version that works with wxArrayString and wxArrayInt. */ - void Set( const wxArrayString& labels, - const wxArrayInt& values = wxArrayInt() ) - { - Free(); - if ( &values ) - Add(labels,values); - else - Add(labels); - } +// ----------------------------------------------------------------------- - // 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; - } - } +#ifndef SWIG - // Returns data, increases refcount. - wxPGChoicesData* GetData() - { - wxASSERT( m_data->m_refCount != 0xFFFFFFF ); - m_data->m_refCount++; - return m_data; - } +/** @class wxPGRootProperty + @ingroup classes + Root parent property. +*/ +class WXDLLIMPEXP_PROPGRID wxPGRootProperty : public wxPGProperty +{ +public: + WX_PG_DECLARE_PROPERTY_CLASS(wxPGRootProperty) +public: - // Returns plain data ptr - no refcounting stuff is done. - wxPGChoicesData* GetDataPtr() const { return m_data; } + /** Constructor. */ + wxPGRootProperty(); + virtual ~wxPGRootProperty(); - // Changes ownership of data to you. - wxPGChoicesData* ExtractData() + virtual bool StringToValue( wxVariant&, const wxString&, int ) const { - wxPGChoicesData* data = m_data; - m_data = wxPGChoicesEmptyData; - return data; + return false; } - wxArrayString GetLabels() const; +protected: +}; -#ifndef SWIG - void operator= (const wxPGChoices& a) - { - AssignData(a.m_data); - } +// ----------------------------------------------------------------------- - wxPGChoiceEntry& operator[](unsigned int i) - { - return Item(i); - } +/** @class wxPropertyCategory + @ingroup classes + Category (caption) property. +*/ +class WXDLLIMPEXP_PROPGRID wxPropertyCategory : public wxPGProperty +{ + friend class wxPropertyGrid; + friend class wxPropertyGridPageState; + WX_PG_DECLARE_PROPERTY_CLASS(wxPropertyCategory) +public: - const wxPGChoiceEntry& operator[](unsigned int i) const - { - return Item(i); - } + /** Default constructor is only used in special cases. */ + wxPropertyCategory(); + + wxPropertyCategory( const wxString& label, + const wxString& name = wxPG_LABEL ); + ~wxPropertyCategory(); + + int GetTextExtent( const wxWindow* wnd, const wxFont& font ) const; protected: - wxPGChoicesData* m_data; + virtual wxString GetValueAsString( int argFlags ) const; + void SetTextColIndex( unsigned int colInd ) + { m_capFgColIndex = (wxByte) colInd; } + unsigned int GetTextColIndex() const + { return (unsigned int) m_capFgColIndex; } + + void CalculateTextExtent( wxWindow* wnd, const wxFont& font ); + + int m_textExtent; // pre-calculated length of text + wxByte m_capFgColIndex; // caption text colour index + +private: void Init(); - void Free(); -#endif // !SWIG }; -inline bool wxPGProperty::SetChoices( const wxArrayString& labels, - const wxArrayInt& values ) -{ - wxPGChoices chs(labels, values); - return SetChoices(chs); -} +#endif // !SWIG // -----------------------------------------------------------------------