include/wx/propgrid/property.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/propgrid/property.h
   3 // Purpose:     wxPGProperty and related support classes
   4 // Author:      Jaakko Salli
   5 // Modified by:
   6 // Created:     2008-08-23
   7 // RCS-ID:      $Id:
   8 // Copyright:   (c) Jaakko Salli
   9 // Licence:     wxWindows license
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_PROPGRID_PROPERTY_H_
  13 #define _WX_PROPGRID_PROPERTY_H_
  14
  15 #include "wx/propgrid/propgriddefs.h"
  16
  17 // -----------------------------------------------------------------------
  18
  19 #define wxNullProperty  ((wxPGProperty*)NULL)
  20
  21
  22 /** @class wxPGPaintData
  23
  24     Contains information relayed to property's OnCustomPaint.
  25 */
  26 struct wxPGPaintData
  27 {
  28     /** wxPropertyGrid. */
  29     const wxPropertyGrid*   m_parent;
  30
  31     /**
  32         Normally -1, otherwise index to drop-down list item that has to be
  33         drawn.
  34      */
  35     int                     m_choiceItem;
  36
  37     /** Set to drawn width in OnCustomPaint (optional). */
  38     int                     m_drawnWidth;
  39
  40     /**
  41         In a measure item call, set this to the height of item at m_choiceItem
  42         index.
  43      */
  44     int                     m_drawnHeight;
  45 };
  46
  47
  48 // Structure for relaying choice/list info.
  49 struct wxPGChoiceInfo
  50 {
  51     wxPGChoices*    m_choices;
  52 };
  53
  54
  55 #ifndef SWIG
  56
  57
  58 // space between vertical sides of a custom image
  59 #define wxPG_CUSTOM_IMAGE_SPACINGY      1
  60
  61 // space between caption and selection rectangle,
  62 #define wxPG_CAPRECTXMARGIN             2
  63
  64 // horizontally and vertically
  65 #define wxPG_CAPRECTYMARGIN             1
  66
  67
  68 /** @class wxPGCellRenderer
  69
  70     Base class for wxPropertyGrid cell renderers.
  71 */
  72 class WXDLLIMPEXP_PROPGRID wxPGCellRenderer
  73 {
  74 public:
  75
  76     wxPGCellRenderer( unsigned int refCount = 1 )
  77         : m_refCount(refCount) { }
  78     virtual ~wxPGCellRenderer() { }
  79
  80     // Render flags
  81     enum
  82     {
  83         Selected        = 0x00010000,
  84         Control         = 0x00020000
  85     };
  86
  87     virtual void Render( wxDC& dc,
  88                          const wxRect& rect,
  89                          const wxPropertyGrid* propertyGrid,
  90                          wxPGProperty* property,
  91                          int column,
  92                          int item,
  93                          int flags ) const = 0;
  94
  95     /** Returns size of the image in front of the editable area.
  96         @remarks
  97         If property is NULL, then this call is for a custom value. In that case
  98         the item is index to wxPropertyGrid's custom values.
  99     */
 100     virtual wxSize GetImageSize( const wxPGProperty* property,
 101                                  int column,
 102                                  int item ) const;
 103
 104     /** Paints property category selection rectangle.
 105     */
 106     virtual void DrawCaptionSelectionRect( wxDC& dc,
 107                                            int x, int y,
 108                                            int w, int h ) const;
 109
 110     /** Utility to draw vertically centered text.
 111     */
 112     void DrawText( wxDC& dc,
 113                    const wxRect& rect,
 114                    int imageWidth,
 115                    const wxString& text ) const;
 116
 117     /**
 118         Utility to draw editor's value, or vertically aligned text if editor is
 119         NULL.
 120     */
 121     void DrawEditorValue( wxDC& dc, const wxRect& rect,
 122                           int xOffset, const wxString& text,
 123                           wxPGProperty* property,
 124                           const wxPGEditor* editor ) const;
 125
 126     /** Utility to render cell bitmap and set text colour plus bg brush colour.
 127
 128         Returns image width that, for instance, can be passed to DrawText.
 129     */
 130     int PreDrawCell( wxDC& dc,
 131                      const wxRect& rect,
 132                      const wxPGCell& cell,
 133                      int flags ) const;
 134
 135     void IncRef()
 136     {
 137         m_refCount++;
 138     }
 139
 140     void DecRef()
 141     {
 142         m_refCount--;
 143         if ( !m_refCount )
 144             delete this;
 145     }
 146 protected:
 147
 148 private:
 149     unsigned int    m_refCount;
 150 };
 151
 152
 153 /** @class wxPGCell
 154
 155     Base class for simple wxPropertyGrid cell information.
 156 */
 157 class WXDLLIMPEXP_PROPGRID wxPGCell
 158 {
 159 public:
 160     wxPGCell();
 161     wxPGCell( const wxString& text,
 162               const wxBitmap& bitmap = wxNullBitmap,
 163               const wxColour& fgCol = wxNullColour,
 164               const wxColour& bgCol = wxNullColour );
 165
 166     virtual ~wxPGCell() { }
 167
 168     void SetText( const wxString& text ) { m_text = text; }
 169     void SetBitmap( const wxBitmap& bitmap ) { m_bitmap = bitmap; }
 170     void SetFgCol( const wxColour& col ) { m_fgCol = col; }
 171     void SetBgCol( const wxColour& col ) { m_bgCol = col; }
 172
 173     const wxString& GetText() const { return m_text; }
 174     const wxBitmap& GetBitmap() const { return m_bitmap; }
 175     const wxColour& GetFgCol() const { return m_fgCol; }
 176     const wxColour& GetBgCol() const { return m_bgCol; }
 177
 178 protected:
 179     wxString    m_text;
 180     wxBitmap    m_bitmap;
 181     wxColour    m_fgCol;
 182     wxColour    m_bgCol;
 183 };
 184
 185
 186 /** @class wxPGDefaultRenderer
 187
 188     Default cell renderer, that can handles the common
 189     scenarios.
 190 */
 191 class WXDLLIMPEXP_PROPGRID wxPGDefaultRenderer : public wxPGCellRenderer
 192 {
 193 public:
 194     virtual void Render( wxDC& dc,
 195                          const wxRect& rect,
 196                          const wxPropertyGrid* propertyGrid,
 197                          wxPGProperty* property,
 198                          int column,
 199                          int item,
 200                          int flags ) const;
 201
 202     virtual wxSize GetImageSize( const wxPGProperty* property,
 203                                  int column,
 204                                  int item ) const;
 205
 206 protected:
 207 };
 208
 209 // -----------------------------------------------------------------------
 210
 211 /** @class wxPGAttributeStorage
 212
 213     wxPGAttributeStorage is somewhat optimized storage for
 214       key=variant pairs (ie. a map).
 215 */
 216 class WXDLLIMPEXP_PROPGRID wxPGAttributeStorage
 217 {
 218 public:
 219     wxPGAttributeStorage();
 220     ~wxPGAttributeStorage();
 221
 222     void Set( const wxString& name, const wxVariant& value );
 223     size_t GetCount() const { return m_map.size(); }
 224     wxVariant FindValue( const wxString& name ) const
 225     {
 226         wxPGHashMapS2P::const_iterator it = m_map.find(name);
 227         if ( it != m_map.end() )
 228         {
 229             wxVariantData* data = (wxVariantData*) it->second;
 230             data->IncRef();
 231             return wxVariant(data, it->first);
 232         }
 233         return wxVariant();
 234     }
 235
 236     typedef wxPGHashMapS2P::const_iterator const_iterator;
 237     const_iterator StartIteration() const
 238     {
 239         return m_map.begin();
 240     }
 241     bool GetNext( const_iterator& it, wxVariant& variant ) const
 242     {
 243         if ( it == m_map.end() )
 244             return false;
 245
 246         wxVariantData* data = (wxVariantData*) it->second;
 247         data->IncRef();
 248         variant.SetData(data);
 249         variant.SetName(it->first);
 250         it++;
 251         return true;
 252     }
 253
 254 protected:
 255     wxPGHashMapS2P  m_map;
 256 };
 257
 258 #endif  // !SWIG
 259
 260 // -----------------------------------------------------------------------
 261
 262 /** @section propgrid_propflags wxPGProperty Flags
 263     @{
 264 */
 265
 266 enum wxPG_PROPERTY_FLAGS
 267 {
 268
 269 /** Indicates bold font.
 270 */
 271 wxPG_PROP_MODIFIED                  = 0x0001,
 272
 273 /** Disables ('greyed' text and editor does not activate) property.
 274 */
 275 wxPG_PROP_DISABLED                  = 0x0002,
 276
 277 /** Hider button will hide this property.
 278 */
 279 wxPG_PROP_HIDDEN                    = 0x0004,
 280
 281 /** This property has custom paint image just in front of its value.
 282     If property only draws custom images into a popup list, then this
 283     flag should not be set.
 284 */
 285 wxPG_PROP_CUSTOMIMAGE               = 0x0008,
 286
 287 /** Do not create text based editor for this property (but button-triggered
 288     dialog and choice are ok).
 289 */
 290 wxPG_PROP_NOEDITOR                  = 0x0010,
 291
 292 /** Property is collapsed, ie. it's children are hidden.
 293 */
 294 wxPG_PROP_COLLAPSED                 = 0x0020,
 295
 296 /**
 297     If property is selected, then indicates that validation failed for pending
 298     value.
 299
 300     If property is not selected, then indicates that the the actual property
 301     value has failed validation (NB: this behavior is not currently supported,
 302     but may be used in future).
 303 */
 304 wxPG_PROP_INVALID_VALUE             = 0x0040,
 305
 306 // 0x0080,
 307
 308 /** Switched via SetWasModified(). Temporary flag - only used when
 309     setting/changing property value.
 310 */
 311 wxPG_PROP_WAS_MODIFIED              = 0x0200,
 312
 313 /**
 314     If set, then child properties (if any) are private, and should be
 315     "invisible" to the application.
 316 */
 317 wxPG_PROP_AGGREGATE                 = 0x0400,
 318
 319 /** If set, then child properties (if any) are copies and should not
 320     be deleted in dtor.
 321 */
 322 wxPG_PROP_CHILDREN_ARE_COPIES       = 0x0800,
 323
 324 /**
 325     Classifies this item as a non-category.
 326
 327     Used for faster item type identification.
 328 */
 329 wxPG_PROP_PROPERTY                  = 0x1000,
 330
 331 /**
 332     Classifies this item as a category.
 333
 334     Used for faster item type identification.
 335 */
 336 wxPG_PROP_CATEGORY                  = 0x2000,
 337
 338 /** Classifies this item as a property that has children, but is not aggregate
 339     (ie children are not private).
 340 */
 341 wxPG_PROP_MISC_PARENT               = 0x4000,
 342
 343 /** Property is read-only. Editor is still created.
 344 */
 345 wxPG_PROP_READONLY                  = 0x8000,
 346
 347 //
 348 // NB: FLAGS ABOVE 0x8000 CANNOT BE USED WITH PROPERTY ITERATORS
 349 //
 350
 351 /** Property's value is composed from values of child properties.
 352     @remarks
 353     This flag cannot be used with property iterators.
 354 */
 355 wxPG_PROP_COMPOSED_VALUE            = 0x00010000,
 356
 357 /** Common value of property is selectable in editor.
 358     @remarks
 359     This flag cannot be used with property iterators.
 360 */
 361 wxPG_PROP_USES_COMMON_VALUE         = 0x00020000,
 362
 363 /** Property can be set to unspecified value via editor.
 364     Currently, this applies to following properties:
 365     - wxIntProperty, wxUIntProperty, wxFloatProperty, wxEditEnumProperty:
 366       Clear the text field
 367
 368     @remarks
 369     This flag cannot be used with property iterators.
 370 */
 371 wxPG_PROP_AUTO_UNSPECIFIED          = 0x00040000,
 372
 373 /** Indicates the bit useable by derived properties.
 374 */
 375 wxPG_PROP_CLASS_SPECIFIC_1          = 0x00080000,
 376
 377 /** Indicates the bit useable by derived properties.
 378 */
 379 wxPG_PROP_CLASS_SPECIFIC_2          = 0x00100000
 380
 381 };
 382
 383 /** Topmost flag.
 384 */
 385 #define wxPG_PROP_MAX               wxPG_PROP_AUTO_UNSPECIFIED
 386
 387 /** Property with children must have one of these set, otherwise iterators
 388     will not work correctly.
 389     Code should automatically take care of this, however.
 390 */
 391 #define wxPG_PROP_PARENTAL_FLAGS \
 392     (wxPG_PROP_AGGREGATE|wxPG_PROP_CATEGORY|wxPG_PROP_MISC_PARENT)
 393
 394 /** @}
 395 */
 396
 397 // Amalgam of flags that should be inherited by sub-properties
 398 #define wxPG_INHERITED_PROPFLAGS        (wxPG_PROP_HIDDEN|wxPG_PROP_NOEDITOR)
 399
 400 // Combination of flags that can be stored by GetFlagsAsString
 401 #define wxPG_STRING_STORED_FLAGS \
 402     (wxPG_PROP_DISABLED|wxPG_PROP_HIDDEN|wxPG_PROP_NOEDITOR|wxPG_PROP_COLLAPSED)
 403
 404 // -----------------------------------------------------------------------
 405
 406 #ifndef SWIG
 407
 408 /**
 409     @section propgrid_property_attributes wxPropertyGrid Property Attribute
 410     Identifiers.
 411
 412     wxPGProperty::SetAttribute() and
 413     wxPropertyGridInterfaces::SetPropertyAttribute() accept one of these as
 414     attribute name argument.
 415
 416     You can use strings instead of constants. However, some of these
 417     constants are redefined to use cached strings which may reduce
 418     your binary size by some amount.
 419
 420     @{
 421 */
 422
 423 /** Set default value for property.
 424 */
 425 #define wxPG_ATTR_DEFAULT_VALUE           wxS("DefaultValue")
 426
 427 /** Universal, int or double. Minimum value for numeric properties.
 428 */
 429 #define wxPG_ATTR_MIN                     wxS("Min")
 430
 431 /** Universal, int or double. Maximum value for numeric properties.
 432 */
 433 #define wxPG_ATTR_MAX                     wxS("Max")
 434
 435 /** Universal, string. When set, will be shown as text after the displayed
 436     text value. Alternatively, if third column is enabled, text will be shown
 437     there (for any type of property).
 438 */
 439 #define wxPG_ATTR_UNITS                     wxS("Units")
 440
 441 /** Universal, string. When set, will be shown in property's value cell
 442     when displayed value string is empty, or value is unspecified.
 443 */
 444 #define wxPG_ATTR_INLINE_HELP               wxS("InlineHelp")
 445
 446 /** wxBoolProperty specific, int, default 0. When 1 sets bool property to
 447     use checkbox instead of choice.
 448 */
 449 #define wxPG_BOOL_USE_CHECKBOX              wxS("UseCheckbox")
 450
 451 /** wxBoolProperty specific, int, default 0. When 1 sets bool property value
 452     to cycle on double click (instead of showing the popup listbox).
 453 */
 454 #define wxPG_BOOL_USE_DOUBLE_CLICK_CYCLING  wxS("UseDClickCycling")
 455
 456 /**
 457     wxFloatProperty (and similar) specific, int, default -1.
 458
 459     Sets the (max) precision used when floating point value is rendered as
 460     text. The default -1 means infinite precision.
 461 */
 462 #define wxPG_FLOAT_PRECISION                wxS("Precision")
 463
 464 /**
 465     The text will be echoed as asterisks (wxTE_PASSWORD will be passed to
 466     textctrl etc).
 467 */
 468 #define wxPG_STRING_PASSWORD                wxS("Password")
 469
 470 /** Define base used by a wxUIntProperty. Valid constants are
 471     wxPG_BASE_OCT, wxPG_BASE_DEC, wxPG_BASE_HEX and wxPG_BASE_HEXL
 472     (lowercase characters).
 473 */
 474 #define wxPG_UINT_BASE                      wxS("Base")
 475
 476 /** Define prefix rendered to wxUIntProperty. Accepted constants
 477     wxPG_PREFIX_NONE, wxPG_PREFIX_0x, and wxPG_PREFIX_DOLLAR_SIGN.
 478     <b>Note:</b> Only wxPG_PREFIX_NONE works with Decimal and Octal
 479     numbers.
 480 */
 481 #define wxPG_UINT_PREFIX                    wxS("Prefix")
 482
 483 /**
 484     wxFileProperty/wxImageFileProperty specific, wxChar*, default is
 485     detected/varies.
 486     Sets the wildcard used in the triggered wxFileDialog. Format is the same.
 487 */
 488 #define wxPG_FILE_WILDCARD                  wxS("Wildcard")
 489
 490 /** wxFileProperty/wxImageFileProperty specific, int, default 1.
 491     When 0, only the file name is shown (i.e. drive and directory are hidden).
 492 */
 493 #define wxPG_FILE_SHOW_FULL_PATH            wxS("ShowFullPath")
 494
 495 /** Specific to wxFileProperty and derived properties, wxString, default empty.
 496     If set, then the filename is shown relative to the given path string.
 497 */
 498 #define wxPG_FILE_SHOW_RELATIVE_PATH        wxS("ShowRelativePath")
 499
 500 /**
 501     Specific to wxFileProperty and derived properties, wxString, default is
 502     empty.
 503
 504     Sets the initial path of where to look for files.
 505 */
 506 #define wxPG_FILE_INITIAL_PATH              wxS("InitialPath")
 507
 508 /** Specific to wxFileProperty and derivatives, wxString, default is empty.
 509     Sets a specific title for the dir dialog.
 510 */
 511 #define wxPG_FILE_DIALOG_TITLE              wxS("DialogTitle")
 512
 513 /** Specific to wxDirProperty, wxString, default is empty.
 514     Sets a specific message for the dir dialog.
 515 */
 516 #define wxPG_DIR_DIALOG_MESSAGE             wxS("DialogMessage")
 517
 518 /** Sets displayed date format for wxDateProperty.
 519 */
 520 #define wxPG_DATE_FORMAT                    wxS("DateFormat")
 521
 522 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
 523     is wxDP_DEFAULT | wxDP_SHOWCENTURY.
 524 */
 525 #define wxPG_DATE_PICKER_STYLE              wxS("PickerStyle")
 526
 527 /** SpinCtrl editor, int or double. How much number changes when button is
 528     pressed (or up/down on keybard).
 529 */
 530 #define wxPG_ATTR_SPINCTRL_STEP             wxS("Step")
 531
 532 /** SpinCtrl editor, bool. If true, value wraps at Min/Max.
 533 */
 534 #define wxPG_ATTR_SPINCTRL_WRAP             wxS("Wrap")
 535
 536 /**
 537     wxMultiChoiceProperty, int.
 538     If 0, no user strings allowed. If 1, user strings appear before list
 539     strings. If 2, user strings appear after list string.
 540 */
 541 #define wxPG_ATTR_MULTICHOICE_USERSTRINGMODE    wxS("UserStringMode")
 542
 543 /**
 544     wxColourProperty and its kind, int, default 1.
 545
 546     Setting this attribute to 0 hides custom colour from property's list of
 547     choices.
 548 */
 549 #define wxPG_COLOUR_ALLOW_CUSTOM            wxS("AllowCustom")
 550
 551 /** First attribute id that is guaranteed not to be used built-in
 552     properties.
 553 */
 554 //#define wxPG_USER_ATTRIBUTE                 192
 555
 556 /** @}
 557 */
 558
 559 #ifndef DOXYGEN
 560
 561 // Redefine attribute macros to use cached strings
 562 #undef wxPG_ATTR_MIN
 563 #define wxPG_ATTR_MIN                     wxPGGlobalVars->m_strMin
 564 #undef wxPG_ATTR_MAX
 565 #define wxPG_ATTR_MAX                     wxPGGlobalVars->m_strMax
 566 #undef wxPG_ATTR_UNITS
 567 #define wxPG_ATTR_UNITS                   wxPGGlobalVars->m_strUnits
 568 #undef wxPG_ATTR_INLINE_HELP
 569 #define wxPG_ATTR_INLINE_HELP             wxPGGlobalVars->m_strInlineHelp
 570
 571 #endif  // !DOXYGEN
 572
 573 #endif  // !SWIG
 574
 575 // -----------------------------------------------------------------------
 576
 577 /** @class wxPGProperty
 578
 579     wxPGProperty is base class for all wxPropertyGrid properties. In
 580     sections below we cover few related topics.
 581
 582     @li @ref pgproperty_properties
 583     @li @ref pgproperty_creating
 584
 585     @section pgproperty_properties Supplied Ready-to-use Property Classes
 586
 587     Here is a list and short description of supplied fully-functional
 588     property classes. They are located in either props.h or advprops.h.
 589
 590     @li @ref wxArrayStringProperty
 591     @li @ref wxBoolProperty
 592     @li @ref wxColourProperty
 593     @li @ref wxCursorProperty
 594     @li @ref wxDateProperty
 595     @li @ref wxDirProperty
 596     @li @ref wxEditEnumProperty
 597     @li @ref wxEnumProperty
 598     @li @ref wxFileProperty
 599     @li @ref wxFlagsProperty
 600     @li @ref wxFloatProperty
 601     @li @ref wxFontProperty
 602     @li @ref wxImageFileProperty
 603     @li @ref wxIntProperty
 604     @li @ref wxLongStringProperty
 605     @li @ref wxMultiChoiceProperty
 606     @li @ref wxPropertyCategory
 607     @li @ref wxStringProperty
 608     @li @ref wxSystemColourProperty
 609     @li @ref wxUIntProperty
 610
 611     @subsection wxPropertyCategory
 612
 613     Not an actual property per se, but a header for a group of properties.
 614     Regardless inherits from wxPGProperty.
 615
 616     @subsection wxStringProperty
 617
 618     Simple string property. wxPG_STRING_PASSWORD attribute may be used
 619     to echo value as asterisks and use wxTE_PASSWORD for wxTextCtrl.
 620
 621     @remarks
 622     * wxStringProperty has a special trait: if it has value of "<composed>",
 623       and also has child properties, then its displayed value becomes
 624       composition of child property values, similar as with wxFontProperty,
 625       for instance.
 626
 627     @subsection wxIntProperty
 628
 629     Like wxStringProperty, but converts text to a signed long integer.
 630     wxIntProperty seamlessly supports 64-bit integers (ie. wxLongLong).
 631
 632     @subsection wxUIntProperty
 633
 634     Like wxIntProperty, but displays value as unsigned int. To set
 635     the prefix used globally, manipulate wxPG_UINT_PREFIX string attribute.
 636     To set the globally used base, manipulate wxPG_UINT_BASE int
 637     attribute. Regardless of current prefix, understands (hex) values starting
 638     with both "0x" and "$".
 639     wxUIntProperty seamlessly supports 64-bit unsigned integers (ie.
 640     wxULongLong).
 641
 642     @subsection wxFloatProperty
 643
 644     Like wxStringProperty, but converts text to a double-precision floating
 645     point. Default float-to-text precision is 6 decimals, but this can be
 646     changed by modifying wxPG_FLOAT_PRECISION attribute.
 647
 648     @subsection wxBoolProperty
 649
 650     Represents a boolean value. wxChoice is used as editor control, by the
 651     default. wxPG_BOOL_USE_CHECKBOX attribute can be set to true inorder to use
 652     check box instead.
 653
 654     @subsection wxLongStringProperty
 655
 656     Like wxStringProperty, but has a button that triggers a small text editor
 657     dialog. Note that in long string values, tabs are represented by "\t" and
 658     line break by "\n".
 659
 660     @subsection wxDirProperty
 661
 662     Like wxLongStringProperty, but the button triggers dir selector instead.
 663     Supported properties (all with string value): wxPG_DIR_DIALOG_MESSAGE.
 664
 665     @subsection wxFileProperty
 666
 667     Like wxLongStringProperty, but the button triggers file selector instead.
 668     Default wildcard is "All files..." but this can be changed by setting
 669     wxPG_FILE_WILDCARD attribute (see wxFileDialog for format details).
 670     Attribute wxPG_FILE_SHOW_FULL_PATH can be set to false inorder to show
 671     only the filename, not the entire path.
 672
 673     @subsection wxEnumProperty
 674
 675     Represents a single selection from a list of choices -
 676     wxOwnerDrawnComboBox is used to edit the value.
 677
 678     @subsection wxFlagsProperty
 679
 680     Represents a bit set that fits in a long integer. wxBoolProperty
 681     sub-properties are created for editing individual bits. Textctrl is created
 682     to manually edit the flags as a text; a continous sequence of spaces,
 683     commas and semicolons is considered as a flag id separator.
 684     <b>Note: </b> When changing "choices" (ie. flag labels) of wxFlagsProperty,
 685     you will need to use SetPropertyChoices - otherwise they will not get
 686     updated properly.
 687
 688     @subsection wxArrayStringProperty
 689
 690     Allows editing of a list of strings in wxTextCtrl and in a separate dialog.
 691
 692     @subsection wxDateProperty
 693
 694     wxDateTime property. Default editor is DatePickerCtrl, altough TextCtrl
 695     should work as well. wxPG_DATE_FORMAT attribute can be used to change
 696     string wxDateTime::Format uses (altough default is recommended as it is
 697     locale-dependant), and wxPG_DATE_PICKER_STYLE allows changing window
 698     style given to DatePickerCtrl (default is wxDP_DEFAULT|wxDP_SHOWCENTURY).
 699
 700     @subsection wxEditEnumProperty
 701
 702     Represents a string that can be freely edited or selected from list of
 703     choices - custom combobox control is used to edit the value.
 704
 705     @subsection wxMultiChoiceProperty
 706
 707     Allows editing a multiple selection from a list of strings. This is
 708     property is pretty much built around concept of wxMultiChoiceDialog.
 709     It uses wxArrayString value.
 710
 711     @subsection wxImageFileProperty
 712
 713     Like wxFileProperty, but has thumbnail of the image in front of
 714     the filename and autogenerates wildcard from available image handlers.
 715
 716     @subsection wxColourProperty
 717
 718     <b>Useful alternate editor:</b> Choice.
 719
 720     Represents wxColour. wxButton is used to trigger a colour picker dialog.
 721
 722     @subsection wxFontProperty
 723
 724     Represents wxFont. Various sub-properties are used to edit individual
 725     subvalues.
 726
 727     @subsection wxSystemColourProperty
 728
 729     Represents wxColour and a system colour index. wxChoice is used to edit
 730     the value. Drop-down list has color images. Note that value type
 731     is wxColourPropertyValue instead of wxColour.
 732     @code
 733         class wxColourPropertyValue : public wxObject
 734         {
 735         public:
 736             //  An integer value relating to the colour, and which exact
 737             //  meaning depends on the property with which it is used.
 738             //
 739             //  For wxSystemColourProperty:
 740             //  Any of wxSYS_COLOUR_XXX, or any web-colour (use
 741             //  wxPG_TO_WEB_COLOUR macro - (currently unsupported) ),
 742             //  or wxPG_COLOUR_CUSTOM.
 743             wxUint32    m_type;
 744
 745             // Resulting colour. Should be correct regardless of type.
 746             wxColour    m_colour;
 747         };
 748     @endcode
 749
 750     @subsection wxCursorProperty
 751
 752     Represents a wxCursor. wxChoice is used to edit the value.
 753     Drop-down list has cursor images under some (wxMSW) platforms.
 754
 755
 756     @section pgproperty_creating Creating Custom Properties
 757
 758     New properties can be created by subclassing wxPGProperty or one
 759     of the provided property classes, and (re)implementing necessary
 760     member functions. Below, each virtual member function has ample
 761     documentation about its purpose and any odd details which to keep
 762     in mind.
 763
 764     Here is a very simple 'template' code:
 765
 766     @code
 767         class MyProperty : public wxPGProperty
 768         {
 769         public:
 770             // All arguments of ctor must have a default value -
 771             // use wxPG_LABEL for label and name
 772             MyProperty( const wxString& label = wxPG_LABEL,
 773                         const wxString& name = wxPG_LABEL,
 774                         const wxString& value = wxEmptyString )
 775             {
 776                 // m_value is wxVariant
 777                 m_value = value;
 778             }
 779
 780             virtual ~MyProperty() { }
 781
 782             const wxPGEditor* DoGetEditorClass() const
 783             {
 784                 // Determines editor used by property.
 785                 // You can replace 'TextCtrl' below with any of these
 786                 // builtin-in property editor identifiers: Choice, ComboBox,
 787                 // TextCtrlAndButton, ChoiceAndButton, CheckBox, SpinCtrl,
 788                 // DatePickerCtrl.
 789                 return wxPGEditor_TextCtrl;
 790             }
 791
 792             virtual wxString GetValueAsString( int argFlags ) const
 793             {
 794                 // TODO: Return property value in string format
 795             }
 796
 797             virtual bool StringToValue( wxVariant& variant,
 798                                         const wxString& text,
 799                                         int argFlags )
 800             {
 801                 // TODO: Adapt string to property value.
 802             }
 803
 804         protected:
 805         };
 806     @endcode
 807
 808     Since wxPGProperty derives from wxObject, you can use standard
 809     DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS macros. From the
 810     above example they were omitted for sake of simplicity, and besides,
 811     they are only really needed if you need to use wxRTTI with your
 812     property class.
 813
 814     You can change the 'value type' of a property by simply assigning different
 815     type of variant with SetValue. <b>It is mandatory to implement
 816     wxVariantData class for all data types used as property values.</b> Also,
 817     it is further recommended to derive your class from wxPGVariantData, like
 818     this:
 819
 820     @code
 821         // In header file:
 822         // (replace DECL with required data declaration, use
 823         // wxEMPTY_PARAMETER_VALUE if none)
 824         WX_PG_DECLARE_VARIANT_DATA(wxPGVariantMyDataClass, MyDataClass, DECL)
 825
 826         // In sources file:
 827         WX_PG_IMPLEMENT_VARIANT_DATA(wxPGVariantMyDataClass, MyDataClass)
 828     @endcode
 829
 830     @library{wxpropgrid}
 831     @category{propgrid}
 832 */
 833 class WXDLLIMPEXP_PROPGRID wxPGProperty : public wxObject
 834 {
 835     friend class wxPropertyGrid;
 836     friend class wxPropertyGridInterface;
 837     friend class wxPropertyGridPageState;
 838     friend class wxPropertyGridPopulator;
 839     friend class wxStringProperty;  // Proper "<composed>" support requires this
 840 #ifndef SWIG
 841     DECLARE_ABSTRACT_CLASS(wxPGProperty)
 842 #endif
 843 public:
 844     typedef wxUint32 FlagType;
 845
 846     /** Basic constructor.
 847     */
 848     wxPGProperty();
 849
 850     /** Constructor.
 851         Non-abstract property classes should have constructor of this style:
 852
 853         @code
 854
 855         // If T is a class, then it should be a constant reference
 856         // (e.g. const T& ) instead.
 857         MyProperty( const wxString& label, const wxString& name, T value )
 858             : wxPGProperty()
 859         {
 860             // Generally recommended way to set the initial value
 861             // (as it should work in pretty much 100% of cases).
 862             wxVariant variant;
 863             variant << value;
 864             SetValue(variant);
 865
 866             // If has private child properties then create them here, e.g.:
 867             //     AddChild( new wxStringProperty( "Subprop 1",
 868             //                                     wxPG_LABEL,
 869             //                                     value.GetSubProp1() ) );
 870         }
 871
 872         @endcode
 873     */
 874     wxPGProperty( const wxString& label, const wxString& name );
 875
 876     /**
 877         Virtual destructor.
 878         It is customary for derived properties to implement this.
 879     */
 880     virtual ~wxPGProperty();
 881
 882     /** This virtual function is called after m_value has been set.
 883
 884         @remarks
 885         - If m_value was set to Null variant (ie. unspecified value),
 886           OnSetValue() will not be called.
 887         - m_value may be of any variant type. Typically properties internally
 888           support only one variant type, and as such OnSetValue() provides a
 889           good opportunity to convert
 890           supported values into internal type.
 891         - Default implementation does nothing.
 892     */
 893     virtual void OnSetValue();
 894
 895     /** Override this to return something else than m_value as the value.
 896     */
 897     virtual wxVariant DoGetValue() const { return m_value; }
 898
 899 #if !defined(SWIG) || defined(CREATE_VCW)
 900     /** Implement this function in derived class to check the value.
 901         Return true if it is ok. Returning false prevents property change events
 902         from occurring.
 903
 904         @remarks
 905         - Default implementation always returns true.
 906     */
 907     virtual bool ValidateValue( wxVariant& value,
 908                                 wxPGValidationInfo& validationInfo ) const;
 909
 910     /**
 911         Converts 'text' into proper value 'variant'.
 912         Returns true if new (different than m_value) value could be interpreted
 913         from the text.
 914         @param argFlags
 915             If wxPG_FULL_VALUE is set, returns complete, storable value instead
 916             of displayable one (they may be different).
 917             If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
 918             composite property string value (as generated by GetValueAsString()
 919             called with this same flag).
 920
 921         @remarks
 922         Default implementation converts semicolon delimited tokens into child
 923         values. Only works for properties with children.
 924     */
 925     virtual bool StringToValue( wxVariant& variant,
 926                                 const wxString& text,
 927                                 int argFlags = 0 ) const;
 928
 929     /**
 930         Converts 'number' (including choice selection) into proper value
 931         'variant'.
 932
 933         Returns true if new (different than m_value) value could be interpreted
 934         from the integer.
 935
 936         @param argFlags
 937             If wxPG_FULL_VALUE is set, returns complete, storable value instead
 938             of displayable one.
 939
 940         @remarks
 941         - If property is not supposed to use choice or spinctrl or other editor
 942           with int-based value, it is not necessary to implement this method.
 943         - Default implementation simply assign given int to m_value.
 944         - If property uses choice control, and displays a dialog on some choice
 945           items, then it is preferred to display that dialog in IntToValue
 946           instead of OnEvent.
 947     */
 948     virtual bool IntToValue( wxVariant& value,
 949                              int number,
 950                              int argFlags = 0 ) const;
 951 #endif  // !defined(SWIG) || defined(CREATE_VCW)
 952
 953 public:
 954     /** Returns text representation of property's value.
 955
 956         @param argFlags
 957             If wxPG_FULL_VALUE is set, returns complete, storable string value
 958             instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
 959             string value that must be editable in textctrl. If
 960             wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
 961             display as a part of composite property string value.
 962
 963         @remarks
 964         Default implementation returns string composed from text
 965         representations of child properties.
 966     */
 967     virtual wxString GetValueAsString( int argFlags = 0 ) const;
 968
 969     /** Converts string to a value, and if successful, calls SetValue() on it.
 970         Default behavior is to do nothing.
 971         @param text
 972         String to get the value from.
 973         @return
 974         true if value was changed.
 975     */
 976     bool SetValueFromString( const wxString& text, int flags = 0 );
 977
 978     /** Converts integer to a value, and if succesful, calls SetValue() on it.
 979         Default behavior is to do nothing.
 980         @param value
 981             Int to get the value from.
 982         @param flags
 983             If has wxPG_FULL_VALUE, then the value given is a actual value and
 984             not an index.
 985         @return
 986             True if value was changed.
 987     */
 988     bool SetValueFromInt( long value, int flags = 0 );
 989
 990     /**
 991         Returns size of the custom painted image in front of property.
 992
 993         This method must be overridden to return non-default value if
 994         OnCustomPaint is to be called.
 995         @param item
 996             Normally -1, but can be an index to the property's list of items.
 997         @remarks
 998         - Default behavior is to return wxSize(0,0), which means no image.
 999         - Default image width or height is indicated with dimension -1.
1000         - You can also return wxPG_DEFAULT_IMAGE_SIZE, i.e. wxSize(-1, -1).
1001     */
1002     virtual wxSize OnMeasureImage( int item = -1 ) const;
1003
1004     /**
1005         Events received by editor widgets are processed here.
1006
1007         Note that editor class usually processes most events. Some, such as
1008         button press events of TextCtrlAndButton class, can be handled here.
1009         Also, if custom handling for regular events is desired, then that can
1010         also be done (for example, wxSystemColourProperty custom handles
1011         wxEVT_COMMAND_CHOICE_SELECTED to display colour picker dialog when
1012         'custom' selection is made).
1013
1014         If the event causes value to be changed, SetValueInEvent()
1015         should be called to set the new value.
1016
1017         @param event
1018         Associated wxEvent.
1019         @return
1020         Should return true if any changes in value should be reported.
1021         @remarks
1022         If property uses choice control, and displays a dialog on some choice
1023         items, then it is preferred to display that dialog in IntToValue
1024         instead of OnEvent.
1025     */
1026     virtual bool OnEvent( wxPropertyGrid* propgrid,
1027                           wxWindow* wnd_primary,
1028                           wxEvent& event );
1029
1030     /**
1031         Called after value of a child property has been altered.
1032
1033         Note that this function is usually called at the time that value of
1034         this property, or given child property, is still pending for change.
1035
1036         Sample pseudo-code implementation:
1037
1038         @code
1039         void MyProperty::ChildChanged( wxVariant& thisValue,
1040                                        int childIndex,
1041                                        wxVariant& childValue ) const
1042         {
1043             // Acquire reference to actual type of data stored in variant
1044             // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros
1045             // were used to create the variant class).
1046             T& data = TFromVariant(thisValue);
1047
1048             // Copy childValue into data.
1049             switch ( childIndex )
1050             {
1051                 case 0:
1052                     data.SetSubProp1( childvalue.GetLong() );
1053                     break;
1054                 case 1:
1055                     data.SetSubProp2( childvalue.GetString() );
1056                     break;
1057                 ...
1058             }
1059         }
1060         @endcode
1061
1062         @param thisValue
1063             Value of this property, that should be altered.
1064         @param childIndex
1065             Index of child changed (you can use Item(childIndex) to get).
1066         @param childValue
1067             Value of the child property.
1068     */
1069     virtual void ChildChanged( wxVariant& thisValue,
1070                                int childIndex,
1071                                wxVariant& childValue ) const;
1072
1073     /** Returns pointer to an instance of used editor.
1074     */
1075     virtual const wxPGEditor* DoGetEditorClass() const;
1076
1077     /** Returns pointer to the wxValidator that should be used
1078         with the editor of this property (NULL for no validator).
1079         Setting validator explicitly via SetPropertyValidator
1080         will override this.
1081
1082         In most situations, code like this should work well
1083         (macros are used to maintain one actual validator instance,
1084         so on the second call the function exits within the first
1085         macro):
1086
1087         @code
1088
1089         wxValidator* wxMyPropertyClass::DoGetValidator () const
1090         {
1091             WX_PG_DOGETVALIDATOR_ENTRY()
1092
1093             wxMyValidator* validator = new wxMyValidator(...);
1094
1095             ... prepare validator...
1096
1097             WX_PG_DOGETVALIDATOR_EXIT(validator)
1098         }
1099
1100         @endcode
1101
1102         @remarks
1103         You can get common filename validator by returning
1104         wxFileProperty::GetClassValidator(). wxDirProperty,
1105         for example, uses it.
1106     */
1107     virtual wxValidator* DoGetValidator () const;
1108
1109     /**
1110         Returns current value's index to the choice control.
1111
1112         May also return, through pointer arguments, strings that should be
1113         inserted to that control. Irrelevant to classes which do not employ
1114         wxPGEditor_Choice or similar.
1115
1116         @remarks
1117         - If returns NULL in choiceinfo.m_choices, then this class must be
1118           derived from wxBaseEnumProperty.
1119         - Must be able to cope situation where property's set of choices is
1120           uninitialized.
1121     */
1122     virtual int GetChoiceInfo( wxPGChoiceInfo* choiceinfo );
1123
1124     /**
1125         Override to paint an image in front of the property value text or
1126         drop-down list item (but only if wxPGProperty::OnMeasureImage is
1127         overridden as well).
1128
1129         If property's OnMeasureImage() returns size that has height != 0 but
1130         less than row height ( < 0 has special meanings), wxPropertyGrid calls
1131         this method to draw a custom image in a limited area in front of the
1132         editor control or value text/graphics, and if control has drop-down
1133         list, then the image is drawn there as well (even in the case
1134         OnMeasureImage() returned higher height than row height).
1135
1136         NOTE: Following applies when OnMeasureImage() returns a "flexible"
1137         height ( using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable
1138         height items: If rect.x is < 0, then this is a measure item call, which
1139         means that dc is invalid and only thing that should be done is to set
1140         paintdata.m_drawnHeight to the height of the image of item at index
1141         paintdata.m_choiceItem. This call may be done even as often as once
1142         every drop-down popup show.
1143
1144         @param dc
1145             wxDC to paint on.
1146         @param rect
1147             Box reserved for custom graphics. Includes surrounding rectangle,
1148             if any. If x is < 0, then this is a measure item call (see above).
1149         @param paintdata
1150             wxPGPaintData structure with much useful data.
1151
1152         @remarks
1153             - You can actually exceed rect width, but if you do so then
1154               paintdata.m_drawnWidth must be set to the full width drawn in
1155               pixels.
1156             - Due to technical reasons, rect's height will be default even if
1157               custom height was reported during measure call.
1158             - Brush is guaranteed to be default background colour. It has been
1159               already used to clear the background of area being painted. It
1160               can be modified.
1161             - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper
1162               colour) pen for drawing framing rectangle. It can be changed as
1163               well.
1164
1165         @see GetValueAsString()
1166     */
1167     virtual void OnCustomPaint( wxDC& dc,
1168                                 const wxRect& rect,
1169                                 wxPGPaintData& paintdata );
1170
1171     /**
1172         Returns used wxPGCellRenderer instance for given property column
1173         (label=0, value=1).
1174
1175         Default implementation returns editor's renderer for all columns.
1176     */
1177     virtual wxPGCellRenderer* GetCellRenderer( int column ) const;
1178
1179     /**
1180         Refresh values of child properties.
1181
1182         Automatically called after value is set.
1183     */
1184     virtual void RefreshChildren();
1185
1186     /** Special handling for attributes of this property.
1187
1188         If returns false, then the attribute will be automatically stored in
1189         m_attributes.
1190
1191         Default implementation simply returns false.
1192     */
1193     virtual bool DoSetAttribute( const wxString& name, wxVariant& value );
1194
1195     /** Returns value of an attribute.
1196
1197         Override if custom handling of attributes is needed.
1198
1199         Default implementation simply return NULL variant.
1200     */
1201     virtual wxVariant DoGetAttribute( const wxString& name ) const;
1202
1203     /** Returns instance of a new wxPGEditorDialogAdapter instance, which is
1204         used when user presses the (optional) button next to the editor control;
1205
1206         Default implementation returns NULL (ie. no action is generated when
1207         button is pressed).
1208     */
1209     virtual wxPGEditorDialogAdapter* GetEditorDialog() const;
1210
1211     /**
1212         Adds entry to property's wxPGChoices and editor control (if it is
1213         active).
1214
1215         Returns index of item added.
1216     */
1217     int AppendChoice( const wxString& label, int value = wxPG_INVALID_VALUE )
1218     {
1219         return InsertChoice(label,-1,value);
1220     }
1221
1222     /** Returns wxPGCell of given column, NULL if none. If valid
1223         object is returned, caller will gain its ownership.
1224     */
1225     wxPGCell* AcquireCell( unsigned int column )
1226     {
1227         if ( column >= m_cells.size() )
1228             return NULL;
1229
1230         wxPGCell* cell = (wxPGCell*) m_cells[column];
1231         m_cells[column] = NULL;
1232         return cell;
1233     }
1234
1235     /**
1236         Returns true if children of this property are component values (for
1237         instance, points size, face name, and is_underlined are component
1238         values of a font).
1239     */
1240     bool AreChildrenComponents() const
1241     {
1242         if ( m_flags & (wxPG_PROP_COMPOSED_VALUE|wxPG_PROP_AGGREGATE) )
1243             return true;
1244
1245         return false;
1246     }
1247
1248     /**
1249         Removes entry from property's wxPGChoices and editor control (if it is
1250         active).
1251
1252         If selected item is deleted, then the value is set to unspecified.
1253     */
1254     void DeleteChoice( int index );
1255
1256     /**
1257         Call to enable or disable usage of common value (integer value that can
1258         be selected for properties instead of their normal values) for this
1259         property.
1260
1261         Common values are disabled by the default for all properties.
1262     */
1263     void EnableCommonValue( bool enable = true )
1264     {
1265         if ( enable ) SetFlag( wxPG_PROP_USES_COMMON_VALUE );
1266         else ClearFlag( wxPG_PROP_USES_COMMON_VALUE );
1267     }
1268
1269     /** Composes text from values of child properties. */
1270     void GenerateComposedValue( wxString& text, int argFlags = 0 ) const;
1271
1272     /** Returns property's label. */
1273     const wxString& GetLabel() const { return m_label; }
1274
1275     /** Returns property's name with all (non-category, non-root) parents. */
1276     wxString GetName() const;
1277
1278     /**
1279         Returns property's base name (ie parent's name is not added in any
1280         case)
1281      */
1282     const wxString& GetBaseName() const { return m_name; }
1283
1284     wxPGChoices& GetChoices();
1285
1286     const wxPGChoices& GetChoices() const;
1287
1288     const wxPGChoiceEntry* GetCurrentChoice() const;
1289
1290     /** Returns coordinate to the top y of the property. Note that the
1291         position of scrollbars is not taken into account.
1292     */
1293     int GetY() const;
1294
1295     wxVariant GetValue() const
1296     {
1297         return DoGetValue();
1298     }
1299
1300 #ifndef SWIG
1301     /** Returns reference to the internal stored value. GetValue is preferred
1302         way to get the actual value, since GetValueRef ignores DoGetValue,
1303         which may override stored value.
1304     */
1305     wxVariant& GetValueRef()
1306     {
1307         return m_value;
1308     }
1309
1310     const wxVariant& GetValueRef() const
1311     {
1312         return m_value;
1313     }
1314 #endif
1315
1316     /** Same as GetValueAsString, except takes common value into account.
1317     */
1318     wxString GetValueString( int argFlags = 0 ) const;
1319
1320     void UpdateControl( wxWindow* primary );
1321
1322     /** Returns wxPGCell of given column, NULL if none. wxPGProperty
1323         will retain ownership of the cell object.
1324     */
1325     wxPGCell* GetCell( unsigned int column ) const
1326     {
1327         if ( column >= m_cells.size() )
1328             return NULL;
1329
1330         return (wxPGCell*) m_cells[column];
1331     }
1332
1333     unsigned int GetChoiceCount() const;
1334
1335     wxString GetChoiceString( unsigned int index );
1336
1337     /** Return number of displayed common values for this property.
1338     */
1339     int GetDisplayedCommonValueCount() const;
1340
1341     wxString GetDisplayedString() const
1342     {
1343         return GetValueString(0);
1344     }
1345
1346     /** Returns property grid where property lies. */
1347     wxPropertyGrid* GetGrid() const;
1348
1349     /** Returns owner wxPropertyGrid, but only if one is currently on a page
1350         displaying this property. */
1351     wxPropertyGrid* GetGridIfDisplayed() const;
1352
1353     /** Returns highest level non-category, non-root parent. Useful when you
1354         have nested wxCustomProperties/wxParentProperties.
1355         @remarks
1356         Thus, if immediate parent is root or category, this will return the
1357         property itself.
1358     */
1359     wxPGProperty* GetMainParent() const;
1360
1361     /** Return parent of property */
1362     wxPGProperty* GetParent() const { return m_parent; }
1363
1364     /** Returns true if property has editable wxTextCtrl when selected.
1365
1366         @remarks
1367         Altough disabled properties do not displayed editor, they still
1368         return True here as being disabled is considered a temporary
1369         condition (unlike being read-only or having limited editing enabled).
1370     */
1371     bool IsTextEditable() const;
1372
1373     bool IsValueUnspecified() const
1374     {
1375         return m_value.IsNull();
1376     }
1377
1378     FlagType HasFlag( FlagType flag ) const
1379     {
1380         return ( m_flags & flag );
1381     }
1382
1383     /** Returns comma-delimited string of property attributes.
1384     */
1385     const wxPGAttributeStorage& GetAttributes() const
1386     {
1387         return m_attributes;
1388     }
1389
1390     /** Returns m_attributes as list wxVariant.
1391     */
1392     wxVariant GetAttributesAsList() const;
1393
1394     FlagType GetFlags() const
1395     {
1396         return m_flags;
1397     }
1398
1399     const wxPGEditor* GetEditorClass() const;
1400
1401     wxString GetValueType() const
1402     {
1403         return m_value.GetType();
1404     }
1405
1406     /** Returns editor used for given column. NULL for no editor.
1407     */
1408     const wxPGEditor* GetColumnEditor( int column ) const
1409     {
1410         if ( column == 1 )
1411             return GetEditorClass();
1412
1413         return NULL;
1414     }
1415
1416     /** Returns common value selected for this property. -1 for none.
1417     */
1418     int GetCommonValue() const
1419     {
1420         return m_commonValue;
1421     }
1422
1423     /** Returns true if property has even one visible child.
1424     */
1425     bool HasVisibleChildren() const;
1426
1427     /**
1428         Adds entry to property's wxPGChoices and editor control (if it is
1429         active).
1430
1431         Returns index of item added.
1432     */
1433     int InsertChoice( const wxString& label,
1434                       int index,
1435                       int value = wxPG_INVALID_VALUE );
1436
1437     /**
1438         Returns true if this property is actually a wxPropertyCategory.
1439     */
1440     bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY)?true:false; }
1441
1442     /** Returns true if this property is actually a wxRootProperty.
1443     */
1444     bool IsRoot() const { return (m_parent == NULL); }
1445
1446     /** Returns true if this is a sub-property. */
1447     bool IsSubProperty() const
1448     {
1449         wxPGProperty* parent = (wxPGProperty*)m_parent;
1450         if ( parent && !parent->IsCategory() )
1451             return true;
1452         return false;
1453     }
1454
1455     /** Returns last visible sub-property, recursively.
1456     */
1457     const wxPGProperty* GetLastVisibleSubItem() const;
1458
1459     wxVariant GetDefaultValue() const;
1460
1461     int GetMaxLength() const
1462     {
1463         return (int) m_maxLen;
1464     }
1465
1466     /**
1467         Determines, recursively, if all children are not unspecified.
1468
1469         Takes values in given list into account.
1470     */
1471     bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const;
1472
1473     /** Updates composed values of parent non-category properties, recursively.
1474         Returns topmost property updated.
1475
1476         @remarks
1477         - Must not call SetValue() (as can be called in it).
1478     */
1479     wxPGProperty* UpdateParentValues();
1480
1481     /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
1482     */
1483     FlagType UsesAutoUnspecified() const
1484     {
1485         return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED);
1486     }
1487
1488     wxBitmap* GetValueImage() const
1489     {
1490         return m_valueBitmap;
1491     }
1492
1493     wxVariant GetAttribute( const wxString& name ) const;
1494
1495     /**
1496         Returns named attribute, as string, if found.
1497
1498         Otherwise defVal is returned.
1499     */
1500     wxString GetAttribute( const wxString& name, const wxString& defVal ) const;
1501
1502     /**
1503         Returns named attribute, as long, if found.
1504
1505         Otherwise defVal is returned.
1506     */
1507     long GetAttributeAsLong( const wxString& name, long defVal ) const;
1508
1509     /**
1510         Returns named attribute, as double, if found.
1511
1512         Otherwise defVal is returned.
1513     */
1514     double GetAttributeAsDouble( const wxString& name, double defVal ) const;
1515
1516     unsigned int GetArrIndex() const { return m_arrIndex; }
1517
1518     unsigned int GetDepth() const { return (unsigned int)m_depth; }
1519
1520     /** Gets flags as a'|' delimited string. Note that flag names are not
1521         prepended with 'wxPG_PROP_'.
1522         @param flagsMask
1523         String will only be made to include flags combined by this parameter.
1524     */
1525     wxString GetFlagsAsString( FlagType flagsMask ) const;
1526
1527     /** Returns position in parent's array. */
1528     unsigned int GetIndexInParent() const
1529     {
1530         return (unsigned int)m_arrIndex;
1531     }
1532
1533     /** Hides or reveals the property.
1534         @param hide
1535             true for hide, false for reveal.
1536         @param flags
1537             By default changes are applied recursively. Set this paramter
1538             wxPG_DONT_RECURSE to prevent this.
1539     */
1540     inline bool Hide( bool hide, int flags = wxPG_RECURSE );
1541
1542     bool IsExpanded() const
1543         { return (!(m_flags & wxPG_PROP_COLLAPSED) && GetChildCount()); }
1544
1545     /** Returns true if all parents expanded.
1546     */
1547     bool IsVisible() const;
1548
1549     bool IsEnabled() const { return !(m_flags & wxPG_PROP_DISABLED); }
1550
1551     /** If property's editor is created this forces its recreation.
1552         Useful in SetAttribute etc. Returns true if actually did anything.
1553     */
1554     bool RecreateEditor();
1555
1556     /** If property's editor is active, then update it's value.
1557     */
1558     void RefreshEditor();
1559
1560     /** Sets an attribute for this property.
1561         @param name
1562         Text identifier of attribute. See @ref propgrid_property_attributes.
1563         @param value
1564         Value of attribute.
1565     */
1566     void SetAttribute( const wxString& name, wxVariant value );
1567
1568     void SetAttributes( const wxPGAttributeStorage& attributes );
1569
1570 #ifndef SWIG
1571     /** Sets editor for a property.
1572
1573         @param editor
1574             For builtin editors, use wxPGEditor_X, where X is builtin editor's
1575             name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
1576             list).
1577
1578         For custom editors, use pointer you received from
1579         wxPropertyGrid::RegisterEditorClass().
1580     */
1581     void SetEditor( const wxPGEditor* editor )
1582     {
1583         m_customEditor = editor;
1584     }
1585 #endif
1586
1587     /** Sets editor for a property.
1588     */
1589     inline void SetEditor( const wxString& editorName );
1590
1591     /** Sets cell information for given column.
1592
1593         Note that the property takes ownership of given wxPGCell instance.
1594     */
1595     void SetCell( int column, wxPGCell* cellObj );
1596
1597     /** Changes value of a property with choices, but only
1598         works if the value type is long or string. */
1599     void SetChoiceSelection( int newValue, const wxPGChoiceInfo& choiceInfo );
1600
1601     /** Sets common value selected for this property. -1 for none.
1602     */
1603     void SetCommonValue( int commonValue )
1604     {
1605         m_commonValue = commonValue;
1606     }
1607
1608     /** Sets flags from a '|' delimited string. Note that flag names are not
1609         prepended with 'wxPG_PROP_'.
1610     */
1611     void SetFlagsFromString( const wxString& str );
1612
1613     /** Sets property's "is it modified?" flag. Affects children recursively.
1614     */
1615     void SetModifiedStatus( bool modified )
1616     {
1617         SetFlagRecursively(wxPG_PROP_MODIFIED, modified);
1618     }
1619
1620     /** Call in OnEvent(), OnButtonClick() etc. to change the property value
1621         based on user input.
1622
1623         @remarks
1624         This method is const since it doesn't actually modify value, but posts
1625         given variant as pending value, stored in wxPropertyGrid.
1626     */
1627     void SetValueInEvent( wxVariant value ) const;
1628
1629     /**
1630         Call this to set value of the property.
1631
1632         Unlike methods in wxPropertyGrid, this does not automatically update
1633         the display.
1634
1635         @remarks
1636         Use wxPropertyGrid::ChangePropertyValue() instead if you need to run
1637         through validation process and send property change event.
1638
1639         If you need to change property value in event, based on user input, use
1640         SetValueInEvent() instead.
1641
1642         @param pList
1643         Pointer to list variant that contains child values. Used to indicate
1644         which children should be marked as modified.
1645         @param flags
1646         Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR).
1647     */
1648     void SetValue( wxVariant value, wxVariant* pList = NULL, int flags = 0 );
1649
1650     /** Set wxBitmap in front of the value. This bitmap may be ignored
1651         by custom cell renderers.
1652     */
1653     void SetValueImage( wxBitmap& bmp );
1654
1655     /** If property has choices and they are not yet exclusive, new such copy
1656         of them will be created.
1657     */
1658     void SetChoicesExclusive();
1659
1660     void SetExpanded( bool expanded )
1661     {
1662         if ( !expanded ) m_flags |= wxPG_PROP_COLLAPSED;
1663         else m_flags &= ~wxPG_PROP_COLLAPSED;
1664     }
1665
1666     void SetFlag( FlagType flag ) { m_flags |= flag; }
1667
1668     void SetFlagRecursively( FlagType flag, bool set );
1669
1670     void SetHelpString( const wxString& helpString )
1671     {
1672         m_helpString = helpString;
1673     }
1674
1675     void SetLabel( const wxString& label ) { m_label = label; }
1676
1677     inline void SetName( const wxString& newName );
1678
1679     void SetValueToUnspecified()
1680     {
1681         wxVariant val;  // Create NULL variant
1682         SetValue(val);
1683     }
1684
1685 #if wxUSE_VALIDATORS
1686     /** Sets wxValidator for a property*/
1687     void SetValidator( const wxValidator& validator )
1688     {
1689         m_validator = wxDynamicCast(validator.Clone(),wxValidator);
1690     }
1691
1692     /** Gets assignable version of property's validator. */
1693     wxValidator* GetValidator() const
1694     {
1695         if ( m_validator )
1696             return m_validator;
1697         return DoGetValidator();
1698     }
1699 #endif // #if wxUSE_VALIDATORS
1700
1701     /** Updates property value in case there were last minute
1702         changes. If value was unspecified, it will be set to default.
1703         Use only for properties that have TextCtrl-based editor.
1704         @remarks
1705         If you have code similar to
1706         @code
1707             // Update the value in case of last minute changes
1708             if ( primary && propgrid->IsEditorsValueModified() )
1709                  GetEditorClass()->CopyValueFromControl( this, primary );
1710         @endcode
1711         in wxPGProperty::OnEvent wxEVT_COMMAND_BUTTON_CLICKED handler,
1712         then replace it with call to this method.
1713         @return
1714         True if value changed.
1715     */
1716     bool PrepareValueForDialogEditing( wxPropertyGrid* propgrid );
1717
1718 #ifndef SWIG
1719     /** Returns client data (void*) of a property.
1720     */
1721     void* GetClientData() const
1722     {
1723         return m_clientData;
1724     }
1725
1726     /** Sets client data (void*) of a property.
1727         @remarks
1728         This untyped client data has to be deleted manually.
1729     */
1730     void SetClientData( void* clientData )
1731     {
1732         m_clientData = clientData;
1733     }
1734
1735     /** Returns client object of a property.
1736     */
1737     void SetClientObject(wxClientData* clientObject)
1738     {
1739         delete m_clientObject;
1740         m_clientObject = clientObject;
1741     }
1742
1743     /** Sets managed client object of a property.
1744     */
1745     wxClientData *GetClientObject() const { return m_clientObject; }
1746 #endif
1747
1748     /** Sets new set of choices for property.
1749
1750         @remarks
1751         This operation clears the property value.
1752     */
1753     bool SetChoices( wxPGChoices& choices );
1754
1755     /** Sets new set of choices for property.
1756     */
1757     inline bool SetChoices( const wxArrayString& labels,
1758                             const wxArrayInt& values = wxArrayInt() );
1759
1760     /** Set max length of text in text editor.
1761     */
1762     inline bool SetMaxLength( int maxLen );
1763
1764     /** Call with 'false' in OnSetValue to cancel value changes after all
1765         (ie. cancel 'true' returned by StringToValue() or IntToValue()).
1766     */
1767     void SetWasModified( bool set = true )
1768     {
1769         if ( set ) m_flags |= wxPG_PROP_WAS_MODIFIED;
1770         else m_flags &= ~wxPG_PROP_WAS_MODIFIED;
1771     }
1772
1773     const wxString& GetHelpString() const
1774     {
1775         return m_helpString;
1776     }
1777
1778     void ClearFlag( FlagType flag ) { m_flags &= ~(flag); }
1779
1780     // Use, for example, to detect if item is inside collapsed section.
1781     bool IsSomeParent( wxPGProperty* candidate_parent ) const;
1782
1783     /**
1784         Adapts list variant into proper value using consecutive
1785         ChildChanged-calls.
1786     */
1787     void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
1788
1789     /** This is used by properties that have fixed sub-properties. */
1790     void AddChild( wxPGProperty* prop );
1791
1792     /** Returns height of children, recursively, and
1793         by taking expanded/collapsed status into account.
1794
1795         iMax is used when finding property y-positions.
1796     */
1797     int GetChildrenHeight( int lh, int iMax = -1 ) const;
1798
1799     /** Returns number of child properties */
1800     unsigned int GetChildCount() const { return m_children.GetCount(); }
1801
1802     /** Returns sub-property at index i. */
1803     wxPGProperty* Item( size_t i ) const
1804         { return (wxPGProperty*)m_children.Item(i); }
1805
1806     /** Returns last sub-property.
1807     */
1808     wxPGProperty* Last() const { return (wxPGProperty*)m_children.Last(); }
1809
1810     /** Returns index of given sub-property. */
1811     int Index( const wxPGProperty* p ) const
1812         { return m_children.Index((wxPGProperty*)p); }
1813
1814     /** Deletes all sub-properties. */
1815     void Empty();
1816
1817     // Puts correct indexes to children
1818     void FixIndexesOfChildren( size_t starthere = 0 );
1819
1820 #ifndef SWIG
1821     // Returns wxPropertyGridPageState in which this property resides.
1822     wxPropertyGridPageState* GetParentState() const { return m_parentState; }
1823 #endif
1824
1825     wxPGProperty* GetItemAtY( unsigned int y,
1826                               unsigned int lh,
1827                               unsigned int* nextItemY ) const;
1828
1829     /** Returns (direct) child property with given name (or NULL if not found).
1830     */
1831     wxPGProperty* GetPropertyByName( const wxString& name ) const;
1832
1833 #ifdef SWIG
1834      %extend {
1835         DocStr(GetClientData,
1836                "Returns the client data object for a property", "");
1837         PyObject* GetClientData() {
1838             wxPyClientData* data = (wxPyClientData*)self->GetClientObject();
1839             if (data) {
1840                 Py_INCREF(data->m_obj);
1841                 return data->m_obj;
1842             } else {
1843                 Py_INCREF(Py_None);
1844                 return Py_None;
1845             }
1846         }
1847
1848         DocStr(SetClientData,
1849                "Associate the given client data.", "");
1850         void SetClientData(PyObject* clientData) {
1851             wxPyClientData* data = new wxPyClientData(clientData);
1852             self->SetClientObject(data);
1853         }
1854     }
1855     %pythoncode {
1856          GetClientObject = GetClientData
1857          SetClientObject = SetClientData
1858     }
1859 #endif
1860
1861 #ifndef SWIG
1862
1863     static wxString*            sm_wxPG_LABEL;
1864
1865     /** This member is public so scripting language bindings
1866         wrapper code can access it freely.
1867     */
1868     void*                       m_clientData;
1869
1870 protected:
1871     /** Returns text for given column.
1872     */
1873     wxString GetColumnText( unsigned int col ) const;
1874
1875     /** Returns (direct) child property with given name (or NULL if not found),
1876         with hint index.
1877
1878         @param hintIndex
1879         Start looking for the child at this index.
1880
1881         @remarks
1882         Does not support scope (ie. Parent.Child notation).
1883     */
1884     wxPGProperty* GetPropertyByNameWH( const wxString& name,
1885                                        unsigned int hintIndex ) const;
1886
1887     /** This is used by Insert etc. */
1888     void AddChild2( wxPGProperty* prop,
1889                     int index = -1,
1890                     bool correct_mode = true );
1891
1892     void DoSetName(const wxString& str) { m_name = str; }
1893
1894     // Call for after sub-properties added with AddChild
1895     void PrepareSubProperties();
1896
1897     void SetParentalType( int flag )
1898     {
1899         m_flags &= ~(wxPG_PROP_PROPERTY|wxPG_PROP_PARENTAL_FLAGS);
1900         m_flags |= flag;
1901     }
1902
1903     void SetParentState( wxPropertyGridPageState* pstate )
1904         { m_parentState = pstate; }
1905
1906     // Call after fixed sub-properties added/removed after creation.
1907     // if oldSelInd >= 0 and < new max items, then selection is
1908     // moved to it.
1909     void SubPropsChanged( int oldSelInd = -1 );
1910
1911     int GetY2( int lh ) const;
1912
1913     wxString                    m_label;
1914     wxString                    m_name;
1915     wxPGProperty*               m_parent;
1916     wxPropertyGridPageState*        m_parentState;
1917
1918     wxClientData*               m_clientObject;
1919
1920     // Overrides editor returned by property class
1921     const wxPGEditor*           m_customEditor;
1922 #if wxUSE_VALIDATORS
1923     // Editor is going to get this validator
1924     wxValidator*                m_validator;
1925 #endif
1926     // Show this in front of the value
1927     //
1928     // TODO: Can bitmap be implemented with wxPGCell?
1929     wxBitmap*                   m_valueBitmap;
1930
1931     wxVariant                   m_value;
1932     wxPGAttributeStorage        m_attributes;
1933     wxArrayPtrVoid              m_children;
1934
1935     // Extended cell information
1936     wxArrayPtrVoid              m_cells;
1937
1938     // Help shown in statusbar or help box.
1939     wxString                    m_helpString;
1940
1941     // Index in parent's property array.
1942     unsigned int                m_arrIndex;
1943
1944     // If not -1, then overrides m_value
1945     int                         m_commonValue;
1946
1947     FlagType                    m_flags;
1948
1949     // Maximum length (mainly for string properties). Could be in some sort of
1950     // wxBaseStringProperty, but currently, for maximum flexibility and
1951     // compatibility, we'll stick it here. Anyway, we had 3 excess bytes to use
1952     // so short int will fit in just fine.
1953     short                       m_maxLen;
1954
1955     // Root has 0, categories etc. at that level 1, etc.
1956     unsigned char               m_depth;
1957
1958     // m_depthBgCol indicates width of background colour between margin and item
1959     // (essentially this is category's depth, if none then equals m_depth).
1960     unsigned char               m_depthBgCol;
1961
1962     unsigned char               m_bgColIndex; // Background brush index.
1963     unsigned char               m_fgColIndex; // Foreground colour index.
1964
1965 private:
1966     // Called in constructors.
1967     void Init();
1968     void Init( const wxString& label, const wxString& name );
1969 #endif // #ifndef SWIG
1970 };
1971
1972 // -----------------------------------------------------------------------
1973
1974 //
1975 // Property class declaration helper macros
1976 // (wxPGRootPropertyClass and wxPropertyCategory require this).
1977 //
1978
1979 #define WX_PG_DECLARE_DOGETEDITORCLASS \
1980     virtual const wxPGEditor* DoGetEditorClass() const;
1981
1982 #ifndef SWIG
1983     #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME) \
1984         public: \
1985             DECLARE_DYNAMIC_CLASS(CLASSNAME) \
1986             WX_PG_DECLARE_DOGETEDITORCLASS \
1987         private:
1988 #else
1989     #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME)
1990 #endif
1991
1992 // Implements sans constructor function. Also, first arg is class name, not
1993 // property name.
1994 #define WX_PG_IMPLEMENT_PROPERTY_CLASS_PLAIN(PROPNAME,T,EDITOR) \
1995 const wxPGEditor* PROPNAME::DoGetEditorClass() const \
1996 { \
1997     return wxPGEditor_##EDITOR; \
1998 }
1999
2000 // -----------------------------------------------------------------------
2001
2002 #ifndef SWIG
2003
2004 /** @class wxPGRootProperty
2005     @ingroup classes
2006     Root parent property.
2007 */
2008 class WXDLLIMPEXP_PROPGRID wxPGRootProperty : public wxPGProperty
2009 {
2010 public:
2011     WX_PG_DECLARE_PROPERTY_CLASS(wxPGRootProperty)
2012 public:
2013
2014     /** Constructor. */
2015     wxPGRootProperty();
2016     virtual ~wxPGRootProperty();
2017
2018     virtual bool StringToValue( wxVariant&, const wxString&, int ) const
2019     {
2020         return false;
2021     }
2022
2023 protected:
2024 };
2025
2026 // -----------------------------------------------------------------------
2027
2028 /** @class wxPropertyCategory
2029     @ingroup classes
2030     Category (caption) property.
2031 */
2032 class WXDLLIMPEXP_PROPGRID wxPropertyCategory : public wxPGProperty
2033 {
2034     friend class wxPropertyGrid;
2035     friend class wxPropertyGridPageState;
2036     WX_PG_DECLARE_PROPERTY_CLASS(wxPropertyCategory)
2037 public:
2038
2039     /** Default constructor is only used in special cases. */
2040     wxPropertyCategory();
2041
2042     wxPropertyCategory( const wxString& label,
2043                         const wxString& name = wxPG_LABEL );
2044     ~wxPropertyCategory();
2045
2046     int GetTextExtent( const wxWindow* wnd, const wxFont& font ) const;
2047
2048 protected:
2049     virtual wxString GetValueAsString( int argFlags ) const;
2050
2051     void SetTextColIndex( unsigned int colInd )
2052         { m_capFgColIndex = (wxByte) colInd; }
2053     unsigned int GetTextColIndex() const
2054         { return (unsigned int) m_capFgColIndex; }
2055
2056     void CalculateTextExtent( wxWindow* wnd, const wxFont& font );
2057
2058     int     m_textExtent;  // pre-calculated length of text
2059     wxByte  m_capFgColIndex;  // caption text colour index
2060
2061 private:
2062     void Init();
2063 };
2064
2065 #endif  // !SWIG
2066
2067 // -----------------------------------------------------------------------
2068
2069 #ifndef SWIG
2070
2071 /** @class wxPGChoiceEntry
2072     Data of a single wxPGChoices choice.
2073 */
2074 class WXDLLIMPEXP_PROPGRID wxPGChoiceEntry : public wxPGCell
2075 {
2076 public:
2077     wxPGChoiceEntry();
2078     wxPGChoiceEntry( const wxPGChoiceEntry& entry );
2079     wxPGChoiceEntry( const wxString& label,
2080                      int value = wxPG_INVALID_VALUE )
2081         : wxPGCell(), m_value(value)
2082     {
2083         m_text = label;
2084     }
2085
2086     wxPGChoiceEntry( const wxString& label,
2087                      int value,
2088                      const wxBitmap& bitmap,
2089                      const wxColour& fgCol = wxNullColour,
2090                      const wxColour& bgCol = wxNullColour )
2091         : wxPGCell(label, bitmap, fgCol, bgCol), m_value(value)
2092     {
2093     }
2094
2095     virtual ~wxPGChoiceEntry()
2096     {
2097     }
2098
2099     void SetValue( int value ) { m_value = value; }
2100
2101     int GetValue() const { return m_value; }
2102
2103     bool HasValue() const { return (m_value != wxPG_INVALID_VALUE); }
2104
2105 protected:
2106     int m_value;
2107 };
2108
2109
2110 typedef void* wxPGChoicesId;
2111
2112 class WXDLLIMPEXP_PROPGRID wxPGChoicesData
2113 {
2114     friend class wxPGChoices;
2115 public:
2116     // Constructor sets m_refCount to 1.
2117     wxPGChoicesData();
2118
2119     void CopyDataFrom( wxPGChoicesData* data );
2120
2121     // Takes ownership of 'item'
2122     void Insert( int index, wxPGChoiceEntry* item )
2123     {
2124         wxArrayPtrVoid::iterator it;
2125         if ( index == -1 )
2126         {
2127             it = m_items.end();
2128             index = m_items.size();
2129         }
2130         else
2131         {
2132             it = m_items.begin() + index;
2133         }
2134
2135         // Need to fix value?
2136         if ( item->GetValue() == wxPG_INVALID_VALUE )
2137             item->SetValue(index);
2138
2139         m_items.insert(it, item);
2140     }
2141
2142     // Delete all entries
2143     void Clear();
2144
2145     size_t GetCount() const { return m_items.size(); }
2146
2147     wxPGChoiceEntry* Item( unsigned int i ) const
2148     {
2149         wxCHECK_MSG( i < GetCount(), NULL, "invalid index" );
2150
2151         return (wxPGChoiceEntry*) m_items[i];
2152     }
2153
2154     void DecRef()
2155     {
2156         m_refCount--;
2157         wxASSERT( m_refCount >= 0 );
2158         if ( m_refCount == 0 )
2159             delete this;
2160     }
2161
2162 private:
2163     wxArrayPtrVoid  m_items;
2164
2165     // So that multiple properties can use the same set
2166     int             m_refCount;
2167
2168     virtual ~wxPGChoicesData();
2169 };
2170
2171 #define wxPGChoicesEmptyData    ((wxPGChoicesData*)NULL)
2172
2173 #endif // SWIG
2174
2175
2176 /** @class wxPGChoices
2177
2178     Helper class for managing choices of wxPropertyGrid properties.
2179     Each entry can have label, value, bitmap, text colour, and background
2180     colour.
2181
2182     @library{wxpropgrid}
2183     @category{propgrid}
2184 */
2185 class WXDLLIMPEXP_PROPGRID wxPGChoices
2186 {
2187 public:
2188     typedef long ValArrItem;
2189
2190     /** Default constructor. */
2191     wxPGChoices()
2192     {
2193         Init();
2194     }
2195
2196     /** Copy constructor. */
2197     wxPGChoices( const wxPGChoices& a )
2198     {
2199         if ( a.m_data != wxPGChoicesEmptyData )
2200         {
2201             m_data = a.m_data;
2202             m_data->m_refCount++;
2203         }
2204     }
2205
2206     /** Constructor. */
2207     wxPGChoices( const wxChar** labels, const long* values = NULL )
2208     {
2209         Init();
2210         Set(labels,values);
2211     }
2212
2213     /** Constructor. */
2214     wxPGChoices( const wxArrayString& labels,
2215                  const wxArrayInt& values = wxArrayInt() )
2216     {
2217         Init();
2218         Set(labels,values);
2219     }
2220
2221     /** Simple interface constructor. */
2222     wxPGChoices( wxPGChoicesData* data )
2223     {
2224         wxASSERT(data);
2225         m_data = data;
2226         data->m_refCount++;
2227     }
2228
2229     /** Destructor. */
2230     ~wxPGChoices()
2231     {
2232         Free();
2233     }
2234
2235     /**
2236         Adds to current.
2237
2238         If did not have own copies, creates them now. If was empty, identical
2239         to set except that creates copies.
2240     */
2241     void Add( const wxChar** labels, const ValArrItem* values = NULL );
2242
2243     /** Version that works with wxArrayString. */
2244     void Add( const wxArrayString& arr, const ValArrItem* values = NULL );
2245
2246     /** Version that works with wxArrayString and wxArrayInt. */
2247     void Add( const wxArrayString& arr, const wxArrayInt& arrint );
2248
2249     /** Adds single item. */
2250     wxPGChoiceEntry& Add( const wxString& label,
2251                           int value = wxPG_INVALID_VALUE );
2252
2253     /** Adds a single item, with bitmap. */
2254     wxPGChoiceEntry& Add( const wxString& label,
2255                           const wxBitmap& bitmap,
2256                           int value = wxPG_INVALID_VALUE );
2257
2258     /** Adds a single item with full entry information. */
2259     wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry )
2260     {
2261         return Insert(entry, -1);
2262     }
2263
2264     /** Adds single item. */
2265     wxPGChoiceEntry& AddAsSorted( const wxString& label,
2266                                   int value = wxPG_INVALID_VALUE );
2267
2268     void Assign( const wxPGChoices& a )
2269     {
2270         AssignData(a.m_data);
2271     }
2272
2273     void AssignData( wxPGChoicesData* data );
2274
2275     /** Delete all choices. */
2276     void Clear()
2277     {
2278         if ( m_data != wxPGChoicesEmptyData )
2279             m_data->Clear();
2280     }
2281
2282     void EnsureData()
2283     {
2284         if ( m_data == wxPGChoicesEmptyData )
2285             m_data = new wxPGChoicesData();
2286     }
2287
2288     /** Gets a unsigned number identifying this list. */
2289     wxPGChoicesId GetId() const { return (wxPGChoicesId) m_data; };
2290
2291     const wxString& GetLabel( size_t ind ) const
2292     {
2293         return Item(ind).GetText();
2294     }
2295
2296     size_t GetCount () const
2297     {
2298         wxASSERT_MSG( m_data, "When checking if wxPGChoices is valid, "
2299                               "use IsOk() instead of GetCount()" );
2300         return m_data->GetCount();
2301     }
2302
2303     int GetValue( size_t ind ) const { return Item(ind).GetValue(); }
2304
2305     /** Returns array of values matching the given strings. Unmatching strings
2306         result in wxPG_INVALID_VALUE entry in array.
2307     */
2308     wxArrayInt GetValuesForStrings( const wxArrayString& strings ) const;
2309
2310     /** Returns array of indices matching given strings. Unmatching strings
2311         are added to 'unmatched', if not NULL.
2312     */
2313     wxArrayInt GetIndicesForStrings( const wxArrayString& strings,
2314                                      wxArrayString* unmatched = NULL ) const;
2315
2316     /** Returns true if choices in general are likely to have values
2317         (depens on that all entries have values or none has)
2318     */
2319     bool HasValues() const;
2320
2321     bool HasValue( unsigned int i ) const
2322         { return (i < m_data->GetCount()) && m_data->Item(i)->HasValue(); }
2323
2324     int Index( const wxString& str ) const;
2325     int Index( int val ) const;
2326
2327     /** Inserts single item. */
2328     wxPGChoiceEntry& Insert( const wxString& label,
2329                              int index,
2330                              int value = wxPG_INVALID_VALUE );
2331
2332     /** Inserts a single item with full entry information. */
2333     wxPGChoiceEntry& Insert( const wxPGChoiceEntry& entry, int index );
2334
2335     /** Returns false if this is a constant empty set of choices,
2336         which should not be modified.
2337     */
2338     bool IsOk() const
2339     {
2340         return ( m_data != wxPGChoicesEmptyData );
2341     }
2342
2343     const wxPGChoiceEntry& Item( unsigned int i ) const
2344     {
2345         wxASSERT( IsOk() );
2346         return *m_data->Item(i);
2347     }
2348
2349     wxPGChoiceEntry& Item( unsigned int i )
2350     {
2351         wxASSERT( IsOk() );
2352         return *m_data->Item(i);
2353     }
2354
2355     /** Removes count items starting at position nIndex. */
2356     void RemoveAt(size_t nIndex, size_t count = 1);
2357
2358 #ifndef SWIG
2359     /** Does not create copies for itself. */
2360     void Set( const wxChar** labels, const long* values = NULL )
2361     {
2362         Free();
2363         Add(labels,values);
2364     }
2365
2366     /** Version that works with wxArrayString.
2367         TODO: Deprecate this.
2368     */
2369     void Set( wxArrayString& arr, const long* values = (const long*) NULL )
2370     {
2371         Free();
2372         Add(arr,values);
2373     }
2374 #endif // SWIG
2375
2376     /** Version that works with wxArrayString and wxArrayInt. */
2377     void Set( const wxArrayString& labels,
2378               const wxArrayInt& values = wxArrayInt() )
2379     {
2380         Free();
2381         if ( &values )
2382             Add(labels,values);
2383         else
2384             Add(labels);
2385     }
2386
2387     // Creates exclusive copy of current choices
2388     void SetExclusive()
2389     {
2390         if ( m_data->m_refCount != 1 )
2391         {
2392             wxPGChoicesData* data = new wxPGChoicesData();
2393             data->CopyDataFrom(m_data);
2394             Free();
2395             m_data = data;
2396         }
2397     }
2398
2399     // Returns data, increases refcount.
2400     wxPGChoicesData* GetData()
2401     {
2402         wxASSERT( m_data->m_refCount != 0xFFFFFFF );
2403         m_data->m_refCount++;
2404         return m_data;
2405     }
2406
2407     // Returns plain data ptr - no refcounting stuff is done.
2408     wxPGChoicesData* GetDataPtr() const { return m_data; }
2409
2410     // Changes ownership of data to you.
2411     wxPGChoicesData* ExtractData()
2412     {
2413         wxPGChoicesData* data = m_data;
2414         m_data = wxPGChoicesEmptyData;
2415         return data;
2416     }
2417
2418     wxArrayString GetLabels() const;
2419
2420 #ifndef SWIG
2421     void operator= (const wxPGChoices& a)
2422     {
2423         AssignData(a.m_data);
2424     }
2425
2426     wxPGChoiceEntry& operator[](unsigned int i)
2427     {
2428         return Item(i);
2429     }
2430
2431     const wxPGChoiceEntry& operator[](unsigned int i) const
2432     {
2433         return Item(i);
2434     }
2435
2436 protected:
2437     wxPGChoicesData*    m_data;
2438
2439     void Init();
2440     void Free();
2441 #endif  // !SWIG
2442 };
2443
2444 inline bool wxPGProperty::SetChoices( const wxArrayString& labels,
2445                                       const wxArrayInt& values )
2446 {
2447     wxPGChoices chs(labels, values);
2448     return SetChoices(chs);
2449 }
2450
2451 // -----------------------------------------------------------------------
2452
2453 #endif // _WX_PROPGRID_PROPERTY_H_