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