1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxPGProperty
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 #define wxNullProperty ((wxPGProperty*)NULL)
13 /** @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers
15 wxPGProperty::SetAttribute() and
16 wxPropertyGridInterface::SetPropertyAttribute()
17 accept one of these as attribute name argument .
19 You can use strings instead of constants. However, some of these
20 constants are redefined to use cached strings which may reduce
21 your binary size by some amount.
26 /** Set default value for property.
28 #define wxPG_ATTR_DEFAULT_VALUE wxS("DefaultValue")
30 /** Universal, int or double. Minimum value for numeric properties.
32 #define wxPG_ATTR_MIN wxS("Min")
34 /** Universal, int or double. Maximum value for numeric properties.
36 #define wxPG_ATTR_MAX wxS("Max")
38 /** Universal, string. When set, will be shown as text after the displayed
39 text value. Alternatively, if third column is enabled, text will be shown
40 there (for any type of property).
42 #define wxPG_ATTR_UNITS wxS("Units")
44 /** Universal, string. When set, will be shown in property's value cell
45 when displayed value string is empty, or value is unspecified.
47 #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp")
49 /** wxBoolProperty specific, int, default 0. When 1 sets bool property to
50 use checkbox instead of choice.
52 #define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox")
54 /** wxBoolProperty specific, int, default 0. When 1 sets bool property value
55 to cycle on double click (instead of showing the popup listbox).
57 #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING wxS("UseDClickCycling")
59 /** wxFloatProperty (and similar) specific, int, default -1. Sets the (max) precision
60 used when floating point value is rendered as text. The default -1 means infinite
63 #define wxPG_FLOAT_PRECISION wxS("Precision")
65 /** The text will be echoed as asterisks (wxTE_PASSWORD will be passed to textctrl etc).
67 #define wxPG_STRING_PASSWORD wxS("Password")
69 /** Define base used by a wxUIntProperty. Valid constants are
70 wxPG_BASE_OCT, wxPG_BASE_DEC, wxPG_BASE_HEX and wxPG_BASE_HEXL
71 (lowercase characters).
73 #define wxPG_UINT_BASE wxS("Base")
75 /** Define prefix rendered to wxUIntProperty. Accepted constants
76 wxPG_PREFIX_NONE, wxPG_PREFIX_0x, and wxPG_PREFIX_DOLLAR_SIGN.
77 <b>Note:</b> Only wxPG_PREFIX_NONE works with Decimal and Octal
80 #define wxPG_UINT_PREFIX wxS("Prefix")
82 /** wxFileProperty/wxImageFileProperty specific, wxChar*, default is detected/varies.
83 Sets the wildcard used in the triggered wxFileDialog. Format is the
86 #define wxPG_FILE_WILDCARD wxS("Wildcard")
88 /** wxFileProperty/wxImageFileProperty specific, int, default 1.
89 When 0, only the file name is shown (i.e. drive and directory are hidden).
91 #define wxPG_FILE_SHOW_FULL_PATH wxS("ShowFullPath")
93 /** Specific to wxFileProperty and derived properties, wxString, default empty.
94 If set, then the filename is shown relative to the given path string.
96 #define wxPG_FILE_SHOW_RELATIVE_PATH wxS("ShowRelativePath")
98 /** Specific to wxFileProperty and derived properties, wxString, default is empty.
99 Sets the initial path of where to look for files.
101 #define wxPG_FILE_INITIAL_PATH wxS("InitialPath")
103 /** Specific to wxFileProperty and derivatives, wxString, default is empty.
104 Sets a specific title for the dir dialog.
106 #define wxPG_FILE_DIALOG_TITLE wxS("DialogTitle")
108 /** Specific to wxDirProperty, wxString, default is empty.
109 Sets a specific message for the dir dialog.
111 #define wxPG_DIR_DIALOG_MESSAGE wxS("DialogMessage")
113 /** Sets displayed date format for wxDateProperty.
115 #define wxPG_DATE_FORMAT wxS("DateFormat")
117 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
118 is wxDP_DEFAULT | wxDP_SHOWCENTURY.
120 #define wxPG_DATE_PICKER_STYLE wxS("PickerStyle")
122 /** SpinCtrl editor, int or double. How much number changes when button is
123 pressed (or up/down on keybard).
125 #define wxPG_ATTR_SPINCTRL_STEP wxS("Step")
127 /** SpinCtrl editor, bool. If true, value wraps at Min/Max.
129 #define wxPG_ATTR_SPINCTRL_WRAP wxS("Wrap")
131 /** wxMultiChoiceProperty, int. If 0, no user strings allowed. If 1, user strings
132 appear before list strings. If 2, user strings appear after list string.
134 #define wxPG_ATTR_MULTICHOICE_USERSTRINGMODE wxS("UserStringMode")
136 /** wxColourProperty and its kind, int, default 1. Setting this attribute to 0 hides custom
137 colour from property's list of choices.
139 #define wxPG_COLOUR_ALLOW_CUSTOM wxS("AllowCustom")
144 // -----------------------------------------------------------------------
146 /** @class wxPGProperty
148 wxPGProperty is base class for all wxPropertyGrid properties. In
149 sections below we cover few related topics.
151 @li @ref pgproperty_properties
152 @li @ref pgproperty_creating
154 @section pgproperty_properties Supplied Ready-to-use Property Classes
156 Here is a list and short description of supplied fully-functional
157 property classes. They are located in either props.h or advprops.h.
159 @li @ref wxArrayStringProperty
160 @li @ref wxBoolProperty
161 @li @ref wxColourProperty
162 @li @ref wxCursorProperty
163 @li @ref wxDateProperty
164 @li @ref wxDirProperty
165 @li @ref wxEditEnumProperty
166 @li @ref wxEnumProperty
167 @li @ref wxFileProperty
168 @li @ref wxFlagsProperty
169 @li @ref wxFloatProperty
170 @li @ref wxFontProperty
171 @li @ref wxImageFileProperty
172 @li @ref wxIntProperty
173 @li @ref wxLongStringProperty
174 @li @ref wxMultiChoiceProperty
175 @li @ref wxPropertyCategory
176 @li @ref wxStringProperty
177 @li @ref wxSystemColourProperty
178 @li @ref wxUIntProperty
180 @subsection wxPropertyCategory
182 Not an actual property per se, but a header for a group of properties.
183 Regardless inherits from wxPGProperty.
185 @subsection wxStringProperty
187 Simple string property. wxPG_STRING_PASSWORD attribute may be used
188 to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl.
190 @remarks wxStringProperty has a special trait: if it has value of
191 "<composed>", and also has child properties, then its displayed
192 value becomes composition of child property values, similar as
193 with wxFontProperty, for instance.
195 @subsection wxIntProperty
197 Like wxStringProperty, but converts text to a signed long integer.
198 wxIntProperty seamlessly supports 64-bit integers (ie. wxLongLong).
199 To safely convert variant to integer, use code like this:
203 ll << property->GetValue();
206 wxLongLong ll = propertyGrid->GetPropertyValueAsLong(property);
209 @subsection wxUIntProperty
211 Like wxIntProperty, but displays value as unsigned int. To set
212 the prefix used globally, manipulate wxPG_UINT_PREFIX string attribute.
213 To set the globally used base, manipulate wxPG_UINT_BASE int
214 attribute. Regardless of current prefix, understands (hex) values starting
215 with both "0x" and "$".
216 Like wxIntProperty, wxUIntProperty seamlessly supports 64-bit unsigned
217 integers (ie. wxULongLong). Same wxVariant safety rules apply.
219 @subsection wxFloatProperty
221 Like wxStringProperty, but converts text to a double-precision floating point.
222 Default float-to-text precision is 6 decimals, but this can be changed
223 by modifying wxPG_FLOAT_PRECISION attribute.
225 @subsection wxBoolProperty
227 Represents a boolean value. wxChoice is used as editor control, by the
228 default. wxPG_BOOL_USE_CHECKBOX attribute can be set to true inorder to use
231 @subsection wxLongStringProperty
233 Like wxStringProperty, but has a button that triggers a small text editor
234 dialog. Note that in long string values, tabs are represented by "\t" and
237 @subsection wxDirProperty
239 Like wxLongStringProperty, but the button triggers dir selector instead.
240 Supported properties (all with string value): wxPG_DIR_DIALOG_MESSAGE.
242 @subsection wxFileProperty
244 Like wxLongStringProperty, but the button triggers file selector instead.
245 Default wildcard is "All files..." but this can be changed by setting
246 wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details).
247 Attribute wxPG_FILE_SHOW_FULL_PATH can be set to false inorder to show
248 only the filename, not the entire path.
250 @subsection wxEnumProperty
252 Represents a single selection from a list of choices -
253 wxOwnerDrawnComboBox is used to edit the value.
255 @subsection wxFlagsProperty
257 Represents a bit set that fits in a long integer. wxBoolProperty sub-properties
258 are created for editing individual bits. Textctrl is created to manually edit
259 the flags as a text; a continous sequence of spaces, commas and semicolons
260 is considered as a flag id separator.
261 <b>Note: </b> When changing "choices" (ie. flag labels) of wxFlagsProperty, you
262 will need to use wxPGProperty::SetChoices() - otherwise they will not get updated
265 @subsection wxArrayStringProperty
267 Allows editing of a list of strings in wxTextCtrl and in a separate dialog.
269 @subsection wxDateProperty
271 wxDateTime property. Default editor is DatePickerCtrl, altough TextCtrl
272 should work as well. wxPG_DATE_FORMAT attribute can be used to change
273 string wxDateTime::Format uses (altough default is recommended as it is
274 locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window
275 style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY).
277 @subsection wxEditEnumProperty
279 Represents a string that can be freely edited or selected from list of choices -
280 custom combobox control is used to edit the value.
282 @subsection wxMultiChoiceProperty
284 Allows editing a multiple selection from a list of strings. This is
285 property is pretty much built around concept of wxMultiChoiceDialog.
286 It uses wxArrayString value.
288 @subsection wxImageFileProperty
290 Like wxFileProperty, but has thumbnail of the image in front of
291 the filename and autogenerates wildcard from available image handlers.
293 @subsection wxColourProperty
295 <b>Useful alternate editor:</b> Choice.
297 Represents wxColour. wxButton is used to trigger a colour picker dialog.
299 @subsection wxFontProperty
301 Represents wxFont. Various sub-properties are used to edit individual
304 @subsection wxSystemColourProperty
306 Represents wxColour and a system colour index. wxChoice is used to edit
307 the value. Drop-down list has color images. Note that value type
308 is wxColourPropertyValue instead of wxColour.
310 class wxColourPropertyValue : public wxObject
313 // An integer value relating to the colour, and which exact
314 // meaning depends on the property with which it is used.
316 // For wxSystemColourProperty:
317 // Any of wxSYS_COLOUR_XXX, or any web-colour ( use wxPG_TO_WEB_COLOUR
318 // macro - (currently unsupported) ), or wxPG_COLOUR_CUSTOM.
321 // Resulting colour. Should be correct regardless of type.
326 @subsection wxCursorProperty
328 Represents a wxCursor. wxChoice is used to edit the value.
329 Drop-down list has cursor images under some (wxMSW) platforms.
332 @section pgproperty_creating Creating Custom Properties
334 New properties can be created by subclassing wxPGProperty or one
335 of the provided property classes, and (re)implementing necessary
336 member functions. Below, each virtual member function has ample
337 documentation about its purpose and any odd details which to keep
340 Here is a very simple 'template' code:
343 class MyProperty : public wxPGProperty
346 // All arguments of ctor must have a default value -
347 // use wxPG_LABEL for label and name
348 MyProperty( const wxString& label = wxPG_LABEL,
349 const wxString& name = wxPG_LABEL,
350 const wxString& value = wxEmptyString )
352 // m_value is wxVariant
356 virtual ~MyProperty() { }
358 const wxPGEditor* DoGetEditorClass() const
360 // Determines editor used by property.
361 // You can replace 'TextCtrl' below with any of these
362 // builtin-in property editor identifiers: Choice, ComboBox,
363 // TextCtrlAndButton, ChoiceAndButton, CheckBox, SpinCtrl,
365 return wxPGEditor_TextCtrl;
368 virtual wxString GetValueAsString( int argFlags ) const
370 // TODO: Return property value in string format
373 virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags )
375 // TODO: Adapt string to property value.
382 Since wxPGProperty derives from wxObject, you can use standard
383 DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS macros. From the
384 above example they were omitted for sake of simplicity, and besides,
385 they are only really needed if you need to use wxRTTI with your
388 You can change the 'value type' of a property by simply assigning different
389 type of variant with SetValue. <b>It is mandatory to implement
390 wxVariantData class for all data types used as property values.</b>
391 You can use macros declared in wxPropertyGrid headers. For instance:
395 // (If you need to have export declaration, use version of macros
396 // with _EXPORTED postfix)
397 WX_PG_DECLARE_VARIANT_DATA(MyDataClass)
400 WX_PG_IMPLEMENT_VARIANT_DATA(MyDataClass)
402 // Or, if you don't have valid == operator:
403 WX_PG_IMPLEMENT_VARIANT_DATA_DUMMY_EQ(MyDataClass)
409 class wxPGProperty
: public wxObject
412 typedef wxUint32 FlagType
;
421 Non-abstract property classes should have constructor of this style:
425 MyProperty( const wxString& label, const wxString& name, const T& value )
428 // Generally recommended way to set the initial value
429 // (as it should work in pretty much 100% of cases).
434 // If has private child properties then create them here. For example:
435 // AddChild( new wxStringProperty( "Subprop 1", wxPG_LABEL, value.GetSubProp1() ) );
440 wxPGProperty( const wxString
& label
, const wxString
& name
);
443 Virtual destructor. It is customary for derived properties to implement this.
445 virtual ~wxPGProperty();
448 This virtual function is called after m_value has been set.
451 - If m_value was set to Null variant (ie. unspecified value), OnSetValue()
453 - m_value may be of any variant type. Typically properties internally support only
454 one variant type, and as such OnSetValue() provides a good opportunity to convert
455 supported values into internal type.
456 - Default implementation does nothing.
458 virtual void OnSetValue();
461 Override this to return something else than m_value as the value.
463 virtual wxVariant
DoGetValue() const { return m_value
; }
466 Implement this function in derived class to check the value.
467 Return true if it is ok. Returning false prevents property change events
471 - Default implementation always returns true.
473 virtual bool ValidateValue( wxVariant
& value
, wxPGValidationInfo
& validationInfo
) const;
476 Converts 'text' into proper value 'variant'. Returns true if new (different than
477 m_value) value could be interpreted from the text.
479 If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable
480 one (they may be different).
481 If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of composite
482 property string value (as generated by GetValueAsString() called with this same
486 Default implementation converts semicolon delimited tokens into child values. Only
487 works for properties with children.
489 virtual bool StringToValue( wxVariant
& variant
, const wxString
& text
, int argFlags
= 0 ) const;
492 Converts 'number' (including choice selection) into proper value 'variant'.
493 Returns true if new (different than m_value) value could be interpreted from the integer.
495 If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable one.
498 - If property is not supposed to use choice or spinctrl or other editor
499 with int-based value, it is not necessary to implement this method.
500 - Default implementation simply assign given int to m_value.
501 - If property uses choice control, and displays a dialog on some choice items,
502 then it is preferred to display that dialog in IntToValue instead of OnEvent.
504 virtual bool IntToValue( wxVariant
& value
, int number
, int argFlags
= 0 ) const;
507 Returns text representation of property's value.
510 If wxPG_FULL_VALUE is set, returns complete, storable string value instead of displayable.
511 If wxPG_EDITABLE_VALUE is set, returns string value that must be editable in textctrl.
512 If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to display
513 as a part of composite property string value.
516 Default implementation returns string composed from text representations of
519 virtual wxString
GetValueAsString( int argFlags
= 0 ) const;
522 Converts string to a value, and if successful, calls SetValue() on it.
523 Default behavior is to do nothing.
525 String to get the value from.
527 true if value was changed.
529 bool SetValueFromString( const wxString
& text
, int flags
= 0 );
532 Converts integer to a value, and if succesful, calls SetValue() on it.
533 Default behavior is to do nothing.
535 Int to get the value from.
537 If has wxPG_FULL_VALUE, then the value given is a actual value and not an index.
539 True if value was changed.
541 bool SetValueFromInt( long value
, int flags
= 0 );
544 Returns size of the custom painted image in front of property. This method
545 must be overridden to return non-default value if OnCustomPaint is to be
548 Normally -1, but can be an index to the property's list of items.
550 - Default behavior is to return wxSize(0,0), which means no image.
551 - Default image width or height is indicated with dimension -1.
552 - You can also return wxPG_DEFAULT_IMAGE_SIZE which equals wxSize(-1, -1).
554 virtual wxSize
OnMeasureImage( int item
= -1 ) const;
557 Events received by editor widgets are processed here. Note that editor class
558 usually processes most events. Some, such as button press events of
559 TextCtrlAndButton class, can be handled here. Also, if custom handling
560 for regular events is desired, then that can also be done (for example,
561 wxSystemColourProperty custom handles wxEVT_COMMAND_CHOICE_SELECTED
562 to display colour picker dialog when 'custom' selection is made).
564 If the event causes value to be changed, SetValueInEvent()
565 should be called to set the new value.
570 Should return true if any changes in value should be reported.
572 - If property uses choice control, and displays a dialog on some choice items,
573 then it is preferred to display that dialog in IntToValue instead of OnEvent.
575 virtual bool OnEvent( wxPropertyGrid
* propgrid
, wxWindow
* wnd_primary
, wxEvent
& event
);
578 Called after value of a child property has been altered. Note that this function is
579 usually called at the time that value of this property, or given child property, is
580 still pending for change.
582 Sample pseudo-code implementation:
585 void MyProperty::ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const
587 // Acquire reference to actual type of data stored in variant
588 // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros were used to create
589 // the variant class).
590 T& data = TFromVariant(thisValue);
592 // Copy childValue into data.
593 switch ( childIndex )
596 data.SetSubProp1( childvalue.GetLong() );
599 data.SetSubProp2( childvalue.GetString() );
607 Value of this property, that should be altered.
609 Index of child changed (you can use Item(childIndex) to get).
611 Value of the child property.
613 virtual void ChildChanged( wxVariant
& thisValue
, int childIndex
, wxVariant
& childValue
) const;
616 Returns pointer to an instance of used editor.
618 virtual const wxPGEditor
* DoGetEditorClass() const;
621 Returns pointer to the wxValidator that should be used
622 with the editor of this property (NULL for no validator).
623 Setting validator explicitly via SetPropertyValidator
626 In most situations, code like this should work well
627 (macros are used to maintain one actual validator instance,
628 so on the second call the function exits within the first
633 wxValidator* wxMyPropertyClass::DoGetValidator () const
635 WX_PG_DOGETVALIDATOR_ENTRY()
637 wxMyValidator* validator = new wxMyValidator(...);
639 ... prepare validator...
641 WX_PG_DOGETVALIDATOR_EXIT(validator)
647 You can get common filename validator by returning
648 wxFileProperty::GetClassValidator(). wxDirProperty,
649 for example, uses it.
651 virtual wxValidator
* DoGetValidator () const;
654 Override to paint an image in front of the property value text or drop-down
655 list item (but only if wxPGProperty::OnMeasureImage is overridden as well).
657 If property's OnMeasureImage() returns size that has height != 0 but less than
658 row height ( < 0 has special meanings), wxPropertyGrid calls this method to
659 draw a custom image in a limited area in front of the editor control or
660 value text/graphics, and if control has drop-down list, then the image is
661 drawn there as well (even in the case OnMeasureImage() returned higher height
664 NOTE: Following applies when OnMeasureImage() returns a "flexible" height (
665 using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable height items:
666 If rect.x is < 0, then this is a measure item call, which means that
667 dc is invalid and only thing that should be done is to set paintdata.m_drawnHeight
668 to the height of the image of item at index paintdata.m_choiceItem. This call
669 may be done even as often as once every drop-down popup show.
674 Box reserved for custom graphics. Includes surrounding rectangle, if any.
675 If x is < 0, then this is a measure item call (see above).
677 wxPGPaintData structure with much useful data about painted item.
682 const wxPropertyGrid* m_parent;
684 // Normally -1, otherwise index to drop-down list item that has to be drawn.
687 // Set to drawn width in OnCustomPaint (optional).
690 // In a measure item call, set this to the height of item at m_choiceItem index
696 - You can actually exceed rect width, but if you do so then paintdata.m_drawnWidth
697 must be set to the full width drawn in pixels.
698 - Due to technical reasons, rect's height will be default even if custom height
699 was reported during measure call.
700 - Brush is guaranteed to be default background colour. It has been already used to
701 clear the background of area being painted. It can be modified.
702 - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper colour) pen for
703 drawing framing rectangle. It can be changed as well.
705 @see GetValueAsString()
707 virtual void OnCustomPaint( wxDC
& dc
, const wxRect
& rect
, wxPGPaintData
& paintdata
);
710 Returns used wxPGCellRenderer instance for given property column (label=0, value=1).
712 Default implementation returns editor's renderer for all columns.
714 virtual wxPGCellRenderer
* GetCellRenderer( int column
) const;
717 Returns which choice is currently selected. Only applies to properties
720 Needs to reimplemented in derived class if property value does not
721 map directly to a choice. Integer as index, bool, and string usually do.
723 virtual int GetChoiceSelection() const;
726 Refresh values of child properties. Automatically called after value is set.
728 virtual void RefreshChildren();
731 Special handling for attributes of this property.
733 If returns false, then the attribute will be automatically stored in
736 Default implementation simply returns false.
738 virtual bool DoSetAttribute( const wxString
& name
, wxVariant
& value
);
741 Returns value of an attribute.
743 Override if custom handling of attributes is needed.
745 Default implementation simply return NULL variant.
747 virtual wxVariant
DoGetAttribute( const wxString
& name
) const;
750 Returns instance of a new wxPGEditorDialogAdapter instance, which is
751 used when user presses the (optional) button next to the editor control;
753 Default implementation returns NULL (ie. no action is generated when
756 virtual wxPGEditorDialogAdapter
* GetEditorDialog() const;
759 Returns wxPGCell of given column, NULL if none. If valid
760 object is returned, caller will gain its ownership.
762 wxPGCell
* AcquireCell( unsigned int column
)
764 if ( column
>= m_cells
.size() )
767 wxPGCell
* cell
= (wxPGCell
*) m_cells
[column
];
768 m_cells
[column
] = NULL
;
773 Append a new choice to property's list of choices.
776 Label for added choice.
779 Value for new choice. Do not specify if you wish this
780 to equal choice index.
783 Index to added choice.
785 int AddChoice( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
788 Properties which have private child properties should add them
789 with this function, called in their constructor.
791 void AddChild( wxPGProperty
* property
);
794 Adapts list variant into proper value using consecutive
795 ChildChanged() calls.
797 void AdaptListToValue( wxVariant
& list
, wxVariant
* value
) const;
800 Determines, recursively, if all children are not unspecified.
803 Assumes members in this wxVariant list as pending
806 bool AreAllChildrenSpecified( wxVariant
* pendingList
= NULL
) const;
809 Returns true if children of this property are component values (for instance,
810 points size, face name, and is_underlined are component values of a font).
812 bool AreChildrenComponents() const
814 if ( m_flags
& (wxPG_PROP_COMPOSED_VALUE
|wxPG_PROP_AGGREGATE
) )
821 Removes entry from property's wxPGChoices and editor control (if it is active).
823 If selected item is deleted, then the value is set to unspecified.
825 void DeleteChoice( int index
);
827 /** Deletes all child properties. */
830 /** Composes text from values of child properties. */
831 void GenerateComposedValue( wxString
& text
, int argFlags
= 0 ) const;
834 Returns property attribute value, null variant if not found.
836 wxVariant
GetAttribute( const wxString
& name
) const;
838 /** Returns named attribute, as string, if found. Otherwise defVal is returned.
840 wxString
GetAttribute( const wxString
& name
, const wxString
& defVal
) const;
842 /** Returns named attribute, as long, if found. Otherwise defVal is returned.
844 long GetAttributeAsLong( const wxString
& name
, long defVal
) const;
846 /** Returns named attribute, as double, if found. Otherwise defVal is returned.
848 double GetAttributeAsDouble( const wxString
& name
, double defVal
) const;
851 Returns attributes as list wxVariant.
853 wxVariant
GetAttributesAsList() const;
856 Returns editor used for given column. NULL for no editor.
858 const wxPGEditor
* GetColumnEditor( int column
) const
861 return GetEditorClass();
866 /** Returns property's base name (ie. parent's name is not added in any case) */
867 const wxString
& GetBaseName() const { return m_name
; }
870 Returns wxPGCell of given column, NULL if none. wxPGProperty
871 will retain ownership of the cell object.
873 wxPGCell
* GetCell( unsigned int column
) const
875 if ( column
>= m_cells
.size() )
878 return (wxPGCell
*) m_cells
[column
];
882 Returns number of child properties.
884 unsigned int GetChildCount() const;
887 Returns height of children, recursively, and
888 by taking expanded/collapsed status into account.
891 Line height. Pass result of GetGrid()->GetRowHeight() here.
894 Only used (internally) when finding property y-positions.
896 int GetChildrenHeight( int lh
, int iMax
= -1 ) const;
899 Returns read-only reference to property's list of choices.
901 const wxPGChoices
& GetChoices() const;
904 Returns client data (void*) of a property.
906 void* GetClientData() const;
908 /** Sets managed client object of a property.
910 wxClientData
*GetClientObject() const;
913 Returns property's default value. If property's value type is not
914 a built-in one, and "DefaultValue" attribute is not defined, then
915 this function usually returns Null variant.
917 wxVariant
GetDefaultValue() const;
919 /** Returns property's displayed text.
921 wxString
GetDisplayedString() const
923 return GetValueString(0);
927 Returns wxPGEditor that will be used and created when
928 property becomes selected. Returns more accurate value
929 than DoGetEditorClass().
931 const wxPGEditor
* GetEditorClass() const;
933 /** Returns property grid where property lies. */
934 wxPropertyGrid
* GetGrid() const;
937 Returns owner wxPropertyGrid, but only if one is currently on a page
938 displaying this property.
940 wxPropertyGrid
* GetGridIfDisplayed() const;
943 Returns property's help or description text.
947 const wxString
& GetHelpString() const;
950 Returns position in parent's array.
952 unsigned int GetIndexInParent() const;
954 /** Returns property's label. */
955 const wxString
& GetLabel() const { return m_label
; }
958 Returns last visible child property, recursively.
960 const wxPGProperty
* GetLastVisibleSubItem() const;
963 Returns highest level non-category, non-root parent. Useful when you
964 have nested wxCustomProperties/wxParentProperties.
966 @remarks If immediate parent is root or category, this will return the
969 wxPGProperty
* GetMainParent() const;
971 /** Returns maximum allowed length of property's text value.
973 int GetMaxLength() const
975 return (int) m_maxLen
;
978 /** Returns property's name with all (non-category, non-root) parents. */
979 wxString
GetName() const;
981 /** Return parent of property */
982 wxPGProperty
* GetParent() const { return m_parent
; }
985 Returns (direct) child property with given name (or NULL if not found).
987 wxPGProperty
* GetPropertyByName( const wxString
& name
) const;
989 /** Gets assignable version of property's validator. */
990 wxValidator
* GetValidator() const;
993 Returns property's value.
995 wxVariant
GetValue() const
1001 Returns bitmap that appears next to value text. Only returns non-NULL
1002 bitmap if one was set with SetValueImage().
1004 wxBitmap
* GetValueImage() const;
1007 To acquire property's value as string, you should use this
1008 function (instead of GetValueAsString()), as it may produce
1009 more accurate value in future versions.
1011 @see GetValueAsString()
1013 wxString
GetValueString( int argFlags
= 0 ) const;
1016 Returns value type used by this property.
1018 wxString
GetValueType() const
1020 return m_value
.GetType();
1024 Returns coordinate to the top y of the property. Note that the
1025 position of scrollbars is not taken into account.
1030 Returns true if property has even one visible child.
1032 bool HasVisibleChildren() const;
1035 Hides or reveals the property.
1038 @true for hide, @false for reveal.
1041 By default changes are applied recursively. Set this parameter wxPG_DONT_RECURSE to prevent this.
1043 bool Hide( bool hide
, int flags
= wxPG_RECURSE
);
1046 Returns index of given child property. wxNOT_FOUND if
1047 given property is not child of this.
1049 int Index( const wxPGProperty
* p
) const;
1052 Inserts a new choice to property's list of choices.
1058 Insertion position. Use wxNOT_FOUND to append.
1061 Value for new choice. Do not specify if you wish this
1062 to equal choice index.
1064 int InsertChoice( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1067 Returns @true if this property is actually a wxPropertyCategory.
1069 bool IsCategory() const;
1072 Returns @true if property is enabled.
1074 bool IsEnabled() const;
1077 Returns @true if property has visible children.
1079 bool IsExpanded() const;
1082 Returns @true if this property is actually a wxRootProperty.
1084 bool IsRoot() const { return (m_parent
== NULL
); }
1087 Returns @true if candidateParent is some parent of this property.
1089 bool IsSomeParent( wxPGProperty
* candidateParent
) const;
1092 Returns true if property has editable wxTextCtrl when selected.
1094 @remarks Altough disabled properties do not displayed editor, they still
1095 return @true here as being disabled is considered a temporary
1096 condition (unlike being read-only or having limited editing enabled).
1098 bool IsTextEditable() const;
1101 Returns @true if property's value is considered unspecified. This
1102 usually means that value is Null variant.
1104 bool IsValueUnspecified() const;
1107 Returns true if all parents expanded.
1109 bool IsVisible() const;
1112 Returns child property at index i.
1114 wxPGProperty
* Item( size_t i
) const;
1117 Updates property value in case there were last minute
1118 changes. If value was unspecified, it will be set to default.
1119 Use only for properties that have TextCtrl-based editor.
1121 @remarks If you have code similar to
1123 // Update the value in case of last minute changes
1124 if ( primary && propgrid->IsEditorsValueModified() )
1125 GetEditorClass()->CopyValueFromControl( this, primary );
1127 in wxPGProperty::OnEvent wxEVT_COMMAND_BUTTON_CLICKED handler,
1128 then replace it with call to this method.
1130 @return Returns @true if value changed.
1132 bool PrepareValueForDialogEditing( wxPropertyGrid
* propgrid
);
1135 If property's editor is active, then update it's value.
1137 void RefreshEditor();
1140 Sets an attribute for this property.
1143 Text identifier of attribute. See @ref propgrid_property_attributes.
1148 @remarks Setting attribute's value to Null variant will simply remove it
1149 from property's set of attributes.
1151 void SetAttribute( const wxString
& name
, wxVariant value
);
1154 Sets editor for a property.
1157 For builtin editors, use wxPGEditor_X, where X is builtin editor's
1158 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list).
1160 For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
1162 void SetEditor( const wxPGEditor
* editor
);
1165 Sets editor for a property, by editor name.
1167 void SetEditor( const wxString
& editorName
);
1170 Sets cell information for given column.
1172 Note that the property takes ownership of given wxPGCell instance.
1174 void SetCell( int column
, wxPGCell
* cellObj
);
1177 Sets new set of choices for property.
1179 @remarks This operation clears the property value.
1181 bool SetChoices( wxPGChoices
& choices
);
1184 If property has choices and they are not yet exclusive, new such copy
1185 of them will be created.
1187 void SetChoicesExclusive();
1190 Sets client data (void*) of a property.
1192 @remarks This untyped client data has to be deleted manually.
1194 void SetClientData( void* clientData
);
1196 /** Returns client object of a property.
1198 void SetClientObject(wxClientData
* clientObject
);
1201 Sets selected choice and changes property value.
1203 Tries to retain value type, although currently if it is not string,
1204 then it is forced to integer.
1206 void SetChoiceSelection( int newValue
);
1209 Sets property's help string, which is shown, for example, in
1210 wxPropertyGridManager's description text box.
1212 void SetHelpString( const wxString
& helpString
);
1215 Sets property's label.
1217 @remarks Properties under same parent may have same labels. However,
1218 property names must still remain unique.
1220 void SetLabel( const wxString
& label
) { m_label
= label
; }
1223 Set max length of text in text editor.
1225 bool SetMaxLength( int maxLen
);
1228 Sets property's "is it modified?" flag. Affects children recursively.
1230 void SetModifiedStatus( bool modified
);
1233 Sets new (base) name for property.
1235 void SetName( const wxString
& newName
);
1237 /** Sets wxValidator for a property */
1238 void SetValidator( const wxValidator
& validator
);
1241 Call this to set value of the property. Unlike methods in wxPropertyGrid,
1242 this does not automatically update the display.
1245 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through
1246 validation process and send property change event.
1248 If you need to change property value in event, based on user input, use
1249 SetValueInEvent() instead.
1252 Pointer to list variant that contains child values. Used to indicate
1253 which children should be marked as modified. Usually you just use NULL.
1256 Use wxPG_SETVAL_REFRESH_EDITOR to update editor control, if it
1259 void SetValue( wxVariant value
, wxVariant
* pList
= NULL
, int flags
= 0 );
1262 Set wxBitmap in front of the value. This bitmap may be ignored
1263 by custom cell renderers.
1265 void SetValueImage( wxBitmap
& bmp
);
1268 Call this function in OnEvent(), OnButtonClick() etc. to change the
1269 property value based on user input.
1271 @remarks This method is const since it doesn't actually modify value, but posts
1272 given variant as pending value, stored in wxPropertyGrid.
1274 void SetValueInEvent( wxVariant value
) const;
1277 Sets property's value to unspecified (ie. Null variant).
1279 void SetValueToUnspecified();
1282 Call with @false in OnSetValue() to cancel value changes after all
1283 (ie. cancel @true returned by StringToValue() or IntToValue()).
1285 void SetWasModified( bool set
= true );
1288 Updates composed values of parent non-category properties, recursively.
1289 Returns topmost property updated.
1291 wxPGProperty
* UpdateParentValues();
1294 Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
1296 bool UsesAutoUnspecified() const;
1300 /** @class wxPGChoices
1302 Helper class for managing choices of wxPropertyGrid properties.
1303 Each entry can have label, value, bitmap, text colour, and background colour.
1305 @library{wxpropgrid}
1308 class WXDLLIMPEXP_PROPGRID wxPGChoices
1311 typedef long ValArrItem
;
1314 Default constructor.
1318 /** Copy constructor. */
1319 wxPGChoices( const wxPGChoices
& a
);
1322 wxPGChoices( const wxChar
** labels
, const long* values
= NULL
);
1325 wxPGChoices( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() );
1328 wxPGChoices( wxPGChoicesData
* data
);
1334 Adds to current. If did not have own copies, creates them now. If was empty,
1335 identical to set except that creates copies.
1337 void Add( const wxChar
** labels
, const ValArrItem
* values
= NULL
);
1339 /** Version that works with wxArrayString. */
1340 void Add( const wxArrayString
& arr
, const ValArrItem
* values
= NULL
);
1342 /** Version that works with wxArrayString and wxArrayInt. */
1343 void Add( const wxArrayString
& arr
, const wxArrayInt
& arrint
);
1345 /** Adds single item. */
1346 wxPGChoiceEntry
& Add( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1348 /** Adds a single item, with bitmap. */
1349 wxPGChoiceEntry
& Add( const wxString
& label
, const wxBitmap
& bitmap
,
1350 int value
= wxPG_INVALID_VALUE
);
1352 /** Adds a single item with full entry information. */
1353 wxPGChoiceEntry
& Add( const wxPGChoiceEntry
& entry
)
1355 return Insert(entry
, -1);
1358 /** Adds single item, sorted. */
1359 wxPGChoiceEntry
& AddAsSorted( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1362 Assigns data from another set of choices.
1364 void Assign( const wxPGChoices
& a
)
1366 AssignData(a
.m_data
);
1370 Assigns data from another set of choices.
1372 void AssignData( wxPGChoicesData
* data
);
1379 if ( m_data
!= wxPGChoicesEmptyData
)
1384 Returns labe of item.
1386 const wxString
& GetLabel( size_t ind
) const;
1389 Returns number of items.
1391 size_t GetCount () const;
1394 Returns value of item;
1396 int GetValue( size_t ind
) const;
1399 Returns array of values matching the given strings. Unmatching strings
1400 result in wxPG_INVALID_VALUE entry in array.
1402 wxArrayInt
GetValuesForStrings( const wxArrayString
& strings
) const;
1405 Returns array of indices matching given strings. Unmatching strings
1406 are added to 'unmatched', if not NULL.
1408 wxArrayInt
GetIndicesForStrings( const wxArrayString
& strings
,
1409 wxArrayString
* unmatched
= NULL
) const;
1412 Returns @true if item at given index has a valid value;
1414 bool HasValue( unsigned int i
) const;
1417 Returns index of item with given label.
1419 int Index( const wxString
& label
) const;
1422 Returns index of item with given value.
1424 int Index( int val
) const;
1427 Inserts single item.
1429 wxPGChoiceEntry
& Insert( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1432 Inserts a single item with full entry information.
1434 wxPGChoiceEntry
& Insert( const wxPGChoiceEntry
& entry
, int index
);
1437 Returns false if this is a constant empty set of choices,
1438 which should not be modified.
1442 return ( m_data
!= wxPGChoicesEmptyData
);
1446 Returns item at given index.
1448 const wxPGChoiceEntry
& Item( unsigned int i
) const
1451 return *m_data
->Item(i
);
1455 Returns item at given index.
1457 wxPGChoiceEntry
& Item( unsigned int i
)
1460 return *m_data
->Item(i
);
1464 Removes count items starting at position nIndex.
1466 void RemoveAt(size_t nIndex
, size_t count
= 1);
1469 Sets contents from lists of strings and values.
1471 void Set( const wxChar
** labels
, const long* values
= NULL
);
1474 Sets contents from lists of strings and values.
1476 void Set( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() );
1479 Creates exclusive copy of current choices.
1481 void SetExclusive();
1484 Returns array of choice labels.
1486 wxArrayString
GetLabels() const;
1488 void operator= (const wxPGChoices
& a
)
1490 AssignData(a
.m_data
);
1493 wxPGChoiceEntry
& operator[](unsigned int i
)
1498 const wxPGChoiceEntry
& operator[](unsigned int i
) const
1504 // -----------------------------------------------------------------------