include/wx/propgrid/property.h

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