include/wx/propgrid/propgrid.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/propgrid/propgrid.h
   3 // Purpose:     wxPropertyGrid
   4 // Author:      Jaakko Salli
   5 // Modified by:
   6 // Created:     2004-09-25
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Jaakko Salli
   9 // Licence:     wxWindows license
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_PROPGRID_PROPGRID_H_
  13 #define _WX_PROPGRID_PROPGRID_H_
  14
  15 #if wxUSE_PROPGRID
  16
  17 #include "wx/dcclient.h"
  18 #include "wx/scrolwin.h"
  19 #include "wx/tooltip.h"
  20 #include "wx/datetime.h"
  21
  22 #include "wx/propgrid/property.h"
  23 #include "wx/propgrid/propgridiface.h"
  24
  25
  26 #ifndef SWIG
  27 extern WXDLLIMPEXP_DATA_PROPGRID(const char) wxPropertyGridNameStr[];
  28 #endif
  29
  30 class wxPGComboBox;
  31
  32 // -----------------------------------------------------------------------
  33 // Global variables
  34 // -----------------------------------------------------------------------
  35
  36 #ifndef SWIG
  37
  38 // This is required for sharing common global variables.
  39 class WXDLLIMPEXP_PROPGRID wxPGGlobalVarsClass
  40 {
  41 public:
  42
  43     wxPGGlobalVarsClass();
  44     ~wxPGGlobalVarsClass();
  45
  46     // Used by advprops, but here to make things easier.
  47     wxString            m_pDefaultImageWildcard;
  48
  49     // Map of editor class instances (keys are name string).
  50     wxPGHashMapS2P      m_mapEditorClasses;
  51
  52 #if wxUSE_VALIDATORS
  53     wxVector<wxValidator*>  m_arrValidators; // These wxValidators need to be freed
  54 #endif
  55
  56     wxPGHashMapS2P      m_dictPropertyClassInfo; // PropertyName -> ClassInfo
  57
  58     wxPGChoices*        m_fontFamilyChoices;
  59
  60     // Replace with your own to affect all properties using default renderer.
  61     wxPGCellRenderer*   m_defaultRenderer;
  62
  63     wxPGChoices         m_boolChoices;
  64
  65     wxVariant           m_vEmptyString;
  66     wxVariant           m_vZero;
  67     wxVariant           m_vMinusOne;
  68     wxVariant           m_vTrue;
  69     wxVariant           m_vFalse;
  70
  71     // Cached constant strings
  72     wxPGCachedString    m_strstring;
  73     wxPGCachedString    m_strlong;
  74     wxPGCachedString    m_strbool;
  75     wxPGCachedString    m_strlist;
  76
  77     wxPGCachedString    m_strDefaultValue;
  78     wxPGCachedString    m_strMin;
  79     wxPGCachedString    m_strMax;
  80     wxPGCachedString    m_strUnits;
  81     wxPGCachedString    m_strInlineHelp;
  82
  83     // If true then some things are automatically translated
  84     bool                m_autoGetTranslation;
  85
  86     // > 0 if errors cannot or should not be shown in statusbar etc.
  87     int                 m_offline;
  88
  89     int                 m_extraStyle;  // global extra style
  90
  91     int                 m_warnings;
  92
  93     int HasExtraStyle( int style ) const { return (m_extraStyle & style); }
  94 };
  95
  96 extern WXDLLIMPEXP_PROPGRID wxPGGlobalVarsClass* wxPGGlobalVars;
  97
  98 #define wxPGVariant_EmptyString     (wxPGGlobalVars->m_vEmptyString)
  99 #define wxPGVariant_Zero            (wxPGGlobalVars->m_vZero)
 100 #define wxPGVariant_MinusOne        (wxPGGlobalVars->m_vMinusOne)
 101 #define wxPGVariant_True            (wxPGGlobalVars->m_vTrue)
 102 #define wxPGVariant_False           (wxPGGlobalVars->m_vFalse)
 103
 104 #define wxPGVariant_Bool(A)     (A?wxPGVariant_True:wxPGVariant_False)
 105
 106 // When wxPG is loaded dynamically after the application is already running
 107 // then the built-in module system won't pick this one up.  Add it manually.
 108 WXDLLIMPEXP_PROPGRID void wxPGInitResourceModule();
 109
 110 #endif // !SWIG
 111
 112 // -----------------------------------------------------------------------
 113
 114 /** @section propgrid_window_styles wxPropertyGrid Window Styles
 115
 116     SetWindowStyleFlag method can be used to modify some of these at run-time.
 117     @{
 118 */
 119 enum wxPG_WINDOW_STYLES
 120 {
 121
 122 /** This will cause Sort() automatically after an item is added.
 123     When inserting a lot of items in this mode, it may make sense to
 124     use Freeze() before operations and Thaw() afterwards to increase
 125     performance.
 126 */
 127 wxPG_AUTO_SORT                      = 0x00000010,
 128
 129 /** Categories are not initially shown (even if added).
 130     IMPORTANT NOTE: If you do not plan to use categories, then this
 131     style will waste resources.
 132     This flag can also be changed using wxPropertyGrid::EnableCategories method.
 133 */
 134 wxPG_HIDE_CATEGORIES                = 0x00000020,
 135
 136 /* This style combines non-categoric mode and automatic sorting.
 137 */
 138 wxPG_ALPHABETIC_MODE                = (wxPG_HIDE_CATEGORIES|wxPG_AUTO_SORT),
 139
 140 /** Modified values are shown in bold font. Changing this requires Refresh()
 141     to show changes.
 142 */
 143 wxPG_BOLD_MODIFIED                  = 0x00000040,
 144
 145 /** When wxPropertyGrid is resized, splitter moves to the center. This
 146     behavior stops once the user manually moves the splitter.
 147 */
 148 wxPG_SPLITTER_AUTO_CENTER           = 0x00000080,
 149
 150 /** Display tooltips for cell text that cannot be shown completely. If
 151     wxUSE_TOOLTIPS is 0, then this doesn't have any effect.
 152 */
 153 wxPG_TOOLTIPS                       = 0x00000100,
 154
 155 /** Disables margin and hides all expand/collapse buttons that would appear
 156     outside the margin (for sub-properties). Toggling this style automatically
 157     expands all collapsed items.
 158 */
 159 wxPG_HIDE_MARGIN                    = 0x00000200,
 160
 161 /** This style prevents user from moving the splitter.
 162 */
 163 wxPG_STATIC_SPLITTER                = 0x00000400,
 164
 165 /** Combination of other styles that make it impossible for user to modify
 166     the layout.
 167 */
 168 wxPG_STATIC_LAYOUT                  = (wxPG_HIDE_MARGIN|wxPG_STATIC_SPLITTER),
 169
 170 /** Disables wxTextCtrl based editors for properties which
 171     can be edited in another way.
 172
 173     Equals calling wxPropertyGrid::LimitPropertyEditing for all added
 174     properties.
 175 */
 176 wxPG_LIMITED_EDITING                = 0x00000800,
 177
 178 /** wxPropertyGridManager only: Show toolbar for mode and page selection. */
 179 wxPG_TOOLBAR                        = 0x00001000,
 180
 181 /** wxPropertyGridManager only: Show adjustable text box showing description
 182     or help text, if available, for currently selected property.
 183 */
 184 wxPG_DESCRIPTION                    = 0x00002000,
 185
 186 /** wxPropertyGridManager only: don't show an internal border around the property grid
 187 */
 188 wxPG_NO_INTERNAL_BORDER             = 0x00004000
 189 };
 190
 191 enum wxPG_EX_WINDOW_STYLES
 192 {
 193
 194 /**
 195     NOTE: wxPG_EX_xxx are extra window styles and must be set using
 196     SetExtraStyle() member function.
 197
 198     Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if
 199     wxPG_HIDE_CATEGORIES is not defined, the non-categorized data storage is
 200     not activated, and switching the mode first time becomes somewhat slower.
 201     wxPG_EX_INIT_NOCAT activates the non-categorized data storage right away.
 202     IMPORTANT NOTE: If you do plan not switching to non-categoric mode, or if
 203     you don't plan to use categories at all, then using this style will result
 204     in waste of resources.
 205
 206 */
 207 wxPG_EX_INIT_NOCAT                  = 0x00001000,
 208
 209 /** Extended window style that sets wxPropertyGridManager toolbar to not
 210     use flat style.
 211 */
 212 wxPG_EX_NO_FLAT_TOOLBAR             = 0x00002000,
 213
 214 /** Shows alphabetic/categoric mode buttons from toolbar.
 215 */
 216 wxPG_EX_MODE_BUTTONS                = 0x00008000,
 217
 218 /** Show property help strings as tool tips instead as text on the status bar.
 219     You can set the help strings using SetPropertyHelpString member function.
 220 */
 221 wxPG_EX_HELP_AS_TOOLTIPS            = 0x00010000,
 222
 223 /** Prevent TAB from focusing to wxButtons. This behavior was default
 224     in version 1.2.0 and earlier.
 225     NOTE! Tabbing to button doesn't work yet. Problem seems to be that on wxMSW
 226       atleast the button doesn't properly propagate key events (yes, I'm using
 227       wxWANTS_CHARS).
 228 */
 229 //wxPG_EX_NO_TAB_TO_BUTTON            = 0x00020000,
 230
 231 /** Allows relying on native double-buffering.
 232 */
 233 wxPG_EX_NATIVE_DOUBLE_BUFFERING         = 0x00080000,
 234
 235 /** Set this style to let user have ability to set values of properties to
 236     unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for
 237     all properties.
 238 */
 239 wxPG_EX_AUTO_UNSPECIFIED_VALUES         = 0x00200000,
 240
 241 /**
 242     If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION
 243     and wxPG_STRING_PASSWORD) are not stored into property's attribute storage
 244     (thus they are not readable).
 245
 246     Note that this option is global, and applies to all wxPG property
 247     containers.
 248 */
 249 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES    = 0x00400000,
 250
 251 /** Hides page selection buttons from toolbar.
 252 */
 253 wxPG_EX_HIDE_PAGE_BUTTONS               = 0x01000000,
 254
 255 /** Allows multiple properties to be selected by user (by pressing SHIFT
 256     when clicking on a property, or by dragging with left mouse button
 257     down).
 258
 259     You can get array of selected properties with
 260     wxPropertyGridInterface::GetSelectedProperties(). In multiple selection
 261     mode wxPropertyGridInterface::GetSelection() returns
 262     property which has editor active (usually the first one
 263     selected). Other useful member functions are ClearSelection(),
 264     AddToSelection() and RemoveFromSelection().
 265 */
 266 wxPG_EX_MULTIPLE_SELECTION              = 0x02000000,
 267
 268 /**
 269     This enables top-level window tracking which allows wxPropertyGrid to
 270     notify the application of last-minute property value changes by user.
 271
 272     This style is not enabled by default because it may cause crashes when
 273     wxPropertyGrid is used in with wxAUI or similar system.
 274
 275     @remarks If you are not in fact using any system that may change
 276              wxPropertyGrid's top-level parent window on its own, then you
 277              are recommended to enable this style.
 278 */
 279 wxPG_EX_ENABLE_TLP_TRACKING             = 0x04000000,
 280
 281 /** Don't show divider above toolbar, on Windows.
 282 */
 283 wxPG_EX_NO_TOOLBAR_DIVIDER              = 0x08000000,
 284
 285 /** Show a separator below the toolbar.
 286 */
 287 wxPG_EX_TOOLBAR_SEPARATOR               = 0x10000000
 288
 289 };
 290
 291 #if wxPG_COMPATIBILITY_1_4
 292     #define wxPG_EX_DISABLE_TLP_TRACKING    0x00000000
 293 #endif
 294
 295 /** Combines various styles.
 296 */
 297 #define wxPG_DEFAULT_STYLE          (0)
 298
 299 /** Combines various styles.
 300 */
 301 #define wxPGMAN_DEFAULT_STYLE       (0)
 302
 303 /** @}
 304 */
 305
 306 // -----------------------------------------------------------------------
 307
 308 //
 309 // Ids for sub-controls
 310 // NB: It should not matter what these are.
 311 #define wxPG_SUBID1                     2
 312 #define wxPG_SUBID2                     3
 313 #define wxPG_SUBID_TEMP1                4
 314
 315 // -----------------------------------------------------------------------
 316
 317 /** @class wxPGCommonValue
 318
 319     wxPropertyGrid stores information about common values in these
 320     records.
 321
 322     NB: Common value feature is not complete, and thus not mentioned in
 323         documentation.
 324 */
 325 class WXDLLIMPEXP_PROPGRID wxPGCommonValue
 326 {
 327 public:
 328
 329     wxPGCommonValue( const wxString& label, wxPGCellRenderer* renderer )
 330     {
 331         m_label = label;
 332         m_renderer = renderer;
 333         renderer->IncRef();
 334     }
 335     virtual ~wxPGCommonValue()
 336     {
 337         m_renderer->DecRef();
 338     }
 339
 340     virtual wxString GetEditableText() const { return m_label; }
 341     const wxString& GetLabel() const { return m_label; }
 342     wxPGCellRenderer* GetRenderer() const { return m_renderer; }
 343
 344 protected:
 345     wxString            m_label;
 346     wxPGCellRenderer*   m_renderer;
 347 };
 348
 349 // -----------------------------------------------------------------------
 350
 351 /** @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
 352     @{
 353 */
 354
 355 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
 356 {
 357
 358 /** Prevents user from leaving property unless value is valid. If this
 359     behavior flag is not used, then value change is instead cancelled.
 360 */
 361 wxPG_VFB_STAY_IN_PROPERTY           = 0x01,
 362
 363 /** Calls wxBell() on validation failure.
 364 */
 365 wxPG_VFB_BEEP                       = 0x02,
 366
 367 /** Cell with invalid value will be marked (with red colour).
 368 */
 369 wxPG_VFB_MARK_CELL                  = 0x04,
 370
 371 /** Display customizable text message explaining the situation.
 372 */
 373 wxPG_VFB_SHOW_MESSAGE               = 0x08,
 374
 375 /** Defaults. */
 376 wxPG_VFB_DEFAULT                    = wxPG_VFB_STAY_IN_PROPERTY|wxPG_VFB_BEEP,
 377
 378 /** Only used internally. */
 379 wxPG_VFB_UNDEFINED                  = 0x80
 380
 381 };
 382
 383 /** @}
 384 */
 385
 386 typedef wxByte wxPGVFBFlags;
 387
 388 /**
 389     wxPGValidationInfo
 390
 391     Used to convey validation information to and from functions that
 392     actually perform validation. Mostly used in custom property
 393     classes.
 394 */
 395 class WXDLLIMPEXP_PROPGRID wxPGValidationInfo
 396 {
 397     friend class wxPropertyGrid;
 398 public:
 399     /**
 400         @return Returns failure behavior which is a combination of
 401                @ref propgrid_vfbflags.
 402     */
 403     wxPGVFBFlags GetFailureBehavior() const
 404         { return m_failureBehavior; }
 405
 406     /**
 407         Returns current failure message.
 408     */
 409     const wxString& GetFailureMessage() const
 410         { return m_failureMessage; }
 411
 412     /**
 413         Returns reference to pending value.
 414     */
 415     const wxVariant& GetValue() const
 416     {
 417         wxASSERT(m_pValue);
 418         return *m_pValue;
 419     }
 420
 421     /** Set validation failure behavior
 422
 423         @param failureBehavior
 424             Mixture of @ref propgrid_vfbflags.
 425     */
 426     void SetFailureBehavior(wxPGVFBFlags failureBehavior)
 427         { m_failureBehavior = failureBehavior; }
 428
 429     /**
 430         Set current failure message.
 431     */
 432     void SetFailureMessage(const wxString& message)
 433         { m_failureMessage = message; }
 434
 435 private:
 436     /** Value to be validated.
 437     */
 438     wxVariant*      m_pValue;
 439
 440     /** Message displayed on validation failure.
 441     */
 442     wxString        m_failureMessage;
 443
 444     /** Validation failure behavior. Use wxPG_VFB_XXX flags.
 445     */
 446     wxPGVFBFlags    m_failureBehavior;
 447 };
 448
 449 // -----------------------------------------------------------------------
 450
 451 /** @section propgrid_pgactions wxPropertyGrid Action Identifiers
 452
 453     These are used with wxPropertyGrid::AddActionTrigger() and
 454     wxPropertyGrid::ClearActionTriggers().
 455     @{
 456 */
 457
 458 enum wxPG_KEYBOARD_ACTIONS
 459 {
 460     wxPG_ACTION_INVALID = 0,
 461     wxPG_ACTION_NEXT_PROPERTY,
 462     wxPG_ACTION_PREV_PROPERTY,
 463     wxPG_ACTION_EXPAND_PROPERTY,
 464     wxPG_ACTION_COLLAPSE_PROPERTY,
 465     wxPG_ACTION_CANCEL_EDIT,
 466     wxPG_ACTION_PRESS_BUTTON,  // Causes editor button (if any) to be pressed
 467     wxPG_ACTION_MAX
 468 };
 469
 470 /** @}
 471 */
 472
 473 // -----------------------------------------------------------------------
 474
 475
 476 // wxPropertyGrid::DoSelectProperty flags (selFlags)
 477
 478 // Focuses to created editor
 479 #define wxPG_SEL_FOCUS                  0x0001
 480 // Forces deletion and recreation of editor
 481 #define wxPG_SEL_FORCE                  0x0002
 482 // For example, doesn't cause EnsureVisible
 483 #define wxPG_SEL_NONVISIBLE             0x0004
 484 // Do not validate editor's value before selecting
 485 #define wxPG_SEL_NOVALIDATE             0x0008
 486 // Property being deselected is about to be deleted
 487 #define wxPG_SEL_DELETING               0x0010
 488 // Property's values was set to unspecified by the user
 489 #define wxPG_SEL_SETUNSPEC              0x0020
 490 // Property's event handler changed the value
 491 #define wxPG_SEL_DIALOGVAL              0x0040
 492 // Set to disable sending of wxEVT_PG_SELECTED event
 493 #define wxPG_SEL_DONT_SEND_EVENT        0x0080
 494 // Don't make any graphics updates
 495 #define wxPG_SEL_NO_REFRESH             0x0100
 496
 497 // -----------------------------------------------------------------------
 498
 499 #ifndef SWIG
 500
 501 // Internal flags
 502 #define wxPG_FL_INITIALIZED                 0x0001
 503 // Set when creating editor controls if it was clicked on.
 504 #define wxPG_FL_ACTIVATION_BY_CLICK         0x0002
 505 #define wxPG_FL_DONT_CENTER_SPLITTER        0x0004
 506 #define wxPG_FL_FOCUSED                     0x0008
 507 #define wxPG_FL_MOUSE_CAPTURED              0x0010
 508 #define wxPG_FL_MOUSE_INSIDE                0x0020
 509 #define wxPG_FL_VALUE_MODIFIED              0x0040
 510 // don't clear background of m_wndEditor
 511 #define wxPG_FL_PRIMARY_FILLS_ENTIRE        0x0080
 512 // currently active editor uses custom image
 513 #define wxPG_FL_CUR_USES_CUSTOM_IMAGE       0x0100
 514 // cell colours override selection colours for selected cell
 515 #define wxPG_FL_CELL_OVERRIDES_SEL          0x0200
 516 #define wxPG_FL_SCROLLED                    0x0400
 517 // set when all added/inserted properties get hideable flag
 518 #define wxPG_FL_ADDING_HIDEABLES            0x0800
 519 // Disables showing help strings on statusbar.
 520 #define wxPG_FL_NOSTATUSBARHELP             0x1000
 521 // Marks that we created the state, so we have to destroy it too.
 522 #define wxPG_FL_CREATEDSTATE                0x2000
 523 // Set if scrollbar's existence was detected in last onresize.
 524 #define wxPG_FL_SCROLLBAR_DETECTED          0x4000
 525 // Set if wxPGMan requires redrawing of description text box.
 526 #define wxPG_FL_DESC_REFRESH_REQUIRED       0x8000
 527 // Set if contained in wxPropertyGridManager
 528 #define wxPG_FL_IN_MANAGER                  0x00020000
 529 // Set after wxPropertyGrid is shown in its initial good size
 530 #define wxPG_FL_GOOD_SIZE_SET               0x00040000
 531 // Set when in SelectProperty.
 532 #define wxPG_FL_IN_SELECT_PROPERTY          0x00100000
 533 // Set when help string is shown in status bar
 534 #define wxPG_FL_STRING_IN_STATUSBAR         0x00200000
 535 // Splitter position has been custom-set by the user
 536 #define wxPG_FL_SPLITTER_PRE_SET            0x00400000
 537 // Validation failed. Clear on modify event.
 538 #define wxPG_FL_VALIDATION_FAILED           0x00800000
 539 // Auto sort is enabled (for categorized mode)
 540 #define wxPG_FL_CATMODE_AUTO_SORT           0x01000000
 541 // Set after page has been inserted to manager
 542 #define wxPG_MAN_FL_PAGE_INSERTED           0x02000000
 543 // Active editor control is abnormally large
 544 #define wxPG_FL_ABNORMAL_EDITOR             0x04000000
 545 // Recursion guard for HandleCustomEditorEvent
 546 #define wxPG_FL_IN_HANDLECUSTOMEDITOREVENT  0x08000000
 547 #define wxPG_FL_VALUE_CHANGE_IN_EVENT       0x10000000
 548 // Editor control width should not change on resize
 549 #define wxPG_FL_FIXED_WIDTH_EDITOR          0x20000000
 550 // Width of panel can be different than width of grid
 551 #define wxPG_FL_HAS_VIRTUAL_WIDTH           0x40000000
 552 // Prevents RecalculateVirtualSize re-entrancy
 553 #define wxPG_FL_RECALCULATING_VIRTUAL_SIZE  0x80000000
 554
 555 #endif // #ifndef SWIG
 556
 557 #if !defined(__wxPG_SOURCE_FILE__) && !defined(SWIG)
 558     // Reduce compile time, but still include in user app
 559     #include "wx/propgrid/props.h"
 560 #endif
 561
 562 // -----------------------------------------------------------------------
 563
 564 /** @class wxPropertyGrid
 565
 566     wxPropertyGrid is a specialized grid for editing properties
 567     such as strings, numbers, flagsets, fonts, and colours. wxPropertySheet
 568     used to do the very same thing, but it hasn't been updated for a while
 569     and it is currently deprecated.
 570
 571     Please note that most member functions are inherited and as such not
 572     documented on this page. This means you will probably also want to read
 573     wxPropertyGridInterface class reference.
 574
 575     See also @ref overview_propgrid.
 576
 577     @section propgrid_window_styles_ Window Styles
 578
 579     See @ref propgrid_window_styles.
 580
 581     @section propgrid_event_handling Event Handling
 582
 583     To process input from a propertygrid control, use these event handler
 584     macros to direct input to member functions that take a wxPropertyGridEvent
 585     argument.
 586
 587     @beginEventTable{wxPropertyGridEvent}
 588     @event{EVT_PG_SELECTED (id, func)}
 589         Respond to wxEVT_PG_SELECTED event, generated when a property selection
 590         has been changed, either by user action or by indirect program
 591         function. For instance, collapsing a parent property programmatically
 592         causes any selected child property to become unselected, and may
 593         therefore cause this event to be generated.
 594     @event{EVT_PG_CHANGING(id, func)}
 595         Respond to wxEVT_PG_CHANGING event, generated when property value
 596         is about to be changed by user. Use wxPropertyGridEvent::GetValue()
 597         to take a peek at the pending value, and wxPropertyGridEvent::Veto()
 598         to prevent change from taking place, if necessary.
 599     @event{EVT_PG_HIGHLIGHTED(id, func)}
 600         Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
 601         moves over a property. Event's property is NULL if hovered area does
 602         not belong to any property.
 603     @event{EVT_PG_RIGHT_CLICK(id, func)}
 604         Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
 605         clicked on with right mouse button.
 606     @event{EVT_PG_DOUBLE_CLICK(id, func)}
 607         Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
 608         double-clicked onwith left mouse button.
 609     @event{EVT_PG_ITEM_COLLAPSED(id, func)}
 610         Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
 611         a property or category..
 612     @event{EVT_PG_ITEM_EXPANDED(id, func)}
 613         Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
 614         a property or category..
 615     @event{EVT_PG_LABEL_EDIT_BEGIN(id, func)}
 616         Respond to wxEVT_PG_LABEL_EDIT_BEGIN event, generated when is about to
 617         begin editing a property label. You can veto this event to prevent the
 618         action.
 619     @event{EVT_PG_LABEL_EDIT_ENDING(id, func)}
 620         Respond to wxEVT_PG_LABEL_EDIT_ENDING event, generated when is about to
 621         end editing of a property label. You can veto this event to prevent the
 622         action.
 623     @endEventTable
 624
 625     @remarks
 626
 627     - Use Freeze() and Thaw() respectively to disable and enable drawing. This
 628       will also delay sorting etc. miscellaneous calculations to the last
 629       possible moment.
 630
 631     @library{wxpropgrid}
 632     @category{propgrid}
 633 */
 634 class WXDLLIMPEXP_PROPGRID
 635     wxPropertyGrid : public wxScrolledWindow, public wxPropertyGridInterface
 636 {
 637     friend class wxPropertyGridPageState;
 638     friend class wxPropertyGridInterface;
 639     friend class wxPropertyGridManager;
 640     friend class wxPGCanvas;
 641
 642     DECLARE_DYNAMIC_CLASS(wxPropertyGrid)
 643 public:
 644
 645 #ifndef SWIG
 646     /**
 647         Two step constructor.
 648
 649         Call Create when this constructor is called to build up the
 650         wxPropertyGrid
 651     */
 652     wxPropertyGrid();
 653 #endif
 654
 655     /** The default constructor. The styles to be used are styles valid for
 656         the wxWindow and wxScrolledWindow.
 657
 658         @see @link wndflags Additional Window Styles @endlink
 659     */
 660     wxPropertyGrid( wxWindow *parent, wxWindowID id = wxID_ANY,
 661                     const wxPoint& pos = wxDefaultPosition,
 662                     const wxSize& size = wxDefaultSize,
 663                     long style = wxPG_DEFAULT_STYLE,
 664                     const wxString& name = wxPropertyGridNameStr );
 665
 666     /** Destructor */
 667     virtual ~wxPropertyGrid();
 668
 669     /** Adds given key combination to trigger given action.
 670
 671         @param action
 672             Which action to trigger. See @link pgactions List of list of
 673             wxPropertyGrid actions@endlink.
 674     */
 675     void AddActionTrigger( int action, int keycode, int modifiers = 0 );
 676
 677     /**
 678         This static function enables or disables automatic use of
 679         wxGetTranslation for following strings: wxEnumProperty list labels,
 680         wxFlagsProperty sub-property labels.
 681
 682         Default is false.
 683     */
 684     static void AutoGetTranslation( bool enable );
 685
 686     /**
 687         Changes value of a property, as if from an editor.
 688
 689         Use this instead of SetPropertyValue() if you need the value to run
 690         through validation process, and also send the property change event.
 691
 692         @return
 693         Returns true if value was successfully changed.
 694     */
 695     bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
 696
 697     /**
 698         Centers the splitter.
 699
 700         If argument is true, automatic splitter centering is enabled (only
 701         applicapple if style wxPG_SPLITTER_AUTO_CENTER was defined).
 702     */
 703     void CenterSplitter( bool enable_auto_centering = false );
 704
 705     /** Deletes all properties.
 706     */
 707     virtual void Clear();
 708
 709     /** Clears action triggers for given action.
 710         @param action
 711             Which action to trigger. See @link pgactions List of list of
 712             wxPropertyGrid actions@endlink.
 713     */
 714     void ClearActionTriggers( int action );
 715
 716     /** Forces updating the value of property from the editor control.
 717
 718         Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
 719         ProcessEvent, meaning your event handlers will be called immediately.
 720
 721         @return
 722         Returns true if anything was changed.
 723     */
 724     virtual bool CommitChangesFromEditor( wxUint32 flags = 0 );
 725
 726     /**
 727         Two step creation.
 728
 729         Whenever the control is created without any parameters, use Create to
 730         actually create it. Don't access the control's public methods before
 731         this is called @see @link wndflags Additional Window Styles@endlink
 732     */
 733     bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
 734                  const wxPoint& pos = wxDefaultPosition,
 735                  const wxSize& size = wxDefaultSize,
 736                  long style = wxPG_DEFAULT_STYLE,
 737                  const wxString& name = wxPropertyGridNameStr );
 738
 739     /**
 740         Call when editor widget's contents is modified.
 741
 742         For example, this is called when changes text in wxTextCtrl (used in
 743         wxStringProperty and wxIntProperty).
 744
 745         @remarks
 746         This function should only be called by custom properties.
 747
 748         @see wxPGProperty::OnEvent()
 749     */
 750     void EditorsValueWasModified() { m_iFlags |= wxPG_FL_VALUE_MODIFIED; }
 751
 752     /** Reverse of EditorsValueWasModified().
 753
 754         @remarks
 755         This function should only be called by custom properties.
 756     */
 757     void EditorsValueWasNotModified()
 758     {
 759         m_iFlags &= ~(wxPG_FL_VALUE_MODIFIED);
 760     }
 761
 762     /**
 763         Enables or disables (shows/hides) categories according to parameter
 764         enable.
 765      */
 766     bool EnableCategories( bool enable );
 767
 768     /** Scrolls and/or expands items to ensure that the given item is visible.
 769         Returns true if something was actually done.
 770     */
 771     bool EnsureVisible( wxPGPropArg id );
 772
 773     /**
 774         Reduces column sizes to minimum possible that contents are still
 775         visibly (naturally some margin space will be applied as well).
 776
 777         @return
 778         Minimum size for the grid to still display everything.
 779
 780         @remarks
 781         Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
 782
 783         This function only works properly if grid size prior to call was already
 784         fairly large.
 785
 786         Note that you can also get calculated column widths by calling
 787         GetState->GetColumnWidth() immediately after this function returns.
 788     */
 789     wxSize FitColumns()
 790     {
 791         wxSize sz = m_pState->DoFitColumns();
 792         return sz;
 793     }
 794
 795     /**
 796         Returns wxWindow that the properties are painted on, and which should
 797         be used as the parent for editor controls.
 798     */
 799     wxPanel* GetPanel() const
 800     {
 801         return m_canvas;
 802     }
 803
 804     /** Returns current category caption background colour. */
 805     wxColour GetCaptionBackgroundColour() const { return m_colCapBack; }
 806
 807     wxFont& GetCaptionFont() { return m_captionFont; }
 808
 809     const wxFont& GetCaptionFont() const { return m_captionFont; }
 810
 811     /** Returns current category caption text colour. */
 812     wxColour GetCaptionForegroundColour() const { return m_colCapFore; }
 813
 814     /** Returns current cell background colour. */
 815     wxColour GetCellBackgroundColour() const { return m_colPropBack; }
 816
 817     /** Returns current cell text colour when disabled. */
 818     wxColour GetCellDisabledTextColour() const { return m_colDisPropFore; }
 819
 820     /** Returns current cell text colour. */
 821     wxColour GetCellTextColour() const { return m_colPropFore; }
 822
 823     /**
 824         Returns number of columns currently on grid.
 825     */
 826     unsigned int GetColumnCount() const
 827     {
 828         return (unsigned int) m_pState->m_colWidths.size();
 829     }
 830
 831     /** Returns colour of empty space below properties. */
 832     wxColour GetEmptySpaceColour() const { return m_colEmptySpace; }
 833
 834     /** Returns height of highest characters of used font. */
 835     int GetFontHeight() const { return m_fontHeight; }
 836
 837     /** Returns pointer to itself. Dummy function that enables same kind
 838         of code to use wxPropertyGrid and wxPropertyGridManager.
 839     */
 840     wxPropertyGrid* GetGrid() { return this; }
 841
 842     /** Returns rectangle of custom paint image.
 843     */
 844     wxRect GetImageRect( wxPGProperty* p, int item ) const;
 845
 846     /** Returns size of the custom paint image in front of property.
 847         If no argument is given, returns preferred size.
 848     */
 849     wxSize GetImageSize( wxPGProperty* p = NULL, int item = -1 ) const;
 850
 851     //@{
 852     /** Returns last item which could be iterated using given flags.
 853         @param flags
 854         See @ref propgrid_iterator_flags.
 855     */
 856     wxPGProperty* GetLastItem( int flags = wxPG_ITERATE_DEFAULT )
 857     {
 858         return m_pState->GetLastItem(flags);
 859     }
 860
 861     const wxPGProperty* GetLastItem( int flags = wxPG_ITERATE_DEFAULT ) const
 862     {
 863         return m_pState->GetLastItem(flags);
 864     }
 865     //@}
 866
 867     /** Returns colour of lines between cells. */
 868     wxColour GetLineColour() const { return m_colLine; }
 869
 870     /** Returns background colour of margin. */
 871     wxColour GetMarginColour() const { return m_colMargin; }
 872
 873     /**
 874         Returns most up-to-date value of selected property. This will return
 875         value different from GetSelectedProperty()->GetValue() only when text
 876         editor is activate and string edited by user represents valid,
 877         uncommitted property value.
 878     */
 879     wxVariant GetUncommittedPropertyValue();
 880
 881     /** Returns "root property". It does not have name, etc. and it is not
 882         visible. It is only useful for accessing its children.
 883     */
 884     wxPGProperty* GetRoot() const { return m_pState->m_properties; }
 885
 886     /** Returns height of a single grid row (in pixels). */
 887     int GetRowHeight() const { return m_lineHeight; }
 888
 889     /** Returns currently selected property. */
 890     wxPGProperty* GetSelectedProperty() const { return GetSelection(); }
 891
 892     /** Returns current selection background colour. */
 893     wxColour GetSelectionBackgroundColour() const { return m_colSelBack; }
 894
 895     /** Returns current selection text colour. */
 896     wxColour GetSelectionForegroundColour() const { return m_colSelFore; }
 897
 898     /** Returns current splitter x position. */
 899     int GetSplitterPosition() const
 900         { return m_pState->DoGetSplitterPosition(0); }
 901
 902     /** Returns wxTextCtrl active in currently selected property, if any. Takes
 903         into account wxOwnerDrawnComboBox.
 904     */
 905     wxTextCtrl* GetEditorTextCtrl() const;
 906
 907     wxPGValidationInfo& GetValidationInfo()
 908     {
 909         return m_validationInfo;
 910     }
 911
 912     /** Returns current vertical spacing. */
 913     int GetVerticalSpacing() const { return (int)m_vspacing; }
 914
 915     /**
 916         Returns @true if a property editor control has focus.
 917     */
 918     bool IsEditorFocused() const;
 919
 920     /** Returns true if editor's value was marked modified.
 921     */
 922     bool IsEditorsValueModified() const
 923         { return  ( m_iFlags & wxPG_FL_VALUE_MODIFIED ) ? true : false; }
 924
 925     /**
 926         Returns information about arbitrary position in the grid.
 927
 928         @param pt
 929             Coordinates in the virtual grid space. You may need to use
 930             wxScrolledWindow::CalcScrolledPosition() for translating
 931             wxPropertyGrid client coordinates into something this member
 932             function can use.
 933     */
 934     wxPropertyGridHitTestResult HitTest( const wxPoint& pt ) const;
 935
 936     /** Returns true if any property has been modified by the user. */
 937     bool IsAnyModified() const { return (m_pState->m_anyModified>0); }
 938
 939     /**
 940         Returns true if updating is frozen (ie Freeze() called but not yet
 941         Thaw() ).
 942      */
 943     bool IsFrozen() const { return (m_frozen>0)?true:false; }
 944
 945     /**
 946         It is recommended that you call this function any time your code causes
 947         wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle()
 948         handler should be able to detect most changes, but it is not perfect.
 949
 950         @param newTLP
 951             New top-level parent that is about to be set. Old top-level parent
 952             window should still exist as the current one.
 953
 954         @remarks This function is automatically called from wxPropertyGrid::
 955                  Reparent() and wxPropertyGridManager::Reparent(). You only
 956                  need to use it if you reparent wxPropertyGrid indirectly.
 957     */
 958     void OnTLPChanging( wxWindow* newTLP );
 959
 960     /** Redraws given property.
 961     */
 962     virtual void RefreshProperty( wxPGProperty* p );
 963
 964 #ifndef SWIG
 965     /** Registers a new editor class.
 966         @return
 967         Pointer to the editor class instance that should be used.
 968     */
 969     static wxPGEditor* RegisterEditorClass( wxPGEditor* editor,
 970                                             bool noDefCheck = false )
 971     {
 972         return DoRegisterEditorClass(editor, wxEmptyString, noDefCheck);
 973     }
 974
 975     static wxPGEditor* DoRegisterEditorClass( wxPGEditor* editorClass,
 976                                               const wxString& editorName,
 977                                               bool noDefCheck = false );
 978 #endif
 979
 980     /** Resets all colours to the original system values.
 981     */
 982     void ResetColours();
 983
 984     /**
 985         Selects a property.
 986         Editor widget is automatically created, but not focused unless focus is
 987         true.
 988
 989         @param id
 990             Property to select.
 991
 992         @return
 993             True if selection finished successfully. Usually only fails if
 994             current value in editor is not valid.
 995
 996         @remarks In wxPropertyGrid 1.4, this member function used to generate
 997                  wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer
 998                  does that.
 999
1000         @remarks This clears any previous selection.
1001     */
1002     bool SelectProperty( wxPGPropArg id, bool focus = false );
1003
1004     /**
1005         Set entire new selection from given list of properties.
1006     */
1007     void SetSelection( const wxArrayPGProperty& newSelection )
1008     {
1009         DoSetSelection( newSelection, wxPG_SEL_DONT_SEND_EVENT );
1010     }
1011
1012     /**
1013         Adds given property into selection. If wxPG_EX_MULTIPLE_SELECTION
1014         extra style is not used, then this has same effect as
1015         calling SelectProperty().
1016
1017         @remarks Multiple selection is not supported for categories. This
1018                  means that if you have properties selected, you cannot
1019                  add category to selection, and also if you have category
1020                  selected, you cannot add other properties to selection.
1021                  This member function will fail silently in these cases,
1022                  even returning true.
1023     */
1024     bool AddToSelection( wxPGPropArg id )
1025     {
1026         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
1027         return DoAddToSelection(p, wxPG_SEL_DONT_SEND_EVENT);
1028     }
1029
1030     /**
1031         Removes given property from selection. If property is not selected,
1032         an assertion failure will occur.
1033     */
1034     bool RemoveFromSelection( wxPGPropArg id )
1035     {
1036         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
1037         return DoRemoveFromSelection(p, wxPG_SEL_DONT_SEND_EVENT);
1038     }
1039
1040     /**
1041         Makes given column editable by user.
1042
1043         @param editable
1044             Using @false here will disable column from being editable.
1045     */
1046     void MakeColumnEditable( unsigned int column, bool editable = true );
1047
1048     /**
1049         Creates label editor wxTextCtrl for given column, for property
1050         that is currently selected. When multiple selection is
1051         enabled, this applies to whatever property GetSelection()
1052         returns.
1053
1054         @param colIndex
1055             Which column's label to edit. Note that you should not
1056             use value 1, which is reserved for property value
1057             column.
1058
1059         @see EndLabelEdit(), MakeColumnEditable()
1060     */
1061     void BeginLabelEdit( unsigned int column = 0 )
1062     {
1063         DoBeginLabelEdit(column, wxPG_SEL_DONT_SEND_EVENT);
1064     }
1065
1066     /**
1067         Destroys label editor wxTextCtrl, if any.
1068
1069         @param commit
1070             Use @true (default) to store edited label text in
1071             property cell data.
1072
1073         @see BeginLabelEdit(), MakeColumnEditable()
1074     */
1075     void EndLabelEdit( bool commit = true )
1076     {
1077         DoEndLabelEdit(commit, wxPG_SEL_DONT_SEND_EVENT);
1078     }
1079
1080     /**
1081         Returns currently active label editor, NULL if none.
1082     */
1083     wxTextCtrl* GetLabelEditor() const
1084     {
1085         return m_labelEditor;
1086     }
1087
1088     /** Sets category caption background colour. */
1089     void SetCaptionBackgroundColour(const wxColour& col);
1090
1091     /** Sets category caption text colour. */
1092     void SetCaptionTextColour(const wxColour& col);
1093
1094     /** Sets default cell background colour - applies to property cells.
1095         Note that appearance of editor widgets may not be affected.
1096     */
1097     void SetCellBackgroundColour(const wxColour& col);
1098
1099     /** Sets cell text colour for disabled properties.
1100     */
1101     void SetCellDisabledTextColour(const wxColour& col);
1102
1103     /** Sets default cell text colour - applies to property name and value text.
1104         Note that appearance of editor widgets may not be affected.
1105     */
1106     void SetCellTextColour(const wxColour& col);
1107
1108     /** Set number of columns (2 or more).
1109     */
1110     void SetColumnCount( int colCount )
1111     {
1112         m_pState->SetColumnCount(colCount);
1113         Refresh();
1114     }
1115
1116     /**
1117         Sets the 'current' category - Append will add non-category properties
1118         under it.
1119     */
1120     void SetCurrentCategory( wxPGPropArg id )
1121     {
1122         wxPG_PROP_ARG_CALL_PROLOG()
1123         wxPropertyCategory* pc = wxDynamicCast(p, wxPropertyCategory);
1124         wxASSERT(pc);
1125         m_pState->m_currentCategory = pc;
1126     }
1127
1128     /** Sets colour of empty space below properties. */
1129     void SetEmptySpaceColour(const wxColour& col);
1130
1131     /** Sets colour of lines between cells. */
1132     void SetLineColour(const wxColour& col);
1133
1134     /** Sets background colour of margin. */
1135     void SetMarginColour(const wxColour& col);
1136
1137     /**
1138         Sets selection background colour - applies to selected property name
1139         background.
1140     */
1141     void SetSelectionBackgroundColour(const wxColour& col);
1142
1143     /**
1144         Sets selection foreground colour - applies to selected property name
1145         text.
1146      */
1147     void SetSelectionTextColour(const wxColour& col);
1148
1149     /** Sets x coordinate of the splitter.
1150         @remarks
1151         Splitter position cannot exceed grid size, and therefore setting it
1152         during form creation may fail as initial grid size is often smaller
1153         than desired splitter position, especially when sizers are being used.
1154     */
1155     void SetSplitterPosition( int newxpos, int col = 0 )
1156     {
1157         DoSetSplitterPosition_(newxpos, true, col);
1158         m_iFlags |= wxPG_FL_SPLITTER_PRE_SET;
1159     }
1160
1161     /**
1162         Sets the property sorting function.
1163
1164         @param sortFunction
1165             The sorting function to be used. It should return a value greater
1166             than 0 if position of p1 is after p2. So, for instance, when
1167             comparing property names, you can use following implementation:
1168
1169             @code
1170                 int MyPropertySortFunction(wxPropertyGrid* propGrid,
1171                                            wxPGProperty* p1,
1172                                            wxPGProperty* p2)
1173                 {
1174                     return p1->GetBaseName().compare( p2->GetBaseName() );
1175                 }
1176             @endcode
1177
1178         @remarks
1179             Default property sort function sorts properties by their labels
1180             (case-insensitively).
1181
1182         @see GetSortFunction, wxPropertyGridInterface::Sort,
1183              wxPropertyGridInterface::SortChildren
1184     */
1185     void SetSortFunction( wxPGSortCallback sortFunction )
1186     {
1187         m_sortFunction = sortFunction;
1188     }
1189
1190     /**
1191         Returns the property sort function (default is @NULL).
1192
1193         @see SetSortFunction
1194     */
1195     wxPGSortCallback GetSortFunction() const
1196     {
1197         return m_sortFunction;
1198     }
1199
1200     /** Set virtual width for this particular page. Width -1 indicates that the
1201         virtual width should be disabled. */
1202     void SetVirtualWidth( int width );
1203
1204     /**
1205         Moves splitter as left as possible, while still allowing all
1206         labels to be shown in full.
1207
1208         @param privateChildrenToo
1209             If @false, will still allow private children to be cropped.
1210     */
1211     void SetSplitterLeft( bool privateChildrenToo = false )
1212     {
1213         m_pState->SetSplitterLeft(privateChildrenToo);
1214     }
1215
1216     /** Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
1217         height. Value of 2 should be default on most platforms.
1218     */
1219     void SetVerticalSpacing( int vspacing )
1220     {
1221         m_vspacing = (unsigned char)vspacing;
1222         CalculateFontAndBitmapStuff( vspacing );
1223         if ( !m_pState->m_itemsAdded ) Refresh();
1224     }
1225
1226     /** Shows an brief error message that is related to a property. */
1227     void ShowPropertyError( wxPGPropArg id, const wxString& msg )
1228     {
1229         wxPG_PROP_ARG_CALL_PROLOG()
1230         DoShowPropertyError(p, msg);
1231     }
1232
1233     /////////////////////////////////////////////////////////////////
1234     //
1235     // Following methods do not need to be (currently) documented
1236     //
1237     /////////////////////////////////////////////////////////////////
1238
1239     bool HasVirtualWidth() const
1240         { return (m_iFlags & wxPG_FL_HAS_VIRTUAL_WIDTH) ? true : false; }
1241
1242     const wxPGCommonValue* GetCommonValue( unsigned int i ) const
1243     {
1244         return (wxPGCommonValue*) m_commonValues[i];
1245     }
1246
1247     /** Returns number of common values.
1248     */
1249     unsigned int GetCommonValueCount() const
1250     {
1251         return (unsigned int) m_commonValues.size();
1252     }
1253
1254     /** Returns label of given common value.
1255     */
1256     wxString GetCommonValueLabel( unsigned int i ) const
1257     {
1258         wxASSERT( GetCommonValue(i) );
1259         return GetCommonValue(i)->GetLabel();
1260     }
1261
1262     /**
1263         Returns index of common value that will truly change value to
1264         unspecified.
1265     */
1266     int GetUnspecifiedCommonValue() const { return m_cvUnspecified; }
1267
1268     /** Set index of common value that will truly change value to unspecified.
1269         Using -1 will set none to have such effect.
1270         Default is 0.
1271     */
1272     void SetUnspecifiedCommonValue( int index ) { m_cvUnspecified = index; }
1273
1274     /**
1275         Shortcut for creating dialog-caller button. Used, for example, by
1276         wxFontProperty.
1277         @remarks
1278         This should only be called by properties.
1279     */
1280     wxWindow* GenerateEditorButton( const wxPoint& pos, const wxSize& sz );
1281
1282     /** Fixes position of wxTextCtrl-like control (wxSpinCtrl usually
1283         fits as one). Call after control has been created (but before
1284         shown).
1285     */
1286     void FixPosForTextCtrl( wxWindow* ctrl,
1287                             unsigned int forColumn = 1,
1288                             const wxPoint& offset = wxPoint(0, 0) );
1289
1290     /** Shortcut for creating text editor widget.
1291         @param pos
1292             Same as pos given for CreateEditor.
1293         @param sz
1294             Same as sz given for CreateEditor.
1295         @param value
1296             Initial text for wxTextCtrl.
1297         @param secondary
1298             If right-side control, such as button, also created, then create it
1299             first and pass it as this parameter.
1300         @param extraStyle
1301             Extra style flags to pass for wxTextCtrl.
1302         @remarks
1303         Note that this should generally be called only by new classes derived
1304         from wxPGProperty.
1305     */
1306     wxWindow* GenerateEditorTextCtrl( const wxPoint& pos,
1307                                       const wxSize& sz,
1308                                       const wxString& value,
1309                                       wxWindow* secondary,
1310                                       int extraStyle = 0,
1311                                       int maxLen = 0,
1312                                       unsigned int forColumn = 1 );
1313
1314     /* Generates both textctrl and button.
1315     */
1316     wxWindow* GenerateEditorTextCtrlAndButton( const wxPoint& pos,
1317         const wxSize& sz, wxWindow** psecondary, int limited_editing,
1318         wxPGProperty* property );
1319
1320     /** Generates position for a widget editor dialog box.
1321         @param p
1322         Property for which dialog is positioned.
1323         @param sz
1324         Known or over-approximated size of the dialog.
1325         @return
1326         Position for dialog.
1327     */
1328     wxPoint GetGoodEditorDialogPosition( wxPGProperty* p,
1329                                          const wxSize& sz );
1330
1331     // Converts escape sequences in src_str to newlines,
1332     // tabs, etc. and copies result to dst_str.
1333     static wxString& ExpandEscapeSequences( wxString& dst_str,
1334                                             wxString& src_str );
1335
1336     // Converts newlines, tabs, etc. in src_str to escape
1337     // sequences, and copies result to dst_str.
1338     static wxString& CreateEscapeSequences( wxString& dst_str,
1339                                             wxString& src_str );
1340
1341     /**
1342         Returns rectangle that fully contains properties between and including
1343         p1 and p2.
1344     */
1345     wxRect GetPropertyRect( const wxPGProperty* p1,
1346                             const wxPGProperty* p2 ) const;
1347
1348     /** Returns pointer to current active primary editor control (NULL if none).
1349     */
1350     wxWindow* GetEditorControl() const;
1351
1352     wxWindow* GetPrimaryEditor() const
1353     {
1354         return GetEditorControl();
1355     }
1356
1357     /**
1358         Returns pointer to current active secondary editor control (NULL if
1359         none).
1360     */
1361     wxWindow* GetEditorControlSecondary() const
1362     {
1363         return m_wndEditor2;
1364     }
1365
1366     /**
1367         Refreshes any active editor control.
1368     */
1369     void RefreshEditor();
1370
1371     // Events from editor controls are forward to this function
1372     void HandleCustomEditorEvent( wxEvent &event );
1373
1374 #ifndef SWIG
1375
1376     /**
1377         Generates contents for string dst based on the contents of
1378         wxArrayString src.
1379
1380         Format will be "(preDelim)str1(postDelim) (preDelim)str2(postDelim) and
1381         so on. Set flags to 1 inorder to convert backslashes to double-back-
1382         slashes and "(preDelims)"'s to "(preDelims)".
1383     */
1384     static void ArrayStringToString( wxString& dst, const wxArrayString& src,
1385                                      wxChar preDelim, wxChar postDelim,
1386                                      int flags );
1387
1388     // Mostly useful for page switching.
1389     void SwitchState( wxPropertyGridPageState* pNewState );
1390
1391     long GetInternalFlags() const { return m_iFlags; }
1392     bool HasInternalFlag( long flag ) const
1393         { return (m_iFlags & flag) ? true : false; }
1394     void SetInternalFlag( long flag ) { m_iFlags |= flag; }
1395     void ClearInternalFlag( long flag ) { m_iFlags &= ~(flag); }
1396     void IncFrozen() { m_frozen++; }
1397     void DecFrozen() { m_frozen--; }
1398
1399     void OnComboItemPaint( const wxPGComboBox* pCb,
1400                            int item,
1401                            wxDC* pDc,
1402                            wxRect& rect,
1403                            int flags );
1404
1405     /** Standardized double-to-string conversion.
1406     */
1407     static void DoubleToString( wxString& target,
1408                                 double value,
1409                                 int precision,
1410                                 bool removeZeroes,
1411                                 wxString* precTemplate );
1412
1413     /**
1414         Call this from wxPGProperty::OnEvent() to cause property value to be
1415         changed after the function returns (with true as return value).
1416         ValueChangeInEvent() must be used if you wish the application to be
1417         able to use wxEVT_PG_CHANGING to potentially veto the given value.
1418     */
1419     void ValueChangeInEvent( wxVariant variant )
1420     {
1421         m_changeInEventValue = variant;
1422         m_iFlags |= wxPG_FL_VALUE_CHANGE_IN_EVENT;
1423     }
1424
1425     /**
1426         You can use this member function, for instance, to detect in
1427         wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was
1428         already called in wxPGEditor::OnEvent(). It really only detects
1429         if was value was changed using wxPGProperty::SetValueInEvent(), which
1430         is usually used when a 'picker' dialog is displayed. If value was
1431         written by "normal means" in wxPGProperty::StringToValue() or
1432         IntToValue(), then this function will return false (on the other hand,
1433         wxPGProperty::OnEvent() is not even called in those cases).
1434     */
1435     bool WasValueChangedInEvent() const
1436     {
1437         return (m_iFlags & wxPG_FL_VALUE_CHANGE_IN_EVENT) ? true : false;
1438     }
1439
1440     /** Returns true if given event is from first of an array of buttons
1441         (as can be in case when wxPGMultiButton is used).
1442     */
1443     bool IsMainButtonEvent( const wxEvent& event )
1444     {
1445         return (event.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED)
1446                     && (m_wndSecId == event.GetId());
1447     }
1448
1449     /** Pending value is expected to be passed in PerformValidation().
1450     */
1451     virtual bool DoPropertyChanged( wxPGProperty* p,
1452                                     unsigned int selFlags = 0 );
1453
1454     /** Called when validation for given property fails.
1455         @param invalidValue
1456             Value which failed in validation.
1457         @return
1458             Return true if user is allowed to change to another property even
1459             if current has invalid value.
1460         @remarks
1461         To add your own validation failure behavior, override
1462         wxPropertyGrid::DoOnValidationFailure().
1463     */
1464     bool OnValidationFailure( wxPGProperty* property,
1465                               wxVariant& invalidValue );
1466
1467     /** Called to indicate property and editor has valid value now.
1468     */
1469     void OnValidationFailureReset( wxPGProperty* property )
1470     {
1471         if ( property && property->HasFlag(wxPG_PROP_INVALID_VALUE) )
1472         {
1473             DoOnValidationFailureReset(property);
1474             property->ClearFlag(wxPG_PROP_INVALID_VALUE);
1475         }
1476         m_validationInfo.m_failureMessage.clear();
1477     }
1478
1479     /** Override in derived class to display error messages in custom manner
1480         (these message usually only result from validation failure).
1481     */
1482     virtual void DoShowPropertyError( wxPGProperty* property,
1483                                       const wxString& msg );
1484
1485     /** Override to customize property validation failure behavior.
1486         @param invalidValue
1487             Value which failed in validation.
1488         @return
1489             Return true if user is allowed to change to another property even
1490             if current has invalid value.
1491     */
1492     virtual bool DoOnValidationFailure( wxPGProperty* property,
1493                                         wxVariant& invalidValue );
1494
1495     /** Override to customize resetting of property validation failure status.
1496         @remarks
1497         Property is guaranteed to have flag wxPG_PROP_INVALID_VALUE set.
1498     */
1499     virtual void DoOnValidationFailureReset( wxPGProperty* property );
1500
1501     int GetSpacingY() const { return m_spacingy; }
1502
1503     /**
1504         Must be called in wxPGEditor::CreateControls() if primary editor window
1505         is wxTextCtrl, just before textctrl is created.
1506         @param text
1507             Initial text value of created wxTextCtrl.
1508     */
1509     void SetupTextCtrlValue( const wxString text ) { m_prevTcValue = text; }
1510
1511     /**
1512         Unfocuses or closes editor if one was open, but does not deselect
1513         property.
1514     */
1515     bool UnfocusEditor();
1516
1517     virtual void SetWindowStyleFlag( long style );
1518
1519     void DrawItems( const wxPGProperty* p1, const wxPGProperty* p2 );
1520
1521     void DrawItem( wxPGProperty* p )
1522     {
1523         DrawItems(p,p);
1524     }
1525
1526     virtual void DrawItemAndChildren( wxPGProperty* p );
1527
1528     /**
1529         Draws item, children, and consequtive parents as long as category is
1530         not met.
1531      */
1532     void DrawItemAndValueRelated( wxPGProperty* p );
1533
1534 protected:
1535
1536     /**
1537         wxPropertyGridPageState used by the grid is created here.
1538
1539         If grid is used in wxPropertyGridManager, there is no point overriding
1540         this - instead, set custom wxPropertyGridPage classes.
1541     */
1542     virtual wxPropertyGridPageState* CreateState() const;
1543
1544     enum PerformValidationFlags
1545     {
1546         SendEvtChanging         = 0x0001,
1547         IsStandaloneValidation  = 0x0002   // Not called in response to event
1548     };
1549
1550     /**
1551         Runs all validation functionality (includes sending wxEVT_PG_CHANGING).
1552         Returns true if all tests passed. Implement in derived class to
1553         add additional validation behavior.
1554     */
1555     virtual bool PerformValidation( wxPGProperty* p,
1556                                     wxVariant& pendingValue,
1557                                     int flags = SendEvtChanging );
1558
1559 public:
1560
1561     // Control font changer helper.
1562     void SetCurControlBoldFont();
1563
1564     wxPGCell& GetPropertyDefaultCell()
1565     {
1566         return m_propertyDefaultCell;
1567     }
1568
1569     wxPGCell& GetCategoryDefaultCell()
1570     {
1571         return m_categoryDefaultCell;
1572     }
1573
1574     //
1575     // Public methods for semi-public use
1576     //
1577     bool DoSelectProperty( wxPGProperty* p, unsigned int flags = 0 );
1578
1579     // Overridden functions.
1580     virtual bool Destroy();
1581     // Returns property at given y coordinate (relative to grid's top left).
1582     wxPGProperty* GetItemAtY( int y ) const { return DoGetItemAtY(y); }
1583
1584     virtual void Refresh( bool eraseBackground = true,
1585                           const wxRect *rect = (const wxRect *) NULL );
1586     virtual bool SetFont( const wxFont& font );
1587 #if wxPG_SUPPORT_TOOLTIPS
1588     void SetToolTip( const wxString& tipString );
1589 #endif
1590     virtual void Freeze();
1591     virtual void SetExtraStyle( long exStyle );
1592     virtual void Thaw();
1593     virtual bool Reparent( wxWindowBase *newParent );
1594
1595 protected:
1596     virtual wxSize DoGetBestSize() const;
1597
1598 #ifndef wxPG_ICON_WIDTH
1599     wxBitmap            *m_expandbmp, *m_collbmp;
1600 #endif
1601
1602     wxCursor            *m_cursorSizeWE;
1603
1604     /** wxWindow pointers to editor control(s). */
1605     wxWindow            *m_wndEditor;
1606     wxWindow            *m_wndEditor2;
1607
1608     /** wxPGCanvas instance. */
1609     wxPanel             *m_canvas;
1610
1611 #if wxPG_DOUBLE_BUFFER
1612     wxBitmap            *m_doubleBuffer;
1613 #endif
1614
1615     /** Local time ms when control was created. */
1616     wxLongLong          m_timeCreated;
1617
1618     /** wxPGProperty::OnEvent can change value by setting this. */
1619     wxVariant           m_changeInEventValue;
1620
1621     /** Id of m_wndEditor2, or its first child, if any. */
1622     int                 m_wndSecId;
1623
1624     /** Extra Y spacing between the items. */
1625     int                 m_spacingy;
1626
1627     /** Control client area width; updated on resize. */
1628     int                 m_width;
1629
1630     /** Control client area height; updated on resize. */
1631     int                 m_height;
1632
1633     /** Current non-client width (needed when auto-centering). */
1634     int                 m_ncWidth;
1635
1636     /** Non-client width (auto-centering helper). */
1637     //int                 m_fWidth;
1638
1639     /** Previously recorded scroll start position. */
1640     int                 m_prevVY;
1641
1642     /**
1643         The gutter spacing in front and back of the image.
1644         This determines the amount of spacing in front of each item
1645      */
1646     int                 m_gutterWidth;
1647
1648     /** Includes separator line. */
1649     int                 m_lineHeight;
1650
1651     /** Gutter*2 + image width. */
1652     int                 m_marginWidth;
1653
1654     // y spacing for expand/collapse button.
1655     int                 m_buttonSpacingY;
1656
1657     /** Extra margin for expanded sub-group items. */
1658     int                 m_subgroup_extramargin;
1659
1660     /**
1661         The image width of the [+] icon.
1662
1663         This is also calculated in the gutter
1664      */
1665     int                 m_iconWidth;
1666
1667 #ifndef wxPG_ICON_WIDTH
1668
1669     /**
1670         The image height of the [+] icon.
1671
1672         This is calculated as minimal size and to align
1673      */
1674     int                 m_iconHeight;
1675 #endif
1676
1677     /** Current cursor id. */
1678     int                 m_curcursor;
1679
1680     /**
1681         This captionFont is made equal to the font of the wxScrolledWindow.
1682
1683         As extra the bold face is set on it when this is wanted by the user
1684         (see flags)
1685      */
1686     wxFont              m_captionFont;
1687
1688     int                 m_fontHeight;  // Height of the font.
1689
1690     /** m_splitterx when drag began. */
1691     int                 m_startingSplitterX;
1692
1693     /**
1694         Index to splitter currently being dragged (0=one after the first
1695         column).
1696      */
1697     int                 m_draggedSplitter;
1698
1699     /** Changed property, calculated in PerformValidation(). */
1700     wxPGProperty*       m_chgInfo_changedProperty;
1701
1702     /**
1703         Lowest property for which editing happened, but which does not have
1704         aggregate parent
1705      */
1706     wxPGProperty*       m_chgInfo_baseChangedProperty;
1707
1708     /** Changed property value, calculated in PerformValidation(). */
1709     wxVariant           m_chgInfo_pendingValue;
1710
1711     /** Passed to SetValue. */
1712     wxVariant           m_chgInfo_valueList;
1713
1714     /** Validation information. */
1715     wxPGValidationInfo  m_validationInfo;
1716
1717     /** Actions and keys that trigger them. */
1718     wxPGHashMapI2I      m_actionTriggers;
1719
1720     //
1721     // Temporary values
1722     //
1723
1724     /** Bits are used to indicate which colours are customized. */
1725     unsigned short      m_coloursCustomized;
1726
1727     /** x - m_splitterx. */
1728     signed char                 m_dragOffset;
1729
1730     /** 0 = not dragging, 1 = drag just started, 2 = drag in progress */
1731     unsigned char       m_dragStatus;
1732
1733     /** 0 = margin, 1 = label, 2 = value. */
1734     unsigned char       m_mouseSide;
1735
1736     /** True when editor control is focused. */
1737     unsigned char       m_editorFocused;
1738
1739     /** 1 if m_latsCaption is also the bottommost caption. */
1740     //unsigned char       m_lastCaptionBottomnest;
1741
1742     /** Set to 1 when graphics frozen. */
1743     unsigned char       m_frozen;
1744
1745     unsigned char       m_vspacing;
1746
1747     // Used to track when Alt/Ctrl+Key was consumed.
1748     unsigned char       m_keyComboConsumed;
1749
1750     /** 1 if in DoPropertyChanged() */
1751     unsigned char       m_inDoPropertyChanged;
1752
1753     /** 1 if in CommitChangesFromEditor() */
1754     unsigned char       m_inCommitChangesFromEditor;
1755
1756     /** 1 if in DoSelectProperty() */
1757     unsigned char       m_inDoSelectProperty;
1758
1759     wxPGVFBFlags        m_permanentValidationFailureBehavior;  // Set by app
1760
1761     /** Internal flags - see wxPG_FL_XXX constants. */
1762     wxUint32            m_iFlags;
1763
1764     /** When drawing next time, clear this many item slots at the end. */
1765     int                 m_clearThisMany;
1766
1767     // Mouse is hovering over this column (index)
1768     unsigned int        m_colHover;
1769
1770     // pointer to property that has mouse hovering
1771     wxPGProperty*       m_propHover;
1772
1773     // Active label editor
1774     wxTextCtrl*         m_labelEditor;
1775
1776     // For which property the label editor is active
1777     wxPGProperty*       m_labelEditorProperty;
1778
1779     // EventObject for wxPropertyGridEvents
1780     wxWindow*           m_eventObject;
1781
1782     // What (global) window is currently focused (needed to resolve event
1783     // handling mess).
1784     wxWindow*           m_curFocused;
1785
1786     // Event currently being sent - NULL if none at the moment
1787     wxPropertyGridEvent*    m_processedEvent;
1788
1789     // Last known top-level parent
1790     wxWindow*           m_tlp;
1791
1792     // Last closed top-level parent
1793     wxWindow*           m_tlpClosed;
1794
1795     // Local time ms when tlp was closed.
1796     wxLongLong          m_tlpClosedTime;
1797
1798     // Sort function
1799     wxPGSortCallback    m_sortFunction;
1800
1801     // y coordinate of property that mouse hovering
1802     int                 m_propHoverY;
1803
1804     // Which column's editor is selected (usually 1)?
1805     unsigned int        m_selColumn;
1806
1807     // x relative to splitter (needed for resize).
1808     int                 m_ctrlXAdjust;
1809
1810     // lines between cells
1811     wxColour            m_colLine;
1812     // property labels and values are written in this colour
1813     wxColour            m_colPropFore;
1814     // or with this colour when disabled
1815     wxColour            m_colDisPropFore;
1816     // background for m_colPropFore
1817     wxColour            m_colPropBack;
1818     // text color for captions
1819     wxColour            m_colCapFore;
1820     // background color for captions
1821     wxColour            m_colCapBack;
1822     // foreground for selected property
1823     wxColour            m_colSelFore;
1824     // background for selected property (actually use background color when
1825     // control out-of-focus)
1826     wxColour            m_colSelBack;
1827     // background colour for margin
1828     wxColour            m_colMargin;
1829     // background colour for empty space below the grid
1830     wxColour            m_colEmptySpace;
1831
1832     // Default property colours
1833     wxPGCell            m_propertyDefaultCell;
1834
1835     // Default property category
1836     wxPGCell            m_categoryDefaultCell;
1837
1838     // Backup of selected property's cells
1839     wxVector<wxPGCell>  m_propCellsBackup;
1840
1841     // NB: These *cannot* be moved to globals.
1842
1843     // labels when properties use common values
1844     wxVector<wxPGCommonValue*>  m_commonValues;
1845
1846     // Which cv selection really sets value to unspecified?
1847     int                 m_cvUnspecified;
1848
1849     // Used to skip excess text editor events
1850     wxString            m_prevTcValue;
1851
1852 protected:
1853
1854     // Sets some members to defaults (called constructors).
1855     void Init1();
1856
1857     // Initializes some members (called by Create and complex constructor).
1858     void Init2();
1859
1860     void OnPaint(wxPaintEvent &event );
1861
1862     // main event receivers
1863     void OnMouseMove( wxMouseEvent &event );
1864     void OnMouseMoveBottom( wxMouseEvent &event );
1865     void OnMouseClick( wxMouseEvent &event );
1866     void OnMouseRightClick( wxMouseEvent &event );
1867     void OnMouseDoubleClick( wxMouseEvent &event );
1868     void OnMouseUp( wxMouseEvent &event );
1869     void OnKey( wxKeyEvent &event );
1870     void OnResize( wxSizeEvent &event );
1871
1872     // event handlers
1873     bool HandleMouseMove( int x, unsigned int y, wxMouseEvent &event );
1874     bool HandleMouseClick( int x, unsigned int y, wxMouseEvent &event );
1875     bool HandleMouseRightClick( int x, unsigned int y, wxMouseEvent &event );
1876     bool HandleMouseDoubleClick( int x, unsigned int y, wxMouseEvent &event );
1877     bool HandleMouseUp( int x, unsigned int y, wxMouseEvent &event );
1878     void HandleKeyEvent( wxKeyEvent &event, bool fromChild );
1879
1880     void OnMouseEntry( wxMouseEvent &event );
1881
1882     void OnIdle( wxIdleEvent &event );
1883     void OnFocusEvent( wxFocusEvent &event );
1884     void OnChildFocusEvent( wxChildFocusEvent& event );
1885
1886     bool OnMouseCommon( wxMouseEvent &event, int* px, int *py );
1887     bool OnMouseChildCommon( wxMouseEvent &event, int* px, int *py );
1888
1889     // sub-control event handlers
1890     void OnMouseClickChild( wxMouseEvent &event );
1891     void OnMouseRightClickChild( wxMouseEvent &event );
1892     void OnMouseMoveChild( wxMouseEvent &event );
1893     void OnMouseUpChild( wxMouseEvent &event );
1894     void OnChildKeyDown( wxKeyEvent &event );
1895
1896     void OnCaptureChange( wxMouseCaptureChangedEvent &event );
1897
1898     void OnScrollEvent( wxScrollWinEvent &event );
1899
1900     void OnSysColourChanged( wxSysColourChangedEvent &event );
1901
1902     void OnTLPClose( wxCloseEvent& event );
1903
1904 protected:
1905
1906     bool AddToSelectionFromInputEvent( wxPGProperty* prop,
1907                                        unsigned int colIndex,
1908                                        wxMouseEvent* event = NULL,
1909                                        int selFlags = 0 );
1910
1911     /**
1912         Adjust the centering of the bitmap icons (collapse / expand) when the
1913         caption font changes.
1914
1915         They need to be centered in the middle of the font, so a bit of deltaY
1916         adjustment is needed. On entry, m_captionFont must be set to window
1917         font. It will be modified properly.
1918       */
1919     void CalculateFontAndBitmapStuff( int vspacing );
1920
1921     wxRect GetEditorWidgetRect( wxPGProperty* p, int column ) const;
1922
1923     void CorrectEditorWidgetSizeX();
1924
1925     /** Called in RecalculateVirtualSize() to reposition control
1926         on virtual height changes.
1927     */
1928     void CorrectEditorWidgetPosY();
1929
1930     int DoDrawItems( wxDC& dc,
1931                      const wxRect* clipRect,
1932                      bool isBuffered ) const;
1933
1934     /** Draws an expand/collapse (ie. +/-) button.
1935     */
1936     virtual void DrawExpanderButton( wxDC& dc, const wxRect& rect,
1937                                      wxPGProperty* property ) const;
1938
1939     /** Draws items from topitemy to bottomitemy */
1940     void DrawItems( wxDC& dc, unsigned int topitemy, unsigned int bottomitemy,
1941                     const wxRect* clip_rect = (const wxRect*) NULL );
1942
1943     // Translate wxKeyEvent to wxPG_ACTION_XXX
1944     int KeyEventToActions(wxKeyEvent &event, int* pSecond) const;
1945
1946     int KeyEventToAction(wxKeyEvent &event) const
1947     {
1948         return KeyEventToActions(event, NULL);
1949     }
1950
1951     void ImprovedClientToScreen( int* px, int* py );
1952
1953     // Called by focus event handlers. newFocused is the window that becomes
1954     // focused.
1955     void HandleFocusChange( wxWindow* newFocused );
1956
1957     /** Reloads all non-customized colours from system settings. */
1958     void RegainColours();
1959
1960     bool DoEditorValidate();
1961
1962     // Similar to DoSelectProperty() but also works on columns
1963     // other than 1. Does not active editor if column is not
1964     // editable.
1965     bool DoSelectAndEdit( wxPGProperty* prop,
1966                           unsigned int colIndex,
1967                           unsigned int selFlags );
1968
1969     void DoSetSelection( const wxArrayPGProperty& newSelection,
1970                          int selFlags = 0 );
1971
1972     bool DoAddToSelection( wxPGProperty* prop,
1973                            int selFlags = 0 );
1974
1975     bool DoRemoveFromSelection( wxPGProperty* prop,
1976                                 int selFlags = 0 );
1977
1978     void DoBeginLabelEdit( unsigned int colIndex, int selFlags = 0 );
1979     void DoEndLabelEdit( bool commit, int selFlags = 0 );
1980     void OnLabelEditorEnterPress( wxCommandEvent& event );
1981     void OnLabelEditorKeyPress( wxKeyEvent& event );
1982
1983     wxPGProperty* DoGetItemAtY( int y ) const;
1984
1985     void DoSetSplitterPosition_( int newxpos,
1986                                  bool refresh = true,
1987                                  int splitterIndex = 0,
1988                                  bool allPages = false );
1989
1990     void DestroyEditorWnd( wxWindow* wnd );
1991     void FreeEditors();
1992
1993     virtual bool DoExpand( wxPGProperty* p, bool sendEvent = false );
1994
1995     virtual bool DoCollapse( wxPGProperty* p, bool sendEvent = false );
1996
1997     // Returns nearest paint visible property (such that will be painted unless
1998     // window is scrolled or resized). If given property is paint visible, then
1999     // it itself will be returned.
2000     wxPGProperty* GetNearestPaintVisible( wxPGProperty* p ) const;
2001
2002     static void RegisterDefaultEditors();
2003
2004     // Sets up basic event handling for child control
2005     void SetupChildEventHandling( wxWindow* wnd );
2006
2007     void CustomSetCursor( int type, bool override = false );
2008
2009     /**
2010         Repositions scrollbar and underlying panel according to changed virtual
2011         size.
2012     */
2013     void RecalculateVirtualSize( int forceXPos = -1 );
2014
2015     void PrepareAfterItemsAdded();
2016
2017     // Omit the wxPG_SEL_NOVALIDATE flag to allow vetoing the event
2018     bool SendEvent( int eventType, wxPGProperty* p,
2019                     wxVariant* pValue = NULL,
2020                     unsigned int selFlags = wxPG_SEL_NOVALIDATE,
2021                     unsigned int column = 1 );
2022
2023     void SetFocusOnCanvas();
2024
2025     bool DoHideProperty( wxPGProperty* p, bool hide, int flags );
2026
2027 private:
2028
2029     bool ButtonTriggerKeyTest( int action, wxKeyEvent& event );
2030
2031     DECLARE_EVENT_TABLE()
2032 #endif // #ifndef SWIG
2033 };
2034
2035 // -----------------------------------------------------------------------
2036 //
2037 // Bunch of inlines that need to resolved after all classes have been defined.
2038 //
2039
2040 #ifndef SWIG
2041 inline bool wxPropertyGridPageState::IsDisplayed() const
2042 {
2043     return ( this == m_pPropGrid->GetState() );
2044 }
2045
2046 inline unsigned int wxPropertyGridPageState::GetActualVirtualHeight() const
2047 {
2048     return DoGetRoot()->GetChildrenHeight(GetGrid()->GetRowHeight());
2049 }
2050 #endif
2051
2052 inline int wxPGProperty::GetDisplayedCommonValueCount() const
2053 {
2054     if ( HasFlag(wxPG_PROP_USES_COMMON_VALUE) )
2055     {
2056         wxPropertyGrid* pg = GetGrid();
2057         if ( pg )
2058             return (int) pg->GetCommonValueCount();
2059     }
2060     return 0;
2061 }
2062
2063 inline void wxPGProperty::SetDefaultValue( wxVariant& value )
2064 {
2065     SetAttribute(wxPG_ATTR_DEFAULT_VALUE, value);
2066 }
2067
2068 inline void wxPGProperty::SetEditor( const wxString& editorName )
2069 {
2070     m_customEditor = wxPropertyGridInterface::GetEditorByName(editorName);
2071 }
2072
2073 inline bool wxPGProperty::Hide( bool hide, int flags )
2074 {
2075     return GetGrid()->HideProperty(this, hide, flags);
2076 }
2077
2078 inline bool wxPGProperty::SetMaxLength( int maxLen )
2079 {
2080     return GetGrid()->SetPropertyMaxLength(this,maxLen);
2081 }
2082
2083 // -----------------------------------------------------------------------
2084
2085 #define wxPG_BASE_EVT_PRE_ID     1775
2086
2087 #ifndef SWIG
2088
2089 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID, wxEVT_PG_SELECTED, wxPropertyGridEvent );
2090 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID, wxEVT_PG_CHANGING, wxPropertyGridEvent );
2091 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID, wxEVT_PG_CHANGED, wxPropertyGridEvent );
2092 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID, wxEVT_PG_HIGHLIGHTED, wxPropertyGridEvent );
2093 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID, wxEVT_PG_RIGHT_CLICK, wxPropertyGridEvent );
2094 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID, wxEVT_PG_PAGE_CHANGED, wxPropertyGridEvent );
2095 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID, wxEVT_PG_ITEM_COLLAPSED, wxPropertyGridEvent );
2096 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID, wxEVT_PG_ITEM_EXPANDED, wxPropertyGridEvent );
2097 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID, wxEVT_PG_DOUBLE_CLICK, wxPropertyGridEvent );
2098 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID,
2099                           wxEVT_PG_LABEL_EDIT_BEGIN, wxPropertyGridEvent );
2100 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID,
2101                           wxEVT_PG_LABEL_EDIT_ENDING, wxPropertyGridEvent );
2102
2103 #else
2104     enum {
2105         wxEVT_PG_SELECTED = wxPG_BASE_EVT_PRE_ID,
2106         wxEVT_PG_CHANGING,
2107         wxEVT_PG_CHANGED,
2108         wxEVT_PG_HIGHLIGHTED,
2109         wxEVT_PG_RIGHT_CLICK,
2110         wxEVT_PG_PAGE_CHANGED,
2111         wxEVT_PG_ITEM_COLLAPSED,
2112         wxEVT_PG_ITEM_EXPANDED,
2113         wxEVT_PG_DOUBLE_CLICK,
2114         wxEVT_PG_LABEL_EDIT_BEGIN,
2115         wxEVT_PG_LABEL_EDIT_ENDING
2116     };
2117 #endif
2118
2119
2120 #define wxPG_BASE_EVT_TYPE       wxEVT_PG_SELECTED
2121 #define wxPG_MAX_EVT_TYPE        (wxPG_BASE_EVT_TYPE+30)
2122
2123
2124 #ifndef SWIG
2125 typedef void (wxEvtHandler::*wxPropertyGridEventFunction)(wxPropertyGridEvent&);
2126
2127 #define EVT_PG_SELECTED(id, fn)              DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_SELECTED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2128 #define EVT_PG_CHANGING(id, fn)              DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGING, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2129 #define EVT_PG_CHANGED(id, fn)               DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2130 #define EVT_PG_HIGHLIGHTED(id, fn)           DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_HIGHLIGHTED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2131 #define EVT_PG_RIGHT_CLICK(id, fn)           DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_RIGHT_CLICK, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2132 #define EVT_PG_DOUBLE_CLICK(id, fn)          DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_DOUBLE_CLICK, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2133 #define EVT_PG_PAGE_CHANGED(id, fn)          DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_PAGE_CHANGED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2134 #define EVT_PG_ITEM_COLLAPSED(id, fn)        DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_COLLAPSED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2135 #define EVT_PG_ITEM_EXPANDED(id, fn)         DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_EXPANDED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2136 #define EVT_PG_LABEL_EDIT_BEGIN(id, fn)      DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_LABEL_EDIT_BEGIN, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2137 #define EVT_PG_LABEL_EDIT_ENDING(id, fn)     DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_LABEL_EDIT_ENDING, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2138
2139 #define wxPropertyGridEventHandler(fn) \
2140     wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn )
2141
2142 #endif
2143
2144
2145 /** @class wxPropertyGridEvent
2146
2147     A propertygrid event holds information about events associated with
2148     wxPropertyGrid objects.
2149
2150     @library{wxpropgrid}
2151     @category{propgrid}
2152 */
2153 class WXDLLIMPEXP_PROPGRID wxPropertyGridEvent : public wxCommandEvent
2154 {
2155 public:
2156
2157     /** Constructor. */
2158     wxPropertyGridEvent(wxEventType commandType=0, int id=0);
2159 #ifndef SWIG
2160     /** Copy constructor. */
2161     wxPropertyGridEvent(const wxPropertyGridEvent& event);
2162 #endif
2163     /** Destructor. */
2164     ~wxPropertyGridEvent();
2165
2166     /** Copyer. */
2167     virtual wxEvent* Clone() const;
2168
2169     /**
2170         Returns the column index associated with this event.
2171     */
2172     unsigned int GetColumn() const
2173     {
2174         return m_column;
2175     }
2176
2177     wxPGProperty* GetMainParent() const
2178     {
2179         wxASSERT(m_property);
2180         return m_property->GetMainParent();
2181     }
2182
2183     /** Returns id of associated property. */
2184     wxPGProperty* GetProperty() const
2185     {
2186         return m_property;
2187     }
2188
2189     wxPGValidationInfo& GetValidationInfo()
2190     {
2191         wxASSERT(m_validationInfo);
2192         return *m_validationInfo;
2193     }
2194
2195     /** Returns true if you can veto the action that the event is signaling.
2196     */
2197     bool CanVeto() const { return m_canVeto; }
2198
2199     /**
2200         Call this from your event handler to veto action that the event is
2201         signaling.
2202
2203         You can only veto a shutdown if wxPropertyGridEvent::CanVeto returns
2204         true.
2205         @remarks
2206         Currently only wxEVT_PG_CHANGING supports vetoing.
2207     */
2208     void Veto( bool veto = true ) { m_wasVetoed = veto; }
2209
2210     /** Returns value that is about to be set for wxEVT_PG_CHANGING.
2211     */
2212     const wxVariant& GetValue() const
2213     {
2214         wxASSERT_MSG( m_validationInfo,
2215                       "Only call GetValue from a handler "
2216                       "of event type that supports it" );
2217         return m_validationInfo->GetValue();
2218     }
2219
2220     /**
2221         Set override validation failure behavior.
2222
2223         Only effective if Veto was also called, and only allowed if event type
2224         is wxEVT_PG_CHANGING.
2225     */
2226     void SetValidationFailureBehavior( wxPGVFBFlags flags )
2227     {
2228         wxASSERT( GetEventType() == wxEVT_PG_CHANGING );
2229         m_validationInfo->SetFailureBehavior( flags );
2230     }
2231
2232     /** Sets custom failure message for this time only. Only applies if
2233         wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
2234     */
2235     void SetValidationFailureMessage( const wxString& message )
2236     {
2237         wxASSERT( GetEventType() == wxEVT_PG_CHANGING );
2238         m_validationInfo->SetFailureMessage( message );
2239     }
2240
2241 #ifndef SWIG
2242     wxPGVFBFlags GetValidationFailureBehavior() const
2243     {
2244         wxASSERT( GetEventType() == wxEVT_PG_CHANGING );
2245         return m_validationInfo->GetFailureBehavior();
2246     }
2247
2248     void SetColumn( unsigned int column )
2249     {
2250         m_column = column;
2251     }
2252
2253     void SetCanVeto( bool canVeto ) { m_canVeto = canVeto; }
2254     bool WasVetoed() const { return m_wasVetoed; }
2255
2256     /** Changes the associated property. */
2257     void SetProperty( wxPGProperty* p ) { m_property = p; }
2258
2259     void SetPropertyGrid( wxPropertyGrid* pg ) { m_pg = pg; }
2260
2261     void SetupValidationInfo()
2262     {
2263         wxASSERT(m_pg);
2264         wxASSERT( GetEventType() == wxEVT_PG_CHANGING );
2265         m_validationInfo = &m_pg->GetValidationInfo();
2266     }
2267
2268 private:
2269     void Init();
2270     DECLARE_DYNAMIC_CLASS(wxPropertyGridEvent)
2271
2272     wxPGProperty*       m_property;
2273     wxPropertyGrid*     m_pg;
2274     wxPGValidationInfo* m_validationInfo;
2275
2276     unsigned int        m_column;
2277
2278     bool                m_canVeto;
2279     bool                m_wasVetoed;
2280
2281 #endif
2282 };
2283
2284
2285 // -----------------------------------------------------------------------
2286
2287 /** @class wxPropertyGridPopulator
2288     @ingroup classes
2289     Allows populating wxPropertyGrid from arbitrary text source.
2290 */
2291 class WXDLLIMPEXP_PROPGRID wxPropertyGridPopulator
2292 {
2293 public:
2294     /** Default constructor.
2295     */
2296     wxPropertyGridPopulator();
2297
2298     /** Destructor. */
2299     virtual ~wxPropertyGridPopulator();
2300
2301     void SetState( wxPropertyGridPageState* state );
2302
2303     void SetGrid( wxPropertyGrid* pg );
2304
2305     /** Appends a new property under bottommost parent.
2306         @param propClass
2307         Property class as string.
2308     */
2309     wxPGProperty* Add( const wxString& propClass,
2310                        const wxString& propLabel,
2311                        const wxString& propName,
2312                        const wxString* propValue,
2313                        wxPGChoices* pChoices = NULL );
2314
2315     /**
2316         Pushes property to the back of parent array (ie it becomes bottommost
2317         parent), and starts scanning/adding children for it.
2318
2319         When finished, parent array is returned to the original state.
2320     */
2321     void AddChildren( wxPGProperty* property );
2322
2323     /** Adds attribute to the bottommost property.
2324         @param type
2325         Allowed values: "string", (same as string), "int", "bool". Empty string
2326           mean autodetect.
2327     */
2328     bool AddAttribute( const wxString& name,
2329                        const wxString& type,
2330                        const wxString& value );
2331
2332     /** Called once in AddChildren.
2333     */
2334     virtual void DoScanForChildren() = 0;
2335
2336     /**
2337         Returns id of parent property for which children can currently be
2338         added.
2339      */
2340     wxPGProperty* GetCurParent() const
2341     {
2342         return (wxPGProperty*) m_propHierarchy[m_propHierarchy.size()-1];
2343     }
2344
2345     wxPropertyGridPageState* GetState() { return m_state; }
2346     const wxPropertyGridPageState* GetState() const { return m_state; }
2347
2348     /** Like wxString::ToLong, except allows N% in addition of N.
2349     */
2350     static bool ToLongPCT( const wxString& s, long* pval, long max );
2351
2352     /** Parses strings of format "choice1"[=value1] ... "choiceN"[=valueN] into
2353         wxPGChoices. Registers parsed result using idString (if not empty).
2354         Also, if choices with given id already registered, then don't parse but
2355         return those choices instead.
2356     */
2357     wxPGChoices ParseChoices( const wxString& choicesString,
2358                               const wxString& idString );
2359
2360     /** Implement in derived class to do custom process when an error occurs.
2361         Default implementation uses wxLogError.
2362     */
2363     virtual void ProcessError( const wxString& msg );
2364
2365 protected:
2366
2367     /** Used property grid. */
2368     wxPropertyGrid*         m_pg;
2369
2370     /** Used property grid state. */
2371     wxPropertyGridPageState*    m_state;
2372
2373     /** Tree-hierarchy of added properties (that can have children). */
2374     wxArrayPGProperty       m_propHierarchy;
2375
2376     /** Hashmap for string-id to wxPGChoicesData mapping. */
2377     wxPGHashMapS2P          m_dictIdChoices;
2378 };
2379
2380 // -----------------------------------------------------------------------
2381
2382 //
2383 // Undefine macros that are not needed outside propertygrid sources
2384 //
2385 #ifndef __wxPG_SOURCE_FILE__
2386     #undef wxPG_FL_DESC_REFRESH_REQUIRED
2387     #undef wxPG_FL_SCROLLBAR_DETECTED
2388     #undef wxPG_FL_CREATEDSTATE
2389     #undef wxPG_FL_NOSTATUSBARHELP
2390     #undef wxPG_FL_SCROLLED
2391     #undef wxPG_FL_FOCUS_INSIDE_CHILD
2392     #undef wxPG_FL_FOCUS_INSIDE
2393     #undef wxPG_FL_MOUSE_INSIDE_CHILD
2394     #undef wxPG_FL_CUR_USES_CUSTOM_IMAGE
2395     #undef wxPG_FL_PRIMARY_FILLS_ENTIRE
2396     #undef wxPG_FL_VALUE_MODIFIED
2397     #undef wxPG_FL_MOUSE_INSIDE
2398     #undef wxPG_FL_FOCUSED
2399     #undef wxPG_FL_MOUSE_CAPTURED
2400     #undef wxPG_FL_INITIALIZED
2401     #undef wxPG_FL_ACTIVATION_BY_CLICK
2402     #undef wxPG_FL_DONT_CENTER_SPLITTER
2403     #undef wxPG_SUPPORT_TOOLTIPS
2404     #undef wxPG_DOUBLE_BUFFER
2405     #undef wxPG_ICON_WIDTH
2406     #undef wxPG_USE_RENDERER_NATIVE
2407 // Following are needed by the manager headers
2408 //    #undef const wxString&
2409 #endif
2410
2411 // -----------------------------------------------------------------------
2412
2413 #endif
2414
2415 #endif // _WX_PROPGRID_PROPGRID_H_
2416