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