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