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