1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxPGProperty
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 #define wxNullProperty ((wxPGProperty*)NULL)
15 Contains information relayed to property's OnCustomPaint.
19 /** wxPropertyGrid. */
20 const wxPropertyGrid
* m_parent
;
22 /** Normally -1, otherwise index to drop-down list item that has to be drawn. */
25 /** Set to drawn width in OnCustomPaint (optional). */
28 /** In a measure item call, set this to the height of item at m_choiceItem index. */
33 // Structure for relaying choice/list info.
36 wxPGChoices
* m_choices
;
40 /** @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers
42 wxPGProperty::SetAttribute() and
43 wxPropertyGridInterface::SetPropertyAttribute()
44 accept one of these as attribute name argument .
46 You can use strings instead of constants. However, some of these
47 constants are redefined to use cached strings which may reduce
48 your binary size by some amount.
53 /** Set default value for property.
55 #define wxPG_ATTR_DEFAULT_VALUE wxS("DefaultValue")
57 /** Universal, int or double. Minimum value for numeric properties.
59 #define wxPG_ATTR_MIN wxS("Min")
61 /** Universal, int or double. Maximum value for numeric properties.
63 #define wxPG_ATTR_MAX wxS("Max")
65 /** Universal, string. When set, will be shown as text after the displayed
66 text value. Alternatively, if third column is enabled, text will be shown
67 there (for any type of property).
69 #define wxPG_ATTR_UNITS wxS("Units")
71 /** Universal, string. When set, will be shown in property's value cell
72 when displayed value string is empty, or value is unspecified.
74 #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp")
76 /** wxBoolProperty specific, int, default 0. When 1 sets bool property to
77 use checkbox instead of choice.
79 #define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox")
81 /** wxBoolProperty specific, int, default 0. When 1 sets bool property value
82 to cycle on double click (instead of showing the popup listbox).
84 #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING wxS("UseDClickCycling")
86 /** wxFloatProperty (and similar) specific, int, default -1. Sets the (max) precision
87 used when floating point value is rendered as text. The default -1 means infinite
90 #define wxPG_FLOAT_PRECISION wxS("Precision")
92 /** The text will be echoed as asterisks (wxTE_PASSWORD will be passed to textctrl etc).
94 #define wxPG_STRING_PASSWORD wxS("Password")
96 /** Define base used by a wxUIntProperty. Valid constants are
97 wxPG_BASE_OCT, wxPG_BASE_DEC, wxPG_BASE_HEX and wxPG_BASE_HEXL
98 (lowercase characters).
100 #define wxPG_UINT_BASE wxS("Base")
102 /** Define prefix rendered to wxUIntProperty. Accepted constants
103 wxPG_PREFIX_NONE, wxPG_PREFIX_0x, and wxPG_PREFIX_DOLLAR_SIGN.
104 <b>Note:</b> Only wxPG_PREFIX_NONE works with Decimal and Octal
107 #define wxPG_UINT_PREFIX wxS("Prefix")
109 /** wxFileProperty/wxImageFileProperty specific, wxChar*, default is detected/varies.
110 Sets the wildcard used in the triggered wxFileDialog. Format is the
113 #define wxPG_FILE_WILDCARD wxS("Wildcard")
115 /** wxFileProperty/wxImageFileProperty specific, int, default 1.
116 When 0, only the file name is shown (i.e. drive and directory are hidden).
118 #define wxPG_FILE_SHOW_FULL_PATH wxS("ShowFullPath")
120 /** Specific to wxFileProperty and derived properties, wxString, default empty.
121 If set, then the filename is shown relative to the given path string.
123 #define wxPG_FILE_SHOW_RELATIVE_PATH wxS("ShowRelativePath")
125 /** Specific to wxFileProperty and derived properties, wxString, default is empty.
126 Sets the initial path of where to look for files.
128 #define wxPG_FILE_INITIAL_PATH wxS("InitialPath")
130 /** Specific to wxFileProperty and derivatives, wxString, default is empty.
131 Sets a specific title for the dir dialog.
133 #define wxPG_FILE_DIALOG_TITLE wxS("DialogTitle")
135 /** Specific to wxDirProperty, wxString, default is empty.
136 Sets a specific message for the dir dialog.
138 #define wxPG_DIR_DIALOG_MESSAGE wxS("DialogMessage")
140 /** Sets displayed date format for wxDateProperty.
142 #define wxPG_DATE_FORMAT wxS("DateFormat")
144 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
145 is wxDP_DEFAULT | wxDP_SHOWCENTURY.
147 #define wxPG_DATE_PICKER_STYLE wxS("PickerStyle")
149 /** SpinCtrl editor, int or double. How much number changes when button is
150 pressed (or up/down on keybard).
152 #define wxPG_ATTR_SPINCTRL_STEP wxS("Step")
154 /** SpinCtrl editor, bool. If true, value wraps at Min/Max.
156 #define wxPG_ATTR_SPINCTRL_WRAP wxS("Wrap")
158 /** wxMultiChoiceProperty, int. If 0, no user strings allowed. If 1, user strings
159 appear before list strings. If 2, user strings appear after list string.
161 #define wxPG_ATTR_MULTICHOICE_USERSTRINGMODE wxS("UserStringMode")
163 /** wxColourProperty and its kind, int, default 1. Setting this attribute to 0 hides custom
164 colour from property's list of choices.
166 #define wxPG_COLOUR_ALLOW_CUSTOM wxS("AllowCustom")
168 /** First attribute id that is guaranteed not to be used built-in
171 //#define wxPG_USER_ATTRIBUTE 192
176 // -----------------------------------------------------------------------
178 /** @class wxPGProperty
180 wxPGProperty is base class for all wxPropertyGrid properties. In
181 sections below we cover few related topics.
183 @li @ref pgproperty_properties
184 @li @ref pgproperty_creating
186 @section pgproperty_properties Supplied Ready-to-use Property Classes
188 Here is a list and short description of supplied fully-functional
189 property classes. They are located in either props.h or advprops.h.
191 @li @ref wxArrayStringProperty
192 @li @ref wxBoolProperty
193 @li @ref wxColourProperty
194 @li @ref wxCursorProperty
195 @li @ref wxDateProperty
196 @li @ref wxDirProperty
197 @li @ref wxEditEnumProperty
198 @li @ref wxEnumProperty
199 @li @ref wxFileProperty
200 @li @ref wxFlagsProperty
201 @li @ref wxFloatProperty
202 @li @ref wxFontProperty
203 @li @ref wxImageFileProperty
204 @li @ref wxIntProperty
205 @li @ref wxLongStringProperty
206 @li @ref wxMultiChoiceProperty
207 @li @ref wxPropertyCategory
208 @li @ref wxStringProperty
209 @li @ref wxSystemColourProperty
210 @li @ref wxUIntProperty
212 @subsection wxPropertyCategory
214 Not an actual property per se, but a header for a group of properties.
215 Regardless inherits from wxPGProperty.
217 @subsection wxStringProperty
219 Simple string property. wxPG_STRING_PASSWORD attribute may be used
220 to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl.
223 * wxStringProperty has a special trait: if it has value of "<composed>",
224 and also has child properties, then its displayed value becomes
225 composition of child property values, similar as with wxFontProperty,
228 @subsection wxIntProperty
230 Like wxStringProperty, but converts text to a signed long integer.
231 wxIntProperty seamlessly supports 64-bit integers (ie. wxLongLong).
233 @subsection wxUIntProperty
235 Like wxIntProperty, but displays value as unsigned int. To set
236 the prefix used globally, manipulate wxPG_UINT_PREFIX string attribute.
237 To set the globally used base, manipulate wxPG_UINT_BASE int
238 attribute. Regardless of current prefix, understands (hex) values starting
239 with both "0x" and "$".
240 wxUIntProperty seamlessly supports 64-bit unsigned integers (ie. wxULongLong).
242 @subsection wxFloatProperty
244 Like wxStringProperty, but converts text to a double-precision floating point.
245 Default float-to-text precision is 6 decimals, but this can be changed
246 by modifying wxPG_FLOAT_PRECISION attribute.
248 @subsection wxBoolProperty
250 Represents a boolean value. wxChoice is used as editor control, by the
251 default. wxPG_BOOL_USE_CHECKBOX attribute can be set to true inorder to use
254 @subsection wxLongStringProperty
256 Like wxStringProperty, but has a button that triggers a small text editor
257 dialog. Note that in long string values, tabs are represented by "\t" and
260 @subsection wxDirProperty
262 Like wxLongStringProperty, but the button triggers dir selector instead.
263 Supported properties (all with string value): wxPG_DIR_DIALOG_MESSAGE.
265 @subsection wxFileProperty
267 Like wxLongStringProperty, but the button triggers file selector instead.
268 Default wildcard is "All files..." but this can be changed by setting
269 wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details).
270 Attribute wxPG_FILE_SHOW_FULL_PATH can be set to false inorder to show
271 only the filename, not the entire path.
273 @subsection wxEnumProperty
275 Represents a single selection from a list of choices -
276 wxOwnerDrawnComboBox is used to edit the value.
278 @subsection wxFlagsProperty
280 Represents a bit set that fits in a long integer. wxBoolProperty sub-properties
281 are created for editing individual bits. Textctrl is created to manually edit
282 the flags as a text; a continous sequence of spaces, commas and semicolons
283 is considered as a flag id separator.
284 <b>Note: </b> When changing "choices" (ie. flag labels) of wxFlagsProperty, you
285 will need to use SetPropertyChoices - otherwise they will not get updated properly.
287 @subsection wxArrayStringProperty
289 Allows editing of a list of strings in wxTextCtrl and in a separate dialog.
291 @subsection wxDateProperty
293 wxDateTime property. Default editor is DatePickerCtrl, altough TextCtrl
294 should work as well. wxPG_DATE_FORMAT attribute can be used to change
295 string wxDateTime::Format uses (altough default is recommended as it is
296 locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window
297 style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY).
299 @subsection wxEditEnumProperty
301 Represents a string that can be freely edited or selected from list of choices -
302 custom combobox control is used to edit the value.
304 @subsection wxMultiChoiceProperty
306 Allows editing a multiple selection from a list of strings. This is
307 property is pretty much built around concept of wxMultiChoiceDialog.
308 It uses wxArrayString value.
310 @subsection wxImageFileProperty
312 Like wxFileProperty, but has thumbnail of the image in front of
313 the filename and autogenerates wildcard from available image handlers.
315 @subsection wxColourProperty
317 <b>Useful alternate editor:</b> Choice.
319 Represents wxColour. wxButton is used to trigger a colour picker dialog.
321 @subsection wxFontProperty
323 Represents wxFont. Various sub-properties are used to edit individual
326 @subsection wxSystemColourProperty
328 Represents wxColour and a system colour index. wxChoice is used to edit
329 the value. Drop-down list has color images. Note that value type
330 is wxColourPropertyValue instead of wxColour.
332 class wxColourPropertyValue : public wxObject
335 // An integer value relating to the colour, and which exact
336 // meaning depends on the property with which it is used.
338 // For wxSystemColourProperty:
339 // Any of wxSYS_COLOUR_XXX, or any web-colour ( use wxPG_TO_WEB_COLOUR
340 // macro - (currently unsupported) ), or wxPG_COLOUR_CUSTOM.
343 // Resulting colour. Should be correct regardless of type.
348 @subsection wxCursorProperty
350 Represents a wxCursor. wxChoice is used to edit the value.
351 Drop-down list has cursor images under some (wxMSW) platforms.
354 @section pgproperty_creating Creating Custom Properties
356 New properties can be created by subclassing wxPGProperty or one
357 of the provided property classes, and (re)implementing necessary
358 member functions. Below, each virtual member function has ample
359 documentation about its purpose and any odd details which to keep
362 Here is a very simple 'template' code:
365 class MyProperty : public wxPGProperty
368 // All arguments of ctor must have a default value -
369 // use wxPG_LABEL for label and name
370 MyProperty( const wxString& label = wxPG_LABEL,
371 const wxString& name = wxPG_LABEL,
372 const wxString& value = wxEmptyString )
374 // m_value is wxVariant
378 virtual ~MyProperty() { }
380 const wxPGEditor* DoGetEditorClass() const
382 // Determines editor used by property.
383 // You can replace 'TextCtrl' below with any of these
384 // builtin-in property editor identifiers: Choice, ComboBox,
385 // TextCtrlAndButton, ChoiceAndButton, CheckBox, SpinCtrl,
387 return wxPGEditor_TextCtrl;
390 virtual wxString GetValueAsString( int argFlags ) const
392 // TODO: Return property value in string format
395 virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags )
397 // TODO: Adapt string to property value.
404 Since wxPGProperty derives from wxObject, you can use standard
405 DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS macros. From the
406 above example they were omitted for sake of simplicity, and besides,
407 they are only really needed if you need to use wxRTTI with your
410 You can change the 'value type' of a property by simply assigning different
411 type of variant with SetValue. <b>It is mandatory to implement
412 wxVariantData class for all data types used as property values.</b>
413 You can use macros declared in wxPropertyGrid headers. For instance:
417 // (If you need to have export declaration, use version of macros
418 // with _EXPORTED postfix)
419 WX_PG_DECLARE_VARIANT_DATA(MyDataClass)
422 WX_PG_IMPLEMENT_VARIANT_DATA(MyDataClass)
424 // Or, if you don't have valid == operator:
425 WX_PG_IMPLEMENT_VARIANT_DATA_DUMMY_EQ(MyDataClass)
431 class wxPGProperty
: public wxObject
434 typedef wxUint32 FlagType
;
436 /** Basic constructor.
441 Non-abstract property classes should have constructor of this style:
445 // If T is a class, then it should be a constant reference
446 // (e.g. const T& ) instead.
447 MyProperty( const wxString& label, const wxString& name, T value )
450 // Generally recommended way to set the initial value
451 // (as it should work in pretty much 100% of cases).
456 // If has private child properties then create them here. For example:
457 // AddChild( new wxStringProperty( "Subprop 1", wxPG_LABEL, value.GetSubProp1() ) );
462 wxPGProperty( const wxString
& label
, const wxString
& name
);
464 /** Virtual destructor. It is customary for derived properties to implement this. */
465 virtual ~wxPGProperty();
467 /** This virtual function is called after m_value has been set.
470 - If m_value was set to Null variant (ie. unspecified value), OnSetValue()
472 - m_value may be of any variant type. Typically properties internally support only
473 one variant type, and as such OnSetValue() provides a good opportunity to convert
474 supported values into internal type.
475 - Default implementation does nothing.
477 virtual void OnSetValue();
479 /** Override this to return something else than m_value as the value.
481 virtual wxVariant
DoGetValue() const { return m_value
; }
483 /** Implement this function in derived class to check the value.
484 Return true if it is ok. Returning false prevents property change events
488 - Default implementation always returns true.
490 virtual bool ValidateValue( wxVariant
& value
, wxPGValidationInfo
& validationInfo
) const;
492 /** Converts 'text' into proper value 'variant'. Returns true if new (different than
493 m_value) value could be interpreted from the text.
495 If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable
496 one (they may be different).
497 If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of composite
498 property string value (as generated by GetValueAsString() called with this same
502 Default implementation converts semicolon delimited tokens into child values. Only
503 works for properties with children.
505 virtual bool StringToValue( wxVariant
& variant
, const wxString
& text
, int argFlags
= 0 ) const;
507 /** Converts 'number' (including choice selection) into proper value 'variant'.
508 Returns true if new (different than m_value) value could be interpreted from the integer.
510 If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable one.
513 - If property is not supposed to use choice or spinctrl or other editor
514 with int-based value, it is not necessary to implement this method.
515 - Default implementation simply assign given int to m_value.
516 - If property uses choice control, and displays a dialog on some choice items,
517 then it is preferred to display that dialog in IntToValue instead of OnEvent.
519 virtual bool IntToValue( wxVariant
& value
, int number
, int argFlags
= 0 ) const;
523 /** Returns text representation of property's value.
526 If wxPG_FULL_VALUE is set, returns complete, storable string value instead of displayable.
527 If wxPG_EDITABLE_VALUE is set, returns string value that must be editable in textctrl.
528 If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to display
529 as a part of composite property string value.
532 Default implementation returns string composed from text representations of
535 virtual wxString
GetValueAsString( int argFlags
= 0 ) const;
537 /** Converts string to a value, and if successful, calls SetValue() on it.
538 Default behavior is to do nothing.
540 String to get the value from.
542 true if value was changed.
544 bool SetValueFromString( const wxString
& text
, int flags
= 0 );
546 /** Converts integer to a value, and if succesful, calls SetValue() on it.
547 Default behavior is to do nothing.
549 Int to get the value from.
551 If has wxPG_FULL_VALUE, then the value given is a actual value and not an index.
553 True if value was changed.
555 bool SetValueFromInt( long value
, int flags
= 0 );
557 /** Returns size of the custom painted image in front of property. This method
558 must be overridden to return non-default value if OnCustomPaint is to be
561 Normally -1, but can be an index to the property's list of items.
563 - Default behavior is to return wxSize(0,0), which means no image.
564 - Default image width or height is indicated with dimension -1.
565 - You can also return wxPG_DEFAULT_IMAGE_SIZE which equals wxSize(-1, -1).
567 virtual wxSize
OnMeasureImage( int item
= -1 ) const;
569 /** Events received by editor widgets are processed here. Note that editor class
570 usually processes most events. Some, such as button press events of
571 TextCtrlAndButton class, can be handled here. Also, if custom handling
572 for regular events is desired, then that can also be done (for example,
573 wxSystemColourProperty custom handles wxEVT_COMMAND_CHOICE_SELECTED
574 to display colour picker dialog when 'custom' selection is made).
576 If the event causes value to be changed, SetValueInEvent()
577 should be called to set the new value.
582 Should return true if any changes in value should be reported.
584 - If property uses choice control, and displays a dialog on some choice items,
585 then it is preferred to display that dialog in IntToValue instead of OnEvent.
587 virtual bool OnEvent( wxPropertyGrid
* propgrid
, wxWindow
* wnd_primary
, wxEvent
& event
);
589 /** Called after value of a child property has been altered. Note that this function is
590 usually called at the time that value of this property, or given child property, is
591 still pending for change.
593 Sample pseudo-code implementation:
596 void MyProperty::ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const
598 // Acquire reference to actual type of data stored in variant
599 // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros were used to create
600 // the variant class).
601 T& data = TFromVariant(thisValue);
603 // Copy childValue into data.
604 switch ( childIndex )
607 data.SetSubProp1( childvalue.GetLong() );
610 data.SetSubProp2( childvalue.GetString() );
618 Value of this property, that should be altered.
620 Index of child changed (you can use Item(childIndex) to get).
622 Value of the child property.
624 virtual void ChildChanged( wxVariant
& thisValue
, int childIndex
, wxVariant
& childValue
) const;
626 /** Returns pointer to an instance of used editor.
628 virtual const wxPGEditor
* DoGetEditorClass() const;
630 /** Returns pointer to the wxValidator that should be used
631 with the editor of this property (NULL for no validator).
632 Setting validator explicitly via SetPropertyValidator
635 In most situations, code like this should work well
636 (macros are used to maintain one actual validator instance,
637 so on the second call the function exits within the first
642 wxValidator* wxMyPropertyClass::DoGetValidator () const
644 WX_PG_DOGETVALIDATOR_ENTRY()
646 wxMyValidator* validator = new wxMyValidator(...);
648 ... prepare validator...
650 WX_PG_DOGETVALIDATOR_EXIT(validator)
656 You can get common filename validator by returning
657 wxFileProperty::GetClassValidator(). wxDirProperty,
658 for example, uses it.
660 virtual wxValidator
* DoGetValidator () const;
662 /** Returns current value's index to the choice control. May also return,
663 through pointer arguments, strings that should be inserted to that control.
664 Irrelevant to classes which do not employ wxPGEditor_Choice or similar.
666 - If returns NULL in choiceinfo.m_choices, then this class must be
667 derived from wxBaseEnumProperty.
668 - Must be able to cope situation where property's set of choices is
671 virtual int GetChoiceInfo( wxPGChoiceInfo
* choiceinfo
);
673 /** Override to paint an image in front of the property value text or drop-down
674 list item (but only if wxPGProperty::OnMeasureImage is overridden as well).
676 If property's OnMeasureImage() returns size that has height != 0 but less than
677 row height ( < 0 has special meanings), wxPropertyGrid calls this method to
678 draw a custom image in a limited area in front of the editor control or
679 value text/graphics, and if control has drop-down list, then the image is
680 drawn there as well (even in the case OnMeasureImage() returned higher height
683 NOTE: Following applies when OnMeasureImage() returns a "flexible" height (
684 using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable height items:
685 If rect.x is < 0, then this is a measure item call, which means that
686 dc is invalid and only thing that should be done is to set paintdata.m_drawnHeight
687 to the height of the image of item at index paintdata.m_choiceItem. This call
688 may be done even as often as once every drop-down popup show.
693 Box reserved for custom graphics. Includes surrounding rectangle, if any.
694 If x is < 0, then this is a measure item call (see above).
696 wxPGPaintData structure with much useful data.
699 - You can actually exceed rect width, but if you do so then paintdata.m_drawnWidth
700 must be set to the full width drawn in pixels.
701 - Due to technical reasons, rect's height will be default even if custom height
702 was reported during measure call.
703 - Brush is guaranteed to be default background colour. It has been already used to
704 clear the background of area being painted. It can be modified.
705 - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper colour) pen for
706 drawing framing rectangle. It can be changed as well.
708 @see GetValueAsString()
710 virtual void OnCustomPaint( wxDC
& dc
, const wxRect
& rect
, wxPGPaintData
& paintdata
);
712 /** Returns used wxPGCellRenderer instance for given property column (label=0, value=1).
714 Default implementation returns editor's renderer for all columns.
716 virtual wxPGCellRenderer
* GetCellRenderer( int column
) const;
718 /** Refresh values of child properties. Automatically called after value is set.
720 virtual void RefreshChildren();
722 /** Special handling for attributes of this property.
724 If returns false, then the attribute will be automatically stored in
727 Default implementation simply returns false.
729 virtual bool DoSetAttribute( const wxString
& name
, wxVariant
& value
);
731 /** Returns value of an attribute.
733 Override if custom handling of attributes is needed.
735 Default implementation simply return NULL variant.
737 virtual wxVariant
DoGetAttribute( const wxString
& name
) const;
739 /** Returns instance of a new wxPGEditorDialogAdapter instance, which is
740 used when user presses the (optional) button next to the editor control;
742 Default implementation returns NULL (ie. no action is generated when
745 virtual wxPGEditorDialogAdapter
* GetEditorDialog() const;
747 /** Adds entry to property's wxPGChoices and editor control (if it is active).
748 Returns index of item added.
750 int AppendChoice( const wxString
& label
, int value
= wxPG_INVALID_VALUE
)
752 return InsertChoice(label
,-1,value
);
755 /** Returns wxPGCell of given column, NULL if none. If valid
756 object is returned, caller will gain its ownership.
758 wxPGCell
* AcquireCell( unsigned int column
)
760 if ( column
>= m_cells
.size() )
763 wxPGCell
* cell
= (wxPGCell
*) m_cells
[column
];
764 m_cells
[column
] = NULL
;
768 /** Returns true if children of this property are component values (for instance,
769 points size, face name, and is_underlined are component values of a font).
771 bool AreChildrenComponents() const
773 if ( m_flags
& (wxPG_PROP_COMPOSED_VALUE
|wxPG_PROP_AGGREGATE
) )
779 /** Removes entry from property's wxPGChoices and editor control (if it is active).
781 If selected item is deleted, then the value is set to unspecified.
783 void DeleteChoice( int index
);
785 /** Call to enable or disable usage of common value (integer value that can be selected for
786 properties instead of their normal values) for this property.
788 Common values are disabled by the default for all properties.
790 void EnableCommonValue( bool enable
= true )
792 if ( enable
) SetFlag( wxPG_PROP_USES_COMMON_VALUE
);
793 else ClearFlag( wxPG_PROP_USES_COMMON_VALUE
);
796 /** Composes text from values of child properties. */
797 void GenerateComposedValue( wxString
& text
, int argFlags
= 0 ) const;
799 /** Returns property's label. */
800 const wxString
& GetLabel() const { return m_label
; }
802 /** Returns property's name with all (non-category, non-root) parents. */
803 wxString
GetName() const;
805 /** Returns property's base name (ie. parent's name is not added in any case) */
806 const wxString
& GetBaseName() const { return m_name
; }
808 wxPGChoices
& GetChoices();
810 const wxPGChoices
& GetChoices() const;
812 const wxPGChoiceEntry
* GetCurrentChoice() const;
814 /** Returns coordinate to the top y of the property. Note that the
815 position of scrollbars is not taken into account.
819 wxVariant
GetValue() const
824 /** Returns reference to the internal stored value. GetValue is preferred
825 way to get the actual value, since GetValueRef ignores DoGetValue,
826 which may override stored value.
828 wxVariant
& GetValueRef()
833 const wxVariant
& GetValueRef() const
838 /** Same as GetValueAsString, except takes common value into account.
840 wxString
GetValueString( int argFlags
= 0 ) const;
842 void UpdateControl( wxWindow
* primary
);
844 /** Returns wxPGCell of given column, NULL if none. wxPGProperty
845 will retain ownership of the cell object.
847 wxPGCell
* GetCell( unsigned int column
) const
849 if ( column
>= m_cells
.size() )
852 return (wxPGCell
*) m_cells
[column
];
855 unsigned int GetChoiceCount() const;
857 wxString
GetChoiceString( unsigned int index
);
859 /** Return number of displayed common values for this property.
861 int GetDisplayedCommonValueCount() const;
863 wxString
GetDisplayedString() const
865 return GetValueString(0);
868 /** Returns property grid where property lies. */
869 wxPropertyGrid
* GetGrid() const;
871 /** Returns owner wxPropertyGrid, but only if one is currently on a page
872 displaying this property. */
873 wxPropertyGrid
* GetGridIfDisplayed() const;
875 /** Returns highest level non-category, non-root parent. Useful when you
876 have nested wxCustomProperties/wxParentProperties.
878 Thus, if immediate parent is root or category, this will return the
881 wxPGProperty
* GetMainParent() const;
883 /** Return parent of property */
884 wxPGProperty
* GetParent() const { return m_parent
; }
886 /** Returns true if property has editable wxTextCtrl when selected.
889 Altough disabled properties do not displayed editor, they still
890 return True here as being disabled is considered a temporary
891 condition (unlike being read-only or having limited editing enabled).
893 bool IsTextEditable() const;
895 bool IsValueUnspecified() const
897 return m_value
.IsNull();
900 FlagType
HasFlag( FlagType flag
) const
902 return ( m_flags
& flag
);
905 /** Returns comma-delimited string of property attributes.
907 const wxPGAttributeStorage
& GetAttributes() const
912 /** Returns m_attributes as list wxVariant.
914 wxVariant
GetAttributesAsList() const;
916 FlagType
GetFlags() const
921 const wxPGEditor
* GetEditorClass() const;
923 wxString
GetValueType() const
925 return m_value
.GetType();
928 /** Returns editor used for given column. NULL for no editor.
930 const wxPGEditor
* GetColumnEditor( int column
) const
933 return GetEditorClass();
938 /** Returns common value selected for this property. -1 for none.
940 int GetCommonValue() const
942 return m_commonValue
;
945 /** Returns true if property has even one visible child.
947 bool HasVisibleChildren() const;
949 /** Adds entry to property's wxPGChoices and editor control (if it is active).
950 Returns index of item added.
952 int InsertChoice( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
954 /** Returns true if this property is actually a wxPropertyCategory.
956 bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY
)?
true:false; }
958 /** Returns true if this property is actually a wxRootProperty.
960 bool IsRoot() const { return (m_parent
== NULL
); }
962 /** Returns true if this is a sub-property. */
963 bool IsSubProperty() const
965 wxPGProperty
* parent
= (wxPGProperty
*)m_parent
;
966 if ( parent
&& !parent
->IsCategory() )
971 /** Returns last visible sub-property, recursively.
973 const wxPGProperty
* GetLastVisibleSubItem() const;
975 wxVariant
GetDefaultValue() const;
977 int GetMaxLength() const
979 return (int) m_maxLen
;
982 /** Determines, recursively, if all children are not unspecified. Takes values in given list into account.
984 bool AreAllChildrenSpecified( wxVariant
* pendingList
= NULL
) const;
986 /** Updates composed values of parent non-category properties, recursively.
987 Returns topmost property updated.
990 - Must not call SetValue() (as can be called in it).
992 wxPGProperty
* UpdateParentValues();
994 /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
996 FlagType
UsesAutoUnspecified() const
998 return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED
);
1001 wxBitmap
* GetValueImage() const
1003 return m_valueBitmap
;
1006 wxVariant
GetAttribute( const wxString
& name
) const;
1008 /** Returns named attribute, as string, if found. Otherwise defVal is returned.
1010 wxString
GetAttribute( const wxString
& name
, const wxString
& defVal
) const;
1012 /** Returns named attribute, as long, if found. Otherwise defVal is returned.
1014 long GetAttributeAsLong( const wxString
& name
, long defVal
) const;
1016 /** Returns named attribute, as double, if found. Otherwise defVal is returned.
1018 double GetAttributeAsDouble( const wxString
& name
, double defVal
) const;
1020 inline unsigned int GetArrIndex() const { return m_arrIndex
; }
1022 inline unsigned int GetDepth() const { return (unsigned int)m_depth
; }
1024 /** Gets flags as a'|' delimited string. Note that flag names are not
1025 prepended with 'wxPG_PROP_'.
1027 String will only be made to include flags combined by this parameter.
1029 wxString
GetFlagsAsString( FlagType flagsMask
) const;
1031 /** Returns position in parent's array. */
1032 unsigned int GetIndexInParent() const
1034 return (unsigned int)m_arrIndex
;
1037 /** Hides or reveals the property.
1039 true for hide, false for reveal.
1041 By default changes are applied recursively. Set this paramter wxPG_DONT_RECURSE to prevent this.
1043 inline bool Hide( bool hide
, int flags
= wxPG_RECURSE
);
1045 bool IsExpanded() const { return (!(m_flags
& wxPG_PROP_COLLAPSED
) && GetChildCount()); }
1047 /** Returns true if all parents expanded.
1049 bool IsVisible() const;
1051 bool IsEnabled() const
1053 return ( m_flags
& wxPG_PROP_DISABLED
) ?
false : true;
1056 /** If property's editor is created this forces its recreation. Useful
1057 in SetAttribute etc. Returns true if actually did anything.
1059 bool RecreateEditor();
1061 /** If property's editor is active, then update it's value.
1063 void RefreshEditor();
1065 /** Sets an attribute for this property.
1067 Text identifier of attribute. See @ref propgrid_property_attributes.
1071 void SetAttribute( const wxString
& name
, wxVariant value
);
1073 void SetAttributes( const wxPGAttributeStorage
& attributes
);
1075 /** Sets editor for a property.
1078 For builtin editors, use wxPGEditor_X, where X is builtin editor's
1079 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list).
1081 For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
1083 void SetEditor( const wxPGEditor
* editor
)
1085 m_customEditor
= editor
;
1088 /** Sets editor for a property.
1090 inline void SetEditor( const wxString
& editorName
);
1092 /** Sets cell information for given column.
1094 Note that the property takes ownership of given wxPGCell instance.
1096 void SetCell( int column
, wxPGCell
* cellObj
);
1098 /** Changes value of a property with choices, but only
1099 works if the value type is long or string. */
1100 void SetChoiceSelection( int newValue
, const wxPGChoiceInfo
& choiceInfo
);
1102 /** Sets common value selected for this property. -1 for none.
1104 void SetCommonValue( int commonValue
)
1106 m_commonValue
= commonValue
;
1109 /** Sets flags from a '|' delimited string. Note that flag names are not
1110 prepended with 'wxPG_PROP_'.
1112 void SetFlagsFromString( const wxString
& str
);
1114 /** Sets property's "is it modified?" flag. Affects children recursively.
1116 void SetModifiedStatus( bool modified
)
1118 SetFlagRecursively(wxPG_PROP_MODIFIED
, modified
);
1121 /** Call in OnEvent(), OnButtonClick() etc. to change the property value
1122 based on user input.
1125 This method is const since it doesn't actually modify value, but posts
1126 given variant as pending value, stored in wxPropertyGrid.
1128 void SetValueInEvent( wxVariant value
) const;
1130 /** Call this to set value of the property. Unlike methods in wxPropertyGrid,
1131 this does not automatically update the display.
1134 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through
1135 validation process and send property change event.
1137 If you need to change property value in event, based on user input, use
1138 SetValueInEvent() instead.
1141 Pointer to list variant that contains child values. Used to indicate
1142 which children should be marked as modified.
1144 Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR).
1146 void SetValue( wxVariant value
, wxVariant
* pList
= NULL
, int flags
= 0 );
1148 /** Set wxBitmap in front of the value. This bitmap may be ignored
1149 by custom cell renderers.
1151 void SetValueImage( wxBitmap
& bmp
);
1153 /** If property has choices and they are not yet exclusive, new such copy
1154 of them will be created.
1156 void SetChoicesExclusive();
1158 void SetExpanded( bool expanded
)
1160 if ( !expanded
) m_flags
|= wxPG_PROP_COLLAPSED
;
1161 else m_flags
&= ~wxPG_PROP_COLLAPSED
;
1164 void SetFlag( FlagType flag
) { m_flags
|= flag
; }
1166 void SetFlagRecursively( FlagType flag
, bool set
);
1168 void SetHelpString( const wxString
& helpString
)
1170 m_helpString
= helpString
;
1173 /** Sets property's label.
1176 - Properties under same parent may have same labels. However,
1177 property names must still remain unique.
1179 void SetLabel( const wxString
& label
) { m_label
= label
; }
1181 inline void SetName( const wxString
& newName
);
1183 void SetValueToUnspecified()
1185 wxVariant val
; // Create NULL variant
1189 /** Sets wxValidator for a property*/
1190 void SetValidator( const wxValidator
& validator
)
1192 m_validator
= wxDynamicCast(validator
.Clone(),wxValidator
);
1195 /** Gets assignable version of property's validator. */
1196 wxValidator
* GetValidator() const
1200 return DoGetValidator();
1203 /** Updates property value in case there were last minute
1204 changes. If value was unspecified, it will be set to default.
1205 Use only for properties that have TextCtrl-based editor.
1207 If you have code similar to
1209 // Update the value in case of last minute changes
1210 if ( primary && propgrid->IsEditorsValueModified() )
1211 GetEditorClass()->CopyValueFromControl( this, primary );
1213 in wxPGProperty::OnEvent wxEVT_COMMAND_BUTTON_CLICKED handler,
1214 then replace it with call to this method.
1216 True if value changed.
1218 bool PrepareValueForDialogEditing( wxPropertyGrid
* propgrid
);
1220 /** Returns client data (void*) of a property.
1222 void* GetClientData() const
1224 return m_clientData
;
1227 /** Sets client data (void*) of a property.
1229 This untyped client data has to be deleted manually.
1231 void SetClientData( void* clientData
)
1233 m_clientData
= clientData
;
1236 /** Returns client object of a property.
1238 void SetClientObject(wxClientData
* clientObject
)
1240 delete m_clientObject
;
1241 m_clientObject
= clientObject
;
1244 /** Sets managed client object of a property.
1246 wxClientData
*GetClientObject() const { return m_clientObject
; }
1248 /** Sets new set of choices for property.
1251 This operation clears the property value.
1253 bool SetChoices( wxPGChoices
& choices
);
1255 /** Sets new set of choices for property.
1257 inline bool SetChoices( const wxArrayString
& labels
,
1258 const wxArrayInt
& values
= wxArrayInt() );
1260 /** Set max length of text in text editor.
1262 inline bool SetMaxLength( int maxLen
);
1264 /** Call with 'false' in OnSetValue to cancel value changes after all
1265 (ie. cancel 'true' returned by StringToValue() or IntToValue()).
1267 void SetWasModified( bool set
= true )
1269 if ( set
) m_flags
|= wxPG_PROP_WAS_MODIFIED
;
1270 else m_flags
&= ~wxPG_PROP_WAS_MODIFIED
;
1273 const wxString
& GetHelpString() const
1275 return m_helpString
;
1278 void ClearFlag( FlagType flag
) { m_flags
&= ~(flag
); }
1280 // Use, for example, to detect if item is inside collapsed section.
1281 bool IsSomeParent( wxPGProperty
* candidate_parent
) const;
1283 /** Adapts list variant into proper value using consequtive ChildChanged-calls.
1285 void AdaptListToValue( wxVariant
& list
, wxVariant
* value
) const;
1287 /** This is used by properties that have fixed sub-properties. */
1288 void AddChild( wxPGProperty
* prop
);
1290 /** Returns height of children, recursively, and
1291 by taking expanded/collapsed status into account.
1293 iMax is used when finding property y-positions.
1295 int GetChildrenHeight( int lh
, int iMax
= -1 ) const;
1297 /** Returns number of child properties */
1298 unsigned int GetChildCount() const { return m_children
.GetCount(); }
1300 /** Returns sub-property at index i. */
1301 wxPGProperty
* Item( size_t i
) const { return (wxPGProperty
*)m_children
.Item(i
); }
1303 /** Returns last sub-property.
1305 wxPGProperty
* Last() const { return (wxPGProperty
*)m_children
.Last(); }
1307 /** Returns index of given sub-property. */
1308 int Index( const wxPGProperty
* p
) const { return m_children
.Index((wxPGProperty
*)p
); }
1310 /** Deletes all sub-properties. */
1313 // Puts correct indexes to children
1314 void FixIndexesOfChildren( size_t starthere
= 0 );
1316 wxPGProperty
* GetItemAtY( unsigned int y
, unsigned int lh
, unsigned int* nextItemY
) const;
1318 /** Returns (direct) child property with given name (or NULL if not found).
1320 wxPGProperty
* GetPropertyByName( const wxString
& name
) const;
1324 /** @class wxPGChoices
1326 Helper class for managing choices of wxPropertyGrid properties.
1327 Each entry can have label, value, bitmap, text colour, and background colour.
1329 @library{wxpropgrid}
1332 class WXDLLIMPEXP_PROPGRID wxPGChoices
1335 typedef long ValArrItem
;
1337 /** Default constructor. */
1343 /** Copy constructor. */
1344 wxPGChoices( const wxPGChoices
& a
)
1346 if ( a
.m_data
!= wxPGChoicesEmptyData
)
1349 m_data
->m_refCount
++;
1354 wxPGChoices( const wxChar
** labels
, const long* values
= NULL
)
1361 wxPGChoices( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() )
1367 /** Simple interface constructor. */
1368 wxPGChoices( wxPGChoicesData
* data
)
1381 /** Adds to current. If did not have own copies, creates them now. If was empty,
1382 identical to set except that creates copies.
1384 void Add( const wxChar
** labels
, const ValArrItem
* values
= NULL
);
1386 /** Version that works with wxArrayString. */
1387 void Add( const wxArrayString
& arr
, const ValArrItem
* values
= NULL
);
1389 /** Version that works with wxArrayString and wxArrayInt. */
1390 void Add( const wxArrayString
& arr
, const wxArrayInt
& arrint
);
1392 /** Adds single item. */
1393 wxPGChoiceEntry
& Add( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1395 /** Adds a single item, with bitmap. */
1396 wxPGChoiceEntry
& Add( const wxString
& label
, const wxBitmap
& bitmap
, int value
= wxPG_INVALID_VALUE
);
1398 /** Adds a single item with full entry information. */
1399 wxPGChoiceEntry
& Add( const wxPGChoiceEntry
& entry
)
1401 return Insert(entry
, -1);
1404 /** Adds single item. */
1405 wxPGChoiceEntry
& AddAsSorted( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1407 void Assign( const wxPGChoices
& a
)
1409 AssignData(a
.m_data
);
1412 void AssignData( wxPGChoicesData
* data
);
1414 /** Delete all choices. */
1417 if ( m_data
!= wxPGChoicesEmptyData
)
1423 if ( m_data
== wxPGChoicesEmptyData
)
1424 m_data
= new wxPGChoicesData();
1427 /** Gets a unsigned number identifying this list. */
1428 wxPGChoicesId
GetId() const { return (wxPGChoicesId
) m_data
; };
1430 const wxString
& GetLabel( size_t ind
) const
1432 wxASSERT( ind
>= 0 && ind
< GetCount() );
1433 return Item(ind
).GetText();
1436 size_t GetCount () const
1438 wxASSERT_MSG( m_data
,
1439 wxT("When checking if wxPGChoices is valid, use IsOk() instead of GetCount()") );
1440 return m_data
->GetCount();
1443 int GetValue( size_t ind
) const { return Item(ind
).GetValue(); }
1445 /** Returns array of values matching the given strings. Unmatching strings
1446 result in wxPG_INVALID_VALUE entry in array.
1448 wxArrayInt
GetValuesForStrings( const wxArrayString
& strings
) const;
1450 /** Returns array of indices matching given strings. Unmatching strings
1451 are added to 'unmatched', if not NULL.
1453 wxArrayInt
GetIndicesForStrings( const wxArrayString
& strings
, wxArrayString
* unmatched
= NULL
) const;
1455 /** Returns true if choices in general are likely to have values
1456 (depens on that all entries have values or none has)
1458 bool HasValues() const;
1460 bool HasValue( unsigned int i
) const { return (m_data
->GetCount() > i
&& m_data
->Item(i
)->HasValue()); }
1462 int Index( const wxString
& str
) const;
1463 int Index( int val
) const;
1465 /** Inserts single item. */
1466 wxPGChoiceEntry
& Insert( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1468 /** Inserts a single item with full entry information. */
1469 wxPGChoiceEntry
& Insert( const wxPGChoiceEntry
& entry
, int index
);
1471 /** Returns false if this is a constant empty set of choices,
1472 which should not be modified.
1476 return ( m_data
!= wxPGChoicesEmptyData
);
1479 const wxPGChoiceEntry
& Item( unsigned int i
) const
1482 return *m_data
->Item(i
);
1485 wxPGChoiceEntry
& Item( unsigned int i
)
1488 return *m_data
->Item(i
);
1491 /** Removes count items starting at position nIndex. */
1492 void RemoveAt(size_t nIndex
, size_t count
= 1);
1494 /** Does not create copies for itself. */
1495 void Set( const wxChar
** labels
, const long* values
= NULL
)
1501 /** Version that works with wxArrayString.
1502 TODO: Deprecate this.
1504 void Set( wxArrayString
& arr
, const long* values
= (const long*) NULL
)
1510 /** Version that works with wxArrayString and wxArrayInt. */
1511 void Set( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() )
1520 // Creates exclusive copy of current choices
1523 if ( m_data
->m_refCount
!= 1 )
1525 wxPGChoicesData
* data
= new wxPGChoicesData();
1526 data
->CopyDataFrom(m_data
);
1532 // Returns data, increases refcount.
1533 wxPGChoicesData
* GetData()
1535 wxASSERT( m_data
->m_refCount
!= 0xFFFFFFF );
1536 m_data
->m_refCount
++;
1540 // Returns plain data ptr - no refcounting stuff is done.
1541 wxPGChoicesData
* GetDataPtr() const { return m_data
; }
1543 // Changes ownership of data to you.
1544 wxPGChoicesData
* ExtractData()
1546 wxPGChoicesData
* data
= m_data
;
1547 m_data
= wxPGChoicesEmptyData
;
1551 wxArrayString
GetLabels() const;
1553 void operator= (const wxPGChoices
& a
)
1555 AssignData(a
.m_data
);
1558 wxPGChoiceEntry
& operator[](unsigned int i
)
1563 const wxPGChoiceEntry
& operator[](unsigned int i
) const
1569 // -----------------------------------------------------------------------