include/wx/propgrid/property.h

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