// Name: property.h
// Purpose: interface of wxPGProperty
// Author: wxWidgets team
-// RCS-ID: $Id:
+// RCS-ID: $Id$
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
#define wxNullProperty ((wxPGProperty*)NULL)
-// Structure for relaying choice/list info.
-struct wxPGChoiceInfo
-{
- wxPGChoices* m_choices;
-};
-
+/**
+ @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers
-/** @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers
+ wxPGProperty::SetAttribute() and wxPropertyGridInterface::SetPropertyAttribute()
+ accept one of these as attribute name argument.
- wxPGProperty::SetAttribute() and
- wxPropertyGridInterface::SetPropertyAttribute()
- accept one of these as attribute name argument .
-
- You can use strings instead of constants. However, some of these
- constants are redefined to use cached strings which may reduce
- your binary size by some amount.
+ You can use strings instead of constants.
+ However, some of these constants are redefined to use cached strings which
+ may reduce your binary size by some amount.
@{
*/
*/
#define wxPG_ATTR_INLINE_HELP wxS("InlineHelp")
-/** wxBoolProperty specific, int, default 0. When 1 sets bool property to
- use checkbox instead of choice.
+/** Universal, wxArrayString. Set to enable auto-completion in any
+ wxTextCtrl-based property editor.
+*/
+#define wxPG_ATTR_AUTOCOMPLETE wxS("AutoComplete")
+
+/** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
+ Default value is False.
+
+ When set to True, bool property will use check box instead of a
+ combo box as its editor control. If you set this attribute
+ for a wxFlagsProperty, it is automatically applied to child
+ bool properties.
*/
#define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox")
-/** wxBoolProperty specific, int, default 0. When 1 sets bool property value
- to cycle on double click (instead of showing the popup listbox).
+/** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
+ Default value is False.
+
+ Set to True for the bool property to cycle value on double click
+ (instead of showing the popup listbox). If you set this attribute
+ for a wxFlagsProperty, it is automatically applied to child
+ bool properties.
*/
#define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING wxS("UseDClickCycling")
#define wxPG_DATE_FORMAT wxS("DateFormat")
/** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
- is wxDP_DEFAULT | wxDP_SHOWCENTURY.
+ is wxDP_DEFAULT | wxDP_SHOWCENTURY. Using wxDP_ALLOWNONE will enable
+ better unspecified value support in the editor.
*/
#define wxPG_DATE_PICKER_STYLE wxS("PickerStyle")
*/
#define wxPG_ATTR_SPINCTRL_STEP wxS("Step")
-/** SpinCtrl editor, bool. If true, value wraps at Min/Max.
+/** SpinCtrl editor, bool. If @true, value wraps at Min/Max.
*/
#define wxPG_ATTR_SPINCTRL_WRAP wxS("Wrap")
+/** SpinCtrl editor, bool. If @true, value can also by changed by moving
+ mouse when left mouse button is being pressed.
+*/
+#define wxPG_ATTR_SPINCTRL_MOTIONSPIN wxS("MotionSpin")
+
/** wxMultiChoiceProperty, int. If 0, no user strings allowed. If 1, user strings
appear before list strings. If 2, user strings appear after list string.
*/
*/
#define wxPG_COLOUR_ALLOW_CUSTOM wxS("AllowCustom")
-/** First attribute id that is guaranteed not to be used built-in
- properties.
-*/
-//#define wxPG_USER_ATTRIBUTE 192
-
/** @}
*/
-// -----------------------------------------------------------------------
-/** @class wxPGProperty
+
+/**
+ @class wxPGProperty
wxPGProperty is base class for all wxPropertyGrid properties. In
sections below we cover few related topics.
Simple string property. wxPG_STRING_PASSWORD attribute may be used
to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl.
+ wxPG_ATTR_AUTOCOMPLETE attribute may be used to enable auto-completion
+ (use a wxArrayString value), and is also supported by any property that
+ happens to use a wxTextCtrl-based editor.
- @remarks
- * wxStringProperty has a special trait: if it has value of "<composed>",
- and also has child properties, then its displayed value becomes
- composition of child property values, similar as with wxFontProperty,
- for instance.
+ @remarks wxStringProperty has a special trait: if it has value of
+ "<composed>", and also has child properties, then its displayed
+ value becomes composition of child property values, similar as
+ with wxFontProperty, for instance.
@subsection wxIntProperty
Like wxStringProperty, but converts text to a signed long integer.
wxIntProperty seamlessly supports 64-bit integers (ie. wxLongLong).
+ To safely convert variant to integer, use code like this:
+
+ @code
+ wxLongLong ll;
+ ll << property->GetValue();
+
+ // or
+ wxLongLong ll = propertyGrid->GetPropertyValueAsLong(property);
+ @endcode
@subsection wxUIntProperty
To set the globally used base, manipulate wxPG_UINT_BASE int
attribute. Regardless of current prefix, understands (hex) values starting
with both "0x" and "$".
- wxUIntProperty seamlessly supports 64-bit unsigned integers (ie. wxULongLong).
+ Like wxIntProperty, wxUIntProperty seamlessly supports 64-bit unsigned
+ integers (ie. wxULongLong). Same wxVariant safety rules apply.
@subsection wxFloatProperty
dialog. Note that in long string values, tabs are represented by "\t" and
line break by "\n".
+ To display custom dialog on button press, you can subclass
+ wxLongStringProperty and implement OnButtonClick, like this:
+
+ @code
+ virtual bool OnButtonClick( wxPropertyGrid* propGrid, wxString& value )
+ {
+ wxSize dialogSize(...size of your dialog...);
+
+ wxPoint dlgPos = propGrid->GetGoodEditorDialogPosition(this,
+ dialogSize)
+
+ // Create dialog dlg at dlgPos. Use value as initial string
+ // value.
+ ...
+
+ if ( dlg.ShowModal() == wxID_OK )
+ {
+ value = dlg.GetStringValue);
+ return true;
+ }
+ return false;
+ }
+ @endcode
+
+ Also, if you wish not to have line breaks and tabs translated to
+ escape sequences, then do following in constructor of your subclass:
+
+ @code
+ m_flags |= wxPG_PROP_NO_ESCAPE;
+ @endcode
+
@subsection wxDirProperty
Like wxLongStringProperty, but the button triggers dir selector instead.
Like wxLongStringProperty, but the button triggers file selector instead.
Default wildcard is "All files..." but this can be changed by setting
wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details).
- Attribute wxPG_FILE_SHOW_FULL_PATH can be set to false inorder to show
+ Attribute wxPG_FILE_SHOW_FULL_PATH can be set to @false inorder to show
only the filename, not the entire path.
@subsection wxEnumProperty
@subsection wxFlagsProperty
- Represents a bit set that fits in a long integer. wxBoolProperty sub-properties
- are created for editing individual bits. Textctrl is created to manually edit
- the flags as a text; a continous sequence of spaces, commas and semicolons
- is considered as a flag id separator.
- <b>Note: </b> When changing "choices" (ie. flag labels) of wxFlagsProperty, you
- will need to use SetPropertyChoices - otherwise they will not get updated properly.
+ Represents a bit set that fits in a long integer. wxBoolProperty sub-
+ properties are created for editing individual bits. Textctrl is created to
+ manually edit the flags as a text; a continous sequence of spaces, commas
+ and semicolons are considered as a flag id separator.
+
+ <b>Note:</b> When changing "choices" (ie. flag labels) of wxFlagsProperty,
+ you will need to use wxPGProperty::SetChoices() - otherwise they will not
+ get updated properly.
+
+ wxFlagsProperty supports the same attributes as wxBoolProperty.
@subsection wxArrayStringProperty
string wxDateTime::Format uses (altough default is recommended as it is
locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window
style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY).
+ Using wxDP_ALLOWNONE will enable better unspecified value support.
@subsection wxEditEnumProperty
<b>Useful alternate editor:</b> Choice.
Represents wxColour. wxButton is used to trigger a colour picker dialog.
+ There are various sub-classing opportunities with this class. See
+ below in wxSystemColourProperty section for details.
@subsection wxFontProperty
Represents wxColour and a system colour index. wxChoice is used to edit
the value. Drop-down list has color images. Note that value type
- is wxColourPropertyValue instead of wxColour.
+ is wxColourPropertyValue instead of wxColour (which wxColourProperty
+ uses).
+
@code
class wxColourPropertyValue : public wxObject
{
};
@endcode
+ in wxSystemColourProperty, and its derived class wxColourProperty, there
+ are various sub-classing features. To set basic list list of colour
+ names, call wxPGProperty::SetChoices().
+
+ @code
+ // Override in derived class to customize how colours are translated
+ // to strings.
+ virtual wxString ColourToString( const wxColour& col, int index ) const;
+
+ // Returns index of entry that triggers colour picker dialog
+ // (default is last).
+ virtual int GetCustomColourIndex() const;
+
+ // Helper function to show the colour dialog
+ bool QueryColourFromUser( wxVariant& variant ) const;
+
+ // Returns colour for given choice.
+ // Default function returns wxSystemSettings::GetColour(index).
+ virtual wxColour GetColour( int index ) const;
+ @endcode
+
@subsection wxCursorProperty
Represents a wxCursor. wxChoice is used to edit the value.
return wxPGEditor_TextCtrl;
}
- virtual wxString GetValueAsString( int argFlags ) const
+ virtual wxString ValueToString( wxVariant& value,
+ int argFlags ) const
{
- // TODO: Return property value in string format
+ // TODO: Convert given property value to a string
}
virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags )
public:
typedef wxUint32 FlagType;
- /** Basic constructor.
+ /**
+ Default constructor.
*/
wxPGProperty();
- /** Constructor.
+ /**
+ Constructor.
Non-abstract property classes should have constructor of this style:
@code
- // If T is a class, then it should be a constant reference
- // (e.g. const T& ) instead.
- MyProperty( const wxString& label, const wxString& name, T value )
+ MyProperty( const wxString& label, const wxString& name, const T& value )
: wxPGProperty()
{
// Generally recommended way to set the initial value
variant << value;
SetValue(variant);
- // If has private child properties then create them here. For example:
- // AddChild( new wxStringProperty( "Subprop 1", wxPG_LABEL, value.GetSubProp1() ) );
+ // If has private child properties then create them here.
+ // For example:
+ // AddPrivateChild( new wxStringProperty("Subprop 1",
+ // wxPG_LABEL,
+ // value.GetSubProp1()));
}
@endcode
*/
wxPGProperty( const wxString& label, const wxString& name );
- /** Virtual destructor. It is customary for derived properties to implement this. */
+ /**
+ Virtual destructor. It is customary for derived properties to implement this.
+ */
virtual ~wxPGProperty();
- /** This virtual function is called after m_value has been set.
+ /**
+ This virtual function is called after m_value has been set.
@remarks
- If m_value was set to Null variant (ie. unspecified value), OnSetValue()
*/
virtual void OnSetValue();
- /** Override this to return something else than m_value as the value.
+ /**
+ Override this to return something else than m_value as the value.
*/
- virtual wxVariant DoGetValue() const { return m_value; }
+ virtual wxVariant DoGetValue() const;
- /** Implement this function in derived class to check the value.
- Return true if it is ok. Returning false prevents property change events
+ /**
+ Implement this function in derived class to check the value.
+ Return @true if it is ok. Returning @false prevents property change events
from occurring.
@remarks
- - Default implementation always returns true.
+ - Default implementation always returns @true.
*/
virtual bool ValidateValue( wxVariant& value, wxPGValidationInfo& validationInfo ) const;
- /** Converts 'text' into proper value 'variant'. Returns true if new (different than
- m_value) value could be interpreted from the text.
+ /**
+ Converts text into wxVariant value appropriate for this property.
+
+ @param variant
+ On function entry this is the old value (should not be wxNullVariant
+ in normal cases). Translated value must be assigned back to it.
+
+ @param text
+ Text to be translated into variant.
+
@param argFlags
- If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable
- one (they may be different).
- If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of composite
- property string value (as generated by GetValueAsString() called with this same
- flag).
+ 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).
- @remarks
- Default implementation converts semicolon delimited tokens into child values. Only
- works for properties with children.
+ @return Returns @true if resulting wxVariant value was different.
+
+ @remarks Default implementation converts semicolon delimited tokens into
+ child values. Only works for properties with children.
+
+ You might want to take into account that m_value is Null variant
+ if property value is unspecified (which is usually only case if
+ you explicitly enabled that sort behavior).
*/
virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags = 0 ) const;
- /** Converts 'number' (including choice selection) into proper value 'variant'.
- Returns true if new (different than m_value) value could be interpreted from the integer.
+ /**
+ Converts integer (possibly a choice selection) into wxVariant value
+ appropriate for this property.
+
+ @param variant
+ On function entry this is the old value (should not be wxNullVariant
+ in normal cases). Translated value must be assigned back to it.
+ @param number
+ Integer to be translated into variant.
@param argFlags
- If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable one.
+ If wxPG_FULL_VALUE is set, returns complete, storable value instead
+ of displayable one.
+
+ @return Returns @true if resulting wxVariant value was different.
@remarks
- If property is not supposed to use choice or spinctrl or other editor
with int-based value, it is not necessary to implement this method.
- 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.
+ - 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 Mull variant if
+ property value is unspecified (which is usually only case if you
+ explicitly enabled that sort behavior).
*/
- virtual bool IntToValue( wxVariant& value, int number, int argFlags = 0 ) const;
+ virtual bool IntToValue( wxVariant& variant, int number, int argFlags = 0 ) const;
-public:
-
- /** Returns text representation of property's value.
+ /**
+ Converts property value into a text representation.
+ @param value
+ Value to be converted.
@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.
+ If 0 (default value), then displayed string is returned.
+ If wxPG_FULL_VALUE is set, returns complete, storable string value
+ instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
+ string value that must be editable in textctrl.
+ If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
+ display as a part of string property's composite text representation.
- @remarks
- Default implementation returns string composed from text representations of
- child properties.
+ @remarks Default implementation calls GenerateComposedValue().
*/
- virtual wxString GetValueAsString( int argFlags = 0 ) const;
+ virtual wxString ValueToString( wxVariant& value, int argFlags = 0 ) const;
- /** Converts string to a value, and if successful, calls SetValue() on it.
+ /**
+ 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.
- @retval
- true if value was changed.
+ String to get the value from.
+ @param flags
+ @todo docme
+
+ @return @true if value was changed.
*/
bool SetValueFromString( const wxString& text, int flags = 0 );
- /** Converts integer to a value, and if succesful, calls SetValue() on it.
+ /**
+ 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.
+ 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.
- @retval
- True if value was changed.
+ 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 );
- /** Returns size of the custom painted image in front of property. This method
+ /**
+ Returns size of the custom painted image in front of property. This method
must be overridden to return non-default value if OnCustomPaint is to be
called.
+
@param item
- Normally -1, but can be an index to the property's list of items.
+ 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.
*/
virtual wxSize OnMeasureImage( int item = -1 ) const;
- /** Events received by editor widgets are processed here. Note that editor class
+ /**
+ Events received by editor widgets are processed here. 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.
+ If the event causes value to be changed, SetValueInEvent() should be called
+ to set the new value.
+
+ The parameter @a event is the associated wxEvent.
- @param event
- Associated wxEvent.
@retval
- Should return true if any changes in value should be reported.
+ Should return @true if any changes in value should be reported.
+
@remarks
- If property uses choice control, and displays a dialog on some choice items,
then it is preferred to display that dialog in IntToValue instead of OnEvent.
*/
virtual bool OnEvent( wxPropertyGrid* propgrid, wxWindow* wnd_primary, wxEvent& event );
- /** Called after value of a child property has been altered. Note that this function is
+ /**
+ 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.
@endcode
@param thisValue
- Value of this property, that should be altered.
+ Value of this property, that should be altered.
@param childIndex
- Index of child changed (you can use Item(childIndex) to get).
+ Index of child changed (you can use Item(childIndex) to get).
@param childValue
- Value of the child property.
+ Value of the child property.
*/
virtual void ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const;
- /** Returns pointer to an instance of used editor.
+ /**
+ 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).
+ /**
+ 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.
*/
virtual wxValidator* DoGetValidator () const;
- /** Returns current value's index to the choice control. 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.
- @remarks
- - If returns NULL in choiceinfo.m_choices, then this class must be
- derived from wxBaseEnumProperty.
- - Must be able to cope situation where property's set of choices is
- uninitialized.
- */
- virtual int GetChoiceInfo( wxPGChoiceInfo* choiceinfo );
-
- /** Override to paint an image in front of the property value text or drop-down
+ /**
+ 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
int m_drawnWidth;
// In a measure item call, set this to the height of item at m_choiceItem index
- int m_drawnHeight;
+ int m_drawnHeight;
};
@endcode
- 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 GetValueAsString()
+ @see ValueToString()
*/
virtual void OnCustomPaint( wxDC& dc, const wxRect& rect, wxPGPaintData& paintdata );
- /** Returns used wxPGCellRenderer instance for given property column (label=0, value=1).
+ /**
+ Returns used wxPGCellRenderer instance for given property column (label=0, value=1).
Default implementation returns editor's renderer for all columns.
*/
virtual wxPGCellRenderer* GetCellRenderer( int column ) const;
- /** Refresh values of child properties. Automatically called after value is set.
+ /**
+ 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.
+ */
+ virtual int GetChoiceSelection() const;
+
+ /**
+ Refresh values of child properties. Automatically called after value is set.
*/
virtual void RefreshChildren();
- /** Special handling for attributes of this property.
+ /**
+ Special handling for attributes of this property.
- If returns false, then the attribute will be automatically stored in
+ If returns @false, then the attribute will be automatically stored in
m_attributes.
- Default implementation simply returns false.
+ Default implementation simply returns @false.
*/
virtual bool DoSetAttribute( const wxString& name, wxVariant& value );
- /** Returns value of an attribute.
+ /**
+ Returns value of an attribute.
Override if custom handling of attributes is needed.
- Default implementation simply return NULL variant.
+ Default implementation simply return @NULL variant.
*/
virtual wxVariant DoGetAttribute( const wxString& name ) const;
- /** Returns instance of a new wxPGEditorDialogAdapter instance, which is
+ /**
+ 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
+ Default implementation returns @NULL (ie. no action is generated when
button is pressed).
*/
virtual wxPGEditorDialogAdapter* GetEditorDialog() const;
- /** Adds entry to property's wxPGChoices and editor control (if it is active).
- Returns index of item added.
- */
- int AppendChoice( const wxString& label, int value = wxPG_INVALID_VALUE )
- {
- return InsertChoice(label,-1,value);
- }
+ /**
+ Called whenever validation has failed with given pending value.
- /** Returns wxPGCell of given column, NULL if none. If valid
- object is returned, caller will gain its ownership.
+ @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.
*/
- wxPGCell* AcquireCell( unsigned int column )
- {
- if ( column >= m_cells.size() )
- return NULL;
+ virtual void OnValidationFailure( wxVariant& pendingValue );
- wxPGCell* cell = (wxPGCell*) m_cells[column];
- m_cells[column] = NULL;
- return cell;
- }
+ /**
+ Append a new choice to property's list of choices.
- /** 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).
+ @param label
+ Label for added choice.
+
+ @param value
+ Value for new choice. Do not specify if you wish this
+ to equal choice index.
+
+ @return
+ Index to added choice.
*/
- bool AreChildrenComponents() const
- {
- if ( m_flags & (wxPG_PROP_COMPOSED_VALUE|wxPG_PROP_AGGREGATE) )
- return true;
+ int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE );
- return false;
- }
+ /**
+ Adds a private child property.
- /** Removes entry from property's wxPGChoices and editor control (if it is active).
+ @deprecated Use AddPrivateChild() instead.
- If selected item is deleted, then the value is set to unspecified.
+ @see AddPrivateChild()
*/
- void DeleteChoice( int index );
+ wxDEPRECATED( 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.
+ /**
+ Adds a private child property. If you use this instead of
+ wxPropertyGridInterface::Insert() or
+ wxPropertyGridInterface::AppendIn(), then property's parental
+ type will automatically be set up to wxPG_PROP_AGGREGATE. In other
+ words, all properties of this property will become private.
+ */
+ void AddPrivateChild( wxPGProperty* prop );
- Common values are disabled by the default for all properties.
+ /**
+ Adapts list variant into proper value using consecutive
+ ChildChanged() calls.
*/
- void EnableCommonValue( bool enable = true )
- {
- if ( enable ) SetFlag( wxPG_PROP_USES_COMMON_VALUE );
- else ClearFlag( wxPG_PROP_USES_COMMON_VALUE );
- }
+ void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
- /** Composes text from values of child properties. */
- void GenerateComposedValue( wxString& text, int argFlags = 0 ) const;
+ /**
+ Use this member function to add independent (ie. regular) children to
+ a property.
- /** Returns property's label. */
- const wxString& GetLabel() const { return m_label; }
+ @return Appended childProperty.
- /** Returns property's name with all (non-category, non-root) parents. */
- wxString GetName() const;
+ @remarks wxPropertyGrid is not automatically refreshed by this
+ function.
- /** Returns property's base name (ie. parent's name is not added in any case) */
- const wxString& GetBaseName() const { return m_name; }
+ @see InsertChild(), AddPrivateChild()
+ */
+ wxPGProperty* AppendChild( wxPGProperty* childProperty );
- wxPGChoices& GetChoices();
+ /**
+ Determines, recursively, if all children are not unspecified.
- const wxPGChoices& GetChoices() const;
+ @param pendingList
+ Assumes members in this wxVariant list as pending
+ replacement values.
+ */
+ bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const;
- const wxPGChoiceEntry* GetCurrentChoice() 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;
- /** Returns coordinate to the top y of the property. Note that the
- position of scrollbars is not taken into account.
+ /**
+ Deletes children of the property.
*/
- int GetY() const;
+ void DeleteChildren();
- wxVariant GetValue() const
- {
- return DoGetValue();
- }
+ /**
+ Removes entry from property's wxPGChoices and editor control (if it is active).
- /** 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.
+ If selected item is deleted, then the value is set to unspecified.
*/
- wxVariant& GetValueRef()
- {
- return m_value;
- }
+ void DeleteChoice( int index );
- const wxVariant& GetValueRef() const
- {
- return m_value;
- }
+ /** Deletes all child properties. */
+ void Empty();
- /** Same as GetValueAsString, except takes common value into account.
+ /**
+ Composes text from values of child properties.
*/
- wxString GetValueString( int argFlags = 0 ) const;
-
- void UpdateControl( wxWindow* primary );
+ wxString GenerateComposedValue() const;
- /** Returns wxPGCell of given column, NULL if none. wxPGProperty
- will retain ownership of the cell object.
+ /**
+ Returns property attribute value, null variant if not found.
*/
- wxPGCell* GetCell( unsigned int column ) const
- {
- if ( column >= m_cells.size() )
- return NULL;
+ wxVariant GetAttribute( const wxString& name ) const;
- return (wxPGCell*) m_cells[column];
- }
+ /** Returns named attribute, as string, if found. Otherwise defVal is returned.
+ */
+ wxString GetAttribute( const wxString& name, const wxString& defVal ) const;
- unsigned int GetChoiceCount() const;
+ /** Returns named attribute, as long, if found. Otherwise defVal is returned.
+ */
+ long GetAttributeAsLong( const wxString& name, long defVal ) const;
- wxString GetChoiceString( unsigned int index );
+ /** Returns named attribute, as double, if found. Otherwise defVal is returned.
+ */
+ double GetAttributeAsDouble( const wxString& name, double defVal ) const;
- /** Return number of displayed common values for this property.
+ /**
+ Returns attributes as list wxVariant.
*/
- int GetDisplayedCommonValueCount() const;
+ wxVariant GetAttributesAsList() const;
- wxString GetDisplayedString() const
- {
- return GetValueString(0);
- }
+ /**
+ Returns editor used for given column. @NULL for no editor.
+ */
+ const wxPGEditor* GetColumnEditor( int column ) const;
- /** Returns property grid where property lies. */
- wxPropertyGrid* GetGrid() const;
+ /** Returns property's base name (ie. parent's name is not added in any case) */
+ const wxString& GetBaseName() const;
- /** Returns owner wxPropertyGrid, but only if one is currently on a page
- displaying this property. */
- wxPropertyGrid* GetGridIfDisplayed() const;
+ /**
+ Returns wxPGCell of given column.
+ */
+ const wxPGCell& GetCell( unsigned int column ) 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.
+ /**
+ Returns number of child properties.
*/
- wxPGProperty* GetMainParent() const;
+ unsigned int GetChildCount() const;
- /** Return parent of property */
- wxPGProperty* GetParent() const { return m_parent; }
+ /**
+ Returns height of children, recursively, and
+ by taking expanded/collapsed status into account.
- /** Returns true if property has editable wxTextCtrl when selected.
+ @param lh
+ Line height. Pass result of GetGrid()->GetRowHeight() here.
- @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).
+ @param iMax
+ Only used (internally) when finding property y-positions.
*/
- bool IsTextEditable() const;
+ int GetChildrenHeight( int lh, int iMax = -1 ) const;
- bool IsValueUnspecified() const
- {
- return m_value.IsNull();
- }
+ /**
+ Returns read-only reference to property's list of choices.
+ */
+ const wxPGChoices& GetChoices() const;
- FlagType HasFlag( FlagType flag ) const
- {
- return ( m_flags & flag );
- }
+ /**
+ Returns client data (void*) of a property.
+ */
+ void* GetClientData() const;
- /** Returns comma-delimited string of property attributes.
+ /** Sets managed client object of a property.
*/
- const wxPGAttributeStorage& GetAttributes() const
- {
- return m_attributes;
- }
+ wxClientData *GetClientObject() const;
- /** Returns m_attributes as list wxVariant.
+ /**
+ Returns property's default value. If property's value type is not
+ a built-in one, and "DefaultValue" attribute is not defined, then
+ this function usually returns Null variant.
*/
- wxVariant GetAttributesAsList() const;
+ wxVariant GetDefaultValue() const;
- FlagType GetFlags() const
- {
- return m_flags;
- }
+ /** Returns property's displayed text.
+ */
+ wxString GetDisplayedString() const;
+ /**
+ Returns wxPGEditor that will be used and created when
+ property becomes selected. Returns more accurate value
+ than DoGetEditorClass().
+ */
const wxPGEditor* GetEditorClass() const;
- wxString GetValueType() const
- {
- return m_value.GetType();
- }
+ /** Returns property grid where property lies. */
+ wxPropertyGrid* GetGrid() const;
- /** Returns editor used for given column. NULL for no editor.
+ /**
+ Returns owner wxPropertyGrid, but only if one is currently on a page
+ displaying this property.
*/
- const wxPGEditor* GetColumnEditor( int column ) const
- {
- if ( column == 1 )
- return GetEditorClass();
+ wxPropertyGrid* GetGridIfDisplayed() const;
- return NULL;
- }
+ /**
+ Returns property's help or description text.
- /** Returns common value selected for this property. -1 for none.
+ @see SetHelpString()
*/
- int GetCommonValue() const
- {
- return m_commonValue;
- }
+ const wxString& GetHelpString() const;
- /** Returns true if property has even one visible child.
+ /**
+ Returns position in parent's array.
*/
- bool HasVisibleChildren() const;
+ unsigned int GetIndexInParent() const;
- /** 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 );
+ /** Returns property's label. */
+ const wxString& GetLabel() const;
- /** Returns true if this property is actually a wxPropertyCategory.
+ /**
+ Returns last visible child property, recursively.
*/
- bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY)?true:false; }
+ const wxPGProperty* GetLastVisibleSubItem() const;
- /** Returns true if this property is actually a wxRootProperty.
- */
- bool IsRoot() const { return (m_parent == NULL); }
+ /**
+ Returns highest level non-category, non-root parent. Useful when you
+ have nested properties with children.
- /** Returns true if this is a sub-property. */
- bool IsSubProperty() const
- {
- wxPGProperty* parent = (wxPGProperty*)m_parent;
- if ( parent && !parent->IsCategory() )
- return true;
- return false;
- }
+ @remarks If immediate parent is root or category, this will return the
+ property itself.
+ */
+ wxPGProperty* GetMainParent() const;
- /** Returns last visible sub-property, recursively.
+ /** Returns maximum allowed length of property's text value.
*/
- const wxPGProperty* GetLastVisibleSubItem() const;
+ int GetMaxLength() const;
- wxVariant GetDefaultValue() const;
+ /** Returns property's name with all (non-category, non-root) parents. */
+ wxString GetName() const;
- int GetMaxLength() const
- {
- return (int) m_maxLen;
- }
+ /** Return parent of property */
+ wxPGProperty* GetParent() const;
- /** Determines, recursively, if all children are not unspecified. Takes values in given list into account.
+ /**
+ Returns (direct) child property with given name (or @NULL if not found).
*/
- bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const;
+ wxPGProperty* GetPropertyByName( const wxString& name ) const;
- /** Updates composed values of parent non-category properties, recursively.
- Returns topmost property updated.
+ /** Gets assignable version of property's validator. */
+ wxValidator* GetValidator() const;
- @remarks
- - Must not call SetValue() (as can be called in it).
+ /**
+ Returns property's value.
*/
- wxPGProperty* UpdateParentValues();
+ wxVariant GetValue() const;
- /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
+ /**
+ Returns bitmap that appears next to value text. Only returns non-@NULL
+ bitmap if one was set with SetValueImage().
*/
- FlagType UsesAutoUnspecified() const
- {
- return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED);
- }
-
- wxBitmap* GetValueImage() const
- {
- return m_valueBitmap;
- }
+ wxBitmap* GetValueImage() const;
- wxVariant GetAttribute( const wxString& name ) const;
+ /** Returns text representation of property's value.
- /** Returns named attribute, as string, if found. Otherwise defVal is returned.
+ @param argFlags
+ If 0 (default value), then displayed string is returned.
+ If wxPG_FULL_VALUE is set, returns complete, storable string value
+ instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
+ string value that must be editable in textctrl. If
+ wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
+ display as a part of string property's composite text
+ representation.
+
+ @remarks In older versions, this function used to be overridden to convert
+ property's value into a string representation. This function is
+ now handled by ValueToString(), and overriding this function now
+ will result in run-time assertion failure.
*/
- wxString GetAttribute( const wxString& name, const wxString& defVal ) const;
+ virtual wxString GetValueAsString( int argFlags = 0 ) const;
- /** Returns named attribute, as long, if found. Otherwise defVal is returned.
- */
- long GetAttributeAsLong( const wxString& name, long defVal ) const;
+ /** Synonymous to GetValueAsString().
- /** Returns named attribute, as double, if found. Otherwise defVal is returned.
+ @deprecated Use GetValueAsString() instead.
+
+ @see GetValueAsString()
*/
- double GetAttributeAsDouble( const wxString& name, double defVal ) const;
+ wxDEPRECATED( wxString GetValueString( int argFlags = 0 ) const );
- inline unsigned int GetArrIndex() const { return m_arrIndex; }
+ /**
+ Returns value type used by this property.
+ */
+ wxString GetValueType() const;
- inline unsigned int GetDepth() const { return (unsigned int)m_depth; }
+ /**
+ Returns coordinate to the top y of the property. Note that the
+ position of scrollbars is not taken into account.
+ */
+ int GetY() const;
- /** 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.
+ /**
+ Returns @true if property has even one visible child.
*/
- wxString GetFlagsAsString( FlagType flagsMask ) const;
+ bool HasVisibleChildren() const;
- /** Returns position in parent's array. */
- unsigned int GetIndexInParent() const
- {
- return (unsigned int)m_arrIndex;
- }
+ /**
+ Hides or reveals the property.
- /** Hides or reveals the property.
@param hide
- true for hide, false for reveal.
+ @true for hide, @false for reveal.
+
@param flags
- By default changes are applied recursively. Set this paramter wxPG_DONT_RECURSE to prevent this.
+ By default changes are applied recursively. Set this parameter wxPG_DONT_RECURSE to prevent this.
*/
- inline bool Hide( bool hide, int flags = wxPG_RECURSE );
+ bool Hide( bool hide, int flags = wxPG_RECURSE );
- bool IsExpanded() const { return (!(m_flags & wxPG_PROP_COLLAPSED) && GetChildCount()); }
-
- /** Returns true if all parents expanded.
+ /**
+ Returns index of given child property. wxNOT_FOUND if
+ given property is not child of this.
*/
- bool IsVisible() const;
+ int Index( const wxPGProperty* p ) const;
- bool IsEnabled() const
- {
- return ( m_flags & wxPG_PROP_DISABLED ) ? false : true;
- }
+ /**
+ Use this member function to add independent (ie. regular) children to
+ a property.
- /** If property's editor is created this forces its recreation. Useful
- in SetAttribute etc. Returns true if actually did anything.
- */
- bool RecreateEditor();
+ @return Inserted childProperty.
- /** If property's editor is active, then update it's value.
- */
- void RefreshEditor();
+ @remarks wxPropertyGrid is not automatically refreshed by this
+ function.
- /** Sets an attribute for this property.
- @param name
- Text identifier of attribute. See @ref propgrid_property_attributes.
- @param value
- Value of attribute.
+ @see AppendChild(), AddPrivateChild()
*/
- void SetAttribute( const wxString& name, wxVariant value );
+ wxPGProperty* InsertChild( int index, wxPGProperty* childProperty );
- void SetAttributes( const wxPGAttributeStorage& attributes );
+ /**
+ Inserts a new choice to property's list of choices.
- /** Sets editor for a property.
+ @param label
+ Text for new choice
- @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 index
+ Insertion position. Use wxNOT_FOUND to append.
- For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
+ @param value
+ Value for new choice. Do not specify if you wish this
+ to equal choice index.
*/
- void SetEditor( const wxPGEditor* editor )
- {
- m_customEditor = editor;
- }
+ int InsertChoice( const wxString& label, int index, int value = wxPG_INVALID_VALUE );
- /** Sets editor for a property.
+ /**
+ Returns @true if this property is actually a wxPropertyCategory.
*/
- inline void SetEditor( const wxString& editorName );
-
- /** Sets cell information for given column.
+ bool IsCategory() const;
- Note that the property takes ownership of given wxPGCell instance.
+ /**
+ Returns @true if property is enabled.
*/
- void SetCell( int column, wxPGCell* cellObj );
+ bool IsEnabled() const;
- /** Changes value of a property with choices, but only
- works if the value type is long or string. */
- void SetChoiceSelection( int newValue, const wxPGChoiceInfo& choiceInfo );
-
- /** Sets common value selected for this property. -1 for none.
+ /**
+ Returns @true if property has visible children.
*/
- void SetCommonValue( int commonValue )
- {
- m_commonValue = commonValue;
- }
+ bool IsExpanded() const;
- /** Sets flags from a '|' delimited string. Note that flag names are not
- prepended with 'wxPG_PROP_'.
+ /**
+ Returns @true if this property is actually a wxRootProperty.
*/
- void SetFlagsFromString( const wxString& str );
+ bool IsRoot() const;
- /** Sets property's "is it modified?" flag. Affects children recursively.
+ /**
+ Returns @true if candidateParent is some parent of this property.
*/
- void SetModifiedStatus( bool modified )
- {
- SetFlagRecursively(wxPG_PROP_MODIFIED, modified);
- }
+ bool IsSomeParent( wxPGProperty* candidateParent ) const;
- /** Call in OnEvent(), OnButtonClick() etc. to change the property value
- based on user input.
+ /**
+ Returns true if property has editable wxTextCtrl when selected.
- @remarks
- This method is const since it doesn't actually modify value, but posts
- given variant as pending value, stored in wxPropertyGrid.
+ @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).
*/
- 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.
+ bool IsTextEditable() const;
- If you need to change property value in event, based on user input, use
- SetValueInEvent() instead.
+ /**
+ Returns @true if property's value is considered unspecified. This
+ usually means that value is Null variant.
+ */
+ bool IsValueUnspecified() const;
- @param pList
- Pointer to list variant that contains child values. Used to indicate
- which children should be marked as modified.
- @param flags
- Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR).
+ /**
+ Returns true if all parents expanded.
*/
- void SetValue( wxVariant value, wxVariant* pList = NULL, int flags = 0 );
+ bool IsVisible() const;
- /** Set wxBitmap in front of the value. This bitmap may be ignored
- by custom cell renderers.
+ /**
+ Returns child property at index i.
*/
- void SetValueImage( wxBitmap& bmp );
+ wxPGProperty* Item( unsigned int i ) const;
- /** If property has choices and they are not yet exclusive, new such copy
- of them will be created.
+ /**
+ If property's editor is active, then update it's value.
*/
- void SetChoicesExclusive();
+ void RefreshEditor();
- void SetExpanded( bool expanded )
- {
- if ( !expanded ) m_flags |= wxPG_PROP_COLLAPSED;
- else m_flags &= ~wxPG_PROP_COLLAPSED;
- }
+ /**
+ Sets an attribute for this property.
- void SetFlag( FlagType flag ) { m_flags |= flag; }
+ @param name
+ Text identifier of attribute. See @ref propgrid_property_attributes.
- void SetFlagRecursively( FlagType flag, bool set );
+ @param value
+ Value of attribute.
- void SetHelpString( const wxString& helpString )
- {
- m_helpString = helpString;
- }
+ @remarks Setting attribute's value to Null variant will simply remove it
+ from property's set of attributes.
+ */
+ void SetAttribute( const wxString& name, wxVariant value );
- /** Sets property's label.
+ /**
+ Sets property's background colour.
- @remarks
- - Properties under same parent may have same labels. However,
- property names must still remain unique.
+ @param colour
+ Background colour to use.
+
+ @param recursively
+ If @true, children are affected recursively, and any categories
+ are not.
*/
- void SetLabel( const wxString& label ) { m_label = label; }
+ void SetBackgroundColour( const wxColour& colour,
+ bool recursively = false );
- inline void SetName( const wxString& newName );
+ /**
+ Sets editor for a property.
- void SetValueToUnspecified()
- {
- wxVariant val; // Create NULL variant
- SetValue(val);
- }
+ @param editor
+ For builtin editors, use wxPGEditor_X, where X is builtin editor's
+ name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list).
- /** Sets wxValidator for a property*/
- void SetValidator( const wxValidator& validator )
- {
- m_validator = wxDynamicCast(validator.Clone(),wxValidator);
- }
+ For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
+ */
+ void SetEditor( const wxPGEditor* editor );
- /** Gets assignable version of property's validator. */
- wxValidator* GetValidator() const
- {
- if ( m_validator )
- return m_validator;
- return DoGetValidator();
- }
-
- /** 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.
- @retval
- True if value changed.
+ /**
+ Sets editor for a property, by editor name.
*/
- bool PrepareValueForDialogEditing( wxPropertyGrid* propgrid );
+ void SetEditor( const wxString& editorName );
- /** Returns client data (void*) of a property.
+ /**
+ Sets cell information for given column.
*/
- void* GetClientData() const
- {
- return m_clientData;
- }
+ void SetCell( int column, const wxPGCell& cell );
- /** Sets client data (void*) of a property.
- @remarks
- This untyped client data has to be deleted manually.
+ /**
+ Sets new set of choices for property.
+
+ @remarks This operation clears the property value.
*/
- void SetClientData( void* clientData )
- {
- m_clientData = clientData;
- }
+ bool SetChoices( wxPGChoices& choices );
- /** Returns client object of a property.
+ /**
+ Sets client data (void*) of a property.
+
+ @remarks This untyped client data has to be deleted manually.
*/
- void SetClientObject(wxClientData* clientObject)
- {
- delete m_clientObject;
- m_clientObject = clientObject;
- }
+ void SetClientData( void* clientData );
- /** Sets managed client object of a property.
+ /** Returns client object of a property.
*/
- wxClientData *GetClientObject() const { return m_clientObject; }
+ void SetClientObject(wxClientData* clientObject);
- /** Sets new set of choices for property.
+ /**
+ Sets selected choice and changes property value.
- @remarks
- This operation clears the property value.
+ Tries to retain value type, although currently if it is not string,
+ then it is forced to integer.
*/
- bool SetChoices( wxPGChoices& choices );
+ void SetChoiceSelection( int newValue );
- /** Sets new set of choices for property.
+ /**
+ Sets property's help string, which is shown, for example, in
+ wxPropertyGridManager's description text box.
*/
- inline bool SetChoices( const wxArrayString& labels,
- const wxArrayInt& values = wxArrayInt() );
+ void SetHelpString( const wxString& helpString );
+
+ /**
+ Sets property's label.
- /** Set max length of text in text editor.
+ @remarks Properties under same parent may have same labels. However,
+ property names must still remain unique.
*/
- inline bool SetMaxLength( int maxLen );
+ void SetLabel( const wxString& label );
- /** Call with 'false' in OnSetValue to cancel value changes after all
- (ie. cancel 'true' returned by StringToValue() or IntToValue()).
+ /**
+ Set max length of text in text editor.
*/
- void SetWasModified( bool set = true )
- {
- if ( set ) m_flags |= wxPG_PROP_WAS_MODIFIED;
- else m_flags &= ~wxPG_PROP_WAS_MODIFIED;
- }
+ bool SetMaxLength( int maxLen );
- const wxString& GetHelpString() const
- {
- return m_helpString;
- }
+ /**
+ Sets property's "is it modified?" flag. Affects children recursively.
+ */
+ void SetModifiedStatus( bool modified );
+
+ /**
+ Sets new (base) name for property.
+ */
+ void SetName( const wxString& newName );
- void ClearFlag( FlagType flag ) { m_flags &= ~(flag); }
+ /**
+ Changes what sort of parent this property is for its children.
- // Use, for example, to detect if item is inside collapsed section.
- bool IsSomeParent( wxPGProperty* candidate_parent ) const;
+ @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).
- /** Adapts list variant into proper value using consequtive ChildChanged-calls.
+ @remarks You generally do not need to call this function.
*/
- void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
+ void SetParentalType( int flag );
- /** This is used by properties that have fixed sub-properties. */
- void AddChild( wxPGProperty* prop );
+ /**
+ Sets property's text colour.
- /** Returns height of children, recursively, and
- by taking expanded/collapsed status into account.
-
- iMax is used when finding property y-positions.
+ @param colour
+ Text colour to use.
+
+ @param recursively
+ If @true, children are affected recursively, and any categories
+ are not.
*/
- int GetChildrenHeight( int lh, int iMax = -1 ) const;
+ void SetTextColour( const wxColour& colour,
+ bool recursively = false );
- /** Returns number of child properties */
- unsigned int GetChildCount() const { return m_children.GetCount(); }
+ /** Sets wxValidator for a property */
+ void SetValidator( const wxValidator& validator );
- /** Returns sub-property at index i. */
- wxPGProperty* Item( size_t i ) const { return (wxPGProperty*)m_children.Item(i); }
+ /**
+ Call this to set value of the property. Unlike methods in wxPropertyGrid,
+ this does not automatically update the display.
- /** Returns last sub-property.
+ @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 value
+ The value to set.
+ @param pList
+ Pointer to list variant that contains child values. Used to indicate
+ which children should be marked as modified. Usually you just use @NULL.
+ @param flags
+ wxPG_SETVAL_REFRESH_EDITOR is set by default, to refresh editor
+ and redraw properties.
*/
- wxPGProperty* Last() const { return (wxPGProperty*)m_children.Last(); }
+ void SetValue( wxVariant value, wxVariant* pList = NULL,
+ int flags = wxPG_SETVAL_REFRESH_EDITOR );
- /** Returns index of given sub-property. */
- int Index( const wxPGProperty* p ) const { return m_children.Index((wxPGProperty*)p); }
+ /**
+ Set wxBitmap in front of the value. This bitmap may be ignored
+ by custom cell renderers.
+ */
+ void SetValueImage( wxBitmap& bmp );
- /** Deletes all sub-properties. */
- void Empty();
+ /**
+ Call this function in OnEvent(), OnButtonClick() etc. to change the
+ property value based on user input.
- // Puts correct indexes to children
- void FixIndexesOfChildren( size_t starthere = 0 );
+ @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;
- wxPGProperty* GetItemAtY( unsigned int y, unsigned int lh, unsigned int* nextItemY ) const;
+ /**
+ Sets property's value to unspecified (ie. Null variant).
+ */
+ void SetValueToUnspecified();
- /** Returns (direct) child property with given name (or NULL if not found).
+ /**
+ Call with @false in OnSetValue() to cancel value changes after all
+ (ie. cancel @true returned by StringToValue() or IntToValue()).
*/
- wxPGProperty* GetPropertyByName( const wxString& name ) const;
+ void SetWasModified( bool set = true );
+
+ /**
+ Updates composed values of parent non-category properties, recursively.
+ Returns topmost property updated.
+ */
+ wxPGProperty* UpdateParentValues();
+
+ /**
+ Returns @true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
+ */
+ bool UsesAutoUnspecified() const;
};
-/** @class wxPGChoices
+/**
+ @class wxPGChoices
Helper class for managing choices of wxPropertyGrid properties.
- Each entry can have label, value, bitmap, text colour, and background colour.
+ Each entry can have label, value, bitmap, text colour, and background
+ colour.
+
+ wxPGChoices uses reference counting, similar to other wxWidgets classes.
+ This means that assignment operator and copy constructor only copy the
+ reference and not the actual data. Use Copy() member function to create a
+ real copy.
+
+ @remarks If you do not specify value for entry, index is used.
@library{wxpropgrid}
@category{propgrid}
public:
typedef long ValArrItem;
- /** Default constructor. */
- wxPGChoices()
- {
- Init();
- }
+ /**
+ Default constructor.
+ */
+ wxPGChoices();
- /** Copy constructor. */
- wxPGChoices( const wxPGChoices& a )
- {
- if ( a.m_data != wxPGChoicesEmptyData )
- {
- m_data = a.m_data;
- m_data->m_refCount++;
- }
- }
+ /**
+ Copy constructor, uses reference counting. To create a real copy,
+ use Copy() member function instead.
+ */
+ wxPGChoices( const wxPGChoices& a );
+
+ /** Constructor. */
+ wxPGChoices( const wxChar** labels, const long* values = NULL );
/** Constructor. */
- wxPGChoices( const wxChar** labels, const long* values = NULL )
- {
- Init();
- Set(labels,values);
- }
+ wxPGChoices( const wxArrayString& labels, const wxArrayInt& values = wxArrayInt() );
/** Constructor. */
- wxPGChoices( const wxArrayString& labels, const wxArrayInt& values = wxArrayInt() )
- {
- Init();
- Set(labels,values);
- }
-
- /** Simple interface constructor. */
- wxPGChoices( wxPGChoicesData* data )
- {
- wxASSERT(data);
- m_data = data;
- data->m_refCount++;
- }
+ wxPGChoices( wxPGChoicesData* data );
/** Destructor. */
- ~wxPGChoices()
- {
- Free();
- }
+ ~wxPGChoices();
- /** Adds to current. If did not have own copies, creates them now. If was empty,
+ /**
+ Adds to current. 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 );
wxPGChoiceEntry& Add( const wxString& label, int value = wxPG_INVALID_VALUE );
/** Adds a single item, with bitmap. */
- wxPGChoiceEntry& Add( const wxString& label, const wxBitmap& bitmap, int value = wxPG_INVALID_VALUE );
+ wxPGChoiceEntry& Add( const wxString& label, const wxBitmap& bitmap,
+ int value = wxPG_INVALID_VALUE );
/** Adds a single item with full entry information. */
- wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry )
- {
- return Insert(entry, -1);
- }
+ wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry );
- /** Adds single item. */
+ /** Adds single item, sorted. */
wxPGChoiceEntry& AddAsSorted( const wxString& label, int value = wxPG_INVALID_VALUE );
- void Assign( const wxPGChoices& a )
- {
- AssignData(a.m_data);
- }
+ /**
+ Assigns choices data, using reference counting. To create a real copy,
+ use Copy() member function instead.
+ */
+ void Assign( const wxPGChoices& a );
+ /**
+ Assigns data from another set of choices.
+ */
void AssignData( wxPGChoicesData* data );
- /** Delete all choices. */
- void Clear()
- {
- if ( m_data != wxPGChoicesEmptyData )
- m_data->Clear();
- }
-
- void EnsureData()
- {
- if ( m_data == wxPGChoicesEmptyData )
- m_data = new wxPGChoicesData();
- }
-
- /** Gets a unsigned number identifying this list. */
- wxPGChoicesId GetId() const { return (wxPGChoicesId) m_data; };
-
- const wxString& GetLabel( size_t ind ) const
- {
- wxASSERT( ind >= 0 && ind < GetCount() );
- return Item(ind).GetText();
- }
-
- size_t GetCount () const
- {
- wxASSERT_MSG( m_data,
- wxT("When checking if wxPGChoices is valid, use IsOk() instead of GetCount()") );
- return m_data->GetCount();
- }
-
- int GetValue( size_t ind ) const { return Item(ind).GetValue(); }
-
- /** Returns array of values matching the given strings. Unmatching strings
+ /**
+ Deletes all items.
+ */
+ void Clear();
+
+ /**
+ Returns a real copy of the choices.
+ */
+ wxPGChoices Copy() const;
+
+ /**
+ Returns labe of item.
+ */
+ const wxString& GetLabel( unsigned int ind ) const;
+
+ /**
+ Returns number of items.
+ */
+ unsigned int GetCount() const;
+
+ /**
+ Returns value of item;
+ */
+ int GetValue( unsigned int ind ) const;
+
+ /**
+ Returns array of values matching the given strings. Unmatching strings
result in wxPG_INVALID_VALUE entry in array.
*/
wxArrayInt GetValuesForStrings( const wxArrayString& strings ) const;
- /** Returns array of indices matching given strings. Unmatching strings
- are added to 'unmatched', if not NULL.
+ /**
+ 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;
+ wxArrayInt GetIndicesForStrings( const wxArrayString& strings,
+ wxArrayString* unmatched = NULL ) const;
- /** Returns true if choices in general are likely to have values
- (depens on that all entries have values or none has)
+ /**
+ Returns @true if item at given index has a valid value;
*/
- bool HasValues() const;
+ bool HasValue( unsigned int i ) const;
- bool HasValue( unsigned int i ) const { return (m_data->GetCount() > i && m_data->Item(i)->HasValue()); }
+ /**
+ Returns index of item with given label.
+ */
+ int Index( const wxString& label ) const;
- int Index( const wxString& str ) const;
+ /**
+ Returns index of item with given value.
+ */
int Index( int val ) const;
- /** Inserts single item. */
+ /**
+ Inserts single item.
+ */
wxPGChoiceEntry& Insert( const wxString& label, int index, int value = wxPG_INVALID_VALUE );
- /** Inserts a single item with full entry information. */
+ /**
+ 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,
+ /**
+ Returns @false if this is a constant empty set of choices,
which should not be modified.
*/
- bool IsOk() const
- {
- return ( m_data != wxPGChoicesEmptyData );
- }
+ bool IsOk() const;
- const wxPGChoiceEntry& Item( unsigned int i ) const
- {
- wxASSERT( IsOk() );
- return *m_data->Item(i);
- }
+ /**
+ Returns item at given index.
+ */
+ const wxPGChoiceEntry& Item( unsigned int i ) const;
- wxPGChoiceEntry& Item( unsigned int i )
- {
- wxASSERT( IsOk() );
- return *m_data->Item(i);
- }
+ /**
+ Returns item at given index.
+ */
+ wxPGChoiceEntry& Item( unsigned int i );
- /** Removes count items starting at position nIndex. */
+ /**
+ Removes count items starting at position nIndex.
+ */
void RemoveAt(size_t nIndex, size_t count = 1);
- /** Does not create copies for itself. */
- void Set( const wxChar** labels, const long* values = NULL )
- {
- Free();
- Add(labels,values);
- }
+ /**
+ Sets contents from lists of strings and values.
+ */
+ void Set( const wxChar** labels, const long* values = NULL );
- /** Version that works with wxArrayString.
- TODO: Deprecate this.
+ /**
+ Sets contents from lists of strings and values.
*/
- void Set( wxArrayString& arr, const long* values = (const long*) NULL )
- {
- Free();
- Add(arr,values);
- }
+ void Set( const wxArrayString& labels, const wxArrayInt& values = wxArrayInt() );
- /** Version that works with wxArrayString and wxArrayInt. */
- void Set( const wxArrayString& labels, const wxArrayInt& values = wxArrayInt() )
- {
- Free();
- if ( &values )
- Add(labels,values);
- else
- Add(labels);
- }
-
- // Creates exclusive copy of current choices
- void SetExclusive()
- {
- if ( m_data->m_refCount != 1 )
- {
- wxPGChoicesData* data = new wxPGChoicesData();
- data->CopyDataFrom(m_data);
- Free();
- m_data = data;
- }
- }
-
- // Returns data, increases refcount.
- wxPGChoicesData* GetData()
- {
- wxASSERT( m_data->m_refCount != 0xFFFFFFF );
- m_data->m_refCount++;
- return m_data;
- }
-
- // 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;
- }
+ /**
+ Creates exclusive copy of current choices.
+ */
+ void AllocExclusive();
+ /**
+ Returns array of choice labels.
+ */
wxArrayString GetLabels() const;
- void operator= (const wxPGChoices& a)
- {
- AssignData(a.m_data);
- }
-
- wxPGChoiceEntry& operator[](unsigned int i)
- {
- return Item(i);
- }
+ void operator= (const wxPGChoices& a);
- const wxPGChoiceEntry& operator[](unsigned int i) const
- {
- return Item(i);
- }
+ wxPGChoiceEntry& operator[](unsigned int i);
+ const wxPGChoiceEntry& operator[](unsigned int i) const;
};
// -----------------------------------------------------------------------
projects / wxWidgets.git / blobdiff