interface/wx/propgrid/property.h

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