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