]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/propgrid/property.h
Added further API for intercepting deletion and content insertion
[wxWidgets.git] / interface / wx / propgrid / property.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: property.h
3 // Purpose: interface of wxPGProperty
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
8
9
10 #define wxNullProperty ((wxPGProperty*)NULL)
11
12
13 /**
14 @section propgrid_property_attributes wxPropertyGrid Property Attribute Identifiers
15
16 wxPGProperty::SetAttribute() and wxPropertyGridInterface::SetPropertyAttribute()
17 accept one of these as attribute name argument.
18
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.
22
23 @{
24 */
25
26 /** Set default value for property.
27 */
28 #define wxPG_ATTR_DEFAULT_VALUE wxS("DefaultValue")
29
30 /** Universal, int or double. Minimum value for numeric properties.
31 */
32 #define wxPG_ATTR_MIN wxS("Min")
33
34 /** Universal, int or double. Maximum value for numeric properties.
35 */
36 #define wxPG_ATTR_MAX wxS("Max")
37
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).
41 */
42 #define wxPG_ATTR_UNITS wxS("Units")
43
44 /** When set, will be shown as 'greyed' text in property's value cell when
45 the actual displayed value is blank.
46 */
47 #define wxPG_ATTR_HINT wxS("Hint")
48
49 /**
50 @deprecated Use "Hint" (wxPG_ATTR_HINT) instead.
51 */
52 #define wxPG_ATTR_INLINE_HELP wxS("InlineHelp")
53
54 /** Universal, wxArrayString. Set to enable auto-completion in any
55 wxTextCtrl-based property editor.
56 */
57 #define wxPG_ATTR_AUTOCOMPLETE wxS("AutoComplete")
58
59 /** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
60 Default value is False.
61
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
65 bool properties.
66 */
67 #define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox")
68
69 /** wxBoolProperty and wxFlagsProperty specific. Value type is bool.
70 Default value is False.
71
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
75 bool properties.
76 */
77 #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING wxS("UseDClickCycling")
78
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
81 precision.
82 */
83 #define wxPG_FLOAT_PRECISION wxS("Precision")
84
85 /** The text will be echoed as asterisks (wxTE_PASSWORD will be passed to textctrl etc).
86 */
87 #define wxPG_STRING_PASSWORD wxS("Password")
88
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).
92 */
93 #define wxPG_UINT_BASE wxS("Base")
94
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
98 numbers.
99 */
100 #define wxPG_UINT_PREFIX wxS("Prefix")
101
102 /** wxFileProperty/wxImageFileProperty specific, wxChar*, default is detected/varies.
103 Sets the wildcard used in the triggered wxFileDialog. Format is the
104 same.
105 */
106 #define wxPG_FILE_WILDCARD wxS("Wildcard")
107
108 /** wxFileProperty/wxImageFileProperty specific, int, default 1.
109 When 0, only the file name is shown (i.e. drive and directory are hidden).
110 */
111 #define wxPG_FILE_SHOW_FULL_PATH wxS("ShowFullPath")
112
113 /** Specific to wxFileProperty and derived properties, wxString, default empty.
114 If set, then the filename is shown relative to the given path string.
115 */
116 #define wxPG_FILE_SHOW_RELATIVE_PATH wxS("ShowRelativePath")
117
118 /** Specific to wxFileProperty and derived properties, wxString, default is empty.
119 Sets the initial path of where to look for files.
120 */
121 #define wxPG_FILE_INITIAL_PATH wxS("InitialPath")
122
123 /** Specific to wxFileProperty and derivatives, wxString, default is empty.
124 Sets a specific title for the dir dialog.
125 */
126 #define wxPG_FILE_DIALOG_TITLE wxS("DialogTitle")
127
128 /** Specific to wxFileProperty and derivatives, long, default is 0.
129 Sets a specific wxFileDialog style for the file dialog, e.g. ::wxFD_SAVE.
130
131 @since 2.9.4
132 */
133 #define wxPG_FILE_DIALOG_STYLE wxS("DialogStyle")
134
135 /** Specific to wxDirProperty, wxString, default is empty.
136 Sets a specific message for the dir dialog.
137 */
138 #define wxPG_DIR_DIALOG_MESSAGE wxS("DialogMessage")
139
140 /**
141 wxArrayStringProperty's string delimiter character. If this is a quotation
142 mark or hyphen, then strings will be quoted instead (with given
143 character).
144
145 Default delimiter is quotation mark.
146 */
147 #define wxPG_ARRAY_DELIMITER wxS("Delimiter")
148
149 /** Sets displayed date format for wxDateProperty.
150 */
151 #define wxPG_DATE_FORMAT wxS("DateFormat")
152
153 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
154 is wxDP_DEFAULT | wxDP_SHOWCENTURY. Using wxDP_ALLOWNONE will enable
155 better unspecified value support in the editor.
156 */
157 #define wxPG_DATE_PICKER_STYLE wxS("PickerStyle")
158
159 /** SpinCtrl editor, int or double. How much number changes when button is
160 pressed (or up/down on keyboard).
161 */
162 #define wxPG_ATTR_SPINCTRL_STEP wxS("Step")
163
164 /** SpinCtrl editor, bool. If @true, value wraps at Min/Max.
165 */
166 #define wxPG_ATTR_SPINCTRL_WRAP wxS("Wrap")
167
168 /** SpinCtrl editor, bool. If @true, value can also by changed by moving
169 mouse when left mouse button is being pressed.
170 */
171 #define wxPG_ATTR_SPINCTRL_MOTIONSPIN wxS("MotionSpin")
172
173 /** wxMultiChoiceProperty, int. If 0, no user strings allowed. If 1, user strings
174 appear before list strings. If 2, user strings appear after list string.
175 */
176 #define wxPG_ATTR_MULTICHOICE_USERSTRINGMODE wxS("UserStringMode")
177
178 /** wxColourProperty and its kind, int, default 1. Setting this attribute to 0 hides custom
179 colour from property's list of choices.
180 */
181 #define wxPG_COLOUR_ALLOW_CUSTOM wxS("AllowCustom")
182
183 /**
184 wxColourProperty and its kind: Set to True in order to support editing
185 alpha colour component.
186 */
187 #define wxPG_COLOUR_HAS_ALPHA wxS("HasAlpha")
188
189 /** @}
190 */
191
192
193 /** @section propgrid_propflags wxPGProperty Flags
194 @{
195 */
196
197 enum wxPGPropertyFlags
198 {
199
200 /** Indicates bold font.
201 */
202 wxPG_PROP_MODIFIED = 0x0001,
203
204 /** Disables ('greyed' text and editor does not activate) property.
205 */
206 wxPG_PROP_DISABLED = 0x0002,
207
208 /** Hider button will hide this property.
209 */
210 wxPG_PROP_HIDDEN = 0x0004,
211
212 /** This property has custom paint image just in front of its value.
213 If property only draws custom images into a popup list, then this
214 flag should not be set.
215 */
216 wxPG_PROP_CUSTOMIMAGE = 0x0008,
217
218 /** Do not create text based editor for this property (but button-triggered
219 dialog and choice are ok).
220 */
221 wxPG_PROP_NOEDITOR = 0x0010,
222
223 /** Property is collapsed, ie. it's children are hidden.
224 */
225 wxPG_PROP_COLLAPSED = 0x0020,
226
227 /**
228 If property is selected, then indicates that validation failed for pending
229 value.
230
231 If property is not selected, then indicates that the actual property
232 value has failed validation (NB: this behaviour is not currently supported,
233 but may be used in the future).
234 */
235 wxPG_PROP_INVALID_VALUE = 0x0040,
236
237 // 0x0080,
238
239 /** Switched via SetWasModified(). Temporary flag - only used when
240 setting/changing property value.
241 */
242 wxPG_PROP_WAS_MODIFIED = 0x0200,
243
244 /**
245 If set, then child properties (if any) are private, and should be
246 "invisible" to the application.
247 */
248 wxPG_PROP_AGGREGATE = 0x0400,
249
250 /** If set, then child properties (if any) are copies and should not
251 be deleted in dtor.
252 */
253 wxPG_PROP_CHILDREN_ARE_COPIES = 0x0800,
254
255 /**
256 Classifies this item as a non-category.
257
258 Used for faster item type identification.
259 */
260 wxPG_PROP_PROPERTY = 0x1000,
261
262 /**
263 Classifies this item as a category.
264
265 Used for faster item type identification.
266 */
267 wxPG_PROP_CATEGORY = 0x2000,
268
269 /** Classifies this item as a property that has children, but is not aggregate
270 (ie children are not private).
271 */
272 wxPG_PROP_MISC_PARENT = 0x4000,
273
274 /** Property is read-only. Editor is still created for wxTextCtrl-based
275 property editors. For others, editor is not usually created because
276 they do implement wxTE_READONLY style or equivalent.
277 */
278 wxPG_PROP_READONLY = 0x8000,
279
280 //
281 // NB: FLAGS ABOVE 0x8000 CANNOT BE USED WITH PROPERTY ITERATORS
282 //
283
284 /** Property's value is composed from values of child properties.
285 @remarks
286 This flag cannot be used with property iterators.
287 */
288 wxPG_PROP_COMPOSED_VALUE = 0x00010000,
289
290 /** Common value of property is selectable in editor.
291 @remarks
292 This flag cannot be used with property iterators.
293 */
294 wxPG_PROP_USES_COMMON_VALUE = 0x00020000,
295
296 /** Property can be set to unspecified value via editor.
297 Currently, this applies to following properties:
298 - wxIntProperty, wxUIntProperty, wxFloatProperty, wxEditEnumProperty:
299 Clear the text field
300
301 @remarks
302 This flag cannot be used with property iterators.
303
304 @see wxPGProperty::SetAutoUnspecified()
305 */
306 wxPG_PROP_AUTO_UNSPECIFIED = 0x00040000,
307
308 /** Indicates the bit useable by derived properties.
309 */
310 wxPG_PROP_CLASS_SPECIFIC_1 = 0x00080000,
311
312 /** Indicates the bit useable by derived properties.
313 */
314 wxPG_PROP_CLASS_SPECIFIC_2 = 0x00100000,
315
316 /** Indicates that the property is being deleted and should be ignored.
317 */
318 wxPG_PROP_BEING_DELETED = 0x00200000
319
320 };
321
322 /** Topmost flag.
323 */
324 #define wxPG_PROP_MAX wxPG_PROP_AUTO_UNSPECIFIED
325
326 /** Property with children must have one of these set, otherwise iterators
327 will not work correctly.
328 Code should automatically take care of this, however.
329 */
330 #define wxPG_PROP_PARENTAL_FLAGS \
331 ((wxPGPropertyFlags)(wxPG_PROP_AGGREGATE | \
332 wxPG_PROP_CATEGORY | \
333 wxPG_PROP_MISC_PARENT))
334
335 /** @}
336 */
337
338
339 /**
340 @class wxPGProperty
341
342 wxPGProperty is base class for all wxPropertyGrid properties. In
343 sections below we cover few related topics.
344
345 @li @ref pgproperty_properties
346 @li @ref pgproperty_creating
347
348 @section pgproperty_properties Supplied Ready-to-use Property Classes
349
350 Here is a list and short description of supplied fully-functional
351 property classes. They are located in either props.h or advprops.h.
352
353 @li @ref wxArrayStringProperty
354 @li @ref wxBoolProperty
355 @li @ref wxColourProperty
356 @li @ref wxCursorProperty
357 @li @ref wxDateProperty
358 @li @ref wxDirProperty
359 @li @ref wxEditEnumProperty
360 @li @ref wxEnumProperty
361 @li @ref wxFileProperty
362 @li @ref wxFlagsProperty
363 @li @ref wxFloatProperty
364 @li @ref wxFontProperty
365 @li @ref wxImageFileProperty
366 @li @ref wxIntProperty
367 @li @ref wxLongStringProperty
368 @li @ref wxMultiChoiceProperty
369 @li @ref wxPropertyCategory
370 @li @ref wxStringProperty
371 @li @ref wxSystemColourProperty
372 @li @ref wxUIntProperty
373
374 @subsection wxPropertyCategory
375
376 Not an actual property per se, but a header for a group of properties.
377 Regardless inherits from wxPGProperty, and supports displaying 'labels'
378 for columns other than the first one. Easiest way to set category's
379 label for second column is to call wxPGProperty::SetValue() with string
380 argument.
381
382 @subsection wxStringProperty
383
384 Simple string property. wxPG_STRING_PASSWORD attribute may be used
385 to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl.
386 wxPG_ATTR_AUTOCOMPLETE attribute may be used to enable auto-completion
387 (use a wxArrayString value), and is also supported by any property that
388 happens to use a wxTextCtrl-based editor.
389
390 @remarks wxStringProperty has a special trait: if it has value of
391 "<composed>", and also has child properties, then its displayed
392 value becomes composition of child property values, similar as
393 with wxFontProperty, for instance.
394
395 @subsection wxIntProperty
396
397 Like wxStringProperty, but converts text to a signed long integer.
398 wxIntProperty seamlessly supports 64-bit integers (ie. wxLongLong).
399 To safely convert variant to integer, use code like this:
400
401 @code
402 wxLongLong ll;
403 ll << property->GetValue();
404
405 // or
406 wxLongLong ll = propertyGrid->GetPropertyValueAsLong(property);
407 @endcode
408
409 @subsection wxUIntProperty
410
411 Like wxIntProperty, but displays value as unsigned int. To set
412 the prefix used globally, manipulate wxPG_UINT_PREFIX string attribute.
413 To set the globally used base, manipulate wxPG_UINT_BASE int
414 attribute. Regardless of current prefix, understands (hex) values starting
415 with both "0x" and "$".
416 Like wxIntProperty, wxUIntProperty seamlessly supports 64-bit unsigned
417 integers (ie. wxULongLong). Same wxVariant safety rules apply.
418
419 @subsection wxFloatProperty
420
421 Like wxStringProperty, but converts text to a double-precision floating point.
422 Default float-to-text precision is 6 decimals, but this can be changed
423 by modifying wxPG_FLOAT_PRECISION attribute.
424
425 Note that when displaying the value, sign is omitted if the resulting
426 textual representation is effectively zero (for example, -0.0001 with
427 precision of 3 will become 0.0 instead of -0.0). This behaviour is unlike
428 what C standard library does, but should result in better end-user
429 experience in almost all cases.
430
431 @subsection wxBoolProperty
432
433 Represents a boolean value. wxChoice is used as editor control, by the
434 <<<<<<< .mine
435 default. wxPG_BOOL_USE_CHECKBOX attribute can be set to true in order to
436 use check box instead.
437 =======
438 default. wxPG_BOOL_USE_CHECKBOX attribute can be set to true in order to use
439 check box instead.
440 >>>>>>> .r67279
441
442 @subsection wxLongStringProperty
443
444 Like wxStringProperty, but has a button that triggers a small text editor
445 dialog. Note that in long string values, tabs are represented by "\t" and
446 line break by "\n".
447
448 To display custom dialog on button press, you can subclass
449 wxLongStringProperty and implement OnButtonClick, like this:
450
451 @code
452 virtual bool OnButtonClick( wxPropertyGrid* propGrid, wxString& value )
453 {
454 wxSize dialogSize(...size of your dialog...);
455
456 wxPoint dlgPos = propGrid->GetGoodEditorDialogPosition(this,
457 dialogSize)
458
459 // Create dialog dlg at dlgPos. Use value as initial string
460 // value.
461 ...
462
463 if ( dlg.ShowModal() == wxID_OK )
464 {
465 value = dlg.GetStringValue);
466 return true;
467 }
468 return false;
469 }
470 @endcode
471
472 Also, if you wish not to have line breaks and tabs translated to
473 escape sequences, then do following in constructor of your subclass:
474
475 @code
476 m_flags |= wxPG_PROP_NO_ESCAPE;
477 @endcode
478
479 @subsection wxDirProperty
480
481 Like wxLongStringProperty, but the button triggers dir selector instead.
482 Supported properties (all with string value): wxPG_DIR_DIALOG_MESSAGE.
483
484 @subsection wxFileProperty
485
486 Like wxLongStringProperty, but the button triggers file selector instead.
487 Default wildcard is "All files..." but this can be changed by setting
488 wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details).
489 Attribute wxPG_FILE_SHOW_FULL_PATH can be set to @false in order to show
490 only the filename, not the entire path.
491
492 @subsection wxEnumProperty
493
494 Represents a single selection from a list of choices -
495 wxOwnerDrawnComboBox is used to edit the value.
496
497 @subsection wxFlagsProperty
498
499 Represents a bit set that fits in a long integer. wxBoolProperty sub-
500 properties are created for editing individual bits. Textctrl is created to
501 manually edit the flags as a text; a continuous sequence of spaces, commas
502 and semicolons are considered as a flag id separator.
503
504 <b>Note:</b> When changing "choices" (ie. flag labels) of wxFlagsProperty,
505 you will need to use wxPGProperty::SetChoices() - otherwise they will not
506 get updated properly.
507
508 wxFlagsProperty supports the same attributes as wxBoolProperty.
509
510 @subsection wxArrayStringProperty
511
512 Allows editing of a list of strings in wxTextCtrl and in a separate
513 dialog. Supports "Delimiter" attribute, which defaults to comma (',').
514
515 @subsection wxDateProperty
516
517 wxDateTime property. Default editor is DatePickerCtrl, although TextCtrl
518 should work as well. wxPG_DATE_FORMAT attribute can be used to change
519 string wxDateTime::Format uses (although default is recommended as it is
520 locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window
521 style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY).
522 Using wxDP_ALLOWNONE will enable better unspecified value support.
523
524 @subsection wxEditEnumProperty
525
526 Represents a string that can be freely edited or selected from list of choices -
527 custom combobox control is used to edit the value.
528
529 @subsection wxMultiChoiceProperty
530
531 Allows editing a multiple selection from a list of strings. This is
532 property is pretty much built around concept of wxMultiChoiceDialog.
533 It uses wxArrayString value.
534
535 @subsection wxImageFileProperty
536
537 Like wxFileProperty, but has thumbnail of the image in front of
538 the filename and autogenerates wildcard from available image handlers.
539
540 @subsection wxColourProperty
541
542 <b>Useful alternate editor:</b> Choice.
543
544 Represents wxColour. wxButton is used to trigger a colour picker dialog.
545 There are various sub-classing opportunities with this class. See
546 below in wxSystemColourProperty section for details.
547
548 Setting "HasAlpha" attribute to @true for this property allows user to
549 edit the alpha colour component.
550
551 @subsection wxFontProperty
552
553 Represents wxFont. Various sub-properties are used to edit individual
554 subvalues.
555
556 @subsection wxSystemColourProperty
557
558 Represents wxColour and a system colour index. wxChoice is used to edit
559 the value. Drop-down list has color images. Note that value type
560 is wxColourPropertyValue instead of wxColour (which wxColourProperty
561 uses).
562
563 @code
564 class wxColourPropertyValue : public wxObject
565 {
566 public:
567 // An integer value relating to the colour, and which exact
568 // meaning depends on the property with which it is used.
569 //
570 // For wxSystemColourProperty:
571 // Any of wxSYS_COLOUR_XXX, or any web-colour ( use wxPG_TO_WEB_COLOUR
572 // macro - (currently unsupported) ), or wxPG_COLOUR_CUSTOM.
573 wxUint32 m_type;
574
575 // Resulting colour. Should be correct regardless of type.
576 wxColour m_colour;
577 };
578 @endcode
579
580 in wxSystemColourProperty, and its derived class wxColourProperty, there
581 are various sub-classing features. To set a basic list of colour
582 names, call wxPGProperty::SetChoices().
583
584 @code
585 // Override in derived class to customize how colours are translated
586 // to strings.
587 virtual wxString ColourToString( const wxColour& col, int index ) const;
588
589 // Returns index of entry that triggers colour picker dialog
590 // (default is last).
591 virtual int GetCustomColourIndex() const;
592
593 // Helper function to show the colour dialog
594 bool QueryColourFromUser( wxVariant& variant ) const;
595
596 // Returns colour for given choice.
597 // Default function returns wxSystemSettings::GetColour(index).
598 virtual wxColour GetColour( int index ) const;
599 @endcode
600
601 @subsection wxCursorProperty
602
603 Represents a wxCursor. wxChoice is used to edit the value.
604 Drop-down list has cursor images under some (wxMSW) platforms.
605
606
607 @section pgproperty_creating Creating Custom Properties
608
609 New properties can be created by subclassing wxPGProperty or one
610 of the provided property classes, and (re)implementing necessary
611 member functions. Below, each virtual member function has ample
612 documentation about its purpose and any odd details which to keep
613 in mind.
614
615 Here is a very simple 'template' code:
616
617 @code
618 class MyProperty : public wxPGProperty
619 {
620 public:
621 // Default constructor
622 MyProperty() { }
623
624 // All arguments of this ctor must have a default value -
625 // use wxPG_LABEL for label and name
626 MyProperty( const wxString& label = wxPG_LABEL,
627 const wxString& name = wxPG_LABEL,
628 const wxString& value = wxEmptyString )
629 : wxPGProperty(label, name)
630 {
631 // m_value is wxVariant
632 m_value = value;
633 }
634
635 virtual ~MyProperty() { }
636
637 const wxPGEditor* DoGetEditorClass() const
638 {
639 // Determines editor used by property.
640 // You can replace 'TextCtrl' below with any of these
641 // builtin-in property editor identifiers: Choice, ComboBox,
642 // TextCtrlAndButton, ChoiceAndButton, CheckBox, SpinCtrl,
643 // DatePickerCtrl.
644 return wxPGEditor_TextCtrl;
645 }
646
647 virtual wxString ValueToString( wxVariant& value,
648 int argFlags ) const
649 {
650 // TODO: Convert given property value to a string
651 }
652
653 virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags )
654 {
655 // TODO: Adapt string to property value.
656 }
657
658 protected:
659 };
660 @endcode
661
662 Since wxPGProperty derives from wxObject, you can use standard
663 wxDECLARE_DYNAMIC_CLASS and wxIMPLEMENT_DYNAMIC_CLASS macros. From the
664 above example they were omitted for sake of simplicity, and besides,
665 they are only really needed if you need to use wxRTTI with your
666 property class.
667
668 You can change the 'value type' of a property by simply assigning different
669 type of variant with SetValue. <b>It is mandatory to implement
670 wxVariantData class for all data types used as property values.</b>
671 You can use macros declared in wxPropertyGrid headers. For instance:
672
673 @code
674 // In header file:
675 // (If you need to have export declaration, use version of macros
676 // with _EXPORTED postfix)
677 WX_PG_DECLARE_VARIANT_DATA(MyDataClass)
678
679 // In sources file:
680 WX_PG_IMPLEMENT_VARIANT_DATA(MyDataClass)
681
682 // Or, if you don't have valid == operator:
683 WX_PG_IMPLEMENT_VARIANT_DATA_DUMMY_EQ(MyDataClass)
684 @endcode
685
686 @library{wxpropgrid}
687 @category{propgrid}
688 */
689 class wxPGProperty : public wxObject
690 {
691 public:
692 typedef wxUint32 FlagType;
693
694 /**
695 Default constructor.
696 */
697 wxPGProperty();
698
699 /**
700 Constructor.
701 Non-abstract property classes should have constructor of this style:
702
703 @code
704
705 MyProperty( const wxString& label, const wxString& name, const T& value )
706 : wxPGProperty(label, name)
707 {
708 // Generally recommended way to set the initial value
709 // (as it should work in pretty much 100% of cases).
710 wxVariant variant;
711 variant << value;
712 SetValue(variant);
713
714 // If has private child properties then create them here.
715 // For example:
716 // AddPrivateChild( new wxStringProperty("Subprop 1",
717 // wxPG_LABEL,
718 // value.GetSubProp1()));
719 }
720
721 @endcode
722 */
723 wxPGProperty( const wxString& label, const wxString& name );
724
725 /**
726 Virtual destructor. It is customary for derived properties to implement this.
727 */
728 virtual ~wxPGProperty();
729
730 /**
731 This virtual function is called after m_value has been set.
732
733 @remarks
734 - If m_value was set to Null variant (ie. unspecified value), OnSetValue()
735 will not be called.
736 - m_value may be of any variant type. Typically properties internally support only
737 one variant type, and as such OnSetValue() provides a good opportunity to convert
738 supported values into internal type.
739 - Default implementation does nothing.
740 */
741 virtual void OnSetValue();
742
743 /**
744 Override this to return something else than m_value as the value.
745 */
746 virtual wxVariant DoGetValue() const;
747
748 /**
749 Implement this function in derived class to check the value.
750 Return @true if it is ok. Returning @false prevents property change events
751 from occurring.
752
753 @remarks
754 - Default implementation always returns @true.
755 */
756 virtual bool ValidateValue( wxVariant& value, wxPGValidationInfo& validationInfo ) const;
757
758 /**
759 Converts text into wxVariant value appropriate for this property.
760
761 @param variant
762 On function entry this is the old value (should not be wxNullVariant
763 in normal cases). Translated value must be assigned back to it.
764
765 @param text
766 Text to be translated into variant.
767
768 @param argFlags
769 If wxPG_FULL_VALUE is set, returns complete, storable value instead
770 of displayable one (they may be different).
771 If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
772 composite property string value (as generated by ValueToString()
773 called with this same flag).
774
775 @return Returns @true if resulting wxVariant value was different.
776
777 @remarks Default implementation converts semicolon delimited tokens into
778 child values. Only works for properties with children.
779
780 You might want to take into account that m_value is Null variant
781 if property value is unspecified (which is usually only case if
782 you explicitly enabled that sort behaviour).
783 */
784 virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags = 0 ) const;
785
786 /**
787 Converts integer (possibly a choice selection) into wxVariant value
788 appropriate for this property.
789
790 @param variant
791 On function entry this is the old value (should not be wxNullVariant
792 in normal cases). Translated value must be assigned back to it.
793 @param number
794 Integer to be translated into variant.
795 @param argFlags
796 If wxPG_FULL_VALUE is set, returns complete, storable value instead
797 of displayable one.
798
799 @return Returns @true if resulting wxVariant value was different.
800
801 @remarks
802 - If property is not supposed to use choice or spinctrl or other editor
803 with int-based value, it is not necessary to implement this method.
804 - Default implementation simply assign given int to m_value.
805 - If property uses choice control, and displays a dialog on some choice
806 items, then it is preferred to display that dialog in IntToValue
807 instead of OnEvent.
808 - You might want to take into account that m_value is Mull variant if
809 property value is unspecified (which is usually only case if you
810 explicitly enabled that sort behaviour).
811 */
812 virtual bool IntToValue( wxVariant& variant, int number, int argFlags = 0 ) const;
813
814 /**
815 Converts property value into a text representation.
816
817 @param value
818 Value to be converted.
819 @param argFlags
820 If 0 (default value), then displayed string is returned.
821 If wxPG_FULL_VALUE is set, returns complete, storable string value
822 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
823 string value that must be editable in textctrl.
824 If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
825 display as a part of string property's composite text representation.
826
827 @remarks Default implementation calls GenerateComposedValue().
828 */
829 virtual wxString ValueToString( wxVariant& value, int argFlags = 0 ) const;
830
831 /**
832 Converts string to a value, and if successful, calls SetValue() on it.
833 Default behaviour is to do nothing.
834
835 @param text
836 String to get the value from.
837 @param flags
838 @todo docme
839
840 @return @true if value was changed.
841 */
842 bool SetValueFromString( const wxString& text, int flags = 0 );
843
844 /**
845 <<<<<<< .mine
846 Converts integer to a value, and if successful, calls SetValue() on it.
847 Default behaviour is to do nothing.
848 =======
849 Converts integer to a value, and if successful, calls SetValue() on it.
850 Default behavior is to do nothing.
851 >>>>>>> .r67279
852
853 @param value
854 Int to get the value from.
855 @param flags
856 If has wxPG_FULL_VALUE, then the value given is a actual value and not an index.
857
858 @return @true if value was changed.
859 */
860 bool SetValueFromInt( long value, int flags = 0 );
861
862 /**
863 Returns size of the custom painted image in front of property. This method
864 must be overridden to return non-default value if OnCustomPaint is to be
865 called.
866
867 @param item
868 Normally -1, but can be an index to the property's list of items.
869
870 @remarks
871 - Default behaviour is to return wxSize(0,0), which means no image.
872 - Default image width or height is indicated with dimension -1.
873 - You can also return wxPG_DEFAULT_IMAGE_SIZE which equals wxSize(-1, -1).
874 */
875 virtual wxSize OnMeasureImage( int item = -1 ) const;
876
877 /**
878 Events received by editor widgets are processed here. Note that editor class
879 usually processes most events. Some, such as button press events of
880 TextCtrlAndButton class, can be handled here. Also, if custom handling
881 for regular events is desired, then that can also be done (for example,
882 wxSystemColourProperty custom handles @c wxEVT_COMMAND_CHOICE_SELECTED
883 to display colour picker dialog when 'custom' selection is made).
884
885 If the event causes value to be changed, SetValueInEvent() should be called
886 to set the new value.
887
888 The parameter @a event is the associated wxEvent.
889
890 @retval
891 Should return @true if any changes in value should be reported.
892
893 @remarks
894 - If property uses choice control, and displays a dialog on some choice items,
895 then it is preferred to display that dialog in IntToValue instead of OnEvent.
896 */
897 virtual bool OnEvent( wxPropertyGrid* propgrid, wxWindow* wnd_primary, wxEvent& event );
898
899 /**
900 Called after value of a child property has been altered. Must return
901 new value of the whole property (after any alterations warranted by
902 child's new value).
903
904 Note that this function is usually called at the time that value of
905 this property, or given child property, is still pending for change,
906 and as such, result of GetValue() or m_value should not be relied
907 on.
908
909 Sample pseudo-code implementation:
910
911 @code
912 wxVariant MyProperty::ChildChanged( wxVariant& thisValue,
913 int childIndex,
914 wxVariant& childValue ) const
915 {
916 // Acquire reference to actual type of data stored in variant
917 // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros
918 // were used to create the variant class).
919 T& data = TFromVariant(thisValue);
920
921 // Copy childValue into data.
922 switch ( childIndex )
923 {
924 case 0:
925 data.SetSubProp1( childvalue.GetLong() );
926 break;
927 case 1:
928 data.SetSubProp2( childvalue.GetString() );
929 break;
930 ...
931 }
932
933 // Return altered data
934 return data;
935 }
936 @endcode
937
938 @param thisValue
939 Value of this property. Changed value should be returned (in
940 previous versions of wxPropertyGrid it was only necessary to
941 write value back to this argument).
942 @param childIndex
943 Index of child changed (you can use Item(childIndex) to get
944 child property).
945 @param childValue
946 (Pending) value of the child property.
947
948 @return
949 Modified value of the whole property.
950 */
951 virtual wxVariant ChildChanged( wxVariant& thisValue,
952 int childIndex,
953 wxVariant& childValue ) const;
954
955 /**
956 Returns pointer to an instance of used editor.
957 */
958 virtual const wxPGEditor* DoGetEditorClass() const;
959
960 /**
961 Returns pointer to the wxValidator that should be used
962 with the editor of this property (@NULL for no validator).
963 Setting validator explicitly via SetPropertyValidator
964 will override this.
965
966 In most situations, code like this should work well
967 (macros are used to maintain one actual validator instance,
968 so on the second call the function exits within the first
969 macro):
970
971 @code
972
973 wxValidator* wxMyPropertyClass::DoGetValidator () const
974 {
975 WX_PG_DOGETVALIDATOR_ENTRY()
976
977 wxMyValidator* validator = new wxMyValidator(...);
978
979 ... prepare validator...
980
981 WX_PG_DOGETVALIDATOR_EXIT(validator)
982 }
983
984 @endcode
985
986 @remarks
987 You can get common filename validator by returning
988 wxFileProperty::GetClassValidator(). wxDirProperty,
989 for example, uses it.
990 */
991 virtual wxValidator* DoGetValidator () const;
992
993 /**
994 Override to paint an image in front of the property value text or drop-down
995 list item (but only if wxPGProperty::OnMeasureImage is overridden as well).
996
997 If property's OnMeasureImage() returns size that has height != 0 but less than
998 row height ( < 0 has special meanings), wxPropertyGrid calls this method to
999 draw a custom image in a limited area in front of the editor control or
1000 value text/graphics, and if control has drop-down list, then the image is
1001 drawn there as well (even in the case OnMeasureImage() returned higher height
1002 than row height).
1003
1004 NOTE: Following applies when OnMeasureImage() returns a "flexible" height (
1005 using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable height items:
1006 If rect.x is < 0, then this is a measure item call, which means that
1007 dc is invalid and only thing that should be done is to set paintdata.m_drawnHeight
1008 to the height of the image of item at index paintdata.m_choiceItem. This call
1009 may be done even as often as once every drop-down popup show.
1010
1011 @param dc
1012 wxDC to paint on.
1013 @param rect
1014 Box reserved for custom graphics. Includes surrounding rectangle, if any.
1015 If x is < 0, then this is a measure item call (see above).
1016 @param paintdata
1017 wxPGPaintData structure with much useful data about painted item.
1018 @code
1019 struct wxPGPaintData
1020 {
1021 // wxPropertyGrid.
1022 const wxPropertyGrid* m_parent;
1023
1024 // Normally -1, otherwise index to drop-down list item that has to be drawn.
1025 int m_choiceItem;
1026
1027 // Set to drawn width in OnCustomPaint (optional).
1028 int m_drawnWidth;
1029
1030 // In a measure item call, set this to the height of item at m_choiceItem index
1031 int m_drawnHeight;
1032 };
1033 @endcode
1034
1035 @remarks
1036 - You can actually exceed rect width, but if you do so then paintdata.m_drawnWidth
1037 must be set to the full width drawn in pixels.
1038 - Due to technical reasons, rect's height will be default even if custom height
1039 was reported during measure call.
1040 - Brush is guaranteed to be default background colour. It has been already used to
1041 clear the background of area being painted. It can be modified.
1042 - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper colour) pen for
1043 drawing framing rectangle. It can be changed as well.
1044
1045 @see ValueToString()
1046 */
1047 virtual void OnCustomPaint( wxDC& dc, const wxRect& rect, wxPGPaintData& paintdata );
1048
1049 /**
1050 Returns used wxPGCellRenderer instance for given property column (label=0, value=1).
1051
1052 Default implementation returns editor's renderer for all columns.
1053 */
1054 virtual wxPGCellRenderer* GetCellRenderer( int column ) const;
1055
1056 /**
1057 Returns which choice is currently selected. Only applies to properties
1058 which have choices.
1059
1060 Needs to reimplemented in derived class if property value does not
1061 map directly to a choice. Integer as index, bool, and string usually do.
1062 */
1063 virtual int GetChoiceSelection() const;
1064
1065 /**
1066 Refresh values of child properties. Automatically called after value is set.
1067 */
1068 virtual void RefreshChildren();
1069
1070 /**
1071 Reimplement this member function to add special handling for
1072 attributes of this property.
1073
1074 @return Return @false to have the attribute automatically stored in
1075 m_attributes. Default implementation simply does that and
1076 nothing else.
1077
1078 @remarks To actually set property attribute values from the
1079 application, use wxPGProperty::SetAttribute() instead.
1080 */
1081 virtual bool DoSetAttribute( const wxString& name, wxVariant& value );
1082
1083 /**
1084 Returns value of an attribute.
1085
1086 Override if custom handling of attributes is needed.
1087
1088 Default implementation simply return @NULL variant.
1089 */
1090 virtual wxVariant DoGetAttribute( const wxString& name ) const;
1091
1092 /**
1093 Returns instance of a new wxPGEditorDialogAdapter instance, which is
1094 used when user presses the (optional) button next to the editor control;
1095
1096 Default implementation returns @NULL (ie. no action is generated when
1097 button is pressed).
1098 */
1099 virtual wxPGEditorDialogAdapter* GetEditorDialog() const;
1100
1101 /**
1102 Called whenever validation has failed with given pending value.
1103
1104 @remarks If you implement this in your custom property class, please
1105 remember to call the baser implementation as well, since they
1106 may use it to revert property into pre-change state.
1107 */
1108 virtual void OnValidationFailure( wxVariant& pendingValue );
1109
1110 /**
1111 Append a new choice to property's list of choices.
1112
1113 @param label
1114 Label for added choice.
1115
1116 @param value
1117 Value for new choice. Do not specify if you wish this
1118 to equal choice index.
1119
1120 @return
1121 Index to added choice.
1122 */
1123 int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE );
1124
1125 /**
1126 Adds a private child property.
1127
1128 @deprecated Use AddPrivateChild() instead.
1129
1130 @see AddPrivateChild()
1131 */
1132 wxDEPRECATED( void AddChild( wxPGProperty* prop ) );
1133
1134 /**
1135 Adds a private child property. If you use this instead of
1136 wxPropertyGridInterface::Insert() or
1137 wxPropertyGridInterface::AppendIn(), then property's parental
1138 type will automatically be set up to wxPG_PROP_AGGREGATE. In other
1139 words, all properties of this property will become private.
1140 */
1141 void AddPrivateChild( wxPGProperty* prop );
1142
1143 /**
1144 Adapts list variant into proper value using consecutive
1145 ChildChanged() calls.
1146 */
1147 void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
1148
1149 /**
1150 Use this member function to add independent (ie. regular) children to
1151 a property.
1152
1153 @return Appended childProperty.
1154
1155 @remarks wxPropertyGrid is not automatically refreshed by this
1156 function.
1157
1158 @see InsertChild(), AddPrivateChild()
1159 */
1160 wxPGProperty* AppendChild( wxPGProperty* childProperty );
1161
1162 /**
1163 Determines, recursively, if all children are not unspecified.
1164
1165 @param pendingList
1166 Assumes members in this wxVariant list as pending
1167 replacement values.
1168 */
1169 bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const;
1170
1171 /**
1172 Returns @true if children of this property are component values (for instance,
1173 points size, face name, and is_underlined are component values of a font).
1174 */
1175 bool AreChildrenComponents() const;
1176
1177 /**
1178 Sets or clears given property flag. Mainly for internal use.
1179
1180 @remarks Setting a property flag never has any side-effect, and is
1181 intended almost exclusively for internal use. So, for
1182 example, if you want to disable a property, call
1183 Enable(false) instead of setting wxPG_PROP_DISABLED flag.
1184
1185 @see HasFlag(), GetFlags()
1186 */
1187 void ChangeFlag( wxPGPropertyFlags flag, bool set );
1188
1189 /**
1190 Deletes children of the property.
1191 */
1192 void DeleteChildren();
1193
1194 /**
1195 Removes entry from property's wxPGChoices and editor control (if it is active).
1196
1197 If selected item is deleted, then the value is set to unspecified.
1198 */
1199 void DeleteChoice( int index );
1200
1201 /** Deletes all child properties. */
1202 void Empty();
1203
1204 /**
1205 Enables or disables the property. Disabled property usually appears
1206 as having grey text.
1207
1208 @param enable
1209 If @false, property is disabled instead.
1210
1211 @see wxPropertyGridInterface::EnableProperty()
1212 */
1213 void Enable( bool enable = true );
1214
1215 /**
1216 Composes text from values of child properties.
1217 */
1218 wxString GenerateComposedValue() const;
1219
1220 /**
1221 Returns property attribute value, null variant if not found.
1222 */
1223 wxVariant GetAttribute( const wxString& name ) const;
1224
1225 /** Returns named attribute, as string, if found. Otherwise defVal is returned.
1226 */
1227 wxString GetAttribute( const wxString& name, const wxString& defVal ) const;
1228
1229 /** Returns named attribute, as long, if found. Otherwise defVal is returned.
1230 */
1231 long GetAttributeAsLong( const wxString& name, long defVal ) const;
1232
1233 /** Returns named attribute, as double, if found. Otherwise defVal is returned.
1234 */
1235 double GetAttributeAsDouble( const wxString& name, double defVal ) const;
1236
1237 /**
1238 Returns attributes as list wxVariant.
1239 */
1240 wxVariant GetAttributesAsList() const;
1241
1242 /**
1243 Returns editor used for given column. @NULL for no editor.
1244 */
1245 const wxPGEditor* GetColumnEditor( int column ) const;
1246
1247 /** Returns property's base name (ie. parent's name is not added in any case) */
1248 const wxString& GetBaseName() const;
1249
1250 /**
1251 Returns wxPGCell of given column.
1252
1253 @remarks const version of this member function returns 'default'
1254 wxPGCell object if the property itself didn't hold
1255 cell data.
1256 */
1257 const wxPGCell& GetCell( unsigned int column ) const;
1258
1259 /**
1260 Returns wxPGCell of given column, creating one if necessary.
1261 */
1262 wxPGCell& GetCell( unsigned int column );
1263
1264 /**
1265 Returns wxPGCell of given column, creating one if necessary.
1266 */
1267 wxPGCell& GetOrCreateCell( unsigned int column );
1268
1269 /**
1270 Returns number of child properties.
1271 */
1272 unsigned int GetChildCount() const;
1273
1274 /**
1275 Returns height of children, recursively, and
1276 by taking expanded/collapsed status into account.
1277
1278 @param lh
1279 Line height. Pass result of GetGrid()->GetRowHeight() here.
1280
1281 @param iMax
1282 Only used (internally) when finding property y-positions.
1283 */
1284 int GetChildrenHeight( int lh, int iMax = -1 ) const;
1285
1286 /**
1287 Returns read-only reference to property's list of choices.
1288 */
1289 const wxPGChoices& GetChoices() const;
1290
1291 /**
1292 Returns client data (void*) of a property.
1293 */
1294 void* GetClientData() const;
1295
1296 /** Sets managed client object of a property.
1297 */
1298 wxClientData *GetClientObject() const;
1299
1300 /**
1301 Returns property's default value. If property's value type is not
1302 a built-in one, and "DefaultValue" attribute is not defined, then
1303 this function usually returns Null variant.
1304 */
1305 wxVariant GetDefaultValue() const;
1306
1307 /** Returns property's displayed text.
1308 */
1309 wxString GetDisplayedString() const;
1310
1311 /**
1312 Returns wxPGEditor that will be used and created when
1313 property becomes selected. Returns more accurate value
1314 than DoGetEditorClass().
1315 */
1316 const wxPGEditor* GetEditorClass() const;
1317
1318 /**
1319 Returns property flags.
1320 */
1321 FlagType GetFlags() const;
1322
1323 /** Returns property grid where property lies. */
1324 wxPropertyGrid* GetGrid() const;
1325
1326 /**
1327 Returns owner wxPropertyGrid, but only if one is currently on a page
1328 displaying this property.
1329 */
1330 wxPropertyGrid* GetGridIfDisplayed() const;
1331
1332 /**
1333 Returns property's help or description text.
1334
1335 @see SetHelpString()
1336 */
1337 const wxString& GetHelpString() const;
1338
1339 /**
1340 Returns position in parent's array.
1341 */
1342 unsigned int GetIndexInParent() const;
1343
1344 /** Returns property's label. */
1345 const wxString& GetLabel() const;
1346
1347 /**
1348 Returns last visible child property, recursively.
1349 */
1350 const wxPGProperty* GetLastVisibleSubItem() const;
1351
1352 /**
1353 Returns highest level non-category, non-root parent. Useful when you
1354 have nested properties with children.
1355
1356 @remarks If immediate parent is root or category, this will return the
1357 property itself.
1358 */
1359 wxPGProperty* GetMainParent() const;
1360
1361 /** Returns maximum allowed length of property's text value.
1362 */
1363 int GetMaxLength() const;
1364
1365 /** Returns property's name with all (non-category, non-root) parents. */
1366 wxString GetName() const;
1367
1368 /** Return parent of property */
1369 wxPGProperty* GetParent() const;
1370
1371 /**
1372 Returns (direct) child property with given name (or @NULL if not found).
1373 */
1374 wxPGProperty* GetPropertyByName( const wxString& name ) const;
1375
1376 /** Gets assignable version of property's validator. */
1377 wxValidator* GetValidator() const;
1378
1379 /**
1380 Returns property's value.
1381 */
1382 wxVariant GetValue() const;
1383
1384 /**
1385 Returns bitmap that appears next to value text. Only returns non-@NULL
1386 bitmap if one was set with SetValueImage().
1387 */
1388 wxBitmap* GetValueImage() const;
1389
1390 /** Returns text representation of property's value.
1391
1392 @param argFlags
1393 If 0 (default value), then displayed string is returned.
1394 If wxPG_FULL_VALUE is set, returns complete, storable string value
1395 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
1396 string value that must be editable in textctrl. If
1397 wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
1398 display as a part of string property's composite text
1399 representation.
1400
1401 @remarks In older versions, this function used to be overridden to convert
1402 property's value into a string representation. This function is
1403 now handled by ValueToString(), and overriding this function now
1404 will result in run-time assertion failure.
1405 */
1406 virtual wxString GetValueAsString( int argFlags = 0 ) const;
1407
1408 /** Synonymous to GetValueAsString().
1409
1410 @deprecated Use GetValueAsString() instead.
1411
1412 @see GetValueAsString()
1413 */
1414 wxDEPRECATED( wxString GetValueString( int argFlags = 0 ) const );
1415
1416 /**
1417 Returns value type used by this property.
1418 */
1419 wxString GetValueType() const;
1420
1421 /**
1422 Returns coordinate to the top y of the property. Note that the
1423 position of scrollbars is not taken into account.
1424 */
1425 int GetY() const;
1426
1427 /**
1428 Returns non-zero if property has given flag set.
1429
1430 @see propgrid_propflags
1431 */
1432 FlagType HasFlag( wxPGPropertyFlags flag ) const;
1433
1434 /**
1435 Returns @true if property has even one visible child.
1436 */
1437 bool HasVisibleChildren() const;
1438
1439 /**
1440 Hides or reveals the property.
1441
1442 @param hide
1443 @true for hide, @false for reveal.
1444
1445 @param flags
1446 By default changes are applied recursively. Set this parameter wxPG_DONT_RECURSE to prevent this.
1447 */
1448 bool Hide( bool hide, int flags = wxPG_RECURSE );
1449
1450 /**
1451 Returns index of given child property. wxNOT_FOUND if
1452 given property is not child of this.
1453 */
1454 int Index( const wxPGProperty* p ) const;
1455
1456 /**
1457 Use this member function to add independent (ie. regular) children to
1458 a property.
1459
1460 @return Inserted childProperty.
1461
1462 @remarks wxPropertyGrid is not automatically refreshed by this
1463 function.
1464
1465 @see AppendChild(), AddPrivateChild()
1466 */
1467 wxPGProperty* InsertChild( int index, wxPGProperty* childProperty );
1468
1469 /**
1470 Inserts a new choice to property's list of choices.
1471
1472 @param label
1473 Text for new choice
1474
1475 @param index
1476 Insertion position. Use wxNOT_FOUND to append.
1477
1478 @param value
1479 Value for new choice. Do not specify if you wish this
1480 to equal choice index.
1481 */
1482 int InsertChoice( const wxString& label, int index, int value = wxPG_INVALID_VALUE );
1483
1484 /**
1485 Returns @true if this property is actually a wxPropertyCategory.
1486 */
1487 bool IsCategory() const;
1488
1489 /**
1490 Returns @true if property is enabled.
1491 */
1492 bool IsEnabled() const;
1493
1494 /**
1495 Returns @true if property has visible children.
1496 */
1497 bool IsExpanded() const;
1498
1499 /**
1500 Returns @true if this property is actually a wxRootProperty.
1501 */
1502 bool IsRoot() const;
1503
1504 /**
1505 Returns @true if candidateParent is some parent of this property.
1506 */
1507 bool IsSomeParent( wxPGProperty* candidateParent ) const;
1508
1509 /**
1510 Returns true if property has editable wxTextCtrl when selected.
1511
1512 @remarks Although disabled properties do not displayed editor, they still
1513 return @true here as being disabled is considered a temporary
1514 condition (unlike being read-only or having limited editing enabled).
1515 */
1516 bool IsTextEditable() const;
1517
1518 /**
1519 Returns @true if property's value is considered unspecified. This
1520 usually means that value is Null variant.
1521 */
1522 bool IsValueUnspecified() const;
1523
1524 /**
1525 Returns true if all parents expanded.
1526 */
1527 bool IsVisible() const;
1528
1529 /**
1530 Returns child property at index i.
1531 */
1532 wxPGProperty* Item( unsigned int i ) const;
1533
1534 /**
1535 If property's editor is active, then update it's value.
1536 */
1537 void RefreshEditor();
1538
1539 /**
1540 Sets an attribute for this property.
1541
1542 @param name
1543 Text identifier of attribute. See @ref propgrid_property_attributes.
1544
1545 @param value
1546 Value of attribute.
1547
1548 @remarks Setting attribute's value to Null variant will simply remove it
1549 from property's set of attributes.
1550 */
1551 void SetAttribute( const wxString& name, wxVariant value );
1552
1553 /**
1554 Set if user can change the property's value to unspecified by
1555 modifying the value of the editor control (usually by clearing
1556 it). Currently, this can work with following properties:
1557 wxIntProperty, wxUIntProperty, wxFloatProperty, wxEditEnumProperty.
1558
1559 @param enable
1560 Whether to enable or disable this behaviour (it is disabled by
1561 default).
1562 */
1563 void SetAutoUnspecified( bool enable = true );
1564
1565 /**
1566 Sets property's background colour.
1567
1568 @param colour
1569 Background colour to use.
1570
1571 @param flags
1572 Default is wxPG_RECURSE which causes colour to be set recursively.
1573 Omit this flag to only set colour for the property in question
1574 and not any of its children.
1575 */
1576 void SetBackgroundColour( const wxColour& colour,
1577 int flags = wxPG_RECURSE );
1578
1579 /**
1580 Sets editor for a property.
1581
1582 @param editor
1583 For builtin editors, use wxPGEditor_X, where X is builtin editor's
1584 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list).
1585
1586 For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
1587 */
1588 void SetEditor( const wxPGEditor* editor );
1589
1590 /**
1591 Sets editor for a property, by editor name.
1592 */
1593 void SetEditor( const wxString& editorName );
1594
1595 /**
1596 Sets cell information for given column.
1597 */
1598 void SetCell( int column, const wxPGCell& cell );
1599
1600 /**
1601 Sets new set of choices for the property.
1602
1603 @remarks This operation deselects the property and clears its
1604 value.
1605 */
1606 bool SetChoices( wxPGChoices& choices );
1607
1608 /**
1609 Sets client data (void*) of a property.
1610
1611 @remarks This untyped client data has to be deleted manually.
1612 */
1613 void SetClientData( void* clientData );
1614
1615 /** Returns client object of a property.
1616 */
1617 void SetClientObject(wxClientData* clientObject);
1618
1619 /**
1620 Sets selected choice and changes property value.
1621
1622 Tries to retain value type, although currently if it is not string,
1623 then it is forced to integer.
1624 */
1625 void SetChoiceSelection( int newValue );
1626
1627 /** Set default value of a property. Synonymous to
1628
1629 @code
1630 SetAttribute("DefaultValue", value);
1631 @endcode
1632 */
1633 void SetDefaultValue( wxVariant& value );
1634
1635 /**
1636 Sets or clears given property flag, recursively. This function is
1637 primarily intended for internal use.
1638
1639 @see ChangeFlag()
1640 */
1641 void SetFlagRecursively( wxPGPropertyFlags flag, bool set );
1642
1643 /**
1644 Sets property's help string, which is shown, for example, in
1645 wxPropertyGridManager's description text box.
1646 */
1647 void SetHelpString( const wxString& helpString );
1648
1649 /**
1650 Sets property's label.
1651
1652 @remarks Properties under same parent may have same labels. However,
1653 property names must still remain unique.
1654 */
1655 void SetLabel( const wxString& label );
1656
1657 /**
1658 Set max length of text in text editor.
1659 */
1660 bool SetMaxLength( int maxLen );
1661
1662 /**
1663 Sets property's "is it modified?" flag. Affects children recursively.
1664 */
1665 void SetModifiedStatus( bool modified );
1666
1667 /**
1668 Sets new (base) name for property.
1669 */
1670 void SetName( const wxString& newName );
1671
1672 /**
1673 Changes what sort of parent this property is for its children.
1674
1675 @param flag
1676 Use one of the following values: wxPG_PROP_MISC_PARENT (for generic
1677 parents), wxPG_PROP_CATEGORY (for categories), or
1678 wxPG_PROP_AGGREGATE (for derived property classes with private
1679 children).
1680
1681 @remarks You generally do not need to call this function.
1682 */
1683 void SetParentalType( int flag );
1684
1685 /**
1686 Sets property's text colour.
1687
1688 @param colour
1689 Text colour to use.
1690
1691 @param flags
1692 Default is wxPG_RECURSE which causes colour to be set recursively.
1693 Omit this flag to only set colour for the property in question
1694 and not any of its children.
1695 */
1696 void SetTextColour( const wxColour& colour,
1697 int flags = wxPG_RECURSE );
1698
1699 /** Sets wxValidator for a property */
1700 void SetValidator( const wxValidator& validator );
1701
1702 /**
1703 Call this to set value of the property. Unlike methods in wxPropertyGrid,
1704 this does not automatically update the display.
1705
1706 @remarks
1707 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through
1708 validation process and send property change event.
1709
1710 If you need to change property value in event, based on user input, use
1711 SetValueInEvent() instead.
1712
1713 @param value
1714 The value to set.
1715 @param pList
1716 Pointer to list variant that contains child values. Used to indicate
1717 which children should be marked as modified. Usually you just use @NULL.
1718 @param flags
1719 wxPG_SETVAL_REFRESH_EDITOR is set by default, to refresh editor
1720 and redraw properties.
1721 */
1722 void SetValue( wxVariant value, wxVariant* pList = NULL,
1723 int flags = wxPG_SETVAL_REFRESH_EDITOR );
1724
1725 /**
1726 Set wxBitmap in front of the value. This bitmap may be ignored
1727 by custom cell renderers.
1728 */
1729 void SetValueImage( wxBitmap& bmp );
1730
1731 /**
1732 Call this function in OnEvent(), OnButtonClick() etc. to change the
1733 property value based on user input.
1734
1735 @remarks This method is const since it doesn't actually modify value, but posts
1736 given variant as pending value, stored in wxPropertyGrid.
1737 */
1738 void SetValueInEvent( wxVariant value ) const;
1739
1740 /**
1741 Sets property's value to unspecified (ie. Null variant).
1742 */
1743 void SetValueToUnspecified();
1744
1745 /**
1746 Call with @false in OnSetValue() to cancel value changes after all
1747 (ie. cancel @true returned by StringToValue() or IntToValue()).
1748 */
1749 void SetWasModified( bool set = true );
1750
1751 /**
1752 Updates composed values of parent non-category properties, recursively.
1753 Returns topmost property updated.
1754 */
1755 wxPGProperty* UpdateParentValues();
1756
1757 /**
1758 Returns @true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
1759 */
1760 bool UsesAutoUnspecified() const;
1761 };
1762
1763
1764 /**
1765 @class wxPGCell
1766
1767 Base class for wxPropertyGrid cell information.
1768
1769 @library{wxpropgrid}
1770 @category{propgrid}
1771 */
1772 class wxPGCell : public wxObject
1773 {
1774 public:
1775 wxPGCell();
1776 wxPGCell(const wxPGCell& other);
1777 wxPGCell( const wxString& text,
1778 const wxBitmap& bitmap = wxNullBitmap,
1779 const wxColour& fgCol = wxNullColour,
1780 const wxColour& bgCol = wxNullColour );
1781
1782 virtual ~wxPGCell();
1783
1784 const wxPGCellData* GetData() const;
1785
1786 /**
1787 Returns @true if this cell has custom text stored within.
1788 */
1789 bool HasText() const;
1790
1791 /**
1792 Merges valid data from srcCell into this.
1793 */
1794 void MergeFrom( const wxPGCell& srcCell );
1795
1796 void SetText( const wxString& text );
1797 void SetBitmap( const wxBitmap& bitmap );
1798 void SetFgCol( const wxColour& col );
1799
1800 /**
1801 Sets font of the cell.
1802
1803 @remarks Because wxPropertyGrid does not support rows of
1804 different height, it makes little sense to change
1805 size of the font. Therefore it is recommended
1806 to use return value of wxPropertyGrid::GetFont()
1807 or wxPropertyGrid::GetCaptionFont() as a basis
1808 for the font that, after modifications, is passed
1809 to this member function.
1810 */
1811 void SetFont( const wxFont& font );
1812
1813 void SetBgCol( const wxColour& col );
1814
1815 const wxString& GetText() const;
1816 const wxBitmap& GetBitmap() const;
1817 const wxColour& GetFgCol() const;
1818
1819 /**
1820 Returns font of the cell. If no specific font is set for this
1821 cell, then the font will be invalid.
1822 */
1823 const wxFont& GetFont() const;
1824
1825 const wxColour& GetBgCol() const;
1826
1827 wxPGCell& operator=( const wxPGCell& other );
1828 };
1829
1830
1831 /**
1832 @class wxPGChoices
1833
1834 Helper class for managing choices of wxPropertyGrid properties.
1835 Each entry can have label, value, bitmap, text colour, and background
1836 colour.
1837
1838 wxPGChoices uses reference counting, similar to other wxWidgets classes.
1839 This means that assignment operator and copy constructor only copy the
1840 reference and not the actual data. Use Copy() member function to create a
1841 real copy.
1842
1843 @remarks If you do not specify value for entry, index is used.
1844
1845 @library{wxpropgrid}
1846 @category{propgrid}
1847 */
1848 class wxPGChoices
1849 {
1850 public:
1851 typedef long ValArrItem;
1852
1853 /**
1854 Default constructor.
1855 */
1856 wxPGChoices();
1857
1858 /**
1859 Copy constructor, uses reference counting. To create a real copy,
1860 use Copy() member function instead.
1861 */
1862 wxPGChoices( const wxPGChoices& a );
1863
1864 /** Constructor. */
1865 wxPGChoices( const wxChar** labels, const long* values = NULL );
1866
1867 /** Constructor. */
1868 wxPGChoices( const wxArrayString& labels, const wxArrayInt& values = wxArrayInt() );
1869
1870 /** Constructor. */
1871 wxPGChoices( wxPGChoicesData* data );
1872
1873 /** Destructor. */
1874 ~wxPGChoices();
1875
1876 /**
1877 Adds to current. If did not have own copies, creates them now. If was empty,
1878 identical to set except that creates copies.
1879 */
1880 void Add( const wxChar** labels, const ValArrItem* values = NULL );
1881
1882 /** Version that works with wxArrayString. */
1883 void Add( const wxArrayString& arr, const ValArrItem* values = NULL );
1884
1885 /** Version that works with wxArrayString and wxArrayInt. */
1886 void Add( const wxArrayString& arr, const wxArrayInt& arrint );
1887
1888 /** Adds single item. */
1889 wxPGChoiceEntry& Add( const wxString& label, int value = wxPG_INVALID_VALUE );
1890
1891 /** Adds a single item, with bitmap. */
1892 wxPGChoiceEntry& Add( const wxString& label, const wxBitmap& bitmap,
1893 int value = wxPG_INVALID_VALUE );
1894
1895 /** Adds a single item with full entry information. */
1896 wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry );
1897
1898 /** Adds single item, sorted. */
1899 wxPGChoiceEntry& AddAsSorted( const wxString& label, int value = wxPG_INVALID_VALUE );
1900
1901 /**
1902 Assigns choices data, using reference counting. To create a real copy,
1903 use Copy() member function instead.
1904 */
1905 void Assign( const wxPGChoices& a );
1906
1907 /**
1908 Assigns data from another set of choices.
1909 */
1910 void AssignData( wxPGChoicesData* data );
1911
1912 /**
1913 Deletes all items.
1914 */
1915 void Clear();
1916
1917 /**
1918 Returns a real copy of the choices.
1919 */
1920 wxPGChoices Copy() const;
1921
1922 /**
1923 Returns label of item.
1924 */
1925 const wxString& GetLabel( unsigned int ind ) const;
1926
1927 /**
1928 Returns number of items.
1929 */
1930 unsigned int GetCount() const;
1931
1932 /**
1933 Returns value of item;
1934 */
1935 int GetValue( unsigned int ind ) const;
1936
1937 /**
1938 Returns array of values matching the given strings. Unmatching strings
1939 result in wxPG_INVALID_VALUE entry in array.
1940 */
1941 wxArrayInt GetValuesForStrings( const wxArrayString& strings ) const;
1942
1943 /**
1944 Returns array of indices matching given strings. Unmatching strings
1945 are added to 'unmatched', if not @NULL.
1946 */
1947 wxArrayInt GetIndicesForStrings( const wxArrayString& strings,
1948 wxArrayString* unmatched = NULL ) const;
1949
1950 /** Returns property at given virtual y coordinate.
1951 */
1952 wxPGProperty* GetItemAtY( unsigned int y ) const;
1953
1954 /**
1955 Returns @true if item at given index has a valid value;
1956 */
1957 bool HasValue( unsigned int i ) const;
1958
1959 /**
1960 Returns index of item with given label.
1961 */
1962 int Index( const wxString& label ) const;
1963
1964 /**
1965 Returns index of item with given value.
1966 */
1967 int Index( int val ) const;
1968
1969 /**
1970 Inserts single item.
1971 */
1972 wxPGChoiceEntry& Insert( const wxString& label, int index, int value = wxPG_INVALID_VALUE );
1973
1974 /**
1975 Inserts a single item with full entry information.
1976 */
1977 wxPGChoiceEntry& Insert( const wxPGChoiceEntry& entry, int index );
1978
1979 /**
1980 Returns @false if this is a constant empty set of choices,
1981 which should not be modified.
1982 */
1983 bool IsOk() const;
1984
1985 /**
1986 Returns item at given index.
1987 */
1988 const wxPGChoiceEntry& Item( unsigned int i ) const;
1989
1990 /**
1991 Returns item at given index.
1992 */
1993 wxPGChoiceEntry& Item( unsigned int i );
1994
1995 /**
1996 Removes count items starting at position nIndex.
1997 */
1998 void RemoveAt(size_t nIndex, size_t count = 1);
1999
2000 /**
2001 Sets contents from lists of strings and values.
2002 */
2003 void Set( const wxChar** labels, const long* values = NULL );
2004
2005 /**
2006 Sets contents from lists of strings and values.
2007 */
2008 void Set( const wxArrayString& labels, const wxArrayInt& values = wxArrayInt() );
2009
2010 /**
2011 Creates exclusive copy of current choices.
2012 */
2013 void AllocExclusive();
2014
2015 /**
2016 Returns array of choice labels.
2017 */
2018 wxArrayString GetLabels() const;
2019
2020 void operator= (const wxPGChoices& a);
2021
2022 wxPGChoiceEntry& operator[](unsigned int i);
2023 const wxPGChoiceEntry& operator[](unsigned int i) const;
2024 };
2025
2026 // -----------------------------------------------------------------------