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