// Author: Jaakko Salli
// Modified by:
// Created: 2008-08-23
-// RCS-ID: $Id:
+// RCS-ID: $Id$
// Copyright: (c) Jaakko Salli
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
};
-// Structure for relaying choice/list info.
-struct wxPGChoiceInfo
-{
- wxPGChoices* m_choices;
-};
-
-
#ifndef SWIG
// Render flags
enum
{
+ // We are painting selected item
Selected = 0x00010000,
- Control = 0x00020000
+
+ // We are painting item in choice popup
+ ChoicePopup = 0x00020000,
+
+ // We are rendering wxOwnerDrawnComboBox control
+ // (or other owner drawn control, but that is only
+ // officially supported one ATM).
+ Control = 0x00040000,
+
+ // We are painting a disable property
+ Disabled = 0x00080000,
+
+ // We are painting selected, disabled, or similar
+ // item that dictates fore- and background colours,
+ // overriding any cell values.
+ DontUseCellFgCol = 0x00100000,
+ DontUseCellBgCol = 0x00200000,
+ DontUseCellColours = DontUseCellFgCol |
+ DontUseCellBgCol
};
virtual void Render( wxDC& dc,
};
+class WXDLLIMPEXP_PROPGRID wxPGCellData : public wxObjectRefData
+{
+ friend class wxPGCell;
+public:
+ wxPGCellData();
+
+ void SetText( const wxString& text )
+ {
+ m_text = text;
+ m_hasValidText = true;
+ }
+ void SetBitmap( const wxBitmap& bitmap ) { m_bitmap = bitmap; }
+ void SetFgCol( const wxColour& col ) { m_fgCol = col; }
+ void SetBgCol( const wxColour& col ) { m_bgCol = col; }
+
+protected:
+ virtual ~wxPGCellData() { }
+
+ wxString m_text;
+ wxBitmap m_bitmap;
+ wxColour m_fgCol;
+ wxColour m_bgCol;
+
+ // True if m_text is valid and specified
+ bool m_hasValidText;
+};
+
/** @class wxPGCell
Base class for simple wxPropertyGrid cell information.
*/
-class WXDLLIMPEXP_PROPGRID wxPGCell
+class WXDLLIMPEXP_PROPGRID wxPGCell : public wxObject
{
public:
wxPGCell();
+ wxPGCell(const wxPGCell& other)
+ : wxObject(other)
+ {
+ }
+
wxPGCell( const wxString& text,
const wxBitmap& bitmap = wxNullBitmap,
const wxColour& fgCol = wxNullColour,
virtual ~wxPGCell() { }
- void SetText( const wxString& text ) { m_text = text; }
- void SetBitmap( const wxBitmap& bitmap ) { m_bitmap = bitmap; }
- void SetFgCol( const wxColour& col ) { m_fgCol = col; }
- void SetBgCol( const wxColour& col ) { m_bgCol = col; }
+ wxPGCellData* GetData()
+ {
+ return (wxPGCellData*) m_refData;
+ }
+
+ const wxPGCellData* GetData() const
+ {
+ return (const wxPGCellData*) m_refData;
+ }
+
+ bool HasText() const
+ {
+ return (m_refData && GetData()->m_hasValidText);
+ }
- const wxString& GetText() const { return m_text; }
- const wxBitmap& GetBitmap() const { return m_bitmap; }
- const wxColour& GetFgCol() const { return m_fgCol; }
- const wxColour& GetBgCol() const { return m_bgCol; }
+ /**
+ Merges valid data from srcCell into this.
+ */
+ void MergeFrom( const wxPGCell& srcCell );
+
+ void SetText( const wxString& text );
+ void SetBitmap( const wxBitmap& bitmap );
+ void SetFgCol( const wxColour& col );
+ 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; }
+ const wxColour& GetBgCol() const { return GetData()->m_bgCol; }
+
+ wxPGCell& operator=( const wxPGCell& other )
+ {
+ if ( this != &other )
+ {
+ Ref(other);
+ }
+ return *this;
+ }
protected:
- wxString m_text;
- wxBitmap m_bitmap;
- wxColour m_fgCol;
- wxColour m_bgCol;
+ virtual wxObjectRefData *CreateRefData() const
+ { return new wxPGCellData(); }
+
+ virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const;
};
~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);
data->IncRef();
variant.SetData(data);
variant.SetName(it->first);
- it++;
+ ++it;
return true;
}
/** @}
*/
-// Amalgam of flags that should be inherited by sub-properties
-#define wxPG_INHERITED_PROPFLAGS (wxPG_PROP_HIDDEN|wxPG_PROP_NOEDITOR)
-
// Combination of flags that can be stored by GetFlagsAsString
#define wxPG_STRING_STORED_FLAGS \
(wxPG_PROP_DISABLED|wxPG_PROP_HIDDEN|wxPG_PROP_NOEDITOR|wxPG_PROP_COLLAPSED)
// -----------------------------------------------------------------------
-/** @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 "<composed>" support requires this
-#ifndef SWIG
- DECLARE_ABSTRACT_CLASS(wxPGProperty)
-#endif
public:
- typedef wxUint32 FlagType;
-
- /** Basic constructor.
- */
- wxPGProperty();
+ wxPGChoiceEntry();
+ wxPGChoiceEntry(const wxPGChoiceEntry& other)
+ : wxPGCell(other)
+ {
+ m_value = other.m_value;
+ }
+ wxPGChoiceEntry( const wxString& label,
+ int value = wxPG_INVALID_VALUE )
+ : wxPGCell(), m_value(value)
+ {
+ SetText(label);
+ }
- /** Constructor.
- Non-abstract property classes should have constructor of this style:
+ virtual ~wxPGChoiceEntry() { }
- @code
+ void SetValue( int value ) { m_value = value; }
+ int GetValue() const { return m_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()
+ wxPGChoiceEntry& operator=( const wxPGChoiceEntry& other )
+ {
+ if ( this != &other )
{
- // Generally recommended way to set the initial value
- // (as it should work in pretty much 100% of cases).
- wxVariant variant;
- variant << value;
- SetValue(variant);
-
- // If has private child properties then create them here, e.g.:
- // AddChild( new wxStringProperty( "Subprop 1",
- // wxPG_LABEL,
- // value.GetSubProp1() ) );
+ Ref(other);
}
+ m_value = other.m_value;
+ return *this;
+ }
- @endcode
- */
- wxPGProperty( const wxString& label, const wxString& name );
-
- /**
- Virtual destructor.
- It is customary for derived properties to implement this.
- */
- virtual ~wxPGProperty();
+protected:
+ int m_value;
+};
- /** 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.
- */
- virtual void OnSetValue();
+typedef void* wxPGChoicesId;
- /** Override this to return something else than m_value as the value.
- */
- virtual wxVariant DoGetValue() const { return m_value; }
+class WXDLLIMPEXP_PROPGRID wxPGChoicesData
+{
+ friend class wxPGChoices;
+public:
+ // Constructor sets m_refCount to 1.
+ wxPGChoicesData();
-#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.
+ void CopyDataFrom( wxPGChoicesData* data );
- @remarks
- - Default implementation always returns true.
- */
- virtual bool ValidateValue( wxVariant& value,
- wxPGValidationInfo& validationInfo ) const;
+ wxPGChoiceEntry& Insert( int index, const wxPGChoiceEntry& item );
- /**
- 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).
+ // Delete all entries
+ void Clear();
- @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;
+ unsigned int GetCount() const
+ {
+ return (unsigned int) m_items.size();
+ }
- /**
- Converts 'number' (including choice selection) into proper value
- 'variant'.
+ const wxPGChoiceEntry& Item( unsigned int i ) const
+ {
+ wxASSERT_MSG( i < GetCount(), "invalid index" );
+ return m_items[i];
+ }
- Returns true if new (different than m_value) value could be interpreted
- from the integer.
+ wxPGChoiceEntry& Item( unsigned int i )
+ {
+ wxASSERT_MSG( i < GetCount(), "invalid index" );
+ return m_items[i];
+ }
- @param argFlags
- If wxPG_FULL_VALUE is set, returns complete, storable value instead
- of displayable one.
+ void DecRef()
+ {
+ m_refCount--;
+ wxASSERT( m_refCount >= 0 );
+ if ( m_refCount == 0 )
+ delete this;
+ }
- @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)
+private:
+ wxVector<wxPGChoiceEntry> m_items;
-public:
- /** Returns text representation of property's value.
+ // So that multiple properties can use the same set
+ int m_refCount;
- @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.
+ virtual ~wxPGChoicesData();
+};
- @remarks
- Default implementation returns string composed from text
- representations of child properties.
- */
- virtual wxString GetValueAsString( int argFlags = 0 ) const;
+#define wxPGChoicesEmptyData ((wxPGChoicesData*)NULL)
- /** 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 );
+#endif // SWIG
- /** 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 );
+/** @class wxPGChoices
- /**
- Returns size of the custom painted image in front of property.
+ Helper class for managing choices of wxPropertyGrid properties.
+ 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.
- 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;
+ @remarks If you do not specify value for entry, index is used.
- /**
- 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).
-
- If the event causes value to be changed, SetValueInEvent()
- should be called to set the new value.
-
- @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 );
+ /** Default constructor. */
+ wxPGChoices()
+ {
+ Init();
+ }
/**
- 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.
-
- Sample pseudo-code implementation:
-
- @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);
-
- // Copy childValue into data.
- switch ( childIndex )
- {
- case 0:
- data.SetSubProp1( childvalue.GetLong() );
- break;
- case 1:
- data.SetSubProp2( childvalue.GetString() );
- break;
- ...
- }
- }
- @endcode
-
- @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.
+ Copy constructor, uses reference counting. To create a real copy,
+ use Copy() member function instead.
*/
- virtual void ChildChanged( wxVariant& thisValue,
- int childIndex,
- wxVariant& childValue ) const;
-
- /** Returns pointer to an instance of used editor.
- */
- 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):
-
- @code
-
- wxValidator* wxMyPropertyClass::DoGetValidator () const
+ wxPGChoices( const wxPGChoices& a )
+ {
+ if ( a.m_data != wxPGChoicesEmptyData )
{
- WX_PG_DOGETVALIDATOR_ENTRY()
-
- wxMyValidator* validator = new wxMyValidator(...);
-
- ... prepare validator...
-
- WX_PG_DOGETVALIDATOR_EXIT(validator)
+ m_data = a.m_data;
+ m_data->m_refCount++;
}
-
- @endcode
-
- @remarks
- You can get common filename validator by returning
- wxFileProperty::GetClassValidator(). wxDirProperty,
- for example, uses it.
- */
- virtual wxValidator* DoGetValidator () const;
+ }
/**
- Returns current value's index to the choice control.
+ Constructor.
- 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.
+ @param labels
+ Labels for choices
- @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.
+ @param values
+ Values for choices. If NULL, indexes are used.
*/
- virtual int GetChoiceInfo( wxPGChoiceInfo* choiceinfo );
+ wxPGChoices( const wxChar** labels, const long* values = NULL )
+ {
+ Init();
+ Set(labels,values);
+ }
/**
- 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).
-
- 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).
+ Constructor.
- 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 labels
+ Labels for choices
- @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.
+ @param values
+ Values for choices. If empty, indexes are used.
+ */
+ wxPGChoices( const wxArrayString& labels,
+ const wxArrayInt& values = wxArrayInt() )
+ {
+ Init();
+ Set(labels,values);
+ }
- @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.
+ /** Simple interface constructor. */
+ wxPGChoices( wxPGChoicesData* data )
+ {
+ wxASSERT(data);
+ m_data = data;
+ data->m_refCount++;
+ }
- @see GetValueAsString()
- */
- virtual void OnCustomPaint( wxDC& dc,
- const wxRect& rect,
- wxPGPaintData& paintdata );
+ /** Destructor. */
+ ~wxPGChoices()
+ {
+ Free();
+ }
/**
- Returns used wxPGCellRenderer instance for given property column
- (label=0, value=1).
+ Adds to current.
- Default implementation returns editor's renderer for all columns.
- */
- virtual wxPGCellRenderer* GetCellRenderer( int column ) const;
+ If did not have own copies, creates them now. If was empty, identical
+ to set except that creates copies.
- /**
- Refresh values of child properties.
+ @param labels
+ Labels for added choices.
- Automatically called after value is set.
+ @param values
+ Values for added choices. If empty, relevant entry indexes are used.
*/
- virtual void RefreshChildren();
+ void Add( const wxChar** labels, const ValArrItem* values = NULL );
- /** Special handling for attributes of this property.
+ /** Version that works with wxArrayString and wxArrayInt. */
+ void Add( const wxArrayString& arr, const wxArrayInt& arrint = wxArrayInt() );
- If returns false, then the attribute will be automatically stored in
- m_attributes.
+ /**
+ Adds a single choice.
- Default implementation simply returns false.
+ @param label
+ Label for added choice.
+
+ @param value
+ Value for added choice. If unspecified, index is used.
*/
- virtual bool DoSetAttribute( const wxString& name, wxVariant& value );
+ wxPGChoiceEntry& Add( const wxString& label,
+ int value = wxPG_INVALID_VALUE );
- /** Returns value of an attribute.
+ /** Adds a single item, with bitmap. */
+ wxPGChoiceEntry& Add( const wxString& label,
+ const wxBitmap& bitmap,
+ int value = wxPG_INVALID_VALUE );
- Override if custom handling of attributes is needed.
+ /** Adds a single item with full entry information. */
+ wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry )
+ {
+ return Insert(entry, -1);
+ }
- Default implementation simply return NULL variant.
+ /** Adds single item. */
+ 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.
*/
- virtual wxVariant DoGetAttribute( const wxString& name ) const;
+ void Assign( const wxPGChoices& a )
+ {
+ AssignData(a.m_data);
+ }
- /** Returns instance of a new wxPGEditorDialogAdapter instance, which is
- used when user presses the (optional) button next to the editor control;
+ void AssignData( wxPGChoicesData* data );
- Default implementation returns NULL (ie. no action is generated when
- button is pressed).
- */
- virtual wxPGEditorDialogAdapter* GetEditorDialog() const;
+ /** Delete all choices. */
+ void Clear();
/**
- Adds entry to property's wxPGChoices and editor control (if it is
- active).
-
- Returns index of item added.
+ Returns a real copy of the choices.
*/
- int AppendChoice( const wxString& label, int value = wxPG_INVALID_VALUE )
+ wxPGChoices Copy() const
{
- return InsertChoice(label,-1,value);
+ wxPGChoices dst;
+ dst.EnsureData();
+ dst.m_data->CopyDataFrom(m_data);
+ return dst;
}
- /** Returns wxPGCell of given column, NULL if none. If valid
- object is returned, caller will gain its ownership.
- */
- wxPGCell* AcquireCell( unsigned int column )
+ void EnsureData()
{
- if ( column >= m_cells.size() )
- return NULL;
+ if ( m_data == wxPGChoicesEmptyData )
+ m_data = new wxPGChoicesData();
+ }
+
+ /** Gets a unsigned number identifying this list. */
+ wxPGChoicesId GetId() const { return (wxPGChoicesId) m_data; };
- wxPGCell* cell = (wxPGCell*) m_cells[column];
- m_cells[column] = NULL;
- return cell;
+ const wxString& GetLabel( unsigned int ind ) const
+ {
+ return Item(ind).GetText();
}
- /**
- 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
+ unsigned int GetCount () const
{
- if ( m_flags & (wxPG_PROP_COMPOSED_VALUE|wxPG_PROP_AGGREGATE) )
- return true;
+ if ( !m_data )
+ return 0;
- return false;
+ return m_data->GetCount();
}
- /**
- Removes entry from property's wxPGChoices and editor control (if it is
- active).
+ int GetValue( unsigned int ind ) const { return Item(ind).GetValue(); }
- If selected item is deleted, then the value is set to unspecified.
+ /** Returns array of values matching the given strings. Unmatching strings
+ result in wxPG_INVALID_VALUE entry in array.
*/
- void DeleteChoice( int index );
-
- /**
- 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.
+ wxArrayInt GetValuesForStrings( const wxArrayString& strings ) const;
- Common values are disabled by the default for all properties.
+ /** Returns array of indices matching given strings. Unmatching strings
+ are added to 'unmatched', if not NULL.
*/
- void EnableCommonValue( bool enable = true )
- {
- if ( enable ) SetFlag( wxPG_PROP_USES_COMMON_VALUE );
- else ClearFlag( wxPG_PROP_USES_COMMON_VALUE );
- }
-
- /** Composes text from values of child properties. */
- void GenerateComposedValue( wxString& text, int argFlags = 0 ) const;
-
- /** Returns property's label. */
- const wxString& GetLabel() const { return m_label; }
-
- /** Returns property's name with all (non-category, non-root) parents. */
- wxString GetName() const;
-
- /**
- Returns property's base name (ie parent's name is not added in any
- case)
- */
- const wxString& GetBaseName() const { return m_name; }
+ wxArrayInt GetIndicesForStrings( const wxArrayString& strings,
+ wxArrayString* unmatched = NULL ) const;
- wxPGChoices& GetChoices();
+ int Index( const wxString& str ) const;
+ int Index( int val ) const;
- const wxPGChoices& GetChoices() const;
+ /** Inserts single item. */
+ wxPGChoiceEntry& Insert( const wxString& label,
+ int index,
+ int value = wxPG_INVALID_VALUE );
- const wxPGChoiceEntry* GetCurrentChoice() const;
+ /** Inserts a single item with full entry information. */
+ wxPGChoiceEntry& Insert( const wxPGChoiceEntry& entry, int index );
- /** Returns coordinate to the top y of the property. Note that the
- position of scrollbars is not taken into account.
+ /** Returns false if this is a constant empty set of choices,
+ which should not be modified.
*/
- int GetY() const;
-
- wxVariant GetValue() const
+ bool IsOk() const
{
- return DoGetValue();
+ return ( m_data != wxPGChoicesEmptyData );
}
-#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.
- */
- wxVariant& GetValueRef()
+ const wxPGChoiceEntry& Item( unsigned int i ) const
{
- return m_value;
+ wxASSERT( IsOk() );
+ return m_data->Item(i);
}
- const wxVariant& GetValueRef() const
+ wxPGChoiceEntry& Item( unsigned int i )
{
- return m_value;
+ wxASSERT( IsOk() );
+ return m_data->Item(i);
}
-#endif
-
- /** Same as GetValueAsString, except takes common value into account.
- */
- wxString GetValueString( int argFlags = 0 ) const;
- void UpdateControl( wxWindow* primary );
+ /** Removes count items starting at position nIndex. */
+ void RemoveAt(size_t nIndex, size_t count = 1);
- /** Returns wxPGCell of given column, NULL if none. wxPGProperty
- will retain ownership of the cell object.
- */
- wxPGCell* GetCell( unsigned int column ) const
+#ifndef SWIG
+ /** Does not create copies for itself. */
+ void Set( const wxChar** labels, const long* values = NULL )
{
- if ( column >= m_cells.size() )
- return NULL;
-
- return (wxPGCell*) m_cells[column];
+ Free();
+ Add(labels,values);
}
+#endif // SWIG
- unsigned int GetChoiceCount() const;
-
- wxString GetChoiceString( unsigned int index );
-
- /** Return number of displayed common values for this property.
- */
- int GetDisplayedCommonValueCount() const;
-
- wxString GetDisplayedString() const
+ /** Version that works with wxArrayString and wxArrayInt. */
+ void Set( const wxArrayString& labels,
+ const wxArrayInt& values = wxArrayInt() )
{
- return GetValueString(0);
+ Free();
+ if ( &values )
+ Add(labels,values);
+ else
+ Add(labels);
}
- /** 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; }
-
- /** Returns true if property has editable wxTextCtrl when selected.
-
- @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;
+ // Creates exclusive copy of current choices
+ void AllocExclusive();
- bool IsValueUnspecified() const
+ // Returns data, increases refcount.
+ wxPGChoicesData* GetData()
{
- return m_value.IsNull();
+ wxASSERT( m_data->m_refCount != 0xFFFFFFF );
+ m_data->m_refCount++;
+ return m_data;
}
- FlagType HasFlag( FlagType flag ) const
- {
- return ( m_flags & flag );
- }
+ // Returns plain data ptr - no refcounting stuff is done.
+ wxPGChoicesData* GetDataPtr() const { return m_data; }
- /** Returns comma-delimited string of property attributes.
- */
- const wxPGAttributeStorage& GetAttributes() const
+ // Changes ownership of data to you.
+ wxPGChoicesData* ExtractData()
{
- return m_attributes;
+ wxPGChoicesData* data = m_data;
+ m_data = wxPGChoicesEmptyData;
+ return data;
}
- /** Returns m_attributes as list wxVariant.
- */
- wxVariant GetAttributesAsList() const;
+ wxArrayString GetLabels() const;
- FlagType GetFlags() const
+#ifndef SWIG
+ void operator= (const wxPGChoices& a)
{
- return m_flags;
+ if (this != &a)
+ AssignData(a.m_data);
}
- const wxPGEditor* GetEditorClass() const;
-
- wxString GetValueType() const
+ wxPGChoiceEntry& operator[](unsigned int i)
{
- return m_value.GetType();
+ return Item(i);
}
- /** Returns editor used for given column. NULL for no editor.
- */
- const wxPGEditor* GetColumnEditor( int column ) const
+ const wxPGChoiceEntry& operator[](unsigned int i) const
{
- if ( column == 1 )
- return GetEditorClass();
-
- return NULL;
+ return Item(i);
}
- /** Returns common value selected for this property. -1 for none.
- */
- int GetCommonValue() const
- {
- return m_commonValue;
- }
+protected:
+ wxPGChoicesData* m_data;
- /** Returns true if property has even one visible child.
- */
- bool HasVisibleChildren() const;
+ void Init();
+ void Free();
+#endif // !SWIG
+};
- /**
- Adds entry to property's wxPGChoices and editor control (if it is
- active).
+// -----------------------------------------------------------------------
- Returns index of item added.
- */
- int InsertChoice( const wxString& label,
- int index,
- int value = wxPG_INVALID_VALUE );
+/** @class wxPGProperty
- /**
- Returns true if this property is actually a wxPropertyCategory.
- */
- bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY)?true:false; }
+ wxPGProperty is base class for all wxPropertyGrid properties.
- /** Returns true if this property is actually a wxRootProperty.
- */
- bool IsRoot() const { return (m_parent == NULL); }
+ NB: Full class overview is now only present in
+ interface/wx/propgrid/property.h.
- /** Returns true if this is a sub-property. */
- bool IsSubProperty() const
- {
- wxPGProperty* parent = (wxPGProperty*)m_parent;
- if ( parent && !parent->IsCategory() )
- return true;
- return false;
- }
+ @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 "<composed>" support requires this
+#ifndef SWIG
+ DECLARE_ABSTRACT_CLASS(wxPGProperty)
+#endif
+public:
+ typedef wxUint32 FlagType;
- /** Returns last visible sub-property, recursively.
+ /** Basic constructor.
*/
- const wxPGProperty* GetLastVisibleSubItem() const;
-
- wxVariant GetDefaultValue() const;
+ wxPGProperty();
- int GetMaxLength() const
- {
- return (int) m_maxLen;
- }
+ /** Constructor.
+ Non-abstract property classes should have constructor of this style:
- /**
- Determines, recursively, if all children are not unspecified.
+ @code
- Takes values in given list into account.
- */
- bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const;
+ // 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);
- /** Updates composed values of parent non-category properties, recursively.
- Returns topmost property updated.
+ // 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() ) );
+ }
- @remarks
- - Must not call SetValue() (as can be called in it).
+ @endcode
*/
- wxPGProperty* UpdateParentValues();
+ wxPGProperty( const wxString& label, const wxString& name );
- /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
+ /**
+ Virtual destructor.
+ It is customary for derived properties to implement this.
*/
- FlagType UsesAutoUnspecified() const
- {
- return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED);
- }
-
- wxBitmap* GetValueImage() const
- {
- return m_valueBitmap;
- }
+ virtual ~wxPGProperty();
- wxVariant GetAttribute( const wxString& name ) const;
+ /** This virtual function is called after m_value has been set.
- /**
- Returns named attribute, as string, if found.
+ @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();
- Otherwise defVal is returned.
+ /** Override this to return something else than m_value as the value.
*/
- wxString GetAttribute( const wxString& name, const wxString& defVal ) const;
+ virtual wxVariant DoGetValue() const { return m_value; }
- /**
- Returns named attribute, as long, if found.
+#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.
- Otherwise defVal is returned.
+ @remarks
+ - Default implementation always returns true.
*/
- long GetAttributeAsLong( const wxString& name, long defVal ) const;
+ virtual bool ValidateValue( wxVariant& value,
+ wxPGValidationInfo& validationInfo ) const;
/**
- Returns named attribute, as double, if found.
+ Converts text into wxVariant value appropriate for this property.
- Otherwise defVal is returned.
- */
- double GetAttributeAsDouble( const wxString& name, double defVal ) const;
+ @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.
- unsigned int GetArrIndex() const { return m_arrIndex; }
+ @param text
+ Text to be translated into variant.
- unsigned int GetDepth() const { return (unsigned int)m_depth; }
+ @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 ValueToString()
+ called with this same flag).
- /** 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;
+ @return Returns @true if resulting wxVariant value was different.
- /** Returns position in parent's array. */
- unsigned int GetIndexInParent() const
- {
- return (unsigned int)m_arrIndex;
- }
+ @remarks Default implementation converts semicolon delimited tokens into
+ child values. Only works for properties with children.
- /** 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.
+ 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).
*/
- inline bool Hide( bool hide, int flags = wxPG_RECURSE );
+ virtual bool StringToValue( wxVariant& variant,
+ const wxString& text,
+ int argFlags = 0 ) const;
- bool IsExpanded() const
- { return (!(m_flags & wxPG_PROP_COLLAPSED) && GetChildCount()); }
+ /**
+ Converts integer (possibly a choice selection) into wxVariant value
+ appropriate for this property.
- /** Returns true if all parents expanded.
- */
- bool IsVisible() const;
+ @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.
- bool IsEnabled() const { return !(m_flags & wxPG_PROP_DISABLED); }
+ @param number
+ Integer to be translated into variant.
- /** If property's editor is created this forces its recreation.
- Useful in SetAttribute etc. Returns true if actually did anything.
- */
- bool RecreateEditor();
+ @param argFlags
+ If wxPG_FULL_VALUE is set, returns complete, storable value instead
+ of displayable one.
- /** If property's editor is active, then update it's value.
- */
- void RefreshEditor();
+ @return Returns @true if resulting wxVariant value was different.
- /** Sets an attribute for this property.
- @param name
- Text identifier of attribute. See @ref propgrid_property_attributes.
- @param value
- Value of attribute.
+ @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).
*/
- void SetAttribute( const wxString& name, wxVariant value );
-
- void SetAttributes( const wxPGAttributeStorage& attributes );
+ virtual bool IntToValue( wxVariant& value,
+ int number,
+ int argFlags = 0 ) const;
+#endif // !defined(SWIG) || defined(CREATE_VCW)
+ /**
+ Converts property value into a text representation.
-#ifndef SWIG
- /** Sets editor for a property.
+ @param value
+ Value to be converted.
- @param editor
- For builtin editors, use wxPGEditor_X, where X is builtin editor's
- name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
- list).
+ @param argFlags
+ If 0 (default value), then displayed string is returned.
+ If wxPG_FULL_VALUE is set, returns complete, storable string value
+ instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
+ string value that must be editable in textctrl. If
+ wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
+ display as a part of string property's composite text
+ representation.
- For custom editors, use pointer you received from
- wxPropertyGrid::RegisterEditorClass().
+ @remarks Default implementation calls GenerateComposedValue().
*/
- void SetEditor( const wxPGEditor* editor )
- {
- m_customEditor = editor;
- }
-#endif
+ virtual wxString ValueToString( wxVariant& value, int argFlags = 0 ) const;
- /** Sets editor for a property.
+ /** 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.
*/
- inline void SetEditor( const wxString& editorName );
+ bool SetValueFromString( const wxString& text, int flags = wxPG_PROGRAMMATIC_VALUE );
- /** Sets cell information for given column.
-
- Note that the property takes ownership of given wxPGCell instance.
+ /** 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.
*/
- void SetCell( int column, wxPGCell* cellObj );
+ bool SetValueFromInt( long value, int flags = 0 );
- /** 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 size of the custom painted image in front of property.
- /** Sets common value selected for this property. -1 for none.
+ 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).
*/
- void SetCommonValue( int commonValue )
- {
- m_commonValue = commonValue;
- }
+ virtual wxSize OnMeasureImage( int item = -1 ) const;
- /** Sets flags from a '|' delimited string. Note that flag names are not
- prepended with 'wxPG_PROP_'.
- */
- void SetFlagsFromString( const wxString& str );
+ /**
+ Events received by editor widgets are processed here.
- /** Sets property's "is it modified?" flag. Affects children recursively.
- */
- void SetModifiedStatus( bool modified )
- {
- SetFlagRecursively(wxPG_PROP_MODIFIED, modified);
- }
+ 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).
- /** Call in OnEvent(), OnButtonClick() etc. to change the property value
- based on user input.
+ If the event causes value to be changed, SetValueInEvent()
+ should be called to set the new value.
+ @param event
+ Associated wxEvent.
+ @return
+ Should return true if any changes in value should be reported.
@remarks
- This method is const since it doesn't actually modify value, but posts
- given variant as pending value, stored in wxPropertyGrid.
+ 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.
*/
- void SetValueInEvent( wxVariant value ) const;
+ virtual bool OnEvent( wxPropertyGrid* propgrid,
+ wxWindow* wnd_primary,
+ wxEvent& event );
/**
- Call this to set value of the property.
+ Called after value of a child property has been altered.
- Unlike methods in wxPropertyGrid, this does not automatically update
- the display.
+ 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
- Use wxPropertyGrid::ChangePropertyValue() instead if you need to run
- through validation process and send property change event.
+ Sample pseudo-code implementation:
- If you need to change property value in event, based on user input, use
- SetValueInEvent() instead.
+ @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);
- @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 );
+ // Copy childValue into data.
+ switch ( childIndex )
+ {
+ case 0:
+ data.SetSubProp1( childvalue.GetLong() );
+ break;
+ case 1:
+ data.SetSubProp2( childvalue.GetString() );
+ break;
+ ...
+ }
+ }
+ @endcode
- /** Set wxBitmap in front of the value. This bitmap may be ignored
- by custom cell renderers.
+ @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.
*/
- void SetValueImage( wxBitmap& bmp );
+ virtual void ChildChanged( wxVariant& thisValue,
+ int childIndex,
+ wxVariant& childValue ) const;
- /** If property has choices and they are not yet exclusive, new such copy
- of them will be created.
+ /** Returns pointer to an instance of used editor.
*/
- void SetChoicesExclusive();
+ virtual const wxPGEditor* DoGetEditorClass() const;
- void SetExpanded( bool expanded )
- {
- if ( !expanded ) m_flags |= wxPG_PROP_COLLAPSED;
- else m_flags &= ~wxPG_PROP_COLLAPSED;
- }
+ /** 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.
- void SetFlag( FlagType flag ) { m_flags |= flag; }
+ 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 SetFlagRecursively( FlagType flag, bool set );
+ @code
- void SetHelpString( const wxString& helpString )
- {
- m_helpString = helpString;
- }
+ wxValidator* wxMyPropertyClass::DoGetValidator () const
+ {
+ WX_PG_DOGETVALIDATOR_ENTRY()
- void SetLabel( const wxString& label ) { m_label = label; }
+ wxMyValidator* validator = new wxMyValidator(...);
- inline void SetName( const wxString& newName );
+ ... prepare validator...
- void SetValueToUnspecified()
- {
- wxVariant val; // Create NULL variant
- SetValue(val);
- }
+ WX_PG_DOGETVALIDATOR_EXIT(validator)
+ }
-#if wxUSE_VALIDATORS
- /** Sets wxValidator for a property*/
- void SetValidator( const wxValidator& validator )
- {
- m_validator = wxDynamicCast(validator.Clone(),wxValidator);
- }
+ @endcode
- /** Gets assignable version of property's validator. */
- wxValidator* GetValidator() const
- {
- if ( m_validator )
- return m_validator;
- return DoGetValidator();
- }
-#endif // #if wxUSE_VALIDATORS
+ @remarks
+ You can get common filename validator by returning
+ wxFileProperty::GetClassValidator(). wxDirProperty,
+ for example, uses it.
+ */
+ virtual wxValidator* DoGetValidator () const;
+
+ /**
+ 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).
+
+ 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).
+
+ 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.
- /** 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.
+ - 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.
+
+ @see ValueToString()
*/
- bool PrepareValueForDialogEditing( wxPropertyGrid* propgrid );
+ virtual void OnCustomPaint( wxDC& dc,
+ const wxRect& rect,
+ wxPGPaintData& paintdata );
-#ifndef SWIG
- /** Returns client data (void*) of a property.
+ /**
+ Returns used wxPGCellRenderer instance for given property column
+ (label=0, value=1).
+
+ Default implementation returns editor's renderer for all columns.
*/
- void* GetClientData() const
- {
- return m_clientData;
- }
+ virtual wxPGCellRenderer* GetCellRenderer( int column ) const;
- /** Sets client data (void*) of a property.
- @remarks
- This untyped client data has to be deleted manually.
+ /** Returns which choice is currently selected. Only applies to properties
+ which have choices.
+
+ Needs to reimplemented in derived class if property value does not
+ map directly to a choice. Integer as index, bool, and string usually do.
*/
- void SetClientData( void* clientData )
- {
- m_clientData = clientData;
- }
+ virtual int GetChoiceSelection() const;
- /** Returns client object of a property.
+ /**
+ Refresh values of child properties.
+
+ Automatically called after value is set.
*/
- void SetClientObject(wxClientData* clientObject)
- {
- delete m_clientObject;
- m_clientObject = clientObject;
- }
+ virtual void RefreshChildren();
- /** Sets managed client object of a property.
+ /** Special handling for attributes of this property.
+
+ If returns false, then the attribute will be automatically stored in
+ m_attributes.
+
+ Default implementation simply returns false.
*/
- wxClientData *GetClientObject() const { return m_clientObject; }
-#endif
+ virtual bool DoSetAttribute( const wxString& name, wxVariant& value );
- /** Sets new set of choices for property.
+ /** Returns value of an attribute.
- @remarks
- This operation clears the property value.
+ Override if custom handling of attributes is needed.
+
+ Default implementation simply return NULL variant.
*/
- bool SetChoices( wxPGChoices& choices );
+ virtual wxVariant DoGetAttribute( const wxString& name ) const;
- /** Sets new set of choices for property.
+ /** Returns instance of a new wxPGEditorDialogAdapter instance, which is
+ used when user presses the (optional) button next to the editor control;
+
+ Default implementation returns NULL (ie. no action is generated when
+ button is pressed).
*/
- inline bool SetChoices( const wxArrayString& labels,
- const wxArrayInt& values = wxArrayInt() );
+ virtual wxPGEditorDialogAdapter* GetEditorDialog() const;
- /** Set max length of text in text editor.
+ /**
+ 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.
*/
- inline bool SetMaxLength( int maxLen );
+ virtual void OnValidationFailure( wxVariant& pendingValue );
- /** Call with 'false' in OnSetValue to cancel value changes after all
- (ie. cancel 'true' returned by StringToValue() or IntToValue()).
+ /** Append a new choice to property's list of choices.
*/
- void SetWasModified( bool set = true )
+ int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE )
{
- if ( set ) m_flags |= wxPG_PROP_WAS_MODIFIED;
- else m_flags &= ~wxPG_PROP_WAS_MODIFIED;
+ return InsertChoice(label, wxNOT_FOUND, value);
}
- const wxString& GetHelpString() const
+ /**
+ 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
{
- return m_helpString;
- }
+ if ( m_flags & (wxPG_PROP_COMPOSED_VALUE|wxPG_PROP_AGGREGATE) )
+ return true;
- void ClearFlag( FlagType flag ) { m_flags &= ~(flag); }
+ return false;
+ }
- // Use, for example, to detect if item is inside collapsed section.
- bool IsSomeParent( wxPGProperty* candidate_parent ) const;
+ /**
+ Deletes children of the property.
+ */
+ void DeleteChildren();
/**
- Adapts list variant into proper value using consecutive
- ChildChanged-calls.
+ Removes entry from property's wxPGChoices and editor control (if it is
+ active).
+
+ If selected item is deleted, then the value is set to unspecified.
*/
- void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
+ void DeleteChoice( int index );
- /** This is used by properties that have fixed sub-properties. */
- void AddChild( wxPGProperty* prop );
+ /**
+ 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.
- /** Returns height of children, recursively, and
- by taking expanded/collapsed status into account.
+ Common values are disabled by the default for all properties.
+ */
+ void EnableCommonValue( bool enable = true )
+ {
+ if ( enable ) SetFlag( wxPG_PROP_USES_COMMON_VALUE );
+ else ClearFlag( wxPG_PROP_USES_COMMON_VALUE );
+ }
- iMax is used when finding property y-positions.
+ /**
+ Composes text from values of child properties.
*/
- int GetChildrenHeight( int lh, int iMax = -1 ) const;
+ wxString GenerateComposedValue() const
+ {
+ wxString s;
+ DoGenerateComposedValue(s);
+ return s;
+ }
- /** Returns number of child properties */
- unsigned int GetChildCount() const { return m_children.GetCount(); }
+ /** Returns property's label. */
+ const wxString& GetLabel() const { return m_label; }
- /** Returns sub-property at index i. */
- wxPGProperty* Item( size_t i ) const
- { return (wxPGProperty*)m_children.Item(i); }
+ /** Returns property's name with all (non-category, non-root) parents. */
+ wxString GetName() const;
- /** Returns last sub-property.
- */
- wxPGProperty* Last() const { return (wxPGProperty*)m_children.Last(); }
+ /**
+ Returns property's base name (ie parent's name is not added in any
+ case)
+ */
+ const wxString& GetBaseName() const { return m_name; }
- /** Returns index of given sub-property. */
- int Index( const wxPGProperty* p ) const
- { return m_children.Index((wxPGProperty*)p); }
+ /** Returns read-only reference to property's list of choices.
+ */
+ const wxPGChoices& GetChoices() const
+ {
+ return m_choices;
+ }
- /** Deletes all sub-properties. */
- void Empty();
+ /** Returns coordinate to the top y of the property. Note that the
+ position of scrollbars is not taken into account.
+ */
+ int GetY() const;
- // Puts correct indexes to children
- void FixIndexesOfChildren( size_t starthere = 0 );
+ wxVariant GetValue() const
+ {
+ return DoGetValue();
+ }
#ifndef SWIG
- // Returns wxPropertyGridPageState in which this property resides.
- wxPropertyGridPageState* GetParentState() const { return m_parentState; }
+ /** 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.
+ */
+ wxVariant& GetValueRef()
+ {
+ return m_value;
+ }
+
+ const wxVariant& GetValueRef() const
+ {
+ return m_value;
+ }
#endif
- wxPGProperty* GetItemAtY( unsigned int y,
- unsigned int lh,
- unsigned int* nextItemY ) const;
+ /** Returns text representation of property's value.
- /** Returns (direct) child property with given name (or NULL if not found).
- */
- wxPGProperty* GetPropertyByName( const wxString& name ) const;
+ @param argFlags
+ If 0 (default value), then displayed string is returned.
+ If wxPG_FULL_VALUE is set, returns complete, storable string value
+ instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
+ string value that must be editable in textctrl. If
+ wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
+ display as a part of string property's composite text
+ representation.
-#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;
- }
- }
+ @remarks In older versions, this function used to be overridden to convert
+ property's value into a string representation. This function is
+ now handled by ValueToString(), and overriding this function now
+ will result in run-time assertion failure.
+ */
+ virtual wxString GetValueAsString( int argFlags = 0 ) const;
- DocStr(SetClientData,
- "Associate the given client data.", "");
- void SetClientData(PyObject* clientData) {
- wxPyClientData* data = new wxPyClientData(clientData);
- self->SetClientObject(data);
- }
+ /** Synonymous to GetValueAsString().
+
+ @deprecated Use GetValueAsString() instead.
+
+ @see GetValueAsString()
+ */
+ wxDEPRECATED( wxString GetValueString( int argFlags = 0 ) const );
+
+ /**
+ Returns wxPGCell of given column.
+ */
+ const wxPGCell& GetCell( unsigned int column ) const;
+
+ wxPGCell& GetCell( unsigned int column );
+
+ /** Return number of displayed common values for this property.
+ */
+ int GetDisplayedCommonValueCount() const;
+
+ wxString GetDisplayedString() const
+ {
+ return GetValueAsString(0);
}
- %pythoncode {
- GetClientObject = GetClientData
- SetClientObject = SetClientData
+
+ /** 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; }
+
+ /** Returns true if property has editable wxTextCtrl when selected.
+
+ @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
+ {
+ return m_value.IsNull();
}
-#endif
-#ifndef SWIG
+ FlagType HasFlag( FlagType flag ) const
+ {
+ return ( m_flags & flag );
+ }
- static wxString* sm_wxPG_LABEL;
+ /** Returns comma-delimited string of property attributes.
+ */
+ const wxPGAttributeStorage& GetAttributes() const
+ {
+ return m_attributes;
+ }
- /** This member is public so scripting language bindings
- wrapper code can access it freely.
+ /** Returns m_attributes as list wxVariant.
*/
- void* m_clientData;
+ wxVariant GetAttributesAsList() const;
-protected:
- /** Returns text for given column.
+ FlagType GetFlags() const
+ {
+ return m_flags;
+ }
+
+ const wxPGEditor* GetEditorClass() const;
+
+ wxString GetValueType() const
+ {
+ return m_value.GetType();
+ }
+
+ /** Returns editor used for given column. NULL for no editor.
*/
- wxString GetColumnText( unsigned int col ) const;
+ const wxPGEditor* GetColumnEditor( int column ) const
+ {
+ if ( column == 1 )
+ return GetEditorClass();
- /** Returns (direct) child property with given name (or NULL if not found),
- with hint index.
+ return NULL;
+ }
- @param hintIndex
- Start looking for the child at this index.
+ /** Returns common value selected for this property. -1 for none.
+ */
+ int GetCommonValue() const
+ {
+ return m_commonValue;
+ }
- @remarks
- Does not support scope (ie. Parent.Child notation).
+ /** Returns true if property has even one visible child.
*/
- wxPGProperty* GetPropertyByNameWH( const wxString& name,
- unsigned int hintIndex ) const;
+ bool HasVisibleChildren() const;
- /** This is used by Insert etc. */
- void AddChild2( wxPGProperty* prop,
- int index = -1,
- bool correct_mode = true );
+ /** Inserts a new choice to property's list of choices.
+ */
+ int InsertChoice( const wxString& label, int index, int value = wxPG_INVALID_VALUE );
- void DoSetName(const wxString& str) { m_name = str; }
+ /**
+ Returns true if this property is actually a wxPropertyCategory.
+ */
+ bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY)?true:false; }
- // Call for after sub-properties added with AddChild
- void PrepareSubProperties();
+ /** Returns true if this property is actually a wxRootProperty.
+ */
+ bool IsRoot() const { return (m_parent == NULL); }
- void SetParentalType( int flag )
+ /** Returns true if this is a sub-property. */
+ bool IsSubProperty() const
{
- m_flags &= ~(wxPG_PROP_PROPERTY|wxPG_PROP_PARENTAL_FLAGS);
- m_flags |= flag;
+ wxPGProperty* parent = (wxPGProperty*)m_parent;
+ if ( parent && !parent->IsCategory() )
+ return true;
+ return false;
}
- void SetParentState( wxPropertyGridPageState* pstate )
- { m_parentState = pstate; }
+ /** Returns last visible sub-property, recursively.
+ */
+ const wxPGProperty* GetLastVisibleSubItem() const;
- // 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 );
+ wxVariant GetDefaultValue() const;
- int GetY2( int lh ) const;
+ int GetMaxLength() const
+ {
+ return (int) m_maxLen;
+ }
- wxString m_label;
- wxString m_name;
- wxPGProperty* m_parent;
- wxPropertyGridPageState* m_parentState;
+ /**
+ Determines, recursively, if all children are not unspecified.
- wxClientData* m_clientObject;
+ @param pendingList
+ Assumes members in this wxVariant list as pending
+ replacement values.
+ */
+ bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const;
- // 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;
+ /** Updates composed values of parent non-category properties, recursively.
+ Returns topmost property updated.
- wxVariant m_value;
- wxPGAttributeStorage m_attributes;
- wxArrayPtrVoid m_children;
+ @remarks
+ - Must not call SetValue() (as can be called in it).
+ */
+ wxPGProperty* UpdateParentValues();
- // Extended cell information
- wxArrayPtrVoid m_cells;
+ /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
+ */
+ bool UsesAutoUnspecified() const
+ {
+ return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED)?true:false;
+ }
- // Help shown in statusbar or help box.
- wxString m_helpString;
+ wxBitmap* GetValueImage() const
+ {
+ return m_valueBitmap;
+ }
- // Index in parent's property array.
- unsigned int m_arrIndex;
+ wxVariant GetAttribute( const wxString& name ) const;
- // If not -1, then overrides m_value
- int m_commonValue;
+ /**
+ Returns named attribute, as string, if found.
- FlagType m_flags;
+ Otherwise defVal is returned.
+ */
+ wxString GetAttribute( const wxString& name, const wxString& defVal ) const;
- // 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;
+ /**
+ Returns named attribute, as long, if found.
- // Root has 0, categories etc. at that level 1, etc.
- unsigned char m_depth;
+ Otherwise defVal is returned.
+ */
+ long GetAttributeAsLong( const wxString& name, long defVal ) const;
- // 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;
+ /**
+ Returns named attribute, as double, if found.
- unsigned char m_bgColIndex; // Background brush index.
- unsigned char m_fgColIndex; // Foreground colour index.
+ Otherwise defVal is returned.
+ */
+ double GetAttributeAsDouble( const wxString& name, double defVal ) const;
-private:
- // Called in constructors.
- void Init();
- void Init( const wxString& label, const wxString& name );
-#endif // #ifndef SWIG
-};
+ unsigned int GetDepth() const { return (unsigned int)m_depth; }
-// -----------------------------------------------------------------------
+ /** 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;
-//
-// Property class declaration helper macros
-// (wxPGRootPropertyClass and wxPropertyCategory require this).
-//
+ /** Returns position in parent's array. */
+ unsigned int GetIndexInParent() const
+ {
+ return (unsigned int)m_arrIndex;
+ }
-#define WX_PG_DECLARE_DOGETEDITORCLASS \
- virtual const wxPGEditor* DoGetEditorClass() const;
+ /** 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 );
+
+ bool IsExpanded() const
+ { return (!(m_flags & wxPG_PROP_COLLAPSED) && GetChildCount()); }
+
+ /** Returns true if all parents expanded.
+ */
+ bool IsVisible() const;
+
+ bool IsEnabled() const { return !(m_flags & wxPG_PROP_DISABLED); }
+
+ /** If property's editor is created this forces its recreation.
+ Useful in SetAttribute etc. Returns true if actually did anything.
+ */
+ bool RecreateEditor();
+
+ /** If property's editor is active, then update it's value.
+ */
+ void RefreshEditor();
+
+ /** 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 );
+
+ void SetAttributes( const wxPGAttributeStorage& attributes );
+
+ /**
+ Sets property's background colour.
+
+ @param colour
+ Background colour to use.
+
+ @param recursively
+ If @true, children are affected recursively, and any categories
+ are not.
+ */
+ void SetBackgroundColour( const wxColour& colour,
+ bool recursively = false );
+
+ /**
+ Sets property's text colour.
+
+ @param colour
+ Text colour to use.
+
+ @param recursively
+ If @true, children are affected recursively, and any categories
+ are not.
+ */
+ void SetTextColour( const wxColour& colour,
+ bool recursively = false );
#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)
+ /** Sets editor for a property.
+
+ @param editor
+ For builtin editors, use wxPGEditor_X, where X is builtin editor's
+ name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
+ list).
+
+ For custom editors, use pointer you received from
+ wxPropertyGrid::RegisterEditorClass().
+ */
+ void SetEditor( const wxPGEditor* editor )
+ {
+ m_customEditor = editor;
+ }
#endif
-// 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; \
-}
+ /** Sets editor for a property.
+ */
+ inline void SetEditor( const wxString& editorName );
-// -----------------------------------------------------------------------
+ /**
+ Sets cell information for given column.
+ */
+ void SetCell( int column, const wxPGCell& cell );
-#ifndef SWIG
+ /** Sets common value selected for this property. -1 for none.
+ */
+ void SetCommonValue( int commonValue )
+ {
+ m_commonValue = commonValue;
+ }
-/** @class wxPGRootProperty
- @ingroup classes
- Root parent property.
-*/
-class WXDLLIMPEXP_PROPGRID wxPGRootProperty : public wxPGProperty
-{
-public:
- WX_PG_DECLARE_PROPERTY_CLASS(wxPGRootProperty)
-public:
+ /** Sets flags from a '|' delimited string. Note that flag names are not
+ prepended with 'wxPG_PROP_'.
+ */
+ void SetFlagsFromString( const wxString& str );
- /** Constructor. */
- wxPGRootProperty();
- virtual ~wxPGRootProperty();
+ /** Sets property's "is it modified?" flag. Affects children recursively.
+ */
+ void SetModifiedStatus( bool modified )
+ {
+ SetFlagRecursively(wxPG_PROP_MODIFIED, modified);
+ }
- virtual bool StringToValue( wxVariant&, const wxString&, int ) const
+ /** 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.
+ */
+ void SetValueInEvent( wxVariant value ) const;
+
+ /**
+ Call this to set value of the property.
+
+ 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.
+
+ If you need to change property value in event, based on user input, use
+ SetValueInEvent() instead.
+
+ @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 );
+
+ /** Set wxBitmap in front of the value. This bitmap may be ignored
+ by custom cell renderers.
+ */
+ void SetValueImage( wxBitmap& bmp );
+
+ /** Sets selected choice and changes property value.
+
+ Tries to retain value type, although currently if it is not string,
+ then it is forced to integer.
+ */
+ void SetChoiceSelection( int newValue );
+
+ void SetExpanded( bool expanded )
{
- return false;
+ if ( !expanded ) m_flags |= wxPG_PROP_COLLAPSED;
+ else m_flags &= ~wxPG_PROP_COLLAPSED;
}
-protected:
-};
+ void SetFlag( FlagType flag ) { m_flags |= flag; }
-// -----------------------------------------------------------------------
+ void SetFlagRecursively( FlagType flag, bool set );
-/** @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:
+ void SetHelpString( const wxString& helpString )
+ {
+ m_helpString = helpString;
+ }
- /** Default constructor is only used in special cases. */
- wxPropertyCategory();
+ void SetLabel( const wxString& label ) { m_label = label; }
- wxPropertyCategory( const wxString& label,
- const wxString& name = wxPG_LABEL );
- ~wxPropertyCategory();
+ inline void SetName( const wxString& newName );
+
+ /**
+ Changes what sort of parent this property is for its children.
+
+ @param flag
+ Use one of the following values: wxPG_PROP_MISC_PARENT (for generic
+ parents), wxPG_PROP_CATEGORY (for categories), or
+ wxPG_PROP_AGGREGATE (for derived property classes with private
+ children).
+
+ @remarks You 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;
+ }
+
+ void SetValueToUnspecified()
+ {
+ wxVariant val; // Create NULL variant
+ SetValue(val);
+ }
- int GetTextExtent( const wxWindow* wnd, const wxFont& font ) const;
+#if wxUSE_VALIDATORS
+ /** Sets wxValidator for a property*/
+ void SetValidator( const wxValidator& validator )
+ {
+ m_validator = wxDynamicCast(validator.Clone(),wxValidator);
+ }
-protected:
- virtual wxString GetValueAsString( int argFlags ) const;
+ /** Gets assignable version of property's validator. */
+ wxValidator* GetValidator() const
+ {
+ if ( m_validator )
+ return m_validator;
+ return DoGetValidator();
+ }
+#endif // #if wxUSE_VALIDATORS
- void SetTextColIndex( unsigned int colInd )
- { m_capFgColIndex = (wxByte) colInd; }
- unsigned int GetTextColIndex() const
- { return (unsigned int) m_capFgColIndex; }
+#ifndef SWIG
+ /** Returns client data (void*) of a property.
+ */
+ void* GetClientData() const
+ {
+ return m_clientData;
+ }
- void CalculateTextExtent( wxWindow* wnd, const wxFont& font );
+ /** Sets client data (void*) of a property.
+ @remarks
+ This untyped client data has to be deleted manually.
+ */
+ void SetClientData( void* clientData )
+ {
+ m_clientData = clientData;
+ }
- int m_textExtent; // pre-calculated length of text
- wxByte m_capFgColIndex; // caption text colour index
+ /** Returns client object of a property.
+ */
+ void SetClientObject(wxClientData* clientObject)
+ {
+ delete m_clientObject;
+ m_clientObject = clientObject;
+ }
-private:
- void Init();
-};
+ /** Sets managed client object of a property.
+ */
+ wxClientData *GetClientObject() const { return m_clientObject; }
+#endif
-#endif // !SWIG
+ /** Sets new set of choices for property.
-// -----------------------------------------------------------------------
+ @remarks
+ This operation clears the property value.
+ */
+ bool SetChoices( wxPGChoices& choices );
-#ifndef SWIG
+ /** Set max length of text in text editor.
+ */
+ inline bool SetMaxLength( int maxLen );
-/** @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)
+ /** Call with 'false' in OnSetValue to cancel value changes after all
+ (ie. cancel 'true' returned by StringToValue() or IntToValue()).
+ */
+ void SetWasModified( bool set = true )
{
- m_text = label;
+ if ( set ) m_flags |= wxPG_PROP_WAS_MODIFIED;
+ else m_flags &= ~wxPG_PROP_WAS_MODIFIED;
}
- 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)
+ const wxString& GetHelpString() const
{
+ return m_helpString;
}
- virtual ~wxPGChoiceEntry()
- {
- }
+ void ClearFlag( FlagType flag ) { m_flags &= ~(flag); }
- void SetValue( int value ) { m_value = value; }
+ // Use, for example, to detect if item is inside collapsed section.
+ bool IsSomeParent( wxPGProperty* candidate_parent ) const;
- int GetValue() const { return m_value; }
+ /**
+ Adapts list variant into proper value using consecutive
+ ChildChanged-calls.
+ */
+ void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
- bool HasValue() const { return (m_value != wxPG_INVALID_VALUE); }
+ /**
+ 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:
-protected:
- int m_value;
-};
+ @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 );
+ /** Returns height of children, recursively, and
+ by taking expanded/collapsed status into account.
-typedef void* wxPGChoicesId;
+ iMax is used when finding property y-positions.
+ */
+ int GetChildrenHeight( int lh, int iMax = -1 ) const;
-class WXDLLIMPEXP_PROPGRID wxPGChoicesData
-{
- friend class wxPGChoices;
-public:
- // Constructor sets m_refCount to 1.
- wxPGChoicesData();
+ /** Returns number of child properties */
+ unsigned int GetChildCount() const
+ {
+ return (unsigned int) m_children.size();
+ }
- void CopyDataFrom( wxPGChoicesData* data );
+ /** Returns sub-property at index i. */
+ wxPGProperty* Item( unsigned int i ) const
+ { return m_children[i]; }
- // Takes ownership of 'item'
- void Insert( int index, wxPGChoiceEntry* item )
- {
- wxArrayPtrVoid::iterator it;
- if ( index == -1 )
- {
- it = m_items.end();
- index = m_items.size();
- }
- else
- {
- it = m_items.begin() + index;
- }
+ /** Returns last sub-property.
+ */
+ wxPGProperty* Last() const { return m_children.back(); }
- // Need to fix value?
- if ( item->GetValue() == wxPG_INVALID_VALUE )
- item->SetValue(index);
+ /** Returns index of given child property. */
+ int Index( const wxPGProperty* p ) const;
- m_items.insert(it, item);
- }
+ // Puts correct indexes to children
+ void FixIndicesOfChildren( unsigned int starthere = 0 );
- // Delete all entries
- void Clear();
+#ifndef SWIG
+ // Returns wxPropertyGridPageState in which this property resides.
+ wxPropertyGridPageState* GetParentState() const { return m_parentState; }
+#endif
- size_t GetCount() const { return m_items.size(); }
+ wxPGProperty* GetItemAtY( unsigned int y,
+ unsigned int lh,
+ unsigned int* nextItemY ) const;
- wxPGChoiceEntry* Item( unsigned int i ) const
- {
- wxCHECK_MSG( i < GetCount(), NULL, "invalid index" );
+ /** Returns (direct) child property with given name (or NULL if not found).
+ */
+ wxPGProperty* GetPropertyByName( const wxString& name ) const;
- return (wxPGChoiceEntry*) m_items[i];
- }
+#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;
+ }
+ }
- void DecRef()
- {
- m_refCount--;
- wxASSERT( m_refCount >= 0 );
- if ( m_refCount == 0 )
- delete this;
+ 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
-private:
- wxArrayPtrVoid m_items;
+#ifndef SWIG
- // So that multiple properties can use the same set
- int m_refCount;
+ // Returns various display-related information for given column
+ void GetDisplayInfo( unsigned int column,
+ int choiceIndex,
+ int flags,
+ wxString* pString,
+ const wxPGCell** pCell );
- virtual ~wxPGChoicesData();
-};
+ static wxString* sm_wxPG_LABEL;
-#define wxPGChoicesEmptyData ((wxPGChoicesData*)NULL)
+ /** This member is public so scripting language bindings
+ wrapper code can access it freely.
+ */
+ void* m_clientData;
-#endif // SWIG
+protected:
+ /**
+ Sets property cell in fashion that reduces number of exclusive
+ copies of cell data. Used when setting, for instance, same
+ background colour for a number of properties.
-/** @class wxPGChoices
+ @param firstCol
+ First column to affect.
- Helper class for managing choices of wxPropertyGrid properties.
- Each entry can have label, value, bitmap, text colour, and background
- colour.
+ @param lastCol
+ Last column to affect.
- @library{wxpropgrid}
- @category{propgrid}
-*/
-class WXDLLIMPEXP_PROPGRID wxPGChoices
-{
-public:
- typedef long ValArrItem;
+ @param preparedCell
+ Pre-prepared cell that is used for those which cell data
+ before this matched unmodCellData.
- /** Default constructor. */
- wxPGChoices()
- {
- Init();
- }
+ @param srcData
+ If unmodCellData did not match, valid cell data from this
+ is merged into cell (usually generating new exclusive copy
+ of cell's data).
- /** Copy constructor. */
- wxPGChoices( const wxPGChoices& a )
- {
- if ( a.m_data != wxPGChoicesEmptyData )
- {
- m_data = a.m_data;
- m_data->m_refCount++;
- }
- }
+ @param unmodCellData
+ If cell's cell data matches this, its cell is now set to
+ preparedCell.
- /** Constructor. */
- wxPGChoices( const wxChar** labels, const long* values = NULL )
- {
- Init();
- Set(labels,values);
- }
+ @param ignoreWithFlags
+ Properties with any one of these flags are skipped.
- /** Constructor. */
- wxPGChoices( const wxArrayString& labels,
- const wxArrayInt& values = wxArrayInt() )
- {
- Init();
- Set(labels,values);
- }
+ @param recursively
+ If @true, apply this operation recursively in child properties.
+ */
+ void AdaptiveSetCell( unsigned int firstCol,
+ unsigned int lastCol,
+ const wxPGCell& preparedCell,
+ const wxPGCell& srcData,
+ wxPGCellData* unmodCellData,
+ FlagType ignoreWithFlags,
+ bool recursively );
- /** Simple interface constructor. */
- wxPGChoices( wxPGChoicesData* data )
- {
- wxASSERT(data);
- m_data = data;
- data->m_refCount++;
- }
+ /**
+ Makes sure m_cells has size of column+1 (or more).
+ */
+ void EnsureCells( unsigned int column );
- /** Destructor. */
- ~wxPGChoices()
- {
- Free();
- }
+ /** 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).
+ */
+ 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 );
- /**
- Adds to current.
+ void DoGenerateComposedValue( wxString& text,
+ int argFlags = wxPG_VALUE_IS_CURRENT,
+ const wxVariantList* valueOverrides = NULL,
+ wxPGHashMapS2S* childResults = NULL ) const;
- If did not have own copies, creates them now. If was empty, identical
- to set except that creates copies.
- */
- void Add( const wxChar** labels, const ValArrItem* values = NULL );
+ void DoSetName(const wxString& str) { m_name = str; }
- /** Version that works with wxArrayString. */
- void Add( const wxArrayString& arr, const ValArrItem* values = NULL );
+ /** Deletes all sub-properties. */
+ void Empty();
- /** Version that works with wxArrayString and wxArrayInt. */
- void Add( const wxArrayString& arr, const wxArrayInt& arrint );
+ void InitAfterAdded( wxPropertyGridPageState* pageState,
+ wxPropertyGrid* propgrid );
- /** Adds single item. */
- wxPGChoiceEntry& Add( const wxString& label,
- int value = wxPG_INVALID_VALUE );
+ // Removes child property with given pointer. Does not delete it.
+ void RemoveChild( wxPGProperty* p );
- /** Adds a single item, with bitmap. */
- wxPGChoiceEntry& Add( const wxString& label,
- const wxBitmap& bitmap,
- int value = wxPG_INVALID_VALUE );
+ void SetParentState( wxPropertyGridPageState* pstate )
+ { m_parentState = pstate; }
- /** Adds a single item with full entry information. */
- wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry )
- {
- return Insert(entry, -1);
- }
+ // 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 );
- /** Adds single item. */
- wxPGChoiceEntry& AddAsSorted( const wxString& label,
- int value = wxPG_INVALID_VALUE );
+ int GetY2( int lh ) const;
- void Assign( const wxPGChoices& a )
- {
- AssignData(a.m_data);
- }
+ wxString m_label;
+ wxString m_name;
+ wxPGProperty* m_parent;
+ wxPropertyGridPageState* m_parentState;
- void AssignData( wxPGChoicesData* data );
+ wxClientData* m_clientObject;
- /** Delete all choices. */
- void Clear()
- {
- if ( m_data != wxPGChoicesEmptyData )
- m_data->Clear();
- }
+ // 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;
- void EnsureData()
- {
- if ( m_data == wxPGChoicesEmptyData )
- m_data = new wxPGChoicesData();
- }
+ wxVariant m_value;
+ wxPGAttributeStorage m_attributes;
+ wxArrayPGProperty m_children;
- /** Gets a unsigned number identifying this list. */
- wxPGChoicesId GetId() const { return (wxPGChoicesId) m_data; };
+ // Extended cell information
+ wxVector<wxPGCell> m_cells;
- const wxString& GetLabel( size_t ind ) const
- {
- return Item(ind).GetText();
- }
+ // Choices shown in drop-down list of editor control.
+ wxPGChoices m_choices;
- size_t GetCount () const
- {
- wxASSERT_MSG( m_data, "When checking if wxPGChoices is valid, "
- "use IsOk() instead of GetCount()" );
- return m_data->GetCount();
- }
+ // Help shown in statusbar or help box.
+ wxString m_helpString;
- int GetValue( size_t ind ) const { return Item(ind).GetValue(); }
+ // Index in parent's property array.
+ unsigned int m_arrIndex;
- /** Returns array of values matching the given strings. Unmatching strings
- result in wxPG_INVALID_VALUE entry in array.
- */
- wxArrayInt GetValuesForStrings( const wxArrayString& strings ) const;
+ // If not -1, then overrides m_value
+ int m_commonValue;
- /** 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;
+ FlagType m_flags;
- /** Returns true if choices in general are likely to have values
- (depens on that all entries have values or none has)
- */
- bool HasValues() const;
+ // 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;
- bool HasValue( unsigned int i ) const
- { return (i < m_data->GetCount()) && m_data->Item(i)->HasValue(); }
+ // Root has 0, categories etc. at that level 1, etc.
+ unsigned char m_depth;
- int Index( const wxString& str ) const;
- int Index( int val ) const;
+ // 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 single item. */
- wxPGChoiceEntry& Insert( const wxString& label,
- int index,
- int value = wxPG_INVALID_VALUE );
+private:
+ // Called in constructors.
+ void Init();
+ void Init( const wxString& label, const wxString& name );
+#endif // #ifndef SWIG
+};
- /** Inserts a single item with full entry information. */
- wxPGChoiceEntry& Insert( const wxPGChoiceEntry& entry, int index );
+// -----------------------------------------------------------------------
- /** Returns false if this is a constant empty set of choices,
- which should not be modified.
- */
- bool IsOk() const
- {
- return ( m_data != wxPGChoicesEmptyData );
- }
+//
+// Property class declaration helper macros
+// (wxPGRootPropertyClass and wxPropertyCategory require this).
+//
- const wxPGChoiceEntry& Item( unsigned int i ) const
- {
- wxASSERT( IsOk() );
- return *m_data->Item(i);
- }
+#define WX_PG_DECLARE_DOGETEDITORCLASS \
+ virtual const wxPGEditor* DoGetEditorClass() const;
- wxPGChoiceEntry& Item( unsigned int i )
- {
- wxASSERT( IsOk() );
- return *m_data->Item(i);
- }
+#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
- /** Removes count items starting at position nIndex. */
- void RemoveAt(size_t nIndex, size_t count = 1);
+// 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; \
+}
+
+// -----------------------------------------------------------------------
#ifndef SWIG
- /** Does not create copies for itself. */
- void Set( const wxChar** labels, const long* values = NULL )
- {
- Free();
- Add(labels,values);
- }
- /** Version that works with wxArrayString.
- TODO: Deprecate this.
- */
- void Set( wxArrayString& arr, const long* values = (const long*) NULL )
- {
- Free();
- Add(arr,values);
- }
-#endif // SWIG
+/** @class wxPGRootProperty
+ @ingroup classes
+ Root parent property.
+*/
+class WXDLLIMPEXP_PROPGRID wxPGRootProperty : public wxPGProperty
+{
+public:
+ WX_PG_DECLARE_PROPERTY_CLASS(wxPGRootProperty)
+public:
- /** 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);
- }
+ /** Constructor. */
+ wxPGRootProperty( const wxString& name = wxS("<Root>") );
+ virtual ~wxPGRootProperty();
- // Creates exclusive copy of current choices
- void SetExclusive()
+ virtual bool StringToValue( wxVariant&, const wxString&, int ) const
{
- if ( m_data->m_refCount != 1 )
- {
- wxPGChoicesData* data = new wxPGChoicesData();
- data->CopyDataFrom(m_data);
- Free();
- m_data = data;
- }
+ return false;
}
- // Returns data, increases refcount.
- wxPGChoicesData* GetData()
- {
- wxASSERT( m_data->m_refCount != 0xFFFFFFF );
- m_data->m_refCount++;
- return m_data;
- }
+protected:
+};
- // Returns plain data ptr - no refcounting stuff is done.
- wxPGChoicesData* GetDataPtr() const { return m_data; }
+// -----------------------------------------------------------------------
- // Changes ownership of data to you.
- wxPGChoicesData* ExtractData()
- {
- wxPGChoicesData* data = m_data;
- m_data = wxPGChoicesEmptyData;
- return data;
- }
+/** @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:
- wxArrayString GetLabels() const;
+ /** Default constructor is only used in special cases. */
+ wxPropertyCategory();
-#ifndef SWIG
- void operator= (const wxPGChoices& a)
- {
- AssignData(a.m_data);
- }
+ wxPropertyCategory( const wxString& label,
+ const wxString& name = wxPG_LABEL );
+ ~wxPropertyCategory();
- wxPGChoiceEntry& operator[](unsigned int i)
- {
- return Item(i);
- }
+ int GetTextExtent( const wxWindow* wnd, const wxFont& font ) const;
- const wxPGChoiceEntry& operator[](unsigned int i) const
- {
- return Item(i);
- }
+ virtual wxString ValueToString( wxVariant& value, int argFlags ) const;
protected:
- wxPGChoicesData* m_data;
+ 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
// -----------------------------------------------------------------------
projects / wxWidgets.git / blobdiff