]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/wx/propgrid/property.h
undo the last change as it results in buildbot configuration error
[wxWidgets.git] / interface / wx / propgrid / property.h
... / ...
CommitLineData
1/////////////////////////////////////////////////////////////////////////////
2// Name: property.h
3// Purpose: interface of wxPGProperty
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
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/** 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
49/** Universal, wxArrayString. Set to enable auto-completion in any
50 wxTextCtrl-based property editor.
51*/
52#define wxPG_ATTR_AUTOCOMPLETE wxS("AutoComplete")
53
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.
61*/
62#define wxPG_BOOL_USE_CHECKBOX wxS("UseCheckbox")
63
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.
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
133 is wxDP_DEFAULT | wxDP_SHOWCENTURY. Using wxDP_ALLOWNONE will enable
134 better unspecified value support in the editor.
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
143/** SpinCtrl editor, bool. If @true, value wraps at Min/Max.
144*/
145#define wxPG_ATTR_SPINCTRL_WRAP wxS("Wrap")
146
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
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
162/** @}
163*/
164
165
166
167/**
168 @class wxPGProperty
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.
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.
214
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.
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).
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
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 "$".
241 Like wxIntProperty, wxUIntProperty seamlessly supports 64-bit unsigned
242 integers (ie. wxULongLong). Same wxVariant safety rules apply.
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
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 {
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
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).
303 Attribute wxPG_FILE_SHOW_FULL_PATH can be set to @false inorder to show
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
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.
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).
335 Using wxDP_ALLOWNONE will enable better unspecified value support.
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.
358 There are various sub-classing opportunities with this class. See
359 below in wxSystemColourProperty section for details.
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
370 is wxColourPropertyValue instead of wxColour (which wxColourProperty
371 uses).
372
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
389
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
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:
431 // All arguments of ctor must have a default value -
432 // use wxPG_LABEL for label and name
433 MyProperty( const wxString& label = wxPG_LABEL,
434 const wxString& name = wxPG_LABEL,
435 const wxString& value = wxEmptyString )
436 {
437 // m_value is wxVariant
438 m_value = value;
439 }
440
441 virtual ~MyProperty() { }
442
443 const wxPGEditor* DoGetEditorClass() const
444 {
445 // Determines editor used by property.
446 // You can replace 'TextCtrl' below with any of these
447 // builtin-in property editor identifiers: Choice, ComboBox,
448 // TextCtrlAndButton, ChoiceAndButton, CheckBox, SpinCtrl,
449 // DatePickerCtrl.
450 return wxPGEditor_TextCtrl;
451 }
452
453 virtual wxString ValueToString( wxVariant& value,
454 int argFlags ) const
455 {
456 // TODO: Convert given property value to a string
457 }
458
459 virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags )
460 {
461 // TODO: Adapt string to property value.
462 }
463
464 protected:
465 };
466 @endcode
467
468 Since wxPGProperty derives from wxObject, you can use standard
469 DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS macros. From the
470 above example they were omitted for sake of simplicity, and besides,
471 they are only really needed if you need to use wxRTTI with your
472 property class.
473
474 You can change the 'value type' of a property by simply assigning different
475 type of variant with SetValue. <b>It is mandatory to implement
476 wxVariantData class for all data types used as property values.</b>
477 You can use macros declared in wxPropertyGrid headers. For instance:
478
479 @code
480 // In header file:
481 // (If you need to have export declaration, use version of macros
482 // with _EXPORTED postfix)
483 WX_PG_DECLARE_VARIANT_DATA(MyDataClass)
484
485 // In sources file:
486 WX_PG_IMPLEMENT_VARIANT_DATA(MyDataClass)
487
488 // Or, if you don't have valid == operator:
489 WX_PG_IMPLEMENT_VARIANT_DATA_DUMMY_EQ(MyDataClass)
490 @endcode
491
492 @library{wxpropgrid}
493 @category{propgrid}
494*/
495class wxPGProperty : public wxObject
496{
497public:
498 typedef wxUint32 FlagType;
499
500 /**
501 Default constructor.
502 */
503 wxPGProperty();
504
505 /**
506 Constructor.
507 Non-abstract property classes should have constructor of this style:
508
509 @code
510
511 MyProperty( const wxString& label, const wxString& name, const T& value )
512 : wxPGProperty()
513 {
514 // Generally recommended way to set the initial value
515 // (as it should work in pretty much 100% of cases).
516 wxVariant variant;
517 variant << value;
518 SetValue(variant);
519
520 // If has private child properties then create them here.
521 // For example:
522 // AddPrivateChild( new wxStringProperty("Subprop 1",
523 // wxPG_LABEL,
524 // value.GetSubProp1()));
525 }
526
527 @endcode
528 */
529 wxPGProperty( const wxString& label, const wxString& name );
530
531 /**
532 Virtual destructor. It is customary for derived properties to implement this.
533 */
534 virtual ~wxPGProperty();
535
536 /**
537 This virtual function is called after m_value has been set.
538
539 @remarks
540 - If m_value was set to Null variant (ie. unspecified value), OnSetValue()
541 will not be called.
542 - m_value may be of any variant type. Typically properties internally support only
543 one variant type, and as such OnSetValue() provides a good opportunity to convert
544 supported values into internal type.
545 - Default implementation does nothing.
546 */
547 virtual void OnSetValue();
548
549 /**
550 Override this to return something else than m_value as the value.
551 */
552 virtual wxVariant DoGetValue() const;
553
554 /**
555 Implement this function in derived class to check the value.
556 Return @true if it is ok. Returning @false prevents property change events
557 from occurring.
558
559 @remarks
560 - Default implementation always returns @true.
561 */
562 virtual bool ValidateValue( wxVariant& value, wxPGValidationInfo& validationInfo ) const;
563
564 /**
565 Converts text into wxVariant value appropriate for this property.
566
567 @param variant
568 On function entry this is the old value (should not be wxNullVariant
569 in normal cases). Translated value must be assigned back to it.
570
571 @param text
572 Text to be translated into variant.
573
574 @param argFlags
575 If wxPG_FULL_VALUE is set, returns complete, storable value instead
576 of displayable one (they may be different).
577 If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
578 composite property string value (as generated by ValueToString()
579 called with this same flag).
580
581 @return Returns @true if resulting wxVariant value was different.
582
583 @remarks Default implementation converts semicolon delimited tokens into
584 child values. Only works for properties with children.
585
586 You might want to take into account that m_value is Null variant
587 if property value is unspecified (which is usually only case if
588 you explicitly enabled that sort behavior).
589 */
590 virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags = 0 ) const;
591
592 /**
593 Converts integer (possibly a choice selection) into wxVariant value
594 appropriate for this property.
595
596 @param variant
597 On function entry this is the old value (should not be wxNullVariant
598 in normal cases). Translated value must be assigned back to it.
599 @param number
600 Integer to be translated into variant.
601 @param argFlags
602 If wxPG_FULL_VALUE is set, returns complete, storable value instead
603 of displayable one.
604
605 @return Returns @true if resulting wxVariant value was different.
606
607 @remarks
608 - If property is not supposed to use choice or spinctrl or other editor
609 with int-based value, it is not necessary to implement this method.
610 - Default implementation simply assign given int to m_value.
611 - If property uses choice control, and displays a dialog on some choice
612 items, then it is preferred to display that dialog in IntToValue
613 instead of OnEvent.
614 - You might want to take into account that m_value is Mull variant if
615 property value is unspecified (which is usually only case if you
616 explicitly enabled that sort behavior).
617 */
618 virtual bool IntToValue( wxVariant& variant, int number, int argFlags = 0 ) const;
619
620 /**
621 Converts property value into a text representation.
622
623 @param value
624 Value to be converted.
625 @param argFlags
626 If 0 (default value), then displayed string is returned.
627 If wxPG_FULL_VALUE is set, returns complete, storable string value
628 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
629 string value that must be editable in textctrl.
630 If wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
631 display as a part of string property's composite text representation.
632
633 @remarks Default implementation calls GenerateComposedValue().
634 */
635 virtual wxString ValueToString( wxVariant& value, int argFlags = 0 ) const;
636
637 /**
638 Converts string to a value, and if successful, calls SetValue() on it.
639 Default behavior is to do nothing.
640
641 @param text
642 String to get the value from.
643 @param flags
644 @todo docme
645
646 @return @true if value was changed.
647 */
648 bool SetValueFromString( const wxString& text, int flags = 0 );
649
650 /**
651 Converts integer to a value, and if succesful, calls SetValue() on it.
652 Default behavior is to do nothing.
653
654 @param value
655 Int to get the value from.
656 @param flags
657 If has wxPG_FULL_VALUE, then the value given is a actual value and not an index.
658
659 @return @true if value was changed.
660 */
661 bool SetValueFromInt( long value, int flags = 0 );
662
663 /**
664 Returns size of the custom painted image in front of property. This method
665 must be overridden to return non-default value if OnCustomPaint is to be
666 called.
667
668 @param item
669 Normally -1, but can be an index to the property's list of items.
670
671 @remarks
672 - Default behavior is to return wxSize(0,0), which means no image.
673 - Default image width or height is indicated with dimension -1.
674 - You can also return wxPG_DEFAULT_IMAGE_SIZE which equals wxSize(-1, -1).
675 */
676 virtual wxSize OnMeasureImage( int item = -1 ) const;
677
678 /**
679 Events received by editor widgets are processed here. Note that editor class
680 usually processes most events. Some, such as button press events of
681 TextCtrlAndButton class, can be handled here. Also, if custom handling
682 for regular events is desired, then that can also be done (for example,
683 wxSystemColourProperty custom handles wxEVT_COMMAND_CHOICE_SELECTED
684 to display colour picker dialog when 'custom' selection is made).
685
686 If the event causes value to be changed, SetValueInEvent() should be called
687 to set the new value.
688
689 The parameter @a event is the associated wxEvent.
690
691 @retval
692 Should return @true if any changes in value should be reported.
693
694 @remarks
695 - If property uses choice control, and displays a dialog on some choice items,
696 then it is preferred to display that dialog in IntToValue instead of OnEvent.
697 */
698 virtual bool OnEvent( wxPropertyGrid* propgrid, wxWindow* wnd_primary, wxEvent& event );
699
700 /**
701 Called after value of a child property has been altered. Note that this function is
702 usually called at the time that value of this property, or given child property, is
703 still pending for change.
704
705 Sample pseudo-code implementation:
706
707 @code
708 void MyProperty::ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const
709 {
710 // Acquire reference to actual type of data stored in variant
711 // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros were used to create
712 // the variant class).
713 T& data = TFromVariant(thisValue);
714
715 // Copy childValue into data.
716 switch ( childIndex )
717 {
718 case 0:
719 data.SetSubProp1( childvalue.GetLong() );
720 break;
721 case 1:
722 data.SetSubProp2( childvalue.GetString() );
723 break;
724 ...
725 }
726 }
727 @endcode
728
729 @param thisValue
730 Value of this property, that should be altered.
731 @param childIndex
732 Index of child changed (you can use Item(childIndex) to get).
733 @param childValue
734 Value of the child property.
735 */
736 virtual void ChildChanged( wxVariant& thisValue, int childIndex, wxVariant& childValue ) const;
737
738 /**
739 Returns pointer to an instance of used editor.
740 */
741 virtual const wxPGEditor* DoGetEditorClass() const;
742
743 /**
744 Returns pointer to the wxValidator that should be used
745 with the editor of this property (@NULL for no validator).
746 Setting validator explicitly via SetPropertyValidator
747 will override this.
748
749 In most situations, code like this should work well
750 (macros are used to maintain one actual validator instance,
751 so on the second call the function exits within the first
752 macro):
753
754 @code
755
756 wxValidator* wxMyPropertyClass::DoGetValidator () const
757 {
758 WX_PG_DOGETVALIDATOR_ENTRY()
759
760 wxMyValidator* validator = new wxMyValidator(...);
761
762 ... prepare validator...
763
764 WX_PG_DOGETVALIDATOR_EXIT(validator)
765 }
766
767 @endcode
768
769 @remarks
770 You can get common filename validator by returning
771 wxFileProperty::GetClassValidator(). wxDirProperty,
772 for example, uses it.
773 */
774 virtual wxValidator* DoGetValidator () const;
775
776 /**
777 Override to paint an image in front of the property value text or drop-down
778 list item (but only if wxPGProperty::OnMeasureImage is overridden as well).
779
780 If property's OnMeasureImage() returns size that has height != 0 but less than
781 row height ( < 0 has special meanings), wxPropertyGrid calls this method to
782 draw a custom image in a limited area in front of the editor control or
783 value text/graphics, and if control has drop-down list, then the image is
784 drawn there as well (even in the case OnMeasureImage() returned higher height
785 than row height).
786
787 NOTE: Following applies when OnMeasureImage() returns a "flexible" height (
788 using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable height items:
789 If rect.x is < 0, then this is a measure item call, which means that
790 dc is invalid and only thing that should be done is to set paintdata.m_drawnHeight
791 to the height of the image of item at index paintdata.m_choiceItem. This call
792 may be done even as often as once every drop-down popup show.
793
794 @param dc
795 wxDC to paint on.
796 @param rect
797 Box reserved for custom graphics. Includes surrounding rectangle, if any.
798 If x is < 0, then this is a measure item call (see above).
799 @param paintdata
800 wxPGPaintData structure with much useful data about painted item.
801 @code
802 struct wxPGPaintData
803 {
804 // wxPropertyGrid.
805 const wxPropertyGrid* m_parent;
806
807 // Normally -1, otherwise index to drop-down list item that has to be drawn.
808 int m_choiceItem;
809
810 // Set to drawn width in OnCustomPaint (optional).
811 int m_drawnWidth;
812
813 // In a measure item call, set this to the height of item at m_choiceItem index
814 int m_drawnHeight;
815 };
816 @endcode
817
818 @remarks
819 - You can actually exceed rect width, but if you do so then paintdata.m_drawnWidth
820 must be set to the full width drawn in pixels.
821 - Due to technical reasons, rect's height will be default even if custom height
822 was reported during measure call.
823 - Brush is guaranteed to be default background colour. It has been already used to
824 clear the background of area being painted. It can be modified.
825 - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper colour) pen for
826 drawing framing rectangle. It can be changed as well.
827
828 @see ValueToString()
829 */
830 virtual void OnCustomPaint( wxDC& dc, const wxRect& rect, wxPGPaintData& paintdata );
831
832 /**
833 Returns used wxPGCellRenderer instance for given property column (label=0, value=1).
834
835 Default implementation returns editor's renderer for all columns.
836 */
837 virtual wxPGCellRenderer* GetCellRenderer( int column ) const;
838
839 /**
840 Returns which choice is currently selected. Only applies to properties
841 which have choices.
842
843 Needs to reimplemented in derived class if property value does not
844 map directly to a choice. Integer as index, bool, and string usually do.
845 */
846 virtual int GetChoiceSelection() const;
847
848 /**
849 Refresh values of child properties. Automatically called after value is set.
850 */
851 virtual void RefreshChildren();
852
853 /**
854 Special handling for attributes of this property.
855
856 If returns @false, then the attribute will be automatically stored in
857 m_attributes.
858
859 Default implementation simply returns @false.
860 */
861 virtual bool DoSetAttribute( const wxString& name, wxVariant& value );
862
863 /**
864 Returns value of an attribute.
865
866 Override if custom handling of attributes is needed.
867
868 Default implementation simply return @NULL variant.
869 */
870 virtual wxVariant DoGetAttribute( const wxString& name ) const;
871
872 /**
873 Returns instance of a new wxPGEditorDialogAdapter instance, which is
874 used when user presses the (optional) button next to the editor control;
875
876 Default implementation returns @NULL (ie. no action is generated when
877 button is pressed).
878 */
879 virtual wxPGEditorDialogAdapter* GetEditorDialog() const;
880
881 /**
882 Called whenever validation has failed with given pending value.
883
884 @remarks If you implement this in your custom property class, please
885 remember to call the baser implementation as well, since they
886 may use it to revert property into pre-change state.
887 */
888 virtual void OnValidationFailure( wxVariant& pendingValue );
889
890 /**
891 Append a new choice to property's list of choices.
892
893 @param label
894 Label for added choice.
895
896 @param value
897 Value for new choice. Do not specify if you wish this
898 to equal choice index.
899
900 @return
901 Index to added choice.
902 */
903 int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE );
904
905 /**
906 Adds a private child property.
907
908 @deprecated Use AddPrivateChild() instead.
909
910 @see AddPrivateChild()
911 */
912 wxDEPRECATED( void AddChild( wxPGProperty* prop ) );
913
914 /**
915 Adds a private child property. If you use this instead of
916 wxPropertyGridInterface::Insert() or
917 wxPropertyGridInterface::AppendIn(), then property's parental
918 type will automatically be set up to wxPG_PROP_AGGREGATE. In other
919 words, all properties of this property will become private.
920 */
921 void AddPrivateChild( wxPGProperty* prop );
922
923 /**
924 Adapts list variant into proper value using consecutive
925 ChildChanged() calls.
926 */
927 void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
928
929 /**
930 Use this member function to add independent (ie. regular) children to
931 a property.
932
933 @return Appended childProperty.
934
935 @remarks wxPropertyGrid is not automatically refreshed by this
936 function.
937
938 @see InsertChild(), AddPrivateChild()
939 */
940 wxPGProperty* AppendChild( wxPGProperty* childProperty );
941
942 /**
943 Determines, recursively, if all children are not unspecified.
944
945 @param pendingList
946 Assumes members in this wxVariant list as pending
947 replacement values.
948 */
949 bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const;
950
951 /**
952 Returns @true if children of this property are component values (for instance,
953 points size, face name, and is_underlined are component values of a font).
954 */
955 bool AreChildrenComponents() const;
956
957 /**
958 Deletes children of the property.
959 */
960 void DeleteChildren();
961
962 /**
963 Removes entry from property's wxPGChoices and editor control (if it is active).
964
965 If selected item is deleted, then the value is set to unspecified.
966 */
967 void DeleteChoice( int index );
968
969 /** Deletes all child properties. */
970 void Empty();
971
972 /**
973 Composes text from values of child properties.
974 */
975 wxString GenerateComposedValue() const;
976
977 /**
978 Returns property attribute value, null variant if not found.
979 */
980 wxVariant GetAttribute( const wxString& name ) const;
981
982 /** Returns named attribute, as string, if found. Otherwise defVal is returned.
983 */
984 wxString GetAttribute( const wxString& name, const wxString& defVal ) const;
985
986 /** Returns named attribute, as long, if found. Otherwise defVal is returned.
987 */
988 long GetAttributeAsLong( const wxString& name, long defVal ) const;
989
990 /** Returns named attribute, as double, if found. Otherwise defVal is returned.
991 */
992 double GetAttributeAsDouble( const wxString& name, double defVal ) const;
993
994 /**
995 Returns attributes as list wxVariant.
996 */
997 wxVariant GetAttributesAsList() const;
998
999 /**
1000 Returns editor used for given column. @NULL for no editor.
1001 */
1002 const wxPGEditor* GetColumnEditor( int column ) const;
1003
1004 /** Returns property's base name (ie. parent's name is not added in any case) */
1005 const wxString& GetBaseName() const;
1006
1007 /**
1008 Returns wxPGCell of given column.
1009 */
1010 const wxPGCell& GetCell( unsigned int column ) const;
1011
1012 /**
1013 Returns number of child properties.
1014 */
1015 unsigned int GetChildCount() const;
1016
1017 /**
1018 Returns height of children, recursively, and
1019 by taking expanded/collapsed status into account.
1020
1021 @param lh
1022 Line height. Pass result of GetGrid()->GetRowHeight() here.
1023
1024 @param iMax
1025 Only used (internally) when finding property y-positions.
1026 */
1027 int GetChildrenHeight( int lh, int iMax = -1 ) const;
1028
1029 /**
1030 Returns read-only reference to property's list of choices.
1031 */
1032 const wxPGChoices& GetChoices() const;
1033
1034 /**
1035 Returns client data (void*) of a property.
1036 */
1037 void* GetClientData() const;
1038
1039 /** Sets managed client object of a property.
1040 */
1041 wxClientData *GetClientObject() const;
1042
1043 /**
1044 Returns property's default value. If property's value type is not
1045 a built-in one, and "DefaultValue" attribute is not defined, then
1046 this function usually returns Null variant.
1047 */
1048 wxVariant GetDefaultValue() const;
1049
1050 /** Returns property's displayed text.
1051 */
1052 wxString GetDisplayedString() const;
1053
1054 /**
1055 Returns wxPGEditor that will be used and created when
1056 property becomes selected. Returns more accurate value
1057 than DoGetEditorClass().
1058 */
1059 const wxPGEditor* GetEditorClass() const;
1060
1061 /** Returns property grid where property lies. */
1062 wxPropertyGrid* GetGrid() const;
1063
1064 /**
1065 Returns owner wxPropertyGrid, but only if one is currently on a page
1066 displaying this property.
1067 */
1068 wxPropertyGrid* GetGridIfDisplayed() const;
1069
1070 /**
1071 Returns property's help or description text.
1072
1073 @see SetHelpString()
1074 */
1075 const wxString& GetHelpString() const;
1076
1077 /**
1078 Returns position in parent's array.
1079 */
1080 unsigned int GetIndexInParent() const;
1081
1082 /** Returns property's label. */
1083 const wxString& GetLabel() const;
1084
1085 /**
1086 Returns last visible child property, recursively.
1087 */
1088 const wxPGProperty* GetLastVisibleSubItem() const;
1089
1090 /**
1091 Returns highest level non-category, non-root parent. Useful when you
1092 have nested properties with children.
1093
1094 @remarks If immediate parent is root or category, this will return the
1095 property itself.
1096 */
1097 wxPGProperty* GetMainParent() const;
1098
1099 /** Returns maximum allowed length of property's text value.
1100 */
1101 int GetMaxLength() const;
1102
1103 /** Returns property's name with all (non-category, non-root) parents. */
1104 wxString GetName() const;
1105
1106 /** Return parent of property */
1107 wxPGProperty* GetParent() const;
1108
1109 /**
1110 Returns (direct) child property with given name (or @NULL if not found).
1111 */
1112 wxPGProperty* GetPropertyByName( const wxString& name ) const;
1113
1114 /** Gets assignable version of property's validator. */
1115 wxValidator* GetValidator() const;
1116
1117 /**
1118 Returns property's value.
1119 */
1120 wxVariant GetValue() const;
1121
1122 /**
1123 Returns bitmap that appears next to value text. Only returns non-@NULL
1124 bitmap if one was set with SetValueImage().
1125 */
1126 wxBitmap* GetValueImage() const;
1127
1128 /** Returns text representation of property's value.
1129
1130 @param argFlags
1131 If 0 (default value), then displayed string is returned.
1132 If wxPG_FULL_VALUE is set, returns complete, storable string value
1133 instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
1134 string value that must be editable in textctrl. If
1135 wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
1136 display as a part of string property's composite text
1137 representation.
1138
1139 @remarks In older versions, this function used to be overridden to convert
1140 property's value into a string representation. This function is
1141 now handled by ValueToString(), and overriding this function now
1142 will result in run-time assertion failure.
1143 */
1144 virtual wxString GetValueAsString( int argFlags = 0 ) const;
1145
1146 /** Synonymous to GetValueAsString().
1147
1148 @deprecated Use GetValueAsString() instead.
1149
1150 @see GetValueAsString()
1151 */
1152 wxDEPRECATED( wxString GetValueString( int argFlags = 0 ) const );
1153
1154 /**
1155 Returns value type used by this property.
1156 */
1157 wxString GetValueType() const;
1158
1159 /**
1160 Returns coordinate to the top y of the property. Note that the
1161 position of scrollbars is not taken into account.
1162 */
1163 int GetY() const;
1164
1165 /**
1166 Returns @true if property has even one visible child.
1167 */
1168 bool HasVisibleChildren() const;
1169
1170 /**
1171 Hides or reveals the property.
1172
1173 @param hide
1174 @true for hide, @false for reveal.
1175
1176 @param flags
1177 By default changes are applied recursively. Set this parameter wxPG_DONT_RECURSE to prevent this.
1178 */
1179 bool Hide( bool hide, int flags = wxPG_RECURSE );
1180
1181 /**
1182 Returns index of given child property. wxNOT_FOUND if
1183 given property is not child of this.
1184 */
1185 int Index( const wxPGProperty* p ) const;
1186
1187 /**
1188 Use this member function to add independent (ie. regular) children to
1189 a property.
1190
1191 @return Inserted childProperty.
1192
1193 @remarks wxPropertyGrid is not automatically refreshed by this
1194 function.
1195
1196 @see AppendChild(), AddPrivateChild()
1197 */
1198 wxPGProperty* InsertChild( int index, wxPGProperty* childProperty );
1199
1200 /**
1201 Inserts a new choice to property's list of choices.
1202
1203 @param label
1204 Text for new choice
1205
1206 @param index
1207 Insertion position. Use wxNOT_FOUND to append.
1208
1209 @param value
1210 Value for new choice. Do not specify if you wish this
1211 to equal choice index.
1212 */
1213 int InsertChoice( const wxString& label, int index, int value = wxPG_INVALID_VALUE );
1214
1215 /**
1216 Returns @true if this property is actually a wxPropertyCategory.
1217 */
1218 bool IsCategory() const;
1219
1220 /**
1221 Returns @true if property is enabled.
1222 */
1223 bool IsEnabled() const;
1224
1225 /**
1226 Returns @true if property has visible children.
1227 */
1228 bool IsExpanded() const;
1229
1230 /**
1231 Returns @true if this property is actually a wxRootProperty.
1232 */
1233 bool IsRoot() const;
1234
1235 /**
1236 Returns @true if candidateParent is some parent of this property.
1237 */
1238 bool IsSomeParent( wxPGProperty* candidateParent ) const;
1239
1240 /**
1241 Returns true if property has editable wxTextCtrl when selected.
1242
1243 @remarks Altough disabled properties do not displayed editor, they still
1244 return @true here as being disabled is considered a temporary
1245 condition (unlike being read-only or having limited editing enabled).
1246 */
1247 bool IsTextEditable() const;
1248
1249 /**
1250 Returns @true if property's value is considered unspecified. This
1251 usually means that value is Null variant.
1252 */
1253 bool IsValueUnspecified() const;
1254
1255 /**
1256 Returns true if all parents expanded.
1257 */
1258 bool IsVisible() const;
1259
1260 /**
1261 Returns child property at index i.
1262 */
1263 wxPGProperty* Item( unsigned int i ) const;
1264
1265 /**
1266 If property's editor is active, then update it's value.
1267 */
1268 void RefreshEditor();
1269
1270 /**
1271 Sets an attribute for this property.
1272
1273 @param name
1274 Text identifier of attribute. See @ref propgrid_property_attributes.
1275
1276 @param value
1277 Value of attribute.
1278
1279 @remarks Setting attribute's value to Null variant will simply remove it
1280 from property's set of attributes.
1281 */
1282 void SetAttribute( const wxString& name, wxVariant value );
1283
1284 /**
1285 Sets property's background colour.
1286
1287 @param colour
1288 Background colour to use.
1289
1290 @param recursively
1291 If @true, children are affected recursively, and any categories
1292 are not.
1293 */
1294 void SetBackgroundColour( const wxColour& colour,
1295 bool recursively = false );
1296
1297 /**
1298 Sets editor for a property.
1299
1300 @param editor
1301 For builtin editors, use wxPGEditor_X, where X is builtin editor's
1302 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list).
1303
1304 For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
1305 */
1306 void SetEditor( const wxPGEditor* editor );
1307
1308 /**
1309 Sets editor for a property, by editor name.
1310 */
1311 void SetEditor( const wxString& editorName );
1312
1313 /**
1314 Sets cell information for given column.
1315 */
1316 void SetCell( int column, const wxPGCell& cell );
1317
1318 /**
1319 Sets new set of choices for property.
1320
1321 @remarks This operation clears the property value.
1322 */
1323 bool SetChoices( wxPGChoices& choices );
1324
1325 /**
1326 Sets client data (void*) of a property.
1327
1328 @remarks This untyped client data has to be deleted manually.
1329 */
1330 void SetClientData( void* clientData );
1331
1332 /** Returns client object of a property.
1333 */
1334 void SetClientObject(wxClientData* clientObject);
1335
1336 /**
1337 Sets selected choice and changes property value.
1338
1339 Tries to retain value type, although currently if it is not string,
1340 then it is forced to integer.
1341 */
1342 void SetChoiceSelection( int newValue );
1343
1344 /**
1345 Sets property's help string, which is shown, for example, in
1346 wxPropertyGridManager's description text box.
1347 */
1348 void SetHelpString( const wxString& helpString );
1349
1350 /**
1351 Sets property's label.
1352
1353 @remarks Properties under same parent may have same labels. However,
1354 property names must still remain unique.
1355 */
1356 void SetLabel( const wxString& label );
1357
1358 /**
1359 Set max length of text in text editor.
1360 */
1361 bool SetMaxLength( int maxLen );
1362
1363 /**
1364 Sets property's "is it modified?" flag. Affects children recursively.
1365 */
1366 void SetModifiedStatus( bool modified );
1367
1368 /**
1369 Sets new (base) name for property.
1370 */
1371 void SetName( const wxString& newName );
1372
1373 /**
1374 Changes what sort of parent this property is for its children.
1375
1376 @param flag
1377 Use one of the following values: wxPG_PROP_MISC_PARENT (for generic
1378 parents), wxPG_PROP_CATEGORY (for categories), or
1379 wxPG_PROP_AGGREGATE (for derived property classes with private
1380 children).
1381
1382 @remarks You generally do not need to call this function.
1383 */
1384 void SetParentalType( int flag );
1385
1386 /**
1387 Sets property's text colour.
1388
1389 @param colour
1390 Text colour to use.
1391
1392 @param recursively
1393 If @true, children are affected recursively, and any categories
1394 are not.
1395 */
1396 void SetTextColour( const wxColour& colour,
1397 bool recursively = false );
1398
1399 /** Sets wxValidator for a property */
1400 void SetValidator( const wxValidator& validator );
1401
1402 /**
1403 Call this to set value of the property. Unlike methods in wxPropertyGrid,
1404 this does not automatically update the display.
1405
1406 @remarks
1407 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through
1408 validation process and send property change event.
1409
1410 If you need to change property value in event, based on user input, use
1411 SetValueInEvent() instead.
1412
1413 @param value
1414 The value to set.
1415 @param pList
1416 Pointer to list variant that contains child values. Used to indicate
1417 which children should be marked as modified. Usually you just use @NULL.
1418 @param flags
1419 wxPG_SETVAL_REFRESH_EDITOR is set by default, to refresh editor
1420 and redraw properties.
1421 */
1422 void SetValue( wxVariant value, wxVariant* pList = NULL,
1423 int flags = wxPG_SETVAL_REFRESH_EDITOR );
1424
1425 /**
1426 Set wxBitmap in front of the value. This bitmap may be ignored
1427 by custom cell renderers.
1428 */
1429 void SetValueImage( wxBitmap& bmp );
1430
1431 /**
1432 Call this function in OnEvent(), OnButtonClick() etc. to change the
1433 property value based on user input.
1434
1435 @remarks This method is const since it doesn't actually modify value, but posts
1436 given variant as pending value, stored in wxPropertyGrid.
1437 */
1438 void SetValueInEvent( wxVariant value ) const;
1439
1440 /**
1441 Sets property's value to unspecified (ie. Null variant).
1442 */
1443 void SetValueToUnspecified();
1444
1445 /**
1446 Call with @false in OnSetValue() to cancel value changes after all
1447 (ie. cancel @true returned by StringToValue() or IntToValue()).
1448 */
1449 void SetWasModified( bool set = true );
1450
1451 /**
1452 Updates composed values of parent non-category properties, recursively.
1453 Returns topmost property updated.
1454 */
1455 wxPGProperty* UpdateParentValues();
1456
1457 /**
1458 Returns @true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
1459 */
1460 bool UsesAutoUnspecified() const;
1461};
1462
1463
1464/**
1465 @class wxPGChoices
1466
1467 Helper class for managing choices of wxPropertyGrid properties.
1468 Each entry can have label, value, bitmap, text colour, and background
1469 colour.
1470
1471 wxPGChoices uses reference counting, similar to other wxWidgets classes.
1472 This means that assignment operator and copy constructor only copy the
1473 reference and not the actual data. Use Copy() member function to create a
1474 real copy.
1475
1476 @remarks If you do not specify value for entry, index is used.
1477
1478 @library{wxpropgrid}
1479 @category{propgrid}
1480*/
1481class WXDLLIMPEXP_PROPGRID wxPGChoices
1482{
1483public:
1484 typedef long ValArrItem;
1485
1486 /**
1487 Default constructor.
1488 */
1489 wxPGChoices();
1490
1491 /**
1492 Copy constructor, uses reference counting. To create a real copy,
1493 use Copy() member function instead.
1494 */
1495 wxPGChoices( const wxPGChoices& a );
1496
1497 /** Constructor. */
1498 wxPGChoices( const wxChar** labels, const long* values = NULL );
1499
1500 /** Constructor. */
1501 wxPGChoices( const wxArrayString& labels, const wxArrayInt& values = wxArrayInt() );
1502
1503 /** Constructor. */
1504 wxPGChoices( wxPGChoicesData* data );
1505
1506 /** Destructor. */
1507 ~wxPGChoices();
1508
1509 /**
1510 Adds to current. If did not have own copies, creates them now. If was empty,
1511 identical to set except that creates copies.
1512 */
1513 void Add( const wxChar** labels, const ValArrItem* values = NULL );
1514
1515 /** Version that works with wxArrayString. */
1516 void Add( const wxArrayString& arr, const ValArrItem* values = NULL );
1517
1518 /** Version that works with wxArrayString and wxArrayInt. */
1519 void Add( const wxArrayString& arr, const wxArrayInt& arrint );
1520
1521 /** Adds single item. */
1522 wxPGChoiceEntry& Add( const wxString& label, int value = wxPG_INVALID_VALUE );
1523
1524 /** Adds a single item, with bitmap. */
1525 wxPGChoiceEntry& Add( const wxString& label, const wxBitmap& bitmap,
1526 int value = wxPG_INVALID_VALUE );
1527
1528 /** Adds a single item with full entry information. */
1529 wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry );
1530
1531 /** Adds single item, sorted. */
1532 wxPGChoiceEntry& AddAsSorted( const wxString& label, int value = wxPG_INVALID_VALUE );
1533
1534 /**
1535 Assigns choices data, using reference counting. To create a real copy,
1536 use Copy() member function instead.
1537 */
1538 void Assign( const wxPGChoices& a );
1539
1540 /**
1541 Assigns data from another set of choices.
1542 */
1543 void AssignData( wxPGChoicesData* data );
1544
1545 /**
1546 Deletes all items.
1547 */
1548 void Clear();
1549
1550 /**
1551 Returns a real copy of the choices.
1552 */
1553 wxPGChoices Copy() const;
1554
1555 /**
1556 Returns labe of item.
1557 */
1558 const wxString& GetLabel( unsigned int ind ) const;
1559
1560 /**
1561 Returns number of items.
1562 */
1563 unsigned int GetCount() const;
1564
1565 /**
1566 Returns value of item;
1567 */
1568 int GetValue( unsigned int ind ) const;
1569
1570 /**
1571 Returns array of values matching the given strings. Unmatching strings
1572 result in wxPG_INVALID_VALUE entry in array.
1573 */
1574 wxArrayInt GetValuesForStrings( const wxArrayString& strings ) const;
1575
1576 /**
1577 Returns array of indices matching given strings. Unmatching strings
1578 are added to 'unmatched', if not @NULL.
1579 */
1580 wxArrayInt GetIndicesForStrings( const wxArrayString& strings,
1581 wxArrayString* unmatched = NULL ) const;
1582
1583 /**
1584 Returns @true if item at given index has a valid value;
1585 */
1586 bool HasValue( unsigned int i ) const;
1587
1588 /**
1589 Returns index of item with given label.
1590 */
1591 int Index( const wxString& label ) const;
1592
1593 /**
1594 Returns index of item with given value.
1595 */
1596 int Index( int val ) const;
1597
1598 /**
1599 Inserts single item.
1600 */
1601 wxPGChoiceEntry& Insert( const wxString& label, int index, int value = wxPG_INVALID_VALUE );
1602
1603 /**
1604 Inserts a single item with full entry information.
1605 */
1606 wxPGChoiceEntry& Insert( const wxPGChoiceEntry& entry, int index );
1607
1608 /**
1609 Returns @false if this is a constant empty set of choices,
1610 which should not be modified.
1611 */
1612 bool IsOk() const;
1613
1614 /**
1615 Returns item at given index.
1616 */
1617 const wxPGChoiceEntry& Item( unsigned int i ) const;
1618
1619 /**
1620 Returns item at given index.
1621 */
1622 wxPGChoiceEntry& Item( unsigned int i );
1623
1624 /**
1625 Removes count items starting at position nIndex.
1626 */
1627 void RemoveAt(size_t nIndex, size_t count = 1);
1628
1629 /**
1630 Sets contents from lists of strings and values.
1631 */
1632 void Set( const wxChar** labels, const long* values = NULL );
1633
1634 /**
1635 Sets contents from lists of strings and values.
1636 */
1637 void Set( const wxArrayString& labels, const wxArrayInt& values = wxArrayInt() );
1638
1639 /**
1640 Creates exclusive copy of current choices.
1641 */
1642 void AllocExclusive();
1643
1644 /**
1645 Returns array of choice labels.
1646 */
1647 wxArrayString GetLabels() const;
1648
1649 void operator= (const wxPGChoices& a);
1650
1651 wxPGChoiceEntry& operator[](unsigned int i);
1652 const wxPGChoiceEntry& operator[](unsigned int i) const;
1653};
1654
1655// -----------------------------------------------------------------------