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