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.
191 * wxStringProperty has a special trait: if it has value of "<composed>",
192 and also has child properties, then its displayed value becomes
193 composition of child property values, similar as with wxFontProperty,
196 @subsection wxIntProperty
198 Like wxStringProperty, but converts text to a signed long integer.
199 wxIntProperty seamlessly supports 64-bit integers (ie. wxLongLong).
200 To safely convert variant to integer, use code like this:
204 ll << property->GetValue();
207 wxLongLong ll = propertyGrid->GetPropertyValueAsLong(property);
210 @subsection wxUIntProperty
212 Like wxIntProperty, but displays value as unsigned int. To set
213 the prefix used globally, manipulate wxPG_UINT_PREFIX string attribute.
214 To set the globally used base, manipulate wxPG_UINT_BASE int
215 attribute. Regardless of current prefix, understands (hex) values starting
216 with both "0x" and "$".
217 Like wxIntProperty, wxUIntProperty seamlessly supports 64-bit unsigned
218 integers (ie. wxULongLong). Same wxVariant safety rules apply.
220 @subsection wxFloatProperty
222 Like wxStringProperty, but converts text to a double-precision floating point.
223 Default float-to-text precision is 6 decimals, but this can be changed
224 by modifying wxPG_FLOAT_PRECISION attribute.
226 @subsection wxBoolProperty
228 Represents a boolean value. wxChoice is used as editor control, by the
229 default. wxPG_BOOL_USE_CHECKBOX attribute can be set to true inorder to use
232 @subsection wxLongStringProperty
234 Like wxStringProperty, but has a button that triggers a small text editor
235 dialog. Note that in long string values, tabs are represented by "\t" and
238 @subsection wxDirProperty
240 Like wxLongStringProperty, but the button triggers dir selector instead.
241 Supported properties (all with string value): wxPG_DIR_DIALOG_MESSAGE.
243 @subsection wxFileProperty
245 Like wxLongStringProperty, but the button triggers file selector instead.
246 Default wildcard is "All files..." but this can be changed by setting
247 wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details).
248 Attribute wxPG_FILE_SHOW_FULL_PATH can be set to false inorder to show
249 only the filename, not the entire path.
251 @subsection wxEnumProperty
253 Represents a single selection from a list of choices -
254 wxOwnerDrawnComboBox is used to edit the value.
256 @subsection wxFlagsProperty
258 Represents a bit set that fits in a long integer. wxBoolProperty sub-properties
259 are created for editing individual bits. Textctrl is created to manually edit
260 the flags as a text; a continous sequence of spaces, commas and semicolons
261 is considered as a flag id separator.
262 <b>Note: </b> When changing "choices" (ie. flag labels) of wxFlagsProperty, you
263 will need to use wxPGProperty::SetChoices() - otherwise they will not get updated
266 @subsection wxArrayStringProperty
268 Allows editing of a list of strings in wxTextCtrl and in a separate dialog.
270 @subsection wxDateProperty
272 wxDateTime property. Default editor is DatePickerCtrl, altough TextCtrl
273 should work as well. wxPG_DATE_FORMAT attribute can be used to change
274 string wxDateTime::Format uses (altough default is recommended as it is
275 locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window
276 style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY).
278 @subsection wxEditEnumProperty
280 Represents a string that can be freely edited or selected from list of choices -
281 custom combobox control is used to edit the value.
283 @subsection wxMultiChoiceProperty
285 Allows editing a multiple selection from a list of strings. This is
286 property is pretty much built around concept of wxMultiChoiceDialog.
287 It uses wxArrayString value.
289 @subsection wxImageFileProperty
291 Like wxFileProperty, but has thumbnail of the image in front of
292 the filename and autogenerates wildcard from available image handlers.
294 @subsection wxColourProperty
296 <b>Useful alternate editor:</b> Choice.
298 Represents wxColour. wxButton is used to trigger a colour picker dialog.
300 @subsection wxFontProperty
302 Represents wxFont. Various sub-properties are used to edit individual
305 @subsection wxSystemColourProperty
307 Represents wxColour and a system colour index. wxChoice is used to edit
308 the value. Drop-down list has color images. Note that value type
309 is wxColourPropertyValue instead of wxColour.
311 class wxColourPropertyValue : public wxObject
314 // An integer value relating to the colour, and which exact
315 // meaning depends on the property with which it is used.
317 // For wxSystemColourProperty:
318 // Any of wxSYS_COLOUR_XXX, or any web-colour ( use wxPG_TO_WEB_COLOUR
319 // macro - (currently unsupported) ), or wxPG_COLOUR_CUSTOM.
322 // Resulting colour. Should be correct regardless of type.
327 @subsection wxCursorProperty
329 Represents a wxCursor. wxChoice is used to edit the value.
330 Drop-down list has cursor images under some (wxMSW) platforms.
333 @section pgproperty_creating Creating Custom Properties
335 New properties can be created by subclassing wxPGProperty or one
336 of the provided property classes, and (re)implementing necessary
337 member functions. Below, each virtual member function has ample
338 documentation about its purpose and any odd details which to keep
341 Here is a very simple 'template' code:
344 class MyProperty : public wxPGProperty
347 // All arguments of ctor must have a default value -
348 // use wxPG_LABEL for label and name
349 MyProperty( const wxString& label = wxPG_LABEL,
350 const wxString& name = wxPG_LABEL,
351 const wxString& value = wxEmptyString )
353 // m_value is wxVariant
357 virtual ~MyProperty() { }
359 const wxPGEditor* DoGetEditorClass() const
361 // Determines editor used by property.
362 // You can replace 'TextCtrl' below with any of these
363 // builtin-in property editor identifiers: Choice, ComboBox,
364 // TextCtrlAndButton, ChoiceAndButton, CheckBox, SpinCtrl,
366 return wxPGEditor_TextCtrl;
369 virtual wxString GetValueAsString( int argFlags ) const
371 // TODO: Return property value in string format
374 virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags )
376 // TODO: Adapt string to property value.
383 Since wxPGProperty derives from wxObject, you can use standard
384 DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS macros. From the
385 above example they were omitted for sake of simplicity, and besides,
386 they are only really needed if you need to use wxRTTI with your
389 You can change the 'value type' of a property by simply assigning different
390 type of variant with SetValue. <b>It is mandatory to implement
391 wxVariantData class for all data types used as property values.</b>
392 You can use macros declared in wxPropertyGrid headers. For instance:
396 // (If you need to have export declaration, use version of macros
397 // with _EXPORTED postfix)
398 WX_PG_DECLARE_VARIANT_DATA(MyDataClass)
401 WX_PG_IMPLEMENT_VARIANT_DATA(MyDataClass)
403 // Or, if you don't have valid == operator:
404 WX_PG_IMPLEMENT_VARIANT_DATA_DUMMY_EQ(MyDataClass)
410 class wxPGProperty
: public wxObject
413 typedef wxUint32 FlagType
;
415 /** Basic constructor.
420 Non-abstract property classes should have constructor of this style:
424 // If T is a class, then it should be a constant reference
425 // (e.g. const T& ) instead.
426 MyProperty( const wxString& label, const wxString& name, T value )
429 // Generally recommended way to set the initial value
430 // (as it should work in pretty much 100% of cases).
435 // If has private child properties then create them here. For example:
436 // AddChild( new wxStringProperty( "Subprop 1", wxPG_LABEL, value.GetSubProp1() ) );
441 wxPGProperty( const wxString
& label
, const wxString
& name
);
443 /** Virtual destructor. It is customary for derived properties to implement this. */
444 virtual ~wxPGProperty();
446 /** This virtual function is called after m_value has been set.
449 - If m_value was set to Null variant (ie. unspecified value), OnSetValue()
451 - m_value may be of any variant type. Typically properties internally support only
452 one variant type, and as such OnSetValue() provides a good opportunity to convert
453 supported values into internal type.
454 - Default implementation does nothing.
456 virtual void OnSetValue();
458 /** Override this to return something else than m_value as the value.
460 virtual wxVariant
DoGetValue() const { return m_value
; }
462 /** Implement this function in derived class to check the value.
463 Return true if it is ok. Returning false prevents property change events
467 - Default implementation always returns true.
469 virtual bool ValidateValue( wxVariant
& value
, wxPGValidationInfo
& validationInfo
) const;
471 /** Converts 'text' into proper value 'variant'. Returns true if new (different than
472 m_value) value could be interpreted from the text.
474 If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable
475 one (they may be different).
476 If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of composite
477 property string value (as generated by GetValueAsString() called with this same
481 Default implementation converts semicolon delimited tokens into child values. Only
482 works for properties with children.
484 virtual bool StringToValue( wxVariant
& variant
, const wxString
& text
, int argFlags
= 0 ) const;
486 /** Converts 'number' (including choice selection) into proper value 'variant'.
487 Returns true if new (different than m_value) value could be interpreted from the integer.
489 If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable one.
492 - If property is not supposed to use choice or spinctrl or other editor
493 with int-based value, it is not necessary to implement this method.
494 - Default implementation simply assign given int to m_value.
495 - If property uses choice control, and displays a dialog on some choice items,
496 then it is preferred to display that dialog in IntToValue instead of OnEvent.
498 virtual bool IntToValue( wxVariant
& value
, int number
, int argFlags
= 0 ) const;
502 /** Returns text representation of property's value.
505 If wxPG_FULL_VALUE is set, returns complete, storable string value instead of displayable.
506 If wxPG_EDITABLE_VALUE is set, returns string value that must be editable in textctrl.
507 If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to display
508 as a part of composite property string value.
511 Default implementation returns string composed from text representations of
514 virtual wxString
GetValueAsString( int argFlags
= 0 ) const;
516 /** Converts string to a value, and if successful, calls SetValue() on it.
517 Default behavior is to do nothing.
519 String to get the value from.
521 true if value was changed.
523 bool SetValueFromString( const wxString
& text
, int flags
= 0 );
525 /** Converts integer to a value, and if succesful, calls SetValue() on it.
526 Default behavior is to do nothing.
528 Int to get the value from.
530 If has wxPG_FULL_VALUE, then the value given is a actual value and not an index.
532 True if value was changed.
534 bool SetValueFromInt( long value
, int flags
= 0 );
536 /** Returns size of the custom painted image in front of property. This method
537 must be overridden to return non-default value if OnCustomPaint is to be
540 Normally -1, but can be an index to the property's list of items.
542 - Default behavior is to return wxSize(0,0), which means no image.
543 - Default image width or height is indicated with dimension -1.
544 - You can also return wxPG_DEFAULT_IMAGE_SIZE which equals wxSize(-1, -1).
546 virtual wxSize
OnMeasureImage( int item
= -1 ) const;
548 /** Events received by editor widgets are processed here. Note that editor class
549 usually processes most events. Some, such as button press events of
550 TextCtrlAndButton class, can be handled here. Also, if custom handling
551 for regular events is desired, then that can also be done (for example,
552 wxSystemColourProperty custom handles wxEVT_COMMAND_CHOICE_SELECTED
553 to display colour picker dialog when 'custom' selection is made).
555 If the event causes value to be changed, SetValueInEvent()
556 should be called to set the new value.
561 Should return true if any changes in value should be reported.
563 - If property uses choice control, and displays a dialog on some choice items,
564 then it is preferred to display that dialog in IntToValue instead of OnEvent.
566 virtual bool OnEvent( wxPropertyGrid
* propgrid
, wxWindow
* wnd_primary
, wxEvent
& event
);
568 /** Called after value of a child property has been altered. Note that this function is
569 usually called at the time that value of this property, or given child property, is
570 still pending for change.
572 Sample pseudo-code implementation:
575 void MyProperty::ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const
577 // Acquire reference to actual type of data stored in variant
578 // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros were used to create
579 // the variant class).
580 T& data = TFromVariant(thisValue);
582 // Copy childValue into data.
583 switch ( childIndex )
586 data.SetSubProp1( childvalue.GetLong() );
589 data.SetSubProp2( childvalue.GetString() );
597 Value of this property, that should be altered.
599 Index of child changed (you can use Item(childIndex) to get).
601 Value of the child property.
603 virtual void ChildChanged( wxVariant
& thisValue
, int childIndex
, wxVariant
& childValue
) const;
605 /** Returns pointer to an instance of used editor.
607 virtual const wxPGEditor
* DoGetEditorClass() const;
609 /** Returns pointer to the wxValidator that should be used
610 with the editor of this property (NULL for no validator).
611 Setting validator explicitly via SetPropertyValidator
614 In most situations, code like this should work well
615 (macros are used to maintain one actual validator instance,
616 so on the second call the function exits within the first
621 wxValidator* wxMyPropertyClass::DoGetValidator () const
623 WX_PG_DOGETVALIDATOR_ENTRY()
625 wxMyValidator* validator = new wxMyValidator(...);
627 ... prepare validator...
629 WX_PG_DOGETVALIDATOR_EXIT(validator)
635 You can get common filename validator by returning
636 wxFileProperty::GetClassValidator(). wxDirProperty,
637 for example, uses it.
639 virtual wxValidator
* DoGetValidator () const;
641 /** Override to paint an image in front of the property value text or drop-down
642 list item (but only if wxPGProperty::OnMeasureImage is overridden as well).
644 If property's OnMeasureImage() returns size that has height != 0 but less than
645 row height ( < 0 has special meanings), wxPropertyGrid calls this method to
646 draw a custom image in a limited area in front of the editor control or
647 value text/graphics, and if control has drop-down list, then the image is
648 drawn there as well (even in the case OnMeasureImage() returned higher height
651 NOTE: Following applies when OnMeasureImage() returns a "flexible" height (
652 using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable height items:
653 If rect.x is < 0, then this is a measure item call, which means that
654 dc is invalid and only thing that should be done is to set paintdata.m_drawnHeight
655 to the height of the image of item at index paintdata.m_choiceItem. This call
656 may be done even as often as once every drop-down popup show.
661 Box reserved for custom graphics. Includes surrounding rectangle, if any.
662 If x is < 0, then this is a measure item call (see above).
664 wxPGPaintData structure with much useful data about painted item.
669 const wxPropertyGrid* m_parent;
671 // Normally -1, otherwise index to drop-down list item that has to be drawn.
674 // Set to drawn width in OnCustomPaint (optional).
677 // In a measure item call, set this to the height of item at m_choiceItem index
683 - You can actually exceed rect width, but if you do so then paintdata.m_drawnWidth
684 must be set to the full width drawn in pixels.
685 - Due to technical reasons, rect's height will be default even if custom height
686 was reported during measure call.
687 - Brush is guaranteed to be default background colour. It has been already used to
688 clear the background of area being painted. It can be modified.
689 - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper colour) pen for
690 drawing framing rectangle. It can be changed as well.
692 @see GetValueAsString()
694 virtual void OnCustomPaint( wxDC
& dc
, const wxRect
& rect
, wxPGPaintData
& paintdata
);
696 /** Returns used wxPGCellRenderer instance for given property column (label=0, value=1).
698 Default implementation returns editor's renderer for all columns.
700 virtual wxPGCellRenderer
* GetCellRenderer( int column
) const;
702 /** Returns which choice is currently selected. Only applies to properties
705 Needs to reimplemented in derived class if property value does not
706 map directly to a choice. Integer as index, bool, and string usually do.
708 virtual int GetChoiceSelection() const;
710 /** Refresh values of child properties. Automatically called after value is set.
712 virtual void RefreshChildren();
714 /** Special handling for attributes of this property.
716 If returns false, then the attribute will be automatically stored in
719 Default implementation simply returns false.
721 virtual bool DoSetAttribute( const wxString
& name
, wxVariant
& value
);
723 /** Returns value of an attribute.
725 Override if custom handling of attributes is needed.
727 Default implementation simply return NULL variant.
729 virtual wxVariant
DoGetAttribute( const wxString
& name
) const;
731 /** Returns instance of a new wxPGEditorDialogAdapter instance, which is
732 used when user presses the (optional) button next to the editor control;
734 Default implementation returns NULL (ie. no action is generated when
737 virtual wxPGEditorDialogAdapter
* GetEditorDialog() const;
739 /** Returns wxPGCell of given column, NULL if none. If valid
740 object is returned, caller will gain its ownership.
742 wxPGCell
* AcquireCell( unsigned int column
)
744 if ( column
>= m_cells
.size() )
747 wxPGCell
* cell
= (wxPGCell
*) m_cells
[column
];
748 m_cells
[column
] = NULL
;
752 /** Append a new choice to property's list of choices.
755 Label for added choice.
758 Value for new choice. Do not specify if you wish this
759 to equal choice index.
762 Index to added choice.
764 int AddChoice( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
766 /** Returns true if children of this property are component values (for instance,
767 points size, face name, and is_underlined are component values of a font).
769 bool AreChildrenComponents() const
771 if ( m_flags
& (wxPG_PROP_COMPOSED_VALUE
|wxPG_PROP_AGGREGATE
) )
777 /** Removes entry from property's wxPGChoices and editor control (if it is active).
779 If selected item is deleted, then the value is set to unspecified.
781 void DeleteChoice( int index
);
783 /** Call to enable or disable usage of common value (integer value that can be selected for
784 properties instead of their normal values) for this property.
786 Common values are disabled by the default for all properties.
788 void EnableCommonValue( bool enable
= true )
790 if ( enable
) SetFlag( wxPG_PROP_USES_COMMON_VALUE
);
791 else ClearFlag( wxPG_PROP_USES_COMMON_VALUE
);
794 /** Composes text from values of child properties. */
795 void GenerateComposedValue( wxString
& text
, int argFlags
= 0 ) const;
797 /** Returns property's label. */
798 const wxString
& GetLabel() const { return m_label
; }
800 /** Returns property's name with all (non-category, non-root) parents. */
801 wxString
GetName() const;
803 /** Returns property's base name (ie. parent's name is not added in any case) */
804 const wxString
& GetBaseName() const { return m_name
; }
806 /** Returns read-only reference to property's list of choices.
808 const wxPGChoices
& GetChoices() const;
810 /** Returns coordinate to the top y of the property. Note that the
811 position of scrollbars is not taken into account.
815 wxVariant
GetValue() const
820 /** Returns reference to the internal stored value. GetValue is preferred
821 way to get the actual value, since GetValueRef ignores DoGetValue,
822 which may override stored value.
824 wxVariant
& GetValueRef()
829 const wxVariant
& GetValueRef() const
834 /** Same as GetValueAsString, except takes common value into account.
836 wxString
GetValueString( int argFlags
= 0 ) const;
838 void UpdateControl( wxWindow
* primary
);
840 /** Returns wxPGCell of given column, NULL if none. wxPGProperty
841 will retain ownership of the cell object.
843 wxPGCell
* GetCell( unsigned int column
) const
845 if ( column
>= m_cells
.size() )
848 return (wxPGCell
*) m_cells
[column
];
851 /** Return number of displayed common values for this property.
853 int GetDisplayedCommonValueCount() const;
855 wxString
GetDisplayedString() const
857 return GetValueString(0);
860 /** Returns property grid where property lies. */
861 wxPropertyGrid
* GetGrid() const;
863 /** Returns owner wxPropertyGrid, but only if one is currently on a page
864 displaying this property. */
865 wxPropertyGrid
* GetGridIfDisplayed() const;
867 /** Returns highest level non-category, non-root parent. Useful when you
868 have nested wxCustomProperties/wxParentProperties.
870 Thus, if immediate parent is root or category, this will return the
873 wxPGProperty
* GetMainParent() const;
875 /** Return parent of property */
876 wxPGProperty
* GetParent() const { return m_parent
; }
878 /** Returns true if property has editable wxTextCtrl when selected.
881 Altough disabled properties do not displayed editor, they still
882 return True here as being disabled is considered a temporary
883 condition (unlike being read-only or having limited editing enabled).
885 bool IsTextEditable() const;
887 bool IsValueUnspecified() const
889 return m_value
.IsNull();
892 FlagType
HasFlag( FlagType flag
) const
894 return ( m_flags
& flag
);
897 /** Returns comma-delimited string of property attributes.
899 const wxPGAttributeStorage
& GetAttributes() const
904 /** Returns m_attributes as list wxVariant.
906 wxVariant
GetAttributesAsList() const;
908 FlagType
GetFlags() const
913 const wxPGEditor
* GetEditorClass() const;
915 wxString
GetValueType() const
917 return m_value
.GetType();
920 /** Returns editor used for given column. NULL for no editor.
922 const wxPGEditor
* GetColumnEditor( int column
) const
925 return GetEditorClass();
930 /** Returns common value selected for this property. -1 for none.
932 int GetCommonValue() const
934 return m_commonValue
;
937 /** Returns true if property has even one visible child.
939 bool HasVisibleChildren() const;
941 /** Inserts a new choice to property's list of choices.
947 Insertion position. Use wxNOT_FOUND to append.
950 Value for new choice. Do not specify if you wish this
951 to equal choice index.
953 int InsertChoice( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
955 /** Returns true if this property is actually a wxPropertyCategory.
957 bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY
)?
true:false; }
959 /** Returns true if this property is actually a wxRootProperty.
961 bool IsRoot() const { return (m_parent
== NULL
); }
963 /** Returns true if this is a sub-property. */
964 bool IsSubProperty() const
966 wxPGProperty
* parent
= (wxPGProperty
*)m_parent
;
967 if ( parent
&& !parent
->IsCategory() )
972 /** Returns last visible sub-property, recursively.
974 const wxPGProperty
* GetLastVisibleSubItem() const;
976 wxVariant
GetDefaultValue() const;
978 int GetMaxLength() const
980 return (int) m_maxLen
;
983 /** Determines, recursively, if all children are not unspecified. Takes values in given list into account.
985 bool AreAllChildrenSpecified( wxVariant
* pendingList
= NULL
) const;
987 /** Updates composed values of parent non-category properties, recursively.
988 Returns topmost property updated.
991 - Must not call SetValue() (as can be called in it).
993 wxPGProperty
* UpdateParentValues();
995 /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
997 FlagType
UsesAutoUnspecified() const
999 return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED
);
1002 wxBitmap
* GetValueImage() const
1004 return m_valueBitmap
;
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;
1021 inline unsigned int GetArrIndex() const { return m_arrIndex
; }
1023 inline unsigned int GetDepth() const { return (unsigned int)m_depth
; }
1025 /** Gets flags as a'|' delimited string. Note that flag names are not
1026 prepended with 'wxPG_PROP_'.
1028 String will only be made to include flags combined by this parameter.
1030 wxString
GetFlagsAsString( FlagType flagsMask
) const;
1032 /** Returns position in parent's array. */
1033 unsigned int GetIndexInParent() const
1035 return (unsigned int)m_arrIndex
;
1038 /** Hides or reveals the property.
1040 true for hide, false for reveal.
1042 By default changes are applied recursively. Set this paramter wxPG_DONT_RECURSE to prevent this.
1044 inline bool Hide( bool hide
, int flags
= wxPG_RECURSE
);
1046 bool IsExpanded() const { return (!(m_flags
& wxPG_PROP_COLLAPSED
) && GetChildCount()); }
1048 /** Returns true if all parents expanded.
1050 bool IsVisible() const;
1052 bool IsEnabled() const
1054 return ( m_flags
& wxPG_PROP_DISABLED
) ?
false : true;
1057 /** If property's editor is created this forces its recreation. Useful
1058 in SetAttribute etc. Returns true if actually did anything.
1060 bool RecreateEditor();
1062 /** If property's editor is active, then update it's value.
1064 void RefreshEditor();
1066 /** Sets an attribute for this property.
1068 Text identifier of attribute. See @ref propgrid_property_attributes.
1072 void SetAttribute( const wxString
& name
, wxVariant value
);
1074 void SetAttributes( const wxPGAttributeStorage
& attributes
);
1076 /** Sets editor for a property.
1079 For builtin editors, use wxPGEditor_X, where X is builtin editor's
1080 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list).
1082 For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
1084 void SetEditor( const wxPGEditor
* editor
)
1086 m_customEditor
= editor
;
1089 /** Sets editor for a property.
1091 inline void SetEditor( const wxString
& editorName
);
1093 /** Sets cell information for given column.
1095 Note that the property takes ownership of given wxPGCell instance.
1097 void SetCell( int column
, wxPGCell
* cellObj
);
1099 /** If property has choices and they are not yet exclusive, new such copy
1100 of them will be created.
1102 void SetChoicesExclusive();
1104 /** Sets selected choice and changes property value.
1106 Tries to retain value type, although currently if it is not string,
1107 then it is forced to integer.
1109 void SetChoiceSelection( int newValue
);
1111 /** Sets common value selected for this property. -1 for none.
1113 void SetCommonValue( int commonValue
)
1115 m_commonValue
= commonValue
;
1118 /** Sets flags from a '|' delimited string. Note that flag names are not
1119 prepended with 'wxPG_PROP_'.
1121 void SetFlagsFromString( const wxString
& str
);
1123 /** Sets property's "is it modified?" flag. Affects children recursively.
1125 void SetModifiedStatus( bool modified
)
1127 SetFlagRecursively(wxPG_PROP_MODIFIED
, modified
);
1130 /** Call in OnEvent(), OnButtonClick() etc. to change the property value
1131 based on user input.
1134 This method is const since it doesn't actually modify value, but posts
1135 given variant as pending value, stored in wxPropertyGrid.
1137 void SetValueInEvent( wxVariant value
) const;
1139 /** Call this to set value of the property. Unlike methods in wxPropertyGrid,
1140 this does not automatically update the display.
1143 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through
1144 validation process and send property change event.
1146 If you need to change property value in event, based on user input, use
1147 SetValueInEvent() instead.
1150 Pointer to list variant that contains child values. Used to indicate
1151 which children should be marked as modified.
1153 Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR).
1155 void SetValue( wxVariant value
, wxVariant
* pList
= NULL
, int flags
= 0 );
1157 /** Set wxBitmap in front of the value. This bitmap may be ignored
1158 by custom cell renderers.
1160 void SetValueImage( wxBitmap
& bmp
);
1162 void SetExpanded( bool expanded
)
1164 if ( !expanded
) m_flags
|= wxPG_PROP_COLLAPSED
;
1165 else m_flags
&= ~wxPG_PROP_COLLAPSED
;
1168 void SetFlag( FlagType flag
) { m_flags
|= flag
; }
1170 void SetFlagRecursively( FlagType flag
, bool set
);
1172 void SetHelpString( const wxString
& helpString
)
1174 m_helpString
= helpString
;
1177 /** Sets property's label.
1180 - Properties under same parent may have same labels. However,
1181 property names must still remain unique.
1183 void SetLabel( const wxString
& label
) { m_label
= label
; }
1185 inline void SetName( const wxString
& newName
);
1187 void SetValueToUnspecified()
1189 wxVariant val
; // Create NULL variant
1193 /** Sets wxValidator for a property*/
1194 void SetValidator( const wxValidator
& validator
)
1196 m_validator
= wxDynamicCast(validator
.Clone(),wxValidator
);
1199 /** Gets assignable version of property's validator. */
1200 wxValidator
* GetValidator() const
1204 return DoGetValidator();
1207 /** Updates property value in case there were last minute
1208 changes. If value was unspecified, it will be set to default.
1209 Use only for properties that have TextCtrl-based editor.
1211 If you have code similar to
1213 // Update the value in case of last minute changes
1214 if ( primary && propgrid->IsEditorsValueModified() )
1215 GetEditorClass()->CopyValueFromControl( this, primary );
1217 in wxPGProperty::OnEvent wxEVT_COMMAND_BUTTON_CLICKED handler,
1218 then replace it with call to this method.
1220 True if value changed.
1222 bool PrepareValueForDialogEditing( wxPropertyGrid
* propgrid
);
1224 /** Returns client data (void*) of a property.
1226 void* GetClientData() const
1228 return m_clientData
;
1231 /** Sets client data (void*) of a property.
1233 This untyped client data has to be deleted manually.
1235 void SetClientData( void* clientData
)
1237 m_clientData
= clientData
;
1240 /** Returns client object of a property.
1242 void SetClientObject(wxClientData
* clientObject
)
1244 delete m_clientObject
;
1245 m_clientObject
= clientObject
;
1248 /** Sets managed client object of a property.
1250 wxClientData
*GetClientObject() const { return m_clientObject
; }
1252 /** Sets new set of choices for property.
1255 This operation clears the property value.
1257 bool SetChoices( wxPGChoices
& choices
);
1259 /** Sets new set of choices for property.
1261 inline bool SetChoices( const wxArrayString
& labels
,
1262 const wxArrayInt
& values
= wxArrayInt() );
1264 /** Set max length of text in text editor.
1266 inline bool SetMaxLength( int maxLen
);
1268 /** Call with 'false' in OnSetValue to cancel value changes after all
1269 (ie. cancel 'true' returned by StringToValue() or IntToValue()).
1271 void SetWasModified( bool set
= true )
1273 if ( set
) m_flags
|= wxPG_PROP_WAS_MODIFIED
;
1274 else m_flags
&= ~wxPG_PROP_WAS_MODIFIED
;
1277 const wxString
& GetHelpString() const
1279 return m_helpString
;
1282 void ClearFlag( FlagType flag
) { m_flags
&= ~(flag
); }
1284 // Use, for example, to detect if item is inside collapsed section.
1285 bool IsSomeParent( wxPGProperty
* candidate_parent
) const;
1287 /** Adapts list variant into proper value using consequtive ChildChanged-calls.
1289 void AdaptListToValue( wxVariant
& list
, wxVariant
* value
) const;
1291 /** This is used by properties that have fixed sub-properties. */
1292 void AddChild( wxPGProperty
* prop
);
1294 /** Returns height of children, recursively, and
1295 by taking expanded/collapsed status into account.
1297 iMax is used when finding property y-positions.
1299 int GetChildrenHeight( int lh
, int iMax
= -1 ) const;
1301 /** Returns number of child properties */
1302 unsigned int GetChildCount() const { return m_children
.GetCount(); }
1304 /** Returns sub-property at index i. */
1305 wxPGProperty
* Item( size_t i
) const { return (wxPGProperty
*)m_children
.Item(i
); }
1307 /** Returns last sub-property.
1309 wxPGProperty
* Last() const { return (wxPGProperty
*)m_children
.Last(); }
1311 /** Returns index of given sub-property. */
1312 int Index( const wxPGProperty
* p
) const { return m_children
.Index((wxPGProperty
*)p
); }
1314 /** Deletes all sub-properties. */
1317 // Puts correct indexes to children
1318 void FixIndexesOfChildren( size_t starthere
= 0 );
1320 wxPGProperty
* GetItemAtY( unsigned int y
, unsigned int lh
, unsigned int* nextItemY
) const;
1322 /** Returns (direct) child property with given name (or NULL if not found).
1324 wxPGProperty
* GetPropertyByName( const wxString
& name
) const;
1328 /** @class wxPGChoices
1330 Helper class for managing choices of wxPropertyGrid properties.
1331 Each entry can have label, value, bitmap, text colour, and background colour.
1333 @library{wxpropgrid}
1336 class WXDLLIMPEXP_PROPGRID wxPGChoices
1339 typedef long ValArrItem
;
1341 /** Default constructor. */
1347 /** Copy constructor. */
1348 wxPGChoices( const wxPGChoices
& a
)
1350 if ( a
.m_data
!= wxPGChoicesEmptyData
)
1353 m_data
->m_refCount
++;
1358 wxPGChoices( const wxChar
** labels
, const long* values
= NULL
)
1365 wxPGChoices( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() )
1371 /** Simple interface constructor. */
1372 wxPGChoices( wxPGChoicesData
* data
)
1385 /** Adds to current. If did not have own copies, creates them now. If was empty,
1386 identical to set except that creates copies.
1388 void Add( const wxChar
** labels
, const ValArrItem
* values
= NULL
);
1390 /** Version that works with wxArrayString. */
1391 void Add( const wxArrayString
& arr
, const ValArrItem
* values
= NULL
);
1393 /** Version that works with wxArrayString and wxArrayInt. */
1394 void Add( const wxArrayString
& arr
, const wxArrayInt
& arrint
);
1396 /** Adds single item. */
1397 wxPGChoiceEntry
& Add( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1399 /** Adds a single item, with bitmap. */
1400 wxPGChoiceEntry
& Add( const wxString
& label
, const wxBitmap
& bitmap
, int value
= wxPG_INVALID_VALUE
);
1402 /** Adds a single item with full entry information. */
1403 wxPGChoiceEntry
& Add( const wxPGChoiceEntry
& entry
)
1405 return Insert(entry
, -1);
1408 /** Adds single item. */
1409 wxPGChoiceEntry
& AddAsSorted( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1411 void Assign( const wxPGChoices
& a
)
1413 AssignData(a
.m_data
);
1416 void AssignData( wxPGChoicesData
* data
);
1418 /** Delete all choices. */
1421 if ( m_data
!= wxPGChoicesEmptyData
)
1427 if ( m_data
== wxPGChoicesEmptyData
)
1428 m_data
= new wxPGChoicesData();
1431 /** Gets a unsigned number identifying this list. */
1432 wxPGChoicesId
GetId() const { return (wxPGChoicesId
) m_data
; };
1434 const wxString
& GetLabel( size_t ind
) const
1436 wxASSERT( ind
>= 0 && ind
< GetCount() );
1437 return Item(ind
).GetText();
1440 size_t GetCount () const
1442 wxASSERT_MSG( m_data
,
1443 wxT("When checking if wxPGChoices is valid, use IsOk() instead of GetCount()") );
1444 return m_data
->GetCount();
1447 int GetValue( size_t ind
) const { return Item(ind
).GetValue(); }
1449 /** Returns array of values matching the given strings. Unmatching strings
1450 result in wxPG_INVALID_VALUE entry in array.
1452 wxArrayInt
GetValuesForStrings( const wxArrayString
& strings
) const;
1454 /** Returns array of indices matching given strings. Unmatching strings
1455 are added to 'unmatched', if not NULL.
1457 wxArrayInt
GetIndicesForStrings( const wxArrayString
& strings
, wxArrayString
* unmatched
= NULL
) const;
1459 /** Returns true if choices in general are likely to have values
1460 (depens on that all entries have values or none has)
1462 bool HasValues() const;
1464 bool HasValue( unsigned int i
) const { return (m_data
->GetCount() > i
&& m_data
->Item(i
)->HasValue()); }
1466 int Index( const wxString
& str
) const;
1467 int Index( int val
) const;
1469 /** Inserts single item. */
1470 wxPGChoiceEntry
& Insert( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1472 /** Inserts a single item with full entry information. */
1473 wxPGChoiceEntry
& Insert( const wxPGChoiceEntry
& entry
, int index
);
1475 /** Returns false if this is a constant empty set of choices,
1476 which should not be modified.
1480 return ( m_data
!= wxPGChoicesEmptyData
);
1483 const wxPGChoiceEntry
& Item( unsigned int i
) const
1486 return *m_data
->Item(i
);
1489 wxPGChoiceEntry
& Item( unsigned int i
)
1492 return *m_data
->Item(i
);
1495 /** Removes count items starting at position nIndex. */
1496 void RemoveAt(size_t nIndex
, size_t count
= 1);
1498 /** Does not create copies for itself. */
1499 void Set( const wxChar
** labels
, const long* values
= NULL
)
1505 /** Version that works with wxArrayString.
1506 TODO: Deprecate this.
1508 void Set( wxArrayString
& arr
, const long* values
= (const long*) NULL
)
1514 /** Version that works with wxArrayString and wxArrayInt. */
1515 void Set( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() )
1524 // Creates exclusive copy of current choices
1527 if ( m_data
->m_refCount
!= 1 )
1529 wxPGChoicesData
* data
= new wxPGChoicesData();
1530 data
->CopyDataFrom(m_data
);
1536 // Returns data, increases refcount.
1537 wxPGChoicesData
* GetData()
1539 wxASSERT( m_data
->m_refCount
!= 0xFFFFFFF );
1540 m_data
->m_refCount
++;
1544 // Returns plain data ptr - no refcounting stuff is done.
1545 wxPGChoicesData
* GetDataPtr() const { return m_data
; }
1547 // Changes ownership of data to you.
1548 wxPGChoicesData
* ExtractData()
1550 wxPGChoicesData
* data
= m_data
;
1551 m_data
= wxPGChoicesEmptyData
;
1555 wxArrayString
GetLabels() const;
1557 void operator= (const wxPGChoices
& a
)
1559 AssignData(a
.m_data
);
1562 wxPGChoiceEntry
& operator[](unsigned int i
)
1567 const wxPGChoiceEntry
& operator[](unsigned int i
) const
1573 // -----------------------------------------------------------------------