include/wx/propgrid/property.h

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