interface/wx/propgrid/propgrid.h

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