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