1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxPGProperty
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 #define wxNullProperty ((wxPGProperty*)NULL)
13 /** @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers
15 wxPGProperty::SetAttribute() and
16 wxPropertyGridInterface::SetPropertyAttribute()
17 accept one of these as attribute name argument .
19 You can use strings instead of constants. However, some of these
20 constants are redefined to use cached strings which may reduce
21 your binary size by some amount.
26 /** Set default value for property.
28 #define wxPG_ATTR_DEFAULT_VALUE wxS("DefaultValue")
30 /** Universal, int or double. Minimum value for numeric properties.
32 #define wxPG_ATTR_MIN wxS("Min")
34 /** Universal, int or double. Maximum value for numeric properties.
36 #define wxPG_ATTR_MAX wxS("Max")
38 /** Universal, string. When set, will be shown as text after the displayed
39 text value. Alternatively, if third column is enabled, text will be shown
40 there (for any type of property).
42 #define wxPG_ATTR_UNITS wxS("Units")
44 /** Universal, string. When set, will be shown in property's value cell
45 when displayed value string is empty, or value is unspecified.
47 #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp")
49 /** wxBoolProperty specific, int, default 0. When 1 sets bool property to
50 use checkbox instead of choice.
52 #define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox")
54 /** wxBoolProperty specific, int, default 0. When 1 sets bool property value
55 to cycle on double click (instead of showing the popup listbox).
57 #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING wxS("UseDClickCycling")
59 /** wxFloatProperty (and similar) specific, int, default -1. Sets the (max) precision
60 used when floating point value is rendered as text. The default -1 means infinite
63 #define wxPG_FLOAT_PRECISION wxS("Precision")
65 /** The text will be echoed as asterisks (wxTE_PASSWORD will be passed to textctrl etc).
67 #define wxPG_STRING_PASSWORD wxS("Password")
69 /** Define base used by a wxUIntProperty. Valid constants are
70 wxPG_BASE_OCT, wxPG_BASE_DEC, wxPG_BASE_HEX and wxPG_BASE_HEXL
71 (lowercase characters).
73 #define wxPG_UINT_BASE wxS("Base")
75 /** Define prefix rendered to wxUIntProperty. Accepted constants
76 wxPG_PREFIX_NONE, wxPG_PREFIX_0x, and wxPG_PREFIX_DOLLAR_SIGN.
77 <b>Note:</b> Only wxPG_PREFIX_NONE works with Decimal and Octal
80 #define wxPG_UINT_PREFIX wxS("Prefix")
82 /** wxFileProperty/wxImageFileProperty specific, wxChar*, default is detected/varies.
83 Sets the wildcard used in the triggered wxFileDialog. Format is the
86 #define wxPG_FILE_WILDCARD wxS("Wildcard")
88 /** wxFileProperty/wxImageFileProperty specific, int, default 1.
89 When 0, only the file name is shown (i.e. drive and directory are hidden).
91 #define wxPG_FILE_SHOW_FULL_PATH wxS("ShowFullPath")
93 /** Specific to wxFileProperty and derived properties, wxString, default empty.
94 If set, then the filename is shown relative to the given path string.
96 #define wxPG_FILE_SHOW_RELATIVE_PATH wxS("ShowRelativePath")
98 /** Specific to wxFileProperty and derived properties, wxString, default is empty.
99 Sets the initial path of where to look for files.
101 #define wxPG_FILE_INITIAL_PATH wxS("InitialPath")
103 /** Specific to wxFileProperty and derivatives, wxString, default is empty.
104 Sets a specific title for the dir dialog.
106 #define wxPG_FILE_DIALOG_TITLE wxS("DialogTitle")
108 /** Specific to wxDirProperty, wxString, default is empty.
109 Sets a specific message for the dir dialog.
111 #define wxPG_DIR_DIALOG_MESSAGE wxS("DialogMessage")
113 /** Sets displayed date format for wxDateProperty.
115 #define wxPG_DATE_FORMAT wxS("DateFormat")
117 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
118 is wxDP_DEFAULT | wxDP_SHOWCENTURY.
120 #define wxPG_DATE_PICKER_STYLE wxS("PickerStyle")
122 /** SpinCtrl editor, int or double. How much number changes when button is
123 pressed (or up/down on keybard).
125 #define wxPG_ATTR_SPINCTRL_STEP wxS("Step")
127 /** SpinCtrl editor, bool. If true, value wraps at Min/Max.
129 #define wxPG_ATTR_SPINCTRL_WRAP wxS("Wrap")
131 /** wxMultiChoiceProperty, int. If 0, no user strings allowed. If 1, user strings
132 appear before list strings. If 2, user strings appear after list string.
134 #define wxPG_ATTR_MULTICHOICE_USERSTRINGMODE wxS("UserStringMode")
136 /** wxColourProperty and its kind, int, default 1. Setting this attribute to 0 hides custom
137 colour from property's list of choices.
139 #define wxPG_COLOUR_ALLOW_CUSTOM wxS("AllowCustom")
144 // -----------------------------------------------------------------------
146 /** @class wxPGProperty
148 wxPGProperty is base class for all wxPropertyGrid properties. In
149 sections below we cover few related topics.
151 @li @ref pgproperty_properties
152 @li @ref pgproperty_creating
154 @section pgproperty_properties Supplied Ready-to-use Property Classes
156 Here is a list and short description of supplied fully-functional
157 property classes. They are located in either props.h or advprops.h.
159 @li @ref wxArrayStringProperty
160 @li @ref wxBoolProperty
161 @li @ref wxColourProperty
162 @li @ref wxCursorProperty
163 @li @ref wxDateProperty
164 @li @ref wxDirProperty
165 @li @ref wxEditEnumProperty
166 @li @ref wxEnumProperty
167 @li @ref wxFileProperty
168 @li @ref wxFlagsProperty
169 @li @ref wxFloatProperty
170 @li @ref wxFontProperty
171 @li @ref wxImageFileProperty
172 @li @ref wxIntProperty
173 @li @ref wxLongStringProperty
174 @li @ref wxMultiChoiceProperty
175 @li @ref wxPropertyCategory
176 @li @ref wxStringProperty
177 @li @ref wxSystemColourProperty
178 @li @ref wxUIntProperty
180 @subsection wxPropertyCategory
182 Not an actual property per se, but a header for a group of properties.
183 Regardless inherits from wxPGProperty.
185 @subsection wxStringProperty
187 Simple string property. wxPG_STRING_PASSWORD attribute may be used
188 to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl.
190 @remarks wxStringProperty has a special trait: if it has value of
191 "<composed>", and also has child properties, then its displayed
192 value becomes composition of child property values, similar as
193 with wxFontProperty, for instance.
195 @subsection wxIntProperty
197 Like wxStringProperty, but converts text to a signed long integer.
198 wxIntProperty seamlessly supports 64-bit integers (ie. wxLongLong).
199 To safely convert variant to integer, use code like this:
203 ll << property->GetValue();
206 wxLongLong ll = propertyGrid->GetPropertyValueAsLong(property);
209 @subsection wxUIntProperty
211 Like wxIntProperty, but displays value as unsigned int. To set
212 the prefix used globally, manipulate wxPG_UINT_PREFIX string attribute.
213 To set the globally used base, manipulate wxPG_UINT_BASE int
214 attribute. Regardless of current prefix, understands (hex) values starting
215 with both "0x" and "$".
216 Like wxIntProperty, wxUIntProperty seamlessly supports 64-bit unsigned
217 integers (ie. wxULongLong). Same wxVariant safety rules apply.
219 @subsection wxFloatProperty
221 Like wxStringProperty, but converts text to a double-precision floating point.
222 Default float-to-text precision is 6 decimals, but this can be changed
223 by modifying wxPG_FLOAT_PRECISION attribute.
225 @subsection wxBoolProperty
227 Represents a boolean value. wxChoice is used as editor control, by the
228 default. wxPG_BOOL_USE_CHECKBOX attribute can be set to true inorder to use
231 @subsection wxLongStringProperty
233 Like wxStringProperty, but has a button that triggers a small text editor
234 dialog. Note that in long string values, tabs are represented by "\t" and
237 To display custom dialog on button press, you can subclass
238 wxLongStringProperty and implement OnButtonClick, like this:
241 virtual bool OnButtonClick( wxPropertyGrid* propGrid, wxString& value )
243 // Update property value from editor, if necessary
244 PrepareValueForDialogEditing(propGrid);
246 wxSize dialogSize(...size of your dialog...);
248 wxPoint dlgPos = propGrid->GetGoodEditorDialogPosition(this,
251 // Create dialog dlg at dlgPos. Use value as initial string
255 if ( dlg.ShowModal() == wxID_OK )
257 value = dlg.GetStringValue);
264 Also, if you wish not to have line breaks and tabs translated to
265 escape sequences, then do following in constructor of your subclass:
268 m_flags |= wxPG_PROP_NO_ESCAPE;
271 @subsection wxDirProperty
273 Like wxLongStringProperty, but the button triggers dir selector instead.
274 Supported properties (all with string value): wxPG_DIR_DIALOG_MESSAGE.
276 @subsection wxFileProperty
278 Like wxLongStringProperty, but the button triggers file selector instead.
279 Default wildcard is "All files..." but this can be changed by setting
280 wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details).
281 Attribute wxPG_FILE_SHOW_FULL_PATH can be set to false inorder to show
282 only the filename, not the entire path.
284 @subsection wxEnumProperty
286 Represents a single selection from a list of choices -
287 wxOwnerDrawnComboBox is used to edit the value.
289 @subsection wxFlagsProperty
291 Represents a bit set that fits in a long integer. wxBoolProperty sub-properties
292 are created for editing individual bits. Textctrl is created to manually edit
293 the flags as a text; a continous sequence of spaces, commas and semicolons
294 is considered as a flag id separator.
295 <b>Note: </b> When changing "choices" (ie. flag labels) of wxFlagsProperty, you
296 will need to use wxPGProperty::SetChoices() - otherwise they will not get updated
299 @subsection wxArrayStringProperty
301 Allows editing of a list of strings in wxTextCtrl and in a separate dialog.
303 @subsection wxDateProperty
305 wxDateTime property. Default editor is DatePickerCtrl, altough TextCtrl
306 should work as well. wxPG_DATE_FORMAT attribute can be used to change
307 string wxDateTime::Format uses (altough default is recommended as it is
308 locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window
309 style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY).
311 @subsection wxEditEnumProperty
313 Represents a string that can be freely edited or selected from list of choices -
314 custom combobox control is used to edit the value.
316 @subsection wxMultiChoiceProperty
318 Allows editing a multiple selection from a list of strings. This is
319 property is pretty much built around concept of wxMultiChoiceDialog.
320 It uses wxArrayString value.
322 @subsection wxImageFileProperty
324 Like wxFileProperty, but has thumbnail of the image in front of
325 the filename and autogenerates wildcard from available image handlers.
327 @subsection wxColourProperty
329 <b>Useful alternate editor:</b> Choice.
331 Represents wxColour. wxButton is used to trigger a colour picker dialog.
333 @subsection wxFontProperty
335 Represents wxFont. Various sub-properties are used to edit individual
338 @subsection wxSystemColourProperty
340 Represents wxColour and a system colour index. wxChoice is used to edit
341 the value. Drop-down list has color images. Note that value type
342 is wxColourPropertyValue instead of wxColour.
344 class wxColourPropertyValue : public wxObject
347 // An integer value relating to the colour, and which exact
348 // meaning depends on the property with which it is used.
350 // For wxSystemColourProperty:
351 // Any of wxSYS_COLOUR_XXX, or any web-colour ( use wxPG_TO_WEB_COLOUR
352 // macro - (currently unsupported) ), or wxPG_COLOUR_CUSTOM.
355 // Resulting colour. Should be correct regardless of type.
360 @subsection wxCursorProperty
362 Represents a wxCursor. wxChoice is used to edit the value.
363 Drop-down list has cursor images under some (wxMSW) platforms.
366 @section pgproperty_creating Creating Custom Properties
368 New properties can be created by subclassing wxPGProperty or one
369 of the provided property classes, and (re)implementing necessary
370 member functions. Below, each virtual member function has ample
371 documentation about its purpose and any odd details which to keep
374 Here is a very simple 'template' code:
377 class MyProperty : public wxPGProperty
380 // All arguments of ctor must have a default value -
381 // use wxPG_LABEL for label and name
382 MyProperty( const wxString& label = wxPG_LABEL,
383 const wxString& name = wxPG_LABEL,
384 const wxString& value = wxEmptyString )
386 // m_value is wxVariant
390 virtual ~MyProperty() { }
392 const wxPGEditor* DoGetEditorClass() const
394 // Determines editor used by property.
395 // You can replace 'TextCtrl' below with any of these
396 // builtin-in property editor identifiers: Choice, ComboBox,
397 // TextCtrlAndButton, ChoiceAndButton, CheckBox, SpinCtrl,
399 return wxPGEditor_TextCtrl;
402 virtual wxString GetValueAsString( int argFlags ) const
404 // TODO: Return property value in string format
407 virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags )
409 // TODO: Adapt string to property value.
416 Since wxPGProperty derives from wxObject, you can use standard
417 DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS macros. From the
418 above example they were omitted for sake of simplicity, and besides,
419 they are only really needed if you need to use wxRTTI with your
422 You can change the 'value type' of a property by simply assigning different
423 type of variant with SetValue. <b>It is mandatory to implement
424 wxVariantData class for all data types used as property values.</b>
425 You can use macros declared in wxPropertyGrid headers. For instance:
429 // (If you need to have export declaration, use version of macros
430 // with _EXPORTED postfix)
431 WX_PG_DECLARE_VARIANT_DATA(MyDataClass)
434 WX_PG_IMPLEMENT_VARIANT_DATA(MyDataClass)
436 // Or, if you don't have valid == operator:
437 WX_PG_IMPLEMENT_VARIANT_DATA_DUMMY_EQ(MyDataClass)
443 class wxPGProperty
: public wxObject
446 typedef wxUint32 FlagType
;
455 Non-abstract property classes should have constructor of this style:
459 MyProperty( const wxString& label, const wxString& name, const T& value )
462 // Generally recommended way to set the initial value
463 // (as it should work in pretty much 100% of cases).
468 // If has private child properties then create them here. For example:
469 // AddChild( new wxStringProperty( "Subprop 1", wxPG_LABEL, value.GetSubProp1() ) );
474 wxPGProperty( const wxString
& label
, const wxString
& name
);
477 Virtual destructor. It is customary for derived properties to implement this.
479 virtual ~wxPGProperty();
482 This virtual function is called after m_value has been set.
485 - If m_value was set to Null variant (ie. unspecified value), OnSetValue()
487 - m_value may be of any variant type. Typically properties internally support only
488 one variant type, and as such OnSetValue() provides a good opportunity to convert
489 supported values into internal type.
490 - Default implementation does nothing.
492 virtual void OnSetValue();
495 Override this to return something else than m_value as the value.
497 virtual wxVariant
DoGetValue() const { return m_value
; }
500 Implement this function in derived class to check the value.
501 Return true if it is ok. Returning false prevents property change events
505 - Default implementation always returns true.
507 virtual bool ValidateValue( wxVariant
& value
, wxPGValidationInfo
& validationInfo
) const;
510 Converts text into wxVariant value appropriate for this property.
513 On function entry this is the old value (should not be wxNullVariant
514 in normal cases). Translated value must be assigned back to it.
517 Text to be translated into variant.
520 If wxPG_FULL_VALUE is set, returns complete, storable value instead
521 of displayable one (they may be different).
522 If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
523 composite property string value (as generated by GetValueAsString()
524 called with this same flag).
526 @return Returns @true if resulting wxVariant value was different.
528 @remarks Default implementation converts semicolon delimited tokens into
529 child values. Only works for properties with children.
531 You might want to take into account that m_value is Null variant
532 if property value is unspecified (which is usually only case if
533 you explicitly enabled that sort behavior).
535 virtual bool StringToValue( wxVariant
& variant
, const wxString
& text
, int argFlags
= 0 ) const;
538 Converts integer (possibly a choice selection) into wxVariant value
539 appropriate for this property.
542 On function entry this is the old value (should not be wxNullVariant
543 in normal cases). Translated value must be assigned back to it.
546 Integer to be translated into variant.
549 If wxPG_FULL_VALUE is set, returns complete, storable value instead
552 @return Returns @true if resulting wxVariant value was different.
555 - If property is not supposed to use choice or spinctrl or other editor
556 with int-based value, it is not necessary to implement this method.
557 - Default implementation simply assign given int to m_value.
558 - If property uses choice control, and displays a dialog on some choice
559 items, then it is preferred to display that dialog in IntToValue
561 - You might want to take into account that m_value is Null variant if
562 property value is unspecified (which is usually only case if you
563 explicitly enabled that sort behavior).
565 virtual bool IntToValue( wxVariant
& value
, int number
, int argFlags
= 0 ) const;
568 Returns text representation of property's value.
571 If wxPG_FULL_VALUE is set, returns complete, storable string value instead of displayable.
572 If wxPG_EDITABLE_VALUE is set, returns string value that must be editable in textctrl.
573 If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to display
574 as a part of composite property string value.
577 Default implementation returns string composed from text representations of
580 virtual wxString
GetValueAsString( int argFlags
= 0 ) const;
583 Converts string to a value, and if successful, calls SetValue() on it.
584 Default behavior is to do nothing.
586 String to get the value from.
588 true if value was changed.
590 bool SetValueFromString( const wxString
& text
, int flags
= 0 );
593 Converts integer to a value, and if succesful, calls SetValue() on it.
594 Default behavior is to do nothing.
596 Int to get the value from.
598 If has wxPG_FULL_VALUE, then the value given is a actual value and not an index.
600 True if value was changed.
602 bool SetValueFromInt( long value
, int flags
= 0 );
605 Returns size of the custom painted image in front of property. This method
606 must be overridden to return non-default value if OnCustomPaint is to be
609 Normally -1, but can be an index to the property's list of items.
611 - Default behavior is to return wxSize(0,0), which means no image.
612 - Default image width or height is indicated with dimension -1.
613 - You can also return wxPG_DEFAULT_IMAGE_SIZE which equals wxSize(-1, -1).
615 virtual wxSize
OnMeasureImage( int item
= -1 ) const;
618 Events received by editor widgets are processed here. Note that editor class
619 usually processes most events. Some, such as button press events of
620 TextCtrlAndButton class, can be handled here. Also, if custom handling
621 for regular events is desired, then that can also be done (for example,
622 wxSystemColourProperty custom handles wxEVT_COMMAND_CHOICE_SELECTED
623 to display colour picker dialog when 'custom' selection is made).
625 If the event causes value to be changed, SetValueInEvent()
626 should be called to set the new value.
631 Should return true if any changes in value should be reported.
633 - If property uses choice control, and displays a dialog on some choice items,
634 then it is preferred to display that dialog in IntToValue instead of OnEvent.
636 virtual bool OnEvent( wxPropertyGrid
* propgrid
, wxWindow
* wnd_primary
, wxEvent
& event
);
639 Called after value of a child property has been altered. Note that this function is
640 usually called at the time that value of this property, or given child property, is
641 still pending for change.
643 Sample pseudo-code implementation:
646 void MyProperty::ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const
648 // Acquire reference to actual type of data stored in variant
649 // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros were used to create
650 // the variant class).
651 T& data = TFromVariant(thisValue);
653 // Copy childValue into data.
654 switch ( childIndex )
657 data.SetSubProp1( childvalue.GetLong() );
660 data.SetSubProp2( childvalue.GetString() );
668 Value of this property, that should be altered.
670 Index of child changed (you can use Item(childIndex) to get).
672 Value of the child property.
674 virtual void ChildChanged( wxVariant
& thisValue
, int childIndex
, wxVariant
& childValue
) const;
677 Returns pointer to an instance of used editor.
679 virtual const wxPGEditor
* DoGetEditorClass() const;
682 Returns pointer to the wxValidator that should be used
683 with the editor of this property (NULL for no validator).
684 Setting validator explicitly via SetPropertyValidator
687 In most situations, code like this should work well
688 (macros are used to maintain one actual validator instance,
689 so on the second call the function exits within the first
694 wxValidator* wxMyPropertyClass::DoGetValidator () const
696 WX_PG_DOGETVALIDATOR_ENTRY()
698 wxMyValidator* validator = new wxMyValidator(...);
700 ... prepare validator...
702 WX_PG_DOGETVALIDATOR_EXIT(validator)
708 You can get common filename validator by returning
709 wxFileProperty::GetClassValidator(). wxDirProperty,
710 for example, uses it.
712 virtual wxValidator
* DoGetValidator () const;
715 Override to paint an image in front of the property value text or drop-down
716 list item (but only if wxPGProperty::OnMeasureImage is overridden as well).
718 If property's OnMeasureImage() returns size that has height != 0 but less than
719 row height ( < 0 has special meanings), wxPropertyGrid calls this method to
720 draw a custom image in a limited area in front of the editor control or
721 value text/graphics, and if control has drop-down list, then the image is
722 drawn there as well (even in the case OnMeasureImage() returned higher height
725 NOTE: Following applies when OnMeasureImage() returns a "flexible" height (
726 using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable height items:
727 If rect.x is < 0, then this is a measure item call, which means that
728 dc is invalid and only thing that should be done is to set paintdata.m_drawnHeight
729 to the height of the image of item at index paintdata.m_choiceItem. This call
730 may be done even as often as once every drop-down popup show.
735 Box reserved for custom graphics. Includes surrounding rectangle, if any.
736 If x is < 0, then this is a measure item call (see above).
738 wxPGPaintData structure with much useful data about painted item.
743 const wxPropertyGrid* m_parent;
745 // Normally -1, otherwise index to drop-down list item that has to be drawn.
748 // Set to drawn width in OnCustomPaint (optional).
751 // In a measure item call, set this to the height of item at m_choiceItem index
757 - You can actually exceed rect width, but if you do so then paintdata.m_drawnWidth
758 must be set to the full width drawn in pixels.
759 - Due to technical reasons, rect's height will be default even if custom height
760 was reported during measure call.
761 - Brush is guaranteed to be default background colour. It has been already used to
762 clear the background of area being painted. It can be modified.
763 - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper colour) pen for
764 drawing framing rectangle. It can be changed as well.
766 @see GetValueAsString()
768 virtual void OnCustomPaint( wxDC
& dc
, const wxRect
& rect
, wxPGPaintData
& paintdata
);
771 Returns used wxPGCellRenderer instance for given property column (label=0, value=1).
773 Default implementation returns editor's renderer for all columns.
775 virtual wxPGCellRenderer
* GetCellRenderer( int column
) const;
778 Returns which choice is currently selected. Only applies to properties
781 Needs to reimplemented in derived class if property value does not
782 map directly to a choice. Integer as index, bool, and string usually do.
784 virtual int GetChoiceSelection() const;
787 Refresh values of child properties. Automatically called after value is set.
789 virtual void RefreshChildren();
792 Special handling for attributes of this property.
794 If returns false, then the attribute will be automatically stored in
797 Default implementation simply returns false.
799 virtual bool DoSetAttribute( const wxString
& name
, wxVariant
& value
);
802 Returns value of an attribute.
804 Override if custom handling of attributes is needed.
806 Default implementation simply return NULL variant.
808 virtual wxVariant
DoGetAttribute( const wxString
& name
) const;
811 Returns instance of a new wxPGEditorDialogAdapter instance, which is
812 used when user presses the (optional) button next to the editor control;
814 Default implementation returns NULL (ie. no action is generated when
817 virtual wxPGEditorDialogAdapter
* GetEditorDialog() const;
820 Returns wxPGCell of given column, NULL if none. If valid
821 object is returned, caller will gain its ownership.
823 wxPGCell
* AcquireCell( unsigned int column
)
825 if ( column
>= m_cells
.size() )
828 wxPGCell
* cell
= (wxPGCell
*) m_cells
[column
];
829 m_cells
[column
] = NULL
;
834 Append a new choice to property's list of choices.
837 Label for added choice.
840 Value for new choice. Do not specify if you wish this
841 to equal choice index.
844 Index to added choice.
846 int AddChoice( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
849 Properties which have private child properties should add them
850 with this function, called in their constructor.
852 void AddChild( wxPGProperty
* property
);
855 Adapts list variant into proper value using consecutive
856 ChildChanged() calls.
858 void AdaptListToValue( wxVariant
& list
, wxVariant
* value
) const;
861 Determines, recursively, if all children are not unspecified.
864 Assumes members in this wxVariant list as pending
867 bool AreAllChildrenSpecified( wxVariant
* pendingList
= NULL
) const;
870 Returns true if children of this property are component values (for instance,
871 points size, face name, and is_underlined are component values of a font).
873 bool AreChildrenComponents() const
875 if ( m_flags
& (wxPG_PROP_COMPOSED_VALUE
|wxPG_PROP_AGGREGATE
) )
882 Removes entry from property's wxPGChoices and editor control (if it is active).
884 If selected item is deleted, then the value is set to unspecified.
886 void DeleteChoice( int index
);
888 /** Deletes all child properties. */
891 /** Composes text from values of child properties. */
892 void GenerateComposedValue( wxString
& text
, int argFlags
= 0 ) const;
895 Returns property attribute value, null variant if not found.
897 wxVariant
GetAttribute( const wxString
& name
) const;
899 /** Returns named attribute, as string, if found. Otherwise defVal is returned.
901 wxString
GetAttribute( const wxString
& name
, const wxString
& defVal
) const;
903 /** Returns named attribute, as long, if found. Otherwise defVal is returned.
905 long GetAttributeAsLong( const wxString
& name
, long defVal
) const;
907 /** Returns named attribute, as double, if found. Otherwise defVal is returned.
909 double GetAttributeAsDouble( const wxString
& name
, double defVal
) const;
912 Returns attributes as list wxVariant.
914 wxVariant
GetAttributesAsList() const;
917 Returns editor used for given column. NULL for no editor.
919 const wxPGEditor
* GetColumnEditor( int column
) const
922 return GetEditorClass();
927 /** Returns property's base name (ie. parent's name is not added in any case) */
928 const wxString
& GetBaseName() const { return m_name
; }
931 Returns wxPGCell of given column, NULL if none. wxPGProperty
932 will retain ownership of the cell object.
934 wxPGCell
* GetCell( unsigned int column
) const
936 if ( column
>= m_cells
.size() )
939 return (wxPGCell
*) m_cells
[column
];
943 Returns number of child properties.
945 unsigned int GetChildCount() const;
948 Returns height of children, recursively, and
949 by taking expanded/collapsed status into account.
952 Line height. Pass result of GetGrid()->GetRowHeight() here.
955 Only used (internally) when finding property y-positions.
957 int GetChildrenHeight( int lh
, int iMax
= -1 ) const;
960 Returns read-only reference to property's list of choices.
962 const wxPGChoices
& GetChoices() const;
965 Returns client data (void*) of a property.
967 void* GetClientData() const;
969 /** Sets managed client object of a property.
971 wxClientData
*GetClientObject() const;
974 Returns property's default value. If property's value type is not
975 a built-in one, and "DefaultValue" attribute is not defined, then
976 this function usually returns Null variant.
978 wxVariant
GetDefaultValue() const;
980 /** Returns property's displayed text.
982 wxString
GetDisplayedString() const
984 return GetValueString(0);
988 Returns wxPGEditor that will be used and created when
989 property becomes selected. Returns more accurate value
990 than DoGetEditorClass().
992 const wxPGEditor
* GetEditorClass() const;
994 /** Returns property grid where property lies. */
995 wxPropertyGrid
* GetGrid() const;
998 Returns owner wxPropertyGrid, but only if one is currently on a page
999 displaying this property.
1001 wxPropertyGrid
* GetGridIfDisplayed() const;
1004 Returns property's help or description text.
1006 @see SetHelpString()
1008 const wxString
& GetHelpString() const;
1011 Returns position in parent's array.
1013 unsigned int GetIndexInParent() const;
1015 /** Returns property's label. */
1016 const wxString
& GetLabel() const { return m_label
; }
1019 Returns last visible child property, recursively.
1021 const wxPGProperty
* GetLastVisibleSubItem() const;
1024 Returns highest level non-category, non-root parent. Useful when you
1025 have nested properties with children.
1027 @remarks If immediate parent is root or category, this will return the
1030 wxPGProperty
* GetMainParent() const;
1032 /** Returns maximum allowed length of property's text value.
1034 int GetMaxLength() const
1036 return (int) m_maxLen
;
1039 /** Returns property's name with all (non-category, non-root) parents. */
1040 wxString
GetName() const;
1042 /** Return parent of property */
1043 wxPGProperty
* GetParent() const { return m_parent
; }
1046 Returns (direct) child property with given name (or NULL if not found).
1048 wxPGProperty
* GetPropertyByName( const wxString
& name
) const;
1050 /** Gets assignable version of property's validator. */
1051 wxValidator
* GetValidator() const;
1054 Returns property's value.
1056 wxVariant
GetValue() const
1058 return DoGetValue();
1062 Returns bitmap that appears next to value text. Only returns non-NULL
1063 bitmap if one was set with SetValueImage().
1065 wxBitmap
* GetValueImage() const;
1068 To acquire property's value as string, you should use this
1069 function (instead of GetValueAsString()), as it may produce
1070 more accurate value in future versions.
1072 @see GetValueAsString()
1074 wxString
GetValueString( int argFlags
= 0 ) const;
1077 Returns value type used by this property.
1079 wxString
GetValueType() const
1081 return m_value
.GetType();
1085 Returns coordinate to the top y of the property. Note that the
1086 position of scrollbars is not taken into account.
1091 Returns true if property has even one visible child.
1093 bool HasVisibleChildren() const;
1096 Hides or reveals the property.
1099 @true for hide, @false for reveal.
1102 By default changes are applied recursively. Set this parameter wxPG_DONT_RECURSE to prevent this.
1104 bool Hide( bool hide
, int flags
= wxPG_RECURSE
);
1107 Returns index of given child property. wxNOT_FOUND if
1108 given property is not child of this.
1110 int Index( const wxPGProperty
* p
) const;
1113 Inserts a new choice to property's list of choices.
1119 Insertion position. Use wxNOT_FOUND to append.
1122 Value for new choice. Do not specify if you wish this
1123 to equal choice index.
1125 int InsertChoice( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1128 Returns @true if this property is actually a wxPropertyCategory.
1130 bool IsCategory() const;
1133 Returns @true if property is enabled.
1135 bool IsEnabled() const;
1138 Returns @true if property has visible children.
1140 bool IsExpanded() const;
1143 Returns @true if this property is actually a wxRootProperty.
1145 bool IsRoot() const { return (m_parent
== NULL
); }
1148 Returns @true if candidateParent is some parent of this property.
1150 bool IsSomeParent( wxPGProperty
* candidateParent
) const;
1153 Returns true if property has editable wxTextCtrl when selected.
1155 @remarks Altough disabled properties do not displayed editor, they still
1156 return @true here as being disabled is considered a temporary
1157 condition (unlike being read-only or having limited editing enabled).
1159 bool IsTextEditable() const;
1162 Returns @true if property's value is considered unspecified. This
1163 usually means that value is Null variant.
1165 bool IsValueUnspecified() const;
1168 Returns true if all parents expanded.
1170 bool IsVisible() const;
1173 Returns child property at index i.
1175 wxPGProperty
* Item( size_t i
) const;
1178 Updates property value in case there were last minute
1179 changes. If value was unspecified, it will be set to default.
1180 Use only for properties that have TextCtrl-based editor.
1182 @remarks If you have code similar to
1184 // Update the value in case of last minute changes
1185 if ( primary && propgrid->IsEditorsValueModified() )
1186 GetEditorClass()->CopyValueFromControl( this, primary );
1188 in wxPGProperty::OnEvent wxEVT_COMMAND_BUTTON_CLICKED handler,
1189 then replace it with call to this method.
1191 @return Returns @true if value changed.
1193 bool PrepareValueForDialogEditing( wxPropertyGrid
* propgrid
);
1196 If property's editor is active, then update it's value.
1198 void RefreshEditor();
1201 Sets an attribute for this property.
1204 Text identifier of attribute. See @ref propgrid_property_attributes.
1209 @remarks Setting attribute's value to Null variant will simply remove it
1210 from property's set of attributes.
1212 void SetAttribute( const wxString
& name
, wxVariant value
);
1215 Sets editor for a property.
1218 For builtin editors, use wxPGEditor_X, where X is builtin editor's
1219 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list).
1221 For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
1223 void SetEditor( const wxPGEditor
* editor
);
1226 Sets editor for a property, by editor name.
1228 void SetEditor( const wxString
& editorName
);
1231 Sets cell information for given column.
1233 Note that the property takes ownership of given wxPGCell instance.
1235 void SetCell( int column
, wxPGCell
* cellObj
);
1238 Sets new set of choices for property.
1240 @remarks This operation clears the property value.
1242 bool SetChoices( wxPGChoices
& choices
);
1245 If property has choices and they are not yet exclusive, new such copy
1246 of them will be created.
1248 void SetChoicesExclusive();
1251 Sets client data (void*) of a property.
1253 @remarks This untyped client data has to be deleted manually.
1255 void SetClientData( void* clientData
);
1257 /** Returns client object of a property.
1259 void SetClientObject(wxClientData
* clientObject
);
1262 Sets selected choice and changes property value.
1264 Tries to retain value type, although currently if it is not string,
1265 then it is forced to integer.
1267 void SetChoiceSelection( int newValue
);
1270 Sets property's help string, which is shown, for example, in
1271 wxPropertyGridManager's description text box.
1273 void SetHelpString( const wxString
& helpString
);
1276 Sets property's label.
1278 @remarks Properties under same parent may have same labels. However,
1279 property names must still remain unique.
1281 void SetLabel( const wxString
& label
) { m_label
= label
; }
1284 Set max length of text in text editor.
1286 bool SetMaxLength( int maxLen
);
1289 Sets property's "is it modified?" flag. Affects children recursively.
1291 void SetModifiedStatus( bool modified
);
1294 Sets new (base) name for property.
1296 void SetName( const wxString
& newName
);
1298 /** Sets wxValidator for a property */
1299 void SetValidator( const wxValidator
& validator
);
1302 Call this to set value of the property. Unlike methods in wxPropertyGrid,
1303 this does not automatically update the display.
1306 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through
1307 validation process and send property change event.
1309 If you need to change property value in event, based on user input, use
1310 SetValueInEvent() instead.
1313 Pointer to list variant that contains child values. Used to indicate
1314 which children should be marked as modified. Usually you just use NULL.
1317 Use wxPG_SETVAL_REFRESH_EDITOR to update editor control, if it
1320 void SetValue( wxVariant value
, wxVariant
* pList
= NULL
, int flags
= 0 );
1323 Set wxBitmap in front of the value. This bitmap may be ignored
1324 by custom cell renderers.
1326 void SetValueImage( wxBitmap
& bmp
);
1329 Call this function in OnEvent(), OnButtonClick() etc. to change the
1330 property value based on user input.
1332 @remarks This method is const since it doesn't actually modify value, but posts
1333 given variant as pending value, stored in wxPropertyGrid.
1335 void SetValueInEvent( wxVariant value
) const;
1338 Sets property's value to unspecified (ie. Null variant).
1340 void SetValueToUnspecified();
1343 Call with @false in OnSetValue() to cancel value changes after all
1344 (ie. cancel @true returned by StringToValue() or IntToValue()).
1346 void SetWasModified( bool set
= true );
1349 Updates composed values of parent non-category properties, recursively.
1350 Returns topmost property updated.
1352 wxPGProperty
* UpdateParentValues();
1355 Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
1357 bool UsesAutoUnspecified() const;
1361 /** @class wxPGChoices
1363 Helper class for managing choices of wxPropertyGrid properties.
1364 Each entry can have label, value, bitmap, text colour, and background colour.
1366 @library{wxpropgrid}
1369 class WXDLLIMPEXP_PROPGRID wxPGChoices
1372 typedef long ValArrItem
;
1375 Default constructor.
1379 /** Copy constructor. */
1380 wxPGChoices( const wxPGChoices
& a
);
1383 wxPGChoices( const wxChar
** labels
, const long* values
= NULL
);
1386 wxPGChoices( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() );
1389 wxPGChoices( wxPGChoicesData
* data
);
1395 Adds to current. If did not have own copies, creates them now. If was empty,
1396 identical to set except that creates copies.
1398 void Add( const wxChar
** labels
, const ValArrItem
* values
= NULL
);
1400 /** Version that works with wxArrayString. */
1401 void Add( const wxArrayString
& arr
, const ValArrItem
* values
= NULL
);
1403 /** Version that works with wxArrayString and wxArrayInt. */
1404 void Add( const wxArrayString
& arr
, const wxArrayInt
& arrint
);
1406 /** Adds single item. */
1407 wxPGChoiceEntry
& Add( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1409 /** Adds a single item, with bitmap. */
1410 wxPGChoiceEntry
& Add( const wxString
& label
, const wxBitmap
& bitmap
,
1411 int value
= wxPG_INVALID_VALUE
);
1413 /** Adds a single item with full entry information. */
1414 wxPGChoiceEntry
& Add( const wxPGChoiceEntry
& entry
)
1416 return Insert(entry
, -1);
1419 /** Adds single item, sorted. */
1420 wxPGChoiceEntry
& AddAsSorted( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1423 Assigns data from another set of choices.
1425 void Assign( const wxPGChoices
& a
)
1427 AssignData(a
.m_data
);
1431 Assigns data from another set of choices.
1433 void AssignData( wxPGChoicesData
* data
);
1440 if ( m_data
!= wxPGChoicesEmptyData
)
1445 Returns labe of item.
1447 const wxString
& GetLabel( size_t ind
) const;
1450 Returns number of items.
1452 size_t GetCount () const;
1455 Returns value of item;
1457 int GetValue( size_t ind
) const;
1460 Returns array of values matching the given strings. Unmatching strings
1461 result in wxPG_INVALID_VALUE entry in array.
1463 wxArrayInt
GetValuesForStrings( const wxArrayString
& strings
) const;
1466 Returns array of indices matching given strings. Unmatching strings
1467 are added to 'unmatched', if not NULL.
1469 wxArrayInt
GetIndicesForStrings( const wxArrayString
& strings
,
1470 wxArrayString
* unmatched
= NULL
) const;
1473 Returns @true if item at given index has a valid value;
1475 bool HasValue( unsigned int i
) const;
1478 Returns index of item with given label.
1480 int Index( const wxString
& label
) const;
1483 Returns index of item with given value.
1485 int Index( int val
) const;
1488 Inserts single item.
1490 wxPGChoiceEntry
& Insert( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1493 Inserts a single item with full entry information.
1495 wxPGChoiceEntry
& Insert( const wxPGChoiceEntry
& entry
, int index
);
1498 Returns false if this is a constant empty set of choices,
1499 which should not be modified.
1503 return ( m_data
!= wxPGChoicesEmptyData
);
1507 Returns item at given index.
1509 const wxPGChoiceEntry
& Item( unsigned int i
) const
1512 return *m_data
->Item(i
);
1516 Returns item at given index.
1518 wxPGChoiceEntry
& Item( unsigned int i
)
1521 return *m_data
->Item(i
);
1525 Removes count items starting at position nIndex.
1527 void RemoveAt(size_t nIndex
, size_t count
= 1);
1530 Sets contents from lists of strings and values.
1532 void Set( const wxChar
** labels
, const long* values
= NULL
);
1535 Sets contents from lists of strings and values.
1537 void Set( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() );
1540 Creates exclusive copy of current choices.
1542 void SetExclusive();
1545 Returns array of choice labels.
1547 wxArrayString
GetLabels() const;
1549 void operator= (const wxPGChoices
& a
)
1551 AssignData(a
.m_data
);
1554 wxPGChoiceEntry
& operator[](unsigned int i
)
1559 const wxPGChoiceEntry
& operator[](unsigned int i
) const
1565 // -----------------------------------------------------------------------