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