1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxPGProperty
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 #define wxNullProperty ((wxPGProperty*)NULL)
13 /** @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers
15 wxPGProperty::SetAttribute() and
16 wxPropertyGridInterface::SetPropertyAttribute()
17 accept one of these as attribute name argument .
19 You can use strings instead of constants. However, some of these
20 constants are redefined to use cached strings which may reduce
21 your binary size by some amount.
26 /** Set default value for property.
28 #define wxPG_ATTR_DEFAULT_VALUE wxS("DefaultValue")
30 /** Universal, int or double. Minimum value for numeric properties.
32 #define wxPG_ATTR_MIN wxS("Min")
34 /** Universal, int or double. Maximum value for numeric properties.
36 #define wxPG_ATTR_MAX wxS("Max")
38 /** Universal, string. When set, will be shown as text after the displayed
39 text value. Alternatively, if third column is enabled, text will be shown
40 there (for any type of property).
42 #define wxPG_ATTR_UNITS wxS("Units")
44 /** Universal, string. When set, will be shown in property's value cell
45 when displayed value string is empty, or value is unspecified.
47 #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp")
49 /** wxBoolProperty specific, int, default 0. When 1 sets bool property to
50 use checkbox instead of choice.
52 #define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox")
54 /** wxBoolProperty specific, int, default 0. When 1 sets bool property value
55 to cycle on double click (instead of showing the popup listbox).
57 #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING wxS("UseDClickCycling")
59 /** wxFloatProperty (and similar) specific, int, default -1. Sets the (max) precision
60 used when floating point value is rendered as text. The default -1 means infinite
63 #define wxPG_FLOAT_PRECISION wxS("Precision")
65 /** The text will be echoed as asterisks (wxTE_PASSWORD will be passed to textctrl etc).
67 #define wxPG_STRING_PASSWORD wxS("Password")
69 /** Define base used by a wxUIntProperty. Valid constants are
70 wxPG_BASE_OCT, wxPG_BASE_DEC, wxPG_BASE_HEX and wxPG_BASE_HEXL
71 (lowercase characters).
73 #define wxPG_UINT_BASE wxS("Base")
75 /** Define prefix rendered to wxUIntProperty. Accepted constants
76 wxPG_PREFIX_NONE, wxPG_PREFIX_0x, and wxPG_PREFIX_DOLLAR_SIGN.
77 <b>Note:</b> Only wxPG_PREFIX_NONE works with Decimal and Octal
80 #define wxPG_UINT_PREFIX wxS("Prefix")
82 /** wxFileProperty/wxImageFileProperty specific, wxChar*, default is detected/varies.
83 Sets the wildcard used in the triggered wxFileDialog. Format is the
86 #define wxPG_FILE_WILDCARD wxS("Wildcard")
88 /** wxFileProperty/wxImageFileProperty specific, int, default 1.
89 When 0, only the file name is shown (i.e. drive and directory are hidden).
91 #define wxPG_FILE_SHOW_FULL_PATH wxS("ShowFullPath")
93 /** Specific to wxFileProperty and derived properties, wxString, default empty.
94 If set, then the filename is shown relative to the given path string.
96 #define wxPG_FILE_SHOW_RELATIVE_PATH wxS("ShowRelativePath")
98 /** Specific to wxFileProperty and derived properties, wxString, default is empty.
99 Sets the initial path of where to look for files.
101 #define wxPG_FILE_INITIAL_PATH wxS("InitialPath")
103 /** Specific to wxFileProperty and derivatives, wxString, default is empty.
104 Sets a specific title for the dir dialog.
106 #define wxPG_FILE_DIALOG_TITLE wxS("DialogTitle")
108 /** Specific to wxDirProperty, wxString, default is empty.
109 Sets a specific message for the dir dialog.
111 #define wxPG_DIR_DIALOG_MESSAGE wxS("DialogMessage")
113 /** Sets displayed date format for wxDateProperty.
115 #define wxPG_DATE_FORMAT wxS("DateFormat")
117 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
118 is wxDP_DEFAULT | wxDP_SHOWCENTURY.
120 #define wxPG_DATE_PICKER_STYLE wxS("PickerStyle")
122 /** SpinCtrl editor, int or double. How much number changes when button is
123 pressed (or up/down on keybard).
125 #define wxPG_ATTR_SPINCTRL_STEP wxS("Step")
127 /** SpinCtrl editor, bool. If true, value wraps at Min/Max.
129 #define wxPG_ATTR_SPINCTRL_WRAP wxS("Wrap")
131 /** wxMultiChoiceProperty, int. If 0, no user strings allowed. If 1, user strings
132 appear before list strings. If 2, user strings appear after list string.
134 #define wxPG_ATTR_MULTICHOICE_USERSTRINGMODE wxS("UserStringMode")
136 /** wxColourProperty and its kind, int, default 1. Setting this attribute to 0 hides custom
137 colour from property's list of choices.
139 #define wxPG_COLOUR_ALLOW_CUSTOM wxS("AllowCustom")
144 // -----------------------------------------------------------------------
146 /** @class wxPGProperty
148 wxPGProperty is base class for all wxPropertyGrid properties. In
149 sections below we cover few related topics.
151 @li @ref pgproperty_properties
152 @li @ref pgproperty_creating
154 @section pgproperty_properties Supplied Ready-to-use Property Classes
156 Here is a list and short description of supplied fully-functional
157 property classes. They are located in either props.h or advprops.h.
159 @li @ref wxArrayStringProperty
160 @li @ref wxBoolProperty
161 @li @ref wxColourProperty
162 @li @ref wxCursorProperty
163 @li @ref wxDateProperty
164 @li @ref wxDirProperty
165 @li @ref wxEditEnumProperty
166 @li @ref wxEnumProperty
167 @li @ref wxFileProperty
168 @li @ref wxFlagsProperty
169 @li @ref wxFloatProperty
170 @li @ref wxFontProperty
171 @li @ref wxImageFileProperty
172 @li @ref wxIntProperty
173 @li @ref wxLongStringProperty
174 @li @ref wxMultiChoiceProperty
175 @li @ref wxPropertyCategory
176 @li @ref wxStringProperty
177 @li @ref wxSystemColourProperty
178 @li @ref wxUIntProperty
180 @subsection wxPropertyCategory
182 Not an actual property per se, but a header for a group of properties.
183 Regardless inherits from wxPGProperty.
185 @subsection wxStringProperty
187 Simple string property. wxPG_STRING_PASSWORD attribute may be used
188 to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl.
191 * wxStringProperty has a special trait: if it has value of "<composed>",
192 and also has child properties, then its displayed value becomes
193 composition of child property values, similar as with wxFontProperty,
196 @subsection wxIntProperty
198 Like wxStringProperty, but converts text to a signed long integer.
199 wxIntProperty seamlessly supports 64-bit integers (ie. wxLongLong).
201 @subsection wxUIntProperty
203 Like wxIntProperty, but displays value as unsigned int. To set
204 the prefix used globally, manipulate wxPG_UINT_PREFIX string attribute.
205 To set the globally used base, manipulate wxPG_UINT_BASE int
206 attribute. Regardless of current prefix, understands (hex) values starting
207 with both "0x" and "$".
208 wxUIntProperty seamlessly supports 64-bit unsigned integers (ie. wxULongLong).
210 @subsection wxFloatProperty
212 Like wxStringProperty, but converts text to a double-precision floating point.
213 Default float-to-text precision is 6 decimals, but this can be changed
214 by modifying wxPG_FLOAT_PRECISION attribute.
216 @subsection wxBoolProperty
218 Represents a boolean value. wxChoice is used as editor control, by the
219 default. wxPG_BOOL_USE_CHECKBOX attribute can be set to true inorder to use
222 @subsection wxLongStringProperty
224 Like wxStringProperty, but has a button that triggers a small text editor
225 dialog. Note that in long string values, tabs are represented by "\t" and
228 @subsection wxDirProperty
230 Like wxLongStringProperty, but the button triggers dir selector instead.
231 Supported properties (all with string value): wxPG_DIR_DIALOG_MESSAGE.
233 @subsection wxFileProperty
235 Like wxLongStringProperty, but the button triggers file selector instead.
236 Default wildcard is "All files..." but this can be changed by setting
237 wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details).
238 Attribute wxPG_FILE_SHOW_FULL_PATH can be set to false inorder to show
239 only the filename, not the entire path.
241 @subsection wxEnumProperty
243 Represents a single selection from a list of choices -
244 wxOwnerDrawnComboBox is used to edit the value.
246 @subsection wxFlagsProperty
248 Represents a bit set that fits in a long integer. wxBoolProperty sub-properties
249 are created for editing individual bits. Textctrl is created to manually edit
250 the flags as a text; a continous sequence of spaces, commas and semicolons
251 is considered as a flag id separator.
252 <b>Note: </b> When changing "choices" (ie. flag labels) of wxFlagsProperty, you
253 will need to use wxPGProperty::SetChoices() - otherwise they will not get updated
256 @subsection wxArrayStringProperty
258 Allows editing of a list of strings in wxTextCtrl and in a separate dialog.
260 @subsection wxDateProperty
262 wxDateTime property. Default editor is DatePickerCtrl, altough TextCtrl
263 should work as well. wxPG_DATE_FORMAT attribute can be used to change
264 string wxDateTime::Format uses (altough default is recommended as it is
265 locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window
266 style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY).
268 @subsection wxEditEnumProperty
270 Represents a string that can be freely edited or selected from list of choices -
271 custom combobox control is used to edit the value.
273 @subsection wxMultiChoiceProperty
275 Allows editing a multiple selection from a list of strings. This is
276 property is pretty much built around concept of wxMultiChoiceDialog.
277 It uses wxArrayString value.
279 @subsection wxImageFileProperty
281 Like wxFileProperty, but has thumbnail of the image in front of
282 the filename and autogenerates wildcard from available image handlers.
284 @subsection wxColourProperty
286 <b>Useful alternate editor:</b> Choice.
288 Represents wxColour. wxButton is used to trigger a colour picker dialog.
290 @subsection wxFontProperty
292 Represents wxFont. Various sub-properties are used to edit individual
295 @subsection wxSystemColourProperty
297 Represents wxColour and a system colour index. wxChoice is used to edit
298 the value. Drop-down list has color images. Note that value type
299 is wxColourPropertyValue instead of wxColour.
301 class wxColourPropertyValue : public wxObject
304 // An integer value relating to the colour, and which exact
305 // meaning depends on the property with which it is used.
307 // For wxSystemColourProperty:
308 // Any of wxSYS_COLOUR_XXX, or any web-colour ( use wxPG_TO_WEB_COLOUR
309 // macro - (currently unsupported) ), or wxPG_COLOUR_CUSTOM.
312 // Resulting colour. Should be correct regardless of type.
317 @subsection wxCursorProperty
319 Represents a wxCursor. wxChoice is used to edit the value.
320 Drop-down list has cursor images under some (wxMSW) platforms.
323 @section pgproperty_creating Creating Custom Properties
325 New properties can be created by subclassing wxPGProperty or one
326 of the provided property classes, and (re)implementing necessary
327 member functions. Below, each virtual member function has ample
328 documentation about its purpose and any odd details which to keep
331 Here is a very simple 'template' code:
334 class MyProperty : public wxPGProperty
337 // All arguments of ctor must have a default value -
338 // use wxPG_LABEL for label and name
339 MyProperty( const wxString& label = wxPG_LABEL,
340 const wxString& name = wxPG_LABEL,
341 const wxString& value = wxEmptyString )
343 // m_value is wxVariant
347 virtual ~MyProperty() { }
349 const wxPGEditor* DoGetEditorClass() const
351 // Determines editor used by property.
352 // You can replace 'TextCtrl' below with any of these
353 // builtin-in property editor identifiers: Choice, ComboBox,
354 // TextCtrlAndButton, ChoiceAndButton, CheckBox, SpinCtrl,
356 return wxPGEditor_TextCtrl;
359 virtual wxString GetValueAsString( int argFlags ) const
361 // TODO: Return property value in string format
364 virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags )
366 // TODO: Adapt string to property value.
373 Since wxPGProperty derives from wxObject, you can use standard
374 DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS macros. From the
375 above example they were omitted for sake of simplicity, and besides,
376 they are only really needed if you need to use wxRTTI with your
379 You can change the 'value type' of a property by simply assigning different
380 type of variant with SetValue. <b>It is mandatory to implement
381 wxVariantData class for all data types used as property values.</b>
382 You can use macros declared in wxPropertyGrid headers. For instance:
386 // (If you need to have export declaration, use version of macros
387 // with _EXPORTED postfix)
388 WX_PG_DECLARE_VARIANT_DATA(MyDataClass)
391 WX_PG_IMPLEMENT_VARIANT_DATA(MyDataClass)
393 // Or, if you don't have valid == operator:
394 WX_PG_IMPLEMENT_VARIANT_DATA_DUMMY_EQ(MyDataClass)
400 class wxPGProperty
: public wxObject
403 typedef wxUint32 FlagType
;
405 /** Basic constructor.
410 Non-abstract property classes should have constructor of this style:
414 // If T is a class, then it should be a constant reference
415 // (e.g. const T& ) instead.
416 MyProperty( const wxString& label, const wxString& name, T value )
419 // Generally recommended way to set the initial value
420 // (as it should work in pretty much 100% of cases).
425 // If has private child properties then create them here. For example:
426 // AddChild( new wxStringProperty( "Subprop 1", wxPG_LABEL, value.GetSubProp1() ) );
431 wxPGProperty( const wxString
& label
, const wxString
& name
);
433 /** Virtual destructor. It is customary for derived properties to implement this. */
434 virtual ~wxPGProperty();
436 /** This virtual function is called after m_value has been set.
439 - If m_value was set to Null variant (ie. unspecified value), OnSetValue()
441 - m_value may be of any variant type. Typically properties internally support only
442 one variant type, and as such OnSetValue() provides a good opportunity to convert
443 supported values into internal type.
444 - Default implementation does nothing.
446 virtual void OnSetValue();
448 /** Override this to return something else than m_value as the value.
450 virtual wxVariant
DoGetValue() const { return m_value
; }
452 /** Implement this function in derived class to check the value.
453 Return true if it is ok. Returning false prevents property change events
457 - Default implementation always returns true.
459 virtual bool ValidateValue( wxVariant
& value
, wxPGValidationInfo
& validationInfo
) const;
461 /** Converts 'text' into proper value 'variant'. Returns true if new (different than
462 m_value) value could be interpreted from the text.
464 If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable
465 one (they may be different).
466 If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of composite
467 property string value (as generated by GetValueAsString() called with this same
471 Default implementation converts semicolon delimited tokens into child values. Only
472 works for properties with children.
474 virtual bool StringToValue( wxVariant
& variant
, const wxString
& text
, int argFlags
= 0 ) const;
476 /** Converts 'number' (including choice selection) into proper value 'variant'.
477 Returns true if new (different than m_value) value could be interpreted from the integer.
479 If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable one.
482 - If property is not supposed to use choice or spinctrl or other editor
483 with int-based value, it is not necessary to implement this method.
484 - Default implementation simply assign given int to m_value.
485 - If property uses choice control, and displays a dialog on some choice items,
486 then it is preferred to display that dialog in IntToValue instead of OnEvent.
488 virtual bool IntToValue( wxVariant
& value
, int number
, int argFlags
= 0 ) const;
492 /** Returns text representation of property's value.
495 If wxPG_FULL_VALUE is set, returns complete, storable string value instead of displayable.
496 If wxPG_EDITABLE_VALUE is set, returns string value that must be editable in textctrl.
497 If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to display
498 as a part of composite property string value.
501 Default implementation returns string composed from text representations of
504 virtual wxString
GetValueAsString( int argFlags
= 0 ) const;
506 /** Converts string to a value, and if successful, calls SetValue() on it.
507 Default behavior is to do nothing.
509 String to get the value from.
511 true if value was changed.
513 bool SetValueFromString( const wxString
& text
, int flags
= 0 );
515 /** Converts integer to a value, and if succesful, calls SetValue() on it.
516 Default behavior is to do nothing.
518 Int to get the value from.
520 If has wxPG_FULL_VALUE, then the value given is a actual value and not an index.
522 True if value was changed.
524 bool SetValueFromInt( long value
, int flags
= 0 );
526 /** Returns size of the custom painted image in front of property. This method
527 must be overridden to return non-default value if OnCustomPaint is to be
530 Normally -1, but can be an index to the property's list of items.
532 - Default behavior is to return wxSize(0,0), which means no image.
533 - Default image width or height is indicated with dimension -1.
534 - You can also return wxPG_DEFAULT_IMAGE_SIZE which equals wxSize(-1, -1).
536 virtual wxSize
OnMeasureImage( int item
= -1 ) const;
538 /** Events received by editor widgets are processed here. Note that editor class
539 usually processes most events. Some, such as button press events of
540 TextCtrlAndButton class, can be handled here. Also, if custom handling
541 for regular events is desired, then that can also be done (for example,
542 wxSystemColourProperty custom handles wxEVT_COMMAND_CHOICE_SELECTED
543 to display colour picker dialog when 'custom' selection is made).
545 If the event causes value to be changed, SetValueInEvent()
546 should be called to set the new value.
551 Should return true if any changes in value should be reported.
553 - If property uses choice control, and displays a dialog on some choice items,
554 then it is preferred to display that dialog in IntToValue instead of OnEvent.
556 virtual bool OnEvent( wxPropertyGrid
* propgrid
, wxWindow
* wnd_primary
, wxEvent
& event
);
558 /** Called after value of a child property has been altered. Note that this function is
559 usually called at the time that value of this property, or given child property, is
560 still pending for change.
562 Sample pseudo-code implementation:
565 void MyProperty::ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const
567 // Acquire reference to actual type of data stored in variant
568 // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros were used to create
569 // the variant class).
570 T& data = TFromVariant(thisValue);
572 // Copy childValue into data.
573 switch ( childIndex )
576 data.SetSubProp1( childvalue.GetLong() );
579 data.SetSubProp2( childvalue.GetString() );
587 Value of this property, that should be altered.
589 Index of child changed (you can use Item(childIndex) to get).
591 Value of the child property.
593 virtual void ChildChanged( wxVariant
& thisValue
, int childIndex
, wxVariant
& childValue
) const;
595 /** Returns pointer to an instance of used editor.
597 virtual const wxPGEditor
* DoGetEditorClass() const;
599 /** Returns pointer to the wxValidator that should be used
600 with the editor of this property (NULL for no validator).
601 Setting validator explicitly via SetPropertyValidator
604 In most situations, code like this should work well
605 (macros are used to maintain one actual validator instance,
606 so on the second call the function exits within the first
611 wxValidator* wxMyPropertyClass::DoGetValidator () const
613 WX_PG_DOGETVALIDATOR_ENTRY()
615 wxMyValidator* validator = new wxMyValidator(...);
617 ... prepare validator...
619 WX_PG_DOGETVALIDATOR_EXIT(validator)
625 You can get common filename validator by returning
626 wxFileProperty::GetClassValidator(). wxDirProperty,
627 for example, uses it.
629 virtual wxValidator
* DoGetValidator () const;
631 /** Override to paint an image in front of the property value text or drop-down
632 list item (but only if wxPGProperty::OnMeasureImage is overridden as well).
634 If property's OnMeasureImage() returns size that has height != 0 but less than
635 row height ( < 0 has special meanings), wxPropertyGrid calls this method to
636 draw a custom image in a limited area in front of the editor control or
637 value text/graphics, and if control has drop-down list, then the image is
638 drawn there as well (even in the case OnMeasureImage() returned higher height
641 NOTE: Following applies when OnMeasureImage() returns a "flexible" height (
642 using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable height items:
643 If rect.x is < 0, then this is a measure item call, which means that
644 dc is invalid and only thing that should be done is to set paintdata.m_drawnHeight
645 to the height of the image of item at index paintdata.m_choiceItem. This call
646 may be done even as often as once every drop-down popup show.
651 Box reserved for custom graphics. Includes surrounding rectangle, if any.
652 If x is < 0, then this is a measure item call (see above).
654 wxPGPaintData structure with much useful data about painted item.
659 const wxPropertyGrid* m_parent;
661 // Normally -1, otherwise index to drop-down list item that has to be drawn.
664 // Set to drawn width in OnCustomPaint (optional).
667 // In a measure item call, set this to the height of item at m_choiceItem index
673 - You can actually exceed rect width, but if you do so then paintdata.m_drawnWidth
674 must be set to the full width drawn in pixels.
675 - Due to technical reasons, rect's height will be default even if custom height
676 was reported during measure call.
677 - Brush is guaranteed to be default background colour. It has been already used to
678 clear the background of area being painted. It can be modified.
679 - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper colour) pen for
680 drawing framing rectangle. It can be changed as well.
682 @see GetValueAsString()
684 virtual void OnCustomPaint( wxDC
& dc
, const wxRect
& rect
, wxPGPaintData
& paintdata
);
686 /** Returns used wxPGCellRenderer instance for given property column (label=0, value=1).
688 Default implementation returns editor's renderer for all columns.
690 virtual wxPGCellRenderer
* GetCellRenderer( int column
) const;
692 /** Returns which choice is currently selected. Only applies to properties
695 Needs to reimplemented in derived class if property value does not
696 map directly to a choice. Integer as index, bool, and string usually do.
698 virtual int GetChoiceSelection() const;
700 /** Refresh values of child properties. Automatically called after value is set.
702 virtual void RefreshChildren();
704 /** Special handling for attributes of this property.
706 If returns false, then the attribute will be automatically stored in
709 Default implementation simply returns false.
711 virtual bool DoSetAttribute( const wxString
& name
, wxVariant
& value
);
713 /** Returns value of an attribute.
715 Override if custom handling of attributes is needed.
717 Default implementation simply return NULL variant.
719 virtual wxVariant
DoGetAttribute( const wxString
& name
) const;
721 /** Returns instance of a new wxPGEditorDialogAdapter instance, which is
722 used when user presses the (optional) button next to the editor control;
724 Default implementation returns NULL (ie. no action is generated when
727 virtual wxPGEditorDialogAdapter
* GetEditorDialog() const;
729 /** Returns wxPGCell of given column, NULL if none. If valid
730 object is returned, caller will gain its ownership.
732 wxPGCell
* AcquireCell( unsigned int column
)
734 if ( column
>= m_cells
.size() )
737 wxPGCell
* cell
= (wxPGCell
*) m_cells
[column
];
738 m_cells
[column
] = NULL
;
742 /** Append a new choice to property's list of choices.
745 Label for added choice.
748 Value for new choice. Do not specify if you wish this
749 to equal choice index.
752 Index to added choice.
754 int AddChoice( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
756 /** Returns true if children of this property are component values (for instance,
757 points size, face name, and is_underlined are component values of a font).
759 bool AreChildrenComponents() const
761 if ( m_flags
& (wxPG_PROP_COMPOSED_VALUE
|wxPG_PROP_AGGREGATE
) )
767 /** Removes entry from property's wxPGChoices and editor control (if it is active).
769 If selected item is deleted, then the value is set to unspecified.
771 void DeleteChoice( int index
);
773 /** Call to enable or disable usage of common value (integer value that can be selected for
774 properties instead of their normal values) for this property.
776 Common values are disabled by the default for all properties.
778 void EnableCommonValue( bool enable
= true )
780 if ( enable
) SetFlag( wxPG_PROP_USES_COMMON_VALUE
);
781 else ClearFlag( wxPG_PROP_USES_COMMON_VALUE
);
784 /** Composes text from values of child properties. */
785 void GenerateComposedValue( wxString
& text
, int argFlags
= 0 ) const;
787 /** Returns property's label. */
788 const wxString
& GetLabel() const { return m_label
; }
790 /** Returns property's name with all (non-category, non-root) parents. */
791 wxString
GetName() const;
793 /** Returns property's base name (ie. parent's name is not added in any case) */
794 const wxString
& GetBaseName() const { return m_name
; }
796 /** Returns read-only reference to property's list of choices.
798 const wxPGChoices
& GetChoices() const;
800 /** Returns coordinate to the top y of the property. Note that the
801 position of scrollbars is not taken into account.
805 wxVariant
GetValue() const
810 /** Returns reference to the internal stored value. GetValue is preferred
811 way to get the actual value, since GetValueRef ignores DoGetValue,
812 which may override stored value.
814 wxVariant
& GetValueRef()
819 const wxVariant
& GetValueRef() const
824 /** Same as GetValueAsString, except takes common value into account.
826 wxString
GetValueString( int argFlags
= 0 ) const;
828 void UpdateControl( wxWindow
* primary
);
830 /** Returns wxPGCell of given column, NULL if none. wxPGProperty
831 will retain ownership of the cell object.
833 wxPGCell
* GetCell( unsigned int column
) const
835 if ( column
>= m_cells
.size() )
838 return (wxPGCell
*) m_cells
[column
];
841 /** Return number of displayed common values for this property.
843 int GetDisplayedCommonValueCount() const;
845 wxString
GetDisplayedString() const
847 return GetValueString(0);
850 /** Returns property grid where property lies. */
851 wxPropertyGrid
* GetGrid() const;
853 /** Returns owner wxPropertyGrid, but only if one is currently on a page
854 displaying this property. */
855 wxPropertyGrid
* GetGridIfDisplayed() const;
857 /** Returns highest level non-category, non-root parent. Useful when you
858 have nested wxCustomProperties/wxParentProperties.
860 Thus, if immediate parent is root or category, this will return the
863 wxPGProperty
* GetMainParent() const;
865 /** Return parent of property */
866 wxPGProperty
* GetParent() const { return m_parent
; }
868 /** Returns true if property has editable wxTextCtrl when selected.
871 Altough disabled properties do not displayed editor, they still
872 return True here as being disabled is considered a temporary
873 condition (unlike being read-only or having limited editing enabled).
875 bool IsTextEditable() const;
877 bool IsValueUnspecified() const
879 return m_value
.IsNull();
882 FlagType
HasFlag( FlagType flag
) const
884 return ( m_flags
& flag
);
887 /** Returns comma-delimited string of property attributes.
889 const wxPGAttributeStorage
& GetAttributes() const
894 /** Returns m_attributes as list wxVariant.
896 wxVariant
GetAttributesAsList() const;
898 FlagType
GetFlags() const
903 const wxPGEditor
* GetEditorClass() const;
905 wxString
GetValueType() const
907 return m_value
.GetType();
910 /** Returns editor used for given column. NULL for no editor.
912 const wxPGEditor
* GetColumnEditor( int column
) const
915 return GetEditorClass();
920 /** Returns common value selected for this property. -1 for none.
922 int GetCommonValue() const
924 return m_commonValue
;
927 /** Returns true if property has even one visible child.
929 bool HasVisibleChildren() const;
931 /** Inserts a new choice to property's list of choices.
937 Insertion position. Use wxNOT_FOUND to append.
940 Value for new choice. Do not specify if you wish this
941 to equal choice index.
943 int InsertChoice( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
945 /** Returns true if this property is actually a wxPropertyCategory.
947 bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY
)?
true:false; }
949 /** Returns true if this property is actually a wxRootProperty.
951 bool IsRoot() const { return (m_parent
== NULL
); }
953 /** Returns true if this is a sub-property. */
954 bool IsSubProperty() const
956 wxPGProperty
* parent
= (wxPGProperty
*)m_parent
;
957 if ( parent
&& !parent
->IsCategory() )
962 /** Returns last visible sub-property, recursively.
964 const wxPGProperty
* GetLastVisibleSubItem() const;
966 wxVariant
GetDefaultValue() const;
968 int GetMaxLength() const
970 return (int) m_maxLen
;
973 /** Determines, recursively, if all children are not unspecified. Takes values in given list into account.
975 bool AreAllChildrenSpecified( wxVariant
* pendingList
= NULL
) const;
977 /** Updates composed values of parent non-category properties, recursively.
978 Returns topmost property updated.
981 - Must not call SetValue() (as can be called in it).
983 wxPGProperty
* UpdateParentValues();
985 /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
987 FlagType
UsesAutoUnspecified() const
989 return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED
);
992 wxBitmap
* GetValueImage() const
994 return m_valueBitmap
;
997 wxVariant
GetAttribute( const wxString
& name
) const;
999 /** Returns named attribute, as string, if found. Otherwise defVal is returned.
1001 wxString
GetAttribute( const wxString
& name
, const wxString
& defVal
) const;
1003 /** Returns named attribute, as long, if found. Otherwise defVal is returned.
1005 long GetAttributeAsLong( const wxString
& name
, long defVal
) const;
1007 /** Returns named attribute, as double, if found. Otherwise defVal is returned.
1009 double GetAttributeAsDouble( const wxString
& name
, double defVal
) const;
1011 inline unsigned int GetArrIndex() const { return m_arrIndex
; }
1013 inline unsigned int GetDepth() const { return (unsigned int)m_depth
; }
1015 /** Gets flags as a'|' delimited string. Note that flag names are not
1016 prepended with 'wxPG_PROP_'.
1018 String will only be made to include flags combined by this parameter.
1020 wxString
GetFlagsAsString( FlagType flagsMask
) const;
1022 /** Returns position in parent's array. */
1023 unsigned int GetIndexInParent() const
1025 return (unsigned int)m_arrIndex
;
1028 /** Hides or reveals the property.
1030 true for hide, false for reveal.
1032 By default changes are applied recursively. Set this paramter wxPG_DONT_RECURSE to prevent this.
1034 inline bool Hide( bool hide
, int flags
= wxPG_RECURSE
);
1036 bool IsExpanded() const { return (!(m_flags
& wxPG_PROP_COLLAPSED
) && GetChildCount()); }
1038 /** Returns true if all parents expanded.
1040 bool IsVisible() const;
1042 bool IsEnabled() const
1044 return ( m_flags
& wxPG_PROP_DISABLED
) ?
false : true;
1047 /** If property's editor is created this forces its recreation. Useful
1048 in SetAttribute etc. Returns true if actually did anything.
1050 bool RecreateEditor();
1052 /** If property's editor is active, then update it's value.
1054 void RefreshEditor();
1056 /** Sets an attribute for this property.
1058 Text identifier of attribute. See @ref propgrid_property_attributes.
1062 void SetAttribute( const wxString
& name
, wxVariant value
);
1064 void SetAttributes( const wxPGAttributeStorage
& attributes
);
1066 /** Sets editor for a property.
1069 For builtin editors, use wxPGEditor_X, where X is builtin editor's
1070 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list).
1072 For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
1074 void SetEditor( const wxPGEditor
* editor
)
1076 m_customEditor
= editor
;
1079 /** Sets editor for a property.
1081 inline void SetEditor( const wxString
& editorName
);
1083 /** Sets cell information for given column.
1085 Note that the property takes ownership of given wxPGCell instance.
1087 void SetCell( int column
, wxPGCell
* cellObj
);
1089 /** If property has choices and they are not yet exclusive, new such copy
1090 of them will be created.
1092 void SetChoicesExclusive();
1094 /** Sets selected choice and changes property value.
1096 Tries to retain value type, although currently if it is not string,
1097 then it is forced to integer.
1099 void SetChoiceSelection( int newValue
);
1101 /** Sets common value selected for this property. -1 for none.
1103 void SetCommonValue( int commonValue
)
1105 m_commonValue
= commonValue
;
1108 /** Sets flags from a '|' delimited string. Note that flag names are not
1109 prepended with 'wxPG_PROP_'.
1111 void SetFlagsFromString( const wxString
& str
);
1113 /** Sets property's "is it modified?" flag. Affects children recursively.
1115 void SetModifiedStatus( bool modified
)
1117 SetFlagRecursively(wxPG_PROP_MODIFIED
, modified
);
1120 /** Call in OnEvent(), OnButtonClick() etc. to change the property value
1121 based on user input.
1124 This method is const since it doesn't actually modify value, but posts
1125 given variant as pending value, stored in wxPropertyGrid.
1127 void SetValueInEvent( wxVariant value
) const;
1129 /** Call this to set value of the property. Unlike methods in wxPropertyGrid,
1130 this does not automatically update the display.
1133 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through
1134 validation process and send property change event.
1136 If you need to change property value in event, based on user input, use
1137 SetValueInEvent() instead.
1140 Pointer to list variant that contains child values. Used to indicate
1141 which children should be marked as modified.
1143 Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR).
1145 void SetValue( wxVariant value
, wxVariant
* pList
= NULL
, int flags
= 0 );
1147 /** Set wxBitmap in front of the value. This bitmap may be ignored
1148 by custom cell renderers.
1150 void SetValueImage( wxBitmap
& bmp
);
1152 void SetExpanded( bool expanded
)
1154 if ( !expanded
) m_flags
|= wxPG_PROP_COLLAPSED
;
1155 else m_flags
&= ~wxPG_PROP_COLLAPSED
;
1158 void SetFlag( FlagType flag
) { m_flags
|= flag
; }
1160 void SetFlagRecursively( FlagType flag
, bool set
);
1162 void SetHelpString( const wxString
& helpString
)
1164 m_helpString
= helpString
;
1167 /** Sets property's label.
1170 - Properties under same parent may have same labels. However,
1171 property names must still remain unique.
1173 void SetLabel( const wxString
& label
) { m_label
= label
; }
1175 inline void SetName( const wxString
& newName
);
1177 void SetValueToUnspecified()
1179 wxVariant val
; // Create NULL variant
1183 /** Sets wxValidator for a property*/
1184 void SetValidator( const wxValidator
& validator
)
1186 m_validator
= wxDynamicCast(validator
.Clone(),wxValidator
);
1189 /** Gets assignable version of property's validator. */
1190 wxValidator
* GetValidator() const
1194 return DoGetValidator();
1197 /** Updates property value in case there were last minute
1198 changes. If value was unspecified, it will be set to default.
1199 Use only for properties that have TextCtrl-based editor.
1201 If you have code similar to
1203 // Update the value in case of last minute changes
1204 if ( primary && propgrid->IsEditorsValueModified() )
1205 GetEditorClass()->CopyValueFromControl( this, primary );
1207 in wxPGProperty::OnEvent wxEVT_COMMAND_BUTTON_CLICKED handler,
1208 then replace it with call to this method.
1210 True if value changed.
1212 bool PrepareValueForDialogEditing( wxPropertyGrid
* propgrid
);
1214 /** Returns client data (void*) of a property.
1216 void* GetClientData() const
1218 return m_clientData
;
1221 /** Sets client data (void*) of a property.
1223 This untyped client data has to be deleted manually.
1225 void SetClientData( void* clientData
)
1227 m_clientData
= clientData
;
1230 /** Returns client object of a property.
1232 void SetClientObject(wxClientData
* clientObject
)
1234 delete m_clientObject
;
1235 m_clientObject
= clientObject
;
1238 /** Sets managed client object of a property.
1240 wxClientData
*GetClientObject() const { return m_clientObject
; }
1242 /** Sets new set of choices for property.
1245 This operation clears the property value.
1247 bool SetChoices( wxPGChoices
& choices
);
1249 /** Sets new set of choices for property.
1251 inline bool SetChoices( const wxArrayString
& labels
,
1252 const wxArrayInt
& values
= wxArrayInt() );
1254 /** Set max length of text in text editor.
1256 inline bool SetMaxLength( int maxLen
);
1258 /** Call with 'false' in OnSetValue to cancel value changes after all
1259 (ie. cancel 'true' returned by StringToValue() or IntToValue()).
1261 void SetWasModified( bool set
= true )
1263 if ( set
) m_flags
|= wxPG_PROP_WAS_MODIFIED
;
1264 else m_flags
&= ~wxPG_PROP_WAS_MODIFIED
;
1267 const wxString
& GetHelpString() const
1269 return m_helpString
;
1272 void ClearFlag( FlagType flag
) { m_flags
&= ~(flag
); }
1274 // Use, for example, to detect if item is inside collapsed section.
1275 bool IsSomeParent( wxPGProperty
* candidate_parent
) const;
1277 /** Adapts list variant into proper value using consequtive ChildChanged-calls.
1279 void AdaptListToValue( wxVariant
& list
, wxVariant
* value
) const;
1281 /** This is used by properties that have fixed sub-properties. */
1282 void AddChild( wxPGProperty
* prop
);
1284 /** Returns height of children, recursively, and
1285 by taking expanded/collapsed status into account.
1287 iMax is used when finding property y-positions.
1289 int GetChildrenHeight( int lh
, int iMax
= -1 ) const;
1291 /** Returns number of child properties */
1292 unsigned int GetChildCount() const { return m_children
.GetCount(); }
1294 /** Returns sub-property at index i. */
1295 wxPGProperty
* Item( size_t i
) const { return (wxPGProperty
*)m_children
.Item(i
); }
1297 /** Returns last sub-property.
1299 wxPGProperty
* Last() const { return (wxPGProperty
*)m_children
.Last(); }
1301 /** Returns index of given sub-property. */
1302 int Index( const wxPGProperty
* p
) const { return m_children
.Index((wxPGProperty
*)p
); }
1304 /** Deletes all sub-properties. */
1307 // Puts correct indexes to children
1308 void FixIndexesOfChildren( size_t starthere
= 0 );
1310 wxPGProperty
* GetItemAtY( unsigned int y
, unsigned int lh
, unsigned int* nextItemY
) const;
1312 /** Returns (direct) child property with given name (or NULL if not found).
1314 wxPGProperty
* GetPropertyByName( const wxString
& name
) const;
1318 /** @class wxPGChoices
1320 Helper class for managing choices of wxPropertyGrid properties.
1321 Each entry can have label, value, bitmap, text colour, and background colour.
1323 @library{wxpropgrid}
1326 class WXDLLIMPEXP_PROPGRID wxPGChoices
1329 typedef long ValArrItem
;
1331 /** Default constructor. */
1337 /** Copy constructor. */
1338 wxPGChoices( const wxPGChoices
& a
)
1340 if ( a
.m_data
!= wxPGChoicesEmptyData
)
1343 m_data
->m_refCount
++;
1348 wxPGChoices( const wxChar
** labels
, const long* values
= NULL
)
1355 wxPGChoices( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() )
1361 /** Simple interface constructor. */
1362 wxPGChoices( wxPGChoicesData
* data
)
1375 /** Adds to current. If did not have own copies, creates them now. If was empty,
1376 identical to set except that creates copies.
1378 void Add( const wxChar
** labels
, const ValArrItem
* values
= NULL
);
1380 /** Version that works with wxArrayString. */
1381 void Add( const wxArrayString
& arr
, const ValArrItem
* values
= NULL
);
1383 /** Version that works with wxArrayString and wxArrayInt. */
1384 void Add( const wxArrayString
& arr
, const wxArrayInt
& arrint
);
1386 /** Adds single item. */
1387 wxPGChoiceEntry
& Add( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1389 /** Adds a single item, with bitmap. */
1390 wxPGChoiceEntry
& Add( const wxString
& label
, const wxBitmap
& bitmap
, int value
= wxPG_INVALID_VALUE
);
1392 /** Adds a single item with full entry information. */
1393 wxPGChoiceEntry
& Add( const wxPGChoiceEntry
& entry
)
1395 return Insert(entry
, -1);
1398 /** Adds single item. */
1399 wxPGChoiceEntry
& AddAsSorted( const wxString
& label
, int value
= wxPG_INVALID_VALUE
);
1401 void Assign( const wxPGChoices
& a
)
1403 AssignData(a
.m_data
);
1406 void AssignData( wxPGChoicesData
* data
);
1408 /** Delete all choices. */
1411 if ( m_data
!= wxPGChoicesEmptyData
)
1417 if ( m_data
== wxPGChoicesEmptyData
)
1418 m_data
= new wxPGChoicesData();
1421 /** Gets a unsigned number identifying this list. */
1422 wxPGChoicesId
GetId() const { return (wxPGChoicesId
) m_data
; };
1424 const wxString
& GetLabel( size_t ind
) const
1426 wxASSERT( ind
>= 0 && ind
< GetCount() );
1427 return Item(ind
).GetText();
1430 size_t GetCount () const
1432 wxASSERT_MSG( m_data
,
1433 wxT("When checking if wxPGChoices is valid, use IsOk() instead of GetCount()") );
1434 return m_data
->GetCount();
1437 int GetValue( size_t ind
) const { return Item(ind
).GetValue(); }
1439 /** Returns array of values matching the given strings. Unmatching strings
1440 result in wxPG_INVALID_VALUE entry in array.
1442 wxArrayInt
GetValuesForStrings( const wxArrayString
& strings
) const;
1444 /** Returns array of indices matching given strings. Unmatching strings
1445 are added to 'unmatched', if not NULL.
1447 wxArrayInt
GetIndicesForStrings( const wxArrayString
& strings
, wxArrayString
* unmatched
= NULL
) const;
1449 /** Returns true if choices in general are likely to have values
1450 (depens on that all entries have values or none has)
1452 bool HasValues() const;
1454 bool HasValue( unsigned int i
) const { return (m_data
->GetCount() > i
&& m_data
->Item(i
)->HasValue()); }
1456 int Index( const wxString
& str
) const;
1457 int Index( int val
) const;
1459 /** Inserts single item. */
1460 wxPGChoiceEntry
& Insert( const wxString
& label
, int index
, int value
= wxPG_INVALID_VALUE
);
1462 /** Inserts a single item with full entry information. */
1463 wxPGChoiceEntry
& Insert( const wxPGChoiceEntry
& entry
, int index
);
1465 /** Returns false if this is a constant empty set of choices,
1466 which should not be modified.
1470 return ( m_data
!= wxPGChoicesEmptyData
);
1473 const wxPGChoiceEntry
& Item( unsigned int i
) const
1476 return *m_data
->Item(i
);
1479 wxPGChoiceEntry
& Item( unsigned int i
)
1482 return *m_data
->Item(i
);
1485 /** Removes count items starting at position nIndex. */
1486 void RemoveAt(size_t nIndex
, size_t count
= 1);
1488 /** Does not create copies for itself. */
1489 void Set( const wxChar
** labels
, const long* values
= NULL
)
1495 /** Version that works with wxArrayString.
1496 TODO: Deprecate this.
1498 void Set( wxArrayString
& arr
, const long* values
= (const long*) NULL
)
1504 /** Version that works with wxArrayString and wxArrayInt. */
1505 void Set( const wxArrayString
& labels
, const wxArrayInt
& values
= wxArrayInt() )
1514 // Creates exclusive copy of current choices
1517 if ( m_data
->m_refCount
!= 1 )
1519 wxPGChoicesData
* data
= new wxPGChoicesData();
1520 data
->CopyDataFrom(m_data
);
1526 // Returns data, increases refcount.
1527 wxPGChoicesData
* GetData()
1529 wxASSERT( m_data
->m_refCount
!= 0xFFFFFFF );
1530 m_data
->m_refCount
++;
1534 // Returns plain data ptr - no refcounting stuff is done.
1535 wxPGChoicesData
* GetDataPtr() const { return m_data
; }
1537 // Changes ownership of data to you.
1538 wxPGChoicesData
* ExtractData()
1540 wxPGChoicesData
* data
= m_data
;
1541 m_data
= wxPGChoicesEmptyData
;
1545 wxArrayString
GetLabels() const;
1547 void operator= (const wxPGChoices
& a
)
1549 AssignData(a
.m_data
);
1552 wxPGChoiceEntry
& operator[](unsigned int i
)
1557 const wxPGChoiceEntry
& operator[](unsigned int i
) const
1563 // -----------------------------------------------------------------------