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