1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxPGProperty
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 #define wxNullProperty ((wxPGProperty*)NULL)
13 /** @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers
15 wxPGProperty::SetAttribute() and
16 wxPropertyGridInterface::SetPropertyAttribute()
17 accept one of these as attribute name argument .
19 You can use strings instead of constants. However, some of these
20 constants are redefined to use cached strings which may reduce
21 your binary size by some amount.
26 /** Set default value for property.
28 #define wxPG_ATTR_DEFAULT_VALUE wxS("DefaultValue")
30 /** Universal, int or double. Minimum value for numeric properties.
32 #define wxPG_ATTR_MIN wxS("Min")
34 /** Universal, int or double. Maximum value for numeric properties.
36 #define wxPG_ATTR_MAX wxS("Max")
38 /** Universal, string. When set, will be shown as text after the displayed
39 text value. Alternatively, if third column is enabled, text will be shown
40 there (for any type of property).
42 #define wxPG_ATTR_UNITS wxS("Units")
44 /** Universal, string. When set, will be shown in property's value cell
45 when displayed value string is empty, or value is unspecified.
47 #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp")
49 /** wxBoolProperty specific, int, default 0. When 1 sets bool property to
50 use checkbox instead of choice.
52 #define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox")
54 /** wxBoolProperty specific, int, default 0. When 1 sets bool property value
55 to cycle on double click (instead of showing the popup listbox).
57 #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING wxS("UseDClickCycling")
59 /** wxFloatProperty (and similar) specific, int, default -1. Sets the (max) precision
60 used when floating point value is rendered as text. The default -1 means infinite
63 #define wxPG_FLOAT_PRECISION wxS("Precision")
65 /** The text will be echoed as asterisks (wxTE_PASSWORD will be passed to textctrl etc).
67 #define wxPG_STRING_PASSWORD wxS("Password")
69 /** Define base used by a wxUIntProperty. Valid constants are
70 wxPG_BASE_OCT, wxPG_BASE_DEC, wxPG_BASE_HEX and wxPG_BASE_HEXL
71 (lowercase characters).
73 #define wxPG_UINT_BASE wxS("Base")
75 /** Define prefix rendered to wxUIntProperty. Accepted constants
76 wxPG_PREFIX_NONE, wxPG_PREFIX_0x, and wxPG_PREFIX_DOLLAR_SIGN.
77 <b>Note:</b> Only wxPG_PREFIX_NONE works with Decimal and Octal
80 #define wxPG_UINT_PREFIX wxS("Prefix")
82 /** wxFileProperty/wxImageFileProperty specific, wxChar*, default is detected/varies.
83 Sets the wildcard used in the triggered wxFileDialog. Format is the
86 #define wxPG_FILE_WILDCARD wxS("Wildcard")
88 /** wxFileProperty/wxImageFileProperty specific, int, default 1.
89 When 0, only the file name is shown (i.e. drive and directory are hidden).
91 #define wxPG_FILE_SHOW_FULL_PATH wxS("ShowFullPath")
93 /** Specific to wxFileProperty and derived properties, wxString, default empty.
94 If set, then the filename is shown relative to the given path string.
96 #define wxPG_FILE_SHOW_RELATIVE_PATH wxS("ShowRelativePath")
98 /** Specific to wxFileProperty and derived properties, wxString, default is empty.
99 Sets the initial path of where to look for files.
101 #define wxPG_FILE_INITIAL_PATH wxS("InitialPath")
103 /** Specific to wxFileProperty and derivatives, wxString, default is empty.
104 Sets a specific title for the dir dialog.
106 #define wxPG_FILE_DIALOG_TITLE wxS("DialogTitle")
108 /** Specific to wxDirProperty, wxString, default is empty.
109 Sets a specific message for the dir dialog.
111 #define wxPG_DIR_DIALOG_MESSAGE wxS("DialogMessage")
113 /** Sets displayed date format for wxDateProperty.
115 #define wxPG_DATE_FORMAT wxS("DateFormat")
117 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
118 is wxDP_DEFAULT | wxDP_SHOWCENTURY.
120 #define wxPG_DATE_PICKER_STYLE wxS("PickerStyle")
122 /** SpinCtrl editor, int or double. How much number changes when button is
123 pressed (or up/down on keybard).
125 #define wxPG_ATTR_SPINCTRL_STEP wxS("Step")
127 /** SpinCtrl editor, bool. If true, value wraps at Min/Max.
129 #define wxPG_ATTR_SPINCTRL_WRAP wxS("Wrap")
131 /** wxMultiChoiceProperty, int. If 0, no user strings allowed. If 1, user strings
132 appear before list strings. If 2, user strings appear after list string.
134 #define wxPG_ATTR_MULTICHOICE_USERSTRINGMODE wxS("UserStringMode")
136 /** wxColourProperty and its kind, int, default 1. Setting this attribute to 0 hides custom
137 colour from property's list of choices.
139 #define wxPG_COLOUR_ALLOW_CUSTOM wxS("AllowCustom")
144 // -----------------------------------------------------------------------
146 /** @class wxPGProperty
148 wxPGProperty is base class for all wxPropertyGrid properties. In
149 sections below we cover few related topics.
151 @li @ref pgproperty_properties
152 @li @ref pgproperty_creating
154 @section pgproperty_properties Supplied Ready-to-use Property Classes
156 Here is a list and short description of supplied fully-functional
157 property classes. They are located in either props.h or advprops.h.
159 @li @ref wxArrayStringProperty
160 @li @ref wxBoolProperty
161 @li @ref wxColourProperty
162 @li @ref wxCursorProperty
163 @li @ref wxDateProperty
164 @li @ref wxDirProperty
165 @li @ref wxEditEnumProperty
166 @li @ref wxEnumProperty
167 @li @ref wxFileProperty
168 @li @ref wxFlagsProperty
169 @li @ref wxFloatProperty
170 @li @ref wxFontProperty
171 @li @ref wxImageFileProperty
172 @li @ref wxIntProperty
173 @li @ref wxLongStringProperty
174 @li @ref wxMultiChoiceProperty
175 @li @ref wxPropertyCategory
176 @li @ref wxStringProperty
177 @li @ref wxSystemColourProperty
178 @li @ref wxUIntProperty
180 @subsection wxPropertyCategory
182 Not an actual property per se, but a header for a group of properties.
183 Regardless inherits from wxPGProperty.
185 @subsection wxStringProperty
187 Simple string property. wxPG_STRING_PASSWORD attribute may be used
188 to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl.
190 @remarks wxStringProperty has a special trait: if it has value of
191 "<composed>", and also has child properties, then its displayed
192 value becomes composition of child property values, similar as
193 with wxFontProperty, for instance.
195 @subsection wxIntProperty
197 Like wxStringProperty, but converts text to a signed long integer.
198 wxIntProperty seamlessly supports 64-bit integers (ie. wxLongLong).
199 To safely convert variant to integer, use code like this:
203 ll << property->GetValue();
206 wxLongLong ll = propertyGrid->GetPropertyValueAsLong(property);
209 @subsection wxUIntProperty
211 Like wxIntProperty, but displays value as unsigned int. To set
212 the prefix used globally, manipulate wxPG_UINT_PREFIX string attribute.
213 To set the globally used base, manipulate wxPG_UINT_BASE int
214 attribute. Regardless of current prefix, understands (hex) values starting
215 with both "0x" and "$".
216 Like wxIntProperty, wxUIntProperty seamlessly supports 64-bit unsigned
217 integers (ie. wxULongLong). Same wxVariant safety rules apply.
219 @subsection wxFloatProperty
221 Like wxStringProperty, but converts text to a double-precision floating point.
222 Default float-to-text precision is 6 decimals, but this can be changed
223 by modifying wxPG_FLOAT_PRECISION attribute.
225 @subsection wxBoolProperty
227 Represents a boolean value. wxChoice is used as editor control, by the
228 default. wxPG_BOOL_USE_CHECKBOX attribute can be set to true inorder to use
231 @subsection wxLongStringProperty
233 Like wxStringProperty, but has a button that triggers a small text editor
234 dialog. Note that in long string values, tabs are represented by "\t" and
237 To display custom dialog on button press, you can subclass
238 wxLongStringProperty and implement OnButtonClick, like this:
241 virtual bool OnButtonClick( wxPropertyGrid* propGrid, wxString& value )
243 // Update property value from editor, if necessary
244 PrepareValueForDialogEditing(propGrid);
246 wxSize dialogSize(...size of your dialog...);
248 wxPoint dlgPos = propGrid->GetGoodEditorDialogPosition(this,
251 // Create dialog dlg at dlgPos. Use value as initial string
255 if ( dlg.ShowModal() == wxID_OK )
257 value = dlg.GetStringValue);
264 Also, if you wish not to have line breaks and tabs translated to
265 escape sequences, then do following in constructor of your subclass:
268 m_flags |= wxPG_PROP_NO_ESCAPE;
271 @subsection wxDirProperty
273 Like wxLongStringProperty, but the button triggers dir selector instead.
274 Supported properties (all with string value): wxPG_DIR_DIALOG_MESSAGE.
276 @subsection wxFileProperty
278 Like wxLongStringProperty, but the button triggers file selector instead.
279 Default wildcard is "All files..." but this can be changed by setting
280 wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details).
281 Attribute wxPG_FILE_SHOW_FULL_PATH can be set to false inorder to show
282 only the filename, not the entire path.
284 @subsection wxEnumProperty
286 Represents a single selection from a list of choices -
287 wxOwnerDrawnComboBox is used to edit the value.
289 @subsection wxFlagsProperty
291 Represents a bit set that fits in a long integer. wxBoolProperty sub-properties
292 are created for editing individual bits. Textctrl is created to manually edit
293 the flags as a text; a continous sequence of spaces, commas and semicolons
294 is considered as a flag id separator.
295 <b>Note: </b> When changing "choices" (ie. flag labels) of wxFlagsProperty, you
296 will need to use wxPGProperty::SetChoices() - otherwise they will not get updated
299 @subsection wxArrayStringProperty
301 Allows editing of a list of strings in wxTextCtrl and in a separate dialog.
303 @subsection wxDateProperty
305 wxDateTime property. Default editor is DatePickerCtrl, altough TextCtrl
306 should work as well. wxPG_DATE_FORMAT attribute can be used to change
307 string wxDateTime::Format uses (altough default is recommended as it is
308 locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window
309 style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY).
311 @subsection wxEditEnumProperty
313 Represents a string that can be freely edited or selected from list of choices -
314 custom combobox control is used to edit the value.
316 @subsection wxMultiChoiceProperty
318 Allows editing a multiple selection from a list of strings. This is
319 property is pretty much built around concept of wxMultiChoiceDialog.
320 It uses wxArrayString value.
322 @subsection wxImageFileProperty
324 Like wxFileProperty, but has thumbnail of the image in front of
325 the filename and autogenerates wildcard from available image handlers.
327 @subsection wxColourProperty
329 <b>Useful alternate editor:</b> Choice.
331 Represents wxColour. wxButton is used to trigger a colour picker dialog.
332 There are various sub-classing opportunities with this class. See
333 below in wxSystemColourProperty section for details.
335 @subsection wxFontProperty
337 Represents wxFont. Various sub-properties are used to edit individual
340 @subsection wxSystemColourProperty
342 Represents wxColour and a system colour index. wxChoice is used to edit
343 the value. Drop-down list has color images. Note that value type
344 is wxColourPropertyValue instead of wxColour (which wxColourProperty
348 class wxColourPropertyValue : public wxObject
351 // An integer value relating to the colour, and which exact
352 // meaning depends on the property with which it is used.
354 // For wxSystemColourProperty:
355 // Any of wxSYS_COLOUR_XXX, or any web-colour ( use wxPG_TO_WEB_COLOUR
356 // macro - (currently unsupported) ), or wxPG_COLOUR_CUSTOM.
359 // Resulting colour. Should be correct regardless of type.
364 in wxSystemColourProperty, and its derived class wxColourProperty, there
365 are various sub-classing features. To set basic list list of colour
366 names, call wxPGProperty::SetChoices().
369 // Override in derived class to customize how colours are translated
371 virtual wxString ColourToString( const wxColour& col, int index ) const;
373 // Returns index of entry that triggers colour picker dialog
374 // (default is last).
375 virtual int GetCustomColourIndex() const;
377 // Helper function to show the colour dialog
378 bool QueryColourFromUser( wxVariant& variant ) const;
380 // Returns colour for given choice.
381 // Default function returns wxSystemSettings::GetColour(index).
382 virtual wxColour GetColour( int index ) const;
385 @subsection wxCursorProperty
387 Represents a wxCursor. wxChoice is used to edit the value.
388 Drop-down list has cursor images under some (wxMSW) platforms.
391 @section pgproperty_creating Creating Custom Properties
393 New properties can be created by subclassing wxPGProperty or one
394 of the provided property classes, and (re)implementing necessary
395 member functions. Below, each virtual member function has ample
396 documentation about its purpose and any odd details which to keep
399 Here is a very simple 'template' code:
402 class MyProperty : public wxPGProperty
405 // All arguments of ctor must have a default value -
406 // use wxPG_LABEL for label and name
407 MyProperty( const wxString& label = wxPG_LABEL,
408 const wxString& name = wxPG_LABEL,
409 const wxString& value = wxEmptyString )
411 // m_value is wxVariant
415 virtual ~MyProperty() { }
417 const wxPGEditor* DoGetEditorClass() const
419 // Determines editor used by property.
420 // You can replace 'TextCtrl' below with any of these
421 // builtin-in property editor identifiers: Choice, ComboBox,
422 // TextCtrlAndButton, ChoiceAndButton, CheckBox, SpinCtrl,
424 return wxPGEditor_TextCtrl;
427 virtual wxString GetValueAsString( int argFlags ) const
429 // TODO: Return property value in string format
432 virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags )
434 // TODO: Adapt string to property value.
441 Since wxPGProperty derives from wxObject, you can use standard
442 DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS macros. From the
443 above example they were omitted for sake of simplicity, and besides,
444 they are only really needed if you need to use wxRTTI with your
447 You can change the 'value type' of a property by simply assigning different
448 type of variant with SetValue. <b>It is mandatory to implement
449 wxVariantData class for all data types used as property values.</b>
450 You can use macros declared in wxPropertyGrid headers. For instance:
454 // (If you need to have export declaration, use version of macros
455 // with _EXPORTED postfix)
456 WX_PG_DECLARE_VARIANT_DATA(MyDataClass)
459 WX_PG_IMPLEMENT_VARIANT_DATA(MyDataClass)
461 // Or, if you don't have valid == operator:
462 WX_PG_IMPLEMENT_VARIANT_DATA_DUMMY_EQ(MyDataClass)
468 class wxPGProperty
: public wxObject
471 typedef wxUint32 FlagType
;
480 Non-abstract property classes should have constructor of this style:
484 MyProperty( const wxString& label, const wxString& name, const T& value )
487 // Generally recommended way to set the initial value
488 // (as it should work in pretty much 100% of cases).
493 // If has private child properties then create them here. For example:
494 // AddChild( new wxStringProperty( "Subprop 1", wxPG_LABEL, value.GetSubProp1() ) );
499 wxPGProperty( const wxString
& label
, const wxString
& name
);
502 Virtual destructor. It is customary for derived properties to implement this.
504 virtual ~wxPGProperty();
507 This virtual function is called after m_value has been set.
510 - If m_value was set to Null variant (ie. unspecified value), OnSetValue()
512 - m_value may be of any variant type. Typically properties internally support only
513 one variant type, and as such OnSetValue() provides a good opportunity to convert
514 supported values into internal type.
515 - Default implementation does nothing.
517 virtual void OnSetValue();
520 Override this to return something else than m_value as the value.
522 virtual wxVariant
DoGetValue() const { return m_value
; }
525 Implement this function in derived class to check the value.
526 Return true if it is ok. Returning false prevents property change events
530 - Default implementation always returns true.
532 virtual bool ValidateValue( wxVariant
& value
, wxPGValidationInfo
& validationInfo
) const;
535 Converts text into wxVariant value appropriate for this property.
538 On function entry this is the old value (should not be wxNullVariant
539 in normal cases). Translated value must be assigned back to it.
542 Text to be translated into variant.
545 If wxPG_FULL_VALUE is set, returns complete, storable value instead
546 of displayable one (they may be different).
547 If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
548 composite property string value (as generated by GetValueAsString()
549 called with this same flag).
551 @return Returns @true if resulting wxVariant value was different.
553 @remarks Default implementation converts semicolon delimited tokens into
554 child values. Only works for properties with children.
556 You might want to take into account that m_value is Null variant
557 if property value is unspecified (which is usually only case if
558 you explicitly enabled that sort behavior).
560 virtual bool StringToValue( wxVariant
& variant
, const wxString
& text
, int argFlags
= 0 ) const;
563 Converts integer (possibly a choice selection) into wxVariant value
564 appropriate for this property.
567 On function entry this is the old value (should not be wxNullVariant
568 in normal cases). Translated value must be assigned back to it.
571 Integer to be translated into variant.
574 If wxPG_FULL_VALUE is set, returns complete, storable value instead
577 @return Returns @true if resulting wxVariant value was different.
580 - If property is not supposed to use choice or spinctrl or other editor
581 with int-based value, it is not necessary to implement this method.
582 - Default implementation simply assign given int to m_value.
583 - If property uses choice control, and displays a dialog on some choice
584 items, then it is preferred to display that dialog in IntToValue
586 - You might want to take into account that m_value is Null variant if
587 property value is unspecified (which is usually only case if you
588 explicitly enabled that sort behavior).
590 virtual bool IntToValue( wxVariant
& value
, int number
, int argFlags
= 0 ) const;
593 Returns text representation of property's value.
596 If wxPG_FULL_VALUE is set, returns complete, storable string value instead of displayable.
597 If wxPG_EDITABLE_VALUE is set, returns string value that must be editable in textctrl.
598 If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to display
599 as a part of composite property string value.
602 Default implementation returns string composed from text representations of
605 virtual wxString
GetValueAsString( int argFlags
= 0 ) const;
608 Converts string to a value, and if successful, calls SetValue() on it.
609 Default behavior is to do nothing.
611 String to get the value from.
613 true if value was changed.
615 bool SetValueFromString( const wxString
& text
, int flags
= 0 );
618 Converts integer to a value, and if succesful, calls SetValue() on it.
619 Default behavior is to do nothing.
621 Int to get the value from.
623 If has wxPG_FULL_VALUE, then the value given is a actual value and not an index.
625 True if value was changed.
627 bool SetValueFromInt( long value
, int flags
= 0 );
630 Returns size of the custom painted image in front of property. This method
631 must be overridden to return non-default value if OnCustomPaint is to be
634 Normally -1, but can be an index to the property's list of items.
636 - Default behavior is to return wxSize(0,0), which means no image.
637 - Default image width or height is indicated with dimension -1.
638 - You can also return wxPG_DEFAULT_IMAGE_SIZE which equals wxSize(-1, -1).
640 virtual wxSize
OnMeasureImage( int item
= -1 ) const;
643 Events received by editor widgets are processed here. Note that editor class
644 usually processes most events. Some, such as button press events of
645 TextCtrlAndButton class, can be handled here. Also, if custom handling
646 for regular events is desired, then that can also be done (for example,
647 wxSystemColourProperty custom handles wxEVT_COMMAND_CHOICE_SELECTED
648 to display colour picker dialog when 'custom' selection is made).
650 If the event causes value to be changed, SetValueInEvent()
651 should be called to set the new value.
656 Should return true if any changes in value should be reported.
658 - If property uses choice control, and displays a dialog on some choice items,
659 then it is preferred to display that dialog in IntToValue instead of OnEvent.
661 virtual bool OnEvent( wxPropertyGrid
* propgrid
, wxWindow
* wnd_primary
, wxEvent
& event
);
664 Called after value of a child property has been altered. Note that this function is
665 usually called at the time that value of this property, or given child property, is
666 still pending for change.
668 Sample pseudo-code implementation:
671 void MyProperty::ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const
673 // Acquire reference to actual type of data stored in variant
674 // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros were used to create
675 // the variant class).
676 T& data = TFromVariant(thisValue);
678 // Copy childValue into data.
679 switch ( childIndex )
682 data.SetSubProp1( childvalue.GetLong() );
685 data.SetSubProp2( childvalue.GetString() );
693 Value of this property, that should be altered.
695 Index of child changed (you can use Item(childIndex) to get).
697 Value of the child property.
699 virtual void ChildChanged( wxVariant
& thisValue
, int childIndex
, wxVariant
& childValue
) const;
702 Returns pointer to an instance of used editor.
704 virtual const wxPGEditor
* DoGetEditorClass() const;
707 Returns pointer to the wxValidator that should be used
708 with the editor of this property (NULL for no validator).
709 Setting validator explicitly via SetPropertyValidator
712 In most situations, code like this should work well
713 (macros are used to maintain one actual validator instance,
714 so on the second call the function exits within the first
719 wxValidator* wxMyPropertyClass::DoGetValidator () const
721 WX_PG_DOGETVALIDATOR_ENTRY()
723 wxMyValidator* validator = new wxMyValidator(...);
725 ... prepare validator...
727 WX_PG_DOGETVALIDATOR_EXIT(validator)
733 You can get common filename validator by returning
734 wxFileProperty::GetClassValidator(). wxDirProperty,
735 for example, uses it.
737 virtual wxValidator
* DoGetValidator () const;
740 Override to paint an image in front of the property value text or drop-down
741 list item (but only if wxPGProperty::OnMeasureImage is overridden as well).
743 If property's OnMeasureImage() returns size that has height != 0 but less than
744 row height ( < 0 has special meanings), wxPropertyGrid calls this method to
745 draw a custom image in a limited area in front of the editor control or
746 value text/graphics, and if control has drop-down list, then the image is
747 drawn there as well (even in the case OnMeasureImage() returned higher height
750 NOTE: Following applies when OnMeasureImage() returns a "flexible" height (
751 using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable height items:
752 If rect.x is < 0, then this is a measure item call, which means that
753 dc is invalid and only thing that should be done is to set paintdata.m_drawnHeight
754 to the height of the image of item at index paintdata.m_choiceItem. This call
755 may be done even as often as once every drop-down popup show.
760 Box reserved for custom graphics. Includes surrounding rectangle, if any.
761 If x is < 0, then this is a measure item call (see above).
763 wxPGPaintData structure with much useful data about painted item.
768 const wxPropertyGrid* m_parent;
770 // Normally -1, otherwise index to drop-down list item that has to be drawn.
773 // Set to drawn width in OnCustomPaint (optional).
776 // In a measure item call, set this to the height of item at m_choiceItem index
782 - You can actually exceed rect width, but if you do so then paintdata.m_drawnWidth
783 must be set to the full width drawn in pixels.
784 - Due to technical reasons, rect's height will be default even if custom height
785 was reported during measure call.
786 - Brush is guaranteed to be default background colour. It has been already used to
787 clear the background of area being painted. It can be modified.
788 - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper colour) pen for
789 drawing framing rectangle. It can be changed as well.
791 @see GetValueAsString()
793 virtual void OnCustomPaint( wxDC
& dc
, const wxRect
& rect
, wxPGPaintData
& paintdata
);
796 Returns used wxPGCellRenderer instance for given property column (label=0, value=1).
798 Default implementation returns editor's renderer for all columns.
800 virtual wxPGCellRenderer
* GetCellRenderer( int column
) const;
803 Returns which choice is currently selected. Only applies to properties
806 Needs to reimplemented in derived class if property value does not
807 map directly to a choice. Integer as index, bool, and string usually do.
809 virtual int GetChoiceSelection() const;
812 Refresh values of child properties. Automatically called after value is set.
814 virtual void RefreshChildren();
817 Special handling for attributes of this property.
819 If returns false, then the attribute will be automatically stored in
822 Default implementation simply returns false.
824 virtual bool DoSetAttribute( const wxString
& name
, wxVariant
& value
);
827 Returns value of an attribute.
829 Override if custom handling of attributes is needed.
831 Default implementation simply return NULL variant.
833 virtual wxVariant
DoGetAttribute( const wxString
& name
) const;
836 Returns instance of a new wxPGEditorDialogAdapter instance, which is
837 used when user presses the (optional) button next to the editor control;
839 Default implementation returns NULL (ie. no action is generated when
842 virtual wxPGEditorDialogAdapter
* GetEditorDialog() const;
845 Returns wxPGCell of given column, NULL if none. If valid
846 object is returned, caller will gain its ownership.
848 wxPGCell
* AcquireCell( unsigned int column
)
850 if ( column
>= m_cells
.size() )
853 wxPGCell
* cell
= (wxPGCell
*) m_cells
[column
];
854 m_cells
[column
] = NULL
;
859 Append a new choice to property's list of choices.
862 Label for added choice.
865 Value for new choice. Do not specify if you wish this
866 to equal choice index.
869 Index to added choice.
871 int AddChoice( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
874 Properties which have private child properties should add them
875 with this function, called in their constructor.
877 void AddChild( wxPGProperty
* property
);
880 Adapts list variant into proper value using consecutive
881 ChildChanged() calls.
883 void AdaptListToValue( wxVariant
& list
, wxVariant
* value
) const;
886 Determines, recursively, if all children are not unspecified.
889 Assumes members in this wxVariant list as pending
892 bool AreAllChildrenSpecified( wxVariant
* pendingList
= NULL
) const;
895 Returns true if children of this property are component values (for instance,
896 points size, face name, and is_underlined are component values of a font).
898 bool AreChildrenComponents() const
900 if ( m_flags
& (wxPG_PROP_COMPOSED_VALUE
|wxPG_PROP_AGGREGATE
) )
907 Removes entry from property's wxPGChoices and editor control (if it is active).
909 If selected item is deleted, then the value is set to unspecified.
911 void DeleteChoice( int index
);
913 /** Deletes all child properties. */
916 /** Composes text from values of child properties. */
917 void GenerateComposedValue( wxString
& text
, int argFlags
= 0 ) const;
920 Returns property attribute value, null variant if not found.
922 wxVariant
GetAttribute( const wxString
& name
) const;
924 /** Returns named attribute, as string, if found. Otherwise defVal is returned.
926 wxString
GetAttribute( const wxString
& name
, const wxString
& defVal
) const;
928 /** Returns named attribute, as long, if found. Otherwise defVal is returned.
930 long GetAttributeAsLong( const wxString
& name
, long defVal
) const;
932 /** Returns named attribute, as double, if found. Otherwise defVal is returned.
934 double GetAttributeAsDouble( const wxString
& name
, double defVal
) const;
937 Returns attributes as list wxVariant.
939 wxVariant
GetAttributesAsList() const;
942 Returns editor used for given column. NULL for no editor.
944 const wxPGEditor
* GetColumnEditor( int column
) const
947 return GetEditorClass();
952 /** Returns property's base name (ie. parent's name is not added in any case) */
953 const wxString
& GetBaseName() const { return m_name
; }
956 Returns wxPGCell of given column, NULL if none. wxPGProperty
957 will retain ownership of the cell object.
959 wxPGCell
* GetCell( unsigned int column
) const
961 if ( column
>= m_cells
.size() )
964 return (wxPGCell
*) m_cells
[column
];
968 Returns number of child properties.
970 unsigned int GetChildCount() const;
973 Returns height of children, recursively, and
974 by taking expanded/collapsed status into account.
977 Line height. Pass result of GetGrid()->GetRowHeight() here.
980 Only used (internally) when finding property y-positions.
982 int GetChildrenHeight( int lh
, int iMax
= -1 ) const;
985 Returns read-only reference to property's list of choices.
987 const wxPGChoices
& GetChoices() const;
990 Returns client data (void*) of a property.
992 void* GetClientData() const;
994 /** Sets managed client object of a property.
996 wxClientData
*GetClientObject() const;
999 Returns property's default value. If property's value type is not
1000 a built-in one, and "DefaultValue" attribute is not defined, then
1001 this function usually returns Null variant.
1003 wxVariant
GetDefaultValue() const;
1005 /** Returns property's displayed text.
1007 wxString
GetDisplayedString() const
1009 return GetValueString(0);
1013 Returns wxPGEditor that will be used and created when
1014 property becomes selected. Returns more accurate value
1015 than DoGetEditorClass().
1017 const wxPGEditor
* GetEditorClass() const;
1019 /** Returns property grid where property lies. */
1020 wxPropertyGrid
* GetGrid() const;
1023 Returns owner wxPropertyGrid, but only if one is currently on a page
1024 displaying this property.
1026 wxPropertyGrid
* GetGridIfDisplayed() const;
1029 Returns property's help or description text.
1031 @see SetHelpString()
1033 const wxString
& GetHelpString() const;
1036 Returns position in parent's array.
1038 unsigned int GetIndexInParent() const;
1040 /** Returns property's label. */
1041 const wxString
& GetLabel() const { return m_label
; }
1044 Returns last visible child property, recursively.
1046 const wxPGProperty
* GetLastVisibleSubItem() const;
1049 Returns highest level non-category, non-root parent. Useful when you
1050 have nested properties with children.
1052 @remarks If immediate parent is root or category, this will return the
1055 wxPGProperty
* GetMainParent() const;
1057 /** Returns maximum allowed length of property's text value.
1059 int GetMaxLength() const
1061 return (int) m_maxLen
;
1064 /** Returns property's name with all (non-category, non-root) parents. */
1065 wxString
GetName() const;
1067 /** Return parent of property */
1068 wxPGProperty
* GetParent() const { return m_parent
; }
1071 Returns (direct) child property with given name (or NULL if not found).
1073 wxPGProperty
* GetPropertyByName( const wxString
& name
) const;
1075 /** Gets assignable version of property's validator. */
1076 wxValidator
* GetValidator() const;
1079 Returns property's value.
1081 wxVariant
GetValue() const
1083 return DoGetValue();
1087 Returns bitmap that appears next to value text. Only returns non-NULL
1088 bitmap if one was set with SetValueImage().
1090 wxBitmap
* GetValueImage() const;
1093 To acquire property's value as string, you should use this
1094 function (instead of GetValueAsString()), as it may produce
1095 more accurate value in future versions.
1097 @see GetValueAsString()
1099 wxString
GetValueString( int argFlags
= 0 ) const;
1102 Returns value type used by this property.
1104 wxString
GetValueType() const
1106 return m_value
.GetType();
1110 Returns coordinate to the top y of the property. Note that the
1111 position of scrollbars is not taken into account.
1116 Returns true if property has even one visible child.
1118 bool HasVisibleChildren() const;
1121 Hides or reveals the property.
1124 @true for hide, @false for reveal.
1127 By default changes are applied recursively. Set this parameter wxPG_DONT_RECURSE to prevent this.
1129 bool Hide( bool hide
, int flags
= wxPG_RECURSE
);
1132 Returns index of given child property. wxNOT_FOUND if
1133 given property is not child of this.
1135 int Index( const wxPGProperty
* p
) const;
1138 Inserts a new choice to property's list of choices.
1144 Insertion position. Use wxNOT_FOUND to append.
1147 Value for new choice. Do not specify if you wish this
1148 to equal choice index.
1150 int InsertChoice( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1153 Returns @true if this property is actually a wxPropertyCategory.
1155 bool IsCategory() const;
1158 Returns @true if property is enabled.
1160 bool IsEnabled() const;
1163 Returns @true if property has visible children.
1165 bool IsExpanded() const;
1168 Returns @true if this property is actually a wxRootProperty.
1170 bool IsRoot() const { return (m_parent
== NULL
); }
1173 Returns @true if candidateParent is some parent of this property.
1175 bool IsSomeParent( wxPGProperty
* candidateParent
) const;
1178 Returns true if property has editable wxTextCtrl when selected.
1180 @remarks Altough disabled properties do not displayed editor, they still
1181 return @true here as being disabled is considered a temporary
1182 condition (unlike being read-only or having limited editing enabled).
1184 bool IsTextEditable() const;
1187 Returns @true if property's value is considered unspecified. This
1188 usually means that value is Null variant.
1190 bool IsValueUnspecified() const;
1193 Returns true if all parents expanded.
1195 bool IsVisible() const;
1198 Returns child property at index i.
1200 wxPGProperty
* Item( size_t i
) const;
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 @remarks 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 @return Returns @true if value changed.
1218 bool PrepareValueForDialogEditing( wxPropertyGrid
* propgrid
);
1221 If property's editor is active, then update it's value.
1223 void RefreshEditor();
1226 Sets an attribute for this property.
1229 Text identifier of attribute. See @ref propgrid_property_attributes.
1234 @remarks Setting attribute's value to Null variant will simply remove it
1235 from property's set of attributes.
1237 void SetAttribute( const wxString
& name
, wxVariant value
);
1240 Sets editor for a property.
1243 For builtin editors, use wxPGEditor_X, where X is builtin editor's
1244 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list).
1246 For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
1248 void SetEditor( const wxPGEditor
* editor
);
1251 Sets editor for a property, by editor name.
1253 void SetEditor( const wxString
& editorName
);
1256 Sets cell information for given column.
1258 Note that the property takes ownership of given wxPGCell instance.
1260 void SetCell( int column
, wxPGCell
* cellObj
);
1263 Sets new set of choices for property.
1265 @remarks This operation clears the property value.
1267 bool SetChoices( wxPGChoices
& choices
);
1270 If property has choices and they are not yet exclusive, new such copy
1271 of them will be created.
1273 void SetChoicesExclusive();
1276 Sets client data (void*) of a property.
1278 @remarks This untyped client data has to be deleted manually.
1280 void SetClientData( void* clientData
);
1282 /** Returns client object of a property.
1284 void SetClientObject(wxClientData
* clientObject
);
1287 Sets selected choice and changes property value.
1289 Tries to retain value type, although currently if it is not string,
1290 then it is forced to integer.
1292 void SetChoiceSelection( int newValue
);
1295 Sets property's help string, which is shown, for example, in
1296 wxPropertyGridManager's description text box.
1298 void SetHelpString( const wxString
& helpString
);
1301 Sets property's label.
1303 @remarks Properties under same parent may have same labels. However,
1304 property names must still remain unique.
1306 void SetLabel( const wxString
& label
) { m_label
= label
; }
1309 Set max length of text in text editor.
1311 bool SetMaxLength( int maxLen
);
1314 Sets property's "is it modified?" flag. Affects children recursively.
1316 void SetModifiedStatus( bool modified
);
1319 Sets new (base) name for property.
1321 void SetName( const wxString
& newName
);
1323 /** Sets wxValidator for a property */
1324 void SetValidator( const wxValidator
& validator
);
1327 Call this to set value of the property. Unlike methods in wxPropertyGrid,
1328 this does not automatically update the display.
1331 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through
1332 validation process and send property change event.
1334 If you need to change property value in event, based on user input, use
1335 SetValueInEvent() instead.
1338 Pointer to list variant that contains child values. Used to indicate
1339 which children should be marked as modified. Usually you just use NULL.
1342 Use wxPG_SETVAL_REFRESH_EDITOR to update editor control, if it
1345 void SetValue( wxVariant value
, wxVariant
* pList
= NULL
, int flags
= 0 );
1348 Set wxBitmap in front of the value. This bitmap may be ignored
1349 by custom cell renderers.
1351 void SetValueImage( wxBitmap
& bmp
);
1354 Call this function in OnEvent(), OnButtonClick() etc. to change the
1355 property value based on user input.
1357 @remarks This method is const since it doesn't actually modify value, but posts
1358 given variant as pending value, stored in wxPropertyGrid.
1360 void SetValueInEvent( wxVariant value
) const;
1363 Sets property's value to unspecified (ie. Null variant).
1365 void SetValueToUnspecified();
1368 Call with @false in OnSetValue() to cancel value changes after all
1369 (ie. cancel @true returned by StringToValue() or IntToValue()).
1371 void SetWasModified( bool set
= true );
1374 Updates composed values of parent non-category properties, recursively.
1375 Returns topmost property updated.
1377 wxPGProperty
* UpdateParentValues();
1380 Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
1382 bool UsesAutoUnspecified() const;
1386 /** @class wxPGChoices
1388 Helper class for managing choices of wxPropertyGrid properties.
1389 Each entry can have label, value, bitmap, text colour, and background colour.
1391 @library{wxpropgrid}
1394 class WXDLLIMPEXP_PROPGRID wxPGChoices
1397 typedef long ValArrItem
;
1400 Default constructor.
1404 /** Copy constructor. */
1405 wxPGChoices( const wxPGChoices
& a
);
1408 wxPGChoices( const wxChar
** labels
, const long* values
= NULL
);
1411 wxPGChoices( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() );
1414 wxPGChoices( wxPGChoicesData
* data
);
1420 Adds to current. If did not have own copies, creates them now. If was empty,
1421 identical to set except that creates copies.
1423 void Add( const wxChar
** labels
, const ValArrItem
* values
= NULL
);
1425 /** Version that works with wxArrayString. */
1426 void Add( const wxArrayString
& arr
, const ValArrItem
* values
= NULL
);
1428 /** Version that works with wxArrayString and wxArrayInt. */
1429 void Add( const wxArrayString
& arr
, const wxArrayInt
& arrint
);
1431 /** Adds single item. */
1432 wxPGChoiceEntry
& Add( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1434 /** Adds a single item, with bitmap. */
1435 wxPGChoiceEntry
& Add( const wxString
& label
, const wxBitmap
& bitmap
,
1436 int value
= wxPG_INVALID_VALUE
);
1438 /** Adds a single item with full entry information. */
1439 wxPGChoiceEntry
& Add( const wxPGChoiceEntry
& entry
)
1441 return Insert(entry
, -1);
1444 /** Adds single item, sorted. */
1445 wxPGChoiceEntry
& AddAsSorted( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1448 Assigns data from another set of choices.
1450 void Assign( const wxPGChoices
& a
)
1452 AssignData(a
.m_data
);
1456 Assigns data from another set of choices.
1458 void AssignData( wxPGChoicesData
* data
);
1465 if ( m_data
!= wxPGChoicesEmptyData
)
1470 Returns labe of item.
1472 const wxString
& GetLabel( size_t ind
) const;
1475 Returns number of items.
1477 size_t GetCount () const;
1480 Returns value of item;
1482 int GetValue( size_t ind
) const;
1485 Returns array of values matching the given strings. Unmatching strings
1486 result in wxPG_INVALID_VALUE entry in array.
1488 wxArrayInt
GetValuesForStrings( const wxArrayString
& strings
) const;
1491 Returns array of indices matching given strings. Unmatching strings
1492 are added to 'unmatched', if not NULL.
1494 wxArrayInt
GetIndicesForStrings( const wxArrayString
& strings
,
1495 wxArrayString
* unmatched
= NULL
) const;
1498 Returns @true if item at given index has a valid value;
1500 bool HasValue( unsigned int i
) const;
1503 Returns index of item with given label.
1505 int Index( const wxString
& label
) const;
1508 Returns index of item with given value.
1510 int Index( int val
) const;
1513 Inserts single item.
1515 wxPGChoiceEntry
& Insert( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1518 Inserts a single item with full entry information.
1520 wxPGChoiceEntry
& Insert( const wxPGChoiceEntry
& entry
, int index
);
1523 Returns false if this is a constant empty set of choices,
1524 which should not be modified.
1528 return ( m_data
!= wxPGChoicesEmptyData
);
1532 Returns item at given index.
1534 const wxPGChoiceEntry
& Item( unsigned int i
) const
1537 return *m_data
->Item(i
);
1541 Returns item at given index.
1543 wxPGChoiceEntry
& Item( unsigned int i
)
1546 return *m_data
->Item(i
);
1550 Removes count items starting at position nIndex.
1552 void RemoveAt(size_t nIndex
, size_t count
= 1);
1555 Sets contents from lists of strings and values.
1557 void Set( const wxChar
** labels
, const long* values
= NULL
);
1560 Sets contents from lists of strings and values.
1562 void Set( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() );
1565 Creates exclusive copy of current choices.
1567 void SetExclusive();
1570 Returns array of choice labels.
1572 wxArrayString
GetLabels() const;
1574 void operator= (const wxPGChoices
& a
)
1576 AssignData(a
.m_data
);
1579 wxPGChoiceEntry
& operator[](unsigned int i
)
1584 const wxPGChoiceEntry
& operator[](unsigned int i
) const
1590 // -----------------------------------------------------------------------