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