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 bool noDefCheck
= false );
889 /** Resets all colours to the original system values.
895 Editor widget is automatically created, but not focused unless focus is
896 true. This will generate wxEVT_PG_SELECT event.
900 True if selection finished successfully. Usually only fails if
901 current value in editor is not valid.
902 @see wxPropertyGrid::Unselect
904 bool SelectProperty( wxPGPropArg id
, bool focus
= false )
906 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
907 return DoSelectProperty(p
,focus
?wxPG_SEL_FOCUS
:0);
910 /** Changes keyboard shortcut to push the editor button.
912 You can set default with keycode 0. Good value for the platform is
913 guessed, but don't expect it to be very accurate.
915 void SetButtonShortcut( int keycode
,
916 bool ctrlDown
= false,
917 bool altDown
= false );
919 /** Sets category caption background colour. */
920 void SetCaptionBackgroundColour(const wxColour
& col
);
922 /** Sets category caption text colour. */
923 void SetCaptionTextColour(const wxColour
& col
);
925 /** Sets default cell background colour - applies to property cells.
926 Note that appearance of editor widgets may not be affected.
928 void SetCellBackgroundColour(const wxColour
& col
);
930 /** Sets cell text colour for disabled properties.
932 void SetCellDisabledTextColour(const wxColour
& col
);
934 /** Sets default cell text colour - applies to property name and value text.
935 Note that appearance of editor widgets may not be affected.
937 void SetCellTextColour(const wxColour
& col
);
939 /** Set number of columns (2 or more).
941 void SetColumnCount( int colCount
)
943 m_pState
->SetColumnCount(colCount
);
948 Sets the 'current' category - Append will add non-category properties
951 void SetCurrentCategory( wxPGPropArg id
)
953 wxPG_PROP_ARG_CALL_PROLOG()
954 wxPropertyCategory
* pc
= wxDynamicCast(p
, wxPropertyCategory
);
956 m_pState
->m_currentCategory
= pc
;
959 /** Sets colour of empty space below properties. */
960 void SetEmptySpaceColour(const wxColour
& col
);
962 /** Sets colour of lines between cells. */
963 void SetLineColour(const wxColour
& col
);
965 /** Sets background colour of margin. */
966 void SetMarginColour(const wxColour
& col
);
968 /** Sets background colour of property and all its children. Colours of
969 captions are not affected. Background brush cache is optimized for often
970 set colours to be set last.
972 void SetPropertyBackgroundColour( wxPGPropArg id
, const wxColour
& col
);
974 /** Resets text and background colours of given property.
976 void SetPropertyColoursToDefault( wxPGPropArg id
);
978 /** Sets text colour of property and all its children.
980 void SetPropertyTextColour( wxPGPropArg id
,
982 bool recursively
= true );
985 Sets selection background colour - applies to selected property name
988 void SetSelectionBackgroundColour(const wxColour
& col
);
991 Sets selection foreground colour - applies to selected property name
994 void SetSelectionTextColour(const wxColour
& col
);
996 /** Sets x coordinate of the splitter.
998 Splitter position cannot exceed grid size, and therefore setting it
999 during form creation may fail as initial grid size is often smaller
1000 than desired splitter position, especially when sizers are being used.
1002 void SetSplitterPosition( int newxpos
, int col
= 0 )
1004 DoSetSplitterPosition_(newxpos
, true, col
);
1005 m_iFlags
|= wxPG_FL_SPLITTER_PRE_SET
;
1008 /** Set virtual width for this particular page. Width -1 indicates that the
1009 virtual width should be disabled. */
1010 void SetVirtualWidth( int width
);
1012 /** Sets name of a property.
1014 Name or pointer of property which name to change.
1018 void SetPropertyName( wxPGPropArg id
, const wxString
& newname
)
1020 wxPG_PROP_ARG_CALL_PROLOG()
1021 DoSetPropertyName( p
, newname
);
1024 /** Moves splitter as left as possible, while still allowing all
1025 labels to be shown in full.
1027 If false, will still allow sub-properties (ie. properties which
1028 parent is not root or category) to be cropped.
1030 void SetSplitterLeft( bool subProps
= false )
1032 m_pState
->SetSplitterLeft(subProps
);
1035 /** Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
1036 height. Value of 2 should be default on most platforms.
1038 On wxMSW, wxComboBox, when used as property editor widget, will spill
1039 out with anything less than 3.
1041 void SetVerticalSpacing( int vspacing
)
1043 m_vspacing
= (unsigned char)vspacing
;
1044 CalculateFontAndBitmapStuff( vspacing
);
1045 if ( !m_pState
->m_itemsAdded
) Refresh();
1048 /** Shows an brief error message that is related to a property. */
1049 void ShowPropertyError( wxPGPropArg id
, const wxString
& msg
)
1051 wxPG_PROP_ARG_CALL_PROLOG()
1052 DoShowPropertyError(p
, msg
);
1055 /** Sorts all items at all levels (except sub-properties). */
1058 /** Sorts children of a category.
1060 void SortChildren( wxPGPropArg id
);
1062 /////////////////////////////////////////////////////////////////
1064 // Following methods do not need to be (currently) documented
1066 /////////////////////////////////////////////////////////////////
1068 bool HasVirtualWidth() const
1069 { return (m_iFlags
& wxPG_FL_HAS_VIRTUAL_WIDTH
) ? true : false; }
1071 const wxPGCommonValue
* GetCommonValue( unsigned int i
) const
1073 return (wxPGCommonValue
*) m_commonValues
[i
];
1076 /** Returns number of common values.
1078 unsigned int GetCommonValueCount() const
1080 return m_commonValues
.size();
1083 /** Returns label of given common value.
1085 wxString
GetCommonValueLabel( unsigned int i
) const
1087 wxASSERT( GetCommonValue(i
) );
1088 return GetCommonValue(i
)->GetLabel();
1092 Returns index of common value that will truly change value to
1095 int GetUnspecifiedCommonValue() const { return m_cvUnspecified
; }
1097 /** Set index of common value that will truly change value to unspecified.
1098 Using -1 will set none to have such effect.
1101 void SetUnspecifiedCommonValue( int index
) { m_cvUnspecified
= index
; }
1104 Shortcut for creating dialog-caller button. Used, for example, by
1107 This should only be called by properties.
1109 wxWindow
* GenerateEditorButton( const wxPoint
& pos
, const wxSize
& sz
);
1111 /** Fixes position of wxTextCtrl-like control (wxSpinCtrl usually
1112 fits as one). Call after control has been created (but before
1115 void FixPosForTextCtrl( wxWindow
* ctrl
,
1116 const wxPoint
& offset
= wxPoint(0, 0) );
1118 /** Shortcut for creating text editor widget.
1120 Same as pos given for CreateEditor.
1122 Same as sz given for CreateEditor.
1124 Initial text for wxTextCtrl.
1126 If right-side control, such as button, also created, then create it
1127 first and pass it as this parameter.
1129 Extra style flags to pass for wxTextCtrl.
1131 Note that this should generally be called only by new classes derived
1134 wxWindow
* GenerateEditorTextCtrl( const wxPoint
& pos
,
1136 const wxString
& value
,
1137 wxWindow
* secondary
,
1141 /* Generates both textctrl and button.
1143 wxWindow
* GenerateEditorTextCtrlAndButton( const wxPoint
& pos
,
1144 const wxSize
& sz
, wxWindow
** psecondary
, int limited_editing
,
1145 wxPGProperty
* property
);
1147 /** Generates position for a widget editor dialog box.
1149 Property for which dialog is positioned.
1151 Known or over-approximated size of the dialog.
1153 Position for dialog.
1155 wxPoint
GetGoodEditorDialogPosition( wxPGProperty
* p
,
1158 // Converts escape sequences in src_str to newlines,
1159 // tabs, etc. and copies result to dst_str.
1160 static wxString
& ExpandEscapeSequences( wxString
& dst_str
,
1161 wxString
& src_str
);
1163 // Converts newlines, tabs, etc. in src_str to escape
1164 // sequences, and copies result to dst_str.
1165 static wxString
& CreateEscapeSequences( wxString
& dst_str
,
1166 wxString
& src_str
);
1169 Returns rectangle that fully contains properties between and including
1172 wxRect
GetPropertyRect( const wxPGProperty
* p1
,
1173 const wxPGProperty
* p2
) const;
1175 /** Returns pointer to current active primary editor control (NULL if none).
1177 If editor uses clipper window, pointer is returned to the actual
1178 editor, not the clipper.
1180 wxWindow
* GetEditorControl() const;
1182 /** Adjusts given position if topCtrlWnd is child of clipper window.
1184 bool AdjustPosForClipperWindow( wxWindow
* topCtrlWnd
, int* x
, int* y
);
1186 wxWindow
* GetPrimaryEditor() const
1188 return GetEditorControl();
1192 Returns pointer to current active secondary editor control (NULL if
1195 wxWindow
* GetEditorControlSecondary() const
1197 return m_wndEditor2
;
1203 Generates contents for string dst based on the contents of
1206 Format will be "(preDelim)str1(postDelim) (preDelim)str2(postDelim) and
1207 so on. Set flags to 1 inorder to convert backslashes to double-back-
1208 slashes and "(preDelims)"'s to "(preDelims)".
1210 static void ArrayStringToString( wxString
& dst
, const wxArrayString
& src
,
1211 wxChar preDelim
, wxChar postDelim
,
1214 // Mostly useful for page switching.
1215 void SwitchState( wxPropertyGridPageState
* pNewState
);
1217 /** Pass this function to Connect calls in propertyclass::CreateEditor.
1219 void OnCustomEditorEvent( wxCommandEvent
&event
);
1221 long GetInternalFlags() const { return m_iFlags
; }
1222 void SetInternalFlag( long flag
) { m_iFlags
|= flag
; }
1223 void ClearInternalFlag( long flag
) { m_iFlags
&= ~(flag
); }
1224 void IncFrozen() { m_frozen
++; }
1225 void DecFrozen() { m_frozen
--; }
1227 void OnComboItemPaint( wxPGCustomComboControl
* pCb
,int item
,wxDC
& dc
,
1228 wxRect
& rect
,int flags
);
1230 // Used by simple check box for keyboard navigation
1231 void SendNavigationKeyEvent( int dir
);
1233 /** Standardized double-to-string conversion.
1235 static void DoubleToString( wxString
& target
,
1239 wxString
* precTemplate
);
1242 Call this from wxPGProperty::OnEvent() to cause property value to be
1243 changed after the function returns (with true as return value).
1244 ValueChangeInEvent() must be used if you wish the application to be
1245 able to use wxEVT_PG_CHANGING to potentially veto the given value.
1247 void ValueChangeInEvent( wxVariant variant
)
1249 m_changeInEventValue
= variant
;
1250 m_iFlags
|= wxPG_FL_VALUE_CHANGE_IN_EVENT
;
1253 /** Returns true if given event is from first of an array of buttons
1254 (as can be in case when wxPGMultiButton is used).
1256 bool IsMainButtonEvent( const wxEvent
& event
)
1258 return (event
.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED
)
1259 && (m_wndSecId
== event
.GetId());
1262 /** Pending value is expected to be passed in PerformValidation().
1264 virtual bool DoPropertyChanged( wxPGProperty
* p
,
1265 unsigned int selFlags
= 0 );
1268 Runs all validation functionality (includes sending wxEVT_PG_CHANGING).
1269 Returns true if all tests passed.
1271 virtual bool PerformValidation( wxPGProperty
* p
, wxVariant
& pendingValue
);
1273 /** Called when validation for given property fails.
1275 Value which failed in validation.
1277 Return true if user is allowed to change to another property even
1278 if current has invalid value.
1280 To add your own validation failure behavior, override
1281 wxPropertyGrid::DoOnValidationFailure().
1283 bool OnValidationFailure( wxPGProperty
* property
, wxVariant
& invalidValue
)
1285 bool res
= DoOnValidationFailure(property
, invalidValue
);
1286 property
->SetFlag(wxPG_PROP_INVALID_VALUE
);
1290 /** Called to indicate property and editor has valid value now.
1292 void OnValidationFailureReset( wxPGProperty
* property
)
1294 if ( property
&& property
->HasFlag(wxPG_PROP_INVALID_VALUE
) )
1296 DoOnValidationFailureReset(property
);
1297 property
->ClearFlag(wxPG_PROP_INVALID_VALUE
);
1299 m_validationInfo
.m_failureMessage
.clear();
1302 /** Override in derived class to display error messages in custom manner
1303 (these message usually only result from validation failure).
1305 virtual void DoShowPropertyError( wxPGProperty
* property
,
1306 const wxString
& msg
);
1308 /** Override to customize property validation failure behavior.
1310 Value which failed in validation.
1312 Return true if user is allowed to change to another property even
1313 if current has invalid value.
1315 virtual bool DoOnValidationFailure( wxPGProperty
* property
,
1316 wxVariant
& invalidValue
);
1318 /** Override to customize resetting of property validation failure status.
1320 Property is guaranteed to have flag wxPG_PROP_INVALID_VALUE set.
1322 virtual void DoOnValidationFailureReset( wxPGProperty
* property
);
1324 int GetSpacingY() const { return m_spacingy
; }
1327 Must be called in wxPGEditor::CreateControls() if primary editor window
1328 is wxTextCtrl, just before textctrl is created.
1330 Initial text value of created wxTextCtrl.
1332 void SetupTextCtrlValue( const wxString text
) { m_prevTcValue
= text
; }
1335 Unfocuses or closes editor if one was open, but does not deselect
1338 bool UnfocusEditor();
1343 wxPropertyGridPageState used by the grid is created here.
1345 If grid is used in wxPropertyGridManager, there is no point overriding
1346 this - instead, set custom wxPropertyGridPage classes.
1348 virtual wxPropertyGridPageState
* CreateState() const;
1353 // Control font changer helper.
1354 void SetCurControlBoldFont();
1357 // Public methods for semi-public use
1358 // (not protected for optimization)
1360 bool DoSelectProperty( wxPGProperty
* p
, unsigned int flags
= 0 );
1362 // Overridden functions.
1363 virtual bool Destroy();
1364 virtual wxSize
DoGetBestSize() const;
1365 // Returns property at given y coordinate (relative to grid's top left).
1366 wxPGProperty
* GetItemAtY( int y
) const { return DoGetItemAtY(y
); }
1368 virtual void Refresh( bool eraseBackground
= true,
1369 const wxRect
*rect
= (const wxRect
*) NULL
);
1370 virtual bool SetFont( const wxFont
& font
);
1371 #if wxPG_SUPPORT_TOOLTIPS
1372 void SetToolTip( const wxString
& tipString
);
1374 virtual void Freeze();
1375 virtual void SetExtraStyle( long exStyle
);
1376 virtual void Thaw();
1381 #ifndef wxPG_ICON_WIDTH
1382 wxBitmap
*m_expandbmp
, *m_collbmp
;
1385 wxCursor
*m_cursorSizeWE
;
1387 /** wxWindow pointers to editor control(s). */
1388 wxWindow
*m_wndEditor
;
1389 wxWindow
*m_wndEditor2
;
1391 /** wxPGCanvas instance. */
1394 #if wxPG_DOUBLE_BUFFER
1395 wxBitmap
*m_doubleBuffer
;
1398 wxArrayPtrVoid
*m_windowsToDelete
;
1400 /** Local time ms when control was created. */
1401 wxLongLong m_timeCreated
;
1403 /** wxPGProperty::OnEvent can change value by setting this. */
1404 wxVariant m_changeInEventValue
;
1406 /** Id of m_wndEditor2, or its first child, if any. */
1409 /** Extra Y spacing between the items. */
1412 /** Control client area width; updated on resize. */
1415 /** Control client area height; updated on resize. */
1418 /** Current non-client width (needed when auto-centering). */
1421 /** Non-client width (auto-centering helper). */
1424 /** Previously recorded scroll start position. */
1428 The gutter spacing in front and back of the image.
1429 This determines the amount of spacing in front of each item
1433 /** Includes separator line. */
1436 /** Gutter*2 + image width. */
1439 // y spacing for expand/collapse button.
1440 int m_buttonSpacingY
;
1442 /** Extra margin for expanded sub-group items. */
1443 int m_subgroup_extramargin
;
1446 The image width of the [+] icon.
1448 This is also calculated in the gutter
1452 #ifndef wxPG_ICON_WIDTH
1455 The image height of the [+] icon.
1457 This is calculated as minimal size and to align
1462 /** Current cursor id. */
1466 This captionFont is made equal to the font of the wxScrolledWindow.
1468 As extra the bold face is set on it when this is wanted by the user
1471 wxFont m_captionFont
;
1473 int m_fontHeight
; // Height of the font.
1475 // Base keycode for triggering push button.
1476 int m_pushButKeyCode
;
1478 /** m_splitterx when drag began. */
1479 int m_startingSplitterX
;
1482 Index to splitter currently being dragged (0=one after the first
1485 int m_draggedSplitter
;
1487 /** Changed property, calculated in PerformValidation(). */
1488 wxPGProperty
* m_chgInfo_changedProperty
;
1491 Lowest property for which editing happened, but which does not have
1494 wxPGProperty
* m_chgInfo_baseChangedProperty
;
1496 /** Changed property value, calculated in PerformValidation(). */
1497 wxVariant m_chgInfo_pendingValue
;
1499 /** Passed to SetValue. */
1500 wxVariant m_chgInfo_valueList
;
1502 /** Validation information. */
1503 wxPGValidationInfo m_validationInfo
;
1505 /** Actions and keys that trigger them. */
1506 wxPGHashMapI2I m_actionTriggers
;
1512 /** Bits are used to indicate which colours are customized. */
1513 unsigned short m_coloursCustomized
;
1515 /** x - m_splitterx. */
1516 signed char m_dragOffset
;
1518 /** 0 = not dragging, 1 = drag just started, 2 = drag in progress */
1519 unsigned char m_dragStatus
;
1521 /** 0 = margin, 1 = label, 2 = value. */
1522 unsigned char m_mouseSide
;
1524 /** True when editor control is focused. */
1525 unsigned char m_editorFocused
;
1527 /** 1 if m_latsCaption is also the bottommost caption. */
1528 //unsigned char m_lastCaptionBottomnest;
1530 /** Set to 1 when graphics frozen. */
1531 unsigned char m_frozen
;
1533 unsigned char m_vspacing
;
1535 // Does triggering push button need Alt down?
1536 unsigned char m_pushButKeyCodeNeedsAlt
;
1538 // Does triggering push button need Ctrl down?
1539 unsigned char m_pushButKeyCodeNeedsCtrl
;
1541 // Used to track when Alt/Ctrl+Key was consumed.
1542 unsigned char m_keyComboConsumed
;
1544 /** 1 if in DoPropertyChanged() */
1545 unsigned char m_inDoPropertyChanged
;
1547 /** 1 if in CommitChangesFromEditor() */
1548 unsigned char m_inCommitChangesFromEditor
;
1550 /** 1 if in DoSelectProperty() */
1551 unsigned char m_inDoSelectProperty
;
1553 wxPGVFBFlags m_permanentValidationFailureBehavior
; // Set by app
1555 /** Internal flags - see wxPG_FL_XXX constants. */
1558 /** When drawing next time, clear this many item slots at the end. */
1559 int m_clearThisMany
;
1561 /** Pointer to selected property. Note that this is duplicated in
1562 m_state for better transiency between pages so that the selected
1563 item can be retained.
1565 wxPGProperty
* m_selected
;
1567 // pointer to property that has mouse hovering
1568 wxPGProperty
* m_propHover
;
1570 // EventObject for wxPropertyGridEvents
1571 wxWindow
* m_eventObject
;
1573 // What (global) window is currently focused (needed to resolve event
1575 wxWindow
* m_curFocused
;
1578 wxEvtHandler
* m_tlwHandler
;
1583 // y coordinate of property that mouse hovering
1585 // Which column's editor is selected (usually 1)?
1588 // x relative to splitter (needed for resize).
1591 // lines between cells
1593 // property labels and values are written in this colour
1594 wxColour m_colPropFore
;
1595 // or with this colour when disabled
1596 wxColour m_colDisPropFore
;
1597 // background for m_colPropFore
1598 wxColour m_colPropBack
;
1599 // text color for captions
1600 wxColour m_colCapFore
;
1601 // background color for captions
1602 wxColour m_colCapBack
;
1603 // foreground for selected property
1604 wxColour m_colSelFore
;
1605 // background for selected property (actually use background color when
1606 // control out-of-focus)
1607 wxColour m_colSelBack
;
1608 // background colour for margin
1609 wxColour m_colMargin
;
1610 // background colour for empty space below the grid
1611 wxColour m_colEmptySpace
;
1613 // NB: These *cannot* be moved to globals.
1615 // Array of background colour brushes.
1616 wxArrayPtrVoid m_arrBgBrushes
;
1617 // Array of foreground colours.
1618 wxArrayPtrVoid m_arrFgCols
;
1620 // labels when properties use common values
1621 wxArrayPtrVoid m_commonValues
;
1622 // Which cv selection really sets value to unspecified?
1623 int m_cvUnspecified
;
1625 // Used to skip excess text editor events
1626 wxString m_prevTcValue
;
1630 // Sets some members to defaults (called constructors).
1633 // Initializes some members (called by Create and complex constructor).
1636 void OnPaint(wxPaintEvent
&event
);
1638 // main event receivers
1639 void OnMouseMove( wxMouseEvent
&event
);
1640 void OnMouseMoveBottom( wxMouseEvent
&event
);
1641 void OnMouseClick( wxMouseEvent
&event
);
1642 void OnMouseRightClick( wxMouseEvent
&event
);
1643 void OnMouseDoubleClick( wxMouseEvent
&event
);
1644 void OnMouseUp( wxMouseEvent
&event
);
1645 void OnKey( wxKeyEvent
&event
);
1646 void OnKeyUp( wxKeyEvent
&event
);
1647 void OnNavigationKey( wxNavigationKeyEvent
& event
);
1648 void OnResize( wxSizeEvent
&event
);
1651 bool HandleMouseMove( int x
, unsigned int y
, wxMouseEvent
&event
);
1652 bool HandleMouseClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1653 bool HandleMouseRightClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1654 bool HandleMouseDoubleClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1655 bool HandleMouseUp( int x
, unsigned int y
, wxMouseEvent
&event
);
1656 void HandleKeyEvent( wxKeyEvent
&event
);
1657 // Handle TAB and ESCAPE in control
1658 bool HandleChildKey( wxKeyEvent
& event
);
1660 void OnMouseEntry( wxMouseEvent
&event
);
1662 void OnIdle( wxIdleEvent
&event
);
1663 void OnFocusEvent( wxFocusEvent
&event
);
1664 void OnChildFocusEvent( wxChildFocusEvent
& event
);
1666 bool OnMouseCommon( wxMouseEvent
&event
, int* px
, int *py
);
1667 bool OnMouseChildCommon( wxMouseEvent
&event
, int* px
, int *py
);
1669 // sub-control event handlers
1670 void OnMouseClickChild( wxMouseEvent
&event
);
1671 void OnMouseRightClickChild( wxMouseEvent
&event
);
1672 void OnMouseMoveChild( wxMouseEvent
&event
);
1673 void OnMouseUpChild( wxMouseEvent
&event
);
1674 void OnChildKeyDown( wxKeyEvent
&event
);
1675 void OnChildKeyUp( wxKeyEvent
&event
);
1677 void OnCaptureChange( wxMouseCaptureChangedEvent
&event
);
1679 void OnScrollEvent( wxScrollWinEvent
&event
);
1681 void OnSysColourChanged( wxSysColourChangedEvent
&event
);
1686 Adjust the centering of the bitmap icons (collapse / expand) when the
1687 caption font changes.
1689 They need to be centered in the middle of the font, so a bit of deltaY
1690 adjustment is needed. On entry, m_captionFont must be set to window
1691 font. It will be modified properly.
1693 void CalculateFontAndBitmapStuff( int vspacing
);
1695 wxRect
GetEditorWidgetRect( wxPGProperty
* p
, int column
) const;
1697 void CorrectEditorWidgetSizeX();
1699 /** Called in RecalculateVirtualSize() to reposition control
1700 on virtual height changes.
1702 void CorrectEditorWidgetPosY();
1706 void OnScreenNote( const wxChar
* format
, ... );
1709 /** Deselect current selection, if any. Returns true if success
1710 (ie. validator did not intercept). */
1711 bool DoClearSelection();
1713 int DoDrawItems( wxDC
& dc
,
1714 const wxPGProperty
* first_item
,
1715 const wxPGProperty
* last_item
,
1716 const wxRect
* clip_rect
,
1717 bool isBuffered
) const;
1719 void DoSetPropertyValueUnspecified( wxPGProperty
* p
);
1721 /** Draws an expand/collapse (ie. +/-) button.
1723 virtual void DrawExpanderButton( wxDC
& dc
, const wxRect
& rect
,
1724 wxPGProperty
* property
) const;
1726 /** Draws items from topitemy to bottomitemy */
1727 void DrawItems( wxDC
& dc
, unsigned int topitemy
, unsigned int bottomitemy
,
1728 const wxRect
* clip_rect
= (const wxRect
*) NULL
);
1730 void DrawItems( const wxPGProperty
* p1
, const wxPGProperty
* p2
);
1732 void DrawItem( wxPGProperty
* p
)
1737 virtual void DrawItemAndChildren( wxPGProperty
* p
);
1740 Draws item, children, and consequtive parents as long as category is
1743 void DrawItemAndValueRelated( wxPGProperty
* p
);
1745 // Translate wxKeyEvent to wxPG_ACTION_XXX
1746 int KeyEventToActions(wxKeyEvent
&event
, int* pSecond
) const;
1748 int KeyEventToAction(wxKeyEvent
&event
) const
1750 return KeyEventToActions(event
, NULL
);
1753 void ImprovedClientToScreen( int* px
, int* py
);
1755 // Called by focus event handlers. newFocused is the window that becomes
1757 void HandleFocusChange( wxWindow
* newFocused
);
1759 /** Reloads all non-customized colours from system settings. */
1760 void RegainColours();
1762 bool DoEditorValidate();
1764 wxPGProperty
* DoGetItemAtY( int y
) const;
1766 void DoSetSplitterPosition_( int newxpos
,
1767 bool refresh
= true,
1768 int splitterIndex
= 0,
1769 bool allPages
= false );
1773 virtual bool DoExpand( wxPGProperty
* p
, bool sendEvent
= false );
1775 virtual bool DoCollapse( wxPGProperty
* p
, bool sendEvent
= false );
1777 // Returns nearest paint visible property (such that will be painted unless
1778 // window is scrolled or resized). If given property is paint visible, then
1779 // it itself will be returned.
1780 wxPGProperty
* GetNearestPaintVisible( wxPGProperty
* p
) const;
1782 static void RegisterDefaultEditors();
1784 // Sets m_bgColIndex to this property and all its children.
1785 void SetBackgroundColourIndex( wxPGProperty
* p
, int index
);
1787 // Sets m_fgColIndex to this property and all its children.
1788 void SetTextColourIndex( wxPGProperty
* p
, int index
, int flags
);
1790 int CacheColour( const wxColour
& colour
);
1792 void DoSetPropertyName( wxPGProperty
* p
, const wxString
& newname
);
1794 // Sets up basic event handling for child control
1795 void SetupChildEventHandling( wxWindow
* wnd
, int id
);
1797 void CustomSetCursor( int type
, bool override
= false );
1799 virtual bool ProcessEvent(wxEvent
& event
);
1800 virtual void SetWindowStyleFlag( long style
);
1803 Repositions scrollbar and underlying panel according to changed virtual
1806 void RecalculateVirtualSize( int forceXPos
= -1 );
1808 void PrepareAfterItemsAdded();
1810 bool SendEvent( int eventType
,
1812 wxVariant
* pValue
= NULL
,
1813 unsigned int selFlags
= 0 );
1815 void SetFocusOnCanvas()
1817 m_canvas
->SetFocusIgnoringChildren();
1818 m_editorFocused
= 0;
1821 bool DoHideProperty( wxPGProperty
* p
, bool hide
, int flags
);
1825 bool ButtonTriggerKeyTest( wxKeyEvent
&event
);
1827 #endif // DOXYGEN_SHOULD_SKIP_THIS
1830 DECLARE_EVENT_TABLE()
1831 #endif // #ifndef SWIG
1834 // -----------------------------------------------------------------------
1836 // Bunch of inlines that need to resolved after all classes have been defined.
1840 inline bool wxPropertyGridPageState::IsDisplayed() const
1842 return ( this == m_pPropGrid
->GetState() );
1845 inline unsigned int wxPropertyGridPageState::GetActualVirtualHeight() const
1847 return DoGetRoot()->GetChildrenHeight(GetGrid()->GetRowHeight());
1851 inline int wxPGProperty::GetDisplayedCommonValueCount() const
1853 if ( HasFlag(wxPG_PROP_USES_COMMON_VALUE
) )
1855 wxPropertyGrid
* pg
= GetGrid();
1857 return pg
->GetCommonValueCount();
1862 inline void wxPGProperty::SetEditor( const wxString
& editorName
)
1864 m_customEditor
= wxPropertyGridInterface::GetEditorByName(editorName
);
1867 inline void wxPGProperty::SetName( const wxString
& newName
)
1869 GetGrid()->SetPropertyName(this, newName
);
1872 inline bool wxPGProperty::Hide( bool hide
, int flags
)
1874 return GetGrid()->HideProperty(this, hide
, flags
);
1877 inline bool wxPGProperty::SetMaxLength( int maxLen
)
1879 return GetGrid()->SetPropertyMaxLength(this,maxLen
);
1882 // -----------------------------------------------------------------------
1887 #define wxPG_BASE_EVT_PRE_ID 1775
1889 BEGIN_DECLARE_EVENT_TYPES()
1890 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_SELECTED
, wxPG_BASE_EVT_PRE_ID
)
1891 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_CHANGING
, wxPG_BASE_EVT_PRE_ID
+1)
1892 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_CHANGED
, wxPG_BASE_EVT_PRE_ID
+2)
1893 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_HIGHLIGHTED
, wxPG_BASE_EVT_PRE_ID
+3)
1894 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_RIGHT_CLICK
, wxPG_BASE_EVT_PRE_ID
+4)
1895 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_PAGE_CHANGED
, wxPG_BASE_EVT_PRE_ID
+5)
1896 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_ITEM_COLLAPSED
, wxPG_BASE_EVT_PRE_ID
+6)
1897 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_ITEM_EXPANDED
, wxPG_BASE_EVT_PRE_ID
+7)
1898 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_DOUBLE_CLICK
, wxPG_BASE_EVT_PRE_ID
+8)
1899 END_DECLARE_EVENT_TYPES()
1902 wxEVT_PG_SELECTED
= wxPG_BASE_EVT_PRE_ID
,
1905 wxEVT_PG_HIGHLIGHTED
,
1906 wxEVT_PG_RIGHT_CLICK
,
1907 wxEVT_PG_PAGE_CHANGED
,
1908 wxEVT_PG_ITEM_COLLAPSED
,
1909 wxEVT_PG_ITEM_EXPANDED
,
1910 wxEVT_PG_DOUBLE_CLICK
1915 #define wxPG_BASE_EVT_TYPE wxEVT_PG_SELECTED
1916 #define wxPG_MAX_EVT_TYPE (wxPG_BASE_EVT_TYPE+30)
1920 typedef void (wxEvtHandler::*wxPropertyGridEventFunction
)(wxPropertyGridEvent
&);
1922 #define EVT_PG_SELECTED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_SELECTED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1923 #define EVT_PG_CHANGING(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGING, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1924 #define EVT_PG_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1925 #define EVT_PG_HIGHLIGHTED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_HIGHLIGHTED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1926 #define EVT_PG_RIGHT_CLICK(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_RIGHT_CLICK, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1927 #define EVT_PG_DOUBLE_CLICK(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_DOUBLE_CLICK, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1928 #define EVT_PG_PAGE_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_PAGE_CHANGED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1929 #define EVT_PG_ITEM_COLLAPSED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_COLLAPSED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1930 #define EVT_PG_ITEM_EXPANDED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_EXPANDED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1932 #define wxPropertyGridEventHandler(A) \
1933 ((wxObjectEventFunction)(wxEventFunction)(wxPropertyGridEventFunction)&A)
1938 /** @class wxPropertyGridEvent
1940 A propertygrid event holds information about events associated with
1941 wxPropertyGrid objects.
1943 @library{wxpropgrid}
1946 class WXDLLIMPEXP_PROPGRID wxPropertyGridEvent
: public wxCommandEvent
1951 wxPropertyGridEvent(wxEventType commandType
=0, int id
=0);
1953 /** Copy constructor. */
1954 wxPropertyGridEvent(const wxPropertyGridEvent
& event
);
1957 ~wxPropertyGridEvent();
1960 virtual wxEvent
* Clone() const;
1962 wxPGProperty
* GetMainParent() const
1964 wxASSERT(m_property
);
1965 return m_property
->GetMainParent();
1968 /** Returns id of associated property. */
1969 wxPGProperty
* GetProperty() const
1974 wxPGValidationInfo
& GetValidationInfo()
1976 wxASSERT(m_validationInfo
);
1977 return *m_validationInfo
;
1980 /** Returns true if event has associated property. */
1981 bool HasProperty() const { return ( m_property
!= (wxPGProperty
*) NULL
); }
1983 /** Returns true if you can veto the action that the event is signaling.
1985 bool CanVeto() const { return m_canVeto
; }
1988 Call this from your event handler to veto action that the event is
1991 You can only veto a shutdown if wxPropertyGridEvent::CanVeto returns
1994 Currently only wxEVT_PG_CHANGING supports vetoing.
1996 void Veto( bool veto
= true ) { m_wasVetoed
= veto
; }
1998 /** Returns value that is about to be set for wxEVT_PG_CHANGING.
2000 const wxVariant
& GetValue() const
2002 wxASSERT_MSG( m_validationInfo
,
2003 "Only call GetValue from a handler "
2004 "of event type that supports it" );
2005 return *m_validationInfo
->m_pValue
;
2009 Set override validation failure behavior.
2011 Only effective if Veto was also called, and only allowed if event type
2012 is wxEVT_PG_CHANGING.
2014 void SetValidationFailureBehavior( int flags
)
2016 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2017 m_validationInfo
->m_failureBehavior
= (wxPGVFBFlags
) flags
;
2020 /** Sets custom failure message for this time only. Only applies if
2021 wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
2023 void SetValidationFailureMessage( const wxString
& message
)
2025 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2026 m_validationInfo
->m_failureMessage
= message
;
2030 wxPGVFBFlags
GetValidationFailureBehavior() const
2032 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2033 return m_validationInfo
->m_failureBehavior
;
2036 void SetCanVeto( bool canVeto
) { m_canVeto
= canVeto
; }
2037 bool WasVetoed() const { return m_wasVetoed
; }
2039 /** Changes the associated property. */
2040 void SetProperty( wxPGProperty
* p
) { m_property
= p
; }
2042 void SetPropertyGrid( wxPropertyGrid
* pg
) { m_pg
= pg
; }
2044 void SetupValidationInfo()
2047 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2048 m_validationInfo
= &m_pg
->GetValidationInfo();
2053 DECLARE_DYNAMIC_CLASS(wxPropertyGridEvent
)
2055 wxPGProperty
* m_property
;
2056 wxPropertyGrid
* m_pg
;
2057 wxPGValidationInfo
* m_validationInfo
;
2066 // -----------------------------------------------------------------------
2068 /** @class wxPropertyGridPopulator
2070 Allows populating wxPropertyGrid from arbitrary text source.
2072 class WXDLLIMPEXP_PROPGRID wxPropertyGridPopulator
2075 /** Default constructor.
2077 wxPropertyGridPopulator();
2080 virtual ~wxPropertyGridPopulator();
2082 void SetState( wxPropertyGridPageState
* state
);
2084 void SetGrid( wxPropertyGrid
* pg
);
2086 /** Appends a new property under bottommost parent.
2088 Property class as string.
2090 wxPGProperty
* Add( const wxString
& propClass
,
2091 const wxString
& propLabel
,
2092 const wxString
& propName
,
2093 const wxString
* propValue
,
2094 wxPGChoices
* pChoices
= NULL
);
2097 Pushes property to the back of parent array (ie it becomes bottommost
2098 parent), and starts scanning/adding children for it.
2100 When finished, parent array is returned to the original state.
2102 void AddChildren( wxPGProperty
* property
);
2104 /** Adds attribute to the bottommost property.
2106 Allowed values: "string", (same as string), "int", "bool". Empty string
2109 bool AddAttribute( const wxString
& name
,
2110 const wxString
& type
,
2111 const wxString
& value
);
2113 /** Called once in AddChildren.
2115 virtual void DoScanForChildren() = 0;
2118 Returns id of parent property for which children can currently be
2121 wxPGProperty
* GetCurParent() const
2123 return (wxPGProperty
*) m_propHierarchy
[m_propHierarchy
.size()-1];
2126 wxPropertyGridPageState
* GetState() { return m_state
; }
2127 const wxPropertyGridPageState
* GetState() const { return m_state
; }
2129 /** Like wxString::ToLong, except allows N% in addition of N.
2131 static bool ToLongPCT( const wxString
& s
, long* pval
, long max
);
2133 /** Parses strings of format "choice1"[=value1] ... "choiceN"[=valueN] into
2134 wxPGChoices. Registers parsed result using idString (if not empty).
2135 Also, if choices with given id already registered, then don't parse but
2136 return those choices instead.
2138 wxPGChoices
ParseChoices( const wxString
& choicesString
,
2139 const wxString
& idString
);
2141 /** Implement in derived class to do custom process when an error occurs.
2142 Default implementation uses wxLogError.
2144 virtual void ProcessError( const wxString
& msg
);
2148 /** Used property grid. */
2149 wxPropertyGrid
* m_pg
;
2151 /** Used property grid state. */
2152 wxPropertyGridPageState
* m_state
;
2154 /** Tree-hierarchy of added properties (that can have children). */
2155 wxArrayPGProperty m_propHierarchy
;
2157 /** Hashmap for string-id to wxPGChoicesData mapping. */
2158 wxPGHashMapS2P m_dictIdChoices
;
2161 // -----------------------------------------------------------------------
2164 // Undefine macros that are not needed outside propertygrid sources
2166 #ifndef __wxPG_SOURCE_FILE__
2167 #undef wxPG_FL_DESC_REFRESH_REQUIRED
2168 #undef wxPG_FL_SCROLLBAR_DETECTED
2169 #undef wxPG_FL_CREATEDSTATE
2170 #undef wxPG_FL_NOSTATUSBARHELP
2171 #undef wxPG_FL_SCROLLED
2172 #undef wxPG_FL_FOCUS_INSIDE_CHILD
2173 #undef wxPG_FL_FOCUS_INSIDE
2174 #undef wxPG_FL_MOUSE_INSIDE_CHILD
2175 #undef wxPG_FL_CUR_USES_CUSTOM_IMAGE
2176 #undef wxPG_FL_PRIMARY_FILLS_ENTIRE
2177 #undef wxPG_FL_VALUE_MODIFIED
2178 #undef wxPG_FL_MOUSE_INSIDE
2179 #undef wxPG_FL_FOCUSED
2180 #undef wxPG_FL_MOUSE_CAPTURED
2181 #undef wxPG_FL_INITIALIZED
2182 #undef wxPG_FL_ACTIVATION_BY_CLICK
2183 #undef wxPG_FL_DONT_CENTER_SPLITTER
2184 #undef wxPG_SUPPORT_TOOLTIPS
2185 #undef wxPG_DOUBLE_BUFFER
2186 #undef wxPG_ICON_WIDTH
2187 #undef wxPG_USE_RENDERER_NATIVE
2188 // Following are needed by the manager headers
2189 // #undef const wxString&
2194 #include "wx/propgrid/editor.h"
2195 #include "wx/propgrid/manager.h"
2198 // -----------------------------------------------------------------------
2202 #endif // _WX_PROPGRID_PROPGRID_H_