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