include/wx/propgrid/property.h

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