include/wx/propgrid/property.h

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