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, that indicates that the actual property
 414     value has failed validation (NB: this behaviour 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 wxFileProperty and derivatives, long, default is 0.
 654     Sets a specific wxFileDialog style for the file dialog.
 655 */
 656 #define wxPG_FILE_DIALOG_STYLE              wxS("DialogStyle")
 657
 658 /** Specific to wxDirProperty, wxString, default is empty.
 659     Sets a specific message for the dir dialog.
 660 */
 661 #define wxPG_DIR_DIALOG_MESSAGE             wxS("DialogMessage")
 662
 663 /**
 664     wxArrayStringProperty's string delimiter character. If this is a quotation
 665     mark or hyphen, then strings will be quoted instead (with given
 666     character).
 667
 668     Default delimiter is quotation mark.
 669 */
 670 #define wxPG_ARRAY_DELIMITER                wxS("Delimiter")
 671
 672 /** Sets displayed date format for wxDateProperty.
 673 */
 674 #define wxPG_DATE_FORMAT                    wxS("DateFormat")
 675
 676 /** Sets wxDatePickerCtrl window style used with wxDateProperty. Default
 677     is wxDP_DEFAULT | wxDP_SHOWCENTURY.
 678 */
 679 #define wxPG_DATE_PICKER_STYLE              wxS("PickerStyle")
 680
 681 /** SpinCtrl editor, int or double. How much number changes when button is
 682     pressed (or up/down on keyboard).
 683 */
 684 #define wxPG_ATTR_SPINCTRL_STEP             wxS("Step")
 685
 686 /** SpinCtrl editor, bool. If true, value wraps at Min/Max.
 687 */
 688 #define wxPG_ATTR_SPINCTRL_WRAP             wxS("Wrap")
 689
 690 /**
 691     wxMultiChoiceProperty, int.
 692     If 0, no user strings allowed. If 1, user strings appear before list
 693     strings. If 2, user strings appear after list string.
 694 */
 695 #define wxPG_ATTR_MULTICHOICE_USERSTRINGMODE    wxS("UserStringMode")
 696
 697 /**
 698     wxColourProperty and its kind, int, default 1.
 699
 700     Setting this attribute to 0 hides custom colour from property's list of
 701     choices.
 702 */
 703 #define wxPG_COLOUR_ALLOW_CUSTOM            wxS("AllowCustom")
 704
 705 /**
 706     wxColourProperty and its kind: Set to True in order to support editing
 707     alpha colour component.
 708 */
 709 #define wxPG_COLOUR_HAS_ALPHA               wxS("HasAlpha")
 710
 711 /** @}
 712 */
 713
 714 // Redefine attribute macros to use cached strings
 715 #undef wxPG_ATTR_DEFAULT_VALUE
 716 #define wxPG_ATTR_DEFAULT_VALUE           wxPGGlobalVars->m_strDefaultValue
 717 #undef wxPG_ATTR_MIN
 718 #define wxPG_ATTR_MIN                     wxPGGlobalVars->m_strMin
 719 #undef wxPG_ATTR_MAX
 720 #define wxPG_ATTR_MAX                     wxPGGlobalVars->m_strMax
 721 #undef wxPG_ATTR_UNITS
 722 #define wxPG_ATTR_UNITS                   wxPGGlobalVars->m_strUnits
 723 #undef wxPG_ATTR_HINT
 724 #define wxPG_ATTR_HINT                    wxPGGlobalVars->m_strHint
 725 #if wxPG_COMPATIBILITY_1_4
 726 #undef wxPG_ATTR_INLINE_HELP
 727 #define wxPG_ATTR_INLINE_HELP             wxPGGlobalVars->m_strInlineHelp
 728 #endif
 729
 730 // -----------------------------------------------------------------------
 731
 732 /** @class wxPGChoiceEntry
 733     Data of a single wxPGChoices choice.
 734 */
 735 class WXDLLIMPEXP_PROPGRID wxPGChoiceEntry : public wxPGCell
 736 {
 737 public:
 738     wxPGChoiceEntry();
 739     wxPGChoiceEntry(const wxPGChoiceEntry& other)
 740         : wxPGCell(other)
 741     {
 742         m_value = other.m_value;
 743     }
 744     wxPGChoiceEntry( const wxString& label,
 745                      int value = wxPG_INVALID_VALUE )
 746         : wxPGCell(), m_value(value)
 747     {
 748         SetText(label);
 749     }
 750
 751     virtual ~wxPGChoiceEntry() { }
 752
 753     void SetValue( int value ) { m_value = value; }
 754     int GetValue() const { return m_value; }
 755
 756     wxPGChoiceEntry& operator=( const wxPGChoiceEntry& other )
 757     {
 758         if ( this != &other )
 759         {
 760             Ref(other);
 761         }
 762         m_value = other.m_value;
 763         return *this;
 764     }
 765
 766 protected:
 767     int m_value;
 768 };
 769
 770
 771 typedef void* wxPGChoicesId;
 772
 773 class WXDLLIMPEXP_PROPGRID wxPGChoicesData : public wxObjectRefData
 774 {
 775     friend class wxPGChoices;
 776 public:
 777     // Constructor sets m_refCount to 1.
 778     wxPGChoicesData();
 779
 780     void CopyDataFrom( wxPGChoicesData* data );
 781
 782     wxPGChoiceEntry& Insert( int index, const wxPGChoiceEntry& item );
 783
 784     // Delete all entries
 785     void Clear();
 786
 787     unsigned int GetCount() const
 788     {
 789         return (unsigned int) m_items.size();
 790     }
 791
 792     const wxPGChoiceEntry& Item( unsigned int i ) const
 793     {
 794         wxASSERT_MSG( i < GetCount(), "invalid index" );
 795         return m_items[i];
 796     }
 797
 798     wxPGChoiceEntry& Item( unsigned int i )
 799     {
 800         wxASSERT_MSG( i < GetCount(), "invalid index" );
 801         return m_items[i];
 802     }
 803
 804 private:
 805     wxVector<wxPGChoiceEntry>   m_items;
 806
 807     virtual ~wxPGChoicesData();
 808 };
 809
 810 #define wxPGChoicesEmptyData    ((wxPGChoicesData*)NULL)
 811
 812
 813 /** @class wxPGChoices
 814
 815     Helper class for managing choices of wxPropertyGrid properties.
 816     Each entry can have label, value, bitmap, text colour, and background
 817     colour.
 818
 819     wxPGChoices uses reference counting, similar to other wxWidgets classes.
 820     This means that assignment operator and copy constructor only copy the
 821     reference and not the actual data. Use Copy() member function to create a
 822     real copy.
 823
 824     @remarks If you do not specify value for entry, index is used.
 825
 826     @library{wxpropgrid}
 827     @category{propgrid}
 828 */
 829 class WXDLLIMPEXP_PROPGRID wxPGChoices
 830 {
 831 public:
 832     typedef long ValArrItem;
 833
 834     /** Default constructor. */
 835     wxPGChoices()
 836     {
 837         Init();
 838     }
 839
 840     /**
 841         Copy constructor, uses reference counting. To create a real copy,
 842         use Copy() member function instead.
 843     */
 844     wxPGChoices( const wxPGChoices& a )
 845     {
 846         if ( a.m_data != wxPGChoicesEmptyData )
 847         {
 848             m_data = a.m_data;
 849             m_data->IncRef();
 850         }
 851     }
 852
 853     /**
 854         Constructor.
 855
 856         @param labels
 857             Labels for choices
 858
 859         @param values
 860             Values for choices. If NULL, indexes are used.
 861     */
 862     wxPGChoices( const wxChar* const* labels, const long* values = NULL )
 863     {
 864         Init();
 865         Set(labels,values);
 866     }
 867
 868     /**
 869         Constructor.
 870
 871         @param labels
 872             Labels for choices
 873
 874         @param values
 875             Values for choices. If empty, indexes are used.
 876     */
 877     wxPGChoices( const wxArrayString& labels,
 878                  const wxArrayInt& values = wxArrayInt() )
 879     {
 880         Init();
 881         Set(labels,values);
 882     }
 883
 884     /** Simple interface constructor. */
 885     wxPGChoices( wxPGChoicesData* data )
 886     {
 887         wxASSERT(data);
 888         m_data = data;
 889         data->IncRef();
 890     }
 891
 892     /** Destructor. */
 893     ~wxPGChoices()
 894     {
 895         Free();
 896     }
 897
 898     /**
 899         Adds to current.
 900
 901         If did not have own copies, creates them now. If was empty, identical
 902         to set except that creates copies.
 903
 904         @param labels
 905             Labels for added choices.
 906
 907         @param values
 908             Values for added choices. If empty, relevant entry indexes are used.
 909     */
 910     void Add( const wxChar* const* labels, const ValArrItem* values = NULL );
 911
 912     /** Version that works with wxArrayString and wxArrayInt. */
 913     void Add( const wxArrayString& arr, const wxArrayInt& arrint = wxArrayInt() );
 914
 915     /**
 916         Adds a single choice.
 917
 918         @param label
 919             Label for added choice.
 920
 921         @param value
 922             Value for added choice. If unspecified, index is used.
 923     */
 924     wxPGChoiceEntry& Add( const wxString& label,
 925                           int value = wxPG_INVALID_VALUE );
 926
 927     /** Adds a single item, with bitmap. */
 928     wxPGChoiceEntry& Add( const wxString& label,
 929                           const wxBitmap& bitmap,
 930                           int value = wxPG_INVALID_VALUE );
 931
 932     /** Adds a single item with full entry information. */
 933     wxPGChoiceEntry& Add( const wxPGChoiceEntry& entry )
 934     {
 935         return Insert(entry, -1);
 936     }
 937
 938     /** Adds single item. */
 939     wxPGChoiceEntry& AddAsSorted( const wxString& label,
 940                                   int value = wxPG_INVALID_VALUE );
 941
 942     /**
 943         Assigns choices data, using reference counting. To create a real copy,
 944         use Copy() member function instead.
 945     */
 946     void Assign( const wxPGChoices& a )
 947     {
 948         AssignData(a.m_data);
 949     }
 950
 951     void AssignData( wxPGChoicesData* data );
 952
 953     /** Delete all choices. */
 954     void Clear();
 955
 956     /**
 957         Returns a real copy of the choices.
 958     */
 959     wxPGChoices Copy() const
 960     {
 961         wxPGChoices dst;
 962         dst.EnsureData();
 963         dst.m_data->CopyDataFrom(m_data);
 964         return dst;
 965     }
 966
 967     void EnsureData()
 968     {
 969         if ( m_data == wxPGChoicesEmptyData )
 970             m_data = new wxPGChoicesData();
 971     }
 972
 973     /** Gets a unsigned number identifying this list. */
 974     wxPGChoicesId GetId() const { return (wxPGChoicesId) m_data; }
 975
 976     const wxString& GetLabel( unsigned int ind ) const
 977     {
 978         return Item(ind).GetText();
 979     }
 980
 981     unsigned int GetCount () const
 982     {
 983         if ( !m_data )
 984             return 0;
 985
 986         return m_data->GetCount();
 987     }
 988
 989     int GetValue( unsigned int ind ) const { return Item(ind).GetValue(); }
 990
 991     /** Returns array of values matching the given strings. Unmatching strings
 992         result in wxPG_INVALID_VALUE entry in array.
 993     */
 994     wxArrayInt GetValuesForStrings( const wxArrayString& strings ) const;
 995
 996     /** Returns array of indices matching given strings. Unmatching strings
 997         are added to 'unmatched', if not NULL.
 998     */
 999     wxArrayInt GetIndicesForStrings( const wxArrayString& strings,
1000                                      wxArrayString* unmatched = NULL ) const;
1001
1002     int Index( const wxString& str ) const;
1003     int Index( int val ) const;
1004
1005     /** Inserts single item. */
1006     wxPGChoiceEntry& Insert( const wxString& label,
1007                              int index,
1008                              int value = wxPG_INVALID_VALUE );
1009
1010     /** Inserts a single item with full entry information. */
1011     wxPGChoiceEntry& Insert( const wxPGChoiceEntry& entry, int index );
1012
1013     /** Returns false if this is a constant empty set of choices,
1014         which should not be modified.
1015     */
1016     bool IsOk() const
1017     {
1018         return ( m_data != wxPGChoicesEmptyData );
1019     }
1020
1021     const wxPGChoiceEntry& Item( unsigned int i ) const
1022     {
1023         wxASSERT( IsOk() );
1024         return m_data->Item(i);
1025     }
1026
1027     wxPGChoiceEntry& Item( unsigned int i )
1028     {
1029         wxASSERT( IsOk() );
1030         return m_data->Item(i);
1031     }
1032
1033     /** Removes count items starting at position nIndex. */
1034     void RemoveAt(size_t nIndex, size_t count = 1);
1035
1036     /** Does not create copies for itself.
1037         TODO: Deprecate.
1038     */
1039     void Set( const wxChar* const* labels, const long* values = NULL )
1040     {
1041         Free();
1042         Add(labels,values);
1043     }
1044
1045     /** Version that works with wxArrayString and wxArrayInt. */
1046     void Set( const wxArrayString& labels,
1047               const wxArrayInt& values = wxArrayInt() )
1048     {
1049         Free();
1050         if ( &values )
1051             Add(labels,values);
1052         else
1053             Add(labels);
1054     }
1055
1056     // Creates exclusive copy of current choices
1057     void AllocExclusive();
1058
1059     // Returns data, increases refcount.
1060     wxPGChoicesData* GetData()
1061     {
1062         wxASSERT( m_data->GetRefCount() != -1 );
1063         m_data->IncRef();
1064         return m_data;
1065     }
1066
1067     // Returns plain data ptr - no refcounting stuff is done.
1068     wxPGChoicesData* GetDataPtr() const { return m_data; }
1069
1070     // Changes ownership of data to you.
1071     wxPGChoicesData* ExtractData()
1072     {
1073         wxPGChoicesData* data = m_data;
1074         m_data = wxPGChoicesEmptyData;
1075         return data;
1076     }
1077
1078     wxArrayString GetLabels() const;
1079
1080     void operator= (const wxPGChoices& a)
1081     {
1082         if (this != &a)
1083             AssignData(a.m_data);
1084     }
1085
1086     wxPGChoiceEntry& operator[](unsigned int i)
1087     {
1088         return Item(i);
1089     }
1090
1091     const wxPGChoiceEntry& operator[](unsigned int i) const
1092     {
1093         return Item(i);
1094     }
1095
1096 protected:
1097     wxPGChoicesData*    m_data;
1098
1099     void Init();
1100     void Free();
1101 };
1102
1103 // -----------------------------------------------------------------------
1104
1105 /** @class wxPGProperty
1106
1107     wxPGProperty is base class for all wxPropertyGrid properties.
1108
1109     NB: Full class overview is now only present in
1110         interface/wx/propgrid/property.h.
1111
1112     @library{wxpropgrid}
1113     @category{propgrid}
1114 */
1115 class WXDLLIMPEXP_PROPGRID wxPGProperty : public wxObject
1116 {
1117     friend class wxPropertyGrid;
1118     friend class wxPropertyGridInterface;
1119     friend class wxPropertyGridPageState;
1120     friend class wxPropertyGridPopulator;
1121     friend class wxStringProperty;  // Proper "<composed>" support requires this
1122
1123     DECLARE_ABSTRACT_CLASS(wxPGProperty)
1124 public:
1125     typedef wxUint32 FlagType;
1126
1127     /**
1128         Default constructor.
1129     */
1130     wxPGProperty();
1131
1132     /**
1133         Constructor.
1134
1135         All non-abstract property classes should have a constructor with
1136         the same first two arguments as this one.
1137     */
1138     wxPGProperty( const wxString& label, const wxString& name );
1139
1140     /**
1141         Virtual destructor.
1142         It is customary for derived properties to implement this.
1143     */
1144     virtual ~wxPGProperty();
1145
1146     /** This virtual function is called after m_value has been set.
1147
1148         @remarks
1149         - If m_value was set to Null variant (ie. unspecified value),
1150           OnSetValue() will not be called.
1151         - m_value may be of any variant type. Typically properties internally
1152           support only one variant type, and as such OnSetValue() provides a
1153           good opportunity to convert
1154           supported values into internal type.
1155         - Default implementation does nothing.
1156     */
1157     virtual void OnSetValue();
1158
1159     /** Override this to return something else than m_value as the value.
1160     */
1161     virtual wxVariant DoGetValue() const { return m_value; }
1162
1163     /** Implement this function in derived class to check the value.
1164         Return true if it is ok. Returning false prevents property change events
1165         from occurring.
1166
1167         @remarks
1168         - Default implementation always returns true.
1169     */
1170     virtual bool ValidateValue( wxVariant& value,
1171                                 wxPGValidationInfo& validationInfo ) const;
1172
1173     /**
1174         Converts text into wxVariant value appropriate for this property.
1175
1176         @param variant
1177             On function entry this is the old value (should not be wxNullVariant
1178             in normal cases). Translated value must be assigned back to it.
1179
1180         @param text
1181             Text to be translated into variant.
1182
1183         @param argFlags
1184             If wxPG_FULL_VALUE is set, returns complete, storable value instead
1185             of displayable one (they may be different).
1186             If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
1187             composite property string value (as generated by ValueToString()
1188             called with this same flag).
1189
1190         @return Returns @true if resulting wxVariant value was different.
1191
1192         @remarks Default implementation converts semicolon delimited tokens into
1193                 child values. Only works for properties with children.
1194
1195                 You might want to take into account that m_value is Null variant
1196                 if property value is unspecified (which is usually only case if
1197                 you explicitly enabled that sort behaviour).
1198     */
1199     virtual bool StringToValue( wxVariant& variant,
1200                                 const wxString& text,
1201                                 int argFlags = 0 ) const;
1202
1203     /**
1204         Converts integer (possibly a choice selection) into wxVariant value
1205         appropriate for this property.
1206
1207         @param variant
1208             On function entry this is the old value (should not be wxNullVariant
1209             in normal cases). Translated value must be assigned back to it.
1210
1211         @param number
1212             Integer to be translated into variant.
1213
1214         @param argFlags
1215             If wxPG_FULL_VALUE is set, returns complete, storable value instead
1216             of displayable one.
1217
1218         @return Returns @true if resulting wxVariant value was different.
1219
1220         @remarks
1221         - If property is not supposed to use choice or spinctrl or other editor
1222           with int-based value, it is not necessary to implement this method.
1223         - Default implementation simply assign given int to m_value.
1224         - If property uses choice control, and displays a dialog on some choice
1225           items, then it is preferred to display that dialog in IntToValue
1226           instead of OnEvent.
1227         - You might want to take into account that m_value is Null variant if
1228           property value is unspecified (which is usually only case if you
1229           explicitly enabled that sort behaviour).
1230     */
1231     virtual bool IntToValue( wxVariant& value,
1232                              int number,
1233                              int argFlags = 0 ) const;
1234
1235     /**
1236         Converts property value into a text representation.
1237
1238         @param value
1239             Value to be converted.
1240
1241         @param argFlags
1242             If 0 (default value), then displayed string is returned.
1243             If wxPG_FULL_VALUE is set, returns complete, storable string value
1244             instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
1245             string value that must be editable in textctrl. If
1246             wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
1247             display as a part of string property's composite text
1248             representation.
1249
1250         @remarks Default implementation calls GenerateComposedValue().
1251     */
1252     virtual wxString ValueToString( wxVariant& value, int argFlags = 0 ) const;
1253
1254     /** Converts string to a value, and if successful, calls SetValue() on it.
1255         Default behaviour is to do nothing.
1256         @param text
1257         String to get the value from.
1258         @return
1259         true if value was changed.
1260     */
1261     bool SetValueFromString( const wxString& text, int flags = wxPG_PROGRAMMATIC_VALUE );
1262
1263     /** Converts integer to a value, and if successful, calls SetValue() on it.
1264         Default behaviour is to do nothing.
1265         @param value
1266             Int to get the value from.
1267         @param flags
1268             If has wxPG_FULL_VALUE, then the value given is a actual value and
1269             not an index.
1270         @return
1271             True if value was changed.
1272     */
1273     bool SetValueFromInt( long value, int flags = 0 );
1274
1275     /**
1276         Returns size of the custom painted image in front of property.
1277
1278         This method must be overridden to return non-default value if
1279         OnCustomPaint is to be called.
1280         @param item
1281             Normally -1, but can be an index to the property's list of items.
1282         @remarks
1283         - Default behaviour is to return wxSize(0,0), which means no image.
1284         - Default image width or height is indicated with dimension -1.
1285         - You can also return wxPG_DEFAULT_IMAGE_SIZE, i.e. wxSize(-1, -1).
1286     */
1287     virtual wxSize OnMeasureImage( int item = -1 ) const;
1288
1289     /**
1290         Events received by editor widgets are processed here.
1291
1292         Note that editor class usually processes most events. Some, such as
1293         button press events of TextCtrlAndButton class, can be handled here.
1294         Also, if custom handling for regular events is desired, then that can
1295         also be done (for example, wxSystemColourProperty custom handles
1296         wxEVT_COMMAND_CHOICE_SELECTED to display colour picker dialog when
1297         'custom' selection is made).
1298
1299         If the event causes value to be changed, SetValueInEvent()
1300         should be called to set the new value.
1301
1302         @param event
1303         Associated wxEvent.
1304         @return
1305         Should return true if any changes in value should be reported.
1306         @remarks
1307         If property uses choice control, and displays a dialog on some choice
1308         items, then it is preferred to display that dialog in IntToValue
1309         instead of OnEvent.
1310     */
1311     virtual bool OnEvent( wxPropertyGrid* propgrid,
1312                           wxWindow* wnd_primary,
1313                           wxEvent& event );
1314
1315     /**
1316         Called after value of a child property has been altered. Must return
1317         new value of the whole property (after any alterations warranted by
1318         child's new value).
1319
1320         Note that this function is usually called at the time that value of
1321         this property, or given child property, is still pending for change,
1322         and as such, result of GetValue() or m_value should not be relied
1323         on.
1324
1325         Sample pseudo-code implementation:
1326
1327         @code
1328         wxVariant MyProperty::ChildChanged( wxVariant& thisValue,
1329                                             int childIndex,
1330                                             wxVariant& childValue ) const
1331         {
1332             // Acquire reference to actual type of data stored in variant
1333             // (TFromVariant only exists if wxPropertyGrid's wxVariant-macros
1334             // were used to create the variant class).
1335             T& data = TFromVariant(thisValue);
1336
1337             // Copy childValue into data.
1338             switch ( childIndex )
1339             {
1340                 case 0:
1341                     data.SetSubProp1( childvalue.GetLong() );
1342                     break;
1343                 case 1:
1344                     data.SetSubProp2( childvalue.GetString() );
1345                     break;
1346                 ...
1347             }
1348
1349             // Return altered data
1350             return data;
1351         }
1352         @endcode
1353
1354         @param thisValue
1355             Value of this property. Changed value should be returned (in
1356             previous versions of wxPropertyGrid it was only necessary to
1357             write value back to this argument).
1358         @param childIndex
1359             Index of child changed (you can use Item(childIndex) to get
1360             child property).
1361         @param childValue
1362             (Pending) value of the child property.
1363
1364         @return
1365             Modified value of the whole property.
1366     */
1367     virtual wxVariant ChildChanged( wxVariant& thisValue,
1368                                     int childIndex,
1369                                     wxVariant& childValue ) const;
1370
1371     /** Returns pointer to an instance of used editor.
1372     */
1373     virtual const wxPGEditor* DoGetEditorClass() const;
1374
1375     /** Returns pointer to the wxValidator that should be used
1376         with the editor of this property (NULL for no validator).
1377         Setting validator explicitly via SetPropertyValidator
1378         will override this.
1379
1380         In most situations, code like this should work well
1381         (macros are used to maintain one actual validator instance,
1382         so on the second call the function exits within the first
1383         macro):
1384
1385         @code
1386
1387         wxValidator* wxMyPropertyClass::DoGetValidator () const
1388         {
1389             WX_PG_DOGETVALIDATOR_ENTRY()
1390
1391             wxMyValidator* validator = new wxMyValidator(...);
1392
1393             ... prepare validator...
1394
1395             WX_PG_DOGETVALIDATOR_EXIT(validator)
1396         }
1397
1398         @endcode
1399
1400         @remarks
1401         You can get common filename validator by returning
1402         wxFileProperty::GetClassValidator(). wxDirProperty,
1403         for example, uses it.
1404     */
1405     virtual wxValidator* DoGetValidator () const;
1406
1407     /**
1408         Override to paint an image in front of the property value text or
1409         drop-down list item (but only if wxPGProperty::OnMeasureImage is
1410         overridden as well).
1411
1412         If property's OnMeasureImage() returns size that has height != 0 but
1413         less than row height ( < 0 has special meanings), wxPropertyGrid calls
1414         this method to draw a custom image in a limited area in front of the
1415         editor control or value text/graphics, and if control has drop-down
1416         list, then the image is drawn there as well (even in the case
1417         OnMeasureImage() returned higher height than row height).
1418
1419         NOTE: Following applies when OnMeasureImage() returns a "flexible"
1420         height ( using wxPG_FLEXIBLE_SIZE(W,H) macro), which implies variable
1421         height items: If rect.x is < 0, then this is a measure item call, which
1422         means that dc is invalid and only thing that should be done is to set
1423         paintdata.m_drawnHeight to the height of the image of item at index
1424         paintdata.m_choiceItem. This call may be done even as often as once
1425         every drop-down popup show.
1426
1427         @param dc
1428             wxDC to paint on.
1429         @param rect
1430             Box reserved for custom graphics. Includes surrounding rectangle,
1431             if any. If x is < 0, then this is a measure item call (see above).
1432         @param paintdata
1433             wxPGPaintData structure with much useful data.
1434
1435         @remarks
1436             - You can actually exceed rect width, but if you do so then
1437               paintdata.m_drawnWidth must be set to the full width drawn in
1438               pixels.
1439             - Due to technical reasons, rect's height will be default even if
1440               custom height was reported during measure call.
1441             - Brush is guaranteed to be default background colour. It has been
1442               already used to clear the background of area being painted. It
1443               can be modified.
1444             - Pen is guaranteed to be 1-wide 'black' (or whatever is the proper
1445               colour) pen for drawing framing rectangle. It can be changed as
1446               well.
1447
1448         @see ValueToString()
1449     */
1450     virtual void OnCustomPaint( wxDC& dc,
1451                                 const wxRect& rect,
1452                                 wxPGPaintData& paintdata );
1453
1454     /**
1455         Returns used wxPGCellRenderer instance for given property column
1456         (label=0, value=1).
1457
1458         Default implementation returns editor's renderer for all columns.
1459     */
1460     virtual wxPGCellRenderer* GetCellRenderer( int column ) const;
1461
1462     /** Returns which choice is currently selected. Only applies to properties
1463         which have choices.
1464
1465         Needs to reimplemented in derived class if property value does not
1466         map directly to a choice. Integer as index, bool, and string usually do.
1467     */
1468     virtual int GetChoiceSelection() const;
1469
1470     /**
1471         Refresh values of child properties.
1472
1473         Automatically called after value is set.
1474     */
1475     virtual void RefreshChildren();
1476
1477     /**
1478         Reimplement this member function to add special handling for
1479         attributes of this property.
1480
1481         @return Return @false to have the attribute automatically stored in
1482                 m_attributes. Default implementation simply does that and
1483                 nothing else.
1484
1485         @remarks To actually set property attribute values from the
1486                  application, use wxPGProperty::SetAttribute() instead.
1487     */
1488     virtual bool DoSetAttribute( const wxString& name, wxVariant& value );
1489
1490     /** Returns value of an attribute.
1491
1492         Override if custom handling of attributes is needed.
1493
1494         Default implementation simply return NULL variant.
1495     */
1496     virtual wxVariant DoGetAttribute( const wxString& name ) const;
1497
1498     /** Returns instance of a new wxPGEditorDialogAdapter instance, which is
1499         used when user presses the (optional) button next to the editor control;
1500
1501         Default implementation returns NULL (ie. no action is generated when
1502         button is pressed).
1503     */
1504     virtual wxPGEditorDialogAdapter* GetEditorDialog() const;
1505
1506     /**
1507         Called whenever validation has failed with given pending value.
1508
1509         @remarks If you implement this in your custom property class, please
1510                  remember to call the baser implementation as well, since they
1511                  may use it to revert property into pre-change state.
1512     */
1513     virtual void OnValidationFailure( wxVariant& pendingValue );
1514
1515     /** Append a new choice to property's list of choices.
1516     */
1517     int AddChoice( const wxString& label, int value = wxPG_INVALID_VALUE )
1518     {
1519         return InsertChoice(label, wxNOT_FOUND, value);
1520     }
1521
1522     /**
1523         Returns true if children of this property are component values (for
1524         instance, points size, face name, and is_underlined are component
1525         values of a font).
1526     */
1527     bool AreChildrenComponents() const
1528     {
1529         if ( m_flags & (wxPG_PROP_COMPOSED_VALUE|wxPG_PROP_AGGREGATE) )
1530             return true;
1531
1532         return false;
1533     }
1534
1535     /**
1536         Deletes children of the property.
1537     */
1538     void DeleteChildren();
1539
1540     /**
1541         Removes entry from property's wxPGChoices and editor control (if it is
1542         active).
1543
1544         If selected item is deleted, then the value is set to unspecified.
1545     */
1546     void DeleteChoice( int index );
1547
1548     /**
1549         Enables or disables the property. Disabled property usually appears
1550         as having grey text.
1551
1552         @param enable
1553             If @false, property is disabled instead.
1554
1555         @see wxPropertyGridInterface::EnableProperty()
1556     */
1557     void Enable( bool enable = true );
1558
1559     /**
1560         Call to enable or disable usage of common value (integer value that can
1561         be selected for properties instead of their normal values) for this
1562         property.
1563
1564         Common values are disabled by the default for all properties.
1565     */
1566     void EnableCommonValue( bool enable = true )
1567     {
1568         if ( enable ) SetFlag( wxPG_PROP_USES_COMMON_VALUE );
1569         else ClearFlag( wxPG_PROP_USES_COMMON_VALUE );
1570     }
1571
1572     /**
1573         Composes text from values of child properties.
1574     */
1575     wxString GenerateComposedValue() const
1576     {
1577         wxString s;
1578         DoGenerateComposedValue(s);
1579         return s;
1580     }
1581
1582     /** Returns property's label. */
1583     const wxString& GetLabel() const { return m_label; }
1584
1585     /** Returns property's name with all (non-category, non-root) parents. */
1586     wxString GetName() const;
1587
1588     /**
1589         Returns property's base name (ie parent's name is not added in any
1590         case)
1591      */
1592     const wxString& GetBaseName() const { return m_name; }
1593
1594     /** Returns read-only reference to property's list of choices.
1595     */
1596     const wxPGChoices& GetChoices() const
1597     {
1598         return m_choices;
1599     }
1600
1601     /** Returns coordinate to the top y of the property. Note that the
1602         position of scrollbars is not taken into account.
1603     */
1604     int GetY() const;
1605
1606     wxVariant GetValue() const
1607     {
1608         return DoGetValue();
1609     }
1610
1611     /** Returns reference to the internal stored value. GetValue is preferred
1612         way to get the actual value, since GetValueRef ignores DoGetValue,
1613         which may override stored value.
1614     */
1615     wxVariant& GetValueRef()
1616     {
1617         return m_value;
1618     }
1619
1620     const wxVariant& GetValueRef() const
1621     {
1622         return m_value;
1623     }
1624
1625     // Helper function (for wxPython bindings and such) for settings protected
1626     // m_value.
1627     wxVariant GetValuePlain() const
1628     {
1629         return m_value;
1630     }
1631
1632     /** Returns text representation of property's value.
1633
1634         @param argFlags
1635             If 0 (default value), then displayed string is returned.
1636             If wxPG_FULL_VALUE is set, returns complete, storable string value
1637             instead of displayable. If wxPG_EDITABLE_VALUE is set, returns
1638             string value that must be editable in textctrl. If
1639             wxPG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to
1640             display as a part of string property's composite text
1641             representation.
1642
1643         @remarks In older versions, this function used to be overridden to convert
1644                  property's value into a string representation. This function is
1645                  now handled by ValueToString(), and overriding this function now
1646                  will result in run-time assertion failure.
1647     */
1648     virtual wxString GetValueAsString( int argFlags = 0 ) const;
1649
1650     /** Synonymous to GetValueAsString().
1651
1652         @deprecated Use GetValueAsString() instead.
1653
1654         @see GetValueAsString()
1655     */
1656     wxDEPRECATED( wxString GetValueString( int argFlags = 0 ) const );
1657
1658     /**
1659         Returns wxPGCell of given column.
1660
1661         @remarks const version of this member function returns 'default'
1662                  wxPGCell object if the property itself didn't hold
1663                  cell data.
1664     */
1665     const wxPGCell& GetCell( unsigned int column ) const;
1666
1667     /**
1668         Returns wxPGCell of given column, creating one if necessary.
1669     */
1670     wxPGCell& GetCell( unsigned int column )
1671     {
1672         return GetOrCreateCell(column);
1673     }
1674
1675     /**
1676         Returns wxPGCell of given column, creating one if necessary.
1677     */
1678     wxPGCell& GetOrCreateCell( unsigned int column );
1679
1680     /** Return number of displayed common values for this property.
1681     */
1682     int GetDisplayedCommonValueCount() const;
1683
1684     wxString GetDisplayedString() const
1685     {
1686         return GetValueAsString(0);
1687     }
1688
1689     /**
1690         Returns property's hint text (shown in empty value cell).
1691     */
1692     inline wxString GetHintText() const;
1693
1694     /** Returns property grid where property lies. */
1695     wxPropertyGrid* GetGrid() const;
1696
1697     /** Returns owner wxPropertyGrid, but only if one is currently on a page
1698         displaying this property. */
1699     wxPropertyGrid* GetGridIfDisplayed() const;
1700
1701     /** Returns highest level non-category, non-root parent. Useful when you
1702         have nested wxCustomProperties/wxParentProperties.
1703         @remarks
1704         Thus, if immediate parent is root or category, this will return the
1705         property itself.
1706     */
1707     wxPGProperty* GetMainParent() const;
1708
1709     /** Return parent of property */
1710     wxPGProperty* GetParent() const { return m_parent; }
1711
1712     /** Returns true if property has editable wxTextCtrl when selected.
1713
1714         @remarks
1715         Although disabled properties do not displayed editor, they still
1716         return True here as being disabled is considered a temporary
1717         condition (unlike being read-only or having limited editing enabled).
1718     */
1719     bool IsTextEditable() const;
1720
1721     bool IsValueUnspecified() const
1722     {
1723         return m_value.IsNull();
1724     }
1725
1726     /**
1727         Returns non-zero if property has given flag set.
1728
1729         @see propgrid_propflags
1730     */
1731     FlagType HasFlag( wxPGPropertyFlags flag ) const
1732     {
1733         return ( m_flags & flag );
1734     }
1735
1736     /** Returns comma-delimited string of property attributes.
1737     */
1738     const wxPGAttributeStorage& GetAttributes() const
1739     {
1740         return m_attributes;
1741     }
1742
1743     /** Returns m_attributes as list wxVariant.
1744     */
1745     wxVariant GetAttributesAsList() const;
1746
1747     /**
1748         Returns property flags.
1749     */
1750     FlagType GetFlags() const
1751     {
1752         return m_flags;
1753     }
1754
1755     const wxPGEditor* GetEditorClass() const;
1756
1757     wxString GetValueType() const
1758     {
1759         return m_value.GetType();
1760     }
1761
1762     /** Returns editor used for given column. NULL for no editor.
1763     */
1764     const wxPGEditor* GetColumnEditor( int column ) const
1765     {
1766         if ( column == 1 )
1767             return GetEditorClass();
1768
1769         return NULL;
1770     }
1771
1772     /** Returns common value selected for this property. -1 for none.
1773     */
1774     int GetCommonValue() const
1775     {
1776         return m_commonValue;
1777     }
1778
1779     /** Returns true if property has even one visible child.
1780     */
1781     bool HasVisibleChildren() const;
1782
1783     /**
1784         Use this member function to add independent (ie. regular) children to
1785         a property.
1786
1787         @return Inserted childProperty.
1788
1789         @remarks wxPropertyGrid is not automatically refreshed by this
1790                  function.
1791
1792         @see AddPrivateChild()
1793     */
1794     wxPGProperty* InsertChild( int index, wxPGProperty* childProperty );
1795
1796     /** Inserts a new choice to property's list of choices.
1797     */
1798     int InsertChoice( const wxString& label, int index, int value = wxPG_INVALID_VALUE );
1799
1800     /**
1801         Returns true if this property is actually a wxPropertyCategory.
1802     */
1803     bool IsCategory() const { return HasFlag(wxPG_PROP_CATEGORY)?true:false; }
1804
1805     /** Returns true if this property is actually a wxRootProperty.
1806     */
1807     bool IsRoot() const { return (m_parent == NULL); }
1808
1809     /** Returns true if this is a sub-property. */
1810     bool IsSubProperty() const
1811     {
1812         wxPGProperty* parent = (wxPGProperty*)m_parent;
1813         if ( parent && !parent->IsCategory() )
1814             return true;
1815         return false;
1816     }
1817
1818     /** Returns last visible sub-property, recursively.
1819     */
1820     const wxPGProperty* GetLastVisibleSubItem() const;
1821
1822     wxVariant GetDefaultValue() const;
1823
1824     int GetMaxLength() const
1825     {
1826         return (int) m_maxLen;
1827     }
1828
1829     /**
1830         Determines, recursively, if all children are not unspecified.
1831
1832         @param pendingList
1833             Assumes members in this wxVariant list as pending
1834             replacement values.
1835     */
1836     bool AreAllChildrenSpecified( wxVariant* pendingList = NULL ) const;
1837
1838     /** Updates composed values of parent non-category properties, recursively.
1839         Returns topmost property updated.
1840
1841         @remarks
1842         - Must not call SetValue() (as can be called in it).
1843     */
1844     wxPGProperty* UpdateParentValues();
1845
1846     /** Returns true if containing grid uses wxPG_EX_AUTO_UNSPECIFIED_VALUES.
1847     */
1848     bool UsesAutoUnspecified() const
1849     {
1850         return HasFlag(wxPG_PROP_AUTO_UNSPECIFIED)?true:false;
1851     }
1852
1853     wxBitmap* GetValueImage() const
1854     {
1855         return m_valueBitmap;
1856     }
1857
1858     wxVariant GetAttribute( const wxString& name ) const;
1859
1860     /**
1861         Returns named attribute, as string, if found.
1862
1863         Otherwise defVal is returned.
1864     */
1865     wxString GetAttribute( const wxString& name, const wxString& defVal ) const;
1866
1867     /**
1868         Returns named attribute, as long, if found.
1869
1870         Otherwise defVal is returned.
1871     */
1872     long GetAttributeAsLong( const wxString& name, long defVal ) const;
1873
1874     /**
1875         Returns named attribute, as double, if found.
1876
1877         Otherwise defVal is returned.
1878     */
1879     double GetAttributeAsDouble( const wxString& name, double defVal ) const;
1880
1881     unsigned int GetDepth() const { return (unsigned int)m_depth; }
1882
1883     /** Gets flags as a'|' delimited string. Note that flag names are not
1884         prepended with 'wxPG_PROP_'.
1885         @param flagsMask
1886         String will only be made to include flags combined by this parameter.
1887     */
1888     wxString GetFlagsAsString( FlagType flagsMask ) const;
1889
1890     /** Returns position in parent's array. */
1891     unsigned int GetIndexInParent() const
1892     {
1893         return (unsigned int)m_arrIndex;
1894     }
1895
1896     /** Hides or reveals the property.
1897         @param hide
1898             true for hide, false for reveal.
1899         @param flags
1900             By default changes are applied recursively. Set this paramter
1901             wxPG_DONT_RECURSE to prevent this.
1902     */
1903     bool Hide( bool hide, int flags = wxPG_RECURSE );
1904
1905     bool IsExpanded() const
1906         { return (!(m_flags & wxPG_PROP_COLLAPSED) && GetChildCount()); }
1907
1908     /** Returns true if all parents expanded.
1909     */
1910     bool IsVisible() const;
1911
1912     bool IsEnabled() const { return !(m_flags & wxPG_PROP_DISABLED); }
1913
1914     /** If property's editor is created this forces its recreation.
1915         Useful in SetAttribute etc. Returns true if actually did anything.
1916     */
1917     bool RecreateEditor();
1918
1919     /** If property's editor is active, then update it's value.
1920     */
1921     void RefreshEditor();
1922
1923     /** Sets an attribute for this property.
1924         @param name
1925         Text identifier of attribute. See @ref propgrid_property_attributes.
1926         @param value
1927         Value of attribute.
1928     */
1929     void SetAttribute( const wxString& name, wxVariant value );
1930
1931     void SetAttributes( const wxPGAttributeStorage& attributes );
1932
1933     /**
1934         Set if user can change the property's value to unspecified by
1935         modifying the value of the editor control (usually by clearing
1936         it).  Currently, this can work with following properties:
1937         wxIntProperty, wxUIntProperty, wxFloatProperty, wxEditEnumProperty.
1938
1939         @param enable
1940             Whether to enable or disable this behaviour (it is disabled by
1941             default).
1942     */
1943     void SetAutoUnspecified( bool enable = true )
1944     {
1945         ChangeFlag(wxPG_PROP_AUTO_UNSPECIFIED, enable);
1946     }
1947
1948     /**
1949         Sets property's background colour.
1950
1951         @param colour
1952             Background colour to use.
1953
1954         @param flags
1955             Default is wxPG_RECURSE which causes colour to be set recursively.
1956             Omit this flag to only set colour for the property in question
1957             and not any of its children.
1958     */
1959     void SetBackgroundColour( const wxColour& colour,
1960                               int flags = wxPG_RECURSE );
1961
1962     /**
1963         Sets property's text colour.
1964
1965         @param colour
1966             Text colour to use.
1967
1968         @param flags
1969             Default is wxPG_RECURSE which causes colour to be set recursively.
1970             Omit this flag to only set colour for the property in question
1971             and not any of its children.
1972     */
1973     void SetTextColour( const wxColour& colour,
1974                         int flags = wxPG_RECURSE );
1975
1976     /** Set default value of a property. Synonymous to
1977
1978         @code
1979             SetAttribute("DefaultValue", value);
1980         @endcode
1981     */
1982     void SetDefaultValue( wxVariant& value );
1983
1984     /** Sets editor for a property.
1985
1986         @param editor
1987             For builtin editors, use wxPGEditor_X, where X is builtin editor's
1988             name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
1989             list).
1990
1991         For custom editors, use pointer you received from
1992         wxPropertyGrid::RegisterEditorClass().
1993     */
1994     void SetEditor( const wxPGEditor* editor )
1995     {
1996         m_customEditor = editor;
1997     }
1998
1999     /** Sets editor for a property.
2000     */
2001     inline void SetEditor( const wxString& editorName );
2002
2003     /**
2004         Sets cell information for given column.
2005     */
2006     void SetCell( int column, const wxPGCell& cell );
2007
2008     /** Sets common value selected for this property. -1 for none.
2009     */
2010     void SetCommonValue( int commonValue )
2011     {
2012         m_commonValue = commonValue;
2013     }
2014
2015     /** Sets flags from a '|' delimited string. Note that flag names are not
2016         prepended with 'wxPG_PROP_'.
2017     */
2018     void SetFlagsFromString( const wxString& str );
2019
2020     /** Sets property's "is it modified?" flag. Affects children recursively.
2021     */
2022     void SetModifiedStatus( bool modified )
2023     {
2024         SetFlagRecursively(wxPG_PROP_MODIFIED, modified);
2025     }
2026
2027     /** Call in OnEvent(), OnButtonClick() etc. to change the property value
2028         based on user input.
2029
2030         @remarks
2031         This method is const since it doesn't actually modify value, but posts
2032         given variant as pending value, stored in wxPropertyGrid.
2033     */
2034     void SetValueInEvent( wxVariant value ) const;
2035
2036     /**
2037         Call this to set value of the property.
2038
2039         Unlike methods in wxPropertyGrid, this does not automatically update
2040         the display.
2041
2042         @remarks
2043         Use wxPropertyGrid::ChangePropertyValue() instead if you need to run
2044         through validation process and send property change event.
2045
2046         If you need to change property value in event, based on user input, use
2047         SetValueInEvent() instead.
2048
2049         @param pList
2050             Pointer to list variant that contains child values. Used to
2051             indicate which children should be marked as modified.
2052
2053         @param flags
2054             Various flags (for instance, wxPG_SETVAL_REFRESH_EDITOR, which is
2055             enabled by default).
2056     */
2057     void SetValue( wxVariant value, wxVariant* pList = NULL,
2058                    int flags = wxPG_SETVAL_REFRESH_EDITOR );
2059
2060     /** Set wxBitmap in front of the value. This bitmap may be ignored
2061         by custom cell renderers.
2062     */
2063     void SetValueImage( wxBitmap& bmp );
2064
2065     /** Sets selected choice and changes property value.
2066
2067         Tries to retain value type, although currently if it is not string,
2068         then it is forced to integer.
2069     */
2070     void SetChoiceSelection( int newValue );
2071
2072     void SetExpanded( bool expanded )
2073     {
2074         if ( !expanded ) m_flags |= wxPG_PROP_COLLAPSED;
2075         else m_flags &= ~wxPG_PROP_COLLAPSED;
2076     }
2077
2078     /**
2079         Sets or clears given property flag. Mainly for internal use.
2080
2081         @remarks Setting a property flag never has any side-effect, and is
2082                  intended almost exclusively for internal use. So, for
2083                  example, if you want to disable a property, call
2084                  Enable(false) instead of setting wxPG_PROP_DISABLED flag.
2085
2086         @see HasFlag(), GetFlags()
2087     */
2088     void ChangeFlag( wxPGPropertyFlags flag, bool set )
2089     {
2090         if ( set )
2091             m_flags |= flag;
2092         else
2093             m_flags &= ~flag;
2094     }
2095
2096     /**
2097         Sets or clears given property flag, recursively. This function is
2098         primarily intended for internal use.
2099
2100         @see ChangeFlag()
2101     */
2102     void SetFlagRecursively( wxPGPropertyFlags flag, bool set );
2103
2104     void SetHelpString( const wxString& helpString )
2105     {
2106         m_helpString = helpString;
2107     }
2108
2109     void SetLabel( const wxString& label ) { m_label = label; }
2110
2111     void SetName( const wxString& newName );
2112
2113     /**
2114         Changes what sort of parent this property is for its children.
2115
2116         @param flag
2117             Use one of the following values: wxPG_PROP_MISC_PARENT (for
2118             generic parents), wxPG_PROP_CATEGORY (for categories), or
2119             wxPG_PROP_AGGREGATE (for derived property classes with private
2120             children).
2121
2122         @remarks You generally do not need to call this function.
2123     */
2124     void SetParentalType( int flag )
2125     {
2126         m_flags &= ~(wxPG_PROP_PROPERTY|wxPG_PROP_PARENTAL_FLAGS);
2127         m_flags |= flag;
2128     }
2129
2130     void SetValueToUnspecified()
2131     {
2132         wxVariant val;  // Create NULL variant
2133         SetValue(val, NULL, wxPG_SETVAL_REFRESH_EDITOR);
2134     }
2135
2136     // Helper function (for wxPython bindings and such) for settings protected
2137     // m_value.
2138     void SetValuePlain( wxVariant value )
2139     {
2140         m_value = value;
2141     }
2142
2143 #if wxUSE_VALIDATORS
2144     /** Sets wxValidator for a property*/
2145     void SetValidator( const wxValidator& validator )
2146     {
2147         m_validator = wxDynamicCast(validator.Clone(),wxValidator);
2148     }
2149
2150     /** Gets assignable version of property's validator. */
2151     wxValidator* GetValidator() const
2152     {
2153         if ( m_validator )
2154             return m_validator;
2155         return DoGetValidator();
2156     }
2157 #endif // wxUSE_VALIDATORS
2158
2159     /** Returns client data (void*) of a property.
2160     */
2161     void* GetClientData() const
2162     {
2163         return m_clientData;
2164     }
2165
2166     /** Sets client data (void*) of a property.
2167         @remarks
2168         This untyped client data has to be deleted manually.
2169     */
2170     void SetClientData( void* clientData )
2171     {
2172         m_clientData = clientData;
2173     }
2174
2175     /** Returns client object of a property.
2176     */
2177     void SetClientObject(wxClientData* clientObject)
2178     {
2179         delete m_clientObject;
2180         m_clientObject = clientObject;
2181     }
2182
2183     /** Sets managed client object of a property.
2184     */
2185     wxClientData *GetClientObject() const { return m_clientObject; }
2186
2187     /**
2188         Sets new set of choices for the property.
2189
2190         @remarks This operation deselects the property and clears its
2191                  value.
2192     */
2193     bool SetChoices( const wxPGChoices& choices );
2194
2195     /** Set max length of text in text editor.
2196     */
2197     inline bool SetMaxLength( int maxLen );
2198
2199     /** Call with 'false' in OnSetValue to cancel value changes after all
2200         (ie. cancel 'true' returned by StringToValue() or IntToValue()).
2201     */
2202     void SetWasModified( bool set = true )
2203     {
2204         if ( set ) m_flags |= wxPG_PROP_WAS_MODIFIED;
2205         else m_flags &= ~wxPG_PROP_WAS_MODIFIED;
2206     }
2207
2208     const wxString& GetHelpString() const
2209     {
2210         return m_helpString;
2211     }
2212
2213     // Use, for example, to detect if item is inside collapsed section.
2214     bool IsSomeParent( wxPGProperty* candidate_parent ) const;
2215
2216     /**
2217         Adapts list variant into proper value using consecutive
2218         ChildChanged-calls.
2219     */
2220     void AdaptListToValue( wxVariant& list, wxVariant* value ) const;
2221
2222 #if wxPG_COMPATIBILITY_1_4
2223     /**
2224         Adds a private child property.
2225
2226         @deprecated Use AddPrivateChild() instead.
2227
2228         @see AddPrivateChild()
2229     */
2230     wxDEPRECATED( void AddChild( wxPGProperty* prop ) );
2231 #endif
2232
2233     /**
2234         Adds a private child property. If you use this instead of
2235         wxPropertyGridInterface::Insert() or
2236         wxPropertyGridInterface::AppendIn(), then property's parental
2237         type will automatically be set up to wxPG_PROP_AGGREGATE. In other
2238         words, all properties of this property will become private.
2239     */
2240     void AddPrivateChild( wxPGProperty* prop );
2241
2242     /**
2243         Appends a new child property.
2244     */
2245     wxPGProperty* AppendChild( wxPGProperty* prop )
2246     {
2247         return InsertChild(-1, prop);
2248     }
2249
2250     /** Returns height of children, recursively, and
2251         by taking expanded/collapsed status into account.
2252
2253         iMax is used when finding property y-positions.
2254     */
2255     int GetChildrenHeight( int lh, int iMax = -1 ) const;
2256
2257     /** Returns number of child properties */
2258     unsigned int GetChildCount() const
2259     {
2260         return (unsigned int) m_children.size();
2261     }
2262
2263     /** Returns sub-property at index i. */
2264     wxPGProperty* Item( unsigned int i ) const
2265         { return m_children[i]; }
2266
2267     /** Returns last sub-property.
2268     */
2269     wxPGProperty* Last() const { return m_children.back(); }
2270
2271     /** Returns index of given child property. */
2272     int Index( const wxPGProperty* p ) const;
2273
2274     // Puts correct indexes to children
2275     void FixIndicesOfChildren( unsigned int starthere = 0 );
2276
2277     /**
2278         Converts image width into full image offset, with margins.
2279     */
2280     int GetImageOffset( int imageWidth ) const;
2281
2282     // Returns wxPropertyGridPageState in which this property resides.
2283     wxPropertyGridPageState* GetParentState() const { return m_parentState; }
2284
2285     wxPGProperty* GetItemAtY( unsigned int y,
2286                               unsigned int lh,
2287                               unsigned int* nextItemY ) const;
2288
2289     /** Returns property at given virtual y coordinate.
2290     */
2291     wxPGProperty* GetItemAtY( unsigned int y ) const;
2292
2293     /** Returns (direct) child property with given name (or NULL if not found).
2294     */
2295     wxPGProperty* GetPropertyByName( const wxString& name ) const;
2296
2297     // Returns various display-related information for given column
2298     void GetDisplayInfo( unsigned int column,
2299                          int choiceIndex,
2300                          int flags,
2301                          wxString* pString,
2302                          const wxPGCell** pCell );
2303
2304     static wxString*            sm_wxPG_LABEL;
2305
2306     /** This member is public so scripting language bindings
2307         wrapper code can access it freely.
2308     */
2309     void*                       m_clientData;
2310
2311 protected:
2312
2313     /**
2314         Sets property cell in fashion that reduces number of exclusive
2315         copies of cell data. Used when setting, for instance, same
2316         background colour for a number of properties.
2317
2318         @param firstCol
2319             First column to affect.
2320
2321         @param lastCol
2322             Last column to affect.
2323
2324         @param preparedCell
2325             Pre-prepared cell that is used for those which cell data
2326             before this matched unmodCellData.
2327
2328         @param srcData
2329             If unmodCellData did not match, valid cell data from this
2330             is merged into cell (usually generating new exclusive copy
2331             of cell's data).
2332
2333         @param unmodCellData
2334             If cell's cell data matches this, its cell is now set to
2335             preparedCell.
2336
2337         @param ignoreWithFlags
2338             Properties with any one of these flags are skipped.
2339
2340         @param recursively
2341             If @true, apply this operation recursively in child properties.
2342     */
2343     void AdaptiveSetCell( unsigned int firstCol,
2344                           unsigned int lastCol,
2345                           const wxPGCell& preparedCell,
2346                           const wxPGCell& srcData,
2347                           wxPGCellData* unmodCellData,
2348                           FlagType ignoreWithFlags,
2349                           bool recursively );
2350
2351     /**
2352         Makes sure m_cells has size of column+1 (or more).
2353     */
2354     void EnsureCells( unsigned int column );
2355
2356     /** Returns (direct) child property with given name (or NULL if not found),
2357         with hint index.
2358
2359         @param hintIndex
2360         Start looking for the child at this index.
2361
2362         @remarks
2363         Does not support scope (ie. Parent.Child notation).
2364     */
2365     wxPGProperty* GetPropertyByNameWH( const wxString& name,
2366                                        unsigned int hintIndex ) const;
2367
2368     /** This is used by Insert etc. */
2369     void DoAddChild( wxPGProperty* prop,
2370                      int index = -1,
2371                      bool correct_mode = true );
2372
2373     void DoGenerateComposedValue( wxString& text,
2374                                   int argFlags = wxPG_VALUE_IS_CURRENT,
2375                                   const wxVariantList* valueOverrides = NULL,
2376                                   wxPGHashMapS2S* childResults = NULL ) const;
2377
2378     bool DoHide( bool hide, int flags );
2379
2380     void DoSetName(const wxString& str) { m_name = str; }
2381
2382     /** Deletes all sub-properties. */
2383     void Empty();
2384
2385     bool HasCell( unsigned int column ) const
2386     {
2387         if ( m_cells.size() > column )
2388             return true;
2389         return false;
2390     }
2391
2392     void InitAfterAdded( wxPropertyGridPageState* pageState,
2393                          wxPropertyGrid* propgrid );
2394
2395     /**
2396         Returns true if child property is selected.
2397     */
2398     bool IsChildSelected( bool recursive = false ) const;
2399
2400     // Removes child property with given pointer. Does not delete it.
2401     void RemoveChild( wxPGProperty* p );
2402
2403     void DoEnable( bool enable );
2404
2405     void DoPreAddChild( int index, wxPGProperty* prop );
2406
2407     void SetParentState( wxPropertyGridPageState* pstate )
2408         { m_parentState = pstate; }
2409
2410     void SetFlag( wxPGPropertyFlags flag )
2411     {
2412         //
2413         // NB: While using wxPGPropertyFlags here makes it difficult to
2414         //     combine different flags, it usefully prevents user from
2415         //     using incorrect flags (say, wxWindow styles).
2416         m_flags |= flag;
2417     }
2418
2419     void ClearFlag( FlagType flag ) { m_flags &= ~(flag); }
2420
2421     // Called when the property is being removed from the grid and/or
2422     // page state (but *not* when it is also deleted).
2423     void OnDetached(wxPropertyGridPageState* state,
2424                     wxPropertyGrid* propgrid);
2425
2426     // Call after fixed sub-properties added/removed after creation.
2427     // if oldSelInd >= 0 and < new max items, then selection is
2428     // moved to it.
2429     void SubPropsChanged( int oldSelInd = -1 );
2430
2431     int GetY2( int lh ) const;
2432
2433     wxString                    m_label;
2434     wxString                    m_name;
2435     wxPGProperty*               m_parent;
2436     wxPropertyGridPageState*    m_parentState;
2437
2438     wxClientData*               m_clientObject;
2439
2440     // Overrides editor returned by property class
2441     const wxPGEditor*           m_customEditor;
2442 #if wxUSE_VALIDATORS
2443     // Editor is going to get this validator
2444     wxValidator*                m_validator;
2445 #endif
2446     // Show this in front of the value
2447     //
2448     // TODO: Can bitmap be implemented with wxPGCell?
2449     wxBitmap*                   m_valueBitmap;
2450
2451     wxVariant                   m_value;
2452     wxPGAttributeStorage        m_attributes;
2453     wxArrayPGProperty           m_children;
2454
2455     // Extended cell information
2456     wxVector<wxPGCell>          m_cells;
2457
2458     // Choices shown in drop-down list of editor control.
2459     wxPGChoices                 m_choices;
2460
2461     // Help shown in statusbar or help box.
2462     wxString                    m_helpString;
2463
2464     // Index in parent's property array.
2465     unsigned int                m_arrIndex;
2466
2467     // If not -1, then overrides m_value
2468     int                         m_commonValue;
2469
2470     FlagType                    m_flags;
2471
2472     // Maximum length (mainly for string properties). Could be in some sort of
2473     // wxBaseStringProperty, but currently, for maximum flexibility and
2474     // compatibility, we'll stick it here. Anyway, we had 3 excess bytes to use
2475     // so short int will fit in just fine.
2476     short                       m_maxLen;
2477
2478     // Root has 0, categories etc. at that level 1, etc.
2479     unsigned char               m_depth;
2480
2481     // m_depthBgCol indicates width of background colour between margin and item
2482     // (essentially this is category's depth, if none then equals m_depth).
2483     unsigned char               m_depthBgCol;
2484
2485 private:
2486     // Called in constructors.
2487     void Init();
2488     void Init( const wxString& label, const wxString& name );
2489 };
2490
2491 // -----------------------------------------------------------------------
2492
2493 //
2494 // Property class declaration helper macros
2495 // (wxPGRootPropertyClass and wxPropertyCategory require this).
2496 //
2497
2498 #define WX_PG_DECLARE_DOGETEDITORCLASS \
2499     virtual const wxPGEditor* DoGetEditorClass() const;
2500
2501 #ifndef WX_PG_DECLARE_PROPERTY_CLASS
2502     #define WX_PG_DECLARE_PROPERTY_CLASS(CLASSNAME) \
2503         public: \
2504             DECLARE_DYNAMIC_CLASS(CLASSNAME) \
2505             WX_PG_DECLARE_DOGETEDITORCLASS \
2506         private:
2507 #endif
2508
2509 // Implements sans constructor function. Also, first arg is class name, not
2510 // property name.
2511 #define WX_PG_IMPLEMENT_PROPERTY_CLASS_PLAIN(PROPNAME,T,EDITOR) \
2512 const wxPGEditor* PROPNAME::DoGetEditorClass() const \
2513 { \
2514     return wxPGEditor_##EDITOR; \
2515 }
2516
2517 // -----------------------------------------------------------------------
2518
2519 /** @class wxPGRootProperty
2520     @ingroup classes
2521     Root parent property.
2522 */
2523 class WXDLLIMPEXP_PROPGRID wxPGRootProperty : public wxPGProperty
2524 {
2525 public:
2526     WX_PG_DECLARE_PROPERTY_CLASS(wxPGRootProperty)
2527 public:
2528
2529     /** Constructor. */
2530     wxPGRootProperty( const wxString& name = wxS("<Root>") );
2531     virtual ~wxPGRootProperty();
2532
2533     virtual bool StringToValue( wxVariant&, const wxString&, int ) const
2534     {
2535         return false;
2536     }
2537
2538 protected:
2539 };
2540
2541 // -----------------------------------------------------------------------
2542
2543 /** @class wxPropertyCategory
2544     @ingroup classes
2545     Category (caption) property.
2546 */
2547 class WXDLLIMPEXP_PROPGRID wxPropertyCategory : public wxPGProperty
2548 {
2549     friend class wxPropertyGrid;
2550     friend class wxPropertyGridPageState;
2551     WX_PG_DECLARE_PROPERTY_CLASS(wxPropertyCategory)
2552 public:
2553
2554     /** Default constructor is only used in special cases. */
2555     wxPropertyCategory();
2556
2557     wxPropertyCategory( const wxString& label,
2558                         const wxString& name = wxPG_LABEL );
2559     ~wxPropertyCategory();
2560
2561     int GetTextExtent( const wxWindow* wnd, const wxFont& font ) const;
2562
2563     virtual wxString ValueToString( wxVariant& value, int argFlags ) const;
2564     virtual wxString GetValueAsString( int argFlags = 0 ) const;
2565
2566 protected:
2567     void SetTextColIndex( unsigned int colInd )
2568         { m_capFgColIndex = (wxByte) colInd; }
2569     unsigned int GetTextColIndex() const
2570         { return (unsigned int) m_capFgColIndex; }
2571
2572     void CalculateTextExtent( wxWindow* wnd, const wxFont& font );
2573
2574     int     m_textExtent;  // pre-calculated length of text
2575     wxByte  m_capFgColIndex;  // caption text colour index
2576
2577 private:
2578     void Init();
2579 };
2580
2581 // -----------------------------------------------------------------------
2582
2583 #endif // wxUSE_PROPGRID
2584
2585 #endif // _WX_PROPGRID_PROPERTY_H_