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 wxPG_PROP_AUTO_UNSPECIFIED
= 0x00040000,
293 /** Indicates the bit useable by derived properties.
295 wxPG_PROP_CLASS_SPECIFIC_1
= 0x00080000,
297 /** Indicates the bit useable by derived properties.
299 wxPG_PROP_CLASS_SPECIFIC_2
= 0x00100000,
301 /** Indicates that the property is being deleted and should be ignored.
303 wxPG_PROP_BEING_DELETED
= 0x00200000
309 #define wxPG_PROP_MAX wxPG_PROP_AUTO_UNSPECIFIED
311 /** Property with children must have one of these set, otherwise iterators
312 will not work correctly.
313 Code should automatically take care of this, however.
315 #define wxPG_PROP_PARENTAL_FLAGS \
316 ((wxPGPropertyFlags)(wxPG_PROP_AGGREGATE | \
317 wxPG_PROP_CATEGORY | \
318 wxPG_PROP_MISC_PARENT))
327 wxPGProperty is base class for all wxPropertyGrid properties. In
328 sections below we cover few related topics.
330 @li @ref pgproperty_properties
331 @li @ref pgproperty_creating
333 @section pgproperty_properties Supplied Ready-to-use Property Classes
335 Here is a list and short description of supplied fully-functional
336 property classes. They are located in either props.h or advprops.h.
338 @li @ref wxArrayStringProperty
339 @li @ref wxBoolProperty
340 @li @ref wxColourProperty
341 @li @ref wxCursorProperty
342 @li @ref wxDateProperty
343 @li @ref wxDirProperty
344 @li @ref wxEditEnumProperty
345 @li @ref wxEnumProperty
346 @li @ref wxFileProperty
347 @li @ref wxFlagsProperty
348 @li @ref wxFloatProperty
349 @li @ref wxFontProperty
350 @li @ref wxImageFileProperty
351 @li @ref wxIntProperty
352 @li @ref wxLongStringProperty
353 @li @ref wxMultiChoiceProperty
354 @li @ref wxPropertyCategory
355 @li @ref wxStringProperty
356 @li @ref wxSystemColourProperty
357 @li @ref wxUIntProperty
359 @subsection wxPropertyCategory
361 Not an actual property per se, but a header for a group of properties.
362 Regardless inherits from wxPGProperty, and supports displaying 'labels'
363 for columns other than the first one. Easiest way to set category's
364 label for second column is to call wxPGProperty::SetValue() with string
367 @subsection wxStringProperty
369 Simple string property. wxPG_STRING_PASSWORD attribute may be used
370 to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl.
371 wxPG_ATTR_AUTOCOMPLETE attribute may be used to enable auto-completion
372 (use a wxArrayString value), and is also supported by any property that
373 happens to use a wxTextCtrl-based editor.
375 @remarks wxStringProperty has a special trait: if it has value of
376 "<composed>", and also has child properties, then its displayed
377 value becomes composition of child property values, similar as
378 with wxFontProperty, for instance.
380 @subsection wxIntProperty
382 Like wxStringProperty, but converts text to a signed long integer.
383 wxIntProperty seamlessly supports 64-bit integers (ie. wxLongLong).
384 To safely convert variant to integer, use code like this:
388 ll << property->GetValue();
391 wxLongLong ll = propertyGrid->GetPropertyValueAsLong(property);
394 @subsection wxUIntProperty
396 Like wxIntProperty, but displays value as unsigned int. To set
397 the prefix used globally, manipulate wxPG_UINT_PREFIX string attribute.
398 To set the globally used base, manipulate wxPG_UINT_BASE int
399 attribute. Regardless of current prefix, understands (hex) values starting
400 with both "0x" and "$".
401 Like wxIntProperty, wxUIntProperty seamlessly supports 64-bit unsigned
402 integers (ie. wxULongLong). Same wxVariant safety rules apply.
404 @subsection wxFloatProperty
406 Like wxStringProperty, but converts text to a double-precision floating point.
407 Default float-to-text precision is 6 decimals, but this can be changed
408 by modifying wxPG_FLOAT_PRECISION attribute.
410 @subsection wxBoolProperty
412 Represents a boolean value. wxChoice is used as editor control, by the
413 default. wxPG_BOOL_USE_CHECKBOX attribute can be set to true inorder to use
416 @subsection wxLongStringProperty
418 Like wxStringProperty, but has a button that triggers a small text editor
419 dialog. Note that in long string values, tabs are represented by "\t" and
422 To display custom dialog on button press, you can subclass
423 wxLongStringProperty and implement OnButtonClick, like this:
426 virtual bool OnButtonClick( wxPropertyGrid* propGrid, wxString& value )
428 wxSize dialogSize(...size of your dialog...);
430 wxPoint dlgPos = propGrid->GetGoodEditorDialogPosition(this,
433 // Create dialog dlg at dlgPos. Use value as initial string
437 if ( dlg.ShowModal() == wxID_OK )
439 value = dlg.GetStringValue);
446 Also, if you wish not to have line breaks and tabs translated to
447 escape sequences, then do following in constructor of your subclass:
450 m_flags |= wxPG_PROP_NO_ESCAPE;
453 @subsection wxDirProperty
455 Like wxLongStringProperty, but the button triggers dir selector instead.
456 Supported properties (all with string value): wxPG_DIR_DIALOG_MESSAGE.
458 @subsection wxFileProperty
460 Like wxLongStringProperty, but the button triggers file selector instead.
461 Default wildcard is "All files..." but this can be changed by setting
462 wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details).
463 Attribute wxPG_FILE_SHOW_FULL_PATH can be set to @false inorder to show
464 only the filename, not the entire path.
466 @subsection wxEnumProperty
468 Represents a single selection from a list of choices -
469 wxOwnerDrawnComboBox is used to edit the value.
471 @subsection wxFlagsProperty
473 Represents a bit set that fits in a long integer. wxBoolProperty sub-
474 properties are created for editing individual bits. Textctrl is created to
475 manually edit the flags as a text; a continous sequence of spaces, commas
476 and semicolons are considered as a flag id separator.
478 <b>Note:</b> When changing "choices" (ie. flag labels) of wxFlagsProperty,
479 you will need to use wxPGProperty::SetChoices() - otherwise they will not
480 get updated properly.
482 wxFlagsProperty supports the same attributes as wxBoolProperty.
484 @subsection wxArrayStringProperty
486 Allows editing of a list of strings in wxTextCtrl and in a separate dialog.
488 @subsection wxDateProperty
490 wxDateTime property. Default editor is DatePickerCtrl, altough TextCtrl
491 should work as well. wxPG_DATE_FORMAT attribute can be used to change
492 string wxDateTime::Format uses (altough default is recommended as it is
493 locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window
494 style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY).
495 Using wxDP_ALLOWNONE will enable better unspecified value support.
497 @subsection wxEditEnumProperty
499 Represents a string that can be freely edited or selected from list of choices -
500 custom combobox control is used to edit the value.
502 @subsection wxMultiChoiceProperty
504 Allows editing a multiple selection from a list of strings. This is
505 property is pretty much built around concept of wxMultiChoiceDialog.
506 It uses wxArrayString value.
508 @subsection wxImageFileProperty
510 Like wxFileProperty, but has thumbnail of the image in front of
511 the filename and autogenerates wildcard from available image handlers.
513 @subsection wxColourProperty
515 <b>Useful alternate editor:</b> Choice.
517 Represents wxColour. wxButton is used to trigger a colour picker dialog.
518 There are various sub-classing opportunities with this class. See
519 below in wxSystemColourProperty section for details.
521 @subsection wxFontProperty
523 Represents wxFont. Various sub-properties are used to edit individual
526 @subsection wxSystemColourProperty
528 Represents wxColour and a system colour index. wxChoice is used to edit
529 the value. Drop-down list has color images. Note that value type
530 is wxColourPropertyValue instead of wxColour (which wxColourProperty
534 class wxColourPropertyValue : public wxObject
537 // An integer value relating to the colour, and which exact
538 // meaning depends on the property with which it is used.
540 // For wxSystemColourProperty:
541 // Any of wxSYS_COLOUR_XXX, or any web-colour ( use wxPG_TO_WEB_COLOUR
542 // macro - (currently unsupported) ), or wxPG_COLOUR_CUSTOM.
545 // Resulting colour. Should be correct regardless of type.
550 in wxSystemColourProperty, and its derived class wxColourProperty, there
551 are various sub-classing features. To set basic list list of colour
552 names, call wxPGProperty::SetChoices().
555 // Override in derived class to customize how colours are translated
557 virtual wxString ColourToString( const wxColour& col, int index ) const;
559 // Returns index of entry that triggers colour picker dialog
560 // (default is last).
561 virtual int GetCustomColourIndex() const;
563 // Helper function to show the colour dialog
564 bool QueryColourFromUser( wxVariant& variant ) const;
566 // Returns colour for given choice.
567 // Default function returns wxSystemSettings::GetColour(index).
568 virtual wxColour GetColour( int index ) const;
571 @subsection wxCursorProperty
573 Represents a wxCursor. wxChoice is used to edit the value.
574 Drop-down list has cursor images under some (wxMSW) platforms.
577 @section pgproperty_creating Creating Custom Properties
579 New properties can be created by subclassing wxPGProperty or one
580 of the provided property classes, and (re)implementing necessary
581 member functions. Below, each virtual member function has ample
582 documentation about its purpose and any odd details which to keep
585 Here is a very simple 'template' code:
588 class MyProperty : public wxPGProperty
591 // Default constructor
594 // All arguments of this ctor must have a default value -
595 // use wxPG_LABEL for label and name
596 MyProperty( const wxString& label = wxPG_LABEL,
597 const wxString& name = wxPG_LABEL,
598 const wxString& value = wxEmptyString )
599 : wxPGProperty(label, name)
601 // m_value is wxVariant
605 virtual ~MyProperty() { }
607 const wxPGEditor* DoGetEditorClass() const
609 // Determines editor used by property.
610 // You can replace 'TextCtrl' below with any of these
611 // builtin-in property editor identifiers: Choice, ComboBox,
612 // TextCtrlAndButton, ChoiceAndButton, CheckBox, SpinCtrl,
614 return wxPGEditor_TextCtrl;
617 virtual wxString ValueToString( wxVariant& value,
620 // TODO: Convert given property value to a string
623 virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags )
625 // TODO: Adapt string to property value.
632 Since wxPGProperty derives from wxObject, you can use standard
633 wxDECLARE_DYNAMIC_CLASS and wxIMPLEMENT_DYNAMIC_CLASS macros. From the
634 above example they were omitted for sake of simplicity, and besides,
635 they are only really needed if you need to use wxRTTI with your
638 You can change the 'value type' of a property by simply assigning different
639 type of variant with SetValue. <b>It is mandatory to implement
640 wxVariantData class for all data types used as property values.</b>
641 You can use macros declared in wxPropertyGrid headers. For instance:
645 // (If you need to have export declaration, use version of macros
646 // with _EXPORTED postfix)
647 WX_PG_DECLARE_VARIANT_DATA(MyDataClass)
650 WX_PG_IMPLEMENT_VARIANT_DATA(MyDataClass)
652 // Or, if you don't have valid == operator:
653 WX_PG_IMPLEMENT_VARIANT_DATA_DUMMY_EQ(MyDataClass)
659 class wxPGProperty
: public wxObject
662 typedef wxUint32 FlagType
;
671 Non-abstract property classes should have constructor of this style:
675 MyProperty( const wxString& label, const wxString& name, const T& value )
676 : wxPGProperty(label, name)
678 // Generally recommended way to set the initial value
679 // (as it should work in pretty much 100% of cases).
684 // If has private child properties then create them here.
686 // AddPrivateChild( new wxStringProperty("Subprop 1",
688 // value.GetSubProp1()));
693 wxPGProperty( const wxString
& label
, const wxString
& name
);
696 Virtual destructor. It is customary for derived properties to implement this.
698 virtual ~wxPGProperty();
701 This virtual function is called after m_value has been set.
704 - If m_value was set to Null variant (ie. unspecified value), OnSetValue()
706 - m_value may be of any variant type. Typically properties internally support only
707 one variant type, and as such OnSetValue() provides a good opportunity to convert
708 supported values into internal type.
709 - Default implementation does nothing.
711 virtual void OnSetValue();
714 Override this to return something else than m_value as the value.
716 virtual wxVariant
DoGetValue() const;
719 Implement this function in derived class to check the value.
720 Return @true if it is ok. Returning @false prevents property change events
724 - Default implementation always returns @true.
726 virtual bool ValidateValue( wxVariant
& value
, wxPGValidationInfo
& validationInfo
) const;
729 Converts text into wxVariant value appropriate for this property.
732 On function entry this is the old value (should not be wxNullVariant
733 in normal cases). Translated value must be assigned back to it.
736 Text to be translated into variant.
739 If wxPG_FULL_VALUE is set, returns complete, storable value instead
740 of displayable one (they may be different).
741 If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
742 composite property string value (as generated by ValueToString()
743 called with this same flag).
745 @return Returns @true if resulting wxVariant value was different.
747 @remarks Default implementation converts semicolon delimited tokens into
748 child values. Only works for properties with children.
750 You might want to take into account that m_value is Null variant
751 if property value is unspecified (which is usually only case if
752 you explicitly enabled that sort behavior).
754 virtual bool StringToValue( wxVariant
& variant
, const wxString
& text
, int argFlags
= 0 ) const;
757 Converts integer (possibly a choice selection) into wxVariant value
758 appropriate for this property.
761 On function entry this is the old value (should not be wxNullVariant
762 in normal cases). Translated value must be assigned back to it.
764 Integer to be translated into variant.
766 If wxPG_FULL_VALUE is set, returns complete, storable value instead
769 @return Returns @true if resulting wxVariant value was different.
772 - If property is not supposed to use choice or spinctrl or other editor
773 with int-based value, it is not necessary to implement this method.
774 - Default implementation simply assign given int to m_value.
775 - If property uses choice control, and displays a dialog on some choice
776 items, then it is preferred to display that dialog in IntToValue
778 - You might want to take into account that m_value is Mull variant if
779 property value is unspecified (which is usually only case if you
780 explicitly enabled that sort behavior).
782 virtual bool IntToValue( wxVariant
& variant
, int number
, int argFlags
= 0 ) const;
785 Converts property value into a text representation.
788 Value to be converted.
790 If 0 (default value), then displayed string is returned.
791 If wxPG_FULL_VALUE is set, returns complete, storable string value
792 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
793 string value that must be editable in textctrl.
794 If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
795 display as a part of string property's composite text representation.
797 @remarks Default implementation calls GenerateComposedValue().
799 virtual wxString
ValueToString( wxVariant
& value
, int argFlags
= 0 ) const;
802 Converts string to a value, and if successful, calls SetValue() on it.
803 Default behavior is to do nothing.
806 String to get the value from.
810 @return @true if value was changed.
812 bool SetValueFromString( const wxString
& text
, int flags
= 0 );
815 Converts integer to a value, and if succesful, calls SetValue() on it.
816 Default behavior is to do nothing.
819 Int to get the value from.
821 If has wxPG_FULL_VALUE, then the value given is a actual value and not an index.
823 @return @true if value was changed.
825 bool SetValueFromInt( long value
, int flags
= 0 );
828 Returns size of the custom painted image in front of property. This method
829 must be overridden to return non-default value if OnCustomPaint is to be
833 Normally -1, but can be an index to the property's list of items.
836 - Default behavior is to return wxSize(0,0), which means no image.
837 - Default image width or height is indicated with dimension -1.
838 - You can also return wxPG_DEFAULT_IMAGE_SIZE which equals wxSize(-1, -1).
840 virtual wxSize
OnMeasureImage( int item
= -1 ) const;
843 Events received by editor widgets are processed here. Note that editor class
844 usually processes most events. Some, such as button press events of
845 TextCtrlAndButton class, can be handled here. Also, if custom handling
846 for regular events is desired, then that can also be done (for example,
847 wxSystemColourProperty custom handles wxEVT_COMMAND_CHOICE_SELECTED
848 to display colour picker dialog when 'custom' selection is made).
850 If the event causes value to be changed, SetValueInEvent() should be called
851 to set the new value.
853 The parameter @a event is the associated wxEvent.
856 Should return @true if any changes in value should be reported.
859 - If property uses choice control, and displays a dialog on some choice items,
860 then it is preferred to display that dialog in IntToValue instead of OnEvent.
862 virtual bool OnEvent( wxPropertyGrid
* propgrid
, wxWindow
* wnd_primary
, wxEvent
& event
);
865 Called after value of a child property has been altered. Must return
866 new value of the whole property (after any alterations warrented by
869 Note that this function is usually called at the time that value of
870 this property, or given child property, is still pending for change,
871 and as such, result of GetValue() or m_value should not be relied
874 Sample pseudo-code implementation:
877 wxVariant MyProperty::ChildChanged( wxVariant& thisValue,
879 wxVariant& childValue ) const
881 // Acquire reference to actual type of data stored in variant
882 // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros
883 // were used to create the variant class).
884 T& data = TFromVariant(thisValue);
886 // Copy childValue into data.
887 switch ( childIndex )
890 data.SetSubProp1( childvalue.GetLong() );
893 data.SetSubProp2( childvalue.GetString() );
898 // Return altered data
904 Value of this property. Changed value should be returned (in
905 previous versions of wxPropertyGrid it was only necessary to
906 write value back to this argument).
908 Index of child changed (you can use Item(childIndex) to get
911 (Pending) value of the child property.
914 Modified value of the whole property.
916 virtual wxVariant
ChildChanged( wxVariant
& thisValue
,
918 wxVariant
& childValue
) const;
921 Returns pointer to an instance of used editor.
923 virtual const wxPGEditor
* DoGetEditorClass() const;
926 Returns pointer to the wxValidator that should be used
927 with the editor of this property (@NULL for no validator).
928 Setting validator explicitly via SetPropertyValidator
931 In most situations, code like this should work well
932 (macros are used to maintain one actual validator instance,
933 so on the second call the function exits within the first
938 wxValidator* wxMyPropertyClass::DoGetValidator () const
940 WX_PG_DOGETVALIDATOR_ENTRY()
942 wxMyValidator* validator = new wxMyValidator(...);
944 ... prepare validator...
946 WX_PG_DOGETVALIDATOR_EXIT(validator)
952 You can get common filename validator by returning
953 wxFileProperty::GetClassValidator(). wxDirProperty,
954 for example, uses it.
956 virtual wxValidator
* DoGetValidator () const;
959 Override to paint an image in front of the property value text or drop-down
960 list item (but only if wxPGProperty::OnMeasureImage is overridden as well).
962 If property's OnMeasureImage() returns size that has height != 0 but less than
963 row height ( < 0 has special meanings), wxPropertyGrid calls this method to
964 draw a custom image in a limited area in front of the editor control or
965 value text/graphics, and if control has drop-down list, then the image is
966 drawn there as well (even in the case OnMeasureImage() returned higher height
969 NOTE: Following applies when OnMeasureImage() returns a "flexible" height (
970 using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable height items:
971 If rect.x is < 0, then this is a measure item call, which means that
972 dc is invalid and only thing that should be done is to set paintdata.m_drawnHeight
973 to the height of the image of item at index paintdata.m_choiceItem. This call
974 may be done even as often as once every drop-down popup show.
979 Box reserved for custom graphics. Includes surrounding rectangle, if any.
980 If x is < 0, then this is a measure item call (see above).
982 wxPGPaintData structure with much useful data about painted item.
987 const wxPropertyGrid* m_parent;
989 // Normally -1, otherwise index to drop-down list item that has to be drawn.
992 // Set to drawn width in OnCustomPaint (optional).
995 // In a measure item call, set this to the height of item at m_choiceItem index
1001 - You can actually exceed rect width, but if you do so then paintdata.m_drawnWidth
1002 must be set to the full width drawn in pixels.
1003 - Due to technical reasons, rect's height will be default even if custom height
1004 was reported during measure call.
1005 - Brush is guaranteed to be default background colour. It has been already used to
1006 clear the background of area being painted. It can be modified.
1007 - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper colour) pen for
1008 drawing framing rectangle. It can be changed as well.
1010 @see ValueToString()
1012 virtual void OnCustomPaint( wxDC
& dc
, const wxRect
& rect
, wxPGPaintData
& paintdata
);
1015 Returns used wxPGCellRenderer instance for given property column (label=0, value=1).
1017 Default implementation returns editor's renderer for all columns.
1019 virtual wxPGCellRenderer
* GetCellRenderer( int column
) const;
1022 Returns which choice is currently selected. Only applies to properties
1025 Needs to reimplemented in derived class if property value does not
1026 map directly to a choice. Integer as index, bool, and string usually do.
1028 virtual int GetChoiceSelection() const;
1031 Refresh values of child properties. Automatically called after value is set.
1033 virtual void RefreshChildren();
1036 Reimplement this member function to add special handling for
1037 attributes of this property.
1039 @return Return @false to have the attribute automatically stored in
1040 m_attributes. Default implementation simply does that and
1043 @remarks To actually set property attribute values from the
1044 application, use wxPGProperty::SetAttribute() instead.
1046 virtual bool DoSetAttribute( const wxString
& name
, wxVariant
& value
);
1049 Returns value of an attribute.
1051 Override if custom handling of attributes is needed.
1053 Default implementation simply return @NULL variant.
1055 virtual wxVariant
DoGetAttribute( const wxString
& name
) const;
1058 Returns instance of a new wxPGEditorDialogAdapter instance, which is
1059 used when user presses the (optional) button next to the editor control;
1061 Default implementation returns @NULL (ie. no action is generated when
1064 virtual wxPGEditorDialogAdapter
* GetEditorDialog() const;
1067 Called whenever validation has failed with given pending value.
1069 @remarks If you implement this in your custom property class, please
1070 remember to call the baser implementation as well, since they
1071 may use it to revert property into pre-change state.
1073 virtual void OnValidationFailure( wxVariant
& pendingValue
);
1076 Append a new choice to property's list of choices.
1079 Label for added choice.
1082 Value for new choice. Do not specify if you wish this
1083 to equal choice index.
1086 Index to added choice.
1088 int AddChoice( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1091 Adds a private child property.
1093 @deprecated Use AddPrivateChild() instead.
1095 @see AddPrivateChild()
1097 wxDEPRECATED( void AddChild( wxPGProperty
* prop
) );
1100 Adds a private child property. If you use this instead of
1101 wxPropertyGridInterface::Insert() or
1102 wxPropertyGridInterface::AppendIn(), then property's parental
1103 type will automatically be set up to wxPG_PROP_AGGREGATE. In other
1104 words, all properties of this property will become private.
1106 void AddPrivateChild( wxPGProperty
* prop
);
1109 Adapts list variant into proper value using consecutive
1110 ChildChanged() calls.
1112 void AdaptListToValue( wxVariant
& list
, wxVariant
* value
) const;
1115 Use this member function to add independent (ie. regular) children to
1118 @return Appended childProperty.
1120 @remarks wxPropertyGrid is not automatically refreshed by this
1123 @see InsertChild(), AddPrivateChild()
1125 wxPGProperty
* AppendChild( wxPGProperty
* childProperty
);
1128 Determines, recursively, if all children are not unspecified.
1131 Assumes members in this wxVariant list as pending
1134 bool AreAllChildrenSpecified( wxVariant
* pendingList
= NULL
) const;
1137 Returns @true if children of this property are component values (for instance,
1138 points size, face name, and is_underlined are component values of a font).
1140 bool AreChildrenComponents() const;
1143 Sets or clears given property flag.
1145 @see propgrid_propflags
1147 void ChangeFlag( wxPGPropertyFlags flag
, bool set
);
1150 Deletes children of the property.
1152 void DeleteChildren();
1155 Removes entry from property's wxPGChoices and editor control (if it is active).
1157 If selected item is deleted, then the value is set to unspecified.
1159 void DeleteChoice( int index
);
1161 /** Deletes all child properties. */
1165 Enables or disables the property. Disabled property usually appears
1166 as having grey text.
1169 If @false, property is disabled instead.
1171 @see wxPropertyGridInterface::EnableProperty()
1173 void Enable( bool enable
= true );
1176 Composes text from values of child properties.
1178 wxString
GenerateComposedValue() const;
1181 Returns property attribute value, null variant if not found.
1183 wxVariant
GetAttribute( const wxString
& name
) const;
1185 /** Returns named attribute, as string, if found. Otherwise defVal is returned.
1187 wxString
GetAttribute( const wxString
& name
, const wxString
& defVal
) const;
1189 /** Returns named attribute, as long, if found. Otherwise defVal is returned.
1191 long GetAttributeAsLong( const wxString
& name
, long defVal
) const;
1193 /** Returns named attribute, as double, if found. Otherwise defVal is returned.
1195 double GetAttributeAsDouble( const wxString
& name
, double defVal
) const;
1198 Returns attributes as list wxVariant.
1200 wxVariant
GetAttributesAsList() const;
1203 Returns editor used for given column. @NULL for no editor.
1205 const wxPGEditor
* GetColumnEditor( int column
) const;
1207 /** Returns property's base name (ie. parent's name is not added in any case) */
1208 const wxString
& GetBaseName() const;
1211 Returns wxPGCell of given column.
1213 @remarks const version of this member function returns 'default'
1214 wxPGCell object if the property itself didn't hold
1217 const wxPGCell
& GetCell( unsigned int column
) const;
1220 Returns wxPGCell of given column, creating one if necessary.
1222 wxPGCell
& GetCell( unsigned int column
);
1225 Returns wxPGCell of given column, creating one if necessary.
1227 wxPGCell
& GetOrCreateCell( unsigned int column
);
1230 Returns number of child properties.
1232 unsigned int GetChildCount() const;
1235 Returns height of children, recursively, and
1236 by taking expanded/collapsed status into account.
1239 Line height. Pass result of GetGrid()->GetRowHeight() here.
1242 Only used (internally) when finding property y-positions.
1244 int GetChildrenHeight( int lh
, int iMax
= -1 ) const;
1247 Returns read-only reference to property's list of choices.
1249 const wxPGChoices
& GetChoices() const;
1252 Returns client data (void*) of a property.
1254 void* GetClientData() const;
1256 /** Sets managed client object of a property.
1258 wxClientData
*GetClientObject() const;
1261 Returns property's default value. If property's value type is not
1262 a built-in one, and "DefaultValue" attribute is not defined, then
1263 this function usually returns Null variant.
1265 wxVariant
GetDefaultValue() const;
1267 /** Returns property's displayed text.
1269 wxString
GetDisplayedString() const;
1272 Returns wxPGEditor that will be used and created when
1273 property becomes selected. Returns more accurate value
1274 than DoGetEditorClass().
1276 const wxPGEditor
* GetEditorClass() const;
1279 Returns property flags.
1281 FlagType
GetFlags() const;
1283 /** Returns property grid where property lies. */
1284 wxPropertyGrid
* GetGrid() const;
1287 Returns owner wxPropertyGrid, but only if one is currently on a page
1288 displaying this property.
1290 wxPropertyGrid
* GetGridIfDisplayed() const;
1293 Returns property's help or description text.
1295 @see SetHelpString()
1297 const wxString
& GetHelpString() const;
1300 Returns position in parent's array.
1302 unsigned int GetIndexInParent() const;
1304 /** Returns property's label. */
1305 const wxString
& GetLabel() const;
1308 Returns last visible child property, recursively.
1310 const wxPGProperty
* GetLastVisibleSubItem() const;
1313 Returns highest level non-category, non-root parent. Useful when you
1314 have nested properties with children.
1316 @remarks If immediate parent is root or category, this will return the
1319 wxPGProperty
* GetMainParent() const;
1321 /** Returns maximum allowed length of property's text value.
1323 int GetMaxLength() const;
1325 /** Returns property's name with all (non-category, non-root) parents. */
1326 wxString
GetName() const;
1328 /** Return parent of property */
1329 wxPGProperty
* GetParent() const;
1332 Returns (direct) child property with given name (or @NULL if not found).
1334 wxPGProperty
* GetPropertyByName( const wxString
& name
) const;
1336 /** Gets assignable version of property's validator. */
1337 wxValidator
* GetValidator() const;
1340 Returns property's value.
1342 wxVariant
GetValue() const;
1345 Returns bitmap that appears next to value text. Only returns non-@NULL
1346 bitmap if one was set with SetValueImage().
1348 wxBitmap
* GetValueImage() const;
1350 /** Returns text representation of property's value.
1353 If 0 (default value), then displayed string is returned.
1354 If wxPG_FULL_VALUE is set, returns complete, storable string value
1355 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
1356 string value that must be editable in textctrl. If
1357 wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
1358 display as a part of string property's composite text
1361 @remarks In older versions, this function used to be overridden to convert
1362 property's value into a string representation. This function is
1363 now handled by ValueToString(), and overriding this function now
1364 will result in run-time assertion failure.
1366 virtual wxString
GetValueAsString( int argFlags
= 0 ) const;
1368 /** Synonymous to GetValueAsString().
1370 @deprecated Use GetValueAsString() instead.
1372 @see GetValueAsString()
1374 wxDEPRECATED( wxString
GetValueString( int argFlags
= 0 ) const );
1377 Returns value type used by this property.
1379 wxString
GetValueType() const;
1382 Returns coordinate to the top y of the property. Note that the
1383 position of scrollbars is not taken into account.
1388 Returns non-zero if property has given flag set.
1390 @see propgrid_propflags
1392 FlagType
HasFlag( wxPGPropertyFlags flag
) const;
1395 Returns @true if property has even one visible child.
1397 bool HasVisibleChildren() const;
1400 Hides or reveals the property.
1403 @true for hide, @false for reveal.
1406 By default changes are applied recursively. Set this parameter wxPG_DONT_RECURSE to prevent this.
1408 bool Hide( bool hide
, int flags
= wxPG_RECURSE
);
1411 Returns index of given child property. wxNOT_FOUND if
1412 given property is not child of this.
1414 int Index( const wxPGProperty
* p
) const;
1417 Use this member function to add independent (ie. regular) children to
1420 @return Inserted childProperty.
1422 @remarks wxPropertyGrid is not automatically refreshed by this
1425 @see AppendChild(), AddPrivateChild()
1427 wxPGProperty
* InsertChild( int index
, wxPGProperty
* childProperty
);
1430 Inserts a new choice to property's list of choices.
1436 Insertion position. Use wxNOT_FOUND to append.
1439 Value for new choice. Do not specify if you wish this
1440 to equal choice index.
1442 int InsertChoice( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1445 Returns @true if this property is actually a wxPropertyCategory.
1447 bool IsCategory() const;
1450 Returns @true if property is enabled.
1452 bool IsEnabled() const;
1455 Returns @true if property has visible children.
1457 bool IsExpanded() const;
1460 Returns @true if this property is actually a wxRootProperty.
1462 bool IsRoot() const;
1465 Returns @true if candidateParent is some parent of this property.
1467 bool IsSomeParent( wxPGProperty
* candidateParent
) const;
1470 Returns true if property has editable wxTextCtrl when selected.
1472 @remarks Altough disabled properties do not displayed editor, they still
1473 return @true here as being disabled is considered a temporary
1474 condition (unlike being read-only or having limited editing enabled).
1476 bool IsTextEditable() const;
1479 Returns @true if property's value is considered unspecified. This
1480 usually means that value is Null variant.
1482 bool IsValueUnspecified() const;
1485 Returns true if all parents expanded.
1487 bool IsVisible() const;
1490 Returns child property at index i.
1492 wxPGProperty
* Item( unsigned int i
) const;
1495 If property's editor is active, then update it's value.
1497 void RefreshEditor();
1500 Sets an attribute for this property.
1503 Text identifier of attribute. See @ref propgrid_property_attributes.
1508 @remarks Setting attribute's value to Null variant will simply remove it
1509 from property's set of attributes.
1511 void SetAttribute( const wxString
& name
, wxVariant value
);
1514 Sets property's background colour.
1517 Background colour to use.
1520 Default is wxPG_RECURSE which causes colour to be set recursively.
1521 Omit this flag to only set colour for the property in question
1522 and not any of its children.
1524 void SetBackgroundColour( const wxColour
& colour
,
1525 int flags
= wxPG_RECURSE
);
1528 Sets editor for a property.
1531 For builtin editors, use wxPGEditor_X, where X is builtin editor's
1532 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list).
1534 For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
1536 void SetEditor( const wxPGEditor
* editor
);
1539 Sets editor for a property, by editor name.
1541 void SetEditor( const wxString
& editorName
);
1544 Sets cell information for given column.
1546 void SetCell( int column
, const wxPGCell
& cell
);
1549 Sets new set of choices for the property.
1551 @remarks This operation deselects the property and clears its
1554 bool SetChoices( wxPGChoices
& choices
);
1557 Sets client data (void*) of a property.
1559 @remarks This untyped client data has to be deleted manually.
1561 void SetClientData( void* clientData
);
1563 /** Returns client object of a property.
1565 void SetClientObject(wxClientData
* clientObject
);
1568 Sets selected choice and changes property value.
1570 Tries to retain value type, although currently if it is not string,
1571 then it is forced to integer.
1573 void SetChoiceSelection( int newValue
);
1575 /** Set default value of a property. Synonymous to
1578 SetAttribute("DefaultValue", value);
1581 void SetDefaultValue( wxVariant
& value
);
1584 Sets given property flag.
1586 @see propgrid_propflags
1588 void SetFlag( wxPGPropertyFlags flag
);
1591 Sets or clears given property flag, recursively.
1593 @see propgrid_propflags
1595 void SetFlagRecursively( wxPGPropertyFlags flag
, bool set
);
1598 Sets property's help string, which is shown, for example, in
1599 wxPropertyGridManager's description text box.
1601 void SetHelpString( const wxString
& helpString
);
1604 Sets property's label.
1606 @remarks Properties under same parent may have same labels. However,
1607 property names must still remain unique.
1609 void SetLabel( const wxString
& label
);
1612 Set max length of text in text editor.
1614 bool SetMaxLength( int maxLen
);
1617 Sets property's "is it modified?" flag. Affects children recursively.
1619 void SetModifiedStatus( bool modified
);
1622 Sets new (base) name for property.
1624 void SetName( const wxString
& newName
);
1627 Changes what sort of parent this property is for its children.
1630 Use one of the following values: wxPG_PROP_MISC_PARENT (for generic
1631 parents), wxPG_PROP_CATEGORY (for categories), or
1632 wxPG_PROP_AGGREGATE (for derived property classes with private
1635 @remarks You generally do not need to call this function.
1637 void SetParentalType( int flag
);
1640 Sets property's text colour.
1646 Default is wxPG_RECURSE which causes colour to be set recursively.
1647 Omit this flag to only set colour for the property in question
1648 and not any of its children.
1650 void SetTextColour( const wxColour
& colour
,
1651 int flags
= wxPG_RECURSE
);
1653 /** Sets wxValidator for a property */
1654 void SetValidator( const wxValidator
& validator
);
1657 Call this to set value of the property. Unlike methods in wxPropertyGrid,
1658 this does not automatically update the display.
1661 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through
1662 validation process and send property change event.
1664 If you need to change property value in event, based on user input, use
1665 SetValueInEvent() instead.
1670 Pointer to list variant that contains child values. Used to indicate
1671 which children should be marked as modified. Usually you just use @NULL.
1673 wxPG_SETVAL_REFRESH_EDITOR is set by default, to refresh editor
1674 and redraw properties.
1676 void SetValue( wxVariant value
, wxVariant
* pList
= NULL
,
1677 int flags
= wxPG_SETVAL_REFRESH_EDITOR
);
1680 Set wxBitmap in front of the value. This bitmap may be ignored
1681 by custom cell renderers.
1683 void SetValueImage( wxBitmap
& bmp
);
1686 Call this function in OnEvent(), OnButtonClick() etc. to change the
1687 property value based on user input.
1689 @remarks This method is const since it doesn't actually modify value, but posts
1690 given variant as pending value, stored in wxPropertyGrid.
1692 void SetValueInEvent( wxVariant value
) const;
1695 Sets property's value to unspecified (ie. Null variant).
1697 void SetValueToUnspecified();
1700 Call with @false in OnSetValue() to cancel value changes after all
1701 (ie. cancel @true returned by StringToValue() or IntToValue()).
1703 void SetWasModified( bool set
= true );
1706 Updates composed values of parent non-category properties, recursively.
1707 Returns topmost property updated.
1709 wxPGProperty
* UpdateParentValues();
1712 Returns @true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
1714 bool UsesAutoUnspecified() const;
1721 Base class for wxPropertyGrid cell information.
1723 @library{wxpropgrid}
1726 class wxPGCell
: public wxObject
1730 wxPGCell(const wxPGCell
& other
);
1731 wxPGCell( const wxString
& text
,
1732 const wxBitmap
& bitmap
= wxNullBitmap
,
1733 const wxColour
& fgCol
= wxNullColour
,
1734 const wxColour
& bgCol
= wxNullColour
);
1736 virtual ~wxPGCell();
1738 const wxPGCellData
* GetData() const;
1741 Returns @true if this cell has custom text stored within.
1743 bool HasText() const;
1746 Merges valid data from srcCell into this.
1748 void MergeFrom( const wxPGCell
& srcCell
);
1750 void SetText( const wxString
& text
);
1751 void SetBitmap( const wxBitmap
& bitmap
);
1752 void SetFgCol( const wxColour
& col
);
1755 Sets font of the cell.
1757 @remarks Because wxPropertyGrid does not support rows of
1758 different height, it makes little sense to change
1759 size of the font. Therefore it is recommended
1760 to use return value of wxPropertyGrid::GetFont()
1761 or wxPropertyGrid::GetCaptionFont() as a basis
1762 for the font that, after modifications, is passed
1763 to this member function.
1765 void SetFont( const wxFont
& font
);
1767 void SetBgCol( const wxColour
& col
);
1769 const wxString
& GetText() const;
1770 const wxBitmap
& GetBitmap() const;
1771 const wxColour
& GetFgCol() const;
1774 Returns font of the cell. If no specific font is set for this
1775 cell, then the font will be invalid.
1777 const wxFont
& GetFont() const;
1779 const wxColour
& GetBgCol() const;
1781 wxPGCell
& operator=( const wxPGCell
& other
);
1788 Helper class for managing choices of wxPropertyGrid properties.
1789 Each entry can have label, value, bitmap, text colour, and background
1792 wxPGChoices uses reference counting, similar to other wxWidgets classes.
1793 This means that assignment operator and copy constructor only copy the
1794 reference and not the actual data. Use Copy() member function to create a
1797 @remarks If you do not specify value for entry, index is used.
1799 @library{wxpropgrid}
1805 typedef long ValArrItem
;
1808 Default constructor.
1813 Copy constructor, uses reference counting. To create a real copy,
1814 use Copy() member function instead.
1816 wxPGChoices( const wxPGChoices
& a
);
1819 wxPGChoices( const wxChar
** labels
, const long* values
= NULL
);
1822 wxPGChoices( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() );
1825 wxPGChoices( wxPGChoicesData
* data
);
1831 Adds to current. If did not have own copies, creates them now. If was empty,
1832 identical to set except that creates copies.
1834 void Add( const wxChar
** labels
, const ValArrItem
* values
= NULL
);
1836 /** Version that works with wxArrayString. */
1837 void Add( const wxArrayString
& arr
, const ValArrItem
* values
= NULL
);
1839 /** Version that works with wxArrayString and wxArrayInt. */
1840 void Add( const wxArrayString
& arr
, const wxArrayInt
& arrint
);
1842 /** Adds single item. */
1843 wxPGChoiceEntry
& Add( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1845 /** Adds a single item, with bitmap. */
1846 wxPGChoiceEntry
& Add( const wxString
& label
, const wxBitmap
& bitmap
,
1847 int value
= wxPG_INVALID_VALUE
);
1849 /** Adds a single item with full entry information. */
1850 wxPGChoiceEntry
& Add( const wxPGChoiceEntry
& entry
);
1852 /** Adds single item, sorted. */
1853 wxPGChoiceEntry
& AddAsSorted( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1856 Assigns choices data, using reference counting. To create a real copy,
1857 use Copy() member function instead.
1859 void Assign( const wxPGChoices
& a
);
1862 Assigns data from another set of choices.
1864 void AssignData( wxPGChoicesData
* data
);
1872 Returns a real copy of the choices.
1874 wxPGChoices
Copy() const;
1877 Returns labe of item.
1879 const wxString
& GetLabel( unsigned int ind
) const;
1882 Returns number of items.
1884 unsigned int GetCount() const;
1887 Returns value of item;
1889 int GetValue( unsigned int ind
) const;
1892 Returns array of values matching the given strings. Unmatching strings
1893 result in wxPG_INVALID_VALUE entry in array.
1895 wxArrayInt
GetValuesForStrings( const wxArrayString
& strings
) const;
1898 Returns array of indices matching given strings. Unmatching strings
1899 are added to 'unmatched', if not @NULL.
1901 wxArrayInt
GetIndicesForStrings( const wxArrayString
& strings
,
1902 wxArrayString
* unmatched
= NULL
) const;
1904 /** Returns property at given virtual y coordinate.
1906 wxPGProperty
* GetItemAtY( unsigned int y
) const;
1909 Returns @true if item at given index has a valid value;
1911 bool HasValue( unsigned int i
) const;
1914 Returns index of item with given label.
1916 int Index( const wxString
& label
) const;
1919 Returns index of item with given value.
1921 int Index( int val
) const;
1924 Inserts single item.
1926 wxPGChoiceEntry
& Insert( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1929 Inserts a single item with full entry information.
1931 wxPGChoiceEntry
& Insert( const wxPGChoiceEntry
& entry
, int index
);
1934 Returns @false if this is a constant empty set of choices,
1935 which should not be modified.
1940 Returns item at given index.
1942 const wxPGChoiceEntry
& Item( unsigned int i
) const;
1945 Returns item at given index.
1947 wxPGChoiceEntry
& Item( unsigned int i
);
1950 Removes count items starting at position nIndex.
1952 void RemoveAt(size_t nIndex
, size_t count
= 1);
1955 Sets contents from lists of strings and values.
1957 void Set( const wxChar
** labels
, const long* values
= NULL
);
1960 Sets contents from lists of strings and values.
1962 void Set( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() );
1965 Creates exclusive copy of current choices.
1967 void AllocExclusive();
1970 Returns array of choice labels.
1972 wxArrayString
GetLabels() const;
1974 void operator= (const wxPGChoices
& a
);
1976 wxPGChoiceEntry
& operator[](unsigned int i
);
1977 const wxPGChoiceEntry
& operator[](unsigned int i
) const;
1980 // -----------------------------------------------------------------------