interface/wx/propgrid/propgrid.h

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