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