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 };
  95
  96 enum wxPG_EX_WINDOW_STYLES
  97 {
  98
  99 /**
 100     NOTE: wxPG_EX_xxx are extra window styles and must be set using SetExtraStyle()
 101     member function.
 102
 103     Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if
 104     wxPG_HIDE_CATEGORIES is not defined, the non-categorized data storage is not
 105     activated, and switching the mode first time becomes somewhat slower.
 106     wxPG_EX_INIT_NOCAT activates the non-categorized data storage right away.
 107
 108     NOTE: If you do plan not switching to non-categoric mode, or if
 109     you don't plan to use categories at all, then using this style will result
 110     in waste of resources.
 111 */
 112 wxPG_EX_INIT_NOCAT                  = 0x00001000,
 113
 114 /**
 115     Extended window style that sets wxPropertyGridManager tool bar to not
 116     use flat style.
 117 */
 118 wxPG_EX_NO_FLAT_TOOLBAR             = 0x00002000,
 119
 120 /**
 121     Shows alphabetic/categoric mode buttons from tool bar.
 122 */
 123 wxPG_EX_MODE_BUTTONS                = 0x00008000,
 124
 125 /**
 126     Show property help strings as tool tips instead as text on the status bar.
 127     You can set the help strings using SetPropertyHelpString member function.
 128 */
 129 wxPG_EX_HELP_AS_TOOLTIPS            = 0x00010000,
 130
 131 /**
 132     Allows relying on native double-buffering.
 133 */
 134 wxPG_EX_NATIVE_DOUBLE_BUFFERING         = 0x00080000,
 135
 136 /**
 137     Set this style to let user have ability to set values of properties to
 138     unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for
 139     all properties.
 140 */
 141 wxPG_EX_AUTO_UNSPECIFIED_VALUES         = 0x00200000,
 142
 143 /**
 144     If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION and
 145     wxPG_STRING_PASSWORD) are not stored into property's attribute storage (thus
 146     they are not readable).
 147
 148     Note that this option is global, and applies to all wxPG property containers.
 149 */
 150 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES    = 0x00400000,
 151
 152 /**
 153     Hides page selection buttons from tool bar.
 154 */
 155 wxPG_EX_HIDE_PAGE_BUTTONS               = 0x01000000,
 156
 157 /** Allows multiple properties to be selected by user (by pressing SHIFT
 158     when clicking on a property, or by dragging with left mouse button
 159     down).
 160
 161     You can get array of selected properties with
 162     wxPropertyGridInterface::GetSelectedProperties(). In multiple selection
 163     mode wxPropertyGridInterface::GetSelection() returns
 164     property which has editor active (usually the first one
 165     selected). Other useful member functions are ClearSelection(),
 166     AddToSelection() and RemoveFromSelection().
 167 */
 168 wxPG_EX_MULTIPLE_SELECTION              = 0x02000000
 169
 170 };
 171
 172 /** Combines various styles.
 173 */
 174 #define wxPG_DEFAULT_STYLE              (0)
 175
 176 /** Combines various styles.
 177 */
 178 #define wxPGMAN_DEFAULT_STYLE       (0)
 179
 180 /** @}
 181 */
 182
 183 // -----------------------------------------------------------------------
 184
 185 /**
 186     @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
 187     @{
 188 */
 189
 190 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
 191 {
 192
 193 /**
 194     Prevents user from leaving property unless value is valid. If this
 195     behavior flag is not used, then value change is instead cancelled.
 196 */
 197 wxPG_VFB_STAY_IN_PROPERTY           = 0x01,
 198
 199 /**
 200     Calls wxBell() on validation failure.
 201 */
 202 wxPG_VFB_BEEP                       = 0x02,
 203
 204 /**
 205     Cell with invalid value will be marked (with red colour).
 206 */
 207 wxPG_VFB_MARK_CELL                  = 0x04,
 208
 209 /**
 210     Display customizable text message explaining the situation.
 211 */
 212 wxPG_VFB_SHOW_MESSAGE               = 0x08,
 213
 214 /**
 215     Defaults.
 216 */
 217 wxPG_VFB_DEFAULT                    = wxPG_VFB_STAY_IN_PROPERTY|wxPG_VFB_BEEP,
 218 };
 219
 220 /** @}
 221 */
 222
 223 typedef wxByte wxPGVFBFlags;
 224
 225 /**
 226     wxPGValidationInfo
 227
 228     Used to convey validation information to and from functions that
 229     actually perform validation. Mostly used in custom property classes.
 230 */
 231 class wxPGValidationInfo
 232 {
 233 public:
 234     /**
 235         @return Returns failure behavior which is a combination of
 236             @ref propgrid_vfbflags.
 237     */
 238     wxPGVFBFlags GetFailureBehavior();
 239
 240     /**
 241         Returns current failure message.
 242     */
 243     const wxString& GetFailureMessage() const;
 244
 245     /**
 246         Returns reference to pending value.
 247     */
 248     const wxVariant& GetValue() const;
 249
 250     /** Set validation failure behavior
 251
 252         @param failureBehavior
 253             Mixture of @ref propgrid_vfbflags.
 254     */
 255     void SetFailureBehavior(wxPGVFBFlags failureBehavior);
 256
 257     /**
 258         Set current failure message.
 259     */
 260     void SetFailureMessage(const wxString& message);
 261 };
 262
 263 // -----------------------------------------------------------------------
 264
 265 /**
 266     @section propgrid_keyboard_actions wxPropertyGrid Action Identifiers
 267
 268     These are used with wxPropertyGrid::AddActionTrigger() and
 269     wxPropertyGrid::ClearActionTriggers().
 270     @{
 271 */
 272
 273 enum wxPG_KEYBOARD_ACTIONS
 274 {
 275     wxPG_ACTION_INVALID = 0,
 276     wxPG_ACTION_NEXT_PROPERTY,
 277     wxPG_ACTION_PREV_PROPERTY,
 278     wxPG_ACTION_EXPAND_PROPERTY,
 279     wxPG_ACTION_COLLAPSE_PROPERTY,
 280     wxPG_ACTION_CANCEL_EDIT,
 281     wxPG_ACTION_MAX
 282 };
 283
 284 /** @}
 285 */
 286
 287 /** This callback function is used for sorting properties.
 288
 289     Call wxPropertyGrid::SetSortFunction() to set it.
 290
 291     Sort function should return a value greater than 0 if position of p1 is
 292     after p2. So, for instance, when comparing property names, you can use
 293     following implementation:
 294
 295         @code
 296             int MyPropertySortFunction(wxPropertyGrid* propGrid,
 297                                        wxPGProperty* p1,
 298                                        wxPGProperty* p2)
 299             {
 300                 return p1->GetBaseName().compare( p2->GetBaseName() );
 301             }
 302         @endcode
 303 */
 304 typedef int (*wxPGSortCallback)(wxPropertyGrid* propGrid,
 305                                 wxPGProperty* p1,
 306                                 wxPGProperty* p2);
 307
 308 // -----------------------------------------------------------------------
 309
 310 /**
 311     @class wxPropertyGrid
 312
 313     wxPropertyGrid is a specialized grid for editing properties - in other
 314     words name = value pairs. List of ready-to-use property classes include
 315     strings, numbers, flag sets, fonts, colours and many others. It is possible,
 316     for example, to categorize properties, set up a complete tree-hierarchy,
 317     add more than two columns, and set arbitrary per-property attributes.
 318
 319     Please note that most member functions are inherited and as such not
 320     documented on this page. This means you will probably also want to read
 321     wxPropertyGridInterface class reference.
 322
 323     See also @ref overview_propgrid.
 324
 325     @section propgrid_window_styles_ Window Styles
 326
 327     See @ref propgrid_window_styles.
 328
 329     @section propgrid_event_handling Event Handling
 330
 331     To process input from a property grid control, use these event handler macros
 332     to direct input to member functions that take a wxPropertyGridEvent argument.
 333
 334     @beginEventEmissionTable{wxPropertyGridEvent}
 335     @event{EVT_PG_SELECTED (id, func)}
 336         Respond to wxEVT_PG_SELECTED event, generated when a property selection
 337         has been changed, either by user action or by indirect program
 338         function. For instance, collapsing a parent property programmatically
 339         causes any selected child property to become unselected, and may
 340         therefore cause this event to be generated.
 341     @event{EVT_PG_CHANGING(id, func)}
 342         Respond to wxEVT_PG_CHANGING event, generated when property value
 343         is about to be changed by user. Use wxPropertyGridEvent::GetValue()
 344         to take a peek at the pending value, and wxPropertyGridEvent::Veto()
 345         to prevent change from taking place, if necessary.
 346     @event{EVT_PG_HIGHLIGHTED(id, func)}
 347         Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
 348         moves over a property. Event's property is NULL if hovered area does
 349         not belong to any property.
 350     @event{EVT_PG_RIGHT_CLICK(id, func)}
 351         Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
 352         clicked on with right mouse button.
 353     @event{EVT_PG_DOUBLE_CLICK(id, func)}
 354         Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
 355         double-clicked on with left mouse button.
 356     @event{EVT_PG_ITEM_COLLAPSED(id, func)}
 357         Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
 358         a property or category.
 359     @event{EVT_PG_ITEM_EXPANDED(id, func)}
 360         Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
 361         a property or category.
 362     @event{EVT_PG_LABEL_EDIT_BEGIN(id, func)}
 363         Respond to wxEVT_PG_LABEL_EDIT_BEGIN event, generated when is about to
 364         begin editing a property label. You can veto this event to prevent the
 365         action.
 366     @event{EVT_PG_LABEL_EDIT_ENDING(id, func)}
 367         Respond to wxEVT_PG_LABEL_EDIT_ENDING event, generated when is about to
 368         end editing of a property label. You can veto this event to prevent the
 369         action.
 370     @endEventTable
 371
 372     @remarks
 373     Use Freeze() and Thaw() respectively to disable and enable drawing.
 374     This will also delay sorting etc. miscellaneous calculations to the last
 375     possible moment.
 376
 377     @library{wxpropgrid}
 378     @category{propgrid}
 379     @appearance{propertygrid.png}
 380 */
 381 class wxPropertyGrid : public wxScrolledWindow, public wxPropertyGridInterface
 382 {
 383 public:
 384     /**
 385         Two step constructor.
 386         Call Create() when this constructor is called to build up the wxPropertyGrid
 387     */
 388     wxPropertyGrid();
 389
 390     /**
 391         Constructor.
 392         The styles to be used are styles valid for the wxWindow and wxScrolledWindow.
 393
 394         @see @ref propgrid_window_styles.
 395     */
 396     wxPropertyGrid( wxWindow *parent, wxWindowID id = wxID_ANY,
 397                     const wxPoint& pos = wxDefaultPosition,
 398                     const wxSize& size = wxDefaultSize,
 399                     long style = wxPG_DEFAULT_STYLE,
 400                     const wxChar* name = wxPropertyGridNameStr );
 401
 402     /** Destructor */
 403     virtual ~wxPropertyGrid();
 404
 405     /**
 406         Adds given key combination to trigger given action.
 407
 408         @param action
 409             Which action to trigger. See @ref propgrid_keyboard_actions.
 410         @param keycode
 411             Which keycode triggers the action.
 412         @param modifiers
 413             Which key event modifiers, in addition to keycode, are needed to
 414             trigger the action.
 415     */
 416     void AddActionTrigger( int action, int keycode, int modifiers = 0 );
 417
 418     /**
 419         Adds given property into selection. If wxPG_EX_MULTIPLE_SELECTION
 420         extra style is not used, then this has same effect as
 421         calling SelectProperty().
 422
 423         @remarks Multiple selection is not supported for categories. This
 424                  means that if you have properties selected, you cannot
 425                  add category to selection, and also if you have category
 426                  selected, you cannot add other properties to selection.
 427                  This member function will fail silently in these cases,
 428                  even returning true.
 429     */
 430     bool AddToSelection( wxPGPropArg id );
 431
 432     /**
 433         This static function enables or disables automatic use of
 434         wxGetTranslation() for following strings: wxEnumProperty list labels,
 435         wxFlagsProperty child property labels.
 436
 437         Default is false.
 438     */
 439     static void AutoGetTranslation( bool enable );
 440
 441     /**
 442         Creates label editor wxTextCtrl for given column, for property
 443         that is currently selected. When multiple selection is
 444         enabled, this applies to whatever property GetSelection()
 445         returns.
 446
 447         @param colIndex
 448             Which column's label to edit. Note that you should not
 449             use value 1, which is reserved for property value
 450             column.
 451
 452         @see EndLabelEdit(), MakeColumnEditable()
 453     */
 454     void BeginLabelEdit( unsigned int column = 0 );
 455
 456     /**
 457         Changes value of a property, as if from an editor. Use this instead of
 458         SetPropertyValue() if you need the value to run through validation
 459         process, and also send the property change event.
 460
 461         @return Returns true if value was successfully changed.
 462     */
 463     bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
 464
 465     /**
 466         Centers the splitter. If argument is true, automatic splitter centering
 467         is enabled (only applicable if style wxPG_SPLITTER_AUTO_CENTER was
 468         defined).
 469     */
 470     void CenterSplitter( bool enable_auto_centering = false );
 471
 472     /**
 473         Deletes all properties.
 474     */
 475     virtual void Clear();
 476
 477     /**
 478         Clears action triggers for given action.
 479
 480         @param action
 481             Which action to trigger. @ref propgrid_keyboard_actions.
 482     */
 483     void ClearActionTriggers( int action );
 484
 485     /**
 486         Forces updating the value of property from the editor control.
 487         Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
 488         ProcessEvent, meaning your event handlers will be called immediately.
 489
 490         @return Returns @true if anything was changed.
 491     */
 492     virtual bool CommitChangesFromEditor( wxUint32 flags = 0 );
 493
 494     /**
 495         Two step creation. Whenever the control is created without any
 496         parameters, use Create to actually create it. Don't access the control's
 497         public methods before this is called
 498
 499         @see @ref propgrid_window_styles.
 500     */
 501     bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
 502                 const wxPoint& pos = wxDefaultPosition,
 503                 const wxSize& size = wxDefaultSize,
 504                 long style = wxPG_DEFAULT_STYLE,
 505                 const wxChar* name = wxPropertyGridNameStr );
 506
 507     /**
 508         Enables or disables (shows/hides) categories according to parameter
 509         enable.
 510
 511         @remarks This functions deselects selected property, if any. Validation
 512                 failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie.
 513                 selection is cleared even if editor had invalid value.
 514     */
 515     bool EnableCategories( bool enable );
 516
 517     /**
 518         Destroys label editor wxTextCtrl, if any.
 519
 520         @param commit
 521             Use @true (default) to store edited label text in
 522             property cell data.
 523
 524         @see BeginLabelEdit(), MakeColumnEditable()
 525     */
 526     void EndLabelEdit( bool commit = true );
 527
 528     /**
 529         Scrolls and/or expands items to ensure that the given item is visible.
 530
 531         @return Returns @true if something was actually done.
 532     */
 533     bool EnsureVisible( wxPGPropArg id );
 534
 535     /**
 536         Reduces column sizes to minimum possible, while still retaining
 537         fully visible grid contents (labels, images).
 538
 539         @return Minimum size for the grid to still display everything.
 540
 541         @remarks Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
 542
 543                 This function only works properly if grid size prior to call was
 544                 already fairly large.
 545
 546                 Note that you can also get calculated column widths by calling
 547                 GetState->GetColumnWidth() immediately after this function
 548                 returns.
 549     */
 550     wxSize FitColumns();
 551
 552     /**
 553         Returns currently active label editor, NULL if none.
 554     */
 555     wxTextCtrl* GetLabelEditor() const;
 556
 557     /**
 558         Returns wxWindow that the properties are painted on, and which should be
 559         used as the parent for editor controls.
 560     */
 561     wxPanel* GetPanel() const;
 562
 563     /**
 564         Returns current category caption background colour.
 565     */
 566     wxColour GetCaptionBackgroundColour() const;
 567
 568     /**
 569         Returns current category caption font.
 570     */
 571     wxFont& GetCaptionFont();
 572
 573     /**
 574         Returns current category caption text colour.
 575     */
 576     wxColour GetCaptionForegroundColour() const;
 577
 578     /**
 579         Returns current cell background colour.
 580     */
 581     wxColour GetCellBackgroundColour() const;
 582
 583     /**
 584         Returns current cell text colour when disabled.
 585     */
 586     wxColour GetCellDisabledTextColour() const;
 587
 588     /**
 589         Returns current cell text colour.
 590     */
 591     wxColour GetCellTextColour() const;
 592
 593     /**
 594         Returns number of columns currently on grid.
 595     */
 596     unsigned int GetColumnCount() const;
 597
 598     /**
 599         Returns colour of empty space below properties.
 600     */
 601     wxColour GetEmptySpaceColour() const;
 602
 603     /**
 604         Returns height of highest characters of used font.
 605     */
 606     int GetFontHeight() const;
 607
 608     /**
 609         Returns pointer to itself. Dummy function that enables same kind
 610         of code to use wxPropertyGrid and wxPropertyGridManager.
 611     */
 612     wxPropertyGrid* GetGrid();
 613
 614     /**
 615         Returns rectangle of custom paint image.
 616
 617         @param property
 618             Return image rectangle for this property.
 619
 620         @param item
 621             Which choice of property to use (each choice may have
 622             different image).
 623     */
 624     wxRect GetImageRect( wxPGProperty* property, int item ) const;
 625
 626     /**
 627         Returns size of the custom paint image in front of property.
 628
 629         @param property
 630             Return image rectangle for this property.
 631             If this argument is NULL, then preferred size is returned.
 632
 633         @param item
 634             Which choice of property to use (each choice may have
 635             different image).
 636     */
 637     wxSize GetImageSize( wxPGProperty* property = NULL, int item = -1 ) const;
 638
 639     /**
 640         Returns last item which could be iterated using given flags.
 641
 642         @param flags
 643             See @ref propgrid_iterator_flags.
 644     */
 645     wxPGProperty* GetLastItem( int flags = wxPG_ITERATE_DEFAULT );
 646
 647     /**
 648         Returns colour of lines between cells.
 649     */
 650     wxColour GetLineColour() const;
 651
 652     /**
 653         Returns background colour of margin.
 654     */
 655     wxColour GetMarginColour() const;
 656
 657     /**
 658         Returns "root property". It does not have name, etc. and it is not
 659         visible. It is only useful for accessing its children.
 660     */
 661     wxPGProperty* GetRoot() const;
 662
 663     /**
 664         Returns height of a single grid row (in pixels).
 665     */
 666     int GetRowHeight() const;
 667
 668     /**
 669         Returns currently selected property.
 670     */
 671     wxPGProperty* GetSelectedProperty() const;
 672
 673     /**
 674         Returns currently selected property.
 675     */
 676     wxPGProperty* GetSelection() const;
 677
 678     /**
 679         Returns current selection background colour.
 680     */
 681     wxColour GetSelectionBackgroundColour() const;
 682
 683     /**
 684         Returns current selection text colour.
 685     */
 686     wxColour GetSelectionForegroundColour() const;
 687
 688     /**
 689         Returns the property sort function (default is @NULL).
 690
 691         @see SetSortFunction
 692     */
 693     wxPGSortCallback GetSortFunction() const;
 694
 695     /**
 696         Returns current splitter x position.
 697     */
 698     int GetSplitterPosition() const;
 699
 700     /**
 701         Returns wxTextCtrl active in currently selected property, if any. Takes
 702         wxOwnerDrawnComboBox into account.
 703     */
 704     wxTextCtrl* GetEditorTextCtrl() const;
 705
 706     /**
 707         Returns current vertical spacing.
 708     */
 709     int GetVerticalSpacing() const;
 710
 711     /**
 712         Returns information about arbitrary position in the grid.
 713
 714         @param pt
 715             Coordinates in the virtual grid space. You may need to use
 716             wxScrolledWindow::CalcScrolledPosition() for translating
 717             wxPropertyGrid client coordinates into something this member
 718             function can use.
 719     */
 720     wxPropertyGridHitTestResult HitTest( const wxPoint& pt ) const;
 721
 722     /**
 723         Returns true if any property has been modified by the user.
 724     */
 725     bool IsAnyModified() const;
 726
 727     /**
 728         Returns @true if a property editor control has focus.
 729     */
 730     bool IsEditorFocused() const;
 731
 732     /**
 733         Returns true if updating is frozen (ie. Freeze() called but not
 734         yet Thaw() ).
 735     */
 736     bool IsFrozen() const;
 737
 738     /**
 739         Makes given column editable by user.
 740
 741         @see BeginLabelEdit(), EndLabelEdit()
 742     */
 743     void MakeColumnEditable( unsigned int column );
 744
 745     /**
 746         It is recommended that you call this function any time your code causes
 747         wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle()
 748         handler should be able to detect most changes, but it is not perfect.
 749
 750         @param newTLP
 751             New top-level parent that is about to be set. Old top-level parent
 752             window should still exist as the current one.
 753
 754         @remarks This function is automatically called from wxPropertyGrid::
 755                  Reparent() and wxPropertyGridManager::Reparent(). You only
 756                  need to use it if you reparent wxPropertyGrid indirectly.
 757     */
 758     void OnTLPChanging( wxWindow* newTLP );
 759
 760     /**
 761         Refreshes any active editor control.
 762     */
 763     void RefreshEditor();
 764
 765     /**
 766         Redraws given property.
 767     */
 768     virtual void RefreshProperty( wxPGProperty* p );
 769
 770     /**
 771         Registers a new editor class.
 772
 773         @return Returns pointer  to the editor class instance that should be used.
 774     */
 775     static wxPGEditor* RegisterEditorClass( wxPGEditor* editor,
 776                                             const wxString& name,
 777                                             bool noDefCheck = false );
 778
 779     /**
 780         Resets all colours to the original system values.
 781     */
 782     void ResetColours();
 783
 784     /**
 785         Removes given property from selection. If property is not selected,
 786         an assertion failure will occur.
 787     */
 788     bool RemoveFromSelection( wxPGPropArg id );
 789
 790     /**
 791         Selects a property. Editor widget is automatically created, but
 792         not focused unless focus is true.
 793
 794         @param id
 795             Property to select (name or pointer).
 796
 797         @param focus
 798             If @true, move keyboard focus to the created editor right away.
 799
 800         @return returns @true if selection finished successfully. Usually only
 801         fails if current value in editor is not valid.
 802
 803         @remarks In wxPropertyGrid 1.4, this member function used to generate
 804                  wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer
 805                  does that.
 806
 807         @remarks This clears any previous selection.
 808
 809         @see wxPropertyGridInterface::ClearSelection()
 810     */
 811     bool SelectProperty( wxPGPropArg id, bool focus = false );
 812
 813     /**
 814         Changes keyboard shortcut to push the editor button.
 815
 816         @remarks You can set default with keycode 0. Good value for the platform
 817                 is guessed, but don't expect it to be very accurate.
 818     */
 819     void SetButtonShortcut( int keycode, bool ctrlDown = false, bool altDown = false );
 820
 821     /**
 822         Sets category caption background colour.
 823     */
 824     void SetCaptionBackgroundColour(const wxColour& col);
 825
 826     /**
 827         Sets category caption text colour.
 828     */
 829     void SetCaptionTextColour(const wxColour& col);
 830
 831     /**
 832         Sets default cell background colour - applies to property cells.
 833         Note that appearance of editor widgets may not be affected.
 834     */
 835     void SetCellBackgroundColour(const wxColour& col);
 836
 837     /**
 838         Sets cell text colour for disabled properties.
 839     */
 840     void SetCellDisabledTextColour(const wxColour& col);
 841
 842     /**
 843         Sets default cell text colour - applies to property name and value text.
 844         Note that appearance of editor widgets may not be affected.
 845     */
 846     void SetCellTextColour(const wxColour& col);
 847
 848     /**
 849         Set number of columns (2 or more).
 850     */
 851     void SetColumnCount( int colCount );
 852
 853     /**
 854         Sets the 'current' category - Append will add non-category properties
 855         under it.
 856     */
 857     void SetCurrentCategory( wxPGPropArg id );
 858
 859     /**
 860         Sets colour of empty space below properties.
 861     */
 862     void SetEmptySpaceColour(const wxColour& col);
 863
 864     /**
 865         Sets colour of lines between cells.
 866     */
 867     void SetLineColour(const wxColour& col);
 868
 869     /**
 870         Sets background colour of margin.
 871     */
 872     void SetMarginColour(const wxColour& col);
 873
 874     /**
 875         Set entire new selection from given list of properties.
 876     */
 877     void SetSelection( const wxArrayPGProperty& newSelection );
 878
 879     /**
 880         Sets selection background colour - applies to selected property name
 881         background.
 882     */
 883     void SetSelectionBackgroundColour(const wxColour& col);
 884
 885     /**
 886         Sets selection foreground colour - applies to selected property name text.
 887     */
 888     void SetSelectionTextColour(const wxColour& col);
 889
 890
 891     /**
 892         Sets the property sorting function.
 893
 894         @param sortFunction
 895             The sorting function to be used. It should return a value greater
 896             than 0 if position of p1 is after p2. So, for instance, when
 897             comparing property names, you can use following implementation:
 898
 899             @code
 900                 int MyPropertySortFunction(wxPropertyGrid* propGrid,
 901                                            wxPGProperty* p1,
 902                                            wxPGProperty* p2)
 903                 {
 904                     return p1->GetBaseName().compare( p2->GetBaseName() );
 905                 }
 906             @endcode
 907
 908         @remarks
 909             Default property sort function sorts properties by their labels
 910             (case-insensitively).
 911
 912         @see GetSortFunction, wxPropertyGridInterface::Sort,
 913              wxPropertyGridInterface::SortChildren
 914     */
 915     void SetSortFunction( wxPGSortCallback sortFunction );
 916
 917     /**
 918         Sets x coordinate of the splitter.
 919
 920         @remarks Splitter position cannot exceed grid size, and therefore setting
 921                 it during form creation may fail as initial grid size is often
 922                 smaller than desired splitter position, especially when sizers
 923                 are being used.
 924     */
 925     void SetSplitterPosition( int newxpos, int col = 0 );
 926
 927     /**
 928         Moves splitter as left as possible, while still allowing all
 929         labels to be shown in full.
 930
 931         @param privateChildrenToo
 932             If @false, will still allow private children to be cropped.
 933     */
 934     void SetSplitterLeft( bool privateChildrenToo = false );
 935
 936     /**
 937         Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
 938         height. Value of 2 should be default on most platforms.
 939     */
 940     void SetVerticalSpacing( int vspacing );
 941
 942
 943     /**
 944         @name Property development functions
 945
 946         These member functions are usually only called when creating custom
 947         user properties.
 948     */
 949     //@{
 950
 951     /**
 952         Call when editor widget's contents is modified. For example, this is
 953         called when changes text in wxTextCtrl (used in wxStringProperty and
 954         wxIntProperty).
 955
 956         @remarks This function should only be called by custom properties.
 957
 958         @see wxPGProperty::OnEvent()
 959     */
 960     void EditorsValueWasModified();
 961
 962     /**
 963         Reverse of EditorsValueWasModified().
 964
 965         @remarks This function should only be called by custom properties.
 966     */
 967     void EditorsValueWasNotModified();
 968
 969     /**
 970         Returns most up-to-date value of selected property. This will return
 971         value different from GetSelectedProperty()->GetValue() only when text
 972         editor is activate and string edited by user represents valid,
 973         uncommitted property value.
 974     */
 975     wxVariant GetUncommittedPropertyValue();
 976
 977     /**
 978         Returns true if editor's value was marked modified.
 979     */
 980     bool IsEditorsValueModified() const;
 981
 982     /**
 983         Shows an brief error message that is related to a property.
 984     */
 985     void ShowPropertyError( wxPGPropArg id, const wxString& msg );
 986
 987     /**
 988         You can use this member function, for instance, to detect in
 989         wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was
 990         already called in wxPGEditor::OnEvent(). It really only detects
 991         if was value was changed using wxPGProperty::SetValueInEvent(), which
 992         is usually used when a 'picker' dialog is displayed. If value was
 993         written by "normal means" in wxPGProperty::StringToValue() or
 994         IntToValue(), then this function will return false (on the other hand,
 995         wxPGProperty::OnEvent() is not even called in those cases).
 996     */
 997     bool WasValueChangedInEvent() const;
 998
 999     //@}
