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