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