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