include/wx/propgrid/property.h

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