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