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_
15 #include "wx/dcclient.h"
16 #include "wx/scrolwin.h"
17 #include "wx/tooltip.h"
18 #include "wx/datetime.h"
20 #include "wx/propgrid/property.h"
21 #include "wx/propgrid/propgridiface.h"
25 extern WXDLLIMPEXP_PROPGRID
const wxChar
*wxPropertyGridNameStr
;
29 // -----------------------------------------------------------------------
31 // -----------------------------------------------------------------------
35 // This is required for sharing common global variables.
36 class WXDLLIMPEXP_PROPGRID wxPGGlobalVarsClass
40 wxPGGlobalVarsClass();
41 ~wxPGGlobalVarsClass();
43 // Used by advprops, but here to make things easier.
44 wxString m_pDefaultImageWildcard
;
46 // Map of editor class instances (keys are name string).
47 wxPGHashMapS2P m_mapEditorClasses
;
50 wxArrayPtrVoid m_arrValidators
; // These wxValidators need to be freed
53 wxPGHashMapS2P m_dictPropertyClassInfo
; // PropertyName -> ClassInfo
55 wxPGChoices
* m_fontFamilyChoices
;
57 // Replace with your own to affect all properties using default renderer.
58 wxPGCellRenderer
* m_defaultRenderer
;
60 // These are for fast variant type comparison
61 wxPGVariantDataClassInfo wxVariantClassInfo_long
;
62 wxPGVariantDataClassInfo wxVariantClassInfo_string
;
63 wxPGVariantDataClassInfo wxVariantClassInfo_double
;
64 wxPGVariantDataClassInfo wxVariantClassInfo_bool
;
65 wxPGVariantDataClassInfo wxVariantClassInfo_arrstring
;
66 wxPGVariantDataClassInfo wxVariantClassInfo_wxobject
;
67 wxPGVariantDataClassInfo wxVariantClassInfo_list
;
68 wxPGVariantDataClassInfo wxVariantClassInfo_wxColour
;
70 wxPGVariantDataClassInfo wxVariantClassInfo_datetime
;
73 wxPGChoices m_boolChoices
;
75 wxVariant m_vEmptyString
;
77 wxVariant m_vMinusOne
;
81 // Cached constant strings
82 wxPGCachedString m_strMin
;
83 wxPGCachedString m_strMax
;
84 wxPGCachedString m_strUnits
;
85 wxPGCachedString m_strInlineHelp
;
87 // If true then some things are automatically translated
88 bool m_autoGetTranslation
;
90 // > 0 if errors cannot or should not be shown in statusbar etc.
93 int m_extraStyle
; // global extra style
99 int HasExtraStyle( int style
) const { return (m_extraStyle
& style
); }
102 extern WXDLLIMPEXP_PROPGRID wxPGGlobalVarsClass
* wxPGGlobalVars
;
104 #define wxPGIsVariantType(VARIANT, T) \
105 ((VARIANT).GetData() && \
106 typeid(*(VARIANT).GetData()) == *wxPGGlobalVars->wxVariantClassInfo_##T)
108 #define wxPGIsVariantClassInfo(CLASSINFO, T) \
109 (*CLASSINFO == *wxPGGlobalVars->wxVariantClassInfo_##T)
111 #define wxPGVariant_EmptyString (wxPGGlobalVars->m_vEmptyString)
112 #define wxPGVariant_Zero (wxPGGlobalVars->m_vZero)
113 #define wxPGVariant_MinusOne (wxPGGlobalVars->m_vMinusOne)
114 #define wxPGVariant_True (wxPGGlobalVars->m_vTrue)
115 #define wxPGVariant_False (wxPGGlobalVars->m_vFalse)
117 #define wxPGVariant_Bool(A) (A?wxPGVariant_True:wxPGVariant_False)
119 #define wxPGVariantAssign(A, B) A = B
123 // -----------------------------------------------------------------------
125 /** @section propgrid_window_styles wxPropertyGrid Window Styles
127 SetWindowStyleFlag method can be used to modify some of these at run-time.
130 enum wxPG_WINDOW_STYLES
133 /** This will cause Sort() automatically after an item is added.
134 When inserting a lot of items in this mode, it may make sense to
135 use Freeze() before operations and Thaw() afterwards to increase
138 wxPG_AUTO_SORT
= 0x00000010,
140 /** Categories are not initially shown (even if added).
141 IMPORTANT NOTE: If you do not plan to use categories, then this
142 style will waste resources.
143 This flag can also be changed using wxPropertyGrid::EnableCategories method.
145 wxPG_HIDE_CATEGORIES
= 0x00000020,
147 /* This style combines non-categoric mode and automatic sorting.
149 wxPG_ALPHABETIC_MODE
= (wxPG_HIDE_CATEGORIES
|wxPG_AUTO_SORT
),
151 /** Modified values are shown in bold font. Changing this requires Refresh()
154 wxPG_BOLD_MODIFIED
= 0x00000040,
156 /** When wxPropertyGrid is resized, splitter moves to the center. This
157 behavior stops once the user manually moves the splitter.
159 wxPG_SPLITTER_AUTO_CENTER
= 0x00000080,
161 /** Display tooltips for cell text that cannot be shown completely. If
162 wxUSE_TOOLTIPS is 0, then this doesn't have any effect.
164 wxPG_TOOLTIPS
= 0x00000100,
166 /** Disables margin and hides all expand/collapse buttons that would appear
167 outside the margin (for sub-properties). Toggling this style automatically
168 expands all collapsed items.
170 wxPG_HIDE_MARGIN
= 0x00000200,
172 /** This style prevents user from moving the splitter.
174 wxPG_STATIC_SPLITTER
= 0x00000400,
176 /** Combination of other styles that make it impossible for user to modify
179 wxPG_STATIC_LAYOUT
= (wxPG_HIDE_MARGIN
|wxPG_STATIC_SPLITTER
),
181 /** Disables wxTextCtrl based editors for properties which
182 can be edited in another way.
184 Equals calling wxPropertyGrid::LimitPropertyEditing for all added
187 wxPG_LIMITED_EDITING
= 0x00000800,
189 /** wxPropertyGridManager only: Show toolbar for mode and page selection. */
190 wxPG_TOOLBAR
= 0x00001000,
192 /** wxPropertyGridManager only: Show adjustable text box showing description
193 or help text, if available, for currently selected property.
195 wxPG_DESCRIPTION
= 0x00002000
199 enum wxPG_EX_WINDOW_STYLES
203 NOTE: wxPG_EX_xxx are extra window styles and must be set using
204 SetExtraStyle() member function.
206 Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if
207 wxPG_HIDE_CATEGORIES is not defined, the non-categorized data storage is
208 not activated, and switching the mode first time becomes somewhat slower.
209 wxPG_EX_INIT_NOCAT activates the non-categorized data storage right away.
210 IMPORTANT NOTE: If you do plan not switching to non-categoric mode, or if
211 you don't plan to use categories at all, then using this style will result
212 in waste of resources.
215 wxPG_EX_INIT_NOCAT
= 0x00001000,
217 /** Extended window style that sets wxPropertyGridManager toolbar to not
220 wxPG_EX_NO_FLAT_TOOLBAR
= 0x00002000,
222 /** Shows alphabetic/categoric mode buttons from toolbar.
224 wxPG_EX_MODE_BUTTONS
= 0x00008000,
226 /** Show property help strings as tool tips instead as text on the status bar.
227 You can set the help strings using SetPropertyHelpString member function.
229 wxPG_EX_HELP_AS_TOOLTIPS
= 0x00010000,
231 /** Prevent TAB from focusing to wxButtons. This behavior was default
232 in version 1.2.0 and earlier.
233 NOTE! Tabbing to button doesn't work yet. Problem seems to be that on wxMSW
234 atleast the button doesn't properly propagate key events (yes, I'm using
237 //wxPG_EX_NO_TAB_TO_BUTTON = 0x00020000,
239 /** Allows relying on native double-buffering.
241 wxPG_EX_NATIVE_DOUBLE_BUFFERING
= 0x00080000,
243 /** Set this style to let user have ability to set values of properties to
244 unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for
247 wxPG_EX_AUTO_UNSPECIFIED_VALUES
= 0x00200000,
250 If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION
251 and wxPG_STRING_PASSWORD) are not stored into property's attribute storage
252 (thus they are not readable).
254 Note that this option is global, and applies to all wxPG property
257 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES
= 0x00400000,
260 With this style Validators on properties will work same as in
263 wxPG_EX_LEGACY_VALIDATORS
= 0x00800000,
265 /** Hides page selection buttons from toolbar.
267 wxPG_EX_HIDE_PAGE_BUTTONS
= 0x01000000
271 /** Combines various styles.
273 #define wxPG_DEFAULT_STYLE (0)
275 /** Combines various styles.
277 #define wxPGMAN_DEFAULT_STYLE (0)
282 // -----------------------------------------------------------------------
285 // Ids for sub-controls
286 // NB: It should not matter what these are.
287 #define wxPG_SUBID1 2
288 #define wxPG_SUBID2 3
289 #define wxPG_SUBID_TEMP1 4
291 // -----------------------------------------------------------------------
293 /** @class wxPGCommonValue
295 wxPropertyGrid stores information about common values in these
298 NB: Common value feature is not complete, and thus not mentioned in
301 class WXDLLIMPEXP_PROPGRID wxPGCommonValue
305 wxPGCommonValue( const wxString
& label
, wxPGCellRenderer
* renderer
)
308 m_renderer
= renderer
;
311 virtual ~wxPGCommonValue()
313 m_renderer
->DecRef();
316 virtual wxString
GetEditableText() const { return m_label
; }
317 const wxString
& GetLabel() const { return m_label
; }
318 wxPGCellRenderer
* GetRenderer() const { return m_renderer
; }
322 wxPGCellRenderer
* m_renderer
;
325 // -----------------------------------------------------------------------
327 /** @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
331 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
334 /** Prevents user from leaving property unless value is valid. If this
335 behavior flag is not used, then value change is instead cancelled.
337 wxPG_VFB_STAY_IN_PROPERTY
= 0x01,
339 /** Calls wxBell() on validation failure.
341 wxPG_VFB_BEEP
= 0x02,
343 /** Cell with invalid value will be marked (with red colour).
345 wxPG_VFB_MARK_CELL
= 0x04,
347 /** Display customizable text message explaining the situation.
349 wxPG_VFB_SHOW_MESSAGE
= 0x08,
352 wxPG_VFB_DEFAULT
= wxPG_VFB_STAY_IN_PROPERTY
|wxPG_VFB_BEEP
,
354 /** Only used internally. */
355 wxPG_VFB_UNDEFINED
= 0x80
362 typedef wxByte wxPGVFBFlags
;
364 /** @class wxPGValidationInfo
366 Used to convey validation information to and from functions that
367 actually perform validation.
369 struct wxPGValidationInfo
371 /** Value to be validated.
375 /** Message displayed on validation failure.
377 wxString m_failureMessage
;
379 /** Validation failure behavior. Use wxPG_VFB_XXX flags.
381 wxPGVFBFlags m_failureBehavior
;
383 wxPGVFBFlags
GetFailureBehavior() const { return m_failureBehavior
; }
385 void SetFailureBehavior(wxPGVFBFlags failureBehavior
)
386 { m_failureBehavior
= failureBehavior
; }
388 const wxString
& GetFailureMessage() const { return m_failureMessage
; }
390 void SetFailureMessage(const wxString
& message
)
391 { m_failureMessage
= message
; }
394 // -----------------------------------------------------------------------
396 /** @section propgrid_pgactions wxPropertyGrid Action Identifiers
398 These are used with wxPropertyGrid::AddActionTrigger() and
399 wxPropertyGrid::ClearActionTriggers().
403 enum wxPG_KEYBOARD_ACTIONS
405 wxPG_ACTION_INVALID
= 0,
406 wxPG_ACTION_NEXT_PROPERTY
,
407 wxPG_ACTION_PREV_PROPERTY
,
408 wxPG_ACTION_EXPAND_PROPERTY
,
409 wxPG_ACTION_COLLAPSE_PROPERTY
,
410 wxPG_ACTION_CANCEL_EDIT
,
420 // -----------------------------------------------------------------------
423 // wxPropertyGrid::DoSelectProperty flags (selFlags)
425 // Focuses to created editor
426 #define wxPG_SEL_FOCUS 0x01
427 // Forces deletion and recreation of editor
428 #define wxPG_SEL_FORCE 0x02
429 // For example, doesn't cause EnsureVisible
430 #define wxPG_SEL_NONVISIBLE 0x04
431 // Do not validate editor's value before selecting
432 #define wxPG_SEL_NOVALIDATE 0x08
433 // Property being deselected is about to be deleted
434 #define wxPG_SEL_DELETING 0x10
435 // Property's values was set to unspecified by the user
436 #define wxPG_SEL_SETUNSPEC 0x20
437 // Property's event handler changed the value
438 #define wxPG_SEL_DIALOGVAL 0x40
441 // -----------------------------------------------------------------------
446 #define wxPG_FL_INITIALIZED 0x0001
447 // Set when creating editor controls if it was clicked on.
448 #define wxPG_FL_ACTIVATION_BY_CLICK 0x0002
449 #define wxPG_FL_DONT_CENTER_SPLITTER 0x0004
450 #define wxPG_FL_FOCUSED 0x0008
451 #define wxPG_FL_MOUSE_CAPTURED 0x0010
452 #define wxPG_FL_MOUSE_INSIDE 0x0020
453 #define wxPG_FL_VALUE_MODIFIED 0x0040
454 // don't clear background of m_wndEditor
455 #define wxPG_FL_PRIMARY_FILLS_ENTIRE 0x0080
456 // currently active editor uses custom image
457 #define wxPG_FL_CUR_USES_CUSTOM_IMAGE 0x0100
458 // cell colours override selection colours for selected cell
459 #define wxPG_FL_CELL_OVERRIDES_SEL 0x0200
460 #define wxPG_FL_SCROLLED 0x0400
461 // set when all added/inserted properties get hideable flag
462 #define wxPG_FL_ADDING_HIDEABLES 0x0800
463 // Disables showing help strings on statusbar.
464 #define wxPG_FL_NOSTATUSBARHELP 0x1000
465 // Marks that we created the state, so we have to destroy it too.
466 #define wxPG_FL_CREATEDSTATE 0x2000
467 // Set if scrollbar's existence was detected in last onresize.
468 #define wxPG_FL_SCROLLBAR_DETECTED 0x4000
469 // Set if wxPGMan requires redrawing of description text box.
470 #define wxPG_FL_DESC_REFRESH_REQUIRED 0x8000
471 // Set if contained in wxPropertyGridManager
472 #define wxPG_FL_IN_MANAGER 0x00020000
473 // Set after wxPropertyGrid is shown in its initial good size
474 #define wxPG_FL_GOOD_SIZE_SET 0x00040000
475 // Next navigation key event will get ignored
476 #define wxPG_FL_IGNORE_NEXT_NAVKEY 0x00080000
477 // Set when in SelectProperty.
478 #define wxPG_FL_IN_SELECT_PROPERTY 0x00100000
479 // Set when help string is shown in status bar
480 #define wxPG_FL_STRING_IN_STATUSBAR 0x00200000
481 // Splitter position has been custom-set by the user
482 #define wxPG_FL_SPLITTER_PRE_SET 0x00400000
483 // Validation failed. Clear on modify event.
484 #define wxPG_FL_VALIDATION_FAILED 0x00800000
485 // Set if selected is fully painted (ie. both image and text)
486 //#define wxPG_FL_SELECTED_IS_FULL_PAINT 0x01000000
487 // Set after page has been inserted to manager
488 #define wxPG_MAN_FL_PAGE_INSERTED 0x02000000
489 // Active editor control is abnormally large
490 #define wxPG_FL_ABNORMAL_EDITOR 0x04000000
491 // Recursion guard for OnCustomEditorEvent
492 #define wxPG_FL_IN_ONCUSTOMEDITOREVENT 0x08000000
493 #define wxPG_FL_VALUE_CHANGE_IN_EVENT 0x10000000
494 // Editor control width should not change on resize
495 #define wxPG_FL_FIXED_WIDTH_EDITOR 0x20000000
496 // Width of panel can be different than width of grid
497 #define wxPG_FL_HAS_VIRTUAL_WIDTH 0x40000000
498 // Prevents RecalculateVirtualSize re-entrancy
499 #define wxPG_FL_RECALCULATING_VIRTUAL_SIZE 0x80000000
501 #endif // #ifndef SWIG
503 #if !defined(__wxPG_SOURCE_FILE__) && !defined(SWIG)
504 // Reduce compile time, but still include in user app
505 #include "wx/propgrid/props.h"
508 // -----------------------------------------------------------------------
510 /** @class wxPropertyGrid
512 wxPropertyGrid is a specialized grid for editing properties
513 such as strings, numbers, flagsets, fonts, and colours. wxPropertySheet
514 used to do the very same thing, but it hasn't been updated for a while
515 and it is currently deprecated.
517 Please note that most member functions are inherited and as such not
518 documented on this page. This means you will probably also want to read
519 wxPropertyGridInterface class reference.
521 See also @ref overview_propgrid.
523 @section propgrid_window_styles_ Window Styles
525 See @ref propgrid_window_styles.
527 @section propgrid_event_handling Event Handling
529 To process input from a propertygrid control, use these event handler
530 macros to direct input to member functions that take a wxPropertyGridEvent
533 @beginEventTable{wxPropertyGridEvent}
534 @event{EVT_PG_SELECTED (id, func)}
535 Respond to wxEVT_PG_SELECTED event, generated when property value
536 has been changed by user.
537 @event{EVT_PG_CHANGING(id, func)}
538 Respond to wxEVT_PG_CHANGING event, generated when property value
539 is about to be changed by user. Use wxPropertyGridEvent::GetValue()
540 to take a peek at the pending value, and wxPropertyGridEvent::Veto()
541 to prevent change from taking place, if necessary.
542 @event{EVT_PG_HIGHLIGHTED(id, func)}
543 Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
544 moves over a property. Event's property is NULL if hovered area does
545 not belong to any property.
546 @event{EVT_PG_RIGHT_CLICK(id, func)}
547 Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
548 clicked on with right mouse button.
549 @event{EVT_PG_DOUBLE_CLICK(id, func)}
550 Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
551 double-clicked onwith left mouse button.
552 @event{EVT_PG_ITEM_COLLAPSED(id, func)}
553 Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
554 a property or category..
555 @event{EVT_PG_ITEM_EXPANDED(id, func)}
556 Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
557 a property or category..
562 - Use Freeze() and Thaw() respectively to disable and enable drawing. This
563 will also delay sorting etc. miscellaneous calculations to the last
569 class WXDLLIMPEXP_PROPGRID
570 wxPropertyGrid
: public wxScrolledWindow
, public wxPropertyGridInterface
572 friend class wxPropertyGridPageState
;
573 friend class wxPropertyGridInterface
;
574 friend class wxPropertyGridManager
;
575 friend class wxPGCanvas
;
578 DECLARE_DYNAMIC_CLASS(wxPropertyGrid
)
583 %pythonAppend wxPropertyGrid
{
584 self
._setOORInfo(self
)
585 self
.DoDefaultTypeMappings()
586 self
.edited_objects
= {}
587 self
.DoDefaultValueTypeMappings()
588 if not hasattr(self
.__class__
,'_vt2setter'):
589 self
.__class__
._vt2setter
= {}
591 %pythonAppend
wxPropertyGrid() ""
593 wxPropertyGrid( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
594 const wxPoint
& pos
= wxDefaultPosition
,
595 const wxSize
& size
= wxDefaultSize
,
596 long style
= wxPG_DEFAULT_STYLE
,
597 const wxChar
* name
= wxPyPropertyGridNameStr
);
598 %RenameCtor
(PrePropertyGrid
, wxPropertyGrid());
602 Two step constructor.
604 Call Create when this constructor is called to build up the
609 /** The default constructor. The styles to be used are styles valid for
610 the wxWindow and wxScrolledWindow.
611 @see @link wndflags Additional Window Styles@endlink
613 wxPropertyGrid( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
614 const wxPoint
& pos
= wxDefaultPosition
,
615 const wxSize
& size
= wxDefaultSize
,
616 long style
= wxPG_DEFAULT_STYLE
,
617 const wxChar
* name
= wxPropertyGridNameStr
);
620 virtual ~wxPropertyGrid();
623 /** Adds given key combination to trigger given action.
625 Which action to trigger. See @link pgactions List of list of
626 wxPropertyGrid actions@endlink.
628 void AddActionTrigger( int action
, int keycode
, int modifiers
= 0 );
631 This static function enables or disables automatic use of
632 wxGetTranslation for following strings: wxEnumProperty list labels,
633 wxFlagsProperty sub-property labels.
637 static void AutoGetTranslation( bool enable
);
640 Changes value of a property, as if from an editor.
642 Use this instead of SetPropertyValue() if you need the value to run
643 through validation process, and also send the property change event.
646 Returns true if value was successfully changed.
648 bool ChangePropertyValue( wxPGPropArg id
, wxVariant newValue
);
651 Centers the splitter.
653 If argument is true, automatic splitter centering is enabled (only
654 applicapple if style wxPG_SPLITTER_AUTO_CENTER was defined).
656 void CenterSplitter( bool enable_auto_centering
= false );
658 /** Deletes all properties.
660 virtual void Clear();
662 /** Clears action triggers for given action.
664 Which action to trigger. See @link pgactions List of list of
665 wxPropertyGrid actions@endlink.
667 void ClearActionTriggers( int action
);
669 /** Forces updating the value of property from the editor control.
671 Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
672 ProcessEvent, meaning your event handlers will be called immediately.
675 Returns true if anything was changed.
677 virtual bool CommitChangesFromEditor( wxUint32 flags
= 0 );
682 Whenever the control is created without any parameters, use Create to
683 actually create it. Don't access the control's public methods before
684 this is called @see @link wndflags Additional Window Styles@endlink
686 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
687 const wxPoint
& pos
= wxDefaultPosition
,
688 const wxSize
& size
= wxDefaultSize
,
689 long style
= wxPG_DEFAULT_STYLE
,
690 const wxChar
* name
= wxPropertyGridNameStr
);
693 Call when editor widget's contents is modified.
695 For example, this is called when changes text in wxTextCtrl (used in
696 wxStringProperty and wxIntProperty).
699 This function should only be called by custom properties.
701 @see wxPGProperty::OnEvent()
703 void EditorsValueWasModified() { m_iFlags
|= wxPG_FL_VALUE_MODIFIED
; }
705 /** Reverse of EditorsValueWasModified().
708 This function should only be called by custom properties.
710 void EditorsValueWasNotModified()
712 m_iFlags
&= ~(wxPG_FL_VALUE_MODIFIED
);
716 Enables or disables (shows/hides) categories according to parameter
719 bool EnableCategories( bool enable
);
721 /** Scrolls and/or expands items to ensure that the given item is visible.
722 Returns true if something was actually done.
724 bool EnsureVisible( wxPGPropArg id
);
727 Reduces column sizes to minimum possible that contents are still
728 visibly (naturally some margin space will be applied as well).
731 Minimum size for the grid to still display everything.
734 Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
736 This function only works properly if grid size prior to call was already
739 Note that you can also get calculated column widths by calling
740 GetState->GetColumnWidth() immediately after this function returns.
744 wxSize sz
= m_pState
->DoFitColumns();
749 Returns wxWindow that the properties are painted on, and which should
750 be used as the parent for editor controls.
752 wxPanel
* GetPanel() const
757 /** Returns current category caption background colour. */
758 wxColour
GetCaptionBackgroundColour() const { return m_colCapBack
; }
760 wxFont
& GetCaptionFont() { return m_captionFont
; }
762 const wxFont
& GetCaptionFont() const { return m_captionFont
; }
764 /** Returns current category caption text colour. */
765 wxColour
GetCaptionForegroundColour() const { return m_colCapFore
; }
767 /** Returns current cell background colour. */
768 wxColour
GetCellBackgroundColour() const { return m_colPropBack
; }
770 /** Returns current cell text colour when disabled. */
771 wxColour
GetCellDisabledTextColour() const { return m_colDisPropFore
; }
773 /** Returns current cell text colour. */
774 wxColour
GetCellTextColour() const { return m_colPropFore
; }
776 /** Returns number of columns on current page. */
777 int GetColumnCount() const
779 return m_pState
->m_colWidths
.size();
782 /** Returns colour of empty space below properties. */
783 wxColour
GetEmptySpaceColour() const { return m_colEmptySpace
; }
785 /** Returns height of highest characters of used font. */
786 int GetFontHeight() const { return m_fontHeight
; }
788 /** Returns pointer to itself. Dummy function that enables same kind
789 of code to use wxPropertyGrid and wxPropertyGridManager.
791 wxPropertyGrid
* GetGrid() { return this; }
793 /** Returns rectangle of custom paint image.
795 wxRect
GetImageRect( wxPGProperty
* p
, int item
) const;
797 /** Returns size of the custom paint image in front of property.
798 If no argument is given, returns preferred size.
800 wxSize
GetImageSize( wxPGProperty
* p
= NULL
, int item
= -1 ) const;
803 /** Returns last item which could be iterated using given flags.
805 See @ref propgrid_iterator_flags.
807 wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
)
809 return m_pState
->GetLastItem(flags
);
812 const wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
) const
814 return m_pState
->GetLastItem(flags
);
818 /** Returns colour of lines between cells. */
819 wxColour
GetLineColour() const { return m_colLine
; }
821 /** Returns background colour of margin. */
822 wxColour
GetMarginColour() const { return m_colMargin
; }
824 /** Returns cell background colour of a property. */
825 wxColour
GetPropertyBackgroundColour( wxPGPropArg id
) const;
827 /** Returns cell background colour of a property. */
828 wxColour
GetPropertyTextColour( wxPGPropArg id
) const;
830 /** Returns "root property". It does not have name, etc. and it is not
831 visible. It is only useful for accessing its children.
833 wxPGProperty
* GetRoot() const { return m_pState
->m_properties
; }
835 /** Returns height of a single grid row (in pixels). */
836 int GetRowHeight() const { return m_lineHeight
; }
838 /** Returns currently selected property. */
839 wxPGProperty
* GetSelectedProperty () const { return GetSelection(); }
841 /** Returns currently selected property. */
842 wxPGProperty
* GetSelection() const
847 /** Returns current selection background colour. */
848 wxColour
GetSelectionBackgroundColour() const { return m_colSelBack
; }
850 /** Returns current selection text colour. */
851 wxColour
GetSelectionForegroundColour() const { return m_colSelFore
; }
853 /** Returns current splitter x position. */
854 int GetSplitterPosition() const
855 { return m_pState
->DoGetSplitterPosition(0); }
857 /** Returns wxTextCtrl active in currently selected property, if any. Takes
858 into account wxOwnerDrawnComboBox.
860 wxTextCtrl
* GetEditorTextCtrl() const;
862 wxPGValidationInfo
& GetValidationInfo()
864 return m_validationInfo
;
867 /** Returns current vertical spacing. */
868 int GetVerticalSpacing() const { return (int)m_vspacing
; }
870 /** Returns true if editor's value was marked modified.
872 bool IsEditorsValueModified() const
873 { return ( m_iFlags
& wxPG_FL_VALUE_MODIFIED
) ? true : false; }
875 /** Returns information about arbitrary position in the grid.
877 For wxPropertyGridHitTestResult definition, see
878 wxPropertyGridPageState::HitTest().
880 wxPropertyGridHitTestResult
HitTest( const wxPoint
& pt
) const;
882 /** Returns true if any property has been modified by the user. */
883 bool IsAnyModified() const { return (m_pState
->m_anyModified
>0); }
886 Returns true if updating is frozen (ie Freeze() called but not yet
889 bool IsFrozen() const { return (m_frozen
>0)?true:false; }
891 /** Redraws given property.
893 virtual void RefreshProperty( wxPGProperty
* p
);
896 /** Registers a new editor class.
898 Pointer to the editor class instance that should be used.
900 static wxPGEditor
* RegisterEditorClass( wxPGEditor
* editor
,
901 const wxString
& name
,
902 bool noDefCheck
= false );
905 /** Resets all colours to the original system values.
911 Editor widget is automatically created, but not focused unless focus is
912 true. This will generate wxEVT_PG_SELECT event.
916 True if selection finished successfully. Usually only fails if
917 current value in editor is not valid.
918 @see wxPropertyGrid::Unselect
920 bool SelectProperty( wxPGPropArg id
, bool focus
= false )
922 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
923 return DoSelectProperty(p
,focus
?wxPG_SEL_FOCUS
:0);
926 /** Changes keyboard shortcut to push the editor button.
928 You can set default with keycode 0. Good value for the platform is
929 guessed, but don't expect it to be very accurate.
931 void SetButtonShortcut( int keycode
,
932 bool ctrlDown
= false,
933 bool altDown
= false );
935 /** Sets category caption background colour. */
936 void SetCaptionBackgroundColour(const wxColour
& col
);
938 /** Sets category caption text colour. */
939 void SetCaptionTextColour(const wxColour
& col
);
941 /** Sets default cell background colour - applies to property cells.
942 Note that appearance of editor widgets may not be affected.
944 void SetCellBackgroundColour(const wxColour
& col
);
946 /** Sets cell text colour for disabled properties.
948 void SetCellDisabledTextColour(const wxColour
& col
);
950 /** Sets default cell text colour - applies to property name and value text.
951 Note that appearance of editor widgets may not be affected.
953 void SetCellTextColour(const wxColour
& col
);
955 /** Set number of columns (2 or more).
957 void SetColumnCount( int colCount
)
959 m_pState
->SetColumnCount(colCount
);
964 Sets the 'current' category - Append will add non-category properties
967 void SetCurrentCategory( wxPGPropArg id
)
969 wxPG_PROP_ARG_CALL_PROLOG()
970 wxPropertyCategory
* pc
= wxDynamicCast(p
, wxPropertyCategory
);
972 m_pState
->m_currentCategory
= pc
;
975 /** Sets colour of empty space below properties. */
976 void SetEmptySpaceColour(const wxColour
& col
);
978 /** Sets colour of lines between cells. */
979 void SetLineColour(const wxColour
& col
);
981 /** Sets background colour of margin. */
982 void SetMarginColour(const wxColour
& col
);
984 /** Sets property attribute for all applicapple properties.
985 Be sure to use this method only after all properties have been
988 void SetPropertyAttributeAll( const wxString
& attrName
, wxVariant value
);
990 /** Sets background colour of property and all its children. Colours of
991 captions are not affected. Background brush cache is optimized for often
992 set colours to be set last.
994 void SetPropertyBackgroundColour( wxPGPropArg id
, const wxColour
& col
);
996 /** Resets text and background colours of given property.
998 void SetPropertyColoursToDefault( wxPGPropArg id
);
1000 /** Sets text colour of property and all its children.
1002 void SetPropertyTextColour( wxPGPropArg id
,
1003 const wxColour
& col
,
1004 bool recursively
= true );
1007 Sets selection background colour - applies to selected property name
1010 void SetSelectionBackgroundColour(const wxColour
& col
);
1013 Sets selection foreground colour - applies to selected property name
1016 void SetSelectionTextColour(const wxColour
& col
);
1018 /** Sets x coordinate of the splitter.
1020 Splitter position cannot exceed grid size, and therefore setting it
1021 during form creation may fail as initial grid size is often smaller
1022 than desired splitter position, especially when sizers are being used.
1024 void SetSplitterPosition( int newxpos
, int col
= 0 )
1026 DoSetSplitterPosition_(newxpos
, true, col
);
1027 m_iFlags
|= wxPG_FL_SPLITTER_PRE_SET
;
1030 /** Set virtual width for this particular page. Width -1 indicates that the
1031 virtual width should be disabled. */
1032 void SetVirtualWidth( int width
);
1034 /** Sets name of a property.
1036 Name or pointer of property which name to change.
1040 void SetPropertyName( wxPGPropArg id
, const wxString
& newname
)
1042 wxPG_PROP_ARG_CALL_PROLOG()
1043 DoSetPropertyName( p
, newname
);
1046 /** Moves splitter as left as possible, while still allowing all
1047 labels to be shown in full.
1049 If false, will still allow sub-properties (ie. properties which
1050 parent is not root or category) to be cropped.
1052 void SetSplitterLeft( bool subProps
= false )
1054 m_pState
->SetSplitterLeft(subProps
);
1057 /** Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
1058 height. Value of 2 should be default on most platforms.
1060 On wxMSW, wxComboBox, when used as property editor widget, will spill
1061 out with anything less than 3.
1063 void SetVerticalSpacing( int vspacing
)
1065 m_vspacing
= (unsigned char)vspacing
;
1066 CalculateFontAndBitmapStuff( vspacing
);
1067 if ( !m_pState
->m_itemsAdded
) Refresh();
1070 /** Shows an brief error message that is related to a property. */
1071 void ShowPropertyError( wxPGPropArg id
, const wxString
& msg
)
1073 wxPG_PROP_ARG_CALL_PROLOG()
1074 DoShowPropertyError(p
, msg
);
1077 /** Sorts all items at all levels (except sub-properties). */
1080 /** Sorts children of a category.
1082 void SortChildren( wxPGPropArg id
);
1084 /////////////////////////////////////////////////////////////////
1086 // Following methods do not need to be (currently) documented
1088 /////////////////////////////////////////////////////////////////
1090 bool HasVirtualWidth() const
1091 { return (m_iFlags
& wxPG_FL_HAS_VIRTUAL_WIDTH
) ? true : false; }
1093 const wxPGCommonValue
* GetCommonValue( unsigned int i
) const
1095 return (wxPGCommonValue
*) m_commonValues
[i
];
1098 /** Returns number of common values.
1100 unsigned int GetCommonValueCount() const
1102 return m_commonValues
.size();
1105 /** Returns label of given common value.
1107 wxString
GetCommonValueLabel( unsigned int i
) const
1109 wxASSERT( GetCommonValue(i
) );
1110 return GetCommonValue(i
)->GetLabel();
1114 Returns index of common value that will truly change value to
1117 int GetUnspecifiedCommonValue() const { return m_cvUnspecified
; }
1119 /** Set index of common value that will truly change value to unspecified.
1120 Using -1 will set none to have such effect.
1123 void SetUnspecifiedCommonValue( int index
) { m_cvUnspecified
= index
; }
1126 Shortcut for creating dialog-caller button. Used, for example, by
1129 This should only be called by properties.
1131 wxWindow
* GenerateEditorButton( const wxPoint
& pos
, const wxSize
& sz
);
1133 /** Fixes position of wxTextCtrl-like control (wxSpinCtrl usually
1134 fits as one). Call after control has been created (but before
1137 void FixPosForTextCtrl( wxWindow
* ctrl
,
1138 const wxPoint
& offset
= wxPoint(0, 0) );
1140 /** Shortcut for creating text editor widget.
1142 Same as pos given for CreateEditor.
1144 Same as sz given for CreateEditor.
1146 Initial text for wxTextCtrl.
1148 If right-side control, such as button, also created, then create it
1149 first and pass it as this parameter.
1151 Extra style flags to pass for wxTextCtrl.
1153 Note that this should generally be called only by new classes derived
1156 wxWindow
* GenerateEditorTextCtrl( const wxPoint
& pos
,
1158 const wxString
& value
,
1159 wxWindow
* secondary
,
1163 /* Generates both textctrl and button.
1165 wxWindow
* GenerateEditorTextCtrlAndButton( const wxPoint
& pos
,
1166 const wxSize
& sz
, wxWindow
** psecondary
, int limited_editing
,
1167 wxPGProperty
* property
);
1169 /** Generates position for a widget editor dialog box.
1171 Property for which dialog is positioned.
1173 Known or over-approximated size of the dialog.
1175 Position for dialog.
1177 wxPoint
GetGoodEditorDialogPosition( wxPGProperty
* p
,
1180 // Converts escape sequences in src_str to newlines,
1181 // tabs, etc. and copies result to dst_str.
1182 static wxString
& ExpandEscapeSequences( wxString
& dst_str
,
1183 wxString
& src_str
);
1185 // Converts newlines, tabs, etc. in src_str to escape
1186 // sequences, and copies result to dst_str.
1187 static wxString
& CreateEscapeSequences( wxString
& dst_str
,
1188 wxString
& src_str
);
1191 Returns rectangle that fully contains properties between and including
1194 wxRect
GetPropertyRect( const wxPGProperty
* p1
,
1195 const wxPGProperty
* p2
) const;
1197 /** Returns pointer to current active primary editor control (NULL if none).
1199 If editor uses clipper window, pointer is returned to the actual
1200 editor, not the clipper.
1202 wxWindow
* GetEditorControl() const;
1204 /** Adjusts given position if topCtrlWnd is child of clipper window.
1206 bool AdjustPosForClipperWindow( wxWindow
* topCtrlWnd
, int* x
, int* y
);
1208 wxWindow
* GetPrimaryEditor() const
1210 return GetEditorControl();
1214 Returns pointer to current active secondary editor control (NULL if
1217 wxWindow
* GetEditorControlSecondary() const
1219 return m_wndEditor2
;
1225 Generates contents for string dst based on the contents of
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)".
1232 static void ArrayStringToString( wxString
& dst
, const wxArrayString
& src
,
1233 wxChar preDelim
, wxChar postDelim
,
1236 // Mostly useful for page switching.
1237 void SwitchState( wxPropertyGridPageState
* pNewState
);
1239 /** Pass this function to Connect calls in propertyclass::CreateEditor.
1241 void OnCustomEditorEvent( wxCommandEvent
&event
);
1243 long GetInternalFlags() const { return m_iFlags
; }
1244 void SetInternalFlag( long flag
) { m_iFlags
|= flag
; }
1245 void ClearInternalFlag( long flag
) { m_iFlags
&= ~(flag
); }
1246 void IncFrozen() { m_frozen
++; }
1247 void DecFrozen() { m_frozen
--; }
1249 void OnComboItemPaint( wxPGCustomComboControl
* pCb
,int item
,wxDC
& dc
,
1250 wxRect
& rect
,int flags
);
1252 // Used by simple check box for keyboard navigation
1253 void SendNavigationKeyEvent( int dir
);
1255 /** Standardized double-to-string conversion.
1257 static void DoubleToString( wxString
& target
,
1261 wxString
* precTemplate
);
1264 Call this from wxPGProperty::OnEvent() to cause property value to be
1265 changed after the function returns (with true as return value).
1266 ValueChangeInEvent() must be used if you wish the application to be
1267 able to use wxEVT_PG_CHANGING to potentially veto the given value.
1269 void ValueChangeInEvent( wxVariant variant
)
1271 m_changeInEventValue
= variant
;
1272 m_iFlags
|= wxPG_FL_VALUE_CHANGE_IN_EVENT
;
1275 /** Returns true if given event is from first of an array of buttons
1276 (as can be in case when wxPGMultiButton is used).
1278 bool IsMainButtonEvent( const wxEvent
& event
)
1280 return (event
.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED
)
1281 && (m_wndSecId
== event
.GetId());
1284 /** Pending value is expected to be passed in PerformValidation().
1286 virtual bool DoPropertyChanged( wxPGProperty
* p
,
1287 unsigned int selFlags
= 0 );
1290 Runs all validation functionality (includes sending wxEVT_PG_CHANGING).
1291 Returns true if all tests passed.
1293 virtual bool PerformValidation( wxPGProperty
* p
, wxVariant
& pendingValue
);
1295 /** Called when validation for given property fails.
1297 Value which failed in validation.
1299 Return true if user is allowed to change to another property even
1300 if current has invalid value.
1302 To add your own validation failure behavior, override
1303 wxPropertyGrid::DoOnValidationFailure().
1305 bool OnValidationFailure( wxPGProperty
* property
, wxVariant
& invalidValue
)
1307 bool res
= DoOnValidationFailure(property
, invalidValue
);
1308 property
->SetFlag(wxPG_PROP_INVALID_VALUE
);
1312 /** Called to indicate property and editor has valid value now.
1314 void OnValidationFailureReset( wxPGProperty
* property
)
1316 if ( property
&& property
->HasFlag(wxPG_PROP_INVALID_VALUE
) )
1318 DoOnValidationFailureReset(property
);
1319 property
->ClearFlag(wxPG_PROP_INVALID_VALUE
);
1321 m_validationInfo
.m_failureMessage
.clear();
1324 /** Override in derived class to display error messages in custom manner
1325 (these message usually only result from validation failure).
1327 virtual void DoShowPropertyError( wxPGProperty
* property
,
1328 const wxString
& msg
);
1330 /** Override to customize property validation failure behavior.
1332 Value which failed in validation.
1334 Return true if user is allowed to change to another property even
1335 if current has invalid value.
1337 virtual bool DoOnValidationFailure( wxPGProperty
* property
,
1338 wxVariant
& invalidValue
);
1340 /** Override to customize resetting of property validation failure status.
1342 Property is guaranteed to have flag wxPG_PROP_INVALID_VALUE set.
1344 virtual void DoOnValidationFailureReset( wxPGProperty
* property
);
1346 int GetSpacingY() const { return m_spacingy
; }
1349 Must be called in wxPGEditor::CreateControls() if primary editor window
1350 is wxTextCtrl, just before textctrl is created.
1352 Initial text value of created wxTextCtrl.
1354 void SetupTextCtrlValue( const wxString text
) { m_prevTcValue
= text
; }
1357 Unfocuses or closes editor if one was open, but does not deselect
1360 bool UnfocusEditor();
1365 wxPropertyGridPageState used by the grid is created here.
1367 If grid is used in wxPropertyGridManager, there is no point overriding
1368 this - instead, set custom wxPropertyGridPage classes.
1370 virtual wxPropertyGridPageState
* CreateState() const;
1375 // Control font changer helper.
1376 void SetCurControlBoldFont();
1379 // Public methods for semi-public use
1380 // (not protected for optimization)
1382 bool DoSelectProperty( wxPGProperty
* p
, unsigned int flags
= 0 );
1384 // Overridden functions.
1385 virtual bool Destroy();
1386 virtual wxSize
DoGetBestSize() const;
1387 // Returns property at given y coordinate (relative to grid's top left).
1388 wxPGProperty
* GetItemAtY( int y
) const { return DoGetItemAtY(y
); }
1390 virtual void Refresh( bool eraseBackground
= true,
1391 const wxRect
*rect
= (const wxRect
*) NULL
);
1392 virtual bool SetFont( const wxFont
& font
);
1393 #if wxPG_SUPPORT_TOOLTIPS
1394 void SetToolTip( const wxString
& tipString
);
1396 virtual void Freeze();
1397 virtual void SetExtraStyle( long exStyle
);
1398 virtual void Thaw();
1403 #ifndef wxPG_ICON_WIDTH
1404 wxBitmap
*m_expandbmp
, *m_collbmp
;
1407 wxCursor
*m_cursorSizeWE
;
1409 /** wxWindow pointers to editor control(s). */
1410 wxWindow
*m_wndEditor
;
1411 wxWindow
*m_wndEditor2
;
1413 /** wxPGCanvas instance. */
1416 #if wxPG_DOUBLE_BUFFER
1417 wxBitmap
*m_doubleBuffer
;
1420 wxArrayPtrVoid
*m_windowsToDelete
;
1422 /** Local time ms when control was created. */
1423 wxLongLong m_timeCreated
;
1425 /** wxPGProperty::OnEvent can change value by setting this. */
1426 wxVariant m_changeInEventValue
;
1428 /** Id of m_wndEditor2, or its first child, if any. */
1431 /** Extra Y spacing between the items. */
1434 /** Control client area width; updated on resize. */
1437 /** Control client area height; updated on resize. */
1440 /** Current non-client width (needed when auto-centering). */
1443 /** Non-client width (auto-centering helper). */
1446 /** Previously recorded scroll start position. */
1450 The gutter spacing in front and back of the image.
1451 This determines the amount of spacing in front of each item
1455 /** Includes separator line. */
1458 /** Gutter*2 + image width. */
1461 // y spacing for expand/collapse button.
1462 int m_buttonSpacingY
;
1464 /** Extra margin for expanded sub-group items. */
1465 int m_subgroup_extramargin
;
1468 The image width of the [+] icon.
1470 This is also calculated in the gutter
1474 #ifndef wxPG_ICON_WIDTH
1477 The image height of the [+] icon.
1479 This is calculated as minimal size and to align
1484 /** Current cursor id. */
1488 This captionFont is made equal to the font of the wxScrolledWindow.
1490 As extra the bold face is set on it when this is wanted by the user
1493 wxFont m_captionFont
;
1495 int m_fontHeight
; // Height of the font.
1497 // Base keycode for triggering push button.
1498 int m_pushButKeyCode
;
1500 /** m_splitterx when drag began. */
1501 int m_startingSplitterX
;
1504 Index to splitter currently being dragged (0=one after the first
1507 int m_draggedSplitter
;
1509 /** Changed property, calculated in PerformValidation(). */
1510 wxPGProperty
* m_chgInfo_changedProperty
;
1513 Lowest property for which editing happened, but which does not have
1516 wxPGProperty
* m_chgInfo_baseChangedProperty
;
1518 /** Changed property value, calculated in PerformValidation(). */
1519 wxVariant m_chgInfo_pendingValue
;
1521 /** Passed to SetValue. */
1522 wxVariant m_chgInfo_valueList
;
1524 /** Validation information. */
1525 wxPGValidationInfo m_validationInfo
;
1527 /** Actions and keys that trigger them. */
1528 wxPGHashMapI2I m_actionTriggers
;
1534 /** Bits are used to indicate which colours are customized. */
1535 unsigned short m_coloursCustomized
;
1537 /** x - m_splitterx. */
1538 signed char m_dragOffset
;
1540 /** 0 = not dragging, 1 = drag just started, 2 = drag in progress */
1541 unsigned char m_dragStatus
;
1543 /** 0 = margin, 1 = label, 2 = value. */
1544 unsigned char m_mouseSide
;
1546 /** True when editor control is focused. */
1547 unsigned char m_editorFocused
;
1549 /** 1 if m_latsCaption is also the bottommost caption. */
1550 //unsigned char m_lastCaptionBottomnest;
1552 /** Set to 1 when graphics frozen. */
1553 unsigned char m_frozen
;
1555 unsigned char m_vspacing
;
1557 // Does triggering push button need Alt down?
1558 unsigned char m_pushButKeyCodeNeedsAlt
;
1560 // Does triggering push button need Ctrl down?
1561 unsigned char m_pushButKeyCodeNeedsCtrl
;
1563 // Used to track when Alt/Ctrl+Key was consumed.
1564 unsigned char m_keyComboConsumed
;
1566 /** 1 if in DoPropertyChanged() */
1567 unsigned char m_inDoPropertyChanged
;
1569 /** 1 if in CommitChangesFromEditor() */
1570 unsigned char m_inCommitChangesFromEditor
;
1572 /** 1 if in DoSelectProperty() */
1573 unsigned char m_inDoSelectProperty
;
1575 wxPGVFBFlags m_permanentValidationFailureBehavior
; // Set by app
1577 /** Internal flags - see wxPG_FL_XXX constants. */
1580 /** When drawing next time, clear this many item slots at the end. */
1581 int m_clearThisMany
;
1583 /** Pointer to selected property. Note that this is duplicated in
1584 m_state for better transiency between pages so that the selected
1585 item can be retained.
1587 wxPGProperty
* m_selected
;
1589 // pointer to property that has mouse hovering
1590 wxPGProperty
* m_propHover
;
1592 // EventObject for wxPropertyGridEvents
1593 wxWindow
* m_eventObject
;
1595 // What (global) window is currently focused (needed to resolve event
1597 wxWindow
* m_curFocused
;
1600 wxEvtHandler
* m_tlwHandler
;
1605 // y coordinate of property that mouse hovering
1607 // Which column's editor is selected (usually 1)?
1610 // x relative to splitter (needed for resize).
1613 // lines between cells
1615 // property labels and values are written in this colour
1616 wxColour m_colPropFore
;
1617 // or with this colour when disabled
1618 wxColour m_colDisPropFore
;
1619 // background for m_colPropFore
1620 wxColour m_colPropBack
;
1621 // text color for captions
1622 wxColour m_colCapFore
;
1623 // background color for captions
1624 wxColour m_colCapBack
;
1625 // foreground for selected property
1626 wxColour m_colSelFore
;
1627 // background for selected property (actually use background color when
1628 // control out-of-focus)
1629 wxColour m_colSelBack
;
1630 // background colour for margin
1631 wxColour m_colMargin
;
1632 // background colour for empty space below the grid
1633 wxColour m_colEmptySpace
;
1635 // temp property array used in DoDrawItems
1636 wxArrayPtrVoid m_visPropArray
;
1638 // NB: These *cannot* be moved to globals.
1640 // Array of background colour brushes.
1641 wxArrayPtrVoid m_arrBgBrushes
;
1642 // Array of foreground colours.
1643 wxArrayPtrVoid m_arrFgCols
;
1645 // labels when properties use common values
1646 wxArrayPtrVoid m_commonValues
;
1647 // Which cv selection really sets value to unspecified?
1648 int m_cvUnspecified
;
1650 // Used to skip excess text editor events
1651 wxString m_prevTcValue
;
1655 // Sets some members to defaults (called constructors).
1658 // Initializes some members (called by Create and complex constructor).
1661 void OnPaint(wxPaintEvent
&event
);
1663 // main event receivers
1664 void OnMouseMove( wxMouseEvent
&event
);
1665 void OnMouseMoveBottom( wxMouseEvent
&event
);
1666 void OnMouseClick( wxMouseEvent
&event
);
1667 void OnMouseRightClick( wxMouseEvent
&event
);
1668 void OnMouseDoubleClick( wxMouseEvent
&event
);
1669 void OnMouseUp( wxMouseEvent
&event
);
1670 void OnKey( wxKeyEvent
&event
);
1671 void OnKeyUp( wxKeyEvent
&event
);
1672 void OnNavigationKey( wxNavigationKeyEvent
& event
);
1673 void OnResize( wxSizeEvent
&event
);
1676 bool HandleMouseMove( int x
, unsigned int y
, wxMouseEvent
&event
);
1677 bool HandleMouseClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1678 bool HandleMouseRightClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1679 bool HandleMouseDoubleClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1680 bool HandleMouseUp( int x
, unsigned int y
, wxMouseEvent
&event
);
1681 void HandleKeyEvent( wxKeyEvent
&event
);
1682 // Handle TAB and ESCAPE in control
1683 bool HandleChildKey( wxKeyEvent
& event
);
1685 void OnMouseEntry( wxMouseEvent
&event
);
1687 void OnIdle( wxIdleEvent
&event
);
1688 void OnFocusEvent( wxFocusEvent
&event
);
1689 void OnChildFocusEvent( wxChildFocusEvent
& event
);
1691 bool OnMouseCommon( wxMouseEvent
&event
, int* px
, int *py
);
1692 bool OnMouseChildCommon( wxMouseEvent
&event
, int* px
, int *py
);
1694 // sub-control event handlers
1695 void OnMouseClickChild( wxMouseEvent
&event
);
1696 void OnMouseRightClickChild( wxMouseEvent
&event
);
1697 void OnMouseMoveChild( wxMouseEvent
&event
);
1698 void OnMouseUpChild( wxMouseEvent
&event
);
1699 void OnChildKeyDown( wxKeyEvent
&event
);
1700 void OnChildKeyUp( wxKeyEvent
&event
);
1702 void OnCaptureChange( wxMouseCaptureChangedEvent
&event
);
1704 void OnScrollEvent( wxScrollWinEvent
&event
);
1706 void OnSysColourChanged( wxSysColourChangedEvent
&event
);
1711 Adjust the centering of the bitmap icons (collapse / expand) when the
1712 caption font changes.
1714 They need to be centered in the middle of the font, so a bit of deltaY
1715 adjustment is needed. On entry, m_captionFont must be set to window
1716 font. It will be modified properly.
1718 void CalculateFontAndBitmapStuff( int vspacing
);
1720 wxRect
GetEditorWidgetRect( wxPGProperty
* p
, int column
) const;
1722 void CorrectEditorWidgetSizeX();
1724 /** Called in RecalculateVirtualSize() to reposition control
1725 on virtual height changes.
1727 void CorrectEditorWidgetPosY();
1731 void OnScreenNote( const wxChar
* format
, ... );
1734 /** Deselect current selection, if any. Returns true if success
1735 (ie. validator did not intercept). */
1736 bool DoClearSelection();
1738 int DoDrawItems( wxDC
& dc
,
1739 const wxPGProperty
* first_item
,
1740 const wxPGProperty
* last_item
,
1741 const wxRect
* clip_rect
,
1742 bool isBuffered
) const;
1744 void DoSetPropertyValueUnspecified( wxPGProperty
* p
);
1746 /** Draws an expand/collapse (ie. +/-) button.
1748 virtual void DrawExpanderButton( wxDC
& dc
, const wxRect
& rect
,
1749 wxPGProperty
* property
) const;
1751 /** Draws items from topitemy to bottomitemy */
1752 void DrawItems( wxDC
& dc
, unsigned int topitemy
, unsigned int bottomitemy
,
1753 const wxRect
* clip_rect
= (const wxRect
*) NULL
);
1755 void DrawItems( const wxPGProperty
* p1
, const wxPGProperty
* p2
);
1757 void DrawItem( wxPGProperty
* p
)
1762 virtual void DrawItemAndChildren( wxPGProperty
* p
);
1765 Draws item, children, and consequtive parents as long as category is
1768 void DrawItemAndValueRelated( wxPGProperty
* p
);
1770 // Translate wxKeyEvent to wxPG_ACTION_XXX
1771 int KeyEventToActions(wxKeyEvent
&event
, int* pSecond
) const;
1773 int KeyEventToAction(wxKeyEvent
&event
) const
1775 return KeyEventToActions(event
, NULL
);
1778 void ImprovedClientToScreen( int* px
, int* py
);
1780 // Called by focus event handlers. newFocused is the window that becomes
1782 void HandleFocusChange( wxWindow
* newFocused
);
1784 /** Reloads all non-customized colours from system settings. */
1785 void RegainColours();
1787 bool DoEditorValidate();
1789 wxPGProperty
* DoGetItemAtY( int y
) const;
1791 void DoSetSplitterPosition_( int newxpos
,
1792 bool refresh
= true,
1793 int splitterIndex
= 0,
1794 bool allPages
= false );
1798 virtual bool DoExpand( wxPGProperty
* p
, bool sendEvent
= false );
1800 virtual bool DoCollapse( wxPGProperty
* p
, bool sendEvent
= false );
1802 // Returns nearest paint visible property (such that will be painted unless
1803 // window is scrolled or resized). If given property is paint visible, then
1804 // it itself will be returned.
1805 wxPGProperty
* GetNearestPaintVisible( wxPGProperty
* p
) const;
1807 static void RegisterDefaultEditors();
1809 // Sets m_bgColIndex to this property and all its children.
1810 void SetBackgroundColourIndex( wxPGProperty
* p
, int index
);
1812 // Sets m_fgColIndex to this property and all its children.
1813 void SetTextColourIndex( wxPGProperty
* p
, int index
, int flags
);
1815 int CacheColour( const wxColour
& colour
);
1817 void DoSetPropertyName( wxPGProperty
* p
, const wxString
& newname
);
1819 // Setups event handling for child control
1820 void SetupEventHandling( wxWindow
* wnd
, int id
);
1822 void CustomSetCursor( int type
, bool override
= false );
1824 virtual bool ProcessEvent(wxEvent
& event
);
1825 virtual void SetWindowStyleFlag( long style
);
1828 Repositions scrollbar and underlying panel according to changed virtual
1831 void RecalculateVirtualSize( int forceXPos
= -1 );
1833 void PrepareAfterItemsAdded();
1835 bool SendEvent( int eventType
,
1837 wxVariant
* pValue
= NULL
,
1838 unsigned int selFlags
= 0 );
1840 bool DoHideProperty( wxPGProperty
* p
, bool hide
, int flags
);
1844 bool ButtonTriggerKeyTest( wxKeyEvent
&event
);
1846 #endif // DOXYGEN_SHOULD_SKIP_THIS
1849 DECLARE_EVENT_TABLE()
1850 #endif // #ifndef SWIG
1853 // -----------------------------------------------------------------------
1855 // Bunch of inlines that need to resolved after all classes have been defined.
1859 inline bool wxPropertyGridPageState::IsDisplayed() const
1861 return ( this == m_pPropGrid
->GetState() );
1864 inline unsigned int wxPropertyGridPageState::GetActualVirtualHeight() const
1866 return DoGetRoot()->GetChildrenHeight(GetGrid()->GetRowHeight());
1870 inline int wxPGProperty::GetDisplayedCommonValueCount() const
1872 if ( HasFlag(wxPG_PROP_USES_COMMON_VALUE
) )
1874 wxPropertyGrid
* pg
= GetGrid();
1876 return pg
->GetCommonValueCount();
1881 inline void wxPGProperty::SetEditor( const wxString
& editorName
)
1883 m_customEditor
= wxPropertyGridInterface::GetEditorByName(editorName
);
1886 inline void wxPGProperty::SetName( const wxString
& newName
)
1888 GetGrid()->SetPropertyName(this, newName
);
1891 inline bool wxPGProperty::Hide( bool hide
, int flags
)
1893 return GetGrid()->HideProperty(this, hide
, flags
);
1896 inline bool wxPGProperty::SetMaxLength( int maxLen
)
1898 return GetGrid()->SetPropertyMaxLength(this,maxLen
);
1901 // -----------------------------------------------------------------------
1906 #define wxPG_BASE_EVT_PRE_ID 1775
1908 BEGIN_DECLARE_EVENT_TYPES()
1909 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_SELECTED
, wxPG_BASE_EVT_PRE_ID
)
1910 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_CHANGING
, wxPG_BASE_EVT_PRE_ID
+1)
1911 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_CHANGED
, wxPG_BASE_EVT_PRE_ID
+2)
1912 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_HIGHLIGHTED
, wxPG_BASE_EVT_PRE_ID
+3)
1913 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_RIGHT_CLICK
, wxPG_BASE_EVT_PRE_ID
+4)
1914 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_PAGE_CHANGED
, wxPG_BASE_EVT_PRE_ID
+5)
1915 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_ITEM_COLLAPSED
, wxPG_BASE_EVT_PRE_ID
+6)
1916 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_ITEM_EXPANDED
, wxPG_BASE_EVT_PRE_ID
+7)
1917 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_DOUBLE_CLICK
, wxPG_BASE_EVT_PRE_ID
+8)
1918 END_DECLARE_EVENT_TYPES()
1921 wxEVT_PG_SELECTED
= wxPG_BASE_EVT_PRE_ID
,
1924 wxEVT_PG_HIGHLIGHTED
,
1925 wxEVT_PG_RIGHT_CLICK
,
1926 wxEVT_PG_PAGE_CHANGED
,
1927 wxEVT_PG_ITEM_COLLAPSED
,
1928 wxEVT_PG_ITEM_EXPANDED
,
1929 wxEVT_PG_DOUBLE_CLICK
1934 #define wxPG_BASE_EVT_TYPE wxEVT_PG_SELECTED
1935 #define wxPG_MAX_EVT_TYPE (wxPG_BASE_EVT_TYPE+30)
1939 typedef void (wxEvtHandler::*wxPropertyGridEventFunction
)(wxPropertyGridEvent
&);
1941 #define EVT_PG_SELECTED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_SELECTED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1942 #define EVT_PG_CHANGING(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGING, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1943 #define EVT_PG_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1944 #define EVT_PG_HIGHLIGHTED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_HIGHLIGHTED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1945 #define EVT_PG_RIGHT_CLICK(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_RIGHT_CLICK, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1946 #define EVT_PG_DOUBLE_CLICK(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_DOUBLE_CLICK, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1947 #define EVT_PG_PAGE_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_PAGE_CHANGED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1948 #define EVT_PG_ITEM_COLLAPSED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_COLLAPSED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1949 #define EVT_PG_ITEM_EXPANDED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_EXPANDED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1951 #define wxPropertyGridEventHandler(A) \
1952 ((wxObjectEventFunction)(wxEventFunction)(wxPropertyGridEventFunction)&A)
1957 /** @class wxPropertyGridEvent
1959 A propertygrid event holds information about events associated with
1960 wxPropertyGrid objects.
1962 @library{wxpropgrid}
1965 class WXDLLIMPEXP_PROPGRID wxPropertyGridEvent
: public wxCommandEvent
1970 wxPropertyGridEvent(wxEventType commandType
=0, int id
=0);
1972 /** Copy constructor. */
1973 wxPropertyGridEvent(const wxPropertyGridEvent
& event
);
1976 ~wxPropertyGridEvent();
1979 virtual wxEvent
* Clone() const;
1981 wxPGProperty
* GetMainParent() const
1983 wxASSERT(m_property
);
1984 return m_property
->GetMainParent();
1987 /** Returns id of associated property. */
1988 wxPGProperty
* GetProperty() const
1993 wxPGValidationInfo
& GetValidationInfo()
1995 wxASSERT(m_validationInfo
);
1996 return *m_validationInfo
;
1999 /** Returns true if event has associated property. */
2000 bool HasProperty() const { return ( m_property
!= (wxPGProperty
*) NULL
); }
2002 /** Returns true if you can veto the action that the event is signaling.
2004 bool CanVeto() const { return m_canVeto
; }
2007 Call this from your event handler to veto action that the event is
2010 You can only veto a shutdown if wxPropertyGridEvent::CanVeto returns
2013 Currently only wxEVT_PG_CHANGING supports vetoing.
2015 void Veto( bool veto
= true ) { m_wasVetoed
= veto
; }
2017 /** Returns value that is about to be set for wxEVT_PG_CHANGING.
2019 const wxVariant
& GetValue() const
2021 wxASSERT_MSG( m_validationInfo
,
2022 "Only call GetValue from a handler "
2023 "of event type that supports it" );
2024 return *m_validationInfo
->m_pValue
;
2028 Set override validation failure behavior.
2030 Only effective if Veto was also called, and only allowed if event type
2031 is wxEVT_PG_CHANGING.
2033 void SetValidationFailureBehavior( int flags
)
2035 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2036 m_validationInfo
->m_failureBehavior
= (wxPGVFBFlags
) flags
;
2039 /** Sets custom failure message for this time only. Only applies if
2040 wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
2042 void SetValidationFailureMessage( const wxString
& message
)
2044 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2045 m_validationInfo
->m_failureMessage
= message
;
2049 wxPGVFBFlags
GetValidationFailureBehavior() const
2051 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2052 return m_validationInfo
->m_failureBehavior
;
2055 void SetCanVeto( bool canVeto
) { m_canVeto
= canVeto
; }
2056 bool WasVetoed() const { return m_wasVetoed
; }
2058 /** Changes the associated property. */
2059 void SetProperty( wxPGProperty
* p
) { m_property
= p
; }
2061 void SetPropertyGrid( wxPropertyGrid
* pg
) { m_pg
= pg
; }
2063 void SetupValidationInfo()
2066 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2067 m_validationInfo
= &m_pg
->GetValidationInfo();
2072 DECLARE_DYNAMIC_CLASS(wxPropertyGridEvent
)
2074 wxPGProperty
* m_property
;
2075 wxPropertyGrid
* m_pg
;
2076 wxPGValidationInfo
* m_validationInfo
;
2085 // -----------------------------------------------------------------------
2087 /** @class wxPropertyGridPopulator
2089 Allows populating wxPropertyGrid from arbitrary text source.
2091 class WXDLLIMPEXP_PROPGRID wxPropertyGridPopulator
2094 /** Default constructor.
2096 wxPropertyGridPopulator();
2099 virtual ~wxPropertyGridPopulator();
2101 void SetState( wxPropertyGridPageState
* state
);
2103 void SetGrid( wxPropertyGrid
* pg
);
2105 /** Appends a new property under bottommost parent.
2107 Property class as string.
2109 wxPGProperty
* Add( const wxString
& propClass
,
2110 const wxString
& propLabel
,
2111 const wxString
& propName
,
2112 const wxString
* propValue
,
2113 wxPGChoices
* pChoices
= NULL
);
2116 Pushes property to the back of parent array (ie it becomes bottommost
2117 parent), and starts scanning/adding children for it.
2119 When finished, parent array is returned to the original state.
2121 void AddChildren( wxPGProperty
* property
);
2123 /** Adds attribute to the bottommost property.
2125 Allowed values: "string", (same as string), "int", "bool". Empty string
2128 bool AddAttribute( const wxString
& name
,
2129 const wxString
& type
,
2130 const wxString
& value
);
2132 /** Called once in AddChildren.
2134 virtual void DoScanForChildren() = 0;
2137 Returns id of parent property for which children can currently be
2140 wxPGProperty
* GetCurParent() const
2142 return (wxPGProperty
*) m_propHierarchy
[m_propHierarchy
.size()-1];
2145 wxPropertyGridPageState
* GetState() { return m_state
; }
2146 const wxPropertyGridPageState
* GetState() const { return m_state
; }
2148 /** Like wxString::ToLong, except allows N% in addition of N.
2150 static bool ToLongPCT( const wxString
& s
, long* pval
, long max
);
2152 /** Parses strings of format "choice1"[=value1] ... "choiceN"[=valueN] into
2153 wxPGChoices. Registers parsed result using idString (if not empty).
2154 Also, if choices with given id already registered, then don't parse but
2155 return those choices instead.
2157 wxPGChoices
ParseChoices( const wxString
& choicesString
,
2158 const wxString
& idString
);
2160 /** Implement in derived class to do custom process when an error occurs.
2161 Default implementation uses wxLogError.
2163 virtual void ProcessError( const wxString
& msg
);
2167 /** Used property grid. */
2168 wxPropertyGrid
* m_pg
;
2170 /** Used property grid state. */
2171 wxPropertyGridPageState
* m_state
;
2173 /** Tree-hierarchy of added properties (that can have children). */
2174 wxArrayPGProperty m_propHierarchy
;
2176 /** Hashmap for string-id to wxPGChoicesData mapping. */
2177 wxPGHashMapS2P m_dictIdChoices
;
2180 // -----------------------------------------------------------------------
2183 // Undefine macros that are not needed outside propertygrid sources
2185 #ifndef __wxPG_SOURCE_FILE__
2186 #undef wxPG_FL_DESC_REFRESH_REQUIRED
2187 #undef wxPG_FL_SCROLLBAR_DETECTED
2188 #undef wxPG_FL_CREATEDSTATE
2189 #undef wxPG_FL_NOSTATUSBARHELP
2190 #undef wxPG_FL_SCROLLED
2191 #undef wxPG_FL_FOCUS_INSIDE_CHILD
2192 #undef wxPG_FL_FOCUS_INSIDE
2193 #undef wxPG_FL_MOUSE_INSIDE_CHILD
2194 #undef wxPG_FL_CUR_USES_CUSTOM_IMAGE
2195 #undef wxPG_FL_PRIMARY_FILLS_ENTIRE
2196 #undef wxPG_FL_VALUE_MODIFIED
2197 #undef wxPG_FL_MOUSE_INSIDE
2198 #undef wxPG_FL_FOCUSED
2199 #undef wxPG_FL_MOUSE_CAPTURED
2200 #undef wxPG_FL_INITIALIZED
2201 #undef wxPG_FL_ACTIVATION_BY_CLICK
2202 #undef wxPG_FL_DONT_CENTER_SPLITTER
2203 #undef wxPG_SUPPORT_TOOLTIPS
2204 #undef wxPG_DOUBLE_BUFFER
2205 #undef wxPG_ICON_WIDTH
2206 #undef wxPG_USE_RENDERER_NATIVE
2207 // Following are needed by the manager headers
2208 // #undef const wxString&
2213 #include "wx/propgrid/editor.h"
2214 #include "wx/propgrid/manager.h"
2217 // -----------------------------------------------------------------------
2219 #endif // _WX_PROPGRID_PROPGRID_H_