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 user is
 393         about to begin editing a property label. You can veto this event to
 394         prevent the action.
 395     @event{EVT_PG_LABEL_EDIT_ENDING(id, func)}
 396         Respond to wxEVT_PG_LABEL_EDIT_ENDING event, generated when user is
 397         about to end editing of a property label. You can veto this event to
 398         prevent the 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 colIndex = 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.
 507
 508         @param enableAutoResizing
 509             If @true, automatic column resizing is enabled (only applicapple
 510             if window style wxPG_SPLITTER_AUTO_CENTER is used).
 511     */
 512     void CenterSplitter( bool enableAutoResizing = false );
 513
 514     /**
 515         Deletes all properties.
 516     */
 517     virtual void Clear();
 518
 519     /**
 520         Clears action triggers for given action.
 521
 522         @param action
 523             Which action to trigger. @ref propgrid_keyboard_actions.
 524     */
 525     void ClearActionTriggers( int action );
 526
 527     /**
 528         Forces updating the value of property from the editor control.
 529         Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
 530         ProcessEvent, meaning your event handlers will be called immediately.
 531
 532         @return Returns @true if anything was changed.
 533     */
 534     virtual bool CommitChangesFromEditor( wxUint32 flags = 0 );
 535
 536     /**
 537         Two step creation. Whenever the control is created without any
 538         parameters, use Create to actually create it. Don't access the control's
 539         public methods before this is called
 540
 541         @see @ref propgrid_window_styles.
 542     */
 543     bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
 544                 const wxPoint& pos = wxDefaultPosition,
 545                 const wxSize& size = wxDefaultSize,
 546                 long style = wxPG_DEFAULT_STYLE,
 547                 const wxChar* name = wxPropertyGridNameStr );
 548
 549     /**
 550         Enables or disables (shows/hides) categories according to parameter
 551         enable.
 552
 553         @remarks This functions deselects selected property, if any. Validation
 554                 failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie.
 555                 selection is cleared even if editor had invalid value.
 556     */
 557     bool EnableCategories( bool enable );
 558
 559     /**
 560         Destroys label editor wxTextCtrl, if any.
 561
 562         @param commit
 563             Use @true (default) to store edited label text in
 564             property cell data.
 565
 566         @see BeginLabelEdit(), MakeColumnEditable()
 567     */
 568     void EndLabelEdit( bool commit = true );
 569
 570     /**
 571         Scrolls and/or expands items to ensure that the given item is visible.
 572
 573         @return Returns @true if something was actually done.
 574     */
 575     bool EnsureVisible( wxPGPropArg id );
 576
 577     /**
 578         Reduces column sizes to minimum possible, while still retaining
 579         fully visible grid contents (labels, images).
 580
 581         @return Minimum size for the grid to still display everything.
 582
 583         @remarks Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
 584
 585                 This function only works properly if grid size prior to call was
 586                 already fairly large.
 587
 588                 Note that you can also get calculated column widths by calling
 589                 GetState->GetColumnWidth() immediately after this function
 590                 returns.
 591     */
 592     wxSize FitColumns();
 593
 594     /**
 595         Returns currently active label editor, NULL if none.
 596     */
 597     wxTextCtrl* GetLabelEditor() const;
 598
 599     /**
 600         Returns wxWindow that the properties are painted on, and which should be
 601         used as the parent for editor controls.
 602     */
 603     wxWindow* GetPanel();
 604
 605     /**
 606         Returns current category caption background colour.
 607     */
 608     wxColour GetCaptionBackgroundColour() const;
 609
 610     /**
 611         Returns current category caption font.
 612     */
 613     wxFont& GetCaptionFont();
 614
 615     /**
 616         Returns current category caption text colour.
 617     */
 618     wxColour GetCaptionForegroundColour() const;
 619
 620     /**
 621         Returns current cell background colour.
 622     */
 623     wxColour GetCellBackgroundColour() const;
 624
 625     /**
 626         Returns current cell text colour when disabled.
 627     */
 628     wxColour GetCellDisabledTextColour() const;
 629
 630     /**
 631         Returns current cell text colour.
 632     */
 633     wxColour GetCellTextColour() const;
 634
 635     /**
 636         Returns number of columns currently on grid.
 637     */
 638     unsigned int GetColumnCount() const;
 639
 640     /**
 641         Returns colour of empty space below properties.
 642     */
 643     wxColour GetEmptySpaceColour() const;
 644
 645     /**
 646         Returns height of highest characters of used font.
 647     */
 648     int GetFontHeight() const;
 649
 650     /**
 651         Returns pointer to itself. Dummy function that enables same kind
 652         of code to use wxPropertyGrid and wxPropertyGridManager.
 653     */
 654     wxPropertyGrid* GetGrid();
 655
 656     /**
 657         Returns rectangle of custom paint image.
 658
 659         @param property
 660             Return image rectangle for this property.
 661
 662         @param item
 663             Which choice of property to use (each choice may have
 664             different image).
 665     */
 666     wxRect GetImageRect( wxPGProperty* property, int item ) const;
 667
 668     /**
 669         Returns size of the custom paint image in front of property.
 670
 671         @param property
 672             Return image rectangle for this property.
 673             If this argument is NULL, then preferred size is returned.
 674
 675         @param item
 676             Which choice of property to use (each choice may have
 677             different image).
 678     */
 679     wxSize GetImageSize( wxPGProperty* property = NULL, int item = -1 ) const;
 680
 681     /**
 682         Returns last item which could be iterated using given flags.
 683
 684         @param flags
 685             See @ref propgrid_iterator_flags.
 686     */
 687     wxPGProperty* GetLastItem( int flags = wxPG_ITERATE_DEFAULT );
 688
 689     /**
 690         Returns colour of lines between cells.
 691     */
 692     wxColour GetLineColour() const;
 693
 694     /**
 695         Returns background colour of margin.
 696     */
 697     wxColour GetMarginColour() const;
 698
 699     /**
 700         Returns "root property". It does not have name, etc. and it is not
 701         visible. It is only useful for accessing its children.
 702     */
 703     wxPGProperty* GetRoot() const;
 704
 705     /**
 706         Returns height of a single grid row (in pixels).
 707     */
 708     int GetRowHeight() const;
 709
 710     /**
 711         Returns currently selected property.
 712     */
 713     wxPGProperty* GetSelectedProperty() const;
 714
 715     /**
 716         Returns currently selected property.
 717     */
 718     wxPGProperty* GetSelection() const;
 719
 720     /**
 721         Returns current selection background colour.
 722     */
 723     wxColour GetSelectionBackgroundColour() const;
 724
 725     /**
 726         Returns current selection text colour.
 727     */
 728     wxColour GetSelectionForegroundColour() const;
 729
 730     /**
 731         Returns the property sort function (default is @NULL).
 732
 733         @see SetSortFunction
 734     */
 735     wxPGSortCallback GetSortFunction() const;
 736
 737     /**
 738         Returns current splitter x position.
 739     */
 740     int GetSplitterPosition( unsigned int splitterIndex = 0 ) const;
 741
 742     /**
 743         Returns wxTextCtrl active in currently selected property, if any. Takes
 744         wxOwnerDrawnComboBox into account.
 745     */
 746     wxTextCtrl* GetEditorTextCtrl() const;
 747
 748     /**
 749         Returns current appearance of unspecified value cells.
 750
 751         @see SetUnspecifiedValueAppearance()
 752     */
 753     const wxPGCell& GetUnspecifiedValueAppearance() const;
 754
 755     /**
 756         Returns (visual) text representation of the unspecified
 757         property value.
 758
 759         @param argFlags For internal use only.
 760     */
 761     wxString GetUnspecifiedValueText( int argFlags = 0 ) const;
 762
 763     /**
 764         Returns current vertical spacing.
 765     */
 766     int GetVerticalSpacing() const;
 767
 768     /**
 769         Returns information about arbitrary position in the grid.
 770
 771         @param pt
 772             Coordinates in the virtual grid space. You may need to use
 773             wxScrolledWindow::CalcScrolledPosition() for translating
 774             wxPropertyGrid client coordinates into something this member
 775             function can use.
 776     */
 777     wxPropertyGridHitTestResult HitTest( const wxPoint& pt ) const;
 778
 779     /**
 780         Returns true if any property has been modified by the user.
 781     */
 782     bool IsAnyModified() const;
 783
 784     /**
 785         Returns @true if a property editor control has focus.
 786     */
 787     bool IsEditorFocused() const;
 788
 789     /**
 790         Returns true if updating is frozen (ie. Freeze() called but not
 791         yet Thaw() ).
 792     */
 793     bool IsFrozen() const;
 794
 795     /**
 796         Makes given column editable by user.
 797
 798         @param column
 799             The index of the column to make editable.
 800         @param editable
 801             Using @false here will disable column from being editable.
 802
 803         @see BeginLabelEdit(), EndLabelEdit()
 804     */
 805     void MakeColumnEditable( unsigned int column, bool editable = true );
 806
 807     /**
 808         It is recommended that you call this function any time your code causes
 809         wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle()
 810         handler should be able to detect most changes, but it is not perfect.
 811
 812         @param newTLP
 813             New top-level parent that is about to be set. Old top-level parent
 814             window should still exist as the current one.
 815
 816         @remarks This function is automatically called from wxPropertyGrid::
 817                  Reparent() and wxPropertyGridManager::Reparent(). You only
 818                  need to use it if you reparent wxPropertyGrid indirectly.
 819     */
 820     void OnTLPChanging( wxWindow* newTLP );
 821
 822     /**
 823         Refreshes any active editor control.
 824     */
 825     void RefreshEditor();
 826
 827     /**
 828         Redraws given property.
 829     */
 830     virtual void RefreshProperty( wxPGProperty* p );
 831
 832     /**
 833         Registers a new editor class.
 834
 835         @return Returns pointer  to the editor class instance that should be used.
 836     */
 837     static wxPGEditor* RegisterEditorClass( wxPGEditor* editor,
 838                                             const wxString& name,
 839                                             bool noDefCheck = false );
 840
 841     /**
 842         Resets all colours to the original system values.
 843     */
 844     void ResetColours();
 845
 846     /**
 847         Resets column sizes and splitter positions, based on proportions.
 848
 849         @param enableAutoResizing
 850             If @true, automatic column resizing is enabled (only applicapple
 851             if window style wxPG_SPLITTER_AUTO_CENTER is used).
 852
 853         @see wxPropertyGridInterface::SetColumnProportion()
 854     */
 855     void ResetColumnSizes( bool enableAutoResizing = false );
 856
 857     /**
 858         Removes given property from selection. If property is not selected,
 859         an assertion failure will occur.
 860     */
 861     bool RemoveFromSelection( wxPGPropArg id );
 862
 863     /**
 864         Selects a property. Editor widget is automatically created, but
 865         not focused unless focus is true.
 866
 867         @param id
 868             Property to select (name or pointer).
 869
 870         @param focus
 871             If @true, move keyboard focus to the created editor right away.
 872
 873         @return returns @true if selection finished successfully. Usually only
 874         fails if current value in editor is not valid.
 875
 876         @remarks In wxPropertyGrid 1.4, this member function used to generate
 877                  wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer
 878                  does that.
 879
 880         @remarks This clears any previous selection.
 881
 882         @see wxPropertyGridInterface::ClearSelection()
 883     */
 884     bool SelectProperty( wxPGPropArg id, bool focus = false );
 885
 886     /**
 887         Changes keyboard shortcut to push the editor button.
 888
 889         @remarks You can set default with keycode 0. Good value for the platform
 890                 is guessed, but don't expect it to be very accurate.
 891     */
 892     void SetButtonShortcut( int keycode, bool ctrlDown = false, bool altDown = false );
 893
 894     /**
 895         Sets category caption background colour.
 896     */
 897     void SetCaptionBackgroundColour(const wxColour& col);
 898
 899     /**
 900         Sets category caption text colour.
 901     */
 902     void SetCaptionTextColour(const wxColour& col);
 903
 904     /**
 905         Sets default cell background colour - applies to property cells.
 906         Note that appearance of editor widgets may not be affected.
 907     */
 908     void SetCellBackgroundColour(const wxColour& col);
 909
 910     /**
 911         Sets cell text colour for disabled properties.
 912     */
 913     void SetCellDisabledTextColour(const wxColour& col);
 914
 915     /**
 916         Sets default cell text colour - applies to property name and value text.
 917         Note that appearance of editor widgets may not be affected.
 918     */
 919     void SetCellTextColour(const wxColour& col);
 920
 921     /**
 922         Set number of columns (2 or more).
 923     */
 924     void SetColumnCount( int colCount );
 925
 926     /**
 927         Sets the 'current' category - Append will add non-category properties
 928         under it.
 929     */
 930     void SetCurrentCategory( wxPGPropArg id );
 931
 932     /**
 933         Sets colour of empty space below properties.
 934     */
 935     void SetEmptySpaceColour(const wxColour& col);
 936
 937     /**
 938         Sets colour of lines between cells.
 939     */
 940     void SetLineColour(const wxColour& col);
 941
 942     /**
 943         Sets background colour of margin.
 944     */
 945     void SetMarginColour(const wxColour& col);
 946
 947     /**
 948         Set entire new selection from given list of properties.
 949     */
 950     void SetSelection( const wxArrayPGProperty& newSelection );
 951
 952     /**
 953         Sets selection background colour - applies to selected property name
 954         background.
 955     */
 956     void SetSelectionBackgroundColour(const wxColour& col);
 957
 958     /**
 959         Sets selection foreground colour - applies to selected property name text.
 960     */
 961     void SetSelectionTextColour(const wxColour& col);
 962
 963
 964     /**
 965         Sets the property sorting function.
 966
 967         @param sortFunction
 968             The sorting function to be used. It should return a value greater
 969             than 0 if position of p1 is after p2. So, for instance, when
 970             comparing property names, you can use following implementation:
 971
 972             @code
 973                 int MyPropertySortFunction(wxPropertyGrid* propGrid,
 974                                            wxPGProperty* p1,
 975                                            wxPGProperty* p2)
 976                 {
 977                     return p1->GetBaseName().compare( p2->GetBaseName() );
 978                 }
 979             @endcode
 980
 981         @remarks
 982             Default property sort function sorts properties by their labels
 983             (case-insensitively).
 984
 985         @see GetSortFunction, wxPropertyGridInterface::Sort,
 986              wxPropertyGridInterface::SortChildren
 987     */
 988     void SetSortFunction( wxPGSortCallback sortFunction );
 989
 990     /**
 991         Sets x coordinate of the splitter.
 992
 993         @remarks Splitter position cannot exceed grid size, and therefore setting
 994                 it during form creation may fail as initial grid size is often
 995                 smaller than desired splitter position, especially when sizers
 996                 are being used.
 997     */
 998     void SetSplitterPosition( int newxpos, int col = 0 );
 999
1000     /**
1001         Moves splitter as left as possible, while still allowing all
1002         labels to be shown in full.
1003
1004         @param privateChildrenToo
1005             If @false, will still allow private children to be cropped.
1006     */
1007     void SetSplitterLeft( bool privateChildrenToo = false );
1008
1009     /**
1010         Sets appearance of value cells representing an unspecified property
1011         value. Default appearance is blank.
1012
1013         @remarks If you set the unspecified value to have any
1014                  textual representation, then that will override
1015                  "InlineHelp" attribute.
1016
1017         @see wxPGProperty::SetValueToUnspecified(),
1018              wxPGProperty::IsValueUnspecified()
1019     */
1020     void SetUnspecifiedValueAppearance( const wxPGCell& cell );
1021
1022     /**
1023         Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
1024         height. Value of 2 should be default on most platforms.
1025     */
1026     void SetVerticalSpacing( int vspacing );
1027
1028
1029     /**
1030         @name Property development functions
1031
1032         These member functions are usually only called when creating custom
1033         user properties.
1034     */
1035     //@{
1036
1037     /**
1038         Call when editor widget's contents is modified. For example, this is
1039         called when changes text in wxTextCtrl (used in wxStringProperty and
1040         wxIntProperty).
1041
1042         @remarks This function should only be called by custom properties.
1043
1044         @see wxPGProperty::OnEvent()
1045     */
1046     void EditorsValueWasModified();
1047
1048     /**
1049         Reverse of EditorsValueWasModified().
1050
1051         @remarks This function should only be called by custom properties.
1052     */
1053     void EditorsValueWasNotModified();
1054
1055     /**
1056         Returns most up-to-date value of selected property. This will return
1057         value different from GetSelectedProperty()->GetValue() only when text
1058         editor is activate and string edited by user represents valid,
1059         uncommitted property value.
1060     */
1061     wxVariant GetUncommittedPropertyValue();
1062
1063     /**
1064         Returns true if editor's value was marked modified.
1065     */
1066     bool IsEditorsValueModified() const;
1067
1068     /**
1069         Shows an brief error message that is related to a property.
1070     */
1071     void ShowPropertyError( wxPGPropArg id, const wxString& msg );
1072
1073     /**
1074         You can use this member function, for instance, to detect in
1075         wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was
1076         already called in wxPGEditor::OnEvent(). It really only detects
1077         if was value was changed using wxPGProperty::SetValueInEvent(), which
1078         is usually used when a 'picker' dialog is displayed. If value was
1079         written by "normal means" in wxPGProperty::StringToValue() or
1080         IntToValue(), then this function will return false (on the other hand,
1081         wxPGProperty::OnEvent() is not even called in those cases).
1082     */
1083     bool WasValueChangedInEvent() const;
1084
1085     //@}
1086 };
1087
1088
1089 /**
1090     @class wxPropertyGridEvent
1091
1092     A property grid event holds information about events associated with
1093     wxPropertyGrid objects.
1094
1095     @library{wxpropgrid}
1096     @category{propgrid}
1097 */
1098 class wxPropertyGridEvent : public wxCommandEvent
1099 {
1100 public:
1101
1102     /** Constructor. */
1103     wxPropertyGridEvent(wxEventType commandType=0, int id=0);
1104
1105     /** Copy constructor. */
1106     wxPropertyGridEvent(const wxPropertyGridEvent& event);
1107
1108     /** Destructor. */
1109     ~wxPropertyGridEvent();
1110
1111     /**
1112         Returns true if you can veto the action that the event is signaling.
1113     */
1114     bool CanVeto() const;
1115
1116     /**
1117         Returns the column index associated with this event.
1118         For the column dragging events, it is the column to the left
1119         of the splitter being dragged
1120     */
1121     unsigned int GetColumn() const;
1122
1123     /**
1124         Returns highest level non-category, non-root parent of property for
1125         which event occurred. Useful when you have nested properties with
1126         children.
1127
1128         @remarks If immediate parent is root or category, this will return the
1129                 property itself.
1130     */
1131     wxPGProperty* GetMainParent() const;
1132
1133     /**
1134         Returns property associated with this event.
1135
1136         @remarks You should assume that this property can always be NULL.
1137                  For instance, wxEVT_PG_SELECTED is emitted not only when
1138                  a new property is selected, but also when selection is
1139                  cleared by user activity.
1140     */
1141     wxPGProperty* GetProperty() const;
1142
1143     /**
1144         Returns current validation failure flags.
1145     */
1146     wxPGVFBFlags GetValidationFailureBehavior() const;
1147
1148     /**
1149         Returns name of the associated property.
1150
1151         @remarks Property name is stored in event, so it remains
1152                  accessible even after the associated property or
1153                  the property grid has been deleted.
1154     */
1155     wxString GetPropertyName() const;
1156
1157     /**
1158         Returns value of the associated property. Works for all event
1159         types, but for wxEVT_PG_CHANGING this member function returns
1160         the value that is pending, so you can call Veto() if the
1161         value is not satisfactory.
1162
1163         @remarks Property value is stored in event, so it remains
1164                  accessible even after the associated property or
1165                  the property grid has been deleted.
1166     */
1167     wxVariant GetPropertyValue() const
1168
1169     /**
1170         @see GetPropertyValue()
1171     */
1172     wxVariant GetValue() const;
1173
1174     /**
1175         Set if event can be vetoed.
1176     */
1177     void SetCanVeto( bool canVeto );
1178
1179     /** Changes the property associated with this event. */
1180     void SetProperty( wxPGProperty* p );
1181
1182     /**
1183         Set override validation failure behavior. Only effective if Veto() was
1184         also called, and only allowed if event type is wxEVT_PG_CHANGING.
1185     */
1186     void SetValidationFailureBehavior( wxPGVFBFlags flags );
1187
1188     /**
1189         Sets custom failure message for this time only. Only applies if
1190         wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
1191     */
1192     void SetValidationFailureMessage( const wxString& message );
1193
1194     /**
1195         Call this from your event handler to veto action that the event is
1196         signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto()
1197         returns true.
1198
1199         @remarks Currently only wxEVT_PG_CHANGING supports vetoing.
1200     */
1201     void Veto( bool veto = true );
1202
1203     /**
1204         Returns @true if event was vetoed.
1205     */
1206     bool WasVetoed() const;
1207 };