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