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