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 licence
   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 a text message explaining the situation.
 237
 238     To customize the way the message is displayed, you need to
 239     reimplement wxPropertyGrid::DoShowPropertyError() in a
 240     derived class. Default behavior is to display the text on
 241     the top-level frame's status bar, if present, and otherwise
 242     using wxMessageBox.
 243 */
 244 wxPG_VFB_SHOW_MESSAGE               = 0x08,
 245
 246 /**
 247     Similar to wxPG_VFB_SHOW_MESSAGE, except always displays the
 248     message using wxMessageBox.
 249 */
 250 wxPG_VFB_SHOW_MESSAGEBOX            = 0x10,
 251
 252 /**
 253     Similar to wxPG_VFB_SHOW_MESSAGE, except always displays the
 254     message on the status bar (when present - you can reimplement
 255     wxPropertyGrid::GetStatusBar() in a derived class to specify
 256     this yourself).
 257 */
 258 wxPG_VFB_SHOW_MESSAGE_ON_STATUSBAR  = 0x20,
 259
 260 /**
 261     Defaults.
 262 */
 263 wxPG_VFB_DEFAULT                    = wxPG_VFB_MARK_CELL |
 264                                       wxPG_VFB_SHOW_MESSAGEBOX,
 265 };
 266
 267 /** @}
 268 */
 269
 270 typedef wxByte wxPGVFBFlags;
 271
 272 /**
 273     wxPGValidationInfo
 274
 275     Used to convey validation information to and from functions that
 276     actually perform validation. Mostly used in custom property classes.
 277 */
 278 class wxPGValidationInfo
 279 {
 280 public:
 281     /**
 282         @return Returns failure behavior which is a combination of
 283             @ref propgrid_vfbflags.
 284     */
 285     wxPGVFBFlags GetFailureBehavior();
 286
 287     /**
 288         Returns current failure message.
 289     */
 290     const wxString& GetFailureMessage() const;
 291
 292     /**
 293         Returns reference to pending value.
 294     */
 295     wxVariant& GetValue();
 296
 297     /** Set validation failure behavior
 298
 299         @param failureBehavior
 300             Mixture of @ref propgrid_vfbflags.
 301     */
 302     void SetFailureBehavior(wxPGVFBFlags failureBehavior);
 303
 304     /**
 305         Set current failure message.
 306     */
 307     void SetFailureMessage(const wxString& message);
 308 };
 309
 310 // -----------------------------------------------------------------------
 311
 312 /**
 313     @section propgrid_keyboard_actions wxPropertyGrid Action Identifiers
 314
 315     These are used with wxPropertyGrid::AddActionTrigger() and
 316     wxPropertyGrid::ClearActionTriggers().
 317     @{
 318 */
 319
 320 enum wxPG_KEYBOARD_ACTIONS
 321 {
 322     wxPG_ACTION_INVALID = 0,
 323
 324     /** Select the next property. */
 325     wxPG_ACTION_NEXT_PROPERTY,
 326
 327     /** Select the previous property. */
 328     wxPG_ACTION_PREV_PROPERTY,
 329
 330     /** Expand the selected property, if it has child items. */
 331     wxPG_ACTION_EXPAND_PROPERTY,
 332
 333     /** Collapse the selected property, if it has child items. */
 334     wxPG_ACTION_COLLAPSE_PROPERTY,
 335
 336     /** Cancel and undo any editing done in the currently active property
 337         editor.
 338     */
 339     wxPG_ACTION_CANCEL_EDIT,
 340
 341     /** Move focus to the editor control of the currently selected
 342         property.
 343     */
 344     wxPG_ACTION_EDIT,
 345
 346     /** Causes editor's button (if any) to be pressed. */
 347     wxPG_ACTION_PRESS_BUTTON,
 348
 349     wxPG_ACTION_MAX
 350 };
 351
 352 /** @}
 353 */
 354
 355 /** This callback function is used for sorting properties.
 356
 357     Call wxPropertyGrid::SetSortFunction() to set it.
 358
 359     Sort function should return a value greater than 0 if position of p1 is
 360     after p2. So, for instance, when comparing property names, you can use
 361     following implementation:
 362
 363         @code
 364             int MyPropertySortFunction(wxPropertyGrid* propGrid,
 365                                        wxPGProperty* p1,
 366                                        wxPGProperty* p2)
 367             {
 368                 return p1->GetBaseName().compare( p2->GetBaseName() );
 369             }
 370         @endcode
 371 */
 372 typedef int (*wxPGSortCallback)(wxPropertyGrid* propGrid,
 373                                 wxPGProperty* p1,
 374                                 wxPGProperty* p2);
 375
 376 // -----------------------------------------------------------------------
 377
 378 /**
 379     @class wxPropertyGrid
 380
 381     wxPropertyGrid is a specialized grid for editing properties - in other
 382     words name = value pairs. List of ready-to-use property classes include
 383     strings, numbers, flag sets, fonts, colours and many others. It is possible,
 384     for example, to categorize properties, set up a complete tree-hierarchy,
 385     add more than two columns, and set arbitrary per-property attributes.
 386
 387     Please note that most member functions are inherited and as such not
 388     documented on this page. This means you will probably also want to read
 389     wxPropertyGridInterface class reference.
 390
 391     See also @ref overview_propgrid.
 392
 393     @section propgrid_window_styles_ Window Styles
 394
 395     See @ref propgrid_window_styles.
 396
 397     @section propgrid_event_handling Event Handling
 398
 399     To process input from a property grid control, use these event handler macros
 400     to direct input to member functions that take a wxPropertyGridEvent argument.
 401
 402     @beginEventEmissionTable{wxPropertyGridEvent}
 403     @event{EVT_PG_SELECTED (id, func)}
 404         Respond to @c wxEVT_PG_SELECTED event, generated when a property selection
 405         has been changed, either by user action or by indirect program
 406         function. For instance, collapsing a parent property programmatically
 407         causes any selected child property to become unselected, and may
 408         therefore cause this event to be generated.
 409     @event{EVT_PG_CHANGED(id, func)}
 410         Respond to @c wxEVT_PG_CHANGED event, generated when property value
 411         has been changed by the user.
 412     @event{EVT_PG_CHANGING(id, func)}
 413         Respond to @c wxEVT_PG_CHANGING event, generated when property value
 414         is about to be changed by user. Use wxPropertyGridEvent::GetValue()
 415         to take a peek at the pending value, and wxPropertyGridEvent::Veto()
 416         to prevent change from taking place, if necessary.
 417     @event{EVT_PG_HIGHLIGHTED(id, func)}
 418         Respond to @c wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
 419         moves over a property. Event's property is NULL if hovered area does
 420         not belong to any property.
 421     @event{EVT_PG_RIGHT_CLICK(id, func)}
 422         Respond to @c wxEVT_PG_RIGHT_CLICK event, which occurs when property is
 423         clicked on with right mouse button.
 424     @event{EVT_PG_DOUBLE_CLICK(id, func)}
 425         Respond to @c wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
 426         double-clicked on with left mouse button.
 427     @event{EVT_PG_ITEM_COLLAPSED(id, func)}
 428         Respond to @c wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
 429         a property or category.
 430     @event{EVT_PG_ITEM_EXPANDED(id, func)}
 431         Respond to @c wxEVT_PG_ITEM_EXPANDED event, generated when user expands
 432         a property or category.
 433     @event{EVT_PG_LABEL_EDIT_BEGIN(id, func)}
 434         Respond to @c wxEVT_PG_LABEL_EDIT_BEGIN event, generated when user is
 435         about to begin editing a property label. You can veto this event to
 436         prevent the action.
 437     @event{EVT_PG_LABEL_EDIT_ENDING(id, func)}
 438         Respond to @c wxEVT_PG_LABEL_EDIT_ENDING event, generated when user is
 439         about to end editing of a property label. You can veto this event to
 440         prevent the action.
 441     @event{EVT_PG_COL_BEGIN_DRAG(id, func)}
 442         Respond to @c wxEVT_PG_COL_BEGIN_DRAG event, generated when user
 443         starts resizing a column - can be vetoed.
 444     @event{EVT_PG_COL_DRAGGING,(id, func)}
 445         Respond to @c wxEVT_PG_COL_DRAGGING, event, generated when a
 446         column resize by user is in progress. This event is also generated
 447         when user double-clicks the splitter in order to recenter
 448         it.
 449     @event{EVT_PG_COL_END_DRAG(id, func)}
 450         Respond to @c wxEVT_PG_COL_END_DRAG event, generated after column
 451         resize by user has finished.
 452     @endEventTable
 453
 454     @remarks
 455     Use Freeze() and Thaw() respectively to disable and enable drawing.
 456     This will also delay sorting etc. miscellaneous calculations to the last
 457     possible moment.
 458
 459     @library{wxpropgrid}
 460     @category{propgrid}
 461     @appearance{propertygrid.png}
 462 */
 463 class wxPropertyGrid : public wxControl,
 464                        public wxScrollHelper,
 465                        public wxPropertyGridInterface
 466 {
 467 public:
 468     /**
 469         Two step constructor.
 470         Call Create() when this constructor is called to build up the wxPropertyGrid
 471     */
 472     wxPropertyGrid();
 473
 474     /**
 475         Constructor.
 476         The styles to be used are styles valid for the wxWindow.
 477
 478         @see @ref propgrid_window_styles.
 479     */
 480     wxPropertyGrid( wxWindow *parent, wxWindowID id = wxID_ANY,
 481                     const wxPoint& pos = wxDefaultPosition,
 482                     const wxSize& size = wxDefaultSize,
 483                     long style = wxPG_DEFAULT_STYLE,
 484                     const wxChar* name = wxPropertyGridNameStr );
 485
 486     /** Destructor */
 487     virtual ~wxPropertyGrid();
 488
 489     /**
 490         Adds given key combination to trigger given action.
 491
 492         Here is a sample code to make Enter key press move focus to
 493         the next property.
 494
 495         @code
 496             propGrid->AddActionTrigger(wxPG_ACTION_NEXT_PROPERTY,
 497                                        WXK_RETURN);
 498             propGrid->DedicateKey(WXK_RETURN);
 499         @endcode
 500
 501         @param action
 502             Which action to trigger. See @ref propgrid_keyboard_actions.
 503         @param keycode
 504             Which keycode triggers the action.
 505         @param modifiers
 506             Which key event modifiers, in addition to keycode, are needed to
 507             trigger the action.
 508     */
 509     void AddActionTrigger( int action, int keycode, int modifiers = 0 );
 510
 511     /**
 512         Adds given property into selection. If wxPG_EX_MULTIPLE_SELECTION
 513         extra style is not used, then this has same effect as
 514         calling SelectProperty().
 515
 516         @remarks Multiple selection is not supported for categories. This
 517                  means that if you have properties selected, you cannot
 518                  add category to selection, and also if you have category
 519                  selected, you cannot add other properties to selection.
 520                  This member function will fail silently in these cases,
 521                  even returning true.
 522     */
 523     bool AddToSelection( wxPGPropArg id );
 524
 525     /**
 526         This static function enables or disables automatic use of
 527         wxGetTranslation() for following strings: wxEnumProperty list labels,
 528         wxFlagsProperty child property labels.
 529
 530         Default is false.
 531     */
 532     static void AutoGetTranslation( bool enable );
 533
 534     /**
 535         Creates label editor wxTextCtrl for given column, for property
 536         that is currently selected. When multiple selection is
 537         enabled, this applies to whatever property GetSelection()
 538         returns.
 539
 540         @param colIndex
 541             Which column's label to edit. Note that you should not
 542             use value 1, which is reserved for property value
 543             column.
 544
 545         @see EndLabelEdit(), MakeColumnEditable()
 546     */
 547     void BeginLabelEdit( unsigned int colIndex = 0 );
 548
 549     /**
 550         Changes value of a property, as if from an editor. Use this instead of
 551         SetPropertyValue() if you need the value to run through validation
 552         process, and also send the property change event.
 553
 554         @return Returns true if value was successfully changed.
 555     */
 556     bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
 557
 558     /**
 559         Centers the splitter.
 560
 561         @param enableAutoResizing
 562             If @true, automatic column resizing is enabled (only applicapple
 563             if window style wxPG_SPLITTER_AUTO_CENTER is used).
 564     */
 565     void CenterSplitter( bool enableAutoResizing = false );
 566
 567     /**
 568         Deletes all properties.
 569     */
 570     virtual void Clear();
 571
 572     /**
 573         Clears action triggers for given action.
 574
 575         @param action
 576             Which action to trigger. @ref propgrid_keyboard_actions.
 577     */
 578     void ClearActionTriggers( int action );
 579
 580     /**
 581         Forces updating the value of property from the editor control.
 582         Note that @c wxEVT_PG_CHANGING and @c wxEVT_PG_CHANGED are dispatched using
 583         ProcessEvent, meaning your event handlers will be called immediately.
 584
 585         @return Returns @true if anything was changed.
 586     */
 587     virtual bool CommitChangesFromEditor( wxUint32 flags = 0 );
 588
 589     /**
 590         Two step creation. Whenever the control is created without any
 591         parameters, use Create to actually create it. Don't access the control's
 592         public methods before this is called
 593
 594         @see @ref propgrid_window_styles.
 595     */
 596     bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
 597                 const wxPoint& pos = wxDefaultPosition,
 598                 const wxSize& size = wxDefaultSize,
 599                 long style = wxPG_DEFAULT_STYLE,
 600                 const wxChar* name = wxPropertyGridNameStr );
 601
 602     /**
 603         Dedicates a specific keycode to wxPropertyGrid. This means that such
 604         key presses will not be redirected to editor controls.
 605
 606         Using this function allows, for example, navigation between
 607         properties using arrow keys even when the focus is in the editor
 608         control.
 609     */
 610     void DedicateKey( int keycode );
 611
 612     /**
 613         Enables or disables (shows/hides) categories according to parameter
 614         enable.
 615
 616         @remarks This functions deselects selected property, if any. Validation
 617                 failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie.
 618                 selection is cleared even if editor had invalid value.
 619     */
 620     bool EnableCategories( bool enable );
 621
 622     /**
 623         Destroys label editor wxTextCtrl, if any.
 624
 625         @param commit
 626             Use @true (default) to store edited label text in
 627             property cell data.
 628
 629         @see BeginLabelEdit(), MakeColumnEditable()
 630     */
 631     void EndLabelEdit( bool commit = true );
 632
 633     /**
 634         Scrolls and/or expands items to ensure that the given item is visible.
 635
 636         @return Returns @true if something was actually done.
 637     */
 638     bool EnsureVisible( wxPGPropArg id );
 639
 640     /**
 641         Reduces column sizes to minimum possible, while still retaining
 642         fully visible grid contents (labels, images).
 643
 644         @return Minimum size for the grid to still display everything.
 645
 646         @remarks Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
 647
 648                 This function only works properly if grid size prior to call was
 649                 already fairly large.
 650
 651                 Note that you can also get calculated column widths by calling
 652                 GetState->GetColumnWidth() immediately after this function
 653                 returns.
 654     */
 655     wxSize FitColumns();
 656
 657     /**
 658         Returns currently active label editor, NULL if none.
 659     */
 660     wxTextCtrl* GetLabelEditor() const;
 661
 662     /**
 663         Returns wxWindow that the properties are painted on, and which should be
 664         used as the parent for editor controls.
 665     */
 666     wxWindow* GetPanel();
 667
 668     /**
 669         Returns current category caption background colour.
 670     */
 671     wxColour GetCaptionBackgroundColour() const;
 672
 673     /**
 674         Returns current category caption font.
 675     */
 676     wxFont& GetCaptionFont();
 677
 678     /**
 679         Returns current category caption text colour.
 680     */
 681     wxColour GetCaptionForegroundColour() const;
 682
 683     /**
 684         Returns current cell background colour.
 685     */
 686     wxColour GetCellBackgroundColour() const;
 687
 688     /**
 689         Returns current cell text colour when disabled.
 690     */
 691     wxColour GetCellDisabledTextColour() const;
 692
 693     /**
 694         Returns current cell text colour.
 695     */
 696     wxColour GetCellTextColour() const;
 697
 698     /**
 699         Returns number of columns currently on grid.
 700     */
 701     unsigned int GetColumnCount() const;
 702
 703     /**
 704         Returns colour of empty space below properties.
 705     */
 706     wxColour GetEmptySpaceColour() const;
 707
 708     /**
 709         Returns height of highest characters of used font.
 710     */
 711     int GetFontHeight() const;
 712
 713     /**
 714         Returns pointer to itself. Dummy function that enables same kind
 715         of code to use wxPropertyGrid and wxPropertyGridManager.
 716     */
 717     wxPropertyGrid* GetGrid();
 718
 719     /**
 720         Returns rectangle of custom paint image.
 721
 722         @param property
 723             Return image rectangle for this property.
 724
 725         @param item
 726             Which choice of property to use (each choice may have
 727             different image).
 728     */
 729     wxRect GetImageRect( wxPGProperty* property, int item ) const;
 730
 731     /**
 732         Returns size of the custom paint image in front of property.
 733
 734         @param property
 735             Return image rectangle for this property.
 736             If this argument is NULL, then preferred size is returned.
 737
 738         @param item
 739             Which choice of property to use (each choice may have
 740             different image).
 741     */
 742     wxSize GetImageSize( wxPGProperty* property = NULL, int item = -1 ) const;
 743
 744     /**
 745         Returns last item which could be iterated using given flags.
 746
 747         @param flags
 748             See @ref propgrid_iterator_flags.
 749     */
 750     wxPGProperty* GetLastItem( int flags = wxPG_ITERATE_DEFAULT );
 751
 752     /**
 753         Returns colour of lines between cells.
 754     */
 755     wxColour GetLineColour() const;
 756
 757     /**
 758         Returns background colour of margin.
 759     */
 760     wxColour GetMarginColour() const;
 761
 762     /**
 763         Returns "root property". It does not have name, etc. and it is not
 764         visible. It is only useful for accessing its children.
 765     */
 766     wxPGProperty* GetRoot() const;
 767
 768     /**
 769         Returns height of a single grid row (in pixels).
 770     */
 771     int GetRowHeight() const;
 772
 773     /**
 774         Returns currently selected property.
 775     */
 776     wxPGProperty* GetSelectedProperty() const;
 777
 778     /**
 779         Returns currently selected property.
 780     */
 781     wxPGProperty* GetSelection() const;
 782
 783     /**
 784         Returns current selection background colour.
 785     */
 786     wxColour GetSelectionBackgroundColour() const;
 787
 788     /**
 789         Returns current selection text colour.
 790     */
 791     wxColour GetSelectionForegroundColour() const;
 792
 793     /**
 794         Returns the property sort function (default is @NULL).
 795
 796         @see SetSortFunction
 797     */
 798     wxPGSortCallback GetSortFunction() const;
 799
 800     /**
 801         Returns current splitter x position.
 802     */
 803     int GetSplitterPosition( unsigned int splitterIndex = 0 ) const;
 804
 805     /**
 806         Returns wxTextCtrl active in currently selected property, if any. Takes
 807         wxOwnerDrawnComboBox into account.
 808     */
 809     wxTextCtrl* GetEditorTextCtrl() const;
 810
 811     /**
 812         Returns current appearance of unspecified value cells.
 813
 814         @see SetUnspecifiedValueAppearance()
 815     */
 816     const wxPGCell& GetUnspecifiedValueAppearance() const;
 817
 818     /**
 819         Returns (visual) text representation of the unspecified
 820         property value.
 821
 822         @param argFlags For internal use only.
 823     */
 824     wxString GetUnspecifiedValueText( int argFlags = 0 ) const;
 825
 826     /**
 827         Returns current vertical spacing.
 828     */
 829     int GetVerticalSpacing() const;
 830
 831     /**
 832         Returns information about arbitrary position in the grid.
 833
 834         @param pt
 835             Coordinates in the virtual grid space. You may need to use
 836             wxScrolled<T>::CalcScrolledPosition() for translating
 837             wxPropertyGrid client coordinates into something this member
 838             function can use.
 839     */
 840     wxPropertyGridHitTestResult HitTest( const wxPoint& pt ) const;
 841
 842     /**
 843         Returns true if any property has been modified by the user.
 844     */
 845     bool IsAnyModified() const;
 846
 847     /**
 848         Returns @true if a property editor control has focus.
 849     */
 850     bool IsEditorFocused() const;
 851
 852     /**
 853         Returns true if updating is frozen (ie. Freeze() called but not
 854         yet Thaw() ).
 855     */
 856     bool IsFrozen() const;
 857
 858     /**
 859         Makes given column editable by user.
 860
 861         @param column
 862             The index of the column to make editable.
 863         @param editable
 864             Using @false here will disable column from being editable.
 865
 866         @see BeginLabelEdit(), EndLabelEdit()
 867     */
 868     void MakeColumnEditable( unsigned int column, bool editable = true );
 869
 870     /**
 871         It is recommended that you call this function any time your code causes
 872         wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle()
 873         handler should be able to detect most changes, but it is not perfect.
 874
 875         @param newTLP
 876             New top-level parent that is about to be set. Old top-level parent
 877             window should still exist as the current one.
 878
 879         @remarks This function is automatically called from wxPropertyGrid::
 880                  Reparent() and wxPropertyGridManager::Reparent(). You only
 881                  need to use it if you reparent wxPropertyGrid indirectly.
 882     */
 883     void OnTLPChanging( wxWindow* newTLP );
 884
 885     /**
 886         Refreshes any active editor control.
 887     */
 888     void RefreshEditor();
 889
 890     /**
 891         Redraws given property.
 892     */
 893     virtual void RefreshProperty( wxPGProperty* p );
 894
 895     /**
 896         Registers a new editor class.
 897
 898         @return Returns pointer  to the editor class instance that should be used.
 899     */
 900     static wxPGEditor* RegisterEditorClass( wxPGEditor* editor,
 901                                             const wxString& name,
 902                                             bool noDefCheck = false );
 903
 904     /**
 905         Resets all colours to the original system values.
 906     */
 907     void ResetColours();
 908
 909     /**
 910         Resets column sizes and splitter positions, based on proportions.
 911
 912         @param enableAutoResizing
 913             If @true, automatic column resizing is enabled (only applicapple
 914             if window style wxPG_SPLITTER_AUTO_CENTER is used).
 915
 916         @see wxPropertyGridInterface::SetColumnProportion()
 917     */
 918     void ResetColumnSizes( bool enableAutoResizing = false );
 919
 920     /**
 921         Removes given property from selection. If property is not selected,
 922         an assertion failure will occur.
 923     */
 924     bool RemoveFromSelection( wxPGPropArg id );
 925
 926     /**
 927         Selects a property. Editor widget is automatically created, but
 928         not focused unless focus is true.
 929
 930         @param id
 931             Property to select (name or pointer).
 932
 933         @param focus
 934             If @true, move keyboard focus to the created editor right away.
 935
 936         @return returns @true if selection finished successfully. Usually only
 937         fails if current value in editor is not valid.
 938
 939         @remarks In wxPropertyGrid 1.4, this member function used to generate
 940                  @c wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer
 941                  does that.
 942
 943         @remarks This clears any previous selection.
 944
 945         @see wxPropertyGridInterface::ClearSelection()
 946     */
 947     bool SelectProperty( wxPGPropArg id, bool focus = false );
 948
 949     /**
 950         Changes keyboard shortcut to push the editor button.
 951
 952         @remarks You can set default with keycode 0. Good value for the platform
 953                 is guessed, but don't expect it to be very accurate.
 954     */
 955     void SetButtonShortcut( int keycode, bool ctrlDown = false, bool altDown = false );
 956
 957     /**
 958         Sets category caption background colour.
 959     */
 960     void SetCaptionBackgroundColour(const wxColour& col);
 961
 962     /**
 963         Sets category caption text colour.
 964     */
 965     void SetCaptionTextColour(const wxColour& col);
 966
 967     /**
 968         Sets default cell background colour - applies to property cells.
 969         Note that appearance of editor widgets may not be affected.
 970     */
 971     void SetCellBackgroundColour(const wxColour& col);
 972
 973     /**
 974         Sets cell text colour for disabled properties.
 975     */
 976     void SetCellDisabledTextColour(const wxColour& col);
 977
 978     /**
 979         Sets default cell text colour - applies to property name and value text.
 980         Note that appearance of editor widgets may not be affected.
 981     */
 982     void SetCellTextColour(const wxColour& col);
 983
 984     /**
 985         Set number of columns (2 or more).
 986     */
 987     void SetColumnCount( int colCount );
 988
 989     /**
 990         Sets the 'current' category - Append will add non-category properties
 991         under it.
 992     */
 993     void SetCurrentCategory( wxPGPropArg id );
 994
 995     /**
 996         Sets colour of empty space below properties.
 997     */
 998     void SetEmptySpaceColour(const wxColour& col);
 999
1000     /**
1001         Sets colour of lines between cells.
1002     */
1003     void SetLineColour(const wxColour& col);
1004
1005     /**
1006         Sets background colour of margin.
1007     */
1008     void SetMarginColour(const wxColour& col);
1009
1010     /**
1011         Set entire new selection from given list of properties.
1012     */
1013     void SetSelection( const wxArrayPGProperty& newSelection );
1014
1015     /**
1016         Sets selection background colour - applies to selected property name
1017         background.
1018     */
1019     void SetSelectionBackgroundColour(const wxColour& col);
1020
1021     /**
1022         Sets selection foreground colour - applies to selected property name text.
1023     */
1024     void SetSelectionTextColour(const wxColour& col);
1025
1026
1027     /**
1028         Sets the property sorting function.
1029
1030         @param sortFunction
1031             The sorting function to be used. It should return a value greater
1032             than 0 if position of p1 is after p2. So, for instance, when
1033             comparing property names, you can use following implementation:
1034
1035             @code
1036                 int MyPropertySortFunction(wxPropertyGrid* propGrid,
1037                                            wxPGProperty* p1,
1038                                            wxPGProperty* p2)
1039                 {
1040                     return p1->GetBaseName().compare( p2->GetBaseName() );
1041                 }
1042             @endcode
1043
1044         @remarks
1045             Default property sort function sorts properties by their labels
1046             (case-insensitively).
1047
1048         @see GetSortFunction, wxPropertyGridInterface::Sort,
1049              wxPropertyGridInterface::SortChildren
1050     */
1051     void SetSortFunction( wxPGSortCallback sortFunction );
1052
1053     /**
1054         Sets x coordinate of the splitter.
1055
1056         @remarks Splitter position cannot exceed grid size, and therefore setting
1057                 it during form creation may fail as initial grid size is often
1058                 smaller than desired splitter position, especially when sizers
1059                 are being used.
1060     */
1061     void SetSplitterPosition( int newxpos, int col = 0 );
1062
1063     /**
1064         Moves splitter as left as possible, while still allowing all
1065         labels to be shown in full.
1066
1067         @param privateChildrenToo
1068             If @false, will still allow private children to be cropped.
1069     */
1070     void SetSplitterLeft( bool privateChildrenToo = false );
1071
1072     /**
1073         Sets appearance of value cells representing an unspecified property
1074         value. Default appearance is blank.
1075
1076         @remarks If you set the unspecified value to have any
1077                  textual representation, then that will override
1078                  "InlineHelp" attribute.
1079
1080         @see wxPGProperty::SetValueToUnspecified(),
1081              wxPGProperty::IsValueUnspecified()
1082     */
1083     void SetUnspecifiedValueAppearance( const wxPGCell& cell );
1084
1085     /**
1086         Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
1087         height. Value of 2 should be default on most platforms.
1088     */
1089     void SetVerticalSpacing( int vspacing );
1090
1091     /**
1092         @name wxPropertyGrid customization
1093
1094         Reimplement these member functions in derived class for better
1095         control over wxPropertyGrid behavior.
1096     */
1097     //@{
1098
1099     /**
1100         Override in derived class to display error messages in custom manner
1101         (these message usually only result from validation failure).
1102
1103         @remarks If you implement this, then you also need to implement
1104                  DoHidePropertyError() - possibly to do nothing, if error
1105                  does not need hiding (e.g. it was logged or shown in a
1106                  message box).
1107
1108         @see DoHidePropertyError()
1109     */
1110     virtual void DoShowPropertyError( wxPGProperty* property,
1111                                       const wxString& msg );
1112
1113     /**
1114         Override in derived class to hide an error displayed by
1115         DoShowPropertyError().
1116
1117         @see DoShowPropertyError()
1118     */
1119     virtual void DoHidePropertyError( wxPGProperty* property );
1120
1121     /**
1122         Return wxStatusBar that is used by this wxPropertyGrid. You can
1123         reimplement this member function in derived class to override
1124         the default behavior of using the top-level wxFrame's status
1125         bar, if any.
1126     */
1127     virtual wxStatusBar* GetStatusBar();
1128
1129     //@}
1130
1131     /**
1132         @name Property development functions
1133
1134         These member functions are usually only called when creating custom
1135         user properties.
1136     */
1137     //@{
1138
1139     /**
1140         Call when editor widget's contents is modified. For example, this is
1141         called when changes text in wxTextCtrl (used in wxStringProperty and
1142         wxIntProperty).
1143
1144         @remarks This function should only be called by custom properties.
1145
1146         @see wxPGProperty::OnEvent()
1147     */
1148     void EditorsValueWasModified();
1149
1150     /**
1151         Reverse of EditorsValueWasModified().
1152
1153         @remarks This function should only be called by custom properties.
1154     */
1155     void EditorsValueWasNotModified();
1156
1157     /**
1158         Returns most up-to-date value of selected property. This will return
1159         value different from GetSelectedProperty()->GetValue() only when text
1160         editor is activate and string edited by user represents valid,
1161         uncommitted property value.
1162     */
1163     wxVariant GetUncommittedPropertyValue();
1164
1165     /**
1166         Returns true if editor's value was marked modified.
1167     */
1168     bool IsEditorsValueModified() const;
1169
1170     /**
1171         Shows an brief error message that is related to a property.
1172     */
1173     void ShowPropertyError( wxPGPropArg id, const wxString& msg );
1174
1175     /**
1176         You can use this member function, for instance, to detect in
1177         wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was
1178         already called in wxPGEditor::OnEvent(). It really only detects
1179         if was value was changed using wxPGProperty::SetValueInEvent(), which
1180         is usually used when a 'picker' dialog is displayed. If value was
1181         written by "normal means" in wxPGProperty::StringToValue() or
1182         IntToValue(), then this function will return false (on the other hand,
1183         wxPGProperty::OnEvent() is not even called in those cases).
1184     */
1185     bool WasValueChangedInEvent() const;
1186
1187     //@}
1188 };
1189
1190
1191 /**
1192     @class wxPropertyGridEvent
1193
1194     A property grid event holds information about events associated with
1195     wxPropertyGrid objects.
1196
1197     @library{wxpropgrid}
1198     @category{propgrid}
1199 */
1200 class wxPropertyGridEvent : public wxCommandEvent
1201 {
1202 public:
1203
1204     /** Constructor. */
1205     wxPropertyGridEvent(wxEventType commandType=0, int id=0);
1206
1207     /** Copy constructor. */
1208     wxPropertyGridEvent(const wxPropertyGridEvent& event);
1209
1210     /** Destructor. */
1211     ~wxPropertyGridEvent();
1212
1213     /**
1214         Returns true if you can veto the action that the event is signaling.
1215     */
1216     bool CanVeto() const;
1217
1218     /**
1219         Returns the column index associated with this event.
1220         For the column dragging events, it is the column to the left
1221         of the splitter being dragged
1222     */
1223     unsigned int GetColumn() const;
1224
1225     /**
1226         Returns highest level non-category, non-root parent of property for
1227         which event occurred. Useful when you have nested properties with
1228         children.
1229
1230         @remarks If immediate parent is root or category, this will return the
1231                 property itself.
1232     */
1233     wxPGProperty* GetMainParent() const;
1234
1235     /**
1236         Returns property associated with this event.
1237
1238         @remarks You should assume that this property can always be NULL.
1239                  For instance, @c wxEVT_PG_SELECTED is emitted not only when
1240                  a new property is selected, but also when selection is
1241                  cleared by user activity.
1242     */
1243     wxPGProperty* GetProperty() const;
1244
1245     /**
1246         Returns current validation failure flags.
1247     */
1248     wxPGVFBFlags GetValidationFailureBehavior() const;
1249
1250     /**
1251         Returns name of the associated property.
1252
1253         @remarks Property name is stored in event, so it remains
1254                  accessible even after the associated property or
1255                  the property grid has been deleted.
1256     */
1257     wxString GetPropertyName() const;
1258
1259     /**
1260         Returns value of the associated property. Works for all event
1261         types, but for @c wxEVT_PG_CHANGING this member function returns
1262         the value that is pending, so you can call Veto() if the
1263         value is not satisfactory.
1264
1265         @remarks Property value is stored in event, so it remains
1266                  accessible even after the associated property or
1267                  the property grid has been deleted.
1268     */
1269     wxVariant GetPropertyValue() const
1270
1271     /**
1272         @see GetPropertyValue()
1273     */
1274     wxVariant GetValue() const;
1275
1276     /**
1277         Set if event can be vetoed.
1278     */
1279     void SetCanVeto( bool canVeto );
1280
1281     /** Changes the property associated with this event. */
1282     void SetProperty( wxPGProperty* p );
1283
1284     /**
1285         Set override validation failure behavior. Only effective if Veto() was
1286         also called, and only allowed if event type is @c wxEVT_PG_CHANGING.
1287     */
1288     void SetValidationFailureBehavior( wxPGVFBFlags flags );
1289
1290     /**
1291         Sets custom failure message for this time only. Only applies if
1292         wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
1293     */
1294     void SetValidationFailureMessage( const wxString& message );
1295
1296     /**
1297         Call this from your event handler to veto action that the event is
1298         signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto()
1299         returns true.
1300
1301         @remarks Currently only @c wxEVT_PG_CHANGING supports vetoing.
1302     */
1303     void Veto( bool veto = true );
1304
1305     /**
1306         Returns @true if event was vetoed.
1307     */
1308     bool WasVetoed() const;
1309 };