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