interface/wx/propgrid/propgrid.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        propgrid.h
   3 // Purpose:     interface of wxPropertyGrid
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id:
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @section propgrid_window_styles wxPropertyGrid Window Styles
  12
  13     SetWindowStyleFlag method can be used to modify some of these at run-time.
  14     @{
  15 */
  16 enum wxPG_WINDOW_STYLES
  17 {
  18
  19 /**
  20     This will cause Sort() automatically after an item is added.
  21     When inserting a lot of items in this mode, it may make sense to
  22     use Freeze() before operations and Thaw() afterwards to increase
  23     performance.
  24 */
  25 wxPG_AUTO_SORT                      = 0x00000010,
  26
  27 /**
  28     Categories are not initially shown (even if added).
  29     IMPORTANT NOTE: If you do not plan to use categories, then this
  30     style will waste resources.
  31     This flag can also be changed using wxPropertyGrid::EnableCategories method.
  32 */
  33 wxPG_HIDE_CATEGORIES                = 0x00000020,
  34
  35 /*
  36     This style combines non-categoric mode and automatic sorting.
  37 */
  38 wxPG_ALPHABETIC_MODE                = (wxPG_HIDE_CATEGORIES|wxPG_AUTO_SORT),
  39
  40 /**
  41     Modified values are shown in bold font. Changing this requires Refresh()
  42     to show changes.
  43 */
  44 wxPG_BOLD_MODIFIED                  = 0x00000040,
  45
  46 /**
  47     When wxPropertyGrid is resized, splitter moves to the center. This
  48     behavior stops once the user manually moves the splitter.
  49 */
  50 wxPG_SPLITTER_AUTO_CENTER           = 0x00000080,
  51
  52 /**
  53     Display tool tips for cell text that cannot be shown completely. If
  54     wxUSE_TOOLTIPS is 0, then this doesn't have any effect.
  55 */
  56 wxPG_TOOLTIPS                       = 0x00000100,
  57
  58 /**
  59     Disables margin and hides all expand/collapse buttons that would appear
  60     outside the margin (for sub-properties). Toggling this style automatically
  61     expands all collapsed items.
  62 */
  63 wxPG_HIDE_MARGIN                    = 0x00000200,
  64
  65 /**
  66     This style prevents user from moving the splitter.
  67 */
  68 wxPG_STATIC_SPLITTER                = 0x00000400,
  69
  70 /**
  71     Combination of other styles that make it impossible for user to modify
  72     the layout.
  73 */
  74 wxPG_STATIC_LAYOUT                  = (wxPG_HIDE_MARGIN|wxPG_STATIC_SPLITTER),
  75
  76 /**
  77     Disables wxTextCtrl based editors for properties which
  78     can be edited in another way. Equals calling
  79     wxPropertyGrid::LimitPropertyEditing() for all added properties.
  80 */
  81 wxPG_LIMITED_EDITING                = 0x00000800,
  82
  83 /**
  84     wxPropertyGridManager only: Show tool bar for mode and page selection.
  85 */
  86 wxPG_TOOLBAR                        = 0x00001000,
  87
  88 /**
  89     wxPropertyGridManager only: Show adjustable text box showing description
  90     or help text, if available, for currently selected property.
  91 */
  92 wxPG_DESCRIPTION                    = 0x00002000
  93
  94 };
  95
  96 enum wxPG_EX_WINDOW_STYLES
  97 {
  98
  99 /**
 100     NOTE: wxPG_EX_xxx are extra window styles and must be set using SetExtraStyle()
 101     member function.
 102
 103     Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if
 104     wxPG_HIDE_CATEGORIES is not defined, the non-categorized data storage is not
 105     activated, and switching the mode first time becomes somewhat slower.
 106     wxPG_EX_INIT_NOCAT activates the non-categorized data storage right away.
 107
 108     NOTE: If you do plan not switching to non-categoric mode, or if
 109     you don't plan to use categories at all, then using this style will result
 110     in waste of resources.
 111 */
 112 wxPG_EX_INIT_NOCAT                  = 0x00001000,
 113
 114 /**
 115     Extended window style that sets wxPropertyGridManager tool bar to not
 116     use flat style.
 117 */
 118 wxPG_EX_NO_FLAT_TOOLBAR             = 0x00002000,
 119
 120 /**
 121     Shows alphabetic/categoric mode buttons from tool bar.
 122 */
 123 wxPG_EX_MODE_BUTTONS                = 0x00008000,
 124
 125 /**
 126     Show property help strings as tool tips instead as text on the status bar.
 127     You can set the help strings using SetPropertyHelpString member function.
 128 */
 129 wxPG_EX_HELP_AS_TOOLTIPS            = 0x00010000,
 130
 131 /**
 132     Allows relying on native double-buffering.
 133 */
 134 wxPG_EX_NATIVE_DOUBLE_BUFFERING         = 0x00080000,
 135
 136 /**
 137     Set this style to let user have ability to set values of properties to
 138     unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for
 139     all properties.
 140 */
 141 wxPG_EX_AUTO_UNSPECIFIED_VALUES         = 0x00200000,
 142
 143 /**
 144     If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION and
 145     wxPG_STRING_PASSWORD) are not stored into property's attribute storage (thus
 146     they are not readable).
 147
 148     Note that this option is global, and applies to all wxPG property containers.
 149 */
 150 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES    = 0x00400000,
 151
 152 /**
 153     With this style Validators on properties will work same as in wxPropertyGrid
 154     1.2.
 155 */
 156 wxPG_EX_LEGACY_VALIDATORS               = 0x00800000,
 157
 158 /**
 159     Hides page selection buttons from tool bar.
 160 */
 161 wxPG_EX_HIDE_PAGE_BUTTONS               = 0x01000000
 162
 163 };
 164
 165 /** Combines various styles.
 166 */
 167 #define wxPG_DEFAULT_STYLE              (0)
 168
 169 /** Combines various styles.
 170 */
 171 #define wxPGMAN_DEFAULT_STYLE       (0)
 172
 173 /** @}
 174 */
 175
 176 // -----------------------------------------------------------------------
 177
 178 /**
 179     @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
 180     @{
 181 */
 182
 183 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
 184 {
 185
 186 /**
 187     Prevents user from leaving property unless value is valid. If this
 188     behavior flag is not used, then value change is instead cancelled.
 189 */
 190 wxPG_VFB_STAY_IN_PROPERTY           = 0x01,
 191
 192 /**
 193     Calls wxBell() on validation failure.
 194 */
 195 wxPG_VFB_BEEP                       = 0x02,
 196
 197 /**
 198     Cell with invalid value will be marked (with red colour).
 199 */
 200 wxPG_VFB_MARK_CELL                  = 0x04,
 201
 202 /**
 203     Display customizable text message explaining the situation.
 204 */
 205 wxPG_VFB_SHOW_MESSAGE               = 0x08,
 206
 207 /**
 208     Defaults.
 209 */
 210 wxPG_VFB_DEFAULT                    = wxPG_VFB_STAY_IN_PROPERTY|wxPG_VFB_BEEP,
 211 };
 212
 213 /** @}
 214 */
 215
 216 typedef wxByte wxPGVFBFlags;
 217
 218 /**
 219     wxPGValidationInfo
 220
 221     Used to convey validation information to and from functions that
 222     actually perform validation. Mostly used in custom property
 223     classes.
 224 */
 225 class wxPGValidationInfo
 226 {
 227 public:
 228     /**
 229         @return Returns failure behavior which is a combination of
 230                @ref propgrid_vfbflags.
 231     */
 232     wxPGVFBFlags GetFailureBehavior();
 233
 234     /**
 235         Returns current failure message.
 236     */
 237     const wxString& GetFailureMessage() const;
 238
 239     /**
 240         Returns reference to pending value.
 241     */
 242     const wxVariant& GetValue() const;
 243
 244     /** Set validation failure behavior
 245
 246         @param failureBehavior
 247             Mixture of @ref propgrid_vfbflags.
 248     */
 249     void SetFailureBehavior(wxPGVFBFlags failureBehavior);
 250
 251     /**
 252         Set current failure message.
 253     */
 254     void SetFailureMessage(const wxString& message);
 255 };
 256
 257 // -----------------------------------------------------------------------
 258
 259 /**
 260     @section propgrid_keyboard_actions wxPropertyGrid Action Identifiers
 261     These are used with wxPropertyGrid::AddActionTrigger() and
 262     wxPropertyGrid::ClearActionTriggers().
 263     @{
 264 */
 265
 266 enum wxPG_KEYBOARD_ACTIONS
 267 {
 268     wxPG_ACTION_INVALID = 0,
 269     wxPG_ACTION_NEXT_PROPERTY,
 270     wxPG_ACTION_PREV_PROPERTY,
 271     wxPG_ACTION_EXPAND_PROPERTY,
 272     wxPG_ACTION_COLLAPSE_PROPERTY,
 273     wxPG_ACTION_CANCEL_EDIT,
 274     wxPG_ACTION_CUT,
 275     wxPG_ACTION_COPY,
 276     wxPG_ACTION_PASTE,
 277     wxPG_ACTION_MAX
 278 };
 279
 280 /** @}
 281 */
 282
 283 // -----------------------------------------------------------------------
 284
 285 /** @class wxPropertyGrid
 286
 287       wxPropertyGrid is a specialized grid for editing properties - in other
 288     words name = value pairs. List of ready-to-use property classes include
 289     strings, numbers, flag sets, fonts, colours and many others. It is possible,
 290     for example, to categorize properties, set up a complete tree-hierarchy,
 291     add more than two columns, and set arbitrary per-property attributes.
 292
 293     Please note that most member functions are inherited and as such not
 294     documented on this page. This means you will probably also want to read
 295     wxPropertyGridInterface class reference.
 296
 297     See also @ref overview_propgrid.
 298
 299     @section propgrid_window_styles_ Window Styles
 300
 301     See @ref propgrid_window_styles.
 302
 303     @section propgrid_event_handling Event Handling
 304
 305     To process input from a property grid control, use these event handler macros
 306     to direct input to member functions that take a wxPropertyGridEvent argument.
 307
 308     @beginEventTable{wxPropertyGridEvent}
 309     @event{EVT_PG_SELECTED (id, func)}
 310         Respond to wxEVT_PG_SELECTED event, generated when property value
 311         has been changed by user.
 312     @event{EVT_PG_CHANGING(id, func)}
 313         Respond to wxEVT_PG_CHANGING event, generated when property value
 314         is about to be changed by user. Use wxPropertyGridEvent::GetValue()
 315         to take a peek at the pending value, and wxPropertyGridEvent::Veto()
 316         to prevent change from taking place, if necessary.
 317     @event{EVT_PG_HIGHLIGHTED(id, func)}
 318         Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
 319         moves over a property. Event's property is NULL if hovered area does
 320         not belong to any property.
 321     @event{EVT_PG_RIGHT_CLICK(id, func)}
 322         Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
 323         clicked on with right mouse button.
 324     @event{EVT_PG_DOUBLE_CLICK(id, func)}
 325         Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
 326         double-clicked on with left mouse button.
 327     @event{EVT_PG_ITEM_COLLAPSED(id, func)}
 328         Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
 329         a property or category.
 330     @event{EVT_PG_ITEM_EXPANDED(id, func)}
 331         Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
 332         a property or category.
 333     @endEventTable
 334
 335     @remarks
 336
 337     - Use Freeze() and Thaw() respectively to disable and enable drawing. This
 338       will also delay sorting etc. miscellaneous calculations to the last
 339       possible moment.
 340
 341     @library{wxpropgrid}
 342     @category{propgrid}
 343 */
 344 class wxPropertyGrid : public wxScrolledWindow, public wxPropertyGridInterface
 345 {
 346 public:
 347
 348         /**
 349         Two step constructor. Call Create when this constructor is called to
 350         build up the wxPropertyGrid
 351         */
 352     wxPropertyGrid();
 353
 354     /**
 355         Constructor. The styles to be used are styles valid for
 356         the wxWindow and wxScrolledWindow.
 357
 358         @see @ref propgrid_window_styles.
 359     */
 360     wxPropertyGrid( wxWindow *parent, wxWindowID id = wxID_ANY,
 361                     const wxPoint& pos = wxDefaultPosition,
 362                     const wxSize& size = wxDefaultSize,
 363                     long style = wxPG_DEFAULT_STYLE,
 364                     const wxChar* name = wxPropertyGridNameStr );
 365
 366     /** Destructor */
 367     virtual ~wxPropertyGrid();
 368
 369     /**
 370         Adds given key combination to trigger given action.
 371
 372         @param action
 373             Which action to trigger. See @ref propgrid_keyboard_actions.
 374
 375         @param keycode
 376             Which keycode triggers the action.
 377
 378         @param modifiers
 379             Which key event modifiers, in addition to keycode, are needed to
 380             trigger the action.
 381     */
 382     void AddActionTrigger( int action, int keycode, int modifiers = 0 );
 383
 384     /**
 385         This static function enables or disables automatic use of
 386         wxGetTranslation() for following strings: wxEnumProperty list labels,
 387         wxFlagsProperty child property labels.
 388
 389         Default is false.
 390     */
 391     static void AutoGetTranslation( bool enable );
 392
 393     /**
 394         Changes value of a property, as if from an editor. Use this instead of
 395         SetPropertyValue() if you need the value to run through validation
 396         process, and also send the property change event.
 397
 398         @return Returns true if value was successfully changed.
 399     */
 400     bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
 401
 402     /**
 403         Centers the splitter. If argument is true, automatic splitter centering
 404         is enabled (only applicable if style wxPG_SPLITTER_AUTO_CENTER was
 405         defined).
 406     */
 407     void CenterSplitter( bool enable_auto_centering = false );
 408
 409     /**
 410         Deletes all properties.
 411     */
 412     virtual void Clear();
 413
 414     /**
 415         Clears action triggers for given action.
 416
 417         @param action
 418             Which action to trigger. @ref propgrid_keyboard_actions.
 419     */
 420     void ClearActionTriggers( int action );
 421
 422     /**
 423         Forces updating the value of property from the editor control.
 424         Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
 425         ProcessEvent, meaning your event handlers will be called immediately.
 426
 427         @return Returns @true if anything was changed.
 428     */
 429     virtual bool CommitChangesFromEditor( wxUint32 flags = 0 );
 430
 431     /**
 432         Two step creation. Whenever the control is created without any
 433         parameters, use Create to actually create it. Don't access the control's
 434         public methods before this is called
 435
 436         @see @ref propgrid_window_styles.
 437     */
 438     bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
 439                  const wxPoint& pos = wxDefaultPosition,
 440                  const wxSize& size = wxDefaultSize,
 441                  long style = wxPG_DEFAULT_STYLE,
 442                  const wxChar* name = wxPropertyGridNameStr );
 443
 444     /**
 445         Call when editor widget's contents is modified. For example, this is
 446         called when changes text in wxTextCtrl (used in wxStringProperty and
 447         wxIntProperty).
 448
 449         @remarks This function should only be called by custom properties.
 450
 451         @see wxPGProperty::OnEvent()
 452     */
 453     void EditorsValueWasModified() { m_iFlags |= wxPG_FL_VALUE_MODIFIED; }
 454
 455     /**
 456         Reverse of EditorsValueWasModified().
 457
 458         @remarks This function should only be called by custom properties.
 459     */
 460     void EditorsValueWasNotModified()
 461     {
 462         m_iFlags &= ~(wxPG_FL_VALUE_MODIFIED);
 463     }
 464
 465     /**
 466         Enables or disables (shows/hides) categories according to parameter
 467         enable.
 468     */
 469     bool EnableCategories( bool enable );
 470
 471     /**
 472         Scrolls and/or expands items to ensure that the given item is visible.
 473
 474         @return Returns @true if something was actually done.
 475     */
 476     bool EnsureVisible( wxPGPropArg id );
 477
 478     /**
 479         Reduces column sizes to minimum possible, while still retaining
 480         fully visible grid contents (labels, images).
 481
 482         @return Minimum size for the grid to still display everything.
 483
 484         @remarks Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
 485
 486                 This function only works properly if grid size prior to call was
 487                 already fairly large.
 488
 489                 Note that you can also get calculated column widths by calling
 490                 GetState->GetColumnWidth() immediately after this function
 491                 returns.
 492     */
 493     wxSize FitColumns();
 494
 495     /**
 496         Returns wxWindow that the properties are painted on, and which should be
 497         used as the parent for editor controls.
 498     */
 499     wxPanel* GetPanel() const;
 500
 501     /**
 502         Returns current category caption background colour.
 503     */
 504     wxColour GetCaptionBackgroundColour() const;
 505
 506     /**
 507         Returns current category caption font.
 508     */
 509     wxFont& GetCaptionFont();
 510
 511     /**
 512         Returns current category caption text colour.
 513     */
 514     wxColour GetCaptionForegroundColour() const;
 515
 516     /**
 517         Returns current cell background colour.
 518     */
 519     wxColour GetCellBackgroundColour() const;
 520
 521     /**
 522         Returns current cell text colour when disabled.
 523     */
 524     wxColour GetCellDisabledTextColour() const;
 525
 526     /**
 527         Returns current cell text colour.
 528     */
 529     wxColour GetCellTextColour() const;
 530
 531     /**
 532         Returns number of columns currently on grid.
 533     */
 534     int GetColumnCount() const;
 535
 536     /**
 537         Returns colour of empty space below properties.
 538     */
 539     wxColour GetEmptySpaceColour() const;
 540
 541     /**
 542         Returns height of highest characters of used font.
 543     */
 544     int GetFontHeight() const;
 545
 546     /**
 547         Returns pointer to itself. Dummy function that enables same kind
 548         of code to use wxPropertyGrid and wxPropertyGridManager.
 549     */
 550     wxPropertyGrid* GetGrid();
 551
 552     /**
 553         Returns rectangle of custom paint image.
 554
 555         @param property
 556             Return image rectangle for this property.
 557
 558         @param item
 559             Which choice of property to use (each choice may have
 560             different image).
 561     */
 562     wxRect GetImageRect( wxPGProperty* property, int item ) const;
 563
 564     /**
 565         Returns size of the custom paint image in front of property.
 566
 567         @param property
 568             Return image rectangle for this property.
 569             If this argument is NULL, then preferred size is returned.
 570
 571         @param item
 572             Which choice of property to use (each choice may have
 573             different image).
 574     */
 575     wxSize GetImageSize( wxPGProperty* property = NULL, int item = -1 ) const;
 576
 577     /**
 578         Returns last item which could be iterated using given flags.
 579
 580         @param flags
 581             See @ref propgrid_iterator_flags.
 582     */
 583     wxPGProperty* GetLastItem( int flags = wxPG_ITERATE_DEFAULT );
 584
 585     /**
 586         Returns colour of lines between cells.
 587     */
 588     wxColour GetLineColour() const;
 589
 590     /**
 591         Returns background colour of margin.
 592     */
 593     wxColour GetMarginColour() const;
 594
 595     /**
 596         Returns cell background colour of a property.
 597     */
 598     wxColour GetPropertyBackgroundColour( wxPGPropArg id ) const;
 599
 600     /**
 601         Returns cell background colour of a property.
 602     */
 603     wxColour GetPropertyTextColour( wxPGPropArg id ) const;
 604
 605     /**
 606         Returns "root property". It does not have name, etc. and it is not
 607         visible. It is only useful for accessing its children.
 608     */
 609     wxPGProperty* GetRoot() const;
 610
 611     /**
 612         Returns height of a single grid row (in pixels).
 613     */
 614     int GetRowHeight() const;
 615
 616     /**
 617         Returns currently selected property.
 618     */
 619     wxPGProperty* GetSelectedProperty() const;
 620
 621     /**
 622         Returns currently selected property.
 623     */
 624     wxPGProperty* GetSelection() const;
 625
 626     /**
 627         Returns current selection background colour.
 628     */
 629     wxColour GetSelectionBackgroundColour() const;
 630
 631     /**
 632         Returns current selection text colour.
 633     */
 634     wxColour GetSelectionForegroundColour() const;
 635
 636     /**
 637         Returns current splitter x position.
 638     */
 639     int GetSplitterPosition() const;
 640
 641     /**
 642         Returns wxTextCtrl active in currently selected property, if any. Takes
 643         wxOwnerDrawnComboBox into account.
 644     */
 645     wxTextCtrl* GetEditorTextCtrl() const;
 646
 647     /**
 648         Returns current vertical spacing.
 649     */
 650     int GetVerticalSpacing() const { return (int)m_vspacing; }
 651
 652     /**
 653         Returns true if editor's value was marked modified.
 654     */
 655     bool IsEditorsValueModified() const;
 656
 657     /**
 658         Returns information about arbitrary position in the grid.
 659     */
 660     wxPropertyGridHitTestResult HitTest( const wxPoint& pt ) const;
 661
 662     /**
 663         Returns true if any property has been modified by the user.
 664     */
 665     bool IsAnyModified() const;
 666
 667     /**
 668         Returns true if updating is frozen (ie. Freeze() called but not
 669         yet Thaw() ).
 670     */
 671     bool IsFrozen() const;
 672
 673     /**
 674         Redraws given property.
 675     */
 676     virtual void RefreshProperty( wxPGProperty* p );
 677
 678     /**
 679         Registers a new editor class.
 680
 681         @return Returns pointer  to the editor class instance that should be used.
 682     */
 683     static wxPGEditor* RegisterEditorClass( wxPGEditor* editor,
 684                                             const wxString& name,
 685                                             bool noDefCheck = false );
 686
 687     /**
 688         Resets all colours to the original system values.
 689     */
 690     void ResetColours();
 691
 692     /**
 693         Selects a property. Editor widget is automatically created, but
 694         not focused unless focus is true. This will generate wxEVT_PG_SELECT
 695         event.
 696
 697         @param id
 698             Property to select (name or pointer).
 699
 700         @param focus
 701             If @true, move keyboard focus to the created editor right away.
 702
 703         @return returns @true if selection finished successfully. Usually only
 704         fails if current value in editor is not valid.
 705
 706         @see wxPropertyGrid::ClearSelection()
 707     */
 708     bool SelectProperty( wxPGPropArg id, bool focus = false );
 709
 710     /**
 711         Changes keyboard shortcut to push the editor button.
 712
 713         @remarks You can set default with keycode 0. Good value for the platform
 714                 is guessed, but don't expect it to be very accurate.
 715     */
 716     void SetButtonShortcut( int keycode, bool ctrlDown = false, bool altDown = false );
 717
 718     /**
 719         Sets category caption background colour.
 720     */
 721     void SetCaptionBackgroundColour(const wxColour& col);
 722
 723     /**
 724         Sets category caption text colour.
 725     */
 726     void SetCaptionTextColour(const wxColour& col);
 727
 728     /**
 729         Sets default cell background colour - applies to property cells.
 730         Note that appearance of editor widgets may not be affected.
 731     */
 732     void SetCellBackgroundColour(const wxColour& col);
 733
 734     /**
 735         Sets cell text colour for disabled properties.
 736     */
 737     void SetCellDisabledTextColour(const wxColour& col);
 738
 739     /**
 740         Sets default cell text colour - applies to property name and value text.
 741         Note that appearance of editor widgets may not be affected.
 742     */
 743     void SetCellTextColour(const wxColour& col);
 744
 745     /**
 746         Set number of columns (2 or more).
 747     */
 748     void SetColumnCount( int colCount );
 749
 750     /**
 751         Sets the 'current' category - Append will add non-category properties
 752         under it.
 753     */
 754     void SetCurrentCategory( wxPGPropArg id );
 755
 756     /**
 757         Sets colour of empty space below properties.
 758     */
 759     void SetEmptySpaceColour(const wxColour& col);
 760
 761     /**
 762         Sets colour of lines between cells.
 763     */
 764     void SetLineColour(const wxColour& col);
 765
 766     /**
 767         Sets background colour of margin.
 768     */
 769     void SetMarginColour(const wxColour& col);
 770
 771     /**
 772         Sets background colour of property and all its children. Colours of
 773         captions are not affected. Background brush cache is optimized for often
 774         set colours to be set last.
 775     */
 776     void SetPropertyBackgroundColour( wxPGPropArg id, const wxColour& col );
 777
 778     /**
 779         Resets text and background colours of given property.
 780     */
 781     void SetPropertyColoursToDefault( wxPGPropArg id );
 782
 783     /**
 784         Sets text colour of property and all its children.
 785     */
 786     void SetPropertyTextColour( wxPGPropArg id, const wxColour& col,
 787                                 bool recursively = true );
 788
 789     /** Sets selection background colour - applies to selected property name
 790         background. */
 791     void SetSelectionBackgroundColour(const wxColour& col);
 792
 793     /** Sets selection foreground colour - applies to selected property name
 794         text. */
 795     void SetSelectionTextColour(const wxColour& col);
 796
 797     /** Sets x coordinate of the splitter.
 798
 799         @remarks Splitter position cannot exceed grid size, and therefore setting
 800                 it during form creation may fail as initial grid size is often
 801                 smaller than desired splitter position, especially when sizers
 802                 are being used.
 803     */
 804     void SetSplitterPosition( int newxpos, int col = 0 );
 805
 806     /**
 807         Sets name of a property.
 808
 809         @param id
 810             Name or pointer of property which name to change.
 811
 812         @param newname
 813             New name.
 814     */
 815     void SetPropertyName( wxPGPropArg id, const wxString& newname );
 816
 817     /**
 818         Moves splitter as left as possible, while still allowing all
 819         labels to be shown in full.
 820
 821         @param privateChildrenToo
 822             If @false, will still allow private children to be cropped.
 823     */
 824     void SetSplitterLeft( bool privateChildrenToo = false )
 825     {
 826         m_pState->SetSplitterLeft(subProps);
 827     }
 828
 829     /**
 830         Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
 831         height. Value of 2 should be default on most platforms.
 832     */
 833     void SetVerticalSpacing( int vspacing );
 834
 835     /**
 836         Shows an brief error message that is related to a property.
 837     */
 838     void ShowPropertyError( wxPGPropArg id, const wxString& msg );
 839
 840     /**
 841         Sorts all items at all levels (except private children).
 842     */
 843     void Sort();
 844
 845     /**
 846         Sorts children of a property.
 847     */
 848     void SortChildren( wxPGPropArg id );
 849 };
 850
 851
 852 /**
 853     @class wxPropertyGridEvent
 854
 855     A property grid event holds information about events associated with
 856     wxPropertyGrid objects.
 857
 858     @library{wxpropgrid}
 859     @category{propgrid}
 860 */
 861 class wxPropertyGridEvent : public wxCommandEvent
 862 {
 863 public:
 864
 865     /** Constructor. */
 866     wxPropertyGridEvent(wxEventType commandType=0, int id=0);
 867
 868     /** Copy constructor. */
 869     wxPropertyGridEvent(const wxPropertyGridEvent& event);
 870
 871     /** Destructor. */
 872     ~wxPropertyGridEvent();
 873
 874     /**
 875         Returns true if you can veto the action that the event is signaling.
 876     */
 877     bool CanVeto() const { return m_canVeto; }
 878
 879     /** Copyer. */
 880     virtual wxEvent* Clone() const;
 881
 882     /**
 883         Returns highest level non-category, non-root parent of property for
 884         which event occurred. Useful when you have nested properties with
 885         children.
 886
 887         @remarks If immediate parent is root or category, this will return the
 888                 property itself.
 889     */
 890     wxPGProperty* GetMainParent() const;
 891
 892     /**
 893         Returns property associated with this event.
 894     */
 895     wxPGProperty* GetProperty() const;
 896
 897     /**
 898         Returns current validation failure flags.
 899     */
 900     wxPGVFBFlags GetValidationFailureBehavior() const;
 901
 902     /**
 903         Returns value that is about to be set for wxEVT_PG_CHANGING.
 904     */
 905     const wxVariant& GetValue() const;
 906
 907     /**
 908         Set if event can be vetoed.
 909     */
 910     void SetCanVeto( bool canVeto );
 911
 912     /** Changes the property associated with this event. */
 913     void SetProperty( wxPGProperty* p );
 914
 915     /**
 916         Set override validation failure behavior. Only effective if Veto() was
 917         also called, and only allowed if event type is wxEVT_PG_CHANGING.
 918     */
 919     void SetValidationFailureBehavior( wxPGVFBFlags flags );
 920
 921     /**
 922         Sets custom failure message for this time only. Only applies if
 923         wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
 924     */
 925     void SetValidationFailureMessage( const wxString& message );
 926
 927     /**
 928         Call this from your event handler to veto action that the event is
 929         signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto()
 930         returns true.
 931
 932         @remarks Currently only wxEVT_PG_CHANGING supports vetoing.
 933     */
 934     void Veto( bool veto = true );
 935
 936     /**
 937         Returns @true if event was vetoed.
 938     */
 939     bool WasVetoed() const;
 940 };