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