1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/propgrid/propgrid.h
3 // Purpose: wxPropertyGrid
4 // Author: Jaakko Salli
8 // Copyright: (c) Jaakko Salli
9 // Licence: wxWindows license
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_PROPGRID_PROPGRID_H_
13 #define _WX_PROPGRID_PROPGRID_H_
17 #include "wx/dcclient.h"
18 #include "wx/scrolwin.h"
19 #include "wx/tooltip.h"
20 #include "wx/datetime.h"
22 #include "wx/propgrid/property.h"
23 #include "wx/propgrid/propgridiface.h"
27 extern WXDLLIMPEXP_PROPGRID
const wxChar
*wxPropertyGridNameStr
;
31 // -----------------------------------------------------------------------
33 // -----------------------------------------------------------------------
37 // This is required for sharing common global variables.
38 class WXDLLIMPEXP_PROPGRID wxPGGlobalVarsClass
42 wxPGGlobalVarsClass();
43 ~wxPGGlobalVarsClass();
45 // Used by advprops, but here to make things easier.
46 wxString m_pDefaultImageWildcard
;
48 // Map of editor class instances (keys are name string).
49 wxPGHashMapS2P m_mapEditorClasses
;
52 wxArrayPtrVoid m_arrValidators
; // These wxValidators need to be freed
55 wxPGHashMapS2P m_dictPropertyClassInfo
; // PropertyName -> ClassInfo
57 wxPGChoices
* m_fontFamilyChoices
;
59 // Replace with your own to affect all properties using default renderer.
60 wxPGCellRenderer
* m_defaultRenderer
;
62 wxPGChoices m_boolChoices
;
64 wxVariant m_vEmptyString
;
66 wxVariant m_vMinusOne
;
70 // Cached constant strings
71 wxPGCachedString m_strstring
;
72 wxPGCachedString m_strlong
;
73 wxPGCachedString m_strbool
;
74 wxPGCachedString m_strlist
;
76 wxPGCachedString m_strMin
;
77 wxPGCachedString m_strMax
;
78 wxPGCachedString m_strUnits
;
79 wxPGCachedString m_strInlineHelp
;
81 // If true then some things are automatically translated
82 bool m_autoGetTranslation
;
84 // > 0 if errors cannot or should not be shown in statusbar etc.
87 int m_extraStyle
; // global extra style
93 int HasExtraStyle( int style
) const { return (m_extraStyle
& style
); }
96 extern WXDLLIMPEXP_PROPGRID wxPGGlobalVarsClass
* wxPGGlobalVars
;
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)
104 #define wxPGVariant_Bool(A) (A?wxPGVariant_True:wxPGVariant_False)
108 // -----------------------------------------------------------------------
110 /** @section propgrid_window_styles wxPropertyGrid Window Styles
112 SetWindowStyleFlag method can be used to modify some of these at run-time.
115 enum wxPG_WINDOW_STYLES
118 /** This will cause Sort() automatically after an item is added.
119 When inserting a lot of items in this mode, it may make sense to
120 use Freeze() before operations and Thaw() afterwards to increase
123 wxPG_AUTO_SORT
= 0x00000010,
125 /** Categories are not initially shown (even if added).
126 IMPORTANT NOTE: If you do not plan to use categories, then this
127 style will waste resources.
128 This flag can also be changed using wxPropertyGrid::EnableCategories method.
130 wxPG_HIDE_CATEGORIES
= 0x00000020,
132 /* This style combines non-categoric mode and automatic sorting.
134 wxPG_ALPHABETIC_MODE
= (wxPG_HIDE_CATEGORIES
|wxPG_AUTO_SORT
),
136 /** Modified values are shown in bold font. Changing this requires Refresh()
139 wxPG_BOLD_MODIFIED
= 0x00000040,
141 /** When wxPropertyGrid is resized, splitter moves to the center. This
142 behavior stops once the user manually moves the splitter.
144 wxPG_SPLITTER_AUTO_CENTER
= 0x00000080,
146 /** Display tooltips for cell text that cannot be shown completely. If
147 wxUSE_TOOLTIPS is 0, then this doesn't have any effect.
149 wxPG_TOOLTIPS
= 0x00000100,
151 /** Disables margin and hides all expand/collapse buttons that would appear
152 outside the margin (for sub-properties). Toggling this style automatically
153 expands all collapsed items.
155 wxPG_HIDE_MARGIN
= 0x00000200,
157 /** This style prevents user from moving the splitter.
159 wxPG_STATIC_SPLITTER
= 0x00000400,
161 /** Combination of other styles that make it impossible for user to modify
164 wxPG_STATIC_LAYOUT
= (wxPG_HIDE_MARGIN
|wxPG_STATIC_SPLITTER
),
166 /** Disables wxTextCtrl based editors for properties which
167 can be edited in another way.
169 Equals calling wxPropertyGrid::LimitPropertyEditing for all added
172 wxPG_LIMITED_EDITING
= 0x00000800,
174 /** wxPropertyGridManager only: Show toolbar for mode and page selection. */
175 wxPG_TOOLBAR
= 0x00001000,
177 /** wxPropertyGridManager only: Show adjustable text box showing description
178 or help text, if available, for currently selected property.
180 wxPG_DESCRIPTION
= 0x00002000
184 enum wxPG_EX_WINDOW_STYLES
188 NOTE: wxPG_EX_xxx are extra window styles and must be set using
189 SetExtraStyle() member function.
191 Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if
192 wxPG_HIDE_CATEGORIES is not defined, the non-categorized data storage is
193 not activated, and switching the mode first time becomes somewhat slower.
194 wxPG_EX_INIT_NOCAT activates the non-categorized data storage right away.
195 IMPORTANT NOTE: If you do plan not switching to non-categoric mode, or if
196 you don't plan to use categories at all, then using this style will result
197 in waste of resources.
200 wxPG_EX_INIT_NOCAT
= 0x00001000,
202 /** Extended window style that sets wxPropertyGridManager toolbar to not
205 wxPG_EX_NO_FLAT_TOOLBAR
= 0x00002000,
207 /** Shows alphabetic/categoric mode buttons from toolbar.
209 wxPG_EX_MODE_BUTTONS
= 0x00008000,
211 /** Show property help strings as tool tips instead as text on the status bar.
212 You can set the help strings using SetPropertyHelpString member function.
214 wxPG_EX_HELP_AS_TOOLTIPS
= 0x00010000,
216 /** Prevent TAB from focusing to wxButtons. This behavior was default
217 in version 1.2.0 and earlier.
218 NOTE! Tabbing to button doesn't work yet. Problem seems to be that on wxMSW
219 atleast the button doesn't properly propagate key events (yes, I'm using
222 //wxPG_EX_NO_TAB_TO_BUTTON = 0x00020000,
224 /** Allows relying on native double-buffering.
226 wxPG_EX_NATIVE_DOUBLE_BUFFERING
= 0x00080000,
228 /** Set this style to let user have ability to set values of properties to
229 unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for
232 wxPG_EX_AUTO_UNSPECIFIED_VALUES
= 0x00200000,
235 If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION
236 and wxPG_STRING_PASSWORD) are not stored into property's attribute storage
237 (thus they are not readable).
239 Note that this option is global, and applies to all wxPG property
242 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES
= 0x00400000,
245 With this style Validators on properties will work same as in
248 wxPG_EX_LEGACY_VALIDATORS
= 0x00800000,
250 /** Hides page selection buttons from toolbar.
252 wxPG_EX_HIDE_PAGE_BUTTONS
= 0x01000000
256 /** Combines various styles.
258 #define wxPG_DEFAULT_STYLE (0)
260 /** Combines various styles.
262 #define wxPGMAN_DEFAULT_STYLE (0)
267 // -----------------------------------------------------------------------
270 // Ids for sub-controls
271 // NB: It should not matter what these are.
272 #define wxPG_SUBID1 2
273 #define wxPG_SUBID2 3
274 #define wxPG_SUBID_TEMP1 4
276 // -----------------------------------------------------------------------
278 /** @class wxPGCommonValue
280 wxPropertyGrid stores information about common values in these
283 NB: Common value feature is not complete, and thus not mentioned in
286 class WXDLLIMPEXP_PROPGRID wxPGCommonValue
290 wxPGCommonValue( const wxString
& label
, wxPGCellRenderer
* renderer
)
293 m_renderer
= renderer
;
296 virtual ~wxPGCommonValue()
298 m_renderer
->DecRef();
301 virtual wxString
GetEditableText() const { return m_label
; }
302 const wxString
& GetLabel() const { return m_label
; }
303 wxPGCellRenderer
* GetRenderer() const { return m_renderer
; }
307 wxPGCellRenderer
* m_renderer
;
310 // -----------------------------------------------------------------------
312 /** @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
316 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
319 /** Prevents user from leaving property unless value is valid. If this
320 behavior flag is not used, then value change is instead cancelled.
322 wxPG_VFB_STAY_IN_PROPERTY
= 0x01,
324 /** Calls wxBell() on validation failure.
326 wxPG_VFB_BEEP
= 0x02,
328 /** Cell with invalid value will be marked (with red colour).
330 wxPG_VFB_MARK_CELL
= 0x04,
332 /** Display customizable text message explaining the situation.
334 wxPG_VFB_SHOW_MESSAGE
= 0x08,
337 wxPG_VFB_DEFAULT
= wxPG_VFB_STAY_IN_PROPERTY
|wxPG_VFB_BEEP
,
339 /** Only used internally. */
340 wxPG_VFB_UNDEFINED
= 0x80
347 typedef wxByte wxPGVFBFlags
;
349 /** @class wxPGValidationInfo
351 Used to convey validation information to and from functions that
352 actually perform validation.
354 struct wxPGValidationInfo
356 /** Value to be validated.
360 /** Message displayed on validation failure.
362 wxString m_failureMessage
;
364 /** Validation failure behavior. Use wxPG_VFB_XXX flags.
366 wxPGVFBFlags m_failureBehavior
;
368 wxPGVFBFlags
GetFailureBehavior() const { return m_failureBehavior
; }
370 void SetFailureBehavior(wxPGVFBFlags failureBehavior
)
371 { m_failureBehavior
= failureBehavior
; }
373 const wxString
& GetFailureMessage() const { return m_failureMessage
; }
375 void SetFailureMessage(const wxString
& message
)
376 { m_failureMessage
= message
; }
379 // -----------------------------------------------------------------------
381 /** @section propgrid_pgactions wxPropertyGrid Action Identifiers
383 These are used with wxPropertyGrid::AddActionTrigger() and
384 wxPropertyGrid::ClearActionTriggers().
388 enum wxPG_KEYBOARD_ACTIONS
390 wxPG_ACTION_INVALID
= 0,
391 wxPG_ACTION_NEXT_PROPERTY
,
392 wxPG_ACTION_PREV_PROPERTY
,
393 wxPG_ACTION_EXPAND_PROPERTY
,
394 wxPG_ACTION_COLLAPSE_PROPERTY
,
395 wxPG_ACTION_CANCEL_EDIT
,
405 // -----------------------------------------------------------------------
408 // wxPropertyGrid::DoSelectProperty flags (selFlags)
410 // Focuses to created editor
411 #define wxPG_SEL_FOCUS 0x01
412 // Forces deletion and recreation of editor
413 #define wxPG_SEL_FORCE 0x02
414 // For example, doesn't cause EnsureVisible
415 #define wxPG_SEL_NONVISIBLE 0x04
416 // Do not validate editor's value before selecting
417 #define wxPG_SEL_NOVALIDATE 0x08
418 // Property being deselected is about to be deleted
419 #define wxPG_SEL_DELETING 0x10
420 // Property's values was set to unspecified by the user
421 #define wxPG_SEL_SETUNSPEC 0x20
422 // Property's event handler changed the value
423 #define wxPG_SEL_DIALOGVAL 0x40
426 // -----------------------------------------------------------------------
431 #define wxPG_FL_INITIALIZED 0x0001
432 // Set when creating editor controls if it was clicked on.
433 #define wxPG_FL_ACTIVATION_BY_CLICK 0x0002
434 #define wxPG_FL_DONT_CENTER_SPLITTER 0x0004
435 #define wxPG_FL_FOCUSED 0x0008
436 #define wxPG_FL_MOUSE_CAPTURED 0x0010
437 #define wxPG_FL_MOUSE_INSIDE 0x0020
438 #define wxPG_FL_VALUE_MODIFIED 0x0040
439 // don't clear background of m_wndEditor
440 #define wxPG_FL_PRIMARY_FILLS_ENTIRE 0x0080
441 // currently active editor uses custom image
442 #define wxPG_FL_CUR_USES_CUSTOM_IMAGE 0x0100
443 // cell colours override selection colours for selected cell
444 #define wxPG_FL_CELL_OVERRIDES_SEL 0x0200
445 #define wxPG_FL_SCROLLED 0x0400
446 // set when all added/inserted properties get hideable flag
447 #define wxPG_FL_ADDING_HIDEABLES 0x0800
448 // Disables showing help strings on statusbar.
449 #define wxPG_FL_NOSTATUSBARHELP 0x1000
450 // Marks that we created the state, so we have to destroy it too.
451 #define wxPG_FL_CREATEDSTATE 0x2000
452 // Set if scrollbar's existence was detected in last onresize.
453 #define wxPG_FL_SCROLLBAR_DETECTED 0x4000
454 // Set if wxPGMan requires redrawing of description text box.
455 #define wxPG_FL_DESC_REFRESH_REQUIRED 0x8000
456 // Set if contained in wxPropertyGridManager
457 #define wxPG_FL_IN_MANAGER 0x00020000
458 // Set after wxPropertyGrid is shown in its initial good size
459 #define wxPG_FL_GOOD_SIZE_SET 0x00040000
460 // Next navigation key event will get ignored
461 #define wxPG_FL_IGNORE_NEXT_NAVKEY 0x00080000
462 // Set when in SelectProperty.
463 #define wxPG_FL_IN_SELECT_PROPERTY 0x00100000
464 // Set when help string is shown in status bar
465 #define wxPG_FL_STRING_IN_STATUSBAR 0x00200000
466 // Splitter position has been custom-set by the user
467 #define wxPG_FL_SPLITTER_PRE_SET 0x00400000
468 // Validation failed. Clear on modify event.
469 #define wxPG_FL_VALIDATION_FAILED 0x00800000
470 // Set if selected is fully painted (ie. both image and text)
471 //#define wxPG_FL_SELECTED_IS_FULL_PAINT 0x01000000
472 // Set after page has been inserted to manager
473 #define wxPG_MAN_FL_PAGE_INSERTED 0x02000000
474 // Active editor control is abnormally large
475 #define wxPG_FL_ABNORMAL_EDITOR 0x04000000
476 // Recursion guard for OnCustomEditorEvent
477 #define wxPG_FL_IN_ONCUSTOMEDITOREVENT 0x08000000
478 #define wxPG_FL_VALUE_CHANGE_IN_EVENT 0x10000000
479 // Editor control width should not change on resize
480 #define wxPG_FL_FIXED_WIDTH_EDITOR 0x20000000
481 // Width of panel can be different than width of grid
482 #define wxPG_FL_HAS_VIRTUAL_WIDTH 0x40000000
483 // Prevents RecalculateVirtualSize re-entrancy
484 #define wxPG_FL_RECALCULATING_VIRTUAL_SIZE 0x80000000
486 #endif // #ifndef SWIG
488 #if !defined(__wxPG_SOURCE_FILE__) && !defined(SWIG)
489 // Reduce compile time, but still include in user app
490 #include "wx/propgrid/props.h"
493 // -----------------------------------------------------------------------
495 /** @class wxPropertyGrid
497 wxPropertyGrid is a specialized grid for editing properties
498 such as strings, numbers, flagsets, fonts, and colours. wxPropertySheet
499 used to do the very same thing, but it hasn't been updated for a while
500 and it is currently deprecated.
502 Please note that most member functions are inherited and as such not
503 documented on this page. This means you will probably also want to read
504 wxPropertyGridInterface class reference.
506 See also @ref overview_propgrid.
508 @section propgrid_window_styles_ Window Styles
510 See @ref propgrid_window_styles.
512 @section propgrid_event_handling Event Handling
514 To process input from a propertygrid control, use these event handler
515 macros to direct input to member functions that take a wxPropertyGridEvent
518 @beginEventTable{wxPropertyGridEvent}
519 @event{EVT_PG_SELECTED (id, func)}
520 Respond to wxEVT_PG_SELECTED event, generated when property value
521 has been changed by user.
522 @event{EVT_PG_CHANGING(id, func)}
523 Respond to wxEVT_PG_CHANGING event, generated when property value
524 is about to be changed by user. Use wxPropertyGridEvent::GetValue()
525 to take a peek at the pending value, and wxPropertyGridEvent::Veto()
526 to prevent change from taking place, if necessary.
527 @event{EVT_PG_HIGHLIGHTED(id, func)}
528 Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
529 moves over a property. Event's property is NULL if hovered area does
530 not belong to any property.
531 @event{EVT_PG_RIGHT_CLICK(id, func)}
532 Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
533 clicked on with right mouse button.
534 @event{EVT_PG_DOUBLE_CLICK(id, func)}
535 Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
536 double-clicked onwith left mouse button.
537 @event{EVT_PG_ITEM_COLLAPSED(id, func)}
538 Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
539 a property or category..
540 @event{EVT_PG_ITEM_EXPANDED(id, func)}
541 Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
542 a property or category..
547 - Use Freeze() and Thaw() respectively to disable and enable drawing. This
548 will also delay sorting etc. miscellaneous calculations to the last
554 class WXDLLIMPEXP_PROPGRID
555 wxPropertyGrid
: public wxScrolledWindow
, public wxPropertyGridInterface
557 friend class wxPropertyGridPageState
;
558 friend class wxPropertyGridInterface
;
559 friend class wxPropertyGridManager
;
560 friend class wxPGCanvas
;
563 DECLARE_DYNAMIC_CLASS(wxPropertyGrid
)
568 %pythonAppend wxPropertyGrid
{
569 self
._setOORInfo(self
)
570 self
.DoDefaultTypeMappings()
571 self
.edited_objects
= {}
572 self
.DoDefaultValueTypeMappings()
573 if not hasattr(self
.__class__
,'_vt2setter'):
574 self
.__class__
._vt2setter
= {}
576 %pythonAppend
wxPropertyGrid() ""
578 wxPropertyGrid( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
579 const wxPoint
& pos
= wxDefaultPosition
,
580 const wxSize
& size
= wxDefaultSize
,
581 long style
= wxPG_DEFAULT_STYLE
,
582 const wxChar
* name
= wxPyPropertyGridNameStr
);
583 %RenameCtor
(PrePropertyGrid
, wxPropertyGrid());
587 Two step constructor.
589 Call Create when this constructor is called to build up the
594 /** The default constructor. The styles to be used are styles valid for
595 the wxWindow and wxScrolledWindow.
596 @see @link wndflags Additional Window Styles@endlink
598 wxPropertyGrid( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
599 const wxPoint
& pos
= wxDefaultPosition
,
600 const wxSize
& size
= wxDefaultSize
,
601 long style
= wxPG_DEFAULT_STYLE
,
602 const wxChar
* name
= wxPropertyGridNameStr
);
605 virtual ~wxPropertyGrid();
608 /** Adds given key combination to trigger given action.
610 Which action to trigger. See @link pgactions List of list of
611 wxPropertyGrid actions@endlink.
613 void AddActionTrigger( int action
, int keycode
, int modifiers
= 0 );
616 This static function enables or disables automatic use of
617 wxGetTranslation for following strings: wxEnumProperty list labels,
618 wxFlagsProperty sub-property labels.
622 static void AutoGetTranslation( bool enable
);
625 Changes value of a property, as if from an editor.
627 Use this instead of SetPropertyValue() if you need the value to run
628 through validation process, and also send the property change event.
631 Returns true if value was successfully changed.
633 bool ChangePropertyValue( wxPGPropArg id
, wxVariant newValue
);
636 Centers the splitter.
638 If argument is true, automatic splitter centering is enabled (only
639 applicapple if style wxPG_SPLITTER_AUTO_CENTER was defined).
641 void CenterSplitter( bool enable_auto_centering
= false );
643 /** Deletes all properties.
645 virtual void Clear();
647 /** Clears action triggers for given action.
649 Which action to trigger. See @link pgactions List of list of
650 wxPropertyGrid actions@endlink.
652 void ClearActionTriggers( int action
);
654 /** Forces updating the value of property from the editor control.
656 Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
657 ProcessEvent, meaning your event handlers will be called immediately.
660 Returns true if anything was changed.
662 virtual bool CommitChangesFromEditor( wxUint32 flags
= 0 );
667 Whenever the control is created without any parameters, use Create to
668 actually create it. Don't access the control's public methods before
669 this is called @see @link wndflags Additional Window Styles@endlink
671 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
672 const wxPoint
& pos
= wxDefaultPosition
,
673 const wxSize
& size
= wxDefaultSize
,
674 long style
= wxPG_DEFAULT_STYLE
,
675 const wxChar
* name
= wxPropertyGridNameStr
);
678 Call when editor widget's contents is modified.
680 For example, this is called when changes text in wxTextCtrl (used in
681 wxStringProperty and wxIntProperty).
684 This function should only be called by custom properties.
686 @see wxPGProperty::OnEvent()
688 void EditorsValueWasModified() { m_iFlags
|= wxPG_FL_VALUE_MODIFIED
; }
690 /** Reverse of EditorsValueWasModified().
693 This function should only be called by custom properties.
695 void EditorsValueWasNotModified()
697 m_iFlags
&= ~(wxPG_FL_VALUE_MODIFIED
);
701 Enables or disables (shows/hides) categories according to parameter
704 bool EnableCategories( bool enable
);
706 /** Scrolls and/or expands items to ensure that the given item is visible.
707 Returns true if something was actually done.
709 bool EnsureVisible( wxPGPropArg id
);
712 Reduces column sizes to minimum possible that contents are still
713 visibly (naturally some margin space will be applied as well).
716 Minimum size for the grid to still display everything.
719 Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
721 This function only works properly if grid size prior to call was already
724 Note that you can also get calculated column widths by calling
725 GetState->GetColumnWidth() immediately after this function returns.
729 wxSize sz
= m_pState
->DoFitColumns();
734 Returns wxWindow that the properties are painted on, and which should
735 be used as the parent for editor controls.
737 wxPanel
* GetPanel() const
742 /** Returns current category caption background colour. */
743 wxColour
GetCaptionBackgroundColour() const { return m_colCapBack
; }
745 wxFont
& GetCaptionFont() { return m_captionFont
; }
747 const wxFont
& GetCaptionFont() const { return m_captionFont
; }
749 /** Returns current category caption text colour. */
750 wxColour
GetCaptionForegroundColour() const { return m_colCapFore
; }
752 /** Returns current cell background colour. */
753 wxColour
GetCellBackgroundColour() const { return m_colPropBack
; }
755 /** Returns current cell text colour when disabled. */
756 wxColour
GetCellDisabledTextColour() const { return m_colDisPropFore
; }
758 /** Returns current cell text colour. */
759 wxColour
GetCellTextColour() const { return m_colPropFore
; }
761 /** Returns number of columns on current page. */
762 int GetColumnCount() const
764 return m_pState
->m_colWidths
.size();
767 /** Returns colour of empty space below properties. */
768 wxColour
GetEmptySpaceColour() const { return m_colEmptySpace
; }
770 /** Returns height of highest characters of used font. */
771 int GetFontHeight() const { return m_fontHeight
; }
773 /** Returns pointer to itself. Dummy function that enables same kind
774 of code to use wxPropertyGrid and wxPropertyGridManager.
776 wxPropertyGrid
* GetGrid() { return this; }
778 /** Returns rectangle of custom paint image.
780 wxRect
GetImageRect( wxPGProperty
* p
, int item
) const;
782 /** Returns size of the custom paint image in front of property.
783 If no argument is given, returns preferred size.
785 wxSize
GetImageSize( wxPGProperty
* p
= NULL
, int item
= -1 ) const;
788 /** Returns last item which could be iterated using given flags.
790 See @ref propgrid_iterator_flags.
792 wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
)
794 return m_pState
->GetLastItem(flags
);
797 const wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
) const
799 return m_pState
->GetLastItem(flags
);
803 /** Returns colour of lines between cells. */
804 wxColour
GetLineColour() const { return m_colLine
; }
806 /** Returns background colour of margin. */
807 wxColour
GetMarginColour() const { return m_colMargin
; }
809 /** Returns cell background colour of a property. */
810 wxColour
GetPropertyBackgroundColour( wxPGPropArg id
) const;
812 /** Returns cell background colour of a property. */
813 wxColour
GetPropertyTextColour( wxPGPropArg id
) const;
815 /** Returns "root property". It does not have name, etc. and it is not
816 visible. It is only useful for accessing its children.
818 wxPGProperty
* GetRoot() const { return m_pState
->m_properties
; }
820 /** Returns height of a single grid row (in pixels). */
821 int GetRowHeight() const { return m_lineHeight
; }
823 /** Returns currently selected property. */
824 wxPGProperty
* GetSelectedProperty () const { return GetSelection(); }
826 /** Returns currently selected property. */
827 wxPGProperty
* GetSelection() const
832 /** Returns current selection background colour. */
833 wxColour
GetSelectionBackgroundColour() const { return m_colSelBack
; }
835 /** Returns current selection text colour. */
836 wxColour
GetSelectionForegroundColour() const { return m_colSelFore
; }
838 /** Returns current splitter x position. */
839 int GetSplitterPosition() const
840 { return m_pState
->DoGetSplitterPosition(0); }
842 /** Returns wxTextCtrl active in currently selected property, if any. Takes
843 into account wxOwnerDrawnComboBox.
845 wxTextCtrl
* GetEditorTextCtrl() const;
847 wxPGValidationInfo
& GetValidationInfo()
849 return m_validationInfo
;
852 /** Returns current vertical spacing. */
853 int GetVerticalSpacing() const { return (int)m_vspacing
; }
855 /** Returns true if editor's value was marked modified.
857 bool IsEditorsValueModified() const
858 { return ( m_iFlags
& wxPG_FL_VALUE_MODIFIED
) ? true : false; }
860 /** Returns information about arbitrary position in the grid.
862 For wxPropertyGridHitTestResult definition, see
863 wxPropertyGridPageState::HitTest().
865 wxPropertyGridHitTestResult
HitTest( const wxPoint
& pt
) const;
867 /** Returns true if any property has been modified by the user. */
868 bool IsAnyModified() const { return (m_pState
->m_anyModified
>0); }
871 Returns true if updating is frozen (ie Freeze() called but not yet
874 bool IsFrozen() const { return (m_frozen
>0)?true:false; }
876 /** Redraws given property.
878 virtual void RefreshProperty( wxPGProperty
* p
);
881 /** Registers a new editor class.
883 Pointer to the editor class instance that should be used.
885 static wxPGEditor
* RegisterEditorClass( wxPGEditor
* editor
,
886 const wxString
& name
,
887 bool noDefCheck
= false );
890 /** Resets all colours to the original system values.
896 Editor widget is automatically created, but not focused unless focus is
897 true. This will generate wxEVT_PG_SELECT event.
901 True if selection finished successfully. Usually only fails if
902 current value in editor is not valid.
903 @see wxPropertyGrid::Unselect
905 bool SelectProperty( wxPGPropArg id
, bool focus
= false )
907 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
908 return DoSelectProperty(p
,focus
?wxPG_SEL_FOCUS
:0);
911 /** Changes keyboard shortcut to push the editor button.
913 You can set default with keycode 0. Good value for the platform is
914 guessed, but don't expect it to be very accurate.
916 void SetButtonShortcut( int keycode
,
917 bool ctrlDown
= false,
918 bool altDown
= false );
920 /** Sets category caption background colour. */
921 void SetCaptionBackgroundColour(const wxColour
& col
);
923 /** Sets category caption text colour. */
924 void SetCaptionTextColour(const wxColour
& col
);
926 /** Sets default cell background colour - applies to property cells.
927 Note that appearance of editor widgets may not be affected.
929 void SetCellBackgroundColour(const wxColour
& col
);
931 /** Sets cell text colour for disabled properties.
933 void SetCellDisabledTextColour(const wxColour
& col
);
935 /** Sets default cell text colour - applies to property name and value text.
936 Note that appearance of editor widgets may not be affected.
938 void SetCellTextColour(const wxColour
& col
);
940 /** Set number of columns (2 or more).
942 void SetColumnCount( int colCount
)
944 m_pState
->SetColumnCount(colCount
);
949 Sets the 'current' category - Append will add non-category properties
952 void SetCurrentCategory( wxPGPropArg id
)
954 wxPG_PROP_ARG_CALL_PROLOG()
955 wxPropertyCategory
* pc
= wxDynamicCast(p
, wxPropertyCategory
);
957 m_pState
->m_currentCategory
= pc
;
960 /** Sets colour of empty space below properties. */
961 void SetEmptySpaceColour(const wxColour
& col
);
963 /** Sets colour of lines between cells. */
964 void SetLineColour(const wxColour
& col
);
966 /** Sets background colour of margin. */
967 void SetMarginColour(const wxColour
& col
);
969 /** Sets property attribute for all applicapple properties.
970 Be sure to use this method only after all properties have been
973 void SetPropertyAttributeAll( const wxString
& attrName
, wxVariant value
);
975 /** Sets background colour of property and all its children. Colours of
976 captions are not affected. Background brush cache is optimized for often
977 set colours to be set last.
979 void SetPropertyBackgroundColour( wxPGPropArg id
, const wxColour
& col
);
981 /** Resets text and background colours of given property.
983 void SetPropertyColoursToDefault( wxPGPropArg id
);
985 /** Sets text colour of property and all its children.
987 void SetPropertyTextColour( wxPGPropArg id
,
989 bool recursively
= true );
992 Sets selection background colour - applies to selected property name
995 void SetSelectionBackgroundColour(const wxColour
& col
);
998 Sets selection foreground colour - applies to selected property name
1001 void SetSelectionTextColour(const wxColour
& col
);
1003 /** Sets x coordinate of the splitter.
1005 Splitter position cannot exceed grid size, and therefore setting it
1006 during form creation may fail as initial grid size is often smaller
1007 than desired splitter position, especially when sizers are being used.
1009 void SetSplitterPosition( int newxpos
, int col
= 0 )
1011 DoSetSplitterPosition_(newxpos
, true, col
);
1012 m_iFlags
|= wxPG_FL_SPLITTER_PRE_SET
;
1015 /** Set virtual width for this particular page. Width -1 indicates that the
1016 virtual width should be disabled. */
1017 void SetVirtualWidth( int width
);
1019 /** Sets name of a property.
1021 Name or pointer of property which name to change.
1025 void SetPropertyName( wxPGPropArg id
, const wxString
& newname
)
1027 wxPG_PROP_ARG_CALL_PROLOG()
1028 DoSetPropertyName( p
, newname
);
1031 /** Moves splitter as left as possible, while still allowing all
1032 labels to be shown in full.
1034 If false, will still allow sub-properties (ie. properties which
1035 parent is not root or category) to be cropped.
1037 void SetSplitterLeft( bool subProps
= false )
1039 m_pState
->SetSplitterLeft(subProps
);
1042 /** Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
1043 height. Value of 2 should be default on most platforms.
1045 On wxMSW, wxComboBox, when used as property editor widget, will spill
1046 out with anything less than 3.
1048 void SetVerticalSpacing( int vspacing
)
1050 m_vspacing
= (unsigned char)vspacing
;
1051 CalculateFontAndBitmapStuff( vspacing
);
1052 if ( !m_pState
->m_itemsAdded
) Refresh();
1055 /** Shows an brief error message that is related to a property. */
1056 void ShowPropertyError( wxPGPropArg id
, const wxString
& msg
)
1058 wxPG_PROP_ARG_CALL_PROLOG()
1059 DoShowPropertyError(p
, msg
);
1062 /** Sorts all items at all levels (except sub-properties). */
1065 /** Sorts children of a category.
1067 void SortChildren( wxPGPropArg id
);
1069 /////////////////////////////////////////////////////////////////
1071 // Following methods do not need to be (currently) documented
1073 /////////////////////////////////////////////////////////////////
1075 bool HasVirtualWidth() const
1076 { return (m_iFlags
& wxPG_FL_HAS_VIRTUAL_WIDTH
) ? true : false; }
1078 const wxPGCommonValue
* GetCommonValue( unsigned int i
) const
1080 return (wxPGCommonValue
*) m_commonValues
[i
];
1083 /** Returns number of common values.
1085 unsigned int GetCommonValueCount() const
1087 return m_commonValues
.size();
1090 /** Returns label of given common value.
1092 wxString
GetCommonValueLabel( unsigned int i
) const
1094 wxASSERT( GetCommonValue(i
) );
1095 return GetCommonValue(i
)->GetLabel();
1099 Returns index of common value that will truly change value to
1102 int GetUnspecifiedCommonValue() const { return m_cvUnspecified
; }
1104 /** Set index of common value that will truly change value to unspecified.
1105 Using -1 will set none to have such effect.
1108 void SetUnspecifiedCommonValue( int index
) { m_cvUnspecified
= index
; }
1111 Shortcut for creating dialog-caller button. Used, for example, by
1114 This should only be called by properties.
1116 wxWindow
* GenerateEditorButton( const wxPoint
& pos
, const wxSize
& sz
);
1118 /** Fixes position of wxTextCtrl-like control (wxSpinCtrl usually
1119 fits as one). Call after control has been created (but before
1122 void FixPosForTextCtrl( wxWindow
* ctrl
,
1123 const wxPoint
& offset
= wxPoint(0, 0) );
1125 /** Shortcut for creating text editor widget.
1127 Same as pos given for CreateEditor.
1129 Same as sz given for CreateEditor.
1131 Initial text for wxTextCtrl.
1133 If right-side control, such as button, also created, then create it
1134 first and pass it as this parameter.
1136 Extra style flags to pass for wxTextCtrl.
1138 Note that this should generally be called only by new classes derived
1141 wxWindow
* GenerateEditorTextCtrl( const wxPoint
& pos
,
1143 const wxString
& value
,
1144 wxWindow
* secondary
,
1148 /* Generates both textctrl and button.
1150 wxWindow
* GenerateEditorTextCtrlAndButton( const wxPoint
& pos
,
1151 const wxSize
& sz
, wxWindow
** psecondary
, int limited_editing
,
1152 wxPGProperty
* property
);
1154 /** Generates position for a widget editor dialog box.
1156 Property for which dialog is positioned.
1158 Known or over-approximated size of the dialog.
1160 Position for dialog.
1162 wxPoint
GetGoodEditorDialogPosition( wxPGProperty
* p
,
1165 // Converts escape sequences in src_str to newlines,
1166 // tabs, etc. and copies result to dst_str.
1167 static wxString
& ExpandEscapeSequences( wxString
& dst_str
,
1168 wxString
& src_str
);
1170 // Converts newlines, tabs, etc. in src_str to escape
1171 // sequences, and copies result to dst_str.
1172 static wxString
& CreateEscapeSequences( wxString
& dst_str
,
1173 wxString
& src_str
);
1176 Returns rectangle that fully contains properties between and including
1179 wxRect
GetPropertyRect( const wxPGProperty
* p1
,
1180 const wxPGProperty
* p2
) const;
1182 /** Returns pointer to current active primary editor control (NULL if none).
1184 If editor uses clipper window, pointer is returned to the actual
1185 editor, not the clipper.
1187 wxWindow
* GetEditorControl() const;
1189 /** Adjusts given position if topCtrlWnd is child of clipper window.
1191 bool AdjustPosForClipperWindow( wxWindow
* topCtrlWnd
, int* x
, int* y
);
1193 wxWindow
* GetPrimaryEditor() const
1195 return GetEditorControl();
1199 Returns pointer to current active secondary editor control (NULL if
1202 wxWindow
* GetEditorControlSecondary() const
1204 return m_wndEditor2
;
1210 Generates contents for string dst based on the contents of
1213 Format will be "(preDelim)str1(postDelim) (preDelim)str2(postDelim) and
1214 so on. Set flags to 1 inorder to convert backslashes to double-back-
1215 slashes and "(preDelims)"'s to "(preDelims)".
1217 static void ArrayStringToString( wxString
& dst
, const wxArrayString
& src
,
1218 wxChar preDelim
, wxChar postDelim
,
1221 // Mostly useful for page switching.
1222 void SwitchState( wxPropertyGridPageState
* pNewState
);
1224 /** Pass this function to Connect calls in propertyclass::CreateEditor.
1226 void OnCustomEditorEvent( wxCommandEvent
&event
);
1228 long GetInternalFlags() const { return m_iFlags
; }
1229 void SetInternalFlag( long flag
) { m_iFlags
|= flag
; }
1230 void ClearInternalFlag( long flag
) { m_iFlags
&= ~(flag
); }
1231 void IncFrozen() { m_frozen
++; }
1232 void DecFrozen() { m_frozen
--; }
1234 void OnComboItemPaint( wxPGCustomComboControl
* pCb
,int item
,wxDC
& dc
,
1235 wxRect
& rect
,int flags
);
1237 // Used by simple check box for keyboard navigation
1238 void SendNavigationKeyEvent( int dir
);
1240 /** Standardized double-to-string conversion.
1242 static void DoubleToString( wxString
& target
,
1246 wxString
* precTemplate
);
1249 Call this from wxPGProperty::OnEvent() to cause property value to be
1250 changed after the function returns (with true as return value).
1251 ValueChangeInEvent() must be used if you wish the application to be
1252 able to use wxEVT_PG_CHANGING to potentially veto the given value.
1254 void ValueChangeInEvent( wxVariant variant
)
1256 m_changeInEventValue
= variant
;
1257 m_iFlags
|= wxPG_FL_VALUE_CHANGE_IN_EVENT
;
1260 /** Returns true if given event is from first of an array of buttons
1261 (as can be in case when wxPGMultiButton is used).
1263 bool IsMainButtonEvent( const wxEvent
& event
)
1265 return (event
.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED
)
1266 && (m_wndSecId
== event
.GetId());
1269 /** Pending value is expected to be passed in PerformValidation().
1271 virtual bool DoPropertyChanged( wxPGProperty
* p
,
1272 unsigned int selFlags
= 0 );
1275 Runs all validation functionality (includes sending wxEVT_PG_CHANGING).
1276 Returns true if all tests passed.
1278 virtual bool PerformValidation( wxPGProperty
* p
, wxVariant
& pendingValue
);
1280 /** Called when validation for given property fails.
1282 Value which failed in validation.
1284 Return true if user is allowed to change to another property even
1285 if current has invalid value.
1287 To add your own validation failure behavior, override
1288 wxPropertyGrid::DoOnValidationFailure().
1290 bool OnValidationFailure( wxPGProperty
* property
, wxVariant
& invalidValue
)
1292 bool res
= DoOnValidationFailure(property
, invalidValue
);
1293 property
->SetFlag(wxPG_PROP_INVALID_VALUE
);
1297 /** Called to indicate property and editor has valid value now.
1299 void OnValidationFailureReset( wxPGProperty
* property
)
1301 if ( property
&& property
->HasFlag(wxPG_PROP_INVALID_VALUE
) )
1303 DoOnValidationFailureReset(property
);
1304 property
->ClearFlag(wxPG_PROP_INVALID_VALUE
);
1306 m_validationInfo
.m_failureMessage
.clear();
1309 /** Override in derived class to display error messages in custom manner
1310 (these message usually only result from validation failure).
1312 virtual void DoShowPropertyError( wxPGProperty
* property
,
1313 const wxString
& msg
);
1315 /** Override to customize property validation failure behavior.
1317 Value which failed in validation.
1319 Return true if user is allowed to change to another property even
1320 if current has invalid value.
1322 virtual bool DoOnValidationFailure( wxPGProperty
* property
,
1323 wxVariant
& invalidValue
);
1325 /** Override to customize resetting of property validation failure status.
1327 Property is guaranteed to have flag wxPG_PROP_INVALID_VALUE set.
1329 virtual void DoOnValidationFailureReset( wxPGProperty
* property
);
1331 int GetSpacingY() const { return m_spacingy
; }
1334 Must be called in wxPGEditor::CreateControls() if primary editor window
1335 is wxTextCtrl, just before textctrl is created.
1337 Initial text value of created wxTextCtrl.
1339 void SetupTextCtrlValue( const wxString text
) { m_prevTcValue
= text
; }
1342 Unfocuses or closes editor if one was open, but does not deselect
1345 bool UnfocusEditor();
1350 wxPropertyGridPageState used by the grid is created here.
1352 If grid is used in wxPropertyGridManager, there is no point overriding
1353 this - instead, set custom wxPropertyGridPage classes.
1355 virtual wxPropertyGridPageState
* CreateState() const;
1360 // Control font changer helper.
1361 void SetCurControlBoldFont();
1364 // Public methods for semi-public use
1365 // (not protected for optimization)
1367 bool DoSelectProperty( wxPGProperty
* p
, unsigned int flags
= 0 );
1369 // Overridden functions.
1370 virtual bool Destroy();
1371 virtual wxSize
DoGetBestSize() const;
1372 // Returns property at given y coordinate (relative to grid's top left).
1373 wxPGProperty
* GetItemAtY( int y
) const { return DoGetItemAtY(y
); }
1375 virtual void Refresh( bool eraseBackground
= true,
1376 const wxRect
*rect
= (const wxRect
*) NULL
);
1377 virtual bool SetFont( const wxFont
& font
);
1378 #if wxPG_SUPPORT_TOOLTIPS
1379 void SetToolTip( const wxString
& tipString
);
1381 virtual void Freeze();
1382 virtual void SetExtraStyle( long exStyle
);
1383 virtual void Thaw();
1388 #ifndef wxPG_ICON_WIDTH
1389 wxBitmap
*m_expandbmp
, *m_collbmp
;
1392 wxCursor
*m_cursorSizeWE
;
1394 /** wxWindow pointers to editor control(s). */
1395 wxWindow
*m_wndEditor
;
1396 wxWindow
*m_wndEditor2
;
1398 /** wxPGCanvas instance. */
1401 #if wxPG_DOUBLE_BUFFER
1402 wxBitmap
*m_doubleBuffer
;
1405 wxArrayPtrVoid
*m_windowsToDelete
;
1407 /** Local time ms when control was created. */
1408 wxLongLong m_timeCreated
;
1410 /** wxPGProperty::OnEvent can change value by setting this. */
1411 wxVariant m_changeInEventValue
;
1413 /** Id of m_wndEditor2, or its first child, if any. */
1416 /** Extra Y spacing between the items. */
1419 /** Control client area width; updated on resize. */
1422 /** Control client area height; updated on resize. */
1425 /** Current non-client width (needed when auto-centering). */
1428 /** Non-client width (auto-centering helper). */
1431 /** Previously recorded scroll start position. */
1435 The gutter spacing in front and back of the image.
1436 This determines the amount of spacing in front of each item
1440 /** Includes separator line. */
1443 /** Gutter*2 + image width. */
1446 // y spacing for expand/collapse button.
1447 int m_buttonSpacingY
;
1449 /** Extra margin for expanded sub-group items. */
1450 int m_subgroup_extramargin
;
1453 The image width of the [+] icon.
1455 This is also calculated in the gutter
1459 #ifndef wxPG_ICON_WIDTH
1462 The image height of the [+] icon.
1464 This is calculated as minimal size and to align
1469 /** Current cursor id. */
1473 This captionFont is made equal to the font of the wxScrolledWindow.
1475 As extra the bold face is set on it when this is wanted by the user
1478 wxFont m_captionFont
;
1480 int m_fontHeight
; // Height of the font.
1482 // Base keycode for triggering push button.
1483 int m_pushButKeyCode
;
1485 /** m_splitterx when drag began. */
1486 int m_startingSplitterX
;
1489 Index to splitter currently being dragged (0=one after the first
1492 int m_draggedSplitter
;
1494 /** Changed property, calculated in PerformValidation(). */
1495 wxPGProperty
* m_chgInfo_changedProperty
;
1498 Lowest property for which editing happened, but which does not have
1501 wxPGProperty
* m_chgInfo_baseChangedProperty
;
1503 /** Changed property value, calculated in PerformValidation(). */
1504 wxVariant m_chgInfo_pendingValue
;
1506 /** Passed to SetValue. */
1507 wxVariant m_chgInfo_valueList
;
1509 /** Validation information. */
1510 wxPGValidationInfo m_validationInfo
;
1512 /** Actions and keys that trigger them. */
1513 wxPGHashMapI2I m_actionTriggers
;
1519 /** Bits are used to indicate which colours are customized. */
1520 unsigned short m_coloursCustomized
;
1522 /** x - m_splitterx. */
1523 signed char m_dragOffset
;
1525 /** 0 = not dragging, 1 = drag just started, 2 = drag in progress */
1526 unsigned char m_dragStatus
;
1528 /** 0 = margin, 1 = label, 2 = value. */
1529 unsigned char m_mouseSide
;
1531 /** True when editor control is focused. */
1532 unsigned char m_editorFocused
;
1534 /** 1 if m_latsCaption is also the bottommost caption. */
1535 //unsigned char m_lastCaptionBottomnest;
1537 /** Set to 1 when graphics frozen. */
1538 unsigned char m_frozen
;
1540 unsigned char m_vspacing
;
1542 // Does triggering push button need Alt down?
1543 unsigned char m_pushButKeyCodeNeedsAlt
;
1545 // Does triggering push button need Ctrl down?
1546 unsigned char m_pushButKeyCodeNeedsCtrl
;
1548 // Used to track when Alt/Ctrl+Key was consumed.
1549 unsigned char m_keyComboConsumed
;
1551 /** 1 if in DoPropertyChanged() */
1552 unsigned char m_inDoPropertyChanged
;
1554 /** 1 if in CommitChangesFromEditor() */
1555 unsigned char m_inCommitChangesFromEditor
;
1557 /** 1 if in DoSelectProperty() */
1558 unsigned char m_inDoSelectProperty
;
1560 wxPGVFBFlags m_permanentValidationFailureBehavior
; // Set by app
1562 /** Internal flags - see wxPG_FL_XXX constants. */
1565 /** When drawing next time, clear this many item slots at the end. */
1566 int m_clearThisMany
;
1568 /** Pointer to selected property. Note that this is duplicated in
1569 m_state for better transiency between pages so that the selected
1570 item can be retained.
1572 wxPGProperty
* m_selected
;
1574 // pointer to property that has mouse hovering
1575 wxPGProperty
* m_propHover
;
1577 // EventObject for wxPropertyGridEvents
1578 wxWindow
* m_eventObject
;
1580 // What (global) window is currently focused (needed to resolve event
1582 wxWindow
* m_curFocused
;
1585 wxEvtHandler
* m_tlwHandler
;
1590 // y coordinate of property that mouse hovering
1592 // Which column's editor is selected (usually 1)?
1595 // x relative to splitter (needed for resize).
1598 // lines between cells
1600 // property labels and values are written in this colour
1601 wxColour m_colPropFore
;
1602 // or with this colour when disabled
1603 wxColour m_colDisPropFore
;
1604 // background for m_colPropFore
1605 wxColour m_colPropBack
;
1606 // text color for captions
1607 wxColour m_colCapFore
;
1608 // background color for captions
1609 wxColour m_colCapBack
;
1610 // foreground for selected property
1611 wxColour m_colSelFore
;
1612 // background for selected property (actually use background color when
1613 // control out-of-focus)
1614 wxColour m_colSelBack
;
1615 // background colour for margin
1616 wxColour m_colMargin
;
1617 // background colour for empty space below the grid
1618 wxColour m_colEmptySpace
;
1620 // NB: These *cannot* be moved to globals.
1622 // Array of background colour brushes.
1623 wxArrayPtrVoid m_arrBgBrushes
;
1624 // Array of foreground colours.
1625 wxArrayPtrVoid m_arrFgCols
;
1627 // labels when properties use common values
1628 wxArrayPtrVoid m_commonValues
;
1629 // Which cv selection really sets value to unspecified?
1630 int m_cvUnspecified
;
1632 // Used to skip excess text editor events
1633 wxString m_prevTcValue
;
1637 // Sets some members to defaults (called constructors).
1640 // Initializes some members (called by Create and complex constructor).
1643 void OnPaint(wxPaintEvent
&event
);
1645 // main event receivers
1646 void OnMouseMove( wxMouseEvent
&event
);
1647 void OnMouseMoveBottom( wxMouseEvent
&event
);
1648 void OnMouseClick( wxMouseEvent
&event
);
1649 void OnMouseRightClick( wxMouseEvent
&event
);
1650 void OnMouseDoubleClick( wxMouseEvent
&event
);
1651 void OnMouseUp( wxMouseEvent
&event
);
1652 void OnKey( wxKeyEvent
&event
);
1653 void OnKeyUp( wxKeyEvent
&event
);
1654 void OnNavigationKey( wxNavigationKeyEvent
& event
);
1655 void OnResize( wxSizeEvent
&event
);
1658 bool HandleMouseMove( int x
, unsigned int y
, wxMouseEvent
&event
);
1659 bool HandleMouseClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1660 bool HandleMouseRightClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1661 bool HandleMouseDoubleClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1662 bool HandleMouseUp( int x
, unsigned int y
, wxMouseEvent
&event
);
1663 void HandleKeyEvent( wxKeyEvent
&event
);
1664 // Handle TAB and ESCAPE in control
1665 bool HandleChildKey( wxKeyEvent
& event
);
1667 void OnMouseEntry( wxMouseEvent
&event
);
1669 void OnIdle( wxIdleEvent
&event
);
1670 void OnFocusEvent( wxFocusEvent
&event
);
1671 void OnChildFocusEvent( wxChildFocusEvent
& event
);
1673 bool OnMouseCommon( wxMouseEvent
&event
, int* px
, int *py
);
1674 bool OnMouseChildCommon( wxMouseEvent
&event
, int* px
, int *py
);
1676 // sub-control event handlers
1677 void OnMouseClickChild( wxMouseEvent
&event
);
1678 void OnMouseRightClickChild( wxMouseEvent
&event
);
1679 void OnMouseMoveChild( wxMouseEvent
&event
);
1680 void OnMouseUpChild( wxMouseEvent
&event
);
1681 void OnChildKeyDown( wxKeyEvent
&event
);
1682 void OnChildKeyUp( wxKeyEvent
&event
);
1684 void OnCaptureChange( wxMouseCaptureChangedEvent
&event
);
1686 void OnScrollEvent( wxScrollWinEvent
&event
);
1688 void OnSysColourChanged( wxSysColourChangedEvent
&event
);
1693 Adjust the centering of the bitmap icons (collapse / expand) when the
1694 caption font changes.
1696 They need to be centered in the middle of the font, so a bit of deltaY
1697 adjustment is needed. On entry, m_captionFont must be set to window
1698 font. It will be modified properly.
1700 void CalculateFontAndBitmapStuff( int vspacing
);
1702 wxRect
GetEditorWidgetRect( wxPGProperty
* p
, int column
) const;
1704 void CorrectEditorWidgetSizeX();
1706 /** Called in RecalculateVirtualSize() to reposition control
1707 on virtual height changes.
1709 void CorrectEditorWidgetPosY();
1713 void OnScreenNote( const wxChar
* format
, ... );
1716 /** Deselect current selection, if any. Returns true if success
1717 (ie. validator did not intercept). */
1718 bool DoClearSelection();
1720 int DoDrawItems( wxDC
& dc
,
1721 const wxPGProperty
* first_item
,
1722 const wxPGProperty
* last_item
,
1723 const wxRect
* clip_rect
,
1724 bool isBuffered
) const;
1726 void DoSetPropertyValueUnspecified( wxPGProperty
* p
);
1728 /** Draws an expand/collapse (ie. +/-) button.
1730 virtual void DrawExpanderButton( wxDC
& dc
, const wxRect
& rect
,
1731 wxPGProperty
* property
) const;
1733 /** Draws items from topitemy to bottomitemy */
1734 void DrawItems( wxDC
& dc
, unsigned int topitemy
, unsigned int bottomitemy
,
1735 const wxRect
* clip_rect
= (const wxRect
*) NULL
);
1737 void DrawItems( const wxPGProperty
* p1
, const wxPGProperty
* p2
);
1739 void DrawItem( wxPGProperty
* p
)
1744 virtual void DrawItemAndChildren( wxPGProperty
* p
);
1747 Draws item, children, and consequtive parents as long as category is
1750 void DrawItemAndValueRelated( wxPGProperty
* p
);
1752 // Translate wxKeyEvent to wxPG_ACTION_XXX
1753 int KeyEventToActions(wxKeyEvent
&event
, int* pSecond
) const;
1755 int KeyEventToAction(wxKeyEvent
&event
) const
1757 return KeyEventToActions(event
, NULL
);
1760 void ImprovedClientToScreen( int* px
, int* py
);
1762 // Called by focus event handlers. newFocused is the window that becomes
1764 void HandleFocusChange( wxWindow
* newFocused
);
1766 /** Reloads all non-customized colours from system settings. */
1767 void RegainColours();
1769 bool DoEditorValidate();
1771 wxPGProperty
* DoGetItemAtY( int y
) const;
1773 void DoSetSplitterPosition_( int newxpos
,
1774 bool refresh
= true,
1775 int splitterIndex
= 0,
1776 bool allPages
= false );
1780 virtual bool DoExpand( wxPGProperty
* p
, bool sendEvent
= false );
1782 virtual bool DoCollapse( wxPGProperty
* p
, bool sendEvent
= false );
1784 // Returns nearest paint visible property (such that will be painted unless
1785 // window is scrolled or resized). If given property is paint visible, then
1786 // it itself will be returned.
1787 wxPGProperty
* GetNearestPaintVisible( wxPGProperty
* p
) const;
1789 static void RegisterDefaultEditors();
1791 // Sets m_bgColIndex to this property and all its children.
1792 void SetBackgroundColourIndex( wxPGProperty
* p
, int index
);
1794 // Sets m_fgColIndex to this property and all its children.
1795 void SetTextColourIndex( wxPGProperty
* p
, int index
, int flags
);
1797 int CacheColour( const wxColour
& colour
);
1799 void DoSetPropertyName( wxPGProperty
* p
, const wxString
& newname
);
1801 // Setups event handling for child control
1802 void SetupEventHandling( wxWindow
* wnd
, int id
);
1804 void CustomSetCursor( int type
, bool override
= false );
1806 virtual bool ProcessEvent(wxEvent
& event
);
1807 virtual void SetWindowStyleFlag( long style
);
1810 Repositions scrollbar and underlying panel according to changed virtual
1813 void RecalculateVirtualSize( int forceXPos
= -1 );
1815 void PrepareAfterItemsAdded();
1817 bool SendEvent( int eventType
,
1819 wxVariant
* pValue
= NULL
,
1820 unsigned int selFlags
= 0 );
1822 bool DoHideProperty( wxPGProperty
* p
, bool hide
, int flags
);
1826 bool ButtonTriggerKeyTest( wxKeyEvent
&event
);
1828 #endif // DOXYGEN_SHOULD_SKIP_THIS
1831 DECLARE_EVENT_TABLE()
1832 #endif // #ifndef SWIG
1835 // -----------------------------------------------------------------------
1837 // Bunch of inlines that need to resolved after all classes have been defined.
1841 inline bool wxPropertyGridPageState::IsDisplayed() const
1843 return ( this == m_pPropGrid
->GetState() );
1846 inline unsigned int wxPropertyGridPageState::GetActualVirtualHeight() const
1848 return DoGetRoot()->GetChildrenHeight(GetGrid()->GetRowHeight());
1852 inline int wxPGProperty::GetDisplayedCommonValueCount() const
1854 if ( HasFlag(wxPG_PROP_USES_COMMON_VALUE
) )
1856 wxPropertyGrid
* pg
= GetGrid();
1858 return pg
->GetCommonValueCount();
1863 inline void wxPGProperty::SetEditor( const wxString
& editorName
)
1865 m_customEditor
= wxPropertyGridInterface::GetEditorByName(editorName
);
1868 inline void wxPGProperty::SetName( const wxString
& newName
)
1870 GetGrid()->SetPropertyName(this, newName
);
1873 inline bool wxPGProperty::Hide( bool hide
, int flags
)
1875 return GetGrid()->HideProperty(this, hide
, flags
);
1878 inline bool wxPGProperty::SetMaxLength( int maxLen
)
1880 return GetGrid()->SetPropertyMaxLength(this,maxLen
);
1883 // -----------------------------------------------------------------------
1888 #define wxPG_BASE_EVT_PRE_ID 1775
1890 BEGIN_DECLARE_EVENT_TYPES()
1891 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_SELECTED
, wxPG_BASE_EVT_PRE_ID
)
1892 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_CHANGING
, wxPG_BASE_EVT_PRE_ID
+1)
1893 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_CHANGED
, wxPG_BASE_EVT_PRE_ID
+2)
1894 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_HIGHLIGHTED
, wxPG_BASE_EVT_PRE_ID
+3)
1895 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_RIGHT_CLICK
, wxPG_BASE_EVT_PRE_ID
+4)
1896 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_PAGE_CHANGED
, wxPG_BASE_EVT_PRE_ID
+5)
1897 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_ITEM_COLLAPSED
, wxPG_BASE_EVT_PRE_ID
+6)
1898 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_ITEM_EXPANDED
, wxPG_BASE_EVT_PRE_ID
+7)
1899 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_DOUBLE_CLICK
, wxPG_BASE_EVT_PRE_ID
+8)
1900 END_DECLARE_EVENT_TYPES()
1903 wxEVT_PG_SELECTED
= wxPG_BASE_EVT_PRE_ID
,
1906 wxEVT_PG_HIGHLIGHTED
,
1907 wxEVT_PG_RIGHT_CLICK
,
1908 wxEVT_PG_PAGE_CHANGED
,
1909 wxEVT_PG_ITEM_COLLAPSED
,
1910 wxEVT_PG_ITEM_EXPANDED
,
1911 wxEVT_PG_DOUBLE_CLICK
1916 #define wxPG_BASE_EVT_TYPE wxEVT_PG_SELECTED
1917 #define wxPG_MAX_EVT_TYPE (wxPG_BASE_EVT_TYPE+30)
1921 typedef void (wxEvtHandler::*wxPropertyGridEventFunction
)(wxPropertyGridEvent
&);
1923 #define EVT_PG_SELECTED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_SELECTED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1924 #define EVT_PG_CHANGING(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGING, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1925 #define EVT_PG_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1926 #define EVT_PG_HIGHLIGHTED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_HIGHLIGHTED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1927 #define EVT_PG_RIGHT_CLICK(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_RIGHT_CLICK, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1928 #define EVT_PG_DOUBLE_CLICK(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_DOUBLE_CLICK, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1929 #define EVT_PG_PAGE_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_PAGE_CHANGED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1930 #define EVT_PG_ITEM_COLLAPSED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_COLLAPSED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1931 #define EVT_PG_ITEM_EXPANDED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_EXPANDED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1933 #define wxPropertyGridEventHandler(A) \
1934 ((wxObjectEventFunction)(wxEventFunction)(wxPropertyGridEventFunction)&A)
1939 /** @class wxPropertyGridEvent
1941 A propertygrid event holds information about events associated with
1942 wxPropertyGrid objects.
1944 @library{wxpropgrid}
1947 class WXDLLIMPEXP_PROPGRID wxPropertyGridEvent
: public wxCommandEvent
1952 wxPropertyGridEvent(wxEventType commandType
=0, int id
=0);
1954 /** Copy constructor. */
1955 wxPropertyGridEvent(const wxPropertyGridEvent
& event
);
1958 ~wxPropertyGridEvent();
1961 virtual wxEvent
* Clone() const;
1963 wxPGProperty
* GetMainParent() const
1965 wxASSERT(m_property
);
1966 return m_property
->GetMainParent();
1969 /** Returns id of associated property. */
1970 wxPGProperty
* GetProperty() const
1975 wxPGValidationInfo
& GetValidationInfo()
1977 wxASSERT(m_validationInfo
);
1978 return *m_validationInfo
;
1981 /** Returns true if event has associated property. */
1982 bool HasProperty() const { return ( m_property
!= (wxPGProperty
*) NULL
); }
1984 /** Returns true if you can veto the action that the event is signaling.
1986 bool CanVeto() const { return m_canVeto
; }
1989 Call this from your event handler to veto action that the event is
1992 You can only veto a shutdown if wxPropertyGridEvent::CanVeto returns
1995 Currently only wxEVT_PG_CHANGING supports vetoing.
1997 void Veto( bool veto
= true ) { m_wasVetoed
= veto
; }
1999 /** Returns value that is about to be set for wxEVT_PG_CHANGING.
2001 const wxVariant
& GetValue() const
2003 wxASSERT_MSG( m_validationInfo
,
2004 "Only call GetValue from a handler "
2005 "of event type that supports it" );
2006 return *m_validationInfo
->m_pValue
;
2010 Set override validation failure behavior.
2012 Only effective if Veto was also called, and only allowed if event type
2013 is wxEVT_PG_CHANGING.
2015 void SetValidationFailureBehavior( int flags
)
2017 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2018 m_validationInfo
->m_failureBehavior
= (wxPGVFBFlags
) flags
;
2021 /** Sets custom failure message for this time only. Only applies if
2022 wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
2024 void SetValidationFailureMessage( const wxString
& message
)
2026 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2027 m_validationInfo
->m_failureMessage
= message
;
2031 wxPGVFBFlags
GetValidationFailureBehavior() const
2033 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2034 return m_validationInfo
->m_failureBehavior
;
2037 void SetCanVeto( bool canVeto
) { m_canVeto
= canVeto
; }
2038 bool WasVetoed() const { return m_wasVetoed
; }
2040 /** Changes the associated property. */
2041 void SetProperty( wxPGProperty
* p
) { m_property
= p
; }
2043 void SetPropertyGrid( wxPropertyGrid
* pg
) { m_pg
= pg
; }
2045 void SetupValidationInfo()
2048 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2049 m_validationInfo
= &m_pg
->GetValidationInfo();
2054 DECLARE_DYNAMIC_CLASS(wxPropertyGridEvent
)
2056 wxPGProperty
* m_property
;
2057 wxPropertyGrid
* m_pg
;
2058 wxPGValidationInfo
* m_validationInfo
;
2067 // -----------------------------------------------------------------------
2069 /** @class wxPropertyGridPopulator
2071 Allows populating wxPropertyGrid from arbitrary text source.
2073 class WXDLLIMPEXP_PROPGRID wxPropertyGridPopulator
2076 /** Default constructor.
2078 wxPropertyGridPopulator();
2081 virtual ~wxPropertyGridPopulator();
2083 void SetState( wxPropertyGridPageState
* state
);
2085 void SetGrid( wxPropertyGrid
* pg
);
2087 /** Appends a new property under bottommost parent.
2089 Property class as string.
2091 wxPGProperty
* Add( const wxString
& propClass
,
2092 const wxString
& propLabel
,
2093 const wxString
& propName
,
2094 const wxString
* propValue
,
2095 wxPGChoices
* pChoices
= NULL
);
2098 Pushes property to the back of parent array (ie it becomes bottommost
2099 parent), and starts scanning/adding children for it.
2101 When finished, parent array is returned to the original state.
2103 void AddChildren( wxPGProperty
* property
);
2105 /** Adds attribute to the bottommost property.
2107 Allowed values: "string", (same as string), "int", "bool". Empty string
2110 bool AddAttribute( const wxString
& name
,
2111 const wxString
& type
,
2112 const wxString
& value
);
2114 /** Called once in AddChildren.
2116 virtual void DoScanForChildren() = 0;
2119 Returns id of parent property for which children can currently be
2122 wxPGProperty
* GetCurParent() const
2124 return (wxPGProperty
*) m_propHierarchy
[m_propHierarchy
.size()-1];
2127 wxPropertyGridPageState
* GetState() { return m_state
; }
2128 const wxPropertyGridPageState
* GetState() const { return m_state
; }
2130 /** Like wxString::ToLong, except allows N% in addition of N.
2132 static bool ToLongPCT( const wxString
& s
, long* pval
, long max
);
2134 /** Parses strings of format "choice1"[=value1] ... "choiceN"[=valueN] into
2135 wxPGChoices. Registers parsed result using idString (if not empty).
2136 Also, if choices with given id already registered, then don't parse but
2137 return those choices instead.
2139 wxPGChoices
ParseChoices( const wxString
& choicesString
,
2140 const wxString
& idString
);
2142 /** Implement in derived class to do custom process when an error occurs.
2143 Default implementation uses wxLogError.
2145 virtual void ProcessError( const wxString
& msg
);
2149 /** Used property grid. */
2150 wxPropertyGrid
* m_pg
;
2152 /** Used property grid state. */
2153 wxPropertyGridPageState
* m_state
;
2155 /** Tree-hierarchy of added properties (that can have children). */
2156 wxArrayPGProperty m_propHierarchy
;
2158 /** Hashmap for string-id to wxPGChoicesData mapping. */
2159 wxPGHashMapS2P m_dictIdChoices
;
2162 // -----------------------------------------------------------------------
2165 // Undefine macros that are not needed outside propertygrid sources
2167 #ifndef __wxPG_SOURCE_FILE__
2168 #undef wxPG_FL_DESC_REFRESH_REQUIRED
2169 #undef wxPG_FL_SCROLLBAR_DETECTED
2170 #undef wxPG_FL_CREATEDSTATE
2171 #undef wxPG_FL_NOSTATUSBARHELP
2172 #undef wxPG_FL_SCROLLED
2173 #undef wxPG_FL_FOCUS_INSIDE_CHILD
2174 #undef wxPG_FL_FOCUS_INSIDE
2175 #undef wxPG_FL_MOUSE_INSIDE_CHILD
2176 #undef wxPG_FL_CUR_USES_CUSTOM_IMAGE
2177 #undef wxPG_FL_PRIMARY_FILLS_ENTIRE
2178 #undef wxPG_FL_VALUE_MODIFIED
2179 #undef wxPG_FL_MOUSE_INSIDE
2180 #undef wxPG_FL_FOCUSED
2181 #undef wxPG_FL_MOUSE_CAPTURED
2182 #undef wxPG_FL_INITIALIZED
2183 #undef wxPG_FL_ACTIVATION_BY_CLICK
2184 #undef wxPG_FL_DONT_CENTER_SPLITTER
2185 #undef wxPG_SUPPORT_TOOLTIPS
2186 #undef wxPG_DOUBLE_BUFFER
2187 #undef wxPG_ICON_WIDTH
2188 #undef wxPG_USE_RENDERER_NATIVE
2189 // Following are needed by the manager headers
2190 // #undef const wxString&
2195 #include "wx/propgrid/editor.h"
2196 #include "wx/propgrid/manager.h"
2199 // -----------------------------------------------------------------------
2203 #endif // _WX_PROPGRID_PROPGRID_H_