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>
 817     You can use macros declared in wxPropertyGrid headers. For instance:
 818
 819     @code
 820         // In header file:
 821         // (If you need to have export declaration, use version of macros
 822         // with _EXPORTED postfix)
 823         WX_PG_DECLARE_VARIANT_DATA(MyDataClass)
 824
 825         // In sources file:
 826         WX_PG_IMPLEMENT_VARIANT_DATA(MyDataClass)
 827
 828         // Or, if you don't have valid == operator:
 829         WX_PG_IMPLEMENT_VARIANT_DATA_DUMMY_EQ(MyDataClass)
 830     @endcode
 831
 832     @library{wxpropgrid}
 833     @category{propgrid}
 834 */
 835 class WXDLLIMPEXP_PROPGRID wxPGProperty : public wxObject
 836 {
 837     friend class wxPropertyGrid;
 838     friend class wxPropertyGridInterface;
 839     friend class wxPropertyGridPageState;
 840     friend class wxPropertyGridPopulator;
 841     friend class wxStringProperty;  // Proper "<composed>" support requires this
 842 #ifndef SWIG
 843     DECLARE_ABSTRACT_CLASS(wxPGProperty)
 844 #endif
 845 public:
 846     typedef wxUint32 FlagType;
 847
 848     /** Basic constructor.
 849     */
 850     wxPGProperty();
 851
 852     /** Constructor.
 853         Non-abstract property classes should have constructor of this style:
 854
 855         @code
 856
 857         // If T is a class, then it should be a constant reference
 858         // (e.g. const T& ) instead.
 859         MyProperty( const wxString& label, const wxString& name, T value )
 860             : wxPGProperty()
 861         {
 862             // Generally recommended way to set the initial value
 863             // (as it should work in pretty much 100% of cases).
 864             wxVariant variant;
 865             variant << value;
 866             SetValue(variant);
 867
 868             // If has private child properties then create them here, e.g.:
 869             //     AddChild( new wxStringProperty( "Subprop 1",
 870             //                                     wxPG_LABEL,
 871             //                                     value.GetSubProp1() ) );
 872         }
 873
 874         @endcode
 875     */
 876     wxPGProperty( const wxString& label, const wxString& name );
 877
 878     /**
 879         Virtual destructor.
 880         It is customary for derived properties to implement this.
 881     */
 882     virtual ~wxPGProperty();
 883
 884     /** This virtual function is called after m_value has been set.
 885
 886         @remarks
 887         - If m_value was set to Null variant (ie. unspecified value),
 888           OnSetValue() will not be called.
 889         - m_value may be of any variant type. Typically properties internally
 890           support only one variant type, and as such OnSetValue() provides a
 891           good opportunity to convert
 892           supported values into internal type.
 893         - Default implementation does nothing.
 894     */
 895     virtual void OnSetValue();
 896
 897     /** Override this to return something else than m_value as the value.
 898     */
 899     virtual wxVariant DoGetValue() const { return m_value; }
 900
 901 #if !defined(SWIG) || defined(CREATE_VCW)
 902     /** Implement this function in derived class to check the value.
 903         Return true if it is ok. Returning false prevents property change events
 904         from occurring.
 905
 906         @remarks
 907         - Default implementation always returns true.
 908     */
 909     virtual bool ValidateValue( wxVariant& value,
 910                                 wxPGValidationInfo& validationInfo ) const;
 911
 912     /**
 913         Converts 'text' into proper value 'variant'.
 914         Returns true if new (different than m_value) value could be interpreted
 915         from the text.
 916         @param argFlags
 917             If wxPG_FULL_VALUE is set, returns complete, storable value instead
 918             of displayable one (they may be different).
 919             If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
 920             composite property string value (as generated by GetValueAsString()
 921             called with this same flag).
 922
 923         @remarks
 924         Default implementation converts semicolon delimited tokens into child
 925         values. Only works for properties with children.
 926     */
 927     virtual bool StringToValue( wxVariant& variant,
 928                                 const wxString& text,
 929                                 int argFlags = 0 ) const;
 930
 931     /**
 932         Converts 'number' (including choice selection) into proper value
 933         'variant'.
 934
 935         Returns true if new (different than m_value) value could be interpreted
 936         from the integer.
 937
 938         @param argFlags
 939             If wxPG_FULL_VALUE is set, returns complete, storable value instead
 940             of displayable one.
 941
 942         @remarks
 943         - If property is not supposed to use choice or spinctrl or other editor
 944           with int-based value, it is not necessary to implement this method.
 945         - Default implementation simply assign given int to m_value.
 946         - If property uses choice control, and displays a dialog on some choice
 947           items, then it is preferred to display that dialog in IntToValue
 948           instead of OnEvent.
 949     */
 950     virtual bool IntToValue( wxVariant& value,
 951                              int number,
 952                              int argFlags = 0 ) const;
 953 #endif  // !defined(SWIG) || defined(CREATE_VCW)
 954
 955 public:
 956     /** Returns text representation of property's value.
 957
 958         @param argFlags
 959             If wxPG_FULL_VALUE is set, returns complete, storable string value
 960             instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
 961             string value that must be editable in textctrl. If
 962             wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
 963             display as a part of composite property string value.
 964
 965         @remarks
 966         Default implementation returns string composed from text
 967         representations of child properties.
 968     */
 969     virtual wxString GetValueAsString( int argFlags = 0 ) const;
 970
 971     /** Converts string to a value, and if successful, calls SetValue() on it.
 972         Default behavior is to do nothing.
 973         @param text
 974         String to get the value from.
 975         @return
 976         true if value was changed.
 977     */
 978     bool SetValueFromString( const wxString& text, int flags = 0 );
 979
 980     /** Converts integer to a value, and if succesful, calls SetValue() on it.
 981         Default behavior is to do nothing.
 982         @param value
 983             Int to get the value from.
 984         @param flags
 985             If has wxPG_FULL_VALUE, then the value given is a actual value and
 986             not an index.
 987         @return
 988             True if value was changed.
 989     */
 990     bool SetValueFromInt( long value, int flags = 0 );
 991
 992     /**
 993         Returns size of the custom painted image in front of property.
 994
 995         This method must be overridden to return non-default value if
 996         OnCustomPaint is to be called.
 997         @param item
 998             Normally -1, but can be an index to the property's list of items.
 999         @remarks
1000         - Default behavior is to return wxSize(0,0), which means no image.
1001         - Default image width or height is indicated with dimension -1.
1002         - You can also return wxPG_DEFAULT_IMAGE_SIZE, i.e. wxSize(-1, -1).
1003     */
1004     virtual wxSize OnMeasureImage( int item = -1 ) const;
1005
1006     /**
1007         Events received by editor widgets are processed here.
1008
1009         Note that editor class usually processes most events. Some, such as
1010         button press events of TextCtrlAndButton class, can be handled here.
1011         Also, if custom handling for regular events is desired, then that can
1012         also be done (for example, wxSystemColourProperty custom handles
1013         wxEVT_COMMAND_CHOICE_SELECTED to display colour picker dialog when
1014         'custom' selection is made).
1015
1016         If the event causes value to be changed, SetValueInEvent()
1017         should be called to set the new value.
1018
1019         @param event
1020         Associated wxEvent.
1021         @return
1022         Should return true if any changes in value should be reported.
1023         @remarks
1024         If property uses choice control, and displays a dialog on some choice
1025         items, then it is preferred to display that dialog in IntToValue
1026         instead of OnEvent.
1027     */
1028     virtual bool OnEvent( wxPropertyGrid* propgrid,
1029                           wxWindow* wnd_primary,
1030                           wxEvent& event );
1031
1032     /**
1033         Called after value of a child property has been altered.
1034
1035         Note that this function is usually called at the time that value of
1036         this property, or given child property, is still pending for change.
1037
1038         Sample pseudo-code implementation:
1039
1040         @code
1041         void MyProperty::ChildChanged( wxVariant& thisValue,
1042                                        int childIndex,
1043                                        wxVariant& childValue ) const
1044         {
1045             // Acquire reference to actual type of data stored in variant
1046             // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros
1047             // were used to create the variant class).
1048             T& data = TFromVariant(thisValue);
1049
1050             // Copy childValue into data.
1051             switch ( childIndex )
1052             {
1053                 case 0:
1054                     data.SetSubProp1( childvalue.GetLong() );
1055                     break;
1056                 case 1:
1057                     data.SetSubProp2( childvalue.GetString() );
1058                     break;
1059                 ...
1060             }
1061         }
1062         @endcode
1063
1064         @param thisValue
1065             Value of this property, that should be altered.
1066         @param childIndex
1067             Index of child changed (you can use Item(childIndex) to get).
1068         @param childValue
1069             Value of the child property.
1070     */
1071     virtual void ChildChanged( wxVariant& thisValue,
1072                                int childIndex,
1073                                wxVariant& childValue ) const;
1074
1075     /** Returns pointer to an instance of used editor.
1076     */
1077     virtual const wxPGEditor* DoGetEditorClass() const;
1078
1079     /** Returns pointer to the wxValidator that should be used
1080         with the editor of this property (NULL for no validator).
1081         Setting validator explicitly via SetPropertyValidator
1082         will override this.
1083
1084         In most situations, code like this should work well
1085         (macros are used to maintain one actual validator instance,
1086         so on the second call the function exits within the first
1087         macro):
1088
1089         @code
1090
1091         wxValidator* wxMyPropertyClass::DoGetValidator () const
1092         {
1093             WX_PG_DOGETVALIDATOR_ENTRY()
1094
1095             wxMyValidator* validator = new wxMyValidator(...);
1096
1097             ... prepare validator...
1098
1099             WX_PG_DOGETVALIDATOR_EXIT(validator)
1100         }
1101
1102         @endcode
1103
1104         @remarks
1105         You can get common filename validator by returning
1106         wxFileProperty::GetClassValidator(). wxDirProperty,
1107         for example, uses it.
1108     */
1109     virtual wxValidator* DoGetValidator () const;
1110
1111     /**
1112         Returns current value's index to the choice control.
1113
1114         May also return, through pointer arguments, strings that should be
1115         inserted to that control. Irrelevant to classes which do not employ
1116         wxPGEditor_Choice or similar.
1117
1118         @remarks
1119         - If returns NULL in choiceinfo.m_choices, then this class must be
1120           derived from wxBaseEnumProperty.
1121         - Must be able to cope situation where property's set of choices is
1122           uninitialized.
1123     */
1124     virtual int GetChoiceInfo( wxPGChoiceInfo* choiceinfo );
1125
1126     /**
1127         Override to paint an image in front of the property value text or
1128         drop-down list item (but only if wxPGProperty::OnMeasureImage is
1129         overridden as well).
1130
1131         If property's OnMeasureImage() returns size that has height != 0 but
1132         less than row height ( < 0 has special meanings), wxPropertyGrid calls
1133         this method to draw a custom image in a limited area in front of the
1134         editor control or value text/graphics, and if control has drop-down
1135         list, then the image is drawn there as well (even in the case
1136         OnMeasureImage() returned higher height than row height).
1137
1138         NOTE: Following applies when OnMeasureImage() returns a "flexible"
1139         height ( using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable
1140         height items: If rect.x is < 0, then this is a measure item call, which
1141         means that dc is invalid and only thing that should be done is to set
1142         paintdata.m_drawnHeight to the height of the image of item at index
1143         paintdata.m_choiceItem. This call may be done even as often as once
1144         every drop-down popup show.
1145
1146         @param dc
1147             wxDC to paint on.
1148         @param rect
1149             Box reserved for custom graphics. Includes surrounding rectangle,
1150             if any. If x is < 0, then this is a measure item call (see above).
1151         @param paintdata
1152             wxPGPaintData structure with much useful data.
1153
1154         @remarks
1155             - You can actually exceed rect width, but if you do so then
1156               paintdata.m_drawnWidth must be set to the full width drawn in
1157               pixels.
1158             - Due to technical reasons, rect's height will be default even if
1159               custom height was reported during measure call.
1160             - Brush is guaranteed to be default background colour. It has been
1161               already used to clear the background of area being painted. It
1162               can be modified.
1163             - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper
1164               colour) pen for drawing framing rectangle. It can be changed as
1165               well.
1166
1167         @see GetValueAsString()
1168     */
1169     virtual void OnCustomPaint( wxDC& dc,
1170                                 const wxRect& rect,
1171                                 wxPGPaintData& paintdata );
1172
1173     /**
1174         Returns used wxPGCellRenderer instance for given property column
1175         (label=0, value=1).
1176
1177         Default implementation returns editor's renderer for all columns.
1178     */
1179     virtual wxPGCellRenderer* GetCellRenderer( int column ) const;
1180
1181     /**
1182         Refresh values of child properties.
1183
1184         Automatically called after value is set.
1185     */
1186     virtual void RefreshChildren();
1187
1188     /** Special handling for attributes of this property.
1189
1190         If returns false, then the attribute will be automatically stored in
1191         m_attributes.
1192
1193         Default implementation simply returns false.
1194     */
1195     virtual bool DoSetAttribute( const wxString& name, wxVariant& value );
1196
1197     /** Returns value of an attribute.
1198
1199         Override if custom handling of attributes is needed.
1200
1201         Default implementation simply return NULL variant.
1202     */
1203     virtual wxVariant DoGetAttribute( const wxString& name ) const;
1204
1205     /** Returns instance of a new wxPGEditorDialogAdapter instance, which is
1206         used when user presses the (optional) button next to the editor control;
1207
1208         Default implementation returns NULL (ie. no action is generated when
1209         button is pressed).
1210     */
1211     virtual wxPGEditorDialogAdapter* GetEditorDialog() const;
1212
1213     /**
1214         Adds entry to property's wxPGChoices and editor control (if it is
1215         active).
1216
1217         Returns index of item added.
1218     */
1219     int AppendChoice( const wxString& label, int value = wxPG_INVALID_VALUE )
1220     {
1221         return InsertChoice(label,-1,value);
1222     }
1223
1224     /** Returns wxPGCell of given column, NULL if none. If valid
1225         object is returned, caller will gain its ownership.
1226     */
1227     wxPGCell* AcquireCell( unsigned int column )
1228     {
1229         if ( column >= m_cells.size() )
1230             return NULL;
1231
1232         wxPGCell* cell = (wxPGCell*) m_cells[column];
1233         m_cells[column] = NULL;
1234         return cell;
1235     }
1236
1237     /**
1238         Returns true if children of this property are component values (for
1239         instance, points size, face name, and is_underlined are component
1240         values of a font).
1241     */
1242     bool AreChildrenComponents() const
1243     {
1244         if ( m_flags & (wxPG_PROP_COMPOSED_VALUE|wxPG_PROP_AGGREGATE) )
1245             return true;
1246
1247         return false;
1248     }
1249
1250     /**
1251         Removes entry from property's wxPGChoices and editor control (if it is
1252         active).
1253
1254         If selected item is deleted, then the value is set to unspecified.
1255     */
1256     void DeleteChoice( int index );
1257
1258     /**
1259         Call to enable or disable usage of common value (integer value that can
1260         be selected for properties instead of their normal values) for this
1261         property.
1262
1263         Common values are disabled by the default for all properties.
1264     */
1265     void EnableCommonValue( bool enable = true )
1266     {
1267         if ( enable ) SetFlag( wxPG_PROP_USES_COMMON_VALUE );
1268         else ClearFlag( wxPG_PROP_USES_COMMON_VALUE );
1269     }
1270
1271     /** Composes text from values of child properties. */
1272     void GenerateComposedValue( wxString& text, int argFlags = 0 ) const;
1273
1274     /** Returns property's label. */
1275     const wxString& GetLabel() const { return m_label; }
1276
1277     /** Returns property's name with all (non-category, non-root) parents. */
1278     wxString GetName() const;
1279
1280     /**
1281         Returns property's base name (ie parent's name is not added in any
1282         case)
1283      */
1284     const wxString& GetBaseName() const { return m_name; }
1285
1286     wxPGChoices& GetChoices();
1287
1288     const wxPGChoices& GetChoices() const;
1289
1290     const wxPGChoiceEntry* GetCurrentChoice() const;
1291
1292     /** Returns coordinate to the top y of the property. Note that the
1293         position of scrollbars is not taken into account.
1294     */
1295     int GetY() const;
1296
1297     wxVariant GetValue() const
1298     {
1299         return DoGetValue();
1300     }
1301
1302 #ifndef SWIG
1303     /** Returns reference to the internal stored value. GetValue is preferred
1304         way to get the actual value, since GetValueRef ignores DoGetValue,
1305         which may override stored value.
1306     */
1307     wxVariant& GetValueRef()
1308     {
1309         return m_value;
1310     }
1311
1312     const wxVariant& GetValueRef() const
1313     {
1314         return m_value;
1315     }
1316 #endif
1317
1318     /** Same as GetValueAsString, except takes common value into account.
1319     */
1320     wxString GetValueString( int argFlags = 0 ) const;
1321
1322     void UpdateControl( wxWindow* primary );
1323
1324     /** Returns wxPGCell of given column, NULL if none. wxPGProperty
1325         will retain ownership of the cell object.
1326     */
1327     wxPGCell* GetCell( unsigned int column ) const
1328     {
1329         if ( column >= m_cells.size() )
1330             return NULL;
1331
1332         return (wxPGCell*) m_cells[column];
1333     }
1334
1335     unsigned int GetChoiceCount() const;
1336
1337     wxString GetChoiceString( unsigned int index );
1338
1339     /** Return number of displayed common values for this property.
1340     */
1341     int GetDisplayedCommonValueCount() const;
1342
1343     wxString GetDisplayedString() const
1344     {
1345         return GetValueString(0);
1346     }
1347
1348     /** Returns property grid where property lies. */
1349     wxPropertyGrid* GetGrid() const;
1350
1351     /** Returns owner wxPropertyGrid, but only if one is currently on a page
1352         displaying this property. */
1353     wxPropertyGrid* GetGridIfDisplayed() const;
1354
1355     /** Returns highest level non-category, non-root parent. Useful when you
1356         have nested wxCustomProperties/wxParentProperties.
1357         @remarks
1358         Thus, if immediate parent is root or category, this will return the
1359         property itself.
1360     */
1361     wxPGProperty* GetMainParent() const;
1362
1363     /** Return parent of property */
1364     wxPGProperty* GetParent() const { return m_parent; }
1365
1366     /** Returns true if property has editable wxTextCtrl when selected.
1367
1368         @remarks
1369         Altough disabled properties do not displayed editor, they still
1370         return True here as being disabled is considered a temporary
1371         condition (unlike being read-only or having limited editing enabled).
1372     */
1373     bool IsTextEditable() const;
1374
1375     bool IsValueUnspecified() const
1376     {
1377         return m_value.IsNull();
1378     }
1379
1380     FlagType HasFlag( FlagType flag ) const
1381     {
1382         return ( m_flags & flag );
1383     }
1384
1385     /** Returns comma-delimited string of property attributes.
1386     */
1387     const wxPGAttributeStorage& GetAttributes() const
1388     {
1389         return m_attributes;
1390     }
1391
1392     /** Returns m_attributes as list wxVariant.
1393     */
1394     wxVariant GetAttributesAsList() const;
1395
1396     FlagType GetFlags() const
1397     {
1398         return m_flags;
1399     }
1400
1401     const wxPGEditor* GetEditorClass() const;
1402
1403     wxString GetValueType() const
1404     {
1405         return m_value.GetType();
1406     }
1407
1408     /** Returns editor used for given column. NULL for no editor.
1409     */
1410     const wxPGEditor* GetColumnEditor( int column ) const
1411     {
1412         if ( column == 1 )
1413             return GetEditorClass();
1414
1415         return NULL;
1416     }
1417
1418     /** Returns common value selected for this property. -1 for none.
1419     */
1420     int GetCommonValue() const
1421     {
1422         return m_commonValue;
1423     }
1424
1425     /** Returns true if property has even one visible child.
1426     */
1427     bool HasVisibleChildren() const;
1428
1429     /**
1430         Adds entry to property's wxPGChoices and editor control (if it is
1431         active).
1432
1433         Returns index of item added.
1434     */
1435     int InsertChoice( const wxString& label,
1436                       int index,
1437                       int value = wxPG_INVALID_VALUE );
1438
1439     /**
1440         Returns true if this property is actually a wxPropertyCategory.
1441     */
1442     bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY)?true:false; }
1443
1444     /** Returns true if this property is actually a wxRootProperty.
1445     */
1446     bool IsRoot() const { return (m_parent == NULL); }
1447
1448     /** Returns true if this is a sub-property. */
1449     bool IsSubProperty() const
1450     {
1451         wxPGProperty* parent = (wxPGProperty*)m_parent;
1452         if ( parent && !parent->IsCategory() )
1453             return true;
1454         return false;
1455     }
1456
1457     /** Returns last visible sub-property, recursively.
1458     */
1459     const wxPGProperty* GetLastVisibleSubItem() const;
1460
1461     wxVariant GetDefaultValue() const;
1462
1463     int GetMaxLength() const
1464     {
1465         return (int) m_maxLen;
1466     }
1467
1468     /**
1469         Determines, recursively, if all children are not unspecified.
1470
1471         Takes values in given list into account.
1472     */
1473     bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const;
1474
1475     /** Updates composed values of parent non-category properties, recursively.
1476         Returns topmost property updated.
1477
1478         @remarks
1479         - Must not call SetValue() (as can be called in it).
1480     */
1481     wxPGProperty* UpdateParentValues();
1482
1483     /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
1484     */
1485     FlagType UsesAutoUnspecified() const
1486     {
1487         return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED);
1488     }
1489
1490     wxBitmap* GetValueImage() const
1491     {
1492         return m_valueBitmap;
1493     }
1494
1495     wxVariant GetAttribute( const wxString& name ) const;
1496
1497     /**
1498         Returns named attribute, as string, if found.
1499
1500         Otherwise defVal is returned.
1501     */
1502     wxString GetAttribute( const wxString& name, const wxString& defVal ) const;
1503
1504     /**
1505         Returns named attribute, as long, if found.
1506
1507         Otherwise defVal is returned.
1508     */
1509     long GetAttributeAsLong( const wxString& name, long defVal ) const;
1510
1511     /**
1512         Returns named attribute, as double, if found.
1513
1514         Otherwise defVal is returned.
1515     */
1516     double GetAttributeAsDouble( const wxString& name, double defVal ) const;
1517
1518     unsigned int GetArrIndex() const { return m_arrIndex; }
1519
1520     unsigned int GetDepth() const { return (unsigned int)m_depth; }
1521
1522     /** Gets flags as a'|' delimited string. Note that flag names are not
1523         prepended with 'wxPG_PROP_'.
1524         @param flagsMask
1525         String will only be made to include flags combined by this parameter.
1526     */
1527     wxString GetFlagsAsString( FlagType flagsMask ) const;
1528
1529     /** Returns position in parent's array. */
1530     unsigned int GetIndexInParent() const
1531     {
1532         return (unsigned int)m_arrIndex;
1533     }
1534
1535     /** Hides or reveals the property.
1536         @param hide
1537             true for hide, false for reveal.
1538         @param flags
1539             By default changes are applied recursively. Set this paramter
1540             wxPG_DONT_RECURSE to prevent this.
1541     */
1542     inline bool Hide( bool hide, int flags = wxPG_RECURSE );
1543
1544     bool IsExpanded() const
1545         { return (!(m_flags & wxPG_PROP_COLLAPSED) && GetChildCount()); }
1546
1547     /** Returns true if all parents expanded.
1548     */
1549     bool IsVisible() const;
1550
1551     bool IsEnabled() const { return !(m_flags & wxPG_PROP_DISABLED); }
1552
1553     /** If property's editor is created this forces its recreation.
1554         Useful in SetAttribute etc. Returns true if actually did anything.
1555     */
1556     bool RecreateEditor();
1557
1558     /** If property's editor is active, then update it's value.
1559     */
1560     void RefreshEditor();
1561
1562     /** Sets an attribute for this property.
1563         @param name
1564         Text identifier of attribute. See @ref propgrid_property_attributes.
1565         @param value
1566         Value of attribute.
1567     */
1568     void SetAttribute( const wxString& name, wxVariant value );
1569
1570     void SetAttributes( const wxPGAttributeStorage& attributes );
1571
1572 #ifndef SWIG
1573     /** Sets editor for a property.
1574
1575         @param editor
1576             For builtin editors, use wxPGEditor_X, where X is builtin editor's
1577             name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
1578             list).
1579
1580         For custom editors, use pointer you received from
1581         wxPropertyGrid::RegisterEditorClass().
1582     */
1583     void SetEditor( const wxPGEditor* editor )
1584     {
1585         m_customEditor = editor;
1586     }
1587 #endif
1588
1589     /** Sets editor for a property.
1590     */
1591     inline void SetEditor( const wxString& editorName );
1592
1593     /** Sets cell information for given column.
1594
1595         Note that the property takes ownership of given wxPGCell instance.
1596     */
1597     void SetCell( int column, wxPGCell* cellObj );
1598
1599     /** Changes value of a property with choices, but only
1600         works if the value type is long or string. */
1601     void SetChoiceSelection( int newValue, const wxPGChoiceInfo& choiceInfo );
1602
1603     /** Sets common value selected for this property. -1 for none.
1604     */
1605     void SetCommonValue( int commonValue )
1606     {
1607         m_commonValue = commonValue;
1608     }
1609
1610     /** Sets flags from a '|' delimited string. Note that flag names are not
1611         prepended with 'wxPG_PROP_'.
1612     */
1613     void SetFlagsFromString( const wxString& str );
1614
1615     /** Sets property's "is it modified?" flag. Affects children recursively.
1616     */
1617     void SetModifiedStatus( bool modified )
1618     {
1619         SetFlagRecursively(wxPG_PROP_MODIFIED, modified);
1620     }
1621
1622     /** Call in OnEvent(), OnButtonClick() etc. to change the property value
1623         based on user input.
1624
1625         @remarks
1626         This method is const since it doesn't actually modify value, but posts
1627         given variant as pending value, stored in wxPropertyGrid.
1628     */
1629     void SetValueInEvent( wxVariant value ) const;
1630
1631     /**
1632         Call this to set value of the property.
1633
1634         Unlike methods in wxPropertyGrid, this does not automatically update
1635         the display.
1636
1637         @remarks
1638         Use wxPropertyGrid::ChangePropertyValue() instead if you need to run
1639         through validation process and send property change event.
1640
1641         If you need to change property value in event, based on user input, use
1642         SetValueInEvent() instead.
1643
1644         @param pList
1645         Pointer to list variant that contains child values. Used to indicate
1646         which children should be marked as modified.
1647         @param flags
1648         Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR).
1649     */
1650     void SetValue( wxVariant value, wxVariant* pList = NULL, int flags = 0 );
1651
1652     /** Set wxBitmap in front of the value. This bitmap may be ignored
1653         by custom cell renderers.
1654     */
1655     void SetValueImage( wxBitmap& bmp );
1656
1657     /** If property has choices and they are not yet exclusive, new such copy
1658         of them will be created.
1659     */
1660     void SetChoicesExclusive();
1661
1662     void SetExpanded( bool expanded )
1663     {
1664         if ( !expanded ) m_flags |= wxPG_PROP_COLLAPSED;
1665         else m_flags &= ~wxPG_PROP_COLLAPSED;
1666     }
1667
1668     void SetFlag( FlagType flag ) { m_flags |= flag; }
1669
1670     void SetFlagRecursively( FlagType flag, bool set );
1671
1672     void SetHelpString( const wxString& helpString )
1673     {
1674         m_helpString = helpString;
1675     }
1676
1677     void SetLabel( const wxString& label ) { m_label = label; }
1678
1679     inline void SetName( const wxString& newName );
1680
1681     void SetValueToUnspecified()
1682     {
1683         wxVariant val;  // Create NULL variant
1684         SetValue(val);
1685     }
1686
1687 #if wxUSE_VALIDATORS
1688     /** Sets wxValidator for a property*/
1689     void SetValidator( const wxValidator& validator )
1690     {
1691         m_validator = wxDynamicCast(validator.Clone(),wxValidator);
1692     }
1693
1694     /** Gets assignable version of property's validator. */
1695     wxValidator* GetValidator() const
1696     {
1697         if ( m_validator )
1698             return m_validator;
1699         return DoGetValidator();
1700     }
1701 #endif // #if wxUSE_VALIDATORS
1702
1703     /** Updates property value in case there were last minute
1704         changes. If value was unspecified, it will be set to default.
1705         Use only for properties that have TextCtrl-based editor.
1706         @remarks
1707         If you have code similar to
1708         @code
1709             // Update the value in case of last minute changes
1710             if ( primary && propgrid->IsEditorsValueModified() )
1711                  GetEditorClass()->CopyValueFromControl( this, primary );
1712         @endcode
1713         in wxPGProperty::OnEvent wxEVT_COMMAND_BUTTON_CLICKED handler,
1714         then replace it with call to this method.
1715         @return
1716         True if value changed.
1717     */
1718     bool PrepareValueForDialogEditing( wxPropertyGrid* propgrid );
1719
1720 #ifndef SWIG
1721     /** Returns client data (void*) of a property.
1722     */
1723     void* GetClientData() const
1724     {
1725         return m_clientData;
1726     }
1727
1728     /** Sets client data (void*) of a property.
1729         @remarks
1730         This untyped client data has to be deleted manually.
1731     */
1732     void SetClientData( void* clientData )
1733     {
1734         m_clientData = clientData;
1735     }
1736
1737     /** Returns client object of a property.
1738     */
1739     void SetClientObject(wxClientData* clientObject)
1740     {
1741         delete m_clientObject;
1742         m_clientObject = clientObject;
1743     }
1744
1745     /** Sets managed client object of a property.
1746     */
1747     wxClientData *GetClientObject() const { return m_clientObject; }
1748 #endif
1749
1750     /** Sets new set of choices for property.
1751
1752         @remarks
1753         This operation clears the property value.
1754     */
1755     bool SetChoices( wxPGChoices& choices );
1756
1757     /** Sets new set of choices for property.
1758     */
1759     inline bool SetChoices( const wxArrayString& labels,
1760                             const wxArrayInt& values = wxArrayInt() );
1761
1762     /** Set max length of text in text editor.
1763     */
1764     inline bool SetMaxLength( int maxLen );
1765
1766     /** Call with 'false' in OnSetValue to cancel value changes after all
1767         (ie. cancel 'true' returned by StringToValue() or IntToValue()).
1768     */
1769     void SetWasModified( bool set = true )
1770     {
1771         if ( set ) m_flags |= wxPG_PROP_WAS_MODIFIED;
1772         else m_flags &= ~wxPG_PROP_WAS_MODIFIED;
1773     }
1774
1775     const wxString& GetHelpString() const
1776     {
1777         return m_helpString;
1778     }
1779
1780     void ClearFlag( FlagType flag ) { m_flags &= ~(flag); }
1781
1782     // Use, for example, to detect if item is inside collapsed section.
1783     bool IsSomeParent( wxPGProperty* candidate_parent ) const;
1784
1785     /**
1786         Adapts list variant into proper value using consecutive
1787         ChildChanged-calls.
1788     */
1789     void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
1790
1791     /** This is used by properties that have fixed sub-properties. */
1792     void AddChild( wxPGProperty* prop );
1793
1794     /** Returns height of children, recursively, and
1795         by taking expanded/collapsed status into account.
1796
1797         iMax is used when finding property y-positions.
1798     */
1799     int GetChildrenHeight( int lh, int iMax = -1 ) const;
1800
1801     /** Returns number of child properties */
1802     unsigned int GetChildCount() const { return m_children.GetCount(); }
1803
1804     /** Returns sub-property at index i. */
1805     wxPGProperty* Item( size_t i ) const
1806         { return (wxPGProperty*)m_children.Item(i); }
1807
1808     /** Returns last sub-property.
1809     */
1810     wxPGProperty* Last() const { return (wxPGProperty*)m_children.Last(); }
1811
1812     /** Returns index of given sub-property. */
1813     int Index( const wxPGProperty* p ) const
1814         { return m_children.Index((wxPGProperty*)p); }
1815
1816     /** Deletes all sub-properties. */
1817     void Empty();
1818
1819     // Puts correct indexes to children
1820     void FixIndexesOfChildren( size_t starthere = 0 );
1821
1822 #ifndef SWIG
1823     // Returns wxPropertyGridPageState in which this property resides.
1824     wxPropertyGridPageState* GetParentState() const { return m_parentState; }
1825 #endif
1826
1827     wxPGProperty* GetItemAtY( unsigned int y,
1828                               unsigned int lh,
1829                               unsigned int* nextItemY ) const;
1830
1831     /** Returns (direct) child property with given name (or NULL if not found).
1832     */
1833     wxPGProperty* GetPropertyByName( const wxString& name ) const;
1834
1835 #ifdef SWIG
1836      %extend {
1837         DocStr(GetClientData,
1838                "Returns the client data object for a property", "");
1839         PyObject* GetClientData() {
1840             wxPyClientData* data = (wxPyClientData*)self->GetClientObject();
1841             if (data) {
1842                 Py_INCREF(data->m_obj);
1843                 return data->m_obj;
1844             } else {
1845                 Py_INCREF(Py_None);
1846                 return Py_None;
1847             }
1848         }
1849
1850         DocStr(SetClientData,
1851                "Associate the given client data.", "");
1852         void SetClientData(PyObject* clientData) {
1853             wxPyClientData* data = new wxPyClientData(clientData);
1854             self->SetClientObject(data);
1855         }
1856     }
1857     %pythoncode {
1858          GetClientObject = GetClientData
1859          SetClientObject = SetClientData
1860     }
1861 #endif
1862
1863 #ifndef SWIG
1864
1865     static wxString*            sm_wxPG_LABEL;
1866
1867     /** This member is public so scripting language bindings
1868         wrapper code can access it freely.
1869     */
1870     void*                       m_clientData;
1871
1872 protected:
1873     /** Returns text for given column.
1874     */
1875     wxString GetColumnText( unsigned int col ) const;
1876
1877     /** Returns (direct) child property with given name (or NULL if not found),
1878         with hint index.
1879
1880         @param hintIndex
1881         Start looking for the child at this index.
1882
1883         @remarks
1884         Does not support scope (ie. Parent.Child notation).
1885     */
1886     wxPGProperty* GetPropertyByNameWH( const wxString& name,
1887                                        unsigned int hintIndex ) const;
1888
1889     /** This is used by Insert etc. */
1890     void AddChild2( wxPGProperty* prop,
1891                     int index = -1,
1892                     bool correct_mode = true );
1893
1894     void DoSetName(const wxString& str) { m_name = str; }
1895
1896     // Call for after sub-properties added with AddChild
1897     void PrepareSubProperties();
1898
1899     void SetParentalType( int flag )
1900     {
1901         m_flags &= ~(wxPG_PROP_PROPERTY|wxPG_PROP_PARENTAL_FLAGS);
1902         m_flags |= flag;
1903     }
1904
1905     void SetParentState( wxPropertyGridPageState* pstate )
1906         { m_parentState = pstate; }
1907
1908     // Call after fixed sub-properties added/removed after creation.
1909     // if oldSelInd >= 0 and < new max items, then selection is
1910     // moved to it.
1911     void SubPropsChanged( int oldSelInd = -1 );
1912
1913     int GetY2( int lh ) const;
1914
1915     wxString                    m_label;
1916     wxString                    m_name;
1917     wxPGProperty*               m_parent;
1918     wxPropertyGridPageState*        m_parentState;
1919
1920     wxClientData*               m_clientObject;
1921
1922     // Overrides editor returned by property class
1923     const wxPGEditor*           m_customEditor;
1924 #if wxUSE_VALIDATORS
1925     // Editor is going to get this validator
1926     wxValidator*                m_validator;
1927 #endif
1928     // Show this in front of the value
1929     //
1930     // TODO: Can bitmap be implemented with wxPGCell?
1931     wxBitmap*                   m_valueBitmap;
1932
1933     wxVariant                   m_value;
1934     wxPGAttributeStorage        m_attributes;
1935     wxArrayPtrVoid              m_children;
1936
1937     // Extended cell information
1938     wxArrayPtrVoid              m_cells;
1939
1940     // Help shown in statusbar or help box.
1941     wxString                    m_helpString;
1942
1943     // Index in parent's property array.
1944     unsigned int                m_arrIndex;
1945
1946     // If not -1, then overrides m_value
1947     int                         m_commonValue;
1948
1949     FlagType                    m_flags;
1950
1951     // Maximum length (mainly for string properties). Could be in some sort of
1952     // wxBaseStringProperty, but currently, for maximum flexibility and
1953     // compatibility, we'll stick it here. Anyway, we had 3 excess bytes to use
1954     // so short int will fit in just fine.
1955     short                       m_maxLen;
1956
1957     // Root has 0, categories etc. at that level 1, etc.
1958     unsigned char               m_depth;
1959
1960     // m_depthBgCol indicates width of background colour between margin and item
1961     // (essentially this is category's depth, if none then equals m_depth).
1962     unsigned char               m_depthBgCol;
1963
1964     unsigned char               m_bgColIndex; // Background brush index.
1965     unsigned char               m_fgColIndex; // Foreground colour index.
1966
1967 private:
1968     // Called in constructors.
1969     void Init();
1970     void Init( const wxString& label, const wxString& name );
1971 #endif // #ifndef SWIG
1972 };
1973
1974 // -----------------------------------------------------------------------
1975
1976 //
1977 // Property class declaration helper macros
1978 // (wxPGRootPropertyClass and wxPropertyCategory require this).
1979 //
1980
1981 #define WX_PG_DECLARE_DOGETEDITORCLASS \
1982     virtual const wxPGEditor* DoGetEditorClass() const;
1983
1984 #ifndef SWIG
1985     #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME) \
1986         public: \
1987             DECLARE_DYNAMIC_CLASS(CLASSNAME) \
1988             WX_PG_DECLARE_DOGETEDITORCLASS \
1989         private:
1990 #else
1991     #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME)
1992 #endif
1993
1994 // Implements sans constructor function. Also, first arg is class name, not
1995 // property name.
1996 #define WX_PG_IMPLEMENT_PROPERTY_CLASS_PLAIN(PROPNAME,T,EDITOR) \
1997 const wxPGEditor* PROPNAME::DoGetEditorClass() const \
1998 { \
1999     return wxPGEditor_##EDITOR; \
2000 }
2001
2002 // -----------------------------------------------------------------------
2003
2004 #ifndef SWIG
2005
2006 /** @class wxPGRootProperty
2007     @ingroup classes
2008     Root parent property.
2009 */
2010 class WXDLLIMPEXP_PROPGRID wxPGRootProperty : public wxPGProperty
2011 {
2012 public:
2013     WX_PG_DECLARE_PROPERTY_CLASS(wxPGRootProperty)
2014 public:
2015
2016     /** Constructor. */
2017     wxPGRootProperty();
2018     virtual ~wxPGRootProperty();
2019
2020     virtual bool StringToValue( wxVariant&, const wxString&, int ) const
2021     {
2022         return false;
2023     }
2024
2025 protected:
2026 };
2027
2028 // -----------------------------------------------------------------------
2029
2030 /** @class wxPropertyCategory
2031     @ingroup classes
2032     Category (caption) property.
2033 */
2034 class WXDLLIMPEXP_PROPGRID wxPropertyCategory : public wxPGProperty
2035 {
2036     friend class wxPropertyGrid;
2037     friend class wxPropertyGridPageState;
2038     WX_PG_DECLARE_PROPERTY_CLASS(wxPropertyCategory)
2039 public:
2040
2041     /** Default constructor is only used in special cases. */
2042     wxPropertyCategory();
2043
2044     wxPropertyCategory( const wxString& label,
2045                         const wxString& name = wxPG_LABEL );
2046     ~wxPropertyCategory();
2047
2048     int GetTextExtent( const wxWindow* wnd, const wxFont& font ) const;
2049
2050 protected:
2051     virtual wxString GetValueAsString( int argFlags ) const;
2052
2053     void SetTextColIndex( unsigned int colInd )
2054         { m_capFgColIndex = (wxByte) colInd; }
2055     unsigned int GetTextColIndex() const
2056         { return (unsigned int) m_capFgColIndex; }
2057
2058     void CalculateTextExtent( wxWindow* wnd, const wxFont& font );
2059
2060     int     m_textExtent;  // pre-calculated length of text
2061     wxByte  m_capFgColIndex;  // caption text colour index
2062
2063 private:
2064     void Init();
2065 };
2066
2067 #endif  // !SWIG
2068
2069 // -----------------------------------------------------------------------
2070
2071 #ifndef SWIG
2072
2073 /** @class wxPGChoiceEntry
2074     Data of a single wxPGChoices choice.
2075 */
2076 class WXDLLIMPEXP_PROPGRID wxPGChoiceEntry : public wxPGCell
2077 {
2078 public:
2079     wxPGChoiceEntry();
2080     wxPGChoiceEntry( const wxPGChoiceEntry& entry );
2081     wxPGChoiceEntry( const wxString& label,
2082                      int value = wxPG_INVALID_VALUE )
2083         : wxPGCell(), m_value(value)
2084     {
2085         m_text = label;
2086     }
2087
2088     wxPGChoiceEntry( const wxString& label,
2089                      int value,
2090                      const wxBitmap& bitmap,
2091                      const wxColour& fgCol = wxNullColour,
2092                      const wxColour& bgCol = wxNullColour )
2093         : wxPGCell(label, bitmap, fgCol, bgCol), m_value(value)
2094     {
2095     }
2096
2097     virtual ~wxPGChoiceEntry()
2098     {
2099     }
2100
2101     void SetValue( int value ) { m_value = value; }
2102
2103     int GetValue() const { return m_value; }
2104
2105     bool HasValue() const { return (m_value != wxPG_INVALID_VALUE); }
2106
2107 protected:
2108     int m_value;
2109 };
2110
2111
2112 typedef void* wxPGChoicesId;
2113
2114 class WXDLLIMPEXP_PROPGRID wxPGChoicesData
2115 {
2116     friend class wxPGChoices;
2117 public:
2118     // Constructor sets m_refCount to 1.
2119     wxPGChoicesData();
2120
2121     void CopyDataFrom( wxPGChoicesData* data );
2122
2123     // Takes ownership of 'item'
2124     void Insert( int index, wxPGChoiceEntry* item )
2125     {
2126         wxArrayPtrVoid::iterator it;
2127         if ( index == -1 )
2128         {
2129             it = m_items.end();
2130             index = m_items.size();
2131         }
2132         else
2133         {
2134             it = m_items.begin() + index;
2135         }
2136
2137         // Need to fix value?
2138         if ( item->GetValue() == wxPG_INVALID_VALUE )
2139             item->SetValue(index);
2140
2141         m_items.insert(it, item);
2142     }
2143
2144     // Delete all entries
2145     void Clear();
2146
2147     size_t GetCount() const { return m_items.size(); }
2148
2149     wxPGChoiceEntry* Item( unsigned int i ) const
2150     {
2151         wxCHECK_MSG( i < GetCount(), NULL, "invalid index" );
2152
2153         return (wxPGChoiceEntry*) m_items[i];
2154     }
2155
2156     void DecRef()
2157     {
2158         m_refCount--;
2159         wxASSERT( m_refCount >= 0 );
2160         if ( m_refCount == 0 )
2161             delete this;
2162     }
2163
2164 private:
2165     wxArrayPtrVoid  m_items;
2166
2167     // So that multiple properties can use the same set
2168     int             m_refCount;
2169
2170     virtual ~wxPGChoicesData();
2171 };
2172
2173 #define wxPGChoicesEmptyData    ((wxPGChoicesData*)NULL)
2174
2175 #endif // SWIG
2176
2177
2178 /** @class wxPGChoices
2179
2180     Helper class for managing choices of wxPropertyGrid properties.
2181     Each entry can have label, value, bitmap, text colour, and background
2182     colour.
2183
2184     @library{wxpropgrid}
2185     @category{propgrid}
2186 */
2187 class WXDLLIMPEXP_PROPGRID wxPGChoices
2188 {
2189 public:
2190     typedef long ValArrItem;
2191
2192     /** Default constructor. */
2193     wxPGChoices()
2194     {
2195         Init();
2196     }
2197
2198     /** Copy constructor. */
2199     wxPGChoices( const wxPGChoices& a )
2200     {
2201         if ( a.m_data != wxPGChoicesEmptyData )
2202         {
2203             m_data = a.m_data;
2204             m_data->m_refCount++;
2205         }
2206     }
2207
2208     /** Constructor. */
2209     wxPGChoices( const wxChar** labels, const long* values = NULL )
2210     {
2211         Init();
2212         Set(labels,values);
2213     }
2214
2215     /** Constructor. */
2216     wxPGChoices( const wxArrayString& labels,
2217                  const wxArrayInt& values = wxArrayInt() )
2218     {
2219         Init();
2220         Set(labels,values);
2221     }
2222
2223     /** Simple interface constructor. */
2224     wxPGChoices( wxPGChoicesData* data )
2225     {
2226         wxASSERT(data);
2227         m_data = data;
2228         data->m_refCount++;
2229     }
2230
2231     /** Destructor. */
2232     ~wxPGChoices()
2233     {
2234         Free();
2235     }
2236
2237     /**
2238         Adds to current.
2239
2240         If did not have own copies, creates them now. If was empty, identical
2241         to set except that creates copies.
2242     */
2243     void Add( const wxChar** labels, const ValArrItem* values = NULL );
2244
2245     /** Version that works with wxArrayString. */
2246     void Add( const wxArrayString& arr, const ValArrItem* values = NULL );
2247
2248     /** Version that works with wxArrayString and wxArrayInt. */
2249     void Add( const wxArrayString& arr, const wxArrayInt& arrint );
2250
2251     /** Adds single item. */
2252     wxPGChoiceEntry& Add( const wxString& label,
2253                           int value = wxPG_INVALID_VALUE );
2254
2255     /** Adds a single item, with bitmap. */
2256     wxPGChoiceEntry& Add( const wxString& label,
2257                           const wxBitmap& bitmap,
2258                           int value = wxPG_INVALID_VALUE );
2259
2260     /** Adds a single item with full entry information. */
2261     wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry )
2262     {
2263         return Insert(entry, -1);
2264     }
2265
2266     /** Adds single item. */
2267     wxPGChoiceEntry& AddAsSorted( const wxString& label,
2268                                   int value = wxPG_INVALID_VALUE );
2269
2270     void Assign( const wxPGChoices& a )
2271     {
2272         AssignData(a.m_data);
2273     }
2274
2275     void AssignData( wxPGChoicesData* data );
2276
2277     /** Delete all choices. */
2278     void Clear()
2279     {
2280         if ( m_data != wxPGChoicesEmptyData )
2281             m_data->Clear();
2282     }
2283
2284     void EnsureData()
2285     {
2286         if ( m_data == wxPGChoicesEmptyData )
2287             m_data = new wxPGChoicesData();
2288     }
2289
2290     /** Gets a unsigned number identifying this list. */
2291     wxPGChoicesId GetId() const { return (wxPGChoicesId) m_data; };
2292
2293     const wxString& GetLabel( size_t ind ) const
2294     {
2295         return Item(ind).GetText();
2296     }
2297
2298     size_t GetCount () const
2299     {
2300         wxASSERT_MSG( m_data, "When checking if wxPGChoices is valid, "
2301                               "use IsOk() instead of GetCount()" );
2302         return m_data->GetCount();
2303     }
2304
2305     int GetValue( size_t ind ) const { return Item(ind).GetValue(); }
2306
2307     /** Returns array of values matching the given strings. Unmatching strings
2308         result in wxPG_INVALID_VALUE entry in array.
2309     */
2310     wxArrayInt GetValuesForStrings( const wxArrayString& strings ) const;
2311
2312     /** Returns array of indices matching given strings. Unmatching strings
2313         are added to 'unmatched', if not NULL.
2314     */
2315     wxArrayInt GetIndicesForStrings( const wxArrayString& strings,
2316                                      wxArrayString* unmatched = NULL ) const;
2317
2318     /** Returns true if choices in general are likely to have values
2319         (depens on that all entries have values or none has)
2320     */
2321     bool HasValues() const;
2322
2323     bool HasValue( unsigned int i ) const
2324         { return (i < m_data->GetCount()) && m_data->Item(i)->HasValue(); }
2325
2326     int Index( const wxString& str ) const;
2327     int Index( int val ) const;
2328
2329     /** Inserts single item. */
2330     wxPGChoiceEntry& Insert( const wxString& label,
2331                              int index,
2332                              int value = wxPG_INVALID_VALUE );
2333
2334     /** Inserts a single item with full entry information. */
2335     wxPGChoiceEntry& Insert( const wxPGChoiceEntry& entry, int index );
2336
2337     /** Returns false if this is a constant empty set of choices,
2338         which should not be modified.
2339     */
2340     bool IsOk() const
2341     {
2342         return ( m_data != wxPGChoicesEmptyData );
2343     }
2344
2345     const wxPGChoiceEntry& Item( unsigned int i ) const
2346     {
2347         wxASSERT( IsOk() );
2348         return *m_data->Item(i);
2349     }
2350
2351     wxPGChoiceEntry& Item( unsigned int i )
2352     {
2353         wxASSERT( IsOk() );
2354         return *m_data->Item(i);
2355     }
2356
2357     /** Removes count items starting at position nIndex. */
2358     void RemoveAt(size_t nIndex, size_t count = 1);
2359
2360 #ifndef SWIG
2361     /** Does not create copies for itself. */
2362     void Set( const wxChar** labels, const long* values = NULL )
2363     {
2364         Free();
2365         Add(labels,values);
2366     }
2367
2368     /** Version that works with wxArrayString.
2369         TODO: Deprecate this.
2370     */
2371     void Set( wxArrayString& arr, const long* values = (const long*) NULL )
2372     {
2373         Free();
2374         Add(arr,values);
2375     }
2376 #endif // SWIG
2377
2378     /** Version that works with wxArrayString and wxArrayInt. */
2379     void Set( const wxArrayString& labels,
2380               const wxArrayInt& values = wxArrayInt() )
2381     {
2382         Free();
2383         if ( &values )
2384             Add(labels,values);
2385         else
2386             Add(labels);
2387     }
2388
2389     // Creates exclusive copy of current choices
2390     void SetExclusive()
2391     {
2392         if ( m_data->m_refCount != 1 )
2393         {
2394             wxPGChoicesData* data = new wxPGChoicesData();
2395             data->CopyDataFrom(m_data);
2396             Free();
2397             m_data = data;
2398         }
2399     }
2400
2401     // Returns data, increases refcount.
2402     wxPGChoicesData* GetData()
2403     {
2404         wxASSERT( m_data->m_refCount != 0xFFFFFFF );
2405         m_data->m_refCount++;
2406         return m_data;
2407     }
2408
2409     // Returns plain data ptr - no refcounting stuff is done.
2410     wxPGChoicesData* GetDataPtr() const { return m_data; }
2411
2412     // Changes ownership of data to you.
2413     wxPGChoicesData* ExtractData()
2414     {
2415         wxPGChoicesData* data = m_data;
2416         m_data = wxPGChoicesEmptyData;
2417         return data;
2418     }
2419
2420     wxArrayString GetLabels() const;
2421
2422 #ifndef SWIG
2423     void operator= (const wxPGChoices& a)
2424     {
2425         AssignData(a.m_data);
2426     }
2427
2428     wxPGChoiceEntry& operator[](unsigned int i)
2429     {
2430         return Item(i);
2431     }
2432
2433     const wxPGChoiceEntry& operator[](unsigned int i) const
2434     {
2435         return Item(i);
2436     }
2437
2438 protected:
2439     wxPGChoicesData*    m_data;
2440
2441     void Init();
2442     void Free();
2443 #endif  // !SWIG
2444 };
2445
2446 inline bool wxPGProperty::SetChoices( const wxArrayString& labels,
2447                                       const wxArrayInt& values )
2448 {
2449     wxPGChoices chs(labels, values);
2450     return SetChoices(chs);
2451 }
2452
2453 // -----------------------------------------------------------------------
2454
2455 #endif // _WX_PROPGRID_PROPERTY_H_