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