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 /** Composes text from values of child properties. */
784 void GenerateComposedValue( wxString
& text
, int argFlags
= 0 ) const;
786 /** Returns property's label. */
787 const wxString
& GetLabel() const { return m_label
; }
789 /** Returns property's name with all (non-category, non-root) parents. */
790 wxString
GetName() const;
792 /** Returns property's base name (ie. parent's name is not added in any case) */
793 const wxString
& GetBaseName() const { return m_name
; }
795 /** Returns read-only reference to property's list of choices.
797 const wxPGChoices
& GetChoices() const;
799 /** Returns coordinate to the top y of the property. Note that the
800 position of scrollbars is not taken into account.
804 wxVariant
GetValue() const
809 /** Returns reference to the internal stored value. GetValue is preferred
810 way to get the actual value, since GetValueRef ignores DoGetValue,
811 which may override stored value.
813 wxVariant
& GetValueRef()
818 const wxVariant
& GetValueRef() const
823 /** To acquire property's value as string, you should use this
824 function (instead of GetValueAsString()), as it may produce
825 more accurate value in future versions.
827 wxString
GetValueString( int argFlags
= 0 ) const;
829 void UpdateControl( wxWindow
* primary
);
831 /** Returns wxPGCell of given column, NULL if none. wxPGProperty
832 will retain ownership of the cell object.
834 wxPGCell
* GetCell( unsigned int column
) const
836 if ( column
>= m_cells
.size() )
839 return (wxPGCell
*) m_cells
[column
];
842 /** Returns property's displayed text.
844 wxString
GetDisplayedString() const
846 return GetValueString(0);
849 /** Returns property grid where property lies. */
850 wxPropertyGrid
* GetGrid() const;
852 /** Returns owner wxPropertyGrid, but only if one is currently on a page
853 displaying this property. */
854 wxPropertyGrid
* GetGridIfDisplayed() const;
856 /** Returns highest level non-category, non-root parent. Useful when you
857 have nested wxCustomProperties/wxParentProperties.
859 Thus, if immediate parent is root or category, this will return the
862 wxPGProperty
* GetMainParent() const;
864 /** Return parent of property */
865 wxPGProperty
* GetParent() const { return m_parent
; }
867 /** Returns true if property has editable wxTextCtrl when selected.
870 Altough disabled properties do not displayed editor, they still
871 return True here as being disabled is considered a temporary
872 condition (unlike being read-only or having limited editing enabled).
874 bool IsTextEditable() const;
876 bool IsValueUnspecified() const
878 return m_value
.IsNull();
881 FlagType
HasFlag( FlagType flag
) const
883 return ( m_flags
& flag
);
886 /** Returns comma-delimited string of property attributes.
888 const wxPGAttributeStorage
& GetAttributes() const
893 /** Returns m_attributes as list wxVariant.
895 wxVariant
GetAttributesAsList() const;
897 FlagType
GetFlags() const
902 const wxPGEditor
* GetEditorClass() const;
904 wxString
GetValueType() const
906 return m_value
.GetType();
909 /** Returns editor used for given column. NULL for no editor.
911 const wxPGEditor
* GetColumnEditor( int column
) const
914 return GetEditorClass();
919 /** Returns true if property has even one visible child.
921 bool HasVisibleChildren() const;
923 /** Inserts a new choice to property's list of choices.
929 Insertion position. Use wxNOT_FOUND to append.
932 Value for new choice. Do not specify if you wish this
933 to equal choice index.
935 int InsertChoice( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
937 /** Returns true if this property is actually a wxPropertyCategory.
939 bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY
)?true:false; }
941 /** Returns true if this property is actually a wxRootProperty.
943 bool IsRoot() const { return (m_parent
== NULL
); }
945 /** Returns true if this is a sub-property. */
946 bool IsSubProperty() const
948 wxPGProperty
* parent
= (wxPGProperty
*)m_parent
;
949 if ( parent
&& !parent
->IsCategory() )
954 /** Returns last visible sub-property, recursively.
956 const wxPGProperty
* GetLastVisibleSubItem() const;
958 wxVariant
GetDefaultValue() const;
960 int GetMaxLength() const
962 return (int) m_maxLen
;
965 /** Determines, recursively, if all children are not unspecified. Takes values in given list into account.
967 bool AreAllChildrenSpecified( wxVariant
* pendingList
= NULL
) const;
969 /** Updates composed values of parent non-category properties, recursively.
970 Returns topmost property updated.
973 - Must not call SetValue() (as can be called in it).
975 wxPGProperty
* UpdateParentValues();
977 /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
979 FlagType
UsesAutoUnspecified() const
981 return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED
);
984 wxBitmap
* GetValueImage() const
986 return m_valueBitmap
;
989 wxVariant
GetAttribute( const wxString
& name
) const;
991 /** Returns named attribute, as string, if found. Otherwise defVal is returned.
993 wxString
GetAttribute( const wxString
& name
, const wxString
& defVal
) const;
995 /** Returns named attribute, as long, if found. Otherwise defVal is returned.
997 long GetAttributeAsLong( const wxString
& name
, long defVal
) const;
999 /** Returns named attribute, as double, if found. Otherwise defVal is returned.
1001 double GetAttributeAsDouble( const wxString
& name
, double defVal
) const;
1003 inline unsigned int GetArrIndex() const { return m_arrIndex
; }
1005 inline unsigned int GetDepth() const { return (unsigned int)m_depth
; }
1007 /** Gets flags as a'|' delimited string. Note that flag names are not
1008 prepended with 'wxPG_PROP_'.
1010 String will only be made to include flags combined by this parameter.
1012 wxString
GetFlagsAsString( FlagType flagsMask
) const;
1014 /** Returns position in parent's array. */
1015 unsigned int GetIndexInParent() const
1017 return (unsigned int)m_arrIndex
;
1020 /** Hides or reveals the property.
1022 true for hide, false for reveal.
1024 By default changes are applied recursively. Set this paramter wxPG_DONT_RECURSE to prevent this.
1026 inline bool Hide( bool hide
, int flags
= wxPG_RECURSE
);
1028 bool IsExpanded() const { return (!(m_flags
& wxPG_PROP_COLLAPSED
) && GetChildCount()); }
1030 /** Returns true if all parents expanded.
1032 bool IsVisible() const;
1034 bool IsEnabled() const
1036 return ( m_flags
& wxPG_PROP_DISABLED
) ? false : true;
1039 /** If property's editor is created this forces its recreation. Useful
1040 in SetAttribute etc. Returns true if actually did anything.
1042 bool RecreateEditor();
1044 /** If property's editor is active, then update it's value.
1046 void RefreshEditor();
1048 /** Sets an attribute for this property.
1050 Text identifier of attribute. See @ref propgrid_property_attributes.
1054 void SetAttribute( const wxString
& name
, wxVariant value
);
1056 void SetAttributes( const wxPGAttributeStorage
& attributes
);
1058 /** Sets editor for a property.
1061 For builtin editors, use wxPGEditor_X, where X is builtin editor's
1062 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list).
1064 For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
1066 void SetEditor( const wxPGEditor
* editor
)
1068 m_customEditor
= editor
;
1071 /** Sets editor for a property.
1073 inline void SetEditor( const wxString
& editorName
);
1075 /** Sets cell information for given column.
1077 Note that the property takes ownership of given wxPGCell instance.
1079 void SetCell( int column
, wxPGCell
* cellObj
);
1081 /** If property has choices and they are not yet exclusive, new such copy
1082 of them will be created.
1084 void SetChoicesExclusive();
1086 /** Sets selected choice and changes property value.
1088 Tries to retain value type, although currently if it is not string,
1089 then it is forced to integer.
1091 void SetChoiceSelection( int newValue
);
1093 /** Sets flags from a '|' delimited string. Note that flag names are not
1094 prepended with 'wxPG_PROP_'.
1096 void SetFlagsFromString( const wxString
& str
);
1098 /** Sets property's "is it modified?" flag. Affects children recursively.
1100 void SetModifiedStatus( bool modified
)
1102 SetFlagRecursively(wxPG_PROP_MODIFIED
, modified
);
1105 /** Call in OnEvent(), OnButtonClick() etc. to change the property value
1106 based on user input.
1109 This method is const since it doesn't actually modify value, but posts
1110 given variant as pending value, stored in wxPropertyGrid.
1112 void SetValueInEvent( wxVariant value
) const;
1114 /** Call this to set value of the property. Unlike methods in wxPropertyGrid,
1115 this does not automatically update the display.
1118 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through
1119 validation process and send property change event.
1121 If you need to change property value in event, based on user input, use
1122 SetValueInEvent() instead.
1125 Pointer to list variant that contains child values. Used to indicate
1126 which children should be marked as modified.
1128 Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR).
1130 void SetValue( wxVariant value
, wxVariant
* pList
= NULL
, int flags
= 0 );
1132 /** Set wxBitmap in front of the value. This bitmap may be ignored
1133 by custom cell renderers.
1135 void SetValueImage( wxBitmap
& bmp
);
1137 void SetExpanded( bool expanded
)
1139 if ( !expanded
) m_flags
|= wxPG_PROP_COLLAPSED
;
1140 else m_flags
&= ~wxPG_PROP_COLLAPSED
;
1143 void SetFlag( FlagType flag
) { m_flags
|= flag
; }
1145 void SetFlagRecursively( FlagType flag
, bool set
);
1147 void SetHelpString( const wxString
& helpString
)
1149 m_helpString
= helpString
;
1152 /** Sets property's label.
1155 - Properties under same parent may have same labels. However,
1156 property names must still remain unique.
1158 void SetLabel( const wxString
& label
) { m_label
= label
; }
1160 inline void SetName( const wxString
& newName
);
1162 void SetValueToUnspecified()
1164 wxVariant val
; // Create NULL variant
1168 /** Sets wxValidator for a property*/
1169 void SetValidator( const wxValidator
& validator
)
1171 m_validator
= wxDynamicCast(validator
.Clone(),wxValidator
);
1174 /** Gets assignable version of property's validator. */
1175 wxValidator
* GetValidator() const
1179 return DoGetValidator();
1182 /** Updates property value in case there were last minute
1183 changes. If value was unspecified, it will be set to default.
1184 Use only for properties that have TextCtrl-based editor.
1186 If you have code similar to
1188 // Update the value in case of last minute changes
1189 if ( primary && propgrid->IsEditorsValueModified() )
1190 GetEditorClass()->CopyValueFromControl( this, primary );
1192 in wxPGProperty::OnEvent wxEVT_COMMAND_BUTTON_CLICKED handler,
1193 then replace it with call to this method.
1195 True if value changed.
1197 bool PrepareValueForDialogEditing( wxPropertyGrid
* propgrid
);
1199 /** Returns client data (void*) of a property.
1201 void* GetClientData() const
1203 return m_clientData
;
1206 /** Sets client data (void*) of a property.
1208 This untyped client data has to be deleted manually.
1210 void SetClientData( void* clientData
)
1212 m_clientData
= clientData
;
1215 /** Returns client object of a property.
1217 void SetClientObject(wxClientData
* clientObject
)
1219 delete m_clientObject
;
1220 m_clientObject
= clientObject
;
1223 /** Sets managed client object of a property.
1225 wxClientData
*GetClientObject() const { return m_clientObject
; }
1227 /** Sets new set of choices for property.
1230 This operation clears the property value.
1232 bool SetChoices( wxPGChoices
& choices
);
1234 /** Sets new set of choices for property.
1236 inline bool SetChoices( const wxArrayString
& labels
,
1237 const wxArrayInt
& values
= wxArrayInt() );
1239 /** Set max length of text in text editor.
1241 inline bool SetMaxLength( int maxLen
);
1243 /** Call with 'false' in OnSetValue to cancel value changes after all
1244 (ie. cancel 'true' returned by StringToValue() or IntToValue()).
1246 void SetWasModified( bool set
= true )
1248 if ( set
) m_flags
|= wxPG_PROP_WAS_MODIFIED
;
1249 else m_flags
&= ~wxPG_PROP_WAS_MODIFIED
;
1252 const wxString
& GetHelpString() const
1254 return m_helpString
;
1257 void ClearFlag( FlagType flag
) { m_flags
&= ~(flag
); }
1259 // Use, for example, to detect if item is inside collapsed section.
1260 bool IsSomeParent( wxPGProperty
* candidate_parent
) const;
1262 /** Adapts list variant into proper value using consequtive ChildChanged-calls.
1264 void AdaptListToValue( wxVariant
& list
, wxVariant
* value
) const;
1266 /** This is used by properties that have fixed sub-properties. */
1267 void AddChild( wxPGProperty
* prop
);
1269 /** Returns height of children, recursively, and
1270 by taking expanded/collapsed status into account.
1272 iMax is used when finding property y-positions.
1274 int GetChildrenHeight( int lh
, int iMax
= -1 ) const;
1276 /** Returns number of child properties */
1277 unsigned int GetChildCount() const { return m_children
.GetCount(); }
1279 /** Returns sub-property at index i. */
1280 wxPGProperty
* Item( size_t i
) const { return (wxPGProperty
*)m_children
.Item(i
); }
1282 /** Returns last sub-property.
1284 wxPGProperty
* Last() const { return (wxPGProperty
*)m_children
.Last(); }
1286 /** Returns index of given sub-property. */
1287 int Index( const wxPGProperty
* p
) const { return m_children
.Index((wxPGProperty
*)p
); }
1289 /** Deletes all sub-properties. */
1292 // Puts correct indexes to children
1293 void FixIndexesOfChildren( size_t starthere
= 0 );
1295 wxPGProperty
* GetItemAtY( unsigned int y
, unsigned int lh
, unsigned int* nextItemY
) const;
1297 /** Returns (direct) child property with given name (or NULL if not found).
1299 wxPGProperty
* GetPropertyByName( const wxString
& name
) const;
1303 /** @class wxPGChoices
1305 Helper class for managing choices of wxPropertyGrid properties.
1306 Each entry can have label, value, bitmap, text colour, and background colour.
1308 @library{wxpropgrid}
1311 class WXDLLIMPEXP_PROPGRID wxPGChoices
1314 typedef long ValArrItem
;
1316 /** Default constructor. */
1322 /** Copy constructor. */
1323 wxPGChoices( const wxPGChoices
& a
)
1325 if ( a
.m_data
!= wxPGChoicesEmptyData
)
1328 m_data
->m_refCount
++;
1333 wxPGChoices( const wxChar
** labels
, const long* values
= NULL
)
1340 wxPGChoices( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() )
1346 /** Simple interface constructor. */
1347 wxPGChoices( wxPGChoicesData
* data
)
1360 /** Adds to current. If did not have own copies, creates them now. If was empty,
1361 identical to set except that creates copies.
1363 void Add( const wxChar
** labels
, const ValArrItem
* values
= NULL
);
1365 /** Version that works with wxArrayString. */
1366 void Add( const wxArrayString
& arr
, const ValArrItem
* values
= NULL
);
1368 /** Version that works with wxArrayString and wxArrayInt. */
1369 void Add( const wxArrayString
& arr
, const wxArrayInt
& arrint
);
1371 /** Adds single item. */
1372 wxPGChoiceEntry
& Add( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1374 /** Adds a single item, with bitmap. */
1375 wxPGChoiceEntry
& Add( const wxString
& label
, const wxBitmap
& bitmap
, int value
= wxPG_INVALID_VALUE
);
1377 /** Adds a single item with full entry information. */
1378 wxPGChoiceEntry
& Add( const wxPGChoiceEntry
& entry
)
1380 return Insert(entry
, -1);
1383 /** Adds single item. */
1384 wxPGChoiceEntry
& AddAsSorted( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1386 void Assign( const wxPGChoices
& a
)
1388 AssignData(a
.m_data
);
1391 void AssignData( wxPGChoicesData
* data
);
1393 /** Delete all choices. */
1396 if ( m_data
!= wxPGChoicesEmptyData
)
1402 if ( m_data
== wxPGChoicesEmptyData
)
1403 m_data
= new wxPGChoicesData();
1406 /** Gets a unsigned number identifying this list. */
1407 wxPGChoicesId
GetId() const { return (wxPGChoicesId
) m_data
; };
1409 const wxString
& GetLabel( size_t ind
) const
1411 wxASSERT( ind
>= 0 && ind
< GetCount() );
1412 return Item(ind
).GetText();
1415 size_t GetCount () const
1417 wxASSERT_MSG( m_data
,
1418 wxT("When checking if wxPGChoices is valid, use IsOk() instead of GetCount()") );
1419 return m_data
->GetCount();
1422 int GetValue( size_t ind
) const { return Item(ind
).GetValue(); }
1424 /** Returns array of values matching the given strings. Unmatching strings
1425 result in wxPG_INVALID_VALUE entry in array.
1427 wxArrayInt
GetValuesForStrings( const wxArrayString
& strings
) const;
1429 /** Returns array of indices matching given strings. Unmatching strings
1430 are added to 'unmatched', if not NULL.
1432 wxArrayInt
GetIndicesForStrings( const wxArrayString
& strings
, wxArrayString
* unmatched
= NULL
) const;
1434 /** Returns true if choices in general are likely to have values
1435 (depens on that all entries have values or none has)
1437 bool HasValues() const;
1439 bool HasValue( unsigned int i
) const { return (m_data
->GetCount() > i
&& m_data
->Item(i
)->HasValue()); }
1441 int Index( const wxString
& str
) const;
1442 int Index( int val
) const;
1444 /** Inserts single item. */
1445 wxPGChoiceEntry
& Insert( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1447 /** Inserts a single item with full entry information. */
1448 wxPGChoiceEntry
& Insert( const wxPGChoiceEntry
& entry
, int index
);
1450 /** Returns false if this is a constant empty set of choices,
1451 which should not be modified.
1455 return ( m_data
!= wxPGChoicesEmptyData
);
1458 const wxPGChoiceEntry
& Item( unsigned int i
) const
1461 return *m_data
->Item(i
);
1464 wxPGChoiceEntry
& Item( unsigned int i
)
1467 return *m_data
->Item(i
);
1470 /** Removes count items starting at position nIndex. */
1471 void RemoveAt(size_t nIndex
, size_t count
= 1);
1473 /** Does not create copies for itself. */
1474 void Set( const wxChar
** labels
, const long* values
= NULL
)
1480 /** Version that works with wxArrayString.
1481 TODO: Deprecate this.
1483 void Set( wxArrayString
& arr
, const long* values
= (const long*) NULL
)
1489 /** Version that works with wxArrayString and wxArrayInt. */
1490 void Set( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() )
1499 // Creates exclusive copy of current choices
1502 if ( m_data
->m_refCount
!= 1 )
1504 wxPGChoicesData
* data
= new wxPGChoicesData();
1505 data
->CopyDataFrom(m_data
);
1511 // Returns data, increases refcount.
1512 wxPGChoicesData
* GetData()
1514 wxASSERT( m_data
->m_refCount
!= 0xFFFFFFF );
1515 m_data
->m_refCount
++;
1519 // Returns plain data ptr - no refcounting stuff is done.
1520 wxPGChoicesData
* GetDataPtr() const { return m_data
; }
1522 // Changes ownership of data to you.
1523 wxPGChoicesData
* ExtractData()
1525 wxPGChoicesData
* data
= m_data
;
1526 m_data
= wxPGChoicesEmptyData
;
1530 wxArrayString
GetLabels() const;
1532 void operator= (const wxPGChoices
& a
)
1534 AssignData(a
.m_data
);
1537 wxPGChoiceEntry
& operator[](unsigned int i
)
1542 const wxPGChoiceEntry
& operator[](unsigned int i
) const
1548 // -----------------------------------------------------------------------