1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxPGProperty
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
10 #define wxNullProperty ((wxPGProperty*)NULL)
14 @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers
16 wxPGProperty::SetAttribute() and wxPropertyGridInterface::SetPropertyAttribute()
17 accept one of these as attribute name argument.
19 You can use strings instead of constants.
20 However, some of these constants are redefined to use cached strings which
21 may reduce your binary size by some amount.
26 /** Set default value for property.
28 #define wxPG_ATTR_DEFAULT_VALUE wxS("DefaultValue")
30 /** Universal, int or double. Minimum value for numeric properties.
32 #define wxPG_ATTR_MIN wxS("Min")
34 /** Universal, int or double. Maximum value for numeric properties.
36 #define wxPG_ATTR_MAX wxS("Max")
38 /** Universal, string. When set, will be shown as text after the displayed
39 text value. Alternatively, if third column is enabled, text will be shown
40 there (for any type of property).
42 #define wxPG_ATTR_UNITS wxS("Units")
44 /** When set, will be shown as 'greyed' text in property's value cell when
45 the actual displayed value is blank.
47 #define wxPG_ATTR_HINT wxS("Hint")
50 @deprecated Use "Hint" (wxPG_ATTR_HINT) instead.
52 #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp")
54 /** Universal, wxArrayString. Set to enable auto-completion in any
55 wxTextCtrl-based property editor.
57 #define wxPG_ATTR_AUTOCOMPLETE wxS("AutoComplete")
59 /** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
60 Default value is False.
62 When set to True, bool property will use check box instead of a
63 combo box as its editor control. If you set this attribute
64 for a wxFlagsProperty, it is automatically applied to child
67 #define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox")
69 /** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
70 Default value is False.
72 Set to True for the bool property to cycle value on double click
73 (instead of showing the popup listbox). If you set this attribute
74 for a wxFlagsProperty, it is automatically applied to child
77 #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING wxS("UseDClickCycling")
79 /** wxFloatProperty (and similar) specific, int, default -1. Sets the (max) precision
80 used when floating point value is rendered as text. The default -1 means infinite
83 #define wxPG_FLOAT_PRECISION wxS("Precision")
85 /** The text will be echoed as asterisks (wxTE_PASSWORD will be passed to textctrl etc).
87 #define wxPG_STRING_PASSWORD wxS("Password")
89 /** Define base used by a wxUIntProperty. Valid constants are
90 wxPG_BASE_OCT, wxPG_BASE_DEC, wxPG_BASE_HEX and wxPG_BASE_HEXL
91 (lowercase characters).
93 #define wxPG_UINT_BASE wxS("Base")
95 /** Define prefix rendered to wxUIntProperty. Accepted constants
96 wxPG_PREFIX_NONE, wxPG_PREFIX_0x, and wxPG_PREFIX_DOLLAR_SIGN.
97 <b>Note:</b> Only wxPG_PREFIX_NONE works with Decimal and Octal
100 #define wxPG_UINT_PREFIX wxS("Prefix")
102 /** wxFileProperty/wxImageFileProperty specific, wxChar*, default is detected/varies.
103 Sets the wildcard used in the triggered wxFileDialog. Format is the
106 #define wxPG_FILE_WILDCARD wxS("Wildcard")
108 /** wxFileProperty/wxImageFileProperty specific, int, default 1.
109 When 0, only the file name is shown (i.e. drive and directory are hidden).
111 #define wxPG_FILE_SHOW_FULL_PATH wxS("ShowFullPath")
113 /** Specific to wxFileProperty and derived properties, wxString, default empty.
114 If set, then the filename is shown relative to the given path string.
116 #define wxPG_FILE_SHOW_RELATIVE_PATH wxS("ShowRelativePath")
118 /** Specific to wxFileProperty and derived properties, wxString, default is empty.
119 Sets the initial path of where to look for files.
121 #define wxPG_FILE_INITIAL_PATH wxS("InitialPath")
123 /** Specific to wxFileProperty and derivatives, wxString, default is empty.
124 Sets a specific title for the dir dialog.
126 #define wxPG_FILE_DIALOG_TITLE wxS("DialogTitle")
128 /** Specific to wxDirProperty, wxString, default is empty.
129 Sets a specific message for the dir dialog.
131 #define wxPG_DIR_DIALOG_MESSAGE wxS("DialogMessage")
134 wxArrayStringProperty's string delimiter character. If this is aquotation
135 mark or hyphen, then strings will be quoted instead (with given
138 Default delimiter is quotation mark.
140 #define wxPG_ARRAY_DELIMITER wxS("Delimiter")
142 /** Sets displayed date format for wxDateProperty.
144 #define wxPG_DATE_FORMAT wxS("DateFormat")
146 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
147 is wxDP_DEFAULT | wxDP_SHOWCENTURY. Using wxDP_ALLOWNONE will enable
148 better unspecified value support in the editor.
150 #define wxPG_DATE_PICKER_STYLE wxS("PickerStyle")
152 /** SpinCtrl editor, int or double. How much number changes when button is
153 pressed (or up/down on keybard).
155 #define wxPG_ATTR_SPINCTRL_STEP wxS("Step")
157 /** SpinCtrl editor, bool. If @true, value wraps at Min/Max.
159 #define wxPG_ATTR_SPINCTRL_WRAP wxS("Wrap")
161 /** SpinCtrl editor, bool. If @true, value can also by changed by moving
162 mouse when left mouse button is being pressed.
164 #define wxPG_ATTR_SPINCTRL_MOTIONSPIN wxS("MotionSpin")
166 /** wxMultiChoiceProperty, int. If 0, no user strings allowed. If 1, user strings
167 appear before list strings. If 2, user strings appear after list string.
169 #define wxPG_ATTR_MULTICHOICE_USERSTRINGMODE wxS("UserStringMode")
171 /** wxColourProperty and its kind, int, default 1. Setting this attribute to 0 hides custom
172 colour from property's list of choices.
174 #define wxPG_COLOUR_ALLOW_CUSTOM wxS("AllowCustom")
180 /** @section propgrid_propflags wxPGProperty Flags
184 enum wxPGPropertyFlags
187 /** Indicates bold font.
189 wxPG_PROP_MODIFIED
= 0x0001,
191 /** Disables ('greyed' text and editor does not activate) property.
193 wxPG_PROP_DISABLED
= 0x0002,
195 /** Hider button will hide this property.
197 wxPG_PROP_HIDDEN
= 0x0004,
199 /** This property has custom paint image just in front of its value.
200 If property only draws custom images into a popup list, then this
201 flag should not be set.
203 wxPG_PROP_CUSTOMIMAGE
= 0x0008,
205 /** Do not create text based editor for this property (but button-triggered
206 dialog and choice are ok).
208 wxPG_PROP_NOEDITOR
= 0x0010,
210 /** Property is collapsed, ie. it's children are hidden.
212 wxPG_PROP_COLLAPSED
= 0x0020,
215 If property is selected, then indicates that validation failed for pending
218 If property is not selected, then indicates that the the actual property
219 value has failed validation (NB: this behavior is not currently supported,
220 but may be used in future).
222 wxPG_PROP_INVALID_VALUE
= 0x0040,
226 /** Switched via SetWasModified(). Temporary flag - only used when
227 setting/changing property value.
229 wxPG_PROP_WAS_MODIFIED
= 0x0200,
232 If set, then child properties (if any) are private, and should be
233 "invisible" to the application.
235 wxPG_PROP_AGGREGATE
= 0x0400,
237 /** If set, then child properties (if any) are copies and should not
240 wxPG_PROP_CHILDREN_ARE_COPIES
= 0x0800,
243 Classifies this item as a non-category.
245 Used for faster item type identification.
247 wxPG_PROP_PROPERTY
= 0x1000,
250 Classifies this item as a category.
252 Used for faster item type identification.
254 wxPG_PROP_CATEGORY
= 0x2000,
256 /** Classifies this item as a property that has children, but is not aggregate
257 (ie children are not private).
259 wxPG_PROP_MISC_PARENT
= 0x4000,
261 /** Property is read-only. Editor is still created for wxTextCtrl-based
262 property editors. For others, editor is not usually created because
263 they do implement wxTE_READONLY style or equivalent.
265 wxPG_PROP_READONLY
= 0x8000,
268 // NB: FLAGS ABOVE 0x8000 CANNOT BE USED WITH PROPERTY ITERATORS
271 /** Property's value is composed from values of child properties.
273 This flag cannot be used with property iterators.
275 wxPG_PROP_COMPOSED_VALUE
= 0x00010000,
277 /** Common value of property is selectable in editor.
279 This flag cannot be used with property iterators.
281 wxPG_PROP_USES_COMMON_VALUE
= 0x00020000,
283 /** Property can be set to unspecified value via editor.
284 Currently, this applies to following properties:
285 - wxIntProperty, wxUIntProperty, wxFloatProperty, wxEditEnumProperty:
289 This flag cannot be used with property iterators.
291 @see wxPGProperty::SetAutoUnspecified()
293 wxPG_PROP_AUTO_UNSPECIFIED
= 0x00040000,
295 /** Indicates the bit useable by derived properties.
297 wxPG_PROP_CLASS_SPECIFIC_1
= 0x00080000,
299 /** Indicates the bit useable by derived properties.
301 wxPG_PROP_CLASS_SPECIFIC_2
= 0x00100000,
303 /** Indicates that the property is being deleted and should be ignored.
305 wxPG_PROP_BEING_DELETED
= 0x00200000
311 #define wxPG_PROP_MAX wxPG_PROP_AUTO_UNSPECIFIED
313 /** Property with children must have one of these set, otherwise iterators
314 will not work correctly.
315 Code should automatically take care of this, however.
317 #define wxPG_PROP_PARENTAL_FLAGS \
318 ((wxPGPropertyFlags)(wxPG_PROP_AGGREGATE | \
319 wxPG_PROP_CATEGORY | \
320 wxPG_PROP_MISC_PARENT))
329 wxPGProperty is base class for all wxPropertyGrid properties. In
330 sections below we cover few related topics.
332 @li @ref pgproperty_properties
333 @li @ref pgproperty_creating
335 @section pgproperty_properties Supplied Ready-to-use Property Classes
337 Here is a list and short description of supplied fully-functional
338 property classes. They are located in either props.h or advprops.h.
340 @li @ref wxArrayStringProperty
341 @li @ref wxBoolProperty
342 @li @ref wxColourProperty
343 @li @ref wxCursorProperty
344 @li @ref wxDateProperty
345 @li @ref wxDirProperty
346 @li @ref wxEditEnumProperty
347 @li @ref wxEnumProperty
348 @li @ref wxFileProperty
349 @li @ref wxFlagsProperty
350 @li @ref wxFloatProperty
351 @li @ref wxFontProperty
352 @li @ref wxImageFileProperty
353 @li @ref wxIntProperty
354 @li @ref wxLongStringProperty
355 @li @ref wxMultiChoiceProperty
356 @li @ref wxPropertyCategory
357 @li @ref wxStringProperty
358 @li @ref wxSystemColourProperty
359 @li @ref wxUIntProperty
361 @subsection wxPropertyCategory
363 Not an actual property per se, but a header for a group of properties.
364 Regardless inherits from wxPGProperty, and supports displaying 'labels'
365 for columns other than the first one. Easiest way to set category's
366 label for second column is to call wxPGProperty::SetValue() with string
369 @subsection wxStringProperty
371 Simple string property. wxPG_STRING_PASSWORD attribute may be used
372 to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl.
373 wxPG_ATTR_AUTOCOMPLETE attribute may be used to enable auto-completion
374 (use a wxArrayString value), and is also supported by any property that
375 happens to use a wxTextCtrl-based editor.
377 @remarks wxStringProperty has a special trait: if it has value of
378 "<composed>", and also has child properties, then its displayed
379 value becomes composition of child property values, similar as
380 with wxFontProperty, for instance.
382 @subsection wxIntProperty
384 Like wxStringProperty, but converts text to a signed long integer.
385 wxIntProperty seamlessly supports 64-bit integers (ie. wxLongLong).
386 To safely convert variant to integer, use code like this:
390 ll << property->GetValue();
393 wxLongLong ll = propertyGrid->GetPropertyValueAsLong(property);
396 @subsection wxUIntProperty
398 Like wxIntProperty, but displays value as unsigned int. To set
399 the prefix used globally, manipulate wxPG_UINT_PREFIX string attribute.
400 To set the globally used base, manipulate wxPG_UINT_BASE int
401 attribute. Regardless of current prefix, understands (hex) values starting
402 with both "0x" and "$".
403 Like wxIntProperty, wxUIntProperty seamlessly supports 64-bit unsigned
404 integers (ie. wxULongLong). Same wxVariant safety rules apply.
406 @subsection wxFloatProperty
408 Like wxStringProperty, but converts text to a double-precision floating point.
409 Default float-to-text precision is 6 decimals, but this can be changed
410 by modifying wxPG_FLOAT_PRECISION attribute.
412 Note that when displaying the value, sign is omitted if the resulting
413 textual representation is effectively zero (for example, -0.0001 with
414 precision of 3 will become 0.0 instead of -0.0). This behavior is unlike
415 what C standard library does, but should result in better end-user
416 experience in almost all cases.
418 @subsection wxBoolProperty
420 Represents a boolean value. wxChoice is used as editor control, by the
421 default. wxPG_BOOL_USE_CHECKBOX attribute can be set to true inorder to use
424 @subsection wxLongStringProperty
426 Like wxStringProperty, but has a button that triggers a small text editor
427 dialog. Note that in long string values, tabs are represented by "\t" and
430 To display custom dialog on button press, you can subclass
431 wxLongStringProperty and implement OnButtonClick, like this:
434 virtual bool OnButtonClick( wxPropertyGrid* propGrid, wxString& value )
436 wxSize dialogSize(...size of your dialog...);
438 wxPoint dlgPos = propGrid->GetGoodEditorDialogPosition(this,
441 // Create dialog dlg at dlgPos. Use value as initial string
445 if ( dlg.ShowModal() == wxID_OK )
447 value = dlg.GetStringValue);
454 Also, if you wish not to have line breaks and tabs translated to
455 escape sequences, then do following in constructor of your subclass:
458 m_flags |= wxPG_PROP_NO_ESCAPE;
461 @subsection wxDirProperty
463 Like wxLongStringProperty, but the button triggers dir selector instead.
464 Supported properties (all with string value): wxPG_DIR_DIALOG_MESSAGE.
466 @subsection wxFileProperty
468 Like wxLongStringProperty, but the button triggers file selector instead.
469 Default wildcard is "All files..." but this can be changed by setting
470 wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details).
471 Attribute wxPG_FILE_SHOW_FULL_PATH can be set to @false inorder to show
472 only the filename, not the entire path.
474 @subsection wxEnumProperty
476 Represents a single selection from a list of choices -
477 wxOwnerDrawnComboBox is used to edit the value.
479 @subsection wxFlagsProperty
481 Represents a bit set that fits in a long integer. wxBoolProperty sub-
482 properties are created for editing individual bits. Textctrl is created to
483 manually edit the flags as a text; a continous sequence of spaces, commas
484 and semicolons are considered as a flag id separator.
486 <b>Note:</b> When changing "choices" (ie. flag labels) of wxFlagsProperty,
487 you will need to use wxPGProperty::SetChoices() - otherwise they will not
488 get updated properly.
490 wxFlagsProperty supports the same attributes as wxBoolProperty.
492 @subsection wxArrayStringProperty
494 Allows editing of a list of strings in wxTextCtrl and in a separate
495 dialog. Supports "Delimiter" attribute, which defaults to comma (',').
497 @subsection wxDateProperty
499 wxDateTime property. Default editor is DatePickerCtrl, altough TextCtrl
500 should work as well. wxPG_DATE_FORMAT attribute can be used to change
501 string wxDateTime::Format uses (altough default is recommended as it is
502 locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window
503 style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY).
504 Using wxDP_ALLOWNONE will enable better unspecified value support.
506 @subsection wxEditEnumProperty
508 Represents a string that can be freely edited or selected from list of choices -
509 custom combobox control is used to edit the value.
511 @subsection wxMultiChoiceProperty
513 Allows editing a multiple selection from a list of strings. This is
514 property is pretty much built around concept of wxMultiChoiceDialog.
515 It uses wxArrayString value.
517 @subsection wxImageFileProperty
519 Like wxFileProperty, but has thumbnail of the image in front of
520 the filename and autogenerates wildcard from available image handlers.
522 @subsection wxColourProperty
524 <b>Useful alternate editor:</b> Choice.
526 Represents wxColour. wxButton is used to trigger a colour picker dialog.
527 There are various sub-classing opportunities with this class. See
528 below in wxSystemColourProperty section for details.
530 @subsection wxFontProperty
532 Represents wxFont. Various sub-properties are used to edit individual
535 @subsection wxSystemColourProperty
537 Represents wxColour and a system colour index. wxChoice is used to edit
538 the value. Drop-down list has color images. Note that value type
539 is wxColourPropertyValue instead of wxColour (which wxColourProperty
543 class wxColourPropertyValue : public wxObject
546 // An integer value relating to the colour, and which exact
547 // meaning depends on the property with which it is used.
549 // For wxSystemColourProperty:
550 // Any of wxSYS_COLOUR_XXX, or any web-colour ( use wxPG_TO_WEB_COLOUR
551 // macro - (currently unsupported) ), or wxPG_COLOUR_CUSTOM.
554 // Resulting colour. Should be correct regardless of type.
559 in wxSystemColourProperty, and its derived class wxColourProperty, there
560 are various sub-classing features. To set basic list list of colour
561 names, call wxPGProperty::SetChoices().
564 // Override in derived class to customize how colours are translated
566 virtual wxString ColourToString( const wxColour& col, int index ) const;
568 // Returns index of entry that triggers colour picker dialog
569 // (default is last).
570 virtual int GetCustomColourIndex() const;
572 // Helper function to show the colour dialog
573 bool QueryColourFromUser( wxVariant& variant ) const;
575 // Returns colour for given choice.
576 // Default function returns wxSystemSettings::GetColour(index).
577 virtual wxColour GetColour( int index ) const;
580 @subsection wxCursorProperty
582 Represents a wxCursor. wxChoice is used to edit the value.
583 Drop-down list has cursor images under some (wxMSW) platforms.
586 @section pgproperty_creating Creating Custom Properties
588 New properties can be created by subclassing wxPGProperty or one
589 of the provided property classes, and (re)implementing necessary
590 member functions. Below, each virtual member function has ample
591 documentation about its purpose and any odd details which to keep
594 Here is a very simple 'template' code:
597 class MyProperty : public wxPGProperty
600 // Default constructor
603 // All arguments of this ctor must have a default value -
604 // use wxPG_LABEL for label and name
605 MyProperty( const wxString& label = wxPG_LABEL,
606 const wxString& name = wxPG_LABEL,
607 const wxString& value = wxEmptyString )
608 : wxPGProperty(label, name)
610 // m_value is wxVariant
614 virtual ~MyProperty() { }
616 const wxPGEditor* DoGetEditorClass() const
618 // Determines editor used by property.
619 // You can replace 'TextCtrl' below with any of these
620 // builtin-in property editor identifiers: Choice, ComboBox,
621 // TextCtrlAndButton, ChoiceAndButton, CheckBox, SpinCtrl,
623 return wxPGEditor_TextCtrl;
626 virtual wxString ValueToString( wxVariant& value,
629 // TODO: Convert given property value to a string
632 virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags )
634 // TODO: Adapt string to property value.
641 Since wxPGProperty derives from wxObject, you can use standard
642 wxDECLARE_DYNAMIC_CLASS and wxIMPLEMENT_DYNAMIC_CLASS macros. From the
643 above example they were omitted for sake of simplicity, and besides,
644 they are only really needed if you need to use wxRTTI with your
647 You can change the 'value type' of a property by simply assigning different
648 type of variant with SetValue. <b>It is mandatory to implement
649 wxVariantData class for all data types used as property values.</b>
650 You can use macros declared in wxPropertyGrid headers. For instance:
654 // (If you need to have export declaration, use version of macros
655 // with _EXPORTED postfix)
656 WX_PG_DECLARE_VARIANT_DATA(MyDataClass)
659 WX_PG_IMPLEMENT_VARIANT_DATA(MyDataClass)
661 // Or, if you don't have valid == operator:
662 WX_PG_IMPLEMENT_VARIANT_DATA_DUMMY_EQ(MyDataClass)
668 class wxPGProperty
: public wxObject
671 typedef wxUint32 FlagType
;
680 Non-abstract property classes should have constructor of this style:
684 MyProperty( const wxString& label, const wxString& name, const T& value )
685 : wxPGProperty(label, name)
687 // Generally recommended way to set the initial value
688 // (as it should work in pretty much 100% of cases).
693 // If has private child properties then create them here.
695 // AddPrivateChild( new wxStringProperty("Subprop 1",
697 // value.GetSubProp1()));
702 wxPGProperty( const wxString
& label
, const wxString
& name
);
705 Virtual destructor. It is customary for derived properties to implement this.
707 virtual ~wxPGProperty();
710 This virtual function is called after m_value has been set.
713 - If m_value was set to Null variant (ie. unspecified value), OnSetValue()
715 - m_value may be of any variant type. Typically properties internally support only
716 one variant type, and as such OnSetValue() provides a good opportunity to convert
717 supported values into internal type.
718 - Default implementation does nothing.
720 virtual void OnSetValue();
723 Override this to return something else than m_value as the value.
725 virtual wxVariant
DoGetValue() const;
728 Implement this function in derived class to check the value.
729 Return @true if it is ok. Returning @false prevents property change events
733 - Default implementation always returns @true.
735 virtual bool ValidateValue( wxVariant
& value
, wxPGValidationInfo
& validationInfo
) const;
738 Converts text into wxVariant value appropriate for this property.
741 On function entry this is the old value (should not be wxNullVariant
742 in normal cases). Translated value must be assigned back to it.
745 Text to be translated into variant.
748 If wxPG_FULL_VALUE is set, returns complete, storable value instead
749 of displayable one (they may be different).
750 If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
751 composite property string value (as generated by ValueToString()
752 called with this same flag).
754 @return Returns @true if resulting wxVariant value was different.
756 @remarks Default implementation converts semicolon delimited tokens into
757 child values. Only works for properties with children.
759 You might want to take into account that m_value is Null variant
760 if property value is unspecified (which is usually only case if
761 you explicitly enabled that sort behavior).
763 virtual bool StringToValue( wxVariant
& variant
, const wxString
& text
, int argFlags
= 0 ) const;
766 Converts integer (possibly a choice selection) into wxVariant value
767 appropriate for this property.
770 On function entry this is the old value (should not be wxNullVariant
771 in normal cases). Translated value must be assigned back to it.
773 Integer to be translated into variant.
775 If wxPG_FULL_VALUE is set, returns complete, storable value instead
778 @return Returns @true if resulting wxVariant value was different.
781 - If property is not supposed to use choice or spinctrl or other editor
782 with int-based value, it is not necessary to implement this method.
783 - Default implementation simply assign given int to m_value.
784 - If property uses choice control, and displays a dialog on some choice
785 items, then it is preferred to display that dialog in IntToValue
787 - You might want to take into account that m_value is Mull variant if
788 property value is unspecified (which is usually only case if you
789 explicitly enabled that sort behavior).
791 virtual bool IntToValue( wxVariant
& variant
, int number
, int argFlags
= 0 ) const;
794 Converts property value into a text representation.
797 Value to be converted.
799 If 0 (default value), then displayed string is returned.
800 If wxPG_FULL_VALUE is set, returns complete, storable string value
801 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
802 string value that must be editable in textctrl.
803 If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
804 display as a part of string property's composite text representation.
806 @remarks Default implementation calls GenerateComposedValue().
808 virtual wxString
ValueToString( wxVariant
& value
, int argFlags
= 0 ) const;
811 Converts string to a value, and if successful, calls SetValue() on it.
812 Default behavior is to do nothing.
815 String to get the value from.
819 @return @true if value was changed.
821 bool SetValueFromString( const wxString
& text
, int flags
= 0 );
824 Converts integer to a value, and if succesful, calls SetValue() on it.
825 Default behavior is to do nothing.
828 Int to get the value from.
830 If has wxPG_FULL_VALUE, then the value given is a actual value and not an index.
832 @return @true if value was changed.
834 bool SetValueFromInt( long value
, int flags
= 0 );
837 Returns size of the custom painted image in front of property. This method
838 must be overridden to return non-default value if OnCustomPaint is to be
842 Normally -1, but can be an index to the property's list of items.
845 - Default behavior is to return wxSize(0,0), which means no image.
846 - Default image width or height is indicated with dimension -1.
847 - You can also return wxPG_DEFAULT_IMAGE_SIZE which equals wxSize(-1, -1).
849 virtual wxSize
OnMeasureImage( int item
= -1 ) const;
852 Events received by editor widgets are processed here. Note that editor class
853 usually processes most events. Some, such as button press events of
854 TextCtrlAndButton class, can be handled here. Also, if custom handling
855 for regular events is desired, then that can also be done (for example,
856 wxSystemColourProperty custom handles wxEVT_COMMAND_CHOICE_SELECTED
857 to display colour picker dialog when 'custom' selection is made).
859 If the event causes value to be changed, SetValueInEvent() should be called
860 to set the new value.
862 The parameter @a event is the associated wxEvent.
865 Should return @true if any changes in value should be reported.
868 - If property uses choice control, and displays a dialog on some choice items,
869 then it is preferred to display that dialog in IntToValue instead of OnEvent.
871 virtual bool OnEvent( wxPropertyGrid
* propgrid
, wxWindow
* wnd_primary
, wxEvent
& event
);
874 Called after value of a child property has been altered. Must return
875 new value of the whole property (after any alterations warrented by
878 Note that this function is usually called at the time that value of
879 this property, or given child property, is still pending for change,
880 and as such, result of GetValue() or m_value should not be relied
883 Sample pseudo-code implementation:
886 wxVariant MyProperty::ChildChanged( wxVariant& thisValue,
888 wxVariant& childValue ) const
890 // Acquire reference to actual type of data stored in variant
891 // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros
892 // were used to create the variant class).
893 T& data = TFromVariant(thisValue);
895 // Copy childValue into data.
896 switch ( childIndex )
899 data.SetSubProp1( childvalue.GetLong() );
902 data.SetSubProp2( childvalue.GetString() );
907 // Return altered data
913 Value of this property. Changed value should be returned (in
914 previous versions of wxPropertyGrid it was only necessary to
915 write value back to this argument).
917 Index of child changed (you can use Item(childIndex) to get
920 (Pending) value of the child property.
923 Modified value of the whole property.
925 virtual wxVariant
ChildChanged( wxVariant
& thisValue
,
927 wxVariant
& childValue
) const;
930 Returns pointer to an instance of used editor.
932 virtual const wxPGEditor
* DoGetEditorClass() const;
935 Returns pointer to the wxValidator that should be used
936 with the editor of this property (@NULL for no validator).
937 Setting validator explicitly via SetPropertyValidator
940 In most situations, code like this should work well
941 (macros are used to maintain one actual validator instance,
942 so on the second call the function exits within the first
947 wxValidator* wxMyPropertyClass::DoGetValidator () const
949 WX_PG_DOGETVALIDATOR_ENTRY()
951 wxMyValidator* validator = new wxMyValidator(...);
953 ... prepare validator...
955 WX_PG_DOGETVALIDATOR_EXIT(validator)
961 You can get common filename validator by returning
962 wxFileProperty::GetClassValidator(). wxDirProperty,
963 for example, uses it.
965 virtual wxValidator
* DoGetValidator () const;
968 Override to paint an image in front of the property value text or drop-down
969 list item (but only if wxPGProperty::OnMeasureImage is overridden as well).
971 If property's OnMeasureImage() returns size that has height != 0 but less than
972 row height ( < 0 has special meanings), wxPropertyGrid calls this method to
973 draw a custom image in a limited area in front of the editor control or
974 value text/graphics, and if control has drop-down list, then the image is
975 drawn there as well (even in the case OnMeasureImage() returned higher height
978 NOTE: Following applies when OnMeasureImage() returns a "flexible" height (
979 using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable height items:
980 If rect.x is < 0, then this is a measure item call, which means that
981 dc is invalid and only thing that should be done is to set paintdata.m_drawnHeight
982 to the height of the image of item at index paintdata.m_choiceItem. This call
983 may be done even as often as once every drop-down popup show.
988 Box reserved for custom graphics. Includes surrounding rectangle, if any.
989 If x is < 0, then this is a measure item call (see above).
991 wxPGPaintData structure with much useful data about painted item.
996 const wxPropertyGrid* m_parent;
998 // Normally -1, otherwise index to drop-down list item that has to be drawn.
1001 // Set to drawn width in OnCustomPaint (optional).
1004 // In a measure item call, set this to the height of item at m_choiceItem index
1010 - You can actually exceed rect width, but if you do so then paintdata.m_drawnWidth
1011 must be set to the full width drawn in pixels.
1012 - Due to technical reasons, rect's height will be default even if custom height
1013 was reported during measure call.
1014 - Brush is guaranteed to be default background colour. It has been already used to
1015 clear the background of area being painted. It can be modified.
1016 - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper colour) pen for
1017 drawing framing rectangle. It can be changed as well.
1019 @see ValueToString()
1021 virtual void OnCustomPaint( wxDC
& dc
, const wxRect
& rect
, wxPGPaintData
& paintdata
);
1024 Returns used wxPGCellRenderer instance for given property column (label=0, value=1).
1026 Default implementation returns editor's renderer for all columns.
1028 virtual wxPGCellRenderer
* GetCellRenderer( int column
) const;
1031 Returns which choice is currently selected. Only applies to properties
1034 Needs to reimplemented in derived class if property value does not
1035 map directly to a choice. Integer as index, bool, and string usually do.
1037 virtual int GetChoiceSelection() const;
1040 Refresh values of child properties. Automatically called after value is set.
1042 virtual void RefreshChildren();
1045 Reimplement this member function to add special handling for
1046 attributes of this property.
1048 @return Return @false to have the attribute automatically stored in
1049 m_attributes. Default implementation simply does that and
1052 @remarks To actually set property attribute values from the
1053 application, use wxPGProperty::SetAttribute() instead.
1055 virtual bool DoSetAttribute( const wxString
& name
, wxVariant
& value
);
1058 Returns value of an attribute.
1060 Override if custom handling of attributes is needed.
1062 Default implementation simply return @NULL variant.
1064 virtual wxVariant
DoGetAttribute( const wxString
& name
) const;
1067 Returns instance of a new wxPGEditorDialogAdapter instance, which is
1068 used when user presses the (optional) button next to the editor control;
1070 Default implementation returns @NULL (ie. no action is generated when
1073 virtual wxPGEditorDialogAdapter
* GetEditorDialog() const;
1076 Called whenever validation has failed with given pending value.
1078 @remarks If you implement this in your custom property class, please
1079 remember to call the baser implementation as well, since they
1080 may use it to revert property into pre-change state.
1082 virtual void OnValidationFailure( wxVariant
& pendingValue
);
1085 Append a new choice to property's list of choices.
1088 Label for added choice.
1091 Value for new choice. Do not specify if you wish this
1092 to equal choice index.
1095 Index to added choice.
1097 int AddChoice( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1100 Adds a private child property.
1102 @deprecated Use AddPrivateChild() instead.
1104 @see AddPrivateChild()
1106 wxDEPRECATED( void AddChild( wxPGProperty
* prop
) );
1109 Adds a private child property. If you use this instead of
1110 wxPropertyGridInterface::Insert() or
1111 wxPropertyGridInterface::AppendIn(), then property's parental
1112 type will automatically be set up to wxPG_PROP_AGGREGATE. In other
1113 words, all properties of this property will become private.
1115 void AddPrivateChild( wxPGProperty
* prop
);
1118 Adapts list variant into proper value using consecutive
1119 ChildChanged() calls.
1121 void AdaptListToValue( wxVariant
& list
, wxVariant
* value
) const;
1124 Use this member function to add independent (ie. regular) children to
1127 @return Appended childProperty.
1129 @remarks wxPropertyGrid is not automatically refreshed by this
1132 @see InsertChild(), AddPrivateChild()
1134 wxPGProperty
* AppendChild( wxPGProperty
* childProperty
);
1137 Determines, recursively, if all children are not unspecified.
1140 Assumes members in this wxVariant list as pending
1143 bool AreAllChildrenSpecified( wxVariant
* pendingList
= NULL
) const;
1146 Returns @true if children of this property are component values (for instance,
1147 points size, face name, and is_underlined are component values of a font).
1149 bool AreChildrenComponents() const;
1152 Sets or clears given property flag. Mainly for internal use.
1154 @remarks Setting a property flag never has any side-effect, and is
1155 intended almost exclusively for internal use. So, for
1156 example, if you want to disable a property, call
1157 Enable(false) instead of setting wxPG_PROP_DISABLED flag.
1159 @see HasFlag(), GetFlags()
1161 void ChangeFlag( wxPGPropertyFlags flag
, bool set
);
1164 Deletes children of the property.
1166 void DeleteChildren();
1169 Removes entry from property's wxPGChoices and editor control (if it is active).
1171 If selected item is deleted, then the value is set to unspecified.
1173 void DeleteChoice( int index
);
1175 /** Deletes all child properties. */
1179 Enables or disables the property. Disabled property usually appears
1180 as having grey text.
1183 If @false, property is disabled instead.
1185 @see wxPropertyGridInterface::EnableProperty()
1187 void Enable( bool enable
= true );
1190 Composes text from values of child properties.
1192 wxString
GenerateComposedValue() const;
1195 Returns property attribute value, null variant if not found.
1197 wxVariant
GetAttribute( const wxString
& name
) const;
1199 /** Returns named attribute, as string, if found. Otherwise defVal is returned.
1201 wxString
GetAttribute( const wxString
& name
, const wxString
& defVal
) const;
1203 /** Returns named attribute, as long, if found. Otherwise defVal is returned.
1205 long GetAttributeAsLong( const wxString
& name
, long defVal
) const;
1207 /** Returns named attribute, as double, if found. Otherwise defVal is returned.
1209 double GetAttributeAsDouble( const wxString
& name
, double defVal
) const;
1212 Returns attributes as list wxVariant.
1214 wxVariant
GetAttributesAsList() const;
1217 Returns editor used for given column. @NULL for no editor.
1219 const wxPGEditor
* GetColumnEditor( int column
) const;
1221 /** Returns property's base name (ie. parent's name is not added in any case) */
1222 const wxString
& GetBaseName() const;
1225 Returns wxPGCell of given column.
1227 @remarks const version of this member function returns 'default'
1228 wxPGCell object if the property itself didn't hold
1231 const wxPGCell
& GetCell( unsigned int column
) const;
1234 Returns wxPGCell of given column, creating one if necessary.
1236 wxPGCell
& GetCell( unsigned int column
);
1239 Returns wxPGCell of given column, creating one if necessary.
1241 wxPGCell
& GetOrCreateCell( unsigned int column
);
1244 Returns number of child properties.
1246 unsigned int GetChildCount() const;
1249 Returns height of children, recursively, and
1250 by taking expanded/collapsed status into account.
1253 Line height. Pass result of GetGrid()->GetRowHeight() here.
1256 Only used (internally) when finding property y-positions.
1258 int GetChildrenHeight( int lh
, int iMax
= -1 ) const;
1261 Returns read-only reference to property's list of choices.
1263 const wxPGChoices
& GetChoices() const;
1266 Returns client data (void*) of a property.
1268 void* GetClientData() const;
1270 /** Sets managed client object of a property.
1272 wxClientData
*GetClientObject() const;
1275 Returns property's default value. If property's value type is not
1276 a built-in one, and "DefaultValue" attribute is not defined, then
1277 this function usually returns Null variant.
1279 wxVariant
GetDefaultValue() const;
1281 /** Returns property's displayed text.
1283 wxString
GetDisplayedString() const;
1286 Returns wxPGEditor that will be used and created when
1287 property becomes selected. Returns more accurate value
1288 than DoGetEditorClass().
1290 const wxPGEditor
* GetEditorClass() const;
1293 Returns property flags.
1295 FlagType
GetFlags() const;
1297 /** Returns property grid where property lies. */
1298 wxPropertyGrid
* GetGrid() const;
1301 Returns owner wxPropertyGrid, but only if one is currently on a page
1302 displaying this property.
1304 wxPropertyGrid
* GetGridIfDisplayed() const;
1307 Returns property's help or description text.
1309 @see SetHelpString()
1311 const wxString
& GetHelpString() const;
1314 Returns position in parent's array.
1316 unsigned int GetIndexInParent() const;
1318 /** Returns property's label. */
1319 const wxString
& GetLabel() const;
1322 Returns last visible child property, recursively.
1324 const wxPGProperty
* GetLastVisibleSubItem() const;
1327 Returns highest level non-category, non-root parent. Useful when you
1328 have nested properties with children.
1330 @remarks If immediate parent is root or category, this will return the
1333 wxPGProperty
* GetMainParent() const;
1335 /** Returns maximum allowed length of property's text value.
1337 int GetMaxLength() const;
1339 /** Returns property's name with all (non-category, non-root) parents. */
1340 wxString
GetName() const;
1342 /** Return parent of property */
1343 wxPGProperty
* GetParent() const;
1346 Returns (direct) child property with given name (or @NULL if not found).
1348 wxPGProperty
* GetPropertyByName( const wxString
& name
) const;
1350 /** Gets assignable version of property's validator. */
1351 wxValidator
* GetValidator() const;
1354 Returns property's value.
1356 wxVariant
GetValue() const;
1359 Returns bitmap that appears next to value text. Only returns non-@NULL
1360 bitmap if one was set with SetValueImage().
1362 wxBitmap
* GetValueImage() const;
1364 /** Returns text representation of property's value.
1367 If 0 (default value), then displayed string is returned.
1368 If wxPG_FULL_VALUE is set, returns complete, storable string value
1369 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
1370 string value that must be editable in textctrl. If
1371 wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
1372 display as a part of string property's composite text
1375 @remarks In older versions, this function used to be overridden to convert
1376 property's value into a string representation. This function is
1377 now handled by ValueToString(), and overriding this function now
1378 will result in run-time assertion failure.
1380 virtual wxString
GetValueAsString( int argFlags
= 0 ) const;
1382 /** Synonymous to GetValueAsString().
1384 @deprecated Use GetValueAsString() instead.
1386 @see GetValueAsString()
1388 wxDEPRECATED( wxString
GetValueString( int argFlags
= 0 ) const );
1391 Returns value type used by this property.
1393 wxString
GetValueType() const;
1396 Returns coordinate to the top y of the property. Note that the
1397 position of scrollbars is not taken into account.
1402 Returns non-zero if property has given flag set.
1404 @see propgrid_propflags
1406 FlagType
HasFlag( wxPGPropertyFlags flag
) const;
1409 Returns @true if property has even one visible child.
1411 bool HasVisibleChildren() const;
1414 Hides or reveals the property.
1417 @true for hide, @false for reveal.
1420 By default changes are applied recursively. Set this parameter wxPG_DONT_RECURSE to prevent this.
1422 bool Hide( bool hide
, int flags
= wxPG_RECURSE
);
1425 Returns index of given child property. wxNOT_FOUND if
1426 given property is not child of this.
1428 int Index( const wxPGProperty
* p
) const;
1431 Use this member function to add independent (ie. regular) children to
1434 @return Inserted childProperty.
1436 @remarks wxPropertyGrid is not automatically refreshed by this
1439 @see AppendChild(), AddPrivateChild()
1441 wxPGProperty
* InsertChild( int index
, wxPGProperty
* childProperty
);
1444 Inserts a new choice to property's list of choices.
1450 Insertion position. Use wxNOT_FOUND to append.
1453 Value for new choice. Do not specify if you wish this
1454 to equal choice index.
1456 int InsertChoice( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1459 Returns @true if this property is actually a wxPropertyCategory.
1461 bool IsCategory() const;
1464 Returns @true if property is enabled.
1466 bool IsEnabled() const;
1469 Returns @true if property has visible children.
1471 bool IsExpanded() const;
1474 Returns @true if this property is actually a wxRootProperty.
1476 bool IsRoot() const;
1479 Returns @true if candidateParent is some parent of this property.
1481 bool IsSomeParent( wxPGProperty
* candidateParent
) const;
1484 Returns true if property has editable wxTextCtrl when selected.
1486 @remarks Altough disabled properties do not displayed editor, they still
1487 return @true here as being disabled is considered a temporary
1488 condition (unlike being read-only or having limited editing enabled).
1490 bool IsTextEditable() const;
1493 Returns @true if property's value is considered unspecified. This
1494 usually means that value is Null variant.
1496 bool IsValueUnspecified() const;
1499 Returns true if all parents expanded.
1501 bool IsVisible() const;
1504 Returns child property at index i.
1506 wxPGProperty
* Item( unsigned int i
) const;
1509 If property's editor is active, then update it's value.
1511 void RefreshEditor();
1514 Sets an attribute for this property.
1517 Text identifier of attribute. See @ref propgrid_property_attributes.
1522 @remarks Setting attribute's value to Null variant will simply remove it
1523 from property's set of attributes.
1525 void SetAttribute( const wxString
& name
, wxVariant value
);
1528 Set if user can change the property's value to unspecified by
1529 modifying the value of the editor control (usually by clearing
1530 it). Currently, this can work with following properties:
1531 wxIntProperty, wxUIntProperty, wxFloatProperty, wxEditEnumProperty.
1534 Whether to enable or disable this behavior (it is disabled by
1537 void SetAutoUnspecified( bool enable
= true );
1540 Sets property's background colour.
1543 Background colour to use.
1546 Default is wxPG_RECURSE which causes colour to be set recursively.
1547 Omit this flag to only set colour for the property in question
1548 and not any of its children.
1550 void SetBackgroundColour( const wxColour
& colour
,
1551 int flags
= wxPG_RECURSE
);
1554 Sets editor for a property.
1557 For builtin editors, use wxPGEditor_X, where X is builtin editor's
1558 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list).
1560 For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
1562 void SetEditor( const wxPGEditor
* editor
);
1565 Sets editor for a property, by editor name.
1567 void SetEditor( const wxString
& editorName
);
1570 Sets cell information for given column.
1572 void SetCell( int column
, const wxPGCell
& cell
);
1575 Sets new set of choices for the property.
1577 @remarks This operation deselects the property and clears its
1580 bool SetChoices( wxPGChoices
& choices
);
1583 Sets client data (void*) of a property.
1585 @remarks This untyped client data has to be deleted manually.
1587 void SetClientData( void* clientData
);
1589 /** Returns client object of a property.
1591 void SetClientObject(wxClientData
* clientObject
);
1594 Sets selected choice and changes property value.
1596 Tries to retain value type, although currently if it is not string,
1597 then it is forced to integer.
1599 void SetChoiceSelection( int newValue
);
1601 /** Set default value of a property. Synonymous to
1604 SetAttribute("DefaultValue", value);
1607 void SetDefaultValue( wxVariant
& value
);
1610 Sets or clears given property flag, recursively. This function is
1611 primarily intended for internal use.
1615 void SetFlagRecursively( wxPGPropertyFlags flag
, bool set
);
1618 Sets property's help string, which is shown, for example, in
1619 wxPropertyGridManager's description text box.
1621 void SetHelpString( const wxString
& helpString
);
1624 Sets property's label.
1626 @remarks Properties under same parent may have same labels. However,
1627 property names must still remain unique.
1629 void SetLabel( const wxString
& label
);
1632 Set max length of text in text editor.
1634 bool SetMaxLength( int maxLen
);
1637 Sets property's "is it modified?" flag. Affects children recursively.
1639 void SetModifiedStatus( bool modified
);
1642 Sets new (base) name for property.
1644 void SetName( const wxString
& newName
);
1647 Changes what sort of parent this property is for its children.
1650 Use one of the following values: wxPG_PROP_MISC_PARENT (for generic
1651 parents), wxPG_PROP_CATEGORY (for categories), or
1652 wxPG_PROP_AGGREGATE (for derived property classes with private
1655 @remarks You generally do not need to call this function.
1657 void SetParentalType( int flag
);
1660 Sets property's text colour.
1666 Default is wxPG_RECURSE which causes colour to be set recursively.
1667 Omit this flag to only set colour for the property in question
1668 and not any of its children.
1670 void SetTextColour( const wxColour
& colour
,
1671 int flags
= wxPG_RECURSE
);
1673 /** Sets wxValidator for a property */
1674 void SetValidator( const wxValidator
& validator
);
1677 Call this to set value of the property. Unlike methods in wxPropertyGrid,
1678 this does not automatically update the display.
1681 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through
1682 validation process and send property change event.
1684 If you need to change property value in event, based on user input, use
1685 SetValueInEvent() instead.
1690 Pointer to list variant that contains child values. Used to indicate
1691 which children should be marked as modified. Usually you just use @NULL.
1693 wxPG_SETVAL_REFRESH_EDITOR is set by default, to refresh editor
1694 and redraw properties.
1696 void SetValue( wxVariant value
, wxVariant
* pList
= NULL
,
1697 int flags
= wxPG_SETVAL_REFRESH_EDITOR
);
1700 Set wxBitmap in front of the value. This bitmap may be ignored
1701 by custom cell renderers.
1703 void SetValueImage( wxBitmap
& bmp
);
1706 Call this function in OnEvent(), OnButtonClick() etc. to change the
1707 property value based on user input.
1709 @remarks This method is const since it doesn't actually modify value, but posts
1710 given variant as pending value, stored in wxPropertyGrid.
1712 void SetValueInEvent( wxVariant value
) const;
1715 Sets property's value to unspecified (ie. Null variant).
1717 void SetValueToUnspecified();
1720 Call with @false in OnSetValue() to cancel value changes after all
1721 (ie. cancel @true returned by StringToValue() or IntToValue()).
1723 void SetWasModified( bool set
= true );
1726 Updates composed values of parent non-category properties, recursively.
1727 Returns topmost property updated.
1729 wxPGProperty
* UpdateParentValues();
1732 Returns @true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
1734 bool UsesAutoUnspecified() const;
1741 Base class for wxPropertyGrid cell information.
1743 @library{wxpropgrid}
1746 class wxPGCell
: public wxObject
1750 wxPGCell(const wxPGCell
& other
);
1751 wxPGCell( const wxString
& text
,
1752 const wxBitmap
& bitmap
= wxNullBitmap
,
1753 const wxColour
& fgCol
= wxNullColour
,
1754 const wxColour
& bgCol
= wxNullColour
);
1756 virtual ~wxPGCell();
1758 const wxPGCellData
* GetData() const;
1761 Returns @true if this cell has custom text stored within.
1763 bool HasText() const;
1766 Merges valid data from srcCell into this.
1768 void MergeFrom( const wxPGCell
& srcCell
);
1770 void SetText( const wxString
& text
);
1771 void SetBitmap( const wxBitmap
& bitmap
);
1772 void SetFgCol( const wxColour
& col
);
1775 Sets font of the cell.
1777 @remarks Because wxPropertyGrid does not support rows of
1778 different height, it makes little sense to change
1779 size of the font. Therefore it is recommended
1780 to use return value of wxPropertyGrid::GetFont()
1781 or wxPropertyGrid::GetCaptionFont() as a basis
1782 for the font that, after modifications, is passed
1783 to this member function.
1785 void SetFont( const wxFont
& font
);
1787 void SetBgCol( const wxColour
& col
);
1789 const wxString
& GetText() const;
1790 const wxBitmap
& GetBitmap() const;
1791 const wxColour
& GetFgCol() const;
1794 Returns font of the cell. If no specific font is set for this
1795 cell, then the font will be invalid.
1797 const wxFont
& GetFont() const;
1799 const wxColour
& GetBgCol() const;
1801 wxPGCell
& operator=( const wxPGCell
& other
);
1808 Helper class for managing choices of wxPropertyGrid properties.
1809 Each entry can have label, value, bitmap, text colour, and background
1812 wxPGChoices uses reference counting, similar to other wxWidgets classes.
1813 This means that assignment operator and copy constructor only copy the
1814 reference and not the actual data. Use Copy() member function to create a
1817 @remarks If you do not specify value for entry, index is used.
1819 @library{wxpropgrid}
1825 typedef long ValArrItem
;
1828 Default constructor.
1833 Copy constructor, uses reference counting. To create a real copy,
1834 use Copy() member function instead.
1836 wxPGChoices( const wxPGChoices
& a
);
1839 wxPGChoices( const wxChar
** labels
, const long* values
= NULL
);
1842 wxPGChoices( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() );
1845 wxPGChoices( wxPGChoicesData
* data
);
1851 Adds to current. If did not have own copies, creates them now. If was empty,
1852 identical to set except that creates copies.
1854 void Add( const wxChar
** labels
, const ValArrItem
* values
= NULL
);
1856 /** Version that works with wxArrayString. */
1857 void Add( const wxArrayString
& arr
, const ValArrItem
* values
= NULL
);
1859 /** Version that works with wxArrayString and wxArrayInt. */
1860 void Add( const wxArrayString
& arr
, const wxArrayInt
& arrint
);
1862 /** Adds single item. */
1863 wxPGChoiceEntry
& Add( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1865 /** Adds a single item, with bitmap. */
1866 wxPGChoiceEntry
& Add( const wxString
& label
, const wxBitmap
& bitmap
,
1867 int value
= wxPG_INVALID_VALUE
);
1869 /** Adds a single item with full entry information. */
1870 wxPGChoiceEntry
& Add( const wxPGChoiceEntry
& entry
);
1872 /** Adds single item, sorted. */
1873 wxPGChoiceEntry
& AddAsSorted( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1876 Assigns choices data, using reference counting. To create a real copy,
1877 use Copy() member function instead.
1879 void Assign( const wxPGChoices
& a
);
1882 Assigns data from another set of choices.
1884 void AssignData( wxPGChoicesData
* data
);
1892 Returns a real copy of the choices.
1894 wxPGChoices
Copy() const;
1897 Returns labe of item.
1899 const wxString
& GetLabel( unsigned int ind
) const;
1902 Returns number of items.
1904 unsigned int GetCount() const;
1907 Returns value of item;
1909 int GetValue( unsigned int ind
) const;
1912 Returns array of values matching the given strings. Unmatching strings
1913 result in wxPG_INVALID_VALUE entry in array.
1915 wxArrayInt
GetValuesForStrings( const wxArrayString
& strings
) const;
1918 Returns array of indices matching given strings. Unmatching strings
1919 are added to 'unmatched', if not @NULL.
1921 wxArrayInt
GetIndicesForStrings( const wxArrayString
& strings
,
1922 wxArrayString
* unmatched
= NULL
) const;
1924 /** Returns property at given virtual y coordinate.
1926 wxPGProperty
* GetItemAtY( unsigned int y
) const;
1929 Returns @true if item at given index has a valid value;
1931 bool HasValue( unsigned int i
) const;
1934 Returns index of item with given label.
1936 int Index( const wxString
& label
) const;
1939 Returns index of item with given value.
1941 int Index( int val
) const;
1944 Inserts single item.
1946 wxPGChoiceEntry
& Insert( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1949 Inserts a single item with full entry information.
1951 wxPGChoiceEntry
& Insert( const wxPGChoiceEntry
& entry
, int index
);
1954 Returns @false if this is a constant empty set of choices,
1955 which should not be modified.
1960 Returns item at given index.
1962 const wxPGChoiceEntry
& Item( unsigned int i
) const;
1965 Returns item at given index.
1967 wxPGChoiceEntry
& Item( unsigned int i
);
1970 Removes count items starting at position nIndex.
1972 void RemoveAt(size_t nIndex
, size_t count
= 1);
1975 Sets contents from lists of strings and values.
1977 void Set( const wxChar
** labels
, const long* values
= NULL
);
1980 Sets contents from lists of strings and values.
1982 void Set( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() );
1985 Creates exclusive copy of current choices.
1987 void AllocExclusive();
1990 Returns array of choice labels.
1992 wxArrayString
GetLabels() const;
1994 void operator= (const wxPGChoices
& a
);
1996 wxPGChoiceEntry
& operator[](unsigned int i
);
1997 const wxPGChoiceEntry
& operator[](unsigned int i
) const;
2000 // -----------------------------------------------------------------------