interface/wx/propgrid/property.h

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