1000 };
1001
1002
1003 /**
1004     @class wxPropertyGridEvent
1005
1006     A property grid event holds information about events associated with
1007     wxPropertyGrid objects.
1008
1009     @library{wxpropgrid}
1010     @category{propgrid}
1011 */
1012 class wxPropertyGridEvent : public wxCommandEvent
1013 {
1014 public:
1015
1016     /** Constructor. */
1017     wxPropertyGridEvent(wxEventType commandType=0, int id=0);
1018
1019     /** Copy constructor. */
1020     wxPropertyGridEvent(const wxPropertyGridEvent& event);
1021
1022     /** Destructor. */
1023     ~wxPropertyGridEvent();
1024
1025     /**
1026         Returns true if you can veto the action that the event is signaling.
1027     */
1028     bool CanVeto() const;
1029
1030     /**
1031         Returns highest level non-category, non-root parent of property for
1032         which event occurred. Useful when you have nested properties with
1033         children.
1034
1035         @remarks If immediate parent is root or category, this will return the
1036                 property itself.
1037     */
1038     wxPGProperty* GetMainParent() const;
1039
1040     /**
1041         Returns property associated with this event.
1042     */
1043     wxPGProperty* GetProperty() const;
1044
1045     /**
1046         Returns current validation failure flags.
1047     */
1048     wxPGVFBFlags GetValidationFailureBehavior() const;
1049
1050     /**
1051         Returns value that is about to be set for wxEVT_PG_CHANGING.
1052     */
1053     const wxVariant& GetValue() const;
1054
1055     /**
1056         Set if event can be vetoed.
1057     */
1058     void SetCanVeto( bool canVeto );
1059
1060     /** Changes the property associated with this event. */
1061     void SetProperty( wxPGProperty* p );
1062
1063     /**
1064         Set override validation failure behavior. Only effective if Veto() was
1065         also called, and only allowed if event type is wxEVT_PG_CHANGING.
1066     */
1067     void SetValidationFailureBehavior( wxPGVFBFlags flags );
1068
1069     /**
1070         Sets custom failure message for this time only. Only applies if
1071         wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
1072     */
1073     void SetValidationFailureMessage( const wxString& message );
1074
1075     /**
1076         Call this from your event handler to veto action that the event is
1077         signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto()
1078         returns true.
1079
1080         @remarks Currently only wxEVT_PG_CHANGING supports vetoing.
1081     */
1082     void Veto( bool veto = true );
1083
1084     /**
1085         Returns @true if event was vetoed.
1086     */
1087     bool WasVetoed() const;
1088 };