*/
#define wxPG_ATTR_UNITS wxS("Units")
-/** Universal, string. When set, will be shown in property's value cell
- when displayed value string is empty, or value is unspecified.
+/** When set, will be shown as 'greyed' text in property's value cell when
+ the actual displayed value is blank.
+*/
+#define wxPG_ATTR_HINT wxS("Hint")
+
+/**
+ @deprecated Use "Hint" (wxPG_ATTR_HINT) instead.
*/
#define wxPG_ATTR_INLINE_HELP wxS("InlineHelp")
*/
#define wxPG_ATTR_AUTOCOMPLETE wxS("AutoComplete")
-/** wxBoolProperty specific, int, default 0. When 1 sets bool property to
- use checkbox instead of choice.
+/** 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")
*/
+/** @section propgrid_propflags wxPGProperty Flags
+ @{
+*/
+
+enum wxPGPropertyFlags
+{
+
+/** Indicates bold font.
+*/
+wxPG_PROP_MODIFIED = 0x0001,
+
+/** Disables ('greyed' text and editor does not activate) property.
+*/
+wxPG_PROP_DISABLED = 0x0002,
+
+/** Hider button will hide this property.
+*/
+wxPG_PROP_HIDDEN = 0x0004,
+
+/** This property has custom paint image just in front of its value.
+ If property only draws custom images into a popup list, then this
+ flag should not be set.
+*/
+wxPG_PROP_CUSTOMIMAGE = 0x0008,
+
+/** Do not create text based editor for this property (but button-triggered
+ dialog and choice are ok).
+*/
+wxPG_PROP_NOEDITOR = 0x0010,
+
+/** Property is collapsed, ie. it's children are hidden.
+*/
+wxPG_PROP_COLLAPSED = 0x0020,
+
+/**
+ If property is selected, then indicates that validation failed for pending
+ value.
+
+ If property is not selected, then indicates that the the actual property
+ value has failed validation (NB: this behavior is not currently supported,
+ but may be used in future).
+*/
+wxPG_PROP_INVALID_VALUE = 0x0040,
+
+// 0x0080,
+
+/** Switched via SetWasModified(). Temporary flag - only used when
+ setting/changing property value.
+*/
+wxPG_PROP_WAS_MODIFIED = 0x0200,
+
+/**
+ If set, then child properties (if any) are private, and should be
+ "invisible" to the application.
+*/
+wxPG_PROP_AGGREGATE = 0x0400,
+
+/** If set, then child properties (if any) are copies and should not
+ be deleted in dtor.
+*/
+wxPG_PROP_CHILDREN_ARE_COPIES = 0x0800,
+
+/**
+ Classifies this item as a non-category.
+
+ Used for faster item type identification.
+*/
+wxPG_PROP_PROPERTY = 0x1000,
+
+/**
+ Classifies this item as a category.
+
+ Used for faster item type identification.
+*/
+wxPG_PROP_CATEGORY = 0x2000,
+
+/** Classifies this item as a property that has children, but is not aggregate
+ (ie children are not private).
+*/
+wxPG_PROP_MISC_PARENT = 0x4000,
+
+/** Property is read-only. Editor is still created for wxTextCtrl-based
+ property editors. For others, editor is not usually created because
+ they do implement wxTE_READONLY style or equivalent.
+*/
+wxPG_PROP_READONLY = 0x8000,
+
+//
+// NB: FLAGS ABOVE 0x8000 CANNOT BE USED WITH PROPERTY ITERATORS
+//
+
+/** Property's value is composed from values of child properties.
+ @remarks
+ This flag cannot be used with property iterators.
+*/
+wxPG_PROP_COMPOSED_VALUE = 0x00010000,
+
+/** Common value of property is selectable in editor.
+ @remarks
+ This flag cannot be used with property iterators.
+*/
+wxPG_PROP_USES_COMMON_VALUE = 0x00020000,
+
+/** Property can be set to unspecified value via editor.
+ Currently, this applies to following properties:
+ - wxIntProperty, wxUIntProperty, wxFloatProperty, wxEditEnumProperty:
+ Clear the text field
+
+ @remarks
+ This flag cannot be used with property iterators.
+*/
+wxPG_PROP_AUTO_UNSPECIFIED = 0x00040000,
+
+/** Indicates the bit useable by derived properties.
+*/
+wxPG_PROP_CLASS_SPECIFIC_1 = 0x00080000,
+
+/** Indicates the bit useable by derived properties.
+*/
+wxPG_PROP_CLASS_SPECIFIC_2 = 0x00100000,
+
+/** Indicates that the property is being deleted and should be ignored.
+*/
+wxPG_PROP_BEING_DELETED = 0x00200000
+
+};
+
+/** Topmost flag.
+*/
+#define wxPG_PROP_MAX wxPG_PROP_AUTO_UNSPECIFIED
+
+/** Property with children must have one of these set, otherwise iterators
+ will not work correctly.
+ Code should automatically take care of this, however.
+*/
+#define wxPG_PROP_PARENTAL_FLAGS \
+ ((wxPGPropertyFlags)(wxPG_PROP_AGGREGATE | \
+ wxPG_PROP_CATEGORY | \
+ wxPG_PROP_MISC_PARENT))
+
+/** @}
+*/
+
/**
@class wxPGProperty
@subsection wxPropertyCategory
Not an actual property per se, but a header for a group of properties.
- Regardless inherits from wxPGProperty.
+ Regardless inherits from wxPGProperty, and supports displaying 'labels'
+ for columns other than the first one. Easiest way to set category's
+ label for second column is to call wxPGProperty::SetValue() with string
+ argument.
@subsection wxStringProperty
@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 wxPGProperty::SetChoices() - 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
class MyProperty : public wxPGProperty
{
public:
- // All arguments of ctor must have a default value -
+ // Default constructor
+ MyProperty() { }
+
+ // All arguments of this ctor must have a default value -
// use wxPG_LABEL for label and name
MyProperty( const wxString& label = wxPG_LABEL,
const wxString& name = wxPG_LABEL,
const wxString& value = wxEmptyString )
+ : wxPGProperty(label, name)
{
// m_value is wxVariant
m_value = value;
@code
MyProperty( const wxString& label, const wxString& name, const T& value )
- : wxPGProperty()
+ : wxPGProperty(label, name)
{
// Generally recommended way to set the initial value
// (as it should work in pretty much 100% of cases).
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
virtual bool OnEvent( wxPropertyGrid* propgrid, wxWindow* wnd_primary, wxEvent& event );
/**
- Called after value of a child property has been altered. Note that this function is
- usually called at the time that value of this property, or given child property, is
- still pending for change.
+ Called after value of a child property has been altered. Must return
+ new value of the whole property (after any alterations warrented by
+ child's new value).
+
+ Note that this function is usually called at the time that value of
+ this property, or given child property, is still pending for change,
+ and as such, result of GetValue() or m_value should not be relied
+ on.
Sample pseudo-code implementation:
@code
- void MyProperty::ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const
+ wxVariant MyProperty::ChildChanged( wxVariant& thisValue,
+ int childIndex,
+ wxVariant& childValue ) const
{
// Acquire reference to actual type of data stored in variant
- // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros were used to create
- // the variant class).
+ // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros
+ // were used to create the variant class).
T& data = TFromVariant(thisValue);
// Copy childValue into data.
break;
...
}
+
+ // Return altered data
+ return data;
}
@endcode
@param thisValue
- Value of this property, that should be altered.
+ Value of this property. Changed value should be returned (in
+ previous versions of wxPropertyGrid it was only necessary to
+ write value back to this argument).
@param childIndex
- Index of child changed (you can use Item(childIndex) to get).
+ Index of child changed (you can use Item(childIndex) to get
+ child property).
@param childValue
- Value of the child property.
+ (Pending) value of the child property.
+
+ @return
+ Modified value of the whole property.
*/
- virtual void ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const;
+ virtual wxVariant ChildChanged( wxVariant& thisValue,
+ int childIndex,
+ wxVariant& childValue ) const;
/**
Returns pointer to an instance of used editor.
virtual void RefreshChildren();
/**
- Special handling for attributes of this property.
+ Reimplement this member function to add special handling for
+ attributes of this property.
- If returns @false, then the attribute will be automatically stored in
- m_attributes.
+ @return Return @false to have the attribute automatically stored in
+ m_attributes. Default implementation simply does that and
+ nothing else.
- Default implementation simply returns @false.
+ @remarks To actually set property attribute values from the
+ application, use wxPGProperty::SetAttribute() instead.
*/
virtual bool DoSetAttribute( const wxString& name, wxVariant& value );
int AddChoice( const wxString& label, int 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:
+ Adds a private child property.
- @code
- wxPGProperty* prop = new wxStringProperty(wxS("Property"));
- prop->SetParentalType(wxPG_PROP_MISC_PARENT);
- wxPGProperty* prop2 = new wxStringProperty(wxS("Property2"));
- prop->AddChild(prop2);
- @endcode
+ @deprecated Use AddPrivateChild() instead.
+
+ @see AddPrivateChild()
*/
- void AddChild( wxPGProperty* property );
+ wxDEPRECATED( void AddChild( wxPGProperty* prop ) );
+
+ /**
+ 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 );
/**
Adapts list variant into proper value using consecutive
*/
void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
+ /**
+ Use this member function to add independent (ie. regular) children to
+ a property.
+
+ @return Appended childProperty.
+
+ @remarks wxPropertyGrid is not automatically refreshed by this
+ function.
+
+ @see InsertChild(), AddPrivateChild()
+ */
+ wxPGProperty* AppendChild( wxPGProperty* childProperty );
+
/**
Determines, recursively, if all children are not unspecified.
*/
bool AreChildrenComponents() const;
+ /**
+ Sets or clears given property flag.
+
+ @see propgrid_propflags
+ */
+ void ChangeFlag( wxPGPropertyFlags flag, bool set );
+
/**
Deletes children of the property.
*/
/**
Returns wxPGCell of given column.
+
+ @remarks const version of this member function returns 'default'
+ wxPGCell object if the property itself didn't hold
+ cell data.
*/
const wxPGCell& GetCell( unsigned int column ) const;
+ /**
+ Returns wxPGCell of given column, creating one if necessary.
+ */
+ wxPGCell& GetCell( unsigned int column );
+
+ /**
+ Returns wxPGCell of given column, creating one if necessary.
+ */
+ wxPGCell& GetOrCreateCell( unsigned int column );
+
/**
Returns number of child properties.
*/
*/
const wxPGEditor* GetEditorClass() const;
+ /**
+ Returns property flags.
+ */
+ FlagType GetFlags() const;
+
/** Returns property grid where property lies. */
wxPropertyGrid* GetGrid() const;
*/
int GetY() const;
+ /**
+ Returns non-zero if property has given flag set.
+
+ @see propgrid_propflags
+ */
+ FlagType HasFlag( wxPGPropertyFlags flag ) const;
+
/**
Returns @true if property has even one visible child.
*/
*/
int Index( const wxPGProperty* p ) const;
+ /**
+ Use this member function to add independent (ie. regular) children to
+ a property.
+
+ @return Inserted childProperty.
+
+ @remarks wxPropertyGrid is not automatically refreshed by this
+ function.
+
+ @see AppendChild(), AddPrivateChild()
+ */
+ wxPGProperty* InsertChild( int index, wxPGProperty* childProperty );
+
/**
Inserts a new choice to property's list of choices.
@param colour
Background colour to use.
- @param recursively
- If @true, children are affected recursively, and any categories
- are not.
+ @param flags
+ Default is wxPG_RECURSE which causes colour to be set recursively.
+ Omit this flag to only set colour for the property in question
+ and not any of its children.
*/
void SetBackgroundColour( const wxColour& colour,
- bool recursively = false );
+ int flags = wxPG_RECURSE );
/**
Sets editor for a property.
void SetCell( int column, const wxPGCell& cell );
/**
- Sets new set of choices for property.
+ Sets new set of choices for the property.
- @remarks This operation clears the property value.
+ @remarks This operation deselects the property and clears its
+ value.
*/
bool SetChoices( wxPGChoices& choices );
*/
void SetChoiceSelection( int newValue );
+ /** Set default value of a property. Synonymous to
+
+ @code
+ SetAttribute("DefaultValue", value);
+ @endcode
+ */
+ void SetDefaultValue( wxVariant& value );
+
+ /**
+ Sets given property flag.
+
+ @see propgrid_propflags
+ */
+ void SetFlag( wxPGPropertyFlags flag );
+
+ /**
+ Sets or clears given property flag, recursively.
+
+ @see propgrid_propflags
+ */
+ void SetFlagRecursively( wxPGPropertyFlags flag, bool set );
+
/**
Sets property's help string, which is shown, for example, in
wxPropertyGridManager's description text box.
wxPG_PROP_AGGREGATE (for derived property classes with private
children).
- @remarks You only need to call this if you use AddChild() to add
- child properties. Adding properties with
- wxPropertyGridInterface::Insert() or
- wxPropertyGridInterface::AppendIn() will automatically set
- property to use wxPG_PROP_MISC_PARENT style.
+ @remarks You generally do not need to call this function.
*/
void SetParentalType( int flag );
@param colour
Text colour to use.
- @param recursively
- If @true, children are affected recursively, and any categories
- are not.
+ @param flags
+ Default is wxPG_RECURSE which causes colour to be set recursively.
+ Omit this flag to only set colour for the property in question
+ and not any of its children.
*/
void SetTextColour( const wxColour& colour,
- bool recursively = false );
+ int flags = wxPG_RECURSE );
/** Sets wxValidator for a property */
void SetValidator( const wxValidator& validator );
};
+/**
+ @class wxPGCell
+
+ Base class for wxPropertyGrid cell information.
+
+ @library{wxpropgrid}
+ @category{propgrid}
+*/
+class wxPGCell : public wxObject
+{
+public:
+ wxPGCell();
+ wxPGCell(const wxPGCell& other);
+ wxPGCell( const wxString& text,
+ const wxBitmap& bitmap = wxNullBitmap,
+ const wxColour& fgCol = wxNullColour,
+ const wxColour& bgCol = wxNullColour );
+
+ virtual ~wxPGCell();
+
+ const wxPGCellData* GetData() const;
+
+ /**
+ Returns @true if this cell has custom text stored within.
+ */
+ bool HasText() const;
+
+ /**
+ Merges valid data from srcCell into this.
+ */
+ void MergeFrom( const wxPGCell& srcCell );
+
+ void SetText( const wxString& text );
+ void SetBitmap( const wxBitmap& bitmap );
+ void SetFgCol( const wxColour& col );
+
+ /**
+ Sets font of the cell.
+
+ @remarks Because wxPropertyGrid does not support rows of
+ different height, it makes little sense to change
+ size of the font. Therefore it is recommended
+ to use return value of wxPropertyGrid::GetFont()
+ or wxPropertyGrid::GetCaptionFont() as a basis
+ for the font that, after modifications, is passed
+ to this member function.
+ */
+ void SetFont( const wxFont& font );
+
+ void SetBgCol( const wxColour& col );
+
+ const wxString& GetText() const;
+ const wxBitmap& GetBitmap() const;
+ const wxColour& GetFgCol() const;
+
+ /**
+ Returns font of the cell. If no specific font is set for this
+ cell, then the font will be invalid.
+ */
+ const wxFont& GetFont() const;
+
+ const wxColour& GetBgCol() const;
+
+ wxPGCell& operator=( const wxPGCell& other );
+};
+
+
/**
@class wxPGChoices
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
@library{wxpropgrid}
@category{propgrid}
*/
-class WXDLLIMPEXP_PROPGRID wxPGChoices
+class wxPGChoices
{
public:
typedef long ValArrItem;
wxArrayInt GetIndicesForStrings( const wxArrayString& strings,
wxArrayString* unmatched = NULL ) const;
+ /** Returns property at given virtual y coordinate.
+ */
+ wxPGProperty* GetItemAtY( unsigned int y ) const;
+
/**
Returns @true if item at given index has a valid value;
*/
projects / wxWidgets.git / blobdiff