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