include/wx/propgrid/property.h

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