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