interface/wx/propgrid/propgrid.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        propgrid.h
   3 // Purpose:     interface of wxPropertyGrid
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @section propgrid_window_styles wxPropertyGrid Window Styles
  12
  13     SetWindowStyleFlag method can be used to modify some of these at run-time.
  14     @{
  15 */
  16 enum wxPG_WINDOW_STYLES
  17 {
  18
  19 /**
  20     This will cause Sort() automatically after an item is added.
  21     When inserting a lot of items in this mode, it may make sense to
  22     use Freeze() before operations and Thaw() afterwards to increase
  23     performance.
  24 */
  25 wxPG_AUTO_SORT                      = 0x00000010,
  26
  27 /**
  28     Categories are not initially shown (even if added).
  29     IMPORTANT NOTE: If you do not plan to use categories, then this
  30     style will waste resources.
  31     This flag can also be changed using wxPropertyGrid::EnableCategories method.
  32 */
  33 wxPG_HIDE_CATEGORIES                = 0x00000020,
  34
  35 /**
  36     This style combines non-categoric mode and automatic sorting.
  37 */
  38 wxPG_ALPHABETIC_MODE                = (wxPG_HIDE_CATEGORIES|wxPG_AUTO_SORT),
  39
  40 /**
  41     Modified values are shown in bold font. Changing this requires Refresh()
  42     to show changes.
  43 */
  44 wxPG_BOLD_MODIFIED                  = 0x00000040,
  45
  46 /**
  47     When wxPropertyGrid is resized, splitter moves to the center. This
  48     behavior stops once the user manually moves the splitter.
  49 */
  50 wxPG_SPLITTER_AUTO_CENTER           = 0x00000080,
  51
  52 /**
  53     Display tool tips for cell text that cannot be shown completely. If
  54     wxUSE_TOOLTIPS is 0, then this doesn't have any effect.
  55 */
  56 wxPG_TOOLTIPS                       = 0x00000100,
  57
  58 /**
  59     Disables margin and hides all expand/collapse buttons that would appear
  60     outside the margin (for sub-properties). Toggling this style automatically
  61     expands all collapsed items.
  62 */
  63 wxPG_HIDE_MARGIN                    = 0x00000200,
  64
  65 /**
  66     This style prevents user from moving the splitter.
  67 */
  68 wxPG_STATIC_SPLITTER                = 0x00000400,
  69
  70 /**
  71     Combination of other styles that make it impossible for user to modify
  72     the layout.
  73 */
  74 wxPG_STATIC_LAYOUT                  = (wxPG_HIDE_MARGIN|wxPG_STATIC_SPLITTER),
  75
  76 /**
  77     Disables wxTextCtrl based editors for properties which
  78     can be edited in another way. Equals calling
  79     wxPropertyGrid::LimitPropertyEditing() for all added properties.
  80 */
  81 wxPG_LIMITED_EDITING                = 0x00000800,
  82
  83 /**
  84     wxPropertyGridManager only: Show tool bar for mode and page selection.
  85 */
  86 wxPG_TOOLBAR                        = 0x00001000,
  87
  88 /**
  89     wxPropertyGridManager only: Show adjustable text box showing description
  90     or help text, if available, for currently selected property.
  91 */
  92 wxPG_DESCRIPTION                    = 0x00002000,
  93
  94 /** wxPropertyGridManager only: don't show an internal border around the
  95     property grid. Recommended if you use a header.
  96 */
  97 wxPG_NO_INTERNAL_BORDER             = 0x00004000
  98
  99 };
 100
 101 enum wxPG_EX_WINDOW_STYLES
 102 {
 103
 104 /**
 105     NOTE: wxPG_EX_xxx are extra window styles and must be set using SetExtraStyle()
 106     member function.
 107
 108     Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if
 109     wxPG_HIDE_CATEGORIES is not defined, the non-categorized data storage is not
 110     activated, and switching the mode first time becomes somewhat slower.
 111     wxPG_EX_INIT_NOCAT activates the non-categorized data storage right away.
 112
 113     NOTE: If you do plan not switching to non-categoric mode, or if
 114     you don't plan to use categories at all, then using this style will result
 115     in waste of resources.
 116 */
 117 wxPG_EX_INIT_NOCAT                  = 0x00001000,
 118
 119 /**
 120     Extended window style that sets wxPropertyGridManager tool bar to not
 121     use flat style.
 122 */
 123 wxPG_EX_NO_FLAT_TOOLBAR             = 0x00002000,
 124
 125 /**
 126     Shows alphabetic/categoric mode buttons from tool bar.
 127 */
 128 wxPG_EX_MODE_BUTTONS                = 0x00008000,
 129
 130 /**
 131     Show property help strings as tool tips instead as text on the status bar.
 132     You can set the help strings using SetPropertyHelpString member function.
 133 */
 134 wxPG_EX_HELP_AS_TOOLTIPS            = 0x00010000,
 135
 136 /**
 137     Allows relying on native double-buffering.
 138 */
 139 wxPG_EX_NATIVE_DOUBLE_BUFFERING         = 0x00080000,
 140
 141 /**
 142     Set this style to let user have ability to set values of properties to
 143     unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for
 144     all properties.
 145 */
 146 wxPG_EX_AUTO_UNSPECIFIED_VALUES         = 0x00200000,
 147
 148 /**
 149     If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION and
 150     wxPG_STRING_PASSWORD) are not stored into property's attribute storage (thus
 151     they are not readable).
 152
 153     Note that this option is global, and applies to all wxPG property containers.
 154 */
 155 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES    = 0x00400000,
 156
 157 /**
 158     Hides page selection buttons from tool bar.
 159 */
 160 wxPG_EX_HIDE_PAGE_BUTTONS               = 0x01000000,
 161
 162 /** Allows multiple properties to be selected by user (by pressing SHIFT
 163     when clicking on a property, or by dragging with left mouse button
 164     down).
 165
 166     You can get array of selected properties with
 167     wxPropertyGridInterface::GetSelectedProperties(). In multiple selection
 168     mode wxPropertyGridInterface::GetSelection() returns
 169     property which has editor active (usually the first one
 170     selected). Other useful member functions are ClearSelection(),
 171     AddToSelection() and RemoveFromSelection().
 172 */
 173 wxPG_EX_MULTIPLE_SELECTION              = 0x02000000,
 174
 175 /**
 176     This enables top-level window tracking which allows wxPropertyGrid to
 177     notify the application of last-minute property value changes by user.
 178
 179     This style is not enabled by default because it may cause crashes when
 180     wxPropertyGrid is used in with wxAUI or similar system.
 181
 182     @remarks If you are not in fact using any system that may change
 183              wxPropertyGrid's top-level parent window on its own, then you
 184              are recommended to enable this style.
 185 */
 186 wxPG_EX_ENABLE_TLP_TRACKING             = 0x04000000,
 187
 188 /** Don't show divider above toolbar, on Windows.
 189 */
 190 wxPG_EX_NO_TOOLBAR_DIVIDER              = 0x04000000,
 191
 192 /** Show a separator below the toolbar.
 193 */
 194 wxPG_EX_TOOLBAR_SEPARATOR               = 0x08000000
 195
 196 };
 197
 198 /** Combines various styles.
 199 */
 200 #define wxPG_DEFAULT_STYLE          (0)
 201
 202 /** Combines various styles.
 203 */
 204 #define wxPGMAN_DEFAULT_STYLE       (0)
 205
 206 /** @}
 207 */
 208
 209 // -----------------------------------------------------------------------
 210
 211 /**
 212     @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
 213     @{
 214 */
 215
 216 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
 217 {
 218
 219 /**
 220     Prevents user from leaving property unless value is valid. If this
 221     behavior flag is not used, then value change is instead cancelled.
 222 */
 223 wxPG_VFB_STAY_IN_PROPERTY           = 0x01,
 224
 225 /**
 226     Calls wxBell() on validation failure.
 227 */
 228 wxPG_VFB_BEEP                       = 0x02,
 229
 230 /**
 231     Cell with invalid value will be marked (with red colour).
 232 */
 233 wxPG_VFB_MARK_CELL                  = 0x04,
 234
 235 /**
 236     Display 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 wxScrolledWindow, public wxPropertyGridInterface
 443 {
 444 public:
 445     /**
 446         Two step constructor.
 447         Call Create() when this constructor is called to build up the wxPropertyGrid
 448     */
 449     wxPropertyGrid();
 450
 451     /**
 452         Constructor.
 453         The styles to be used are styles valid for the wxWindow and wxScrolledWindow.
 454
 455         @see @ref propgrid_window_styles.
 456     */
 457     wxPropertyGrid( wxWindow *parent, wxWindowID id = wxID_ANY,
 458                     const wxPoint& pos = wxDefaultPosition,
 459                     const wxSize& size = wxDefaultSize,
 460                     long style = wxPG_DEFAULT_STYLE,
 461                     const wxChar* name = wxPropertyGridNameStr );
 462
 463     /** Destructor */
 464     virtual ~wxPropertyGrid();
 465
 466     /**
 467         Adds given key combination to trigger given action.
 468
 469         Here is a sample code to make Enter key press move focus to
 470         the next property.
 471
 472         @code
 473             propGrid->AddActionTrigger(wxPG_ACTION_NEXT_PROPERTY,
 474                                        WXK_RETURN);
 475             propGrid->DedicateKey(WXK_RETURN);
 476         @endcode
 477
 478         @param action
 479             Which action to trigger. See @ref propgrid_keyboard_actions.
 480         @param keycode
 481             Which keycode triggers the action.
 482         @param modifiers
 483             Which key event modifiers, in addition to keycode, are needed to
 484             trigger the action.
 485     */
 486     void AddActionTrigger( int action, int keycode, int modifiers = 0 );
 487
 488     /**
 489         Adds given property into selection. If wxPG_EX_MULTIPLE_SELECTION
 490         extra style is not used, then this has same effect as
 491         calling SelectProperty().
 492
 493         @remarks Multiple selection is not supported for categories. This
 494                  means that if you have properties selected, you cannot
 495                  add category to selection, and also if you have category
 496                  selected, you cannot add other properties to selection.
 497                  This member function will fail silently in these cases,
 498                  even returning true.
 499     */
 500     bool AddToSelection( wxPGPropArg id );
 501
 502     /**
 503         This static function enables or disables automatic use of
 504         wxGetTranslation() for following strings: wxEnumProperty list labels,
 505         wxFlagsProperty child property labels.
 506
 507         Default is false.
 508     */
 509     static void AutoGetTranslation( bool enable );
 510
 511     /**
 512         Creates label editor wxTextCtrl for given column, for property
 513         that is currently selected. When multiple selection is
 514         enabled, this applies to whatever property GetSelection()
 515         returns.
 516
 517         @param colIndex
 518             Which column's label to edit. Note that you should not
 519             use value 1, which is reserved for property value
 520             column.
 521
 522         @see EndLabelEdit(), MakeColumnEditable()
 523     */
 524     void BeginLabelEdit( unsigned int colIndex = 0 );
 525
 526     /**
 527         Changes value of a property, as if from an editor. Use this instead of
 528         SetPropertyValue() if you need the value to run through validation
 529         process, and also send the property change event.
 530
 531         @return Returns true if value was successfully changed.
 532     */
 533     bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
 534
 535     /**
 536         Centers the splitter.
 537
 538         @param enableAutoResizing
 539             If @true, automatic column resizing is enabled (only applicapple
 540             if window style wxPG_SPLITTER_AUTO_CENTER is used).
 541     */
 542     void CenterSplitter( bool enableAutoResizing = false );
 543
 544     /**
 545         Deletes all properties.
 546     */
 547     virtual void Clear();
 548
 549     /**
 550         Clears action triggers for given action.
 551
 552         @param action
 553             Which action to trigger. @ref propgrid_keyboard_actions.
 554     */
 555     void ClearActionTriggers( int action );
 556
 557     /**
 558         Forces updating the value of property from the editor control.
 559         Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
 560         ProcessEvent, meaning your event handlers will be called immediately.
 561
 562         @return Returns @true if anything was changed.
 563     */
 564     virtual bool CommitChangesFromEditor( wxUint32 flags = 0 );
 565
 566     /**
 567         Two step creation. Whenever the control is created without any
 568         parameters, use Create to actually create it. Don't access the control's
 569         public methods before this is called
 570
 571         @see @ref propgrid_window_styles.
 572     */
 573     bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
 574                 const wxPoint& pos = wxDefaultPosition,
 575                 const wxSize& size = wxDefaultSize,
 576                 long style = wxPG_DEFAULT_STYLE,
 577                 const wxChar* name = wxPropertyGridNameStr );
 578
 579     /**
 580         Dedicates a specific keycode to wxPropertyGrid. This means that such
 581         key presses will not be redirected to editor controls.
 582
 583         Using this function allows, for example, navigation between
 584         properties using arrow keys even when the focus is in the editor
 585         control.
 586     */
 587     void DedicateKey( int keycode );
 588
 589     /**
 590         Enables or disables (shows/hides) categories according to parameter
 591         enable.
 592
 593         @remarks This functions deselects selected property, if any. Validation
 594                 failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie.
 595                 selection is cleared even if editor had invalid value.
 596     */
 597     bool EnableCategories( bool enable );
 598
 599     /**
 600         Destroys label editor wxTextCtrl, if any.
 601
 602         @param commit
 603             Use @true (default) to store edited label text in
 604             property cell data.
 605
 606         @see BeginLabelEdit(), MakeColumnEditable()
 607     */
 608     void EndLabelEdit( bool commit = true );
 609
 610     /**
 611         Scrolls and/or expands items to ensure that the given item is visible.
 612
 613         @return Returns @true if something was actually done.
 614     */
 615     bool EnsureVisible( wxPGPropArg id );
 616
 617     /**
 618         Reduces column sizes to minimum possible, while still retaining
 619         fully visible grid contents (labels, images).
 620
 621         @return Minimum size for the grid to still display everything.
 622
 623         @remarks Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
 624
 625                 This function only works properly if grid size prior to call was
 626                 already fairly large.
 627
 628                 Note that you can also get calculated column widths by calling
 629                 GetState->GetColumnWidth() immediately after this function
 630                 returns.
 631     */
 632     wxSize FitColumns();
 633
 634     /**
 635         Returns currently active label editor, NULL if none.
 636     */
 637     wxTextCtrl* GetLabelEditor() const;
 638
 639     /**
 640         Returns wxWindow that the properties are painted on, and which should be
 641         used as the parent for editor controls.
 642     */
 643     wxWindow* GetPanel();
 644
 645     /**
 646         Returns current category caption background colour.
 647     */
 648     wxColour GetCaptionBackgroundColour() const;
 649
 650     /**
 651         Returns current category caption font.
 652     */
 653     wxFont& GetCaptionFont();
 654
 655     /**
 656         Returns current category caption text colour.
 657     */
 658     wxColour GetCaptionForegroundColour() const;
 659
 660     /**
 661         Returns current cell background colour.
 662     */
 663     wxColour GetCellBackgroundColour() const;
 664
 665     /**
 666         Returns current cell text colour when disabled.
 667     */
 668     wxColour GetCellDisabledTextColour() const;
 669
 670     /**
 671         Returns current cell text colour.
 672     */
 673     wxColour GetCellTextColour() const;
 674
 675     /**
 676         Returns number of columns currently on grid.
 677     */
 678     unsigned int GetColumnCount() const;
 679
 680     /**
 681         Returns colour of empty space below properties.
 682     */
 683     wxColour GetEmptySpaceColour() const;
 684
 685     /**
 686         Returns height of highest characters of used font.
 687     */
 688     int GetFontHeight() const;
 689
 690     /**
 691         Returns pointer to itself. Dummy function that enables same kind
 692         of code to use wxPropertyGrid and wxPropertyGridManager.
 693     */
 694     wxPropertyGrid* GetGrid();
 695
 696     /**
 697         Returns rectangle of custom paint image.
 698
 699         @param property
 700             Return image rectangle for this property.
 701
 702         @param item
 703             Which choice of property to use (each choice may have
 704             different image).
 705     */
 706     wxRect GetImageRect( wxPGProperty* property, int item ) const;
 707
 708     /**
 709         Returns size of the custom paint image in front of property.
 710
 711         @param property
 712             Return image rectangle for this property.
 713             If this argument is NULL, then preferred size is returned.
 714
 715         @param item
 716             Which choice of property to use (each choice may have
 717             different image).
 718     */
 719     wxSize GetImageSize( wxPGProperty* property = NULL, int item = -1 ) const;
 720
 721     /**
 722         Returns last item which could be iterated using given flags.
 723
 724         @param flags
 725             See @ref propgrid_iterator_flags.
 726     */
 727     wxPGProperty* GetLastItem( int flags = wxPG_ITERATE_DEFAULT );
 728
 729     /**
 730         Returns colour of lines between cells.
 731     */
 732     wxColour GetLineColour() const;
 733
 734     /**
 735         Returns background colour of margin.
 736     */
 737     wxColour GetMarginColour() const;
 738
 739     /**
 740         Returns "root property". It does not have name, etc. and it is not
 741         visible. It is only useful for accessing its children.
 742     */
 743     wxPGProperty* GetRoot() const;
 744
 745     /**
 746         Returns height of a single grid row (in pixels).
 747     */
 748     int GetRowHeight() const;
 749
 750     /**
 751         Returns currently selected property.
 752     */
 753     wxPGProperty* GetSelectedProperty() const;
 754
 755     /**
 756         Returns currently selected property.
 757     */
 758     wxPGProperty* GetSelection() const;
 759
 760     /**
 761         Returns current selection background colour.
 762     */
 763     wxColour GetSelectionBackgroundColour() const;
 764
 765     /**
 766         Returns current selection text colour.
 767     */
 768     wxColour GetSelectionForegroundColour() const;
 769
 770     /**
 771         Returns the property sort function (default is @NULL).
 772
 773         @see SetSortFunction
 774     */
 775     wxPGSortCallback GetSortFunction() const;
 776
 777     /**
 778         Returns current splitter x position.
 779     */
 780     int GetSplitterPosition( unsigned int splitterIndex = 0 ) const;
 781
 782     /**
 783         Returns wxTextCtrl active in currently selected property, if any. Takes
 784         wxOwnerDrawnComboBox into account.
 785     */
 786     wxTextCtrl* GetEditorTextCtrl() const;
 787
 788     /**
 789         Returns current appearance of unspecified value cells.
 790
 791         @see SetUnspecifiedValueAppearance()
 792     */
 793     const wxPGCell& GetUnspecifiedValueAppearance() const;
 794
 795     /**
 796         Returns (visual) text representation of the unspecified
 797         property value.
 798
 799         @param argFlags For internal use only.
 800     */
 801     wxString GetUnspecifiedValueText( int argFlags = 0 ) const;
 802
 803     /**
 804         Returns current vertical spacing.
 805     */
 806     int GetVerticalSpacing() const;
 807
 808     /**
 809         Returns information about arbitrary position in the grid.
 810
 811         @param pt
 812             Coordinates in the virtual grid space. You may need to use
 813             wxScrolledWindow::CalcScrolledPosition() for translating
 814             wxPropertyGrid client coordinates into something this member
 815             function can use.
 816     */
 817     wxPropertyGridHitTestResult HitTest( const wxPoint& pt ) const;
 818
 819     /**
 820         Returns true if any property has been modified by the user.
 821     */
 822     bool IsAnyModified() const;
 823
 824     /**
 825         Returns @true if a property editor control has focus.
 826     */
 827     bool IsEditorFocused() const;
 828
 829     /**
 830         Returns true if updating is frozen (ie. Freeze() called but not
 831         yet Thaw() ).
 832     */
 833     bool IsFrozen() const;
 834
 835     /**
 836         Makes given column editable by user.
 837
 838         @param column
 839             The index of the column to make editable.
 840         @param editable
 841             Using @false here will disable column from being editable.
 842
 843         @see BeginLabelEdit(), EndLabelEdit()
 844     */
 845     void MakeColumnEditable( unsigned int column, bool editable = true );
 846
 847     /**
 848         It is recommended that you call this function any time your code causes
 849         wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle()
 850         handler should be able to detect most changes, but it is not perfect.
 851
 852         @param newTLP
 853             New top-level parent that is about to be set. Old top-level parent
 854             window should still exist as the current one.
 855
 856         @remarks This function is automatically called from wxPropertyGrid::
 857                  Reparent() and wxPropertyGridManager::Reparent(). You only
 858                  need to use it if you reparent wxPropertyGrid indirectly.
 859     */
 860     void OnTLPChanging( wxWindow* newTLP );
 861
 862     /**
 863         Refreshes any active editor control.
 864     */
 865     void RefreshEditor();
 866
 867     /**
 868         Redraws given property.
 869     */
 870     virtual void RefreshProperty( wxPGProperty* p );
 871
 872     /**
 873         Registers a new editor class.
 874
 875         @return Returns pointer  to the editor class instance that should be used.
 876     */
 877     static wxPGEditor* RegisterEditorClass( wxPGEditor* editor,
 878                                             const wxString& name,
 879                                             bool noDefCheck = false );
 880
 881     /**
 882         Resets all colours to the original system values.
 883     */
 884     void ResetColours();
 885
 886     /**
 887         Resets column sizes and splitter positions, based on proportions.
 888
 889         @param enableAutoResizing
 890             If @true, automatic column resizing is enabled (only applicapple
 891             if window style wxPG_SPLITTER_AUTO_CENTER is used).
 892
 893         @see wxPropertyGridInterface::SetColumnProportion()
 894     */
 895     void ResetColumnSizes( bool enableAutoResizing = false );
 896
 897     /**
 898         Removes given property from selection. If property is not selected,
 899         an assertion failure will occur.
 900     */
 901     bool RemoveFromSelection( wxPGPropArg id );
 902
 903     /**
 904         Selects a property. Editor widget is automatically created, but
 905         not focused unless focus is true.
 906
 907         @param id
 908             Property to select (name or pointer).
 909
 910         @param focus
 911             If @true, move keyboard focus to the created editor right away.
 912
 913         @return returns @true if selection finished successfully. Usually only
 914         fails if current value in editor is not valid.
 915
 916         @remarks In wxPropertyGrid 1.4, this member function used to generate
 917                  wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer
 918                  does that.
 919
 920         @remarks This clears any previous selection.
 921
 922         @see wxPropertyGridInterface::ClearSelection()
 923     */
 924     bool SelectProperty( wxPGPropArg id, bool focus = false );
 925
 926     /**
 927         Changes keyboard shortcut to push the editor button.
 928
 929         @remarks You can set default with keycode 0. Good value for the platform
 930                 is guessed, but don't expect it to be very accurate.
 931     */
 932     void SetButtonShortcut( int keycode, bool ctrlDown = false, bool altDown = false );
 933
 934     /**
 935         Sets category caption background colour.
 936     */
 937     void SetCaptionBackgroundColour(const wxColour& col);
 938
 939     /**
 940         Sets category caption text colour.
 941     */
 942     void SetCaptionTextColour(const wxColour& col);
 943
 944     /**
 945         Sets default cell background colour - applies to property cells.
 946         Note that appearance of editor widgets may not be affected.
 947     */
 948     void SetCellBackgroundColour(const wxColour& col);
 949
 950     /**
 951         Sets cell text colour for disabled properties.
 952     */
 953     void SetCellDisabledTextColour(const wxColour& col);
 954
 955     /**
 956         Sets default cell text colour - applies to property name and value text.
 957         Note that appearance of editor widgets may not be affected.
 958     */
 959     void SetCellTextColour(const wxColour& col);
 960
 961     /**
 962         Set number of columns (2 or more).
 963     */
 964     void SetColumnCount( int colCount );
 965
 966     /**
 967         Sets the 'current' category - Append will add non-category properties
 968         under it.
 969     */
 970     void SetCurrentCategory( wxPGPropArg id );
 971
 972     /**
 973         Sets colour of empty space below properties.
 974     */
 975     void SetEmptySpaceColour(const wxColour& col);
 976
 977     /**
 978         Sets colour of lines between cells.
 979     */
 980     void SetLineColour(const wxColour& col);
 981
 982     /**
 983         Sets background colour of margin.
 984     */
 985     void SetMarginColour(const wxColour& col);
 986
 987     /**
 988         Set entire new selection from given list of properties.
 989     */
 990     void SetSelection( const wxArrayPGProperty& newSelection );
 991
 992     /**
 993         Sets selection background colour - applies to selected property name
 994         background.
 995     */
 996     void SetSelectionBackgroundColour(const wxColour& col);
 997
 998     /**
 999         Sets selection foreground colour - applies to selected property name text.
1000     */
1001     void SetSelectionTextColour(const wxColour& col);
1002
1003
1004     /**
1005         Sets the property sorting function.
1006
1007         @param sortFunction
1008             The sorting function to be used. It should return a value greater
1009             than 0 if position of p1 is after p2. So, for instance, when
1010             comparing property names, you can use following implementation:
1011
1012             @code
1013                 int MyPropertySortFunction(wxPropertyGrid* propGrid,
1014                                            wxPGProperty* p1,
1015                                            wxPGProperty* p2)
1016                 {
1017                     return p1->GetBaseName().compare( p2->GetBaseName() );
1018                 }
1019             @endcode
1020
1021         @remarks
1022             Default property sort function sorts properties by their labels
1023             (case-insensitively).
1024
1025         @see GetSortFunction, wxPropertyGridInterface::Sort,
1026              wxPropertyGridInterface::SortChildren
1027     */
1028     void SetSortFunction( wxPGSortCallback sortFunction );
1029
1030     /**
1031         Sets x coordinate of the splitter.
1032
1033         @remarks Splitter position cannot exceed grid size, and therefore setting
1034                 it during form creation may fail as initial grid size is often
1035                 smaller than desired splitter position, especially when sizers
1036                 are being used.
1037     */
1038     void SetSplitterPosition( int newxpos, int col = 0 );
1039
1040     /**
1041         Moves splitter as left as possible, while still allowing all
1042         labels to be shown in full.
1043
1044         @param privateChildrenToo
1045             If @false, will still allow private children to be cropped.
1046     */
1047     void SetSplitterLeft( bool privateChildrenToo = false );
1048
1049     /**
1050         Sets appearance of value cells representing an unspecified property
1051         value. Default appearance is blank.
1052
1053         @remarks If you set the unspecified value to have any
1054                  textual representation, then that will override
1055                  "InlineHelp" attribute.
1056
1057         @see wxPGProperty::SetValueToUnspecified(),
1058              wxPGProperty::IsValueUnspecified()
1059     */
1060     void SetUnspecifiedValueAppearance( const wxPGCell& cell );
1061
1062     /**
1063         Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
1064         height. Value of 2 should be default on most platforms.
1065     */
1066     void SetVerticalSpacing( int vspacing );
1067
1068     /**
1069         @name wxPropertyGrid customization
1070
1071         Reimplement these member functions in derived class for better
1072         control over wxPropertyGrid behavior.
1073     */
1074     //@{
1075
1076     /**
1077         Override in derived class to display error messages in custom manner
1078         (these message usually only result from validation failure).
1079
1080         @remarks If you implement this, then you also need to implement
1081                  DoHidePropertyError() - possibly to do nothing, if error
1082                  does not need hiding (e.g. it was logged or shown in a
1083                  message box).
1084
1085         @see DoHidePropertyError()
1086     */
1087     virtual void DoShowPropertyError( wxPGProperty* property,
1088                                       const wxString& msg );
1089
1090     /**
1091         Override in derived class to hide an error displayed by
1092         DoShowPropertyError().
1093
1094         @see DoShowPropertyError()
1095     */
1096     virtual void DoHidePropertyError( wxPGProperty* property );
1097
1098     /**
1099         Return wxStatusBar that is used by this wxPropertyGrid. You can
1100         reimplement this member function in derived class to override
1101         the default behavior of using the top-level wxFrame's status
1102         bar, if any.
1103     */
1104     virtual wxStatusBar* GetStatusBar();
1105
1106     //@}
1107
1108     /**
1109         @name Property development functions
1110
1111         These member functions are usually only called when creating custom
1112         user properties.
1113     */
1114     //@{
1115
1116     /**
1117         Call when editor widget's contents is modified. For example, this is
1118         called when changes text in wxTextCtrl (used in wxStringProperty and
1119         wxIntProperty).
1120
1121         @remarks This function should only be called by custom properties.
1122
1123         @see wxPGProperty::OnEvent()
1124     */
1125     void EditorsValueWasModified();
1126
1127     /**
1128         Reverse of EditorsValueWasModified().
1129
1130         @remarks This function should only be called by custom properties.
1131     */
1132     void EditorsValueWasNotModified();
1133
1134     /**
1135         Returns most up-to-date value of selected property. This will return
1136         value different from GetSelectedProperty()->GetValue() only when text
1137         editor is activate and string edited by user represents valid,
1138         uncommitted property value.
1139     */
1140     wxVariant GetUncommittedPropertyValue();
1141
1142     /**
1143         Returns true if editor's value was marked modified.
1144     */
1145     bool IsEditorsValueModified() const;
1146
1147     /**
1148         Shows an brief error message that is related to a property.
1149     */
1150     void ShowPropertyError( wxPGPropArg id, const wxString& msg );
1151
1152     /**
1153         You can use this member function, for instance, to detect in
1154         wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was
1155         already called in wxPGEditor::OnEvent(). It really only detects
1156         if was value was changed using wxPGProperty::SetValueInEvent(), which
1157         is usually used when a 'picker' dialog is displayed. If value was
1158         written by "normal means" in wxPGProperty::StringToValue() or
1159         IntToValue(), then this function will return false (on the other hand,
1160         wxPGProperty::OnEvent() is not even called in those cases).
1161     */
1162     bool WasValueChangedInEvent() const;
1163
1164     //@}
1165 };
1166
1167
1168 /**
1169     @class wxPropertyGridEvent
1170
1171     A property grid event holds information about events associated with
1172     wxPropertyGrid objects.
1173
1174     @library{wxpropgrid}
1175     @category{propgrid}
1176 */
1177 class wxPropertyGridEvent : public wxCommandEvent
1178 {
1179 public:
1180
1181     /** Constructor. */
1182     wxPropertyGridEvent(wxEventType commandType=0, int id=0);
1183
1184     /** Copy constructor. */
1185     wxPropertyGridEvent(const wxPropertyGridEvent& event);
1186
1187     /** Destructor. */
1188     ~wxPropertyGridEvent();
1189
1190     /**
1191         Returns true if you can veto the action that the event is signaling.
1192     */
1193     bool CanVeto() const;
1194
1195     /**
1196         Returns the column index associated with this event.
1197         For the column dragging events, it is the column to the left
1198         of the splitter being dragged
1199     */
1200     unsigned int GetColumn() const;
1201
1202     /**
1203         Returns highest level non-category, non-root parent of property for
1204         which event occurred. Useful when you have nested properties with
1205         children.
1206
1207         @remarks If immediate parent is root or category, this will return the
1208                 property itself.
1209     */
1210     wxPGProperty* GetMainParent() const;
1211
1212     /**
1213         Returns property associated with this event.
1214
1215         @remarks You should assume that this property can always be NULL.
1216                  For instance, wxEVT_PG_SELECTED is emitted not only when
1217                  a new property is selected, but also when selection is
1218                  cleared by user activity.
1219     */
1220     wxPGProperty* GetProperty() const;
1221
1222     /**
1223         Returns current validation failure flags.
1224     */
1225     wxPGVFBFlags GetValidationFailureBehavior() const;
1226
1227     /**
1228         Returns name of the associated property.
1229
1230         @remarks Property name is stored in event, so it remains
1231                  accessible even after the associated property or
1232                  the property grid has been deleted.
1233     */
1234     wxString GetPropertyName() const;
1235
1236     /**
1237         Returns value of the associated property. Works for all event
1238         types, but for wxEVT_PG_CHANGING this member function returns
1239         the value that is pending, so you can call Veto() if the
1240         value is not satisfactory.
1241
1242         @remarks Property value is stored in event, so it remains
1243                  accessible even after the associated property or
1244                  the property grid has been deleted.
1245     */
1246     wxVariant GetPropertyValue() const
1247
1248     /**
1249         @see GetPropertyValue()
1250     */
1251     wxVariant GetValue() const;
1252
1253     /**
1254         Set if event can be vetoed.
1255     */
1256     void SetCanVeto( bool canVeto );
1257
1258     /** Changes the property associated with this event. */
1259     void SetProperty( wxPGProperty* p );
1260
1261     /**
1262         Set override validation failure behavior. Only effective if Veto() was
1263         also called, and only allowed if event type is wxEVT_PG_CHANGING.
1264     */
1265     void SetValidationFailureBehavior( wxPGVFBFlags flags );
1266
1267     /**
1268         Sets custom failure message for this time only. Only applies if
1269         wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
1270     */
1271     void SetValidationFailureMessage( const wxString& message );
1272
1273     /**
1274         Call this from your event handler to veto action that the event is
1275         signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto()
1276         returns true.
1277
1278         @remarks Currently only wxEVT_PG_CHANGING supports vetoing.
1279     */
1280     void Veto( bool veto = true );
1281
1282     /**
1283         Returns @true if event was vetoed.
1284     */
1285     bool WasVetoed() const;
1286 };