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         Called whenever validation has failed with given pending value.
 857
 858         @remarks If you implement this in your custom property class, please
 859                  remember to call the baser implementation as well, since they
 860                  may use it to revert property into pre-change state.
 861     */
 862     virtual void OnValidationFailure( wxVariant& pendingValue );
 863
 864     /**
 865         Append a new choice to property's list of choices.
 866
 867         @param label
 868             Label for added choice.
 869
 870         @param value
 871             Value for new choice. Do not specify if you wish this
 872             to equal choice index.
 873
 874         @return
 875             Index to added choice.
 876     */
 877     int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE );
 878
 879     /**
 880         Adds a child property. If you use this instead of
 881         wxPropertyGridInterface::Insert() or
 882         wxPropertyGridInterface::AppendIn(), then you must set up
 883         property's parental type before making the call. To do this,
 884         call property's SetParentalType() function with either
 885         wxPG_PROP_MISC_PARENT (normal, public children) or with
 886         wxPG_PROP_AGGREGATE (private children for subclassed property).
 887         For instance:
 888
 889         @code
 890             wxPGProperty* prop = new wxStringProperty(wxS("Property"));
 891             prop->SetParentalType(wxPG_PROP_MISC_PARENT);
 892             wxPGProperty* prop2 = new wxStringProperty(wxS("Property2"));
 893             prop->AddChild(prop2);
 894         @endcode
 895     */
 896     void AddChild( wxPGProperty* property );
 897
 898     /**
 899         Adapts list variant into proper value using consecutive
 900         ChildChanged() calls.
 901     */
 902     void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
 903
 904     /**
 905         Determines, recursively, if all children are not unspecified.
 906
 907         @param pendingList
 908             Assumes members in this wxVariant list as pending
 909             replacement values.
 910     */
 911     bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const;
 912
 913     /**
 914         Returns @true if children of this property are component values (for instance,
 915         points size, face name, and is_underlined are component values of a font).
 916     */
 917     bool AreChildrenComponents() const;
 918
 919     /**
 920         Deletes children of the property.
 921     */
 922     void DeleteChildren();
 923
 924     /**
 925         Removes entry from property's wxPGChoices and editor control (if it is active).
 926
 927         If selected item is deleted, then the value is set to unspecified.
 928     */
 929     void DeleteChoice( int index );
 930
 931     /** Deletes all child properties. */
 932     void Empty();
 933
 934     /**
 935         Composes text from values of child properties.
 936     */
 937     wxString GenerateComposedValue() const;
 938
 939     /**
 940         Returns property attribute value, null variant if not found.
 941     */
 942     wxVariant GetAttribute( const wxString& name ) const;
 943
 944     /** Returns named attribute, as string, if found. Otherwise defVal is returned.
 945     */
 946     wxString GetAttribute( const wxString& name, const wxString& defVal ) const;
 947
 948     /** Returns named attribute, as long, if found. Otherwise defVal is returned.
 949     */
 950     long GetAttributeAsLong( const wxString& name, long defVal ) const;
 951
 952     /** Returns named attribute, as double, if found. Otherwise defVal is returned.
 953     */
 954     double GetAttributeAsDouble( const wxString& name, double defVal ) const;
 955
 956     /**
 957         Returns attributes as list wxVariant.
 958     */
 959     wxVariant GetAttributesAsList() const;
 960
 961     /**
 962         Returns editor used for given column. @NULL for no editor.
 963     */
 964     const wxPGEditor* GetColumnEditor( int column ) const;
 965
 966     /** Returns property's base name (ie. parent's name is not added in any case) */
 967     const wxString& GetBaseName() const;
 968
 969     /**
 970         Returns wxPGCell of given column.
 971     */
 972     const wxPGCell& GetCell( unsigned int column ) const;
 973
 974     /**
 975         Returns number of child properties.
 976     */
 977     unsigned int GetChildCount() const;
 978
 979     /**
 980         Returns height of children, recursively, and
 981         by taking expanded/collapsed status into account.
 982
 983         @param lh
 984             Line height. Pass result of GetGrid()->GetRowHeight() here.
 985
 986         @param iMax
 987             Only used (internally) when finding property y-positions.
 988     */
 989     int GetChildrenHeight( int lh, int iMax = -1 ) const;
 990
 991     /**
 992         Returns read-only reference to property's list of choices.
 993     */
 994     const wxPGChoices& GetChoices() const;
 995
 996     /**
 997         Returns client data (void*) of a property.
 998     */
 999     void* GetClientData() const;
1000
1001     /** Sets managed client object of a property.
1002     */
1003     wxClientData *GetClientObject() const;
1004
1005     /**
1006         Returns property's default value. If property's value type is not
1007         a built-in one, and "DefaultValue" attribute is not defined, then
1008         this function usually returns Null variant.
1009     */
1010     wxVariant GetDefaultValue() const;
1011
1012     /** Returns property's displayed text.
1013     */
1014     wxString GetDisplayedString() const;
1015
1016     /**
1017         Returns wxPGEditor that will be used and created when
1018         property becomes selected. Returns more accurate value
1019         than DoGetEditorClass().
1020     */
1021     const wxPGEditor* GetEditorClass() const;
1022
1023     /** Returns property grid where property lies. */
1024     wxPropertyGrid* GetGrid() const;
1025
1026     /**
1027         Returns owner wxPropertyGrid, but only if one is currently on a page
1028         displaying this property.
1029     */
1030     wxPropertyGrid* GetGridIfDisplayed() const;
1031
1032     /**
1033         Returns property's help or description text.
1034
1035         @see SetHelpString()
1036     */
1037     const wxString& GetHelpString() const;
1038
1039     /**
1040         Returns position in parent's array.
1041     */
1042     unsigned int GetIndexInParent() const;
1043
1044     /** Returns property's label. */
1045     const wxString& GetLabel() const;
1046
1047     /**
1048         Returns last visible child property, recursively.
1049     */
1050     const wxPGProperty* GetLastVisibleSubItem() const;
1051
1052     /**
1053         Returns highest level non-category, non-root parent. Useful when you
1054         have nested properties with children.
1055
1056         @remarks If immediate parent is root or category, this will return the
1057                 property itself.
1058     */
1059     wxPGProperty* GetMainParent() const;
1060
1061     /** Returns maximum allowed length of property's text value.
1062     */
1063     int GetMaxLength() const;
1064
1065     /** Returns property's name with all (non-category, non-root) parents. */
1066     wxString GetName() const;
1067
1068     /** Return parent of property */
1069     wxPGProperty* GetParent() const;
1070
1071     /**
1072         Returns (direct) child property with given name (or @NULL if not found).
1073     */
1074     wxPGProperty* GetPropertyByName( const wxString& name ) const;
1075
1076     /** Gets assignable version of property's validator. */
1077     wxValidator* GetValidator() const;
1078
1079     /**
1080         Returns property's value.
1081     */
1082     wxVariant GetValue() const;
1083
1084     /**
1085         Returns bitmap that appears next to value text. Only returns non-@NULL
1086         bitmap if one was set with SetValueImage().
1087     */
1088     wxBitmap* GetValueImage() const;
1089
1090     /** Returns text representation of property's value.
1091
1092         @param argFlags
1093             If 0 (default value), then displayed string is returned.
1094             If wxPG_FULL_VALUE is set, returns complete, storable string value
1095             instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
1096             string value that must be editable in textctrl. If
1097             wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
1098             display as a part of string property's composite text
1099             representation.
1100
1101         @remarks In older versions, this function used to be overridden to convert
1102                  property's value into a string representation. This function is
1103                  now handled by ValueToString(), and overriding this function now
1104                  will result in run-time assertion failure.
1105     */
1106     virtual wxString GetValueAsString( int argFlags = 0 ) const;
1107
1108     /** Synonymous to GetValueAsString().
1109
1110         @deprecated Use GetValueAsString() instead.
1111
1112         @see GetValueAsString()
1113     */
1114     wxDEPRECATED( wxString GetValueString( int argFlags = 0 ) const );
1115
1116     /**
1117         Returns value type used by this property.
1118     */
1119     wxString GetValueType() const;
1120
1121     /**
1122         Returns coordinate to the top y of the property. Note that the
1123         position of scrollbars is not taken into account.
1124     */
1125     int GetY() const;
1126
1127     /**
1128         Returns @true if property has even one visible child.
1129     */
1130     bool HasVisibleChildren() const;
1131
1132     /**
1133         Hides or reveals the property.
1134
1135         @param hide
1136             @true for hide, @false for reveal.
1137
1138         @param flags
1139             By default changes are applied recursively. Set this parameter wxPG_DONT_RECURSE to prevent this.
1140     */
1141     bool Hide( bool hide, int flags = wxPG_RECURSE );
1142
1143     /**
1144         Returns index of given child property. wxNOT_FOUND if
1145         given property is not child of this.
1146     */
1147     int Index( const wxPGProperty* p ) const;
1148
1149     /**
1150         Inserts a new choice to property's list of choices.
1151
1152         @param label
1153             Text for new choice
1154
1155         @param index
1156             Insertion position. Use wxNOT_FOUND to append.
1157
1158         @param value
1159             Value for new choice. Do not specify if you wish this
1160             to equal choice index.
1161     */
1162     int InsertChoice( const wxString& label, int index, int value = wxPG_INVALID_VALUE );
1163
1164     /**
1165         Returns @true if this property is actually a wxPropertyCategory.
1166     */
1167     bool IsCategory() const;
1168
1169     /**
1170         Returns @true if property is enabled.
1171     */
1172     bool IsEnabled() const;
1173
1174     /**
1175         Returns @true if property has visible children.
1176     */
1177     bool IsExpanded() const;
1178
1179     /**
1180         Returns @true if this property is actually a wxRootProperty.
1181     */
1182     bool IsRoot() const;
1183
1184     /**
1185         Returns @true if candidateParent is some parent of this property.
1186     */
1187     bool IsSomeParent( wxPGProperty* candidateParent ) const;
1188
1189     /**
1190         Returns true if property has editable wxTextCtrl when selected.
1191
1192         @remarks Altough disabled properties do not displayed editor, they still
1193                 return @true here as being disabled is considered a temporary
1194                 condition (unlike being read-only or having limited editing enabled).
1195     */
1196     bool IsTextEditable() const;
1197
1198     /**
1199         Returns @true if property's value is considered unspecified. This
1200         usually means that value is Null variant.
1201     */
1202     bool IsValueUnspecified() const;
1203
1204     /**
1205         Returns true if all parents expanded.
1206     */
1207     bool IsVisible() const;
1208
1209     /**
1210         Returns child property at index i.
1211     */
1212     wxPGProperty* Item( unsigned int i ) const;
1213
1214     /**
1215         If property's editor is active, then update it's value.
1216     */
1217     void RefreshEditor();
1218
1219     /**
1220         Sets an attribute for this property.
1221
1222         @param name
1223             Text identifier of attribute. See @ref propgrid_property_attributes.
1224
1225         @param value
1226             Value of attribute.
1227
1228         @remarks Setting attribute's value to Null variant will simply remove it
1229                 from property's set of attributes.
1230     */
1231     void SetAttribute( const wxString& name, wxVariant value );
1232
1233     /**
1234         Sets property's background colour.
1235
1236         @param colour
1237             Background colour to use.
1238
1239         @param recursively
1240             If @true, children are affected recursively, and any categories
1241             are not.
1242     */
1243     void SetBackgroundColour( const wxColour& colour,
1244                               bool recursively = false );
1245
1246     /**
1247         Sets editor for a property.
1248
1249         @param editor
1250             For builtin editors, use wxPGEditor_X, where X is builtin editor's
1251             name (TextCtrl, Choice, etc. see wxPGEditor documentation for full list).
1252
1253         For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
1254     */
1255     void SetEditor( const wxPGEditor* editor );
1256
1257     /**
1258         Sets editor for a property, by editor name.
1259     */
1260     void SetEditor( const wxString& editorName );
1261
1262     /**
1263         Sets cell information for given column.
1264     */
1265     void SetCell( int column, const wxPGCell& cell );
1266
1267     /**
1268         Sets new set of choices for property.
1269
1270         @remarks This operation clears the property value.
1271     */
1272     bool SetChoices( wxPGChoices& choices );
1273
1274     /**
1275         If property has choices and they are not yet exclusive, new such copy
1276         of them will be created.
1277     */
1278     void SetChoicesExclusive();
1279
1280     /**
1281         Sets client data (void*) of a property.
1282
1283         @remarks This untyped client data has to be deleted manually.
1284     */
1285     void SetClientData( void* clientData );
1286
1287     /** Returns client object of a property.
1288     */
1289     void SetClientObject(wxClientData* clientObject);
1290
1291     /**
1292         Sets selected choice and changes property value.
1293
1294         Tries to retain value type, although currently if it is not string,
1295         then it is forced to integer.
1296     */
1297     void SetChoiceSelection( int newValue );
1298
1299     /**
1300         Sets property's help string, which is shown, for example, in
1301         wxPropertyGridManager's description text box.
1302     */
1303     void SetHelpString( const wxString& helpString );
1304
1305     /**
1306         Sets property's label.
1307
1308         @remarks Properties under same parent may have same labels. However,
1309                 property names must still remain unique.
1310     */
1311     void SetLabel( const wxString& label );
1312
1313     /**
1314         Set max length of text in text editor.
1315     */
1316     bool SetMaxLength( int maxLen );
1317
1318     /**
1319         Sets property's "is it modified?" flag. Affects children recursively.
1320     */
1321     void SetModifiedStatus( bool modified );
1322
1323     /**
1324         Sets new (base) name for property.
1325     */
1326     void SetName( const wxString& newName );
1327
1328     /**
1329         Changes what sort of parent this property is for its children.
1330
1331         @param flag
1332             Use one of the following values: wxPG_PROP_MISC_PARENT (for generic
1333             parents), wxPG_PROP_CATEGORY (for categories), or
1334             wxPG_PROP_AGGREGATE (for derived property classes with private
1335             children).
1336
1337         @remarks You only need to call this if you use AddChild() to add
1338                  child properties. Adding properties with
1339                  wxPropertyGridInterface::Insert() or
1340                  wxPropertyGridInterface::AppendIn() will automatically set
1341                  property to use wxPG_PROP_MISC_PARENT style.
1342     */
1343     void SetParentalType( int flag );
1344
1345     /**
1346         Sets property's text colour.
1347
1348         @param colour
1349             Text colour to use.
1350
1351         @param recursively
1352             If @true, children are affected recursively, and any categories
1353             are not.
1354     */
1355     void SetTextColour( const wxColour& colour,
1356                         bool recursively = false );
1357
1358     /** Sets wxValidator for a property */
1359     void SetValidator( const wxValidator& validator );
1360
1361     /**
1362         Call this to set value of the property. Unlike methods in wxPropertyGrid,
1363         this does not automatically update the display.
1364
1365         @remarks
1366             Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through
1367             validation process and send property change event.
1368
1369             If you need to change property value in event, based on user input, use
1370             SetValueInEvent() instead.
1371
1372         @param value
1373             The value to set.
1374         @param pList
1375             Pointer to list variant that contains child values. Used to indicate
1376             which children should be marked as modified. Usually you just use @NULL.
1377         @param flags
1378             Use wxPG_SETVAL_REFRESH_EDITOR to update editor control, if it
1379             was selected.
1380     */
1381     void SetValue( wxVariant value, wxVariant* pList = NULL, int flags = 0 );
1382
1383     /**
1384         Set wxBitmap in front of the value. This bitmap may be ignored
1385         by custom cell renderers.
1386     */
1387     void SetValueImage( wxBitmap& bmp );
1388
1389     /**
1390         Call this function in OnEvent(), OnButtonClick() etc. to change the
1391         property value based on user input.
1392
1393         @remarks This method is const since it doesn't actually modify value, but posts
1394                 given variant as pending value, stored in wxPropertyGrid.
1395     */
1396     void SetValueInEvent( wxVariant value ) const;
1397
1398     /**
1399         Sets property's value to unspecified (ie. Null variant).
1400     */
1401     void SetValueToUnspecified();
1402
1403     /**
1404         Call with @false in OnSetValue() to cancel value changes after all
1405         (ie. cancel @true returned by StringToValue() or IntToValue()).
1406     */
1407     void SetWasModified( bool set = true );
1408
1409     /**
1410         Updates composed values of parent non-category properties, recursively.
1411         Returns topmost property updated.
1412     */
1413     wxPGProperty* UpdateParentValues();
1414
1415     /**
1416         Returns @true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
1417     */
1418     bool UsesAutoUnspecified() const;
1419 };
1420
1421
1422 /**
1423     @class wxPGChoices
1424
1425     Helper class for managing choices of wxPropertyGrid properties.
1426     Each entry can have label, value, bitmap, text colour, and background colour.
1427
1428     @library{wxpropgrid}
1429     @category{propgrid}
1430 */
1431 class WXDLLIMPEXP_PROPGRID wxPGChoices
1432 {
1433 public:
1434     typedef long ValArrItem;
1435
1436     /**
1437         Default constructor.
1438     */
1439     wxPGChoices();
1440
1441     /** Copy constructor. */
1442     wxPGChoices( const wxPGChoices& a );
1443
1444     /** Constructor. */
1445     wxPGChoices( const wxChar** labels, const long* values = NULL );
1446
1447     /** Constructor. */
1448     wxPGChoices( const wxArrayString& labels, const wxArrayInt& values = wxArrayInt() );
1449
1450     /** Constructor. */
1451     wxPGChoices( wxPGChoicesData* data );
1452
1453     /** Destructor. */
1454     ~wxPGChoices();
1455
1456     /**
1457         Adds to current. If did not have own copies, creates them now. If was empty,
1458         identical to set except that creates copies.
1459     */
1460     void Add( const wxChar** labels, const ValArrItem* values = NULL );
1461
1462     /** Version that works with wxArrayString. */
1463     void Add( const wxArrayString& arr, const ValArrItem* values = NULL );
1464
1465     /** Version that works with wxArrayString and wxArrayInt. */
1466     void Add( const wxArrayString& arr, const wxArrayInt& arrint );
1467
1468     /** Adds single item. */
1469     wxPGChoiceEntry& Add( const wxString& label, int value = wxPG_INVALID_VALUE );
1470
1471     /** Adds a single item, with bitmap. */
1472     wxPGChoiceEntry& Add( const wxString& label, const wxBitmap& bitmap,
1473                           int value = wxPG_INVALID_VALUE );
1474
1475     /** Adds a single item with full entry information. */
1476     wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry );
1477
1478     /** Adds single item, sorted. */
1479     wxPGChoiceEntry& AddAsSorted( const wxString& label, int value = wxPG_INVALID_VALUE );
1480
1481     /**
1482         Assigns data from another set of choices.
1483     */
1484     void Assign( const wxPGChoices& a );
1485
1486     /**
1487         Assigns data from another set of choices.
1488     */
1489     void AssignData( wxPGChoicesData* data );
1490
1491     /**
1492         Deletes all items.
1493     */
1494     void Clear();
1495
1496     /**
1497         Returns labe of item.
1498     */
1499     const wxString& GetLabel( unsigned int ind ) const;
1500
1501     /**
1502         Returns number of items.
1503     */
1504     unsigned int GetCount() const;
1505
1506     /**
1507         Returns value of item;
1508     */
1509     int GetValue( unsigned int ind ) const;
1510
1511     /**
1512         Returns array of values matching the given strings. Unmatching strings
1513         result in wxPG_INVALID_VALUE entry in array.
1514     */
1515     wxArrayInt GetValuesForStrings( const wxArrayString& strings ) const;
1516
1517     /**
1518         Returns array of indices matching given strings. Unmatching strings
1519         are added to 'unmatched', if not @NULL.
1520     */
1521     wxArrayInt GetIndicesForStrings( const wxArrayString& strings,
1522                                      wxArrayString* unmatched = NULL ) const;
1523
1524     /**
1525         Returns @true if item at given index has a valid value;
1526     */
1527     bool HasValue( unsigned int i ) const;
1528
1529     /**
1530         Returns index of item with given label.
1531     */
1532     int Index( const wxString& label ) const;
1533
1534     /**
1535         Returns index of item with given value.
1536     */
1537     int Index( int val ) const;
1538
1539     /**
1540         Inserts single item.
1541     */
1542     wxPGChoiceEntry& Insert( const wxString& label, int index, int value = wxPG_INVALID_VALUE );
1543
1544     /**
1545         Inserts a single item with full entry information.
1546     */
1547     wxPGChoiceEntry& Insert( const wxPGChoiceEntry& entry, int index );
1548
1549     /**
1550         Returns @false if this is a constant empty set of choices,
1551         which should not be modified.
1552     */
1553     bool IsOk() const;
1554
1555     /**
1556         Returns item at given index.
1557     */
1558     const wxPGChoiceEntry& Item( unsigned int i ) const;
1559
1560     /**
1561         Returns item at given index.
1562     */
1563     wxPGChoiceEntry& Item( unsigned int i );
1564
1565     /**
1566         Removes count items starting at position nIndex.
1567     */
1568     void RemoveAt(size_t nIndex, size_t count = 1);
1569
1570     /**
1571         Sets contents from lists of strings and values.
1572     */
1573     void Set( const wxChar** labels, const long* values = NULL );
1574
1575     /**
1576         Sets contents from lists of strings and values.
1577     */
1578     void Set( const wxArrayString& labels, const wxArrayInt& values = wxArrayInt() );
1579
1580     /**
1581         Creates exclusive copy of current choices.
1582     */
1583     void SetExclusive();
1584
1585     /**
1586         Returns array of choice labels.
1587     */
1588     wxArrayString GetLabels() const;
1589
1590     void operator= (const wxPGChoices& a);
1591
1592     wxPGChoiceEntry& operator[](unsigned int i);
1593     const wxPGChoiceEntry& operator[](unsigned int i) const;
1594 };
1595
1596 // -----------------------------------------------------------------------