1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxPGProperty
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 #define wxNullProperty ((wxPGProperty*)NULL)
14 @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers
16 wxPGProperty::SetAttribute() and wxPropertyGridInterface::SetPropertyAttribute()
17 accept one of these as attribute name argument.
19 You can use strings instead of constants.
20 However, some of these constants are redefined to use cached strings which
21 may reduce 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 /** When set, will be shown as 'greyed' text in property's value cell when
45 the actual displayed value is blank.
47 #define wxPG_ATTR_HINT wxS("Hint")
50 @deprecated Use "Hint" (wxPG_ATTR_INLINE_HELP) instead.
52 #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp")
54 /** Universal, wxArrayString. Set to enable auto-completion in any
55 wxTextCtrl-based property editor.
57 #define wxPG_ATTR_AUTOCOMPLETE wxS("AutoComplete")
59 /** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
60 Default value is False.
62 When set to True, bool property will use check box instead of a
63 combo box as its editor control. If you set this attribute
64 for a wxFlagsProperty, it is automatically applied to child
67 #define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox")
69 /** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
70 Default value is False.
72 Set to True for the bool property to cycle value on double click
73 (instead of showing the popup listbox). If you set this attribute
74 for a wxFlagsProperty, it is automatically applied to child
77 #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING wxS("UseDClickCycling")
79 /** wxFloatProperty (and similar) specific, int, default -1. Sets the (max) precision
80 used when floating point value is rendered as text. The default -1 means infinite
83 #define wxPG_FLOAT_PRECISION wxS("Precision")
85 /** The text will be echoed as asterisks (wxTE_PASSWORD will be passed to textctrl etc).
87 #define wxPG_STRING_PASSWORD wxS("Password")
89 /** Define base used by a wxUIntProperty. Valid constants are
90 wxPG_BASE_OCT, wxPG_BASE_DEC, wxPG_BASE_HEX and wxPG_BASE_HEXL
91 (lowercase characters).
93 #define wxPG_UINT_BASE wxS("Base")
95 /** Define prefix rendered to wxUIntProperty. Accepted constants
96 wxPG_PREFIX_NONE, wxPG_PREFIX_0x, and wxPG_PREFIX_DOLLAR_SIGN.
97 <b>Note:</b> Only wxPG_PREFIX_NONE works with Decimal and Octal
100 #define wxPG_UINT_PREFIX wxS("Prefix")
102 /** wxFileProperty/wxImageFileProperty specific, wxChar*, default is detected/varies.
103 Sets the wildcard used in the triggered wxFileDialog. Format is the
106 #define wxPG_FILE_WILDCARD wxS("Wildcard")
108 /** wxFileProperty/wxImageFileProperty specific, int, default 1.
109 When 0, only the file name is shown (i.e. drive and directory are hidden).
111 #define wxPG_FILE_SHOW_FULL_PATH wxS("ShowFullPath")
113 /** Specific to wxFileProperty and derived properties, wxString, default empty.
114 If set, then the filename is shown relative to the given path string.
116 #define wxPG_FILE_SHOW_RELATIVE_PATH wxS("ShowRelativePath")
118 /** Specific to wxFileProperty and derived properties, wxString, default is empty.
119 Sets the initial path of where to look for files.
121 #define wxPG_FILE_INITIAL_PATH wxS("InitialPath")
123 /** Specific to wxFileProperty and derivatives, wxString, default is empty.
124 Sets a specific title for the dir dialog.
126 #define wxPG_FILE_DIALOG_TITLE wxS("DialogTitle")
128 /** Specific to wxDirProperty, wxString, default is empty.
129 Sets a specific message for the dir dialog.
131 #define wxPG_DIR_DIALOG_MESSAGE wxS("DialogMessage")
133 /** Sets displayed date format for wxDateProperty.
135 #define wxPG_DATE_FORMAT wxS("DateFormat")
137 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
138 is wxDP_DEFAULT | wxDP_SHOWCENTURY. Using wxDP_ALLOWNONE will enable
139 better unspecified value support in the editor.
141 #define wxPG_DATE_PICKER_STYLE wxS("PickerStyle")
143 /** SpinCtrl editor, int or double. How much number changes when button is
144 pressed (or up/down on keybard).
146 #define wxPG_ATTR_SPINCTRL_STEP wxS("Step")
148 /** SpinCtrl editor, bool. If @true, value wraps at Min/Max.
150 #define wxPG_ATTR_SPINCTRL_WRAP wxS("Wrap")
152 /** SpinCtrl editor, bool. If @true, value can also by changed by moving
153 mouse when left mouse button is being pressed.
155 #define wxPG_ATTR_SPINCTRL_MOTIONSPIN wxS("MotionSpin")
157 /** wxMultiChoiceProperty, int. If 0, no user strings allowed. If 1, user strings
158 appear before list strings. If 2, user strings appear after list string.
160 #define wxPG_ATTR_MULTICHOICE_USERSTRINGMODE wxS("UserStringMode")
162 /** wxColourProperty and its kind, int, default 1. Setting this attribute to 0 hides custom
163 colour from property's list of choices.
165 #define wxPG_COLOUR_ALLOW_CUSTOM wxS("AllowCustom")
175 wxPGProperty is base class for all wxPropertyGrid properties. In
176 sections below we cover few related topics.
178 @li @ref pgproperty_properties
179 @li @ref pgproperty_creating
181 @section pgproperty_properties Supplied Ready-to-use Property Classes
183 Here is a list and short description of supplied fully-functional
184 property classes. They are located in either props.h or advprops.h.
186 @li @ref wxArrayStringProperty
187 @li @ref wxBoolProperty
188 @li @ref wxColourProperty
189 @li @ref wxCursorProperty
190 @li @ref wxDateProperty
191 @li @ref wxDirProperty
192 @li @ref wxEditEnumProperty
193 @li @ref wxEnumProperty
194 @li @ref wxFileProperty
195 @li @ref wxFlagsProperty
196 @li @ref wxFloatProperty
197 @li @ref wxFontProperty
198 @li @ref wxImageFileProperty
199 @li @ref wxIntProperty
200 @li @ref wxLongStringProperty
201 @li @ref wxMultiChoiceProperty
202 @li @ref wxPropertyCategory
203 @li @ref wxStringProperty
204 @li @ref wxSystemColourProperty
205 @li @ref wxUIntProperty
207 @subsection wxPropertyCategory
209 Not an actual property per se, but a header for a group of properties.
210 Regardless inherits from wxPGProperty.
212 @subsection wxStringProperty
214 Simple string property. wxPG_STRING_PASSWORD attribute may be used
215 to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl.
216 wxPG_ATTR_AUTOCOMPLETE attribute may be used to enable auto-completion
217 (use a wxArrayString value), and is also supported by any property that
218 happens to use a wxTextCtrl-based editor.
220 @remarks wxStringProperty has a special trait: if it has value of
221 "<composed>", and also has child properties, then its displayed
222 value becomes composition of child property values, similar as
223 with wxFontProperty, for instance.
225 @subsection wxIntProperty
227 Like wxStringProperty, but converts text to a signed long integer.
228 wxIntProperty seamlessly supports 64-bit integers (ie. wxLongLong).
229 To safely convert variant to integer, use code like this:
233 ll << property->GetValue();
236 wxLongLong ll = propertyGrid->GetPropertyValueAsLong(property);
239 @subsection wxUIntProperty
241 Like wxIntProperty, but displays value as unsigned int. To set
242 the prefix used globally, manipulate wxPG_UINT_PREFIX string attribute.
243 To set the globally used base, manipulate wxPG_UINT_BASE int
244 attribute. Regardless of current prefix, understands (hex) values starting
245 with both "0x" and "$".
246 Like wxIntProperty, wxUIntProperty seamlessly supports 64-bit unsigned
247 integers (ie. wxULongLong). Same wxVariant safety rules apply.
249 @subsection wxFloatProperty
251 Like wxStringProperty, but converts text to a double-precision floating point.
252 Default float-to-text precision is 6 decimals, but this can be changed
253 by modifying wxPG_FLOAT_PRECISION attribute.
255 @subsection wxBoolProperty
257 Represents a boolean value. wxChoice is used as editor control, by the
258 default. wxPG_BOOL_USE_CHECKBOX attribute can be set to true inorder to use
261 @subsection wxLongStringProperty
263 Like wxStringProperty, but has a button that triggers a small text editor
264 dialog. Note that in long string values, tabs are represented by "\t" and
267 To display custom dialog on button press, you can subclass
268 wxLongStringProperty and implement OnButtonClick, like this:
271 virtual bool OnButtonClick( wxPropertyGrid* propGrid, wxString& value )
273 wxSize dialogSize(...size of your dialog...);
275 wxPoint dlgPos = propGrid->GetGoodEditorDialogPosition(this,
278 // Create dialog dlg at dlgPos. Use value as initial string
282 if ( dlg.ShowModal() == wxID_OK )
284 value = dlg.GetStringValue);
291 Also, if you wish not to have line breaks and tabs translated to
292 escape sequences, then do following in constructor of your subclass:
295 m_flags |= wxPG_PROP_NO_ESCAPE;
298 @subsection wxDirProperty
300 Like wxLongStringProperty, but the button triggers dir selector instead.
301 Supported properties (all with string value): wxPG_DIR_DIALOG_MESSAGE.
303 @subsection wxFileProperty
305 Like wxLongStringProperty, but the button triggers file selector instead.
306 Default wildcard is "All files..." but this can be changed by setting
307 wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details).
308 Attribute wxPG_FILE_SHOW_FULL_PATH can be set to @false inorder to show
309 only the filename, not the entire path.
311 @subsection wxEnumProperty
313 Represents a single selection from a list of choices -
314 wxOwnerDrawnComboBox is used to edit the value.
316 @subsection wxFlagsProperty
318 Represents a bit set that fits in a long integer. wxBoolProperty sub-
319 properties are created for editing individual bits. Textctrl is created to
320 manually edit the flags as a text; a continous sequence of spaces, commas
321 and semicolons are considered as a flag id separator.
323 <b>Note:</b> When changing "choices" (ie. flag labels) of wxFlagsProperty,
324 you will need to use wxPGProperty::SetChoices() - otherwise they will not
325 get updated properly.
327 wxFlagsProperty supports the same attributes as wxBoolProperty.
329 @subsection wxArrayStringProperty
331 Allows editing of a list of strings in wxTextCtrl and in a separate dialog.
333 @subsection wxDateProperty
335 wxDateTime property. Default editor is DatePickerCtrl, altough TextCtrl
336 should work as well. wxPG_DATE_FORMAT attribute can be used to change
337 string wxDateTime::Format uses (altough default is recommended as it is
338 locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window
339 style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY).
340 Using wxDP_ALLOWNONE will enable better unspecified value support.
342 @subsection wxEditEnumProperty
344 Represents a string that can be freely edited or selected from list of choices -
345 custom combobox control is used to edit the value.
347 @subsection wxMultiChoiceProperty
349 Allows editing a multiple selection from a list of strings. This is
350 property is pretty much built around concept of wxMultiChoiceDialog.
351 It uses wxArrayString value.
353 @subsection wxImageFileProperty
355 Like wxFileProperty, but has thumbnail of the image in front of
356 the filename and autogenerates wildcard from available image handlers.
358 @subsection wxColourProperty
360 <b>Useful alternate editor:</b> Choice.
362 Represents wxColour. wxButton is used to trigger a colour picker dialog.
363 There are various sub-classing opportunities with this class. See
364 below in wxSystemColourProperty section for details.
366 @subsection wxFontProperty
368 Represents wxFont. Various sub-properties are used to edit individual
371 @subsection wxSystemColourProperty
373 Represents wxColour and a system colour index. wxChoice is used to edit
374 the value. Drop-down list has color images. Note that value type
375 is wxColourPropertyValue instead of wxColour (which wxColourProperty
379 class wxColourPropertyValue : public wxObject
382 // An integer value relating to the colour, and which exact
383 // meaning depends on the property with which it is used.
385 // For wxSystemColourProperty:
386 // Any of wxSYS_COLOUR_XXX, or any web-colour ( use wxPG_TO_WEB_COLOUR
387 // macro - (currently unsupported) ), or wxPG_COLOUR_CUSTOM.
390 // Resulting colour. Should be correct regardless of type.
395 in wxSystemColourProperty, and its derived class wxColourProperty, there
396 are various sub-classing features. To set basic list list of colour
397 names, call wxPGProperty::SetChoices().
400 // Override in derived class to customize how colours are translated
402 virtual wxString ColourToString( const wxColour& col, int index ) const;
404 // Returns index of entry that triggers colour picker dialog
405 // (default is last).
406 virtual int GetCustomColourIndex() const;
408 // Helper function to show the colour dialog
409 bool QueryColourFromUser( wxVariant& variant ) const;
411 // Returns colour for given choice.
412 // Default function returns wxSystemSettings::GetColour(index).
413 virtual wxColour GetColour( int index ) const;
416 @subsection wxCursorProperty
418 Represents a wxCursor. wxChoice is used to edit the value.
419 Drop-down list has cursor images under some (wxMSW) platforms.
422 @section pgproperty_creating Creating Custom Properties
424 New properties can be created by subclassing wxPGProperty or one
425 of the provided property classes, and (re)implementing necessary
426 member functions. Below, each virtual member function has ample
427 documentation about its purpose and any odd details which to keep
430 Here is a very simple 'template' code:
433 class MyProperty : public wxPGProperty
436 // Default constructor
439 // All arguments of this ctor must have a default value -
440 // use wxPG_LABEL for label and name
441 MyProperty( const wxString& label = wxPG_LABEL,
442 const wxString& name = wxPG_LABEL,
443 const wxString& value = wxEmptyString )
444 : wxPGProperty(label, name)
446 // m_value is wxVariant
450 virtual ~MyProperty() { }
452 const wxPGEditor* DoGetEditorClass() const
454 // Determines editor used by property.
455 // You can replace 'TextCtrl' below with any of these
456 // builtin-in property editor identifiers: Choice, ComboBox,
457 // TextCtrlAndButton, ChoiceAndButton, CheckBox, SpinCtrl,
459 return wxPGEditor_TextCtrl;
462 virtual wxString ValueToString( wxVariant& value,
465 // TODO: Convert given property value to a string
468 virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags )
470 // TODO: Adapt string to property value.
477 Since wxPGProperty derives from wxObject, you can use standard
478 DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS macros. From the
479 above example they were omitted for sake of simplicity, and besides,
480 they are only really needed if you need to use wxRTTI with your
483 You can change the 'value type' of a property by simply assigning different
484 type of variant with SetValue. <b>It is mandatory to implement
485 wxVariantData class for all data types used as property values.</b>
486 You can use macros declared in wxPropertyGrid headers. For instance:
490 // (If you need to have export declaration, use version of macros
491 // with _EXPORTED postfix)
492 WX_PG_DECLARE_VARIANT_DATA(MyDataClass)
495 WX_PG_IMPLEMENT_VARIANT_DATA(MyDataClass)
497 // Or, if you don't have valid == operator:
498 WX_PG_IMPLEMENT_VARIANT_DATA_DUMMY_EQ(MyDataClass)
504 class wxPGProperty
: public wxObject
507 typedef wxUint32 FlagType
;
516 Non-abstract property classes should have constructor of this style:
520 MyProperty( const wxString& label, const wxString& name, const T& value )
521 : wxPGProperty(label, name)
523 // Generally recommended way to set the initial value
524 // (as it should work in pretty much 100% of cases).
529 // If has private child properties then create them here.
531 // AddPrivateChild( new wxStringProperty("Subprop 1",
533 // value.GetSubProp1()));
538 wxPGProperty( const wxString
& label
, const wxString
& name
);
541 Virtual destructor. It is customary for derived properties to implement this.
543 virtual ~wxPGProperty();
546 This virtual function is called after m_value has been set.
549 - If m_value was set to Null variant (ie. unspecified value), OnSetValue()
551 - m_value may be of any variant type. Typically properties internally support only
552 one variant type, and as such OnSetValue() provides a good opportunity to convert
553 supported values into internal type.
554 - Default implementation does nothing.
556 virtual void OnSetValue();
559 Override this to return something else than m_value as the value.
561 virtual wxVariant
DoGetValue() const;
564 Implement this function in derived class to check the value.
565 Return @true if it is ok. Returning @false prevents property change events
569 - Default implementation always returns @true.
571 virtual bool ValidateValue( wxVariant
& value
, wxPGValidationInfo
& validationInfo
) const;
574 Converts text into wxVariant value appropriate for this property.
577 On function entry this is the old value (should not be wxNullVariant
578 in normal cases). Translated value must be assigned back to it.
581 Text to be translated into variant.
584 If wxPG_FULL_VALUE is set, returns complete, storable value instead
585 of displayable one (they may be different).
586 If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
587 composite property string value (as generated by ValueToString()
588 called with this same flag).
590 @return Returns @true if resulting wxVariant value was different.
592 @remarks Default implementation converts semicolon delimited tokens into
593 child values. Only works for properties with children.
595 You might want to take into account that m_value is Null variant
596 if property value is unspecified (which is usually only case if
597 you explicitly enabled that sort behavior).
599 virtual bool StringToValue( wxVariant
& variant
, const wxString
& text
, int argFlags
= 0 ) const;
602 Converts integer (possibly a choice selection) into wxVariant value
603 appropriate for this property.
606 On function entry this is the old value (should not be wxNullVariant
607 in normal cases). Translated value must be assigned back to it.
609 Integer to be translated into variant.
611 If wxPG_FULL_VALUE is set, returns complete, storable value instead
614 @return Returns @true if resulting wxVariant value was different.
617 - If property is not supposed to use choice or spinctrl or other editor
618 with int-based value, it is not necessary to implement this method.
619 - Default implementation simply assign given int to m_value.
620 - If property uses choice control, and displays a dialog on some choice
621 items, then it is preferred to display that dialog in IntToValue
623 - You might want to take into account that m_value is Mull variant if
624 property value is unspecified (which is usually only case if you
625 explicitly enabled that sort behavior).
627 virtual bool IntToValue( wxVariant
& variant
, int number
, int argFlags
= 0 ) const;
630 Converts property value into a text representation.
633 Value to be converted.
635 If 0 (default value), then displayed string is returned.
636 If wxPG_FULL_VALUE is set, returns complete, storable string value
637 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
638 string value that must be editable in textctrl.
639 If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
640 display as a part of string property's composite text representation.
642 @remarks Default implementation calls GenerateComposedValue().
644 virtual wxString
ValueToString( wxVariant
& value
, int argFlags
= 0 ) const;
647 Converts string to a value, and if successful, calls SetValue() on it.
648 Default behavior is to do nothing.
651 String to get the value from.
655 @return @true if value was changed.
657 bool SetValueFromString( const wxString
& text
, int flags
= 0 );
660 Converts integer to a value, and if succesful, calls SetValue() on it.
661 Default behavior is to do nothing.
664 Int to get the value from.
666 If has wxPG_FULL_VALUE, then the value given is a actual value and not an index.
668 @return @true if value was changed.
670 bool SetValueFromInt( long value
, int flags
= 0 );
673 Returns size of the custom painted image in front of property. This method
674 must be overridden to return non-default value if OnCustomPaint is to be
678 Normally -1, but can be an index to the property's list of items.
681 - Default behavior is to return wxSize(0,0), which means no image.
682 - Default image width or height is indicated with dimension -1.
683 - You can also return wxPG_DEFAULT_IMAGE_SIZE which equals wxSize(-1, -1).
685 virtual wxSize
OnMeasureImage( int item
= -1 ) const;
688 Events received by editor widgets are processed here. Note that editor class
689 usually processes most events. Some, such as button press events of
690 TextCtrlAndButton class, can be handled here. Also, if custom handling
691 for regular events is desired, then that can also be done (for example,
692 wxSystemColourProperty custom handles wxEVT_COMMAND_CHOICE_SELECTED
693 to display colour picker dialog when 'custom' selection is made).
695 If the event causes value to be changed, SetValueInEvent() should be called
696 to set the new value.
698 The parameter @a event is the associated wxEvent.
701 Should return @true if any changes in value should be reported.
704 - If property uses choice control, and displays a dialog on some choice items,
705 then it is preferred to display that dialog in IntToValue instead of OnEvent.
707 virtual bool OnEvent( wxPropertyGrid
* propgrid
, wxWindow
* wnd_primary
, wxEvent
& event
);
710 Called after value of a child property has been altered. Must return
711 new value of the whole property (after any alterations warrented by
714 Note that this function is usually called at the time that value of
715 this property, or given child property, is still pending for change,
716 and as such, result of GetValue() or m_value should not be relied
719 Sample pseudo-code implementation:
722 wxVariant MyProperty::ChildChanged( wxVariant& thisValue,
724 wxVariant& childValue ) const
726 // Acquire reference to actual type of data stored in variant
727 // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros
728 // were used to create the variant class).
729 T& data = TFromVariant(thisValue);
731 // Copy childValue into data.
732 switch ( childIndex )
735 data.SetSubProp1( childvalue.GetLong() );
738 data.SetSubProp2( childvalue.GetString() );
743 // Return altered data
749 Value of this property. Changed value should be returned (in
750 previous versions of wxPropertyGrid it was only necessary to
751 write value back to this argument).
753 Index of child changed (you can use Item(childIndex) to get
756 (Pending) value of the child property.
759 Modified value of the whole property.
761 virtual wxVariant
ChildChanged( wxVariant
& thisValue
,
763 wxVariant
& childValue
) const;
766 Returns pointer to an instance of used editor.
768 virtual const wxPGEditor
* DoGetEditorClass() const;
771 Returns pointer to the wxValidator that should be used
772 with the editor of this property (@NULL for no validator).
773 Setting validator explicitly via SetPropertyValidator
776 In most situations, code like this should work well
777 (macros are used to maintain one actual validator instance,
778 so on the second call the function exits within the first
783 wxValidator* wxMyPropertyClass::DoGetValidator () const
785 WX_PG_DOGETVALIDATOR_ENTRY()
787 wxMyValidator* validator = new wxMyValidator(...);
789 ... prepare validator...
791 WX_PG_DOGETVALIDATOR_EXIT(validator)
797 You can get common filename validator by returning
798 wxFileProperty::GetClassValidator(). wxDirProperty,
799 for example, uses it.
801 virtual wxValidator
* DoGetValidator () const;
804 Override to paint an image in front of the property value text or drop-down
805 list item (but only if wxPGProperty::OnMeasureImage is overridden as well).
807 If property's OnMeasureImage() returns size that has height != 0 but less than
808 row height ( < 0 has special meanings), wxPropertyGrid calls this method to
809 draw a custom image in a limited area in front of the editor control or
810 value text/graphics, and if control has drop-down list, then the image is
811 drawn there as well (even in the case OnMeasureImage() returned higher height
814 NOTE: Following applies when OnMeasureImage() returns a "flexible" height (
815 using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable height items:
816 If rect.x is < 0, then this is a measure item call, which means that
817 dc is invalid and only thing that should be done is to set paintdata.m_drawnHeight
818 to the height of the image of item at index paintdata.m_choiceItem. This call
819 may be done even as often as once every drop-down popup show.
824 Box reserved for custom graphics. Includes surrounding rectangle, if any.
825 If x is < 0, then this is a measure item call (see above).
827 wxPGPaintData structure with much useful data about painted item.
832 const wxPropertyGrid* m_parent;
834 // Normally -1, otherwise index to drop-down list item that has to be drawn.
837 // Set to drawn width in OnCustomPaint (optional).
840 // In a measure item call, set this to the height of item at m_choiceItem index
846 - You can actually exceed rect width, but if you do so then paintdata.m_drawnWidth
847 must be set to the full width drawn in pixels.
848 - Due to technical reasons, rect's height will be default even if custom height
849 was reported during measure call.
850 - Brush is guaranteed to be default background colour. It has been already used to
851 clear the background of area being painted. It can be modified.
852 - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper colour) pen for
853 drawing framing rectangle. It can be changed as well.
857 virtual void OnCustomPaint( wxDC
& dc
, const wxRect
& rect
, wxPGPaintData
& paintdata
);
860 Returns used wxPGCellRenderer instance for given property column (label=0, value=1).
862 Default implementation returns editor's renderer for all columns.
864 virtual wxPGCellRenderer
* GetCellRenderer( int column
) const;
867 Returns which choice is currently selected. Only applies to properties
870 Needs to reimplemented in derived class if property value does not
871 map directly to a choice. Integer as index, bool, and string usually do.
873 virtual int GetChoiceSelection() const;
876 Refresh values of child properties. Automatically called after value is set.
878 virtual void RefreshChildren();
881 Special handling for attributes of this property.
883 If returns @false, then the attribute will be automatically stored in
886 Default implementation simply returns @false.
888 virtual bool DoSetAttribute( const wxString
& name
, wxVariant
& value
);
891 Returns value of an attribute.
893 Override if custom handling of attributes is needed.
895 Default implementation simply return @NULL variant.
897 virtual wxVariant
DoGetAttribute( const wxString
& name
) const;
900 Returns instance of a new wxPGEditorDialogAdapter instance, which is
901 used when user presses the (optional) button next to the editor control;
903 Default implementation returns @NULL (ie. no action is generated when
906 virtual wxPGEditorDialogAdapter
* GetEditorDialog() const;
909 Called whenever validation has failed with given pending value.
911 @remarks If you implement this in your custom property class, please
912 remember to call the baser implementation as well, since they
913 may use it to revert property into pre-change state.
915 virtual void OnValidationFailure( wxVariant
& pendingValue
);
918 Append a new choice to property's list of choices.
921 Label for added choice.
924 Value for new choice. Do not specify if you wish this
925 to equal choice index.
928 Index to added choice.
930 int AddChoice( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
933 Adds a private child property.
935 @deprecated Use AddPrivateChild() instead.
937 @see AddPrivateChild()
939 wxDEPRECATED( void AddChild( wxPGProperty
* prop
) );
942 Adds a private child property. If you use this instead of
943 wxPropertyGridInterface::Insert() or
944 wxPropertyGridInterface::AppendIn(), then property's parental
945 type will automatically be set up to wxPG_PROP_AGGREGATE. In other
946 words, all properties of this property will become private.
948 void AddPrivateChild( wxPGProperty
* prop
);
951 Adapts list variant into proper value using consecutive
952 ChildChanged() calls.
954 void AdaptListToValue( wxVariant
& list
, wxVariant
* value
) const;
957 Use this member function to add independent (ie. regular) children to
960 @return Appended childProperty.
962 @remarks wxPropertyGrid is not automatically refreshed by this
965 @see InsertChild(), AddPrivateChild()
967 wxPGProperty
* AppendChild( wxPGProperty
* childProperty
);
970 Determines, recursively, if all children are not unspecified.
973 Assumes members in this wxVariant list as pending
976 bool AreAllChildrenSpecified( wxVariant
* pendingList
= NULL
) const;
979 Returns @true if children of this property are component values (for instance,
980 points size, face name, and is_underlined are component values of a font).
982 bool AreChildrenComponents() const;
985 Deletes children of the property.
987 void DeleteChildren();
990 Removes entry from property's wxPGChoices and editor control (if it is active).
992 If selected item is deleted, then the value is set to unspecified.
994 void DeleteChoice( int index
);
996 /** Deletes all child properties. */
1000 Composes text from values of child properties.
1002 wxString
GenerateComposedValue() const;
1005 Returns property attribute value, null variant if not found.
1007 wxVariant
GetAttribute( const wxString
& name
) const;
1009 /** Returns named attribute, as string, if found. Otherwise defVal is returned.
1011 wxString
GetAttribute( const wxString
& name
, const wxString
& defVal
) const;
1013 /** Returns named attribute, as long, if found. Otherwise defVal is returned.
1015 long GetAttributeAsLong( const wxString
& name
, long defVal
) const;
1017 /** Returns named attribute, as double, if found. Otherwise defVal is returned.
1019 double GetAttributeAsDouble( const wxString
& name
, double defVal
) const;
1022 Returns attributes as list wxVariant.
1024 wxVariant
GetAttributesAsList() const;
1027 Returns editor used for given column. @NULL for no editor.
1029 const wxPGEditor
* GetColumnEditor( int column
) const;
1031 /** Returns property's base name (ie. parent's name is not added in any case) */
1032 const wxString
& GetBaseName() const;
1035 Returns wxPGCell of given column.
1037 @remarks const version of this member function returns 'default'
1038 wxPGCell object if the property itself didn't hold
1041 const wxPGCell
& GetCell( unsigned int column
) const;
1044 Returns wxPGCell of given column, creating one if necessary.
1046 wxPGCell
& GetCell( unsigned int column
);
1049 Returns wxPGCell of given column, creating one if necessary.
1051 wxPGCell
& GetOrCreateCell( unsigned int column
);
1054 Returns number of child properties.
1056 unsigned int GetChildCount() const;
1059 Returns height of children, recursively, and
1060 by taking expanded/collapsed status into account.
1063 Line height. Pass result of GetGrid()->GetRowHeight() here.
1066 Only used (internally) when finding property y-positions.
1068 int GetChildrenHeight( int lh
, int iMax
= -1 ) const;
1071 Returns read-only reference to property's list of choices.
1073 const wxPGChoices
& GetChoices() const;
1076 Returns client data (void*) of a property.
1078 void* GetClientData() const;
1080 /** Sets managed client object of a property.
1082 wxClientData
*GetClientObject() const;
1085 Returns property's default value. If property's value type is not
1086 a built-in one, and "DefaultValue" attribute is not defined, then
1087 this function usually returns Null variant.
1089 wxVariant
GetDefaultValue() const;
1091 /** Returns property's displayed text.
1093 wxString
GetDisplayedString() const;
1096 Returns wxPGEditor that will be used and created when
1097 property becomes selected. Returns more accurate value
1098 than DoGetEditorClass().
1100 const wxPGEditor
* GetEditorClass() const;
1102 /** Returns property grid where property lies. */
1103 wxPropertyGrid
* GetGrid() const;
1106 Returns owner wxPropertyGrid, but only if one is currently on a page
1107 displaying this property.
1109 wxPropertyGrid
* GetGridIfDisplayed() const;
1112 Returns property's help or description text.
1114 @see SetHelpString()
1116 const wxString
& GetHelpString() const;
1119 Returns position in parent's array.
1121 unsigned int GetIndexInParent() const;
1123 /** Returns property's label. */
1124 const wxString
& GetLabel() const;
1127 Returns last visible child property, recursively.
1129 const wxPGProperty
* GetLastVisibleSubItem() const;
1132 Returns highest level non-category, non-root parent. Useful when you
1133 have nested properties with children.
1135 @remarks If immediate parent is root or category, this will return the
1138 wxPGProperty
* GetMainParent() const;
1140 /** Returns maximum allowed length of property's text value.
1142 int GetMaxLength() const;
1144 /** Returns property's name with all (non-category, non-root) parents. */
1145 wxString
GetName() const;
1147 /** Return parent of property */
1148 wxPGProperty
* GetParent() const;
1151 Returns (direct) child property with given name (or @NULL if not found).
1153 wxPGProperty
* GetPropertyByName( const wxString
& name
) const;
1155 /** Gets assignable version of property's validator. */
1156 wxValidator
* GetValidator() const;
1159 Returns property's value.
1161 wxVariant
GetValue() const;
1164 Returns bitmap that appears next to value text. Only returns non-@NULL
1165 bitmap if one was set with SetValueImage().
1167 wxBitmap
* GetValueImage() const;
1169 /** Returns text representation of property's value.
1172 If 0 (default value), then displayed string is returned.
1173 If wxPG_FULL_VALUE is set, returns complete, storable string value
1174 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
1175 string value that must be editable in textctrl. If
1176 wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
1177 display as a part of string property's composite text
1180 @remarks In older versions, this function used to be overridden to convert
1181 property's value into a string representation. This function is
1182 now handled by ValueToString(), and overriding this function now
1183 will result in run-time assertion failure.
1185 virtual wxString
GetValueAsString( int argFlags
= 0 ) const;
1187 /** Synonymous to GetValueAsString().
1189 @deprecated Use GetValueAsString() instead.
1191 @see GetValueAsString()
1193 wxDEPRECATED( wxString
GetValueString( int argFlags
= 0 ) const );
1196 Returns value type used by this property.
1198 wxString
GetValueType() const;
1201 Returns coordinate to the top y of the property. Note that the
1202 position of scrollbars is not taken into account.
1207 Returns @true if property has even one visible child.
1209 bool HasVisibleChildren() const;
1212 Hides or reveals the property.
1215 @true for hide, @false for reveal.
1218 By default changes are applied recursively. Set this parameter wxPG_DONT_RECURSE to prevent this.
1220 bool Hide( bool hide
, int flags
= wxPG_RECURSE
);
1223 Returns index of given child property. wxNOT_FOUND if
1224 given property is not child of this.
1226 int Index( const wxPGProperty
* p
) const;
1229 Use this member function to add independent (ie. regular) children to
1232 @return Inserted childProperty.
1234 @remarks wxPropertyGrid is not automatically refreshed by this
1237 @see AppendChild(), AddPrivateChild()
1239 wxPGProperty
* InsertChild( int index
, wxPGProperty
* childProperty
);
1242 Inserts a new choice to property's list of choices.
1248 Insertion position. Use wxNOT_FOUND to append.
1251 Value for new choice. Do not specify if you wish this
1252 to equal choice index.
1254 int InsertChoice( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1257 Returns @true if this property is actually a wxPropertyCategory.
1259 bool IsCategory() const;
1262 Returns @true if property is enabled.
1264 bool IsEnabled() const;
1267 Returns @true if property has visible children.
1269 bool IsExpanded() const;
1272 Returns @true if this property is actually a wxRootProperty.
1274 bool IsRoot() const;
1277 Returns @true if candidateParent is some parent of this property.
1279 bool IsSomeParent( wxPGProperty
* candidateParent
) const;
1282 Returns true if property has editable wxTextCtrl when selected.
1284 @remarks Altough disabled properties do not displayed editor, they still
1285 return @true here as being disabled is considered a temporary
1286 condition (unlike being read-only or having limited editing enabled).
1288 bool IsTextEditable() const;
1291 Returns @true if property's value is considered unspecified. This
1292 usually means that value is Null variant.
1294 bool IsValueUnspecified() const;
1297 Returns true if all parents expanded.
1299 bool IsVisible() const;
1302 Returns child property at index i.
1304 wxPGProperty
* Item( unsigned int i
) const;
1307 If property's editor is active, then update it's value.
1309 void RefreshEditor();
1312 Sets an attribute for this property.
1315 Text identifier of attribute. See @ref propgrid_property_attributes.
1320 @remarks Setting attribute's value to Null variant will simply remove it
1321 from property's set of attributes.
1323 void SetAttribute( const wxString
& name
, wxVariant value
);
1326 Sets property's background colour.
1329 Background colour to use.
1332 Default is wxPG_RECURSE which causes colour to be set recursively.
1333 Omit this flag to only set colour for the property in question
1334 and not any of its children.
1336 void SetBackgroundColour( const wxColour
& colour
,
1337 int flags
= wxPG_RECURSE
);
1340 Sets editor for a property.
1343 For builtin editors, use wxPGEditor_X, where X is builtin editor's
1344 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list).
1346 For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
1348 void SetEditor( const wxPGEditor
* editor
);
1351 Sets editor for a property, by editor name.
1353 void SetEditor( const wxString
& editorName
);
1356 Sets cell information for given column.
1358 void SetCell( int column
, const wxPGCell
& cell
);
1361 Sets new set of choices for property.
1363 @remarks This operation clears the property value.
1365 bool SetChoices( wxPGChoices
& choices
);
1368 Sets client data (void*) of a property.
1370 @remarks This untyped client data has to be deleted manually.
1372 void SetClientData( void* clientData
);
1374 /** Returns client object of a property.
1376 void SetClientObject(wxClientData
* clientObject
);
1379 Sets selected choice and changes property value.
1381 Tries to retain value type, although currently if it is not string,
1382 then it is forced to integer.
1384 void SetChoiceSelection( int newValue
);
1386 /** Set default value of a property. Synonymous to
1389 SetAttribute("DefaultValue", value);
1392 void SetDefaultValue( wxVariant
& value
);
1395 Sets property's help string, which is shown, for example, in
1396 wxPropertyGridManager's description text box.
1398 void SetHelpString( const wxString
& helpString
);
1401 Sets property's label.
1403 @remarks Properties under same parent may have same labels. However,
1404 property names must still remain unique.
1406 void SetLabel( const wxString
& label
);
1409 Set max length of text in text editor.
1411 bool SetMaxLength( int maxLen
);
1414 Sets property's "is it modified?" flag. Affects children recursively.
1416 void SetModifiedStatus( bool modified
);
1419 Sets new (base) name for property.
1421 void SetName( const wxString
& newName
);
1424 Changes what sort of parent this property is for its children.
1427 Use one of the following values: wxPG_PROP_MISC_PARENT (for generic
1428 parents), wxPG_PROP_CATEGORY (for categories), or
1429 wxPG_PROP_AGGREGATE (for derived property classes with private
1432 @remarks You generally do not need to call this function.
1434 void SetParentalType( int flag
);
1437 Sets property's text colour.
1443 Default is wxPG_RECURSE which causes colour to be set recursively.
1444 Omit this flag to only set colour for the property in question
1445 and not any of its children.
1447 void SetTextColour( const wxColour
& colour
,
1448 int flags
= wxPG_RECURSE
);
1450 /** Sets wxValidator for a property */
1451 void SetValidator( const wxValidator
& validator
);
1454 Call this to set value of the property. Unlike methods in wxPropertyGrid,
1455 this does not automatically update the display.
1458 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through
1459 validation process and send property change event.
1461 If you need to change property value in event, based on user input, use
1462 SetValueInEvent() instead.
1467 Pointer to list variant that contains child values. Used to indicate
1468 which children should be marked as modified. Usually you just use @NULL.
1470 wxPG_SETVAL_REFRESH_EDITOR is set by default, to refresh editor
1471 and redraw properties.
1473 void SetValue( wxVariant value
, wxVariant
* pList
= NULL
,
1474 int flags
= wxPG_SETVAL_REFRESH_EDITOR
);
1477 Set wxBitmap in front of the value. This bitmap may be ignored
1478 by custom cell renderers.
1480 void SetValueImage( wxBitmap
& bmp
);
1483 Call this function in OnEvent(), OnButtonClick() etc. to change the
1484 property value based on user input.
1486 @remarks This method is const since it doesn't actually modify value, but posts
1487 given variant as pending value, stored in wxPropertyGrid.
1489 void SetValueInEvent( wxVariant value
) const;
1492 Sets property's value to unspecified (ie. Null variant).
1494 void SetValueToUnspecified();
1497 Call with @false in OnSetValue() to cancel value changes after all
1498 (ie. cancel @true returned by StringToValue() or IntToValue()).
1500 void SetWasModified( bool set
= true );
1503 Updates composed values of parent non-category properties, recursively.
1504 Returns topmost property updated.
1506 wxPGProperty
* UpdateParentValues();
1509 Returns @true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
1511 bool UsesAutoUnspecified() const;
1518 Base class for wxPropertyGrid cell information.
1520 @library{wxpropgrid}
1523 class wxPGCell
: public wxObject
1527 wxPGCell(const wxPGCell
& other
);
1528 wxPGCell( const wxString
& text
,
1529 const wxBitmap
& bitmap
= wxNullBitmap
,
1530 const wxColour
& fgCol
= wxNullColour
,
1531 const wxColour
& bgCol
= wxNullColour
);
1533 virtual ~wxPGCell();
1535 const wxPGCellData
* GetData() const;
1538 Returns @true if this cell has custom text stored within.
1540 bool HasText() const;
1543 Merges valid data from srcCell into this.
1545 void MergeFrom( const wxPGCell
& srcCell
);
1547 void SetText( const wxString
& text
);
1548 void SetBitmap( const wxBitmap
& bitmap
);
1549 void SetFgCol( const wxColour
& col
);
1552 Sets font of the cell.
1554 @remarks Because wxPropertyGrid does not support rows of
1555 different height, it makes little sense to change
1556 size of the font. Therefore it is recommended
1557 to use return value of wxPropertyGrid::GetFont()
1558 or wxPropertyGrid::GetCaptionFont() as a basis
1559 for the font that, after modifications, is passed
1560 to this member function.
1562 void SetFont( const wxFont
& font
);
1564 void SetBgCol( const wxColour
& col
);
1566 const wxString
& GetText() const;
1567 const wxBitmap
& GetBitmap() const;
1568 const wxColour
& GetFgCol() const;
1571 Returns font of the cell. If no specific font is set for this
1572 cell, then the font will be invalid.
1574 const wxFont
& GetFont() const;
1576 const wxColour
& GetBgCol() const;
1578 wxPGCell
& operator=( const wxPGCell
& other
);
1585 Helper class for managing choices of wxPropertyGrid properties.
1586 Each entry can have label, value, bitmap, text colour, and background
1589 wxPGChoices uses reference counting, similar to other wxWidgets classes.
1590 This means that assignment operator and copy constructor only copy the
1591 reference and not the actual data. Use Copy() member function to create a
1594 @remarks If you do not specify value for entry, index is used.
1596 @library{wxpropgrid}
1602 typedef long ValArrItem
;
1605 Default constructor.
1610 Copy constructor, uses reference counting. To create a real copy,
1611 use Copy() member function instead.
1613 wxPGChoices( const wxPGChoices
& a
);
1616 wxPGChoices( const wxChar
** labels
, const long* values
= NULL
);
1619 wxPGChoices( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() );
1622 wxPGChoices( wxPGChoicesData
* data
);
1628 Adds to current. If did not have own copies, creates them now. If was empty,
1629 identical to set except that creates copies.
1631 void Add( const wxChar
** labels
, const ValArrItem
* values
= NULL
);
1633 /** Version that works with wxArrayString. */
1634 void Add( const wxArrayString
& arr
, const ValArrItem
* values
= NULL
);
1636 /** Version that works with wxArrayString and wxArrayInt. */
1637 void Add( const wxArrayString
& arr
, const wxArrayInt
& arrint
);
1639 /** Adds single item. */
1640 wxPGChoiceEntry
& Add( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1642 /** Adds a single item, with bitmap. */
1643 wxPGChoiceEntry
& Add( const wxString
& label
, const wxBitmap
& bitmap
,
1644 int value
= wxPG_INVALID_VALUE
);
1646 /** Adds a single item with full entry information. */
1647 wxPGChoiceEntry
& Add( const wxPGChoiceEntry
& entry
);
1649 /** Adds single item, sorted. */
1650 wxPGChoiceEntry
& AddAsSorted( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1653 Assigns choices data, using reference counting. To create a real copy,
1654 use Copy() member function instead.
1656 void Assign( const wxPGChoices
& a
);
1659 Assigns data from another set of choices.
1661 void AssignData( wxPGChoicesData
* data
);
1669 Returns a real copy of the choices.
1671 wxPGChoices
Copy() const;
1674 Returns labe of item.
1676 const wxString
& GetLabel( unsigned int ind
) const;
1679 Returns number of items.
1681 unsigned int GetCount() const;
1684 Returns value of item;
1686 int GetValue( unsigned int ind
) const;
1689 Returns array of values matching the given strings. Unmatching strings
1690 result in wxPG_INVALID_VALUE entry in array.
1692 wxArrayInt
GetValuesForStrings( const wxArrayString
& strings
) const;
1695 Returns array of indices matching given strings. Unmatching strings
1696 are added to 'unmatched', if not @NULL.
1698 wxArrayInt
GetIndicesForStrings( const wxArrayString
& strings
,
1699 wxArrayString
* unmatched
= NULL
) const;
1701 /** Returns property at given virtual y coordinate.
1703 wxPGProperty
* GetItemAtY( unsigned int y
) const;
1706 Returns @true if item at given index has a valid value;
1708 bool HasValue( unsigned int i
) const;
1711 Returns index of item with given label.
1713 int Index( const wxString
& label
) const;
1716 Returns index of item with given value.
1718 int Index( int val
) const;
1721 Inserts single item.
1723 wxPGChoiceEntry
& Insert( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1726 Inserts a single item with full entry information.
1728 wxPGChoiceEntry
& Insert( const wxPGChoiceEntry
& entry
, int index
);
1731 Returns @false if this is a constant empty set of choices,
1732 which should not be modified.
1737 Returns item at given index.
1739 const wxPGChoiceEntry
& Item( unsigned int i
) const;
1742 Returns item at given index.
1744 wxPGChoiceEntry
& Item( unsigned int i
);
1747 Removes count items starting at position nIndex.
1749 void RemoveAt(size_t nIndex
, size_t count
= 1);
1752 Sets contents from lists of strings and values.
1754 void Set( const wxChar
** labels
, const long* values
= NULL
);
1757 Sets contents from lists of strings and values.
1759 void Set( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() );
1762 Creates exclusive copy of current choices.
1764 void AllocExclusive();
1767 Returns array of choice labels.
1769 wxArrayString
GetLabels() const;
1771 void operator= (const wxPGChoices
& a
);
1773 wxPGChoiceEntry
& operator[](unsigned int i
);
1774 const wxPGChoiceEntry
& operator[](unsigned int i
) const;
1777 // -----------------------------------------------------------------------