include/wx/propgrid/property.h

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