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