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