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_DATA_PROPGRID(const char) 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 wxVector
<wxValidator
*> 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,
244 /** Hides page selection buttons from toolbar.
246 wxPG_EX_HIDE_PAGE_BUTTONS
= 0x01000000
250 /** Combines various styles.
252 #define wxPG_DEFAULT_STYLE (0)
254 /** Combines various styles.
256 #define wxPGMAN_DEFAULT_STYLE (0)
261 // -----------------------------------------------------------------------
264 // Ids for sub-controls
265 // NB: It should not matter what these are.
266 #define wxPG_SUBID1 2
267 #define wxPG_SUBID2 3
268 #define wxPG_SUBID_TEMP1 4
270 // -----------------------------------------------------------------------
272 /** @class wxPGCommonValue
274 wxPropertyGrid stores information about common values in these
277 NB: Common value feature is not complete, and thus not mentioned in
280 class WXDLLIMPEXP_PROPGRID wxPGCommonValue
284 wxPGCommonValue( const wxString
& label
, wxPGCellRenderer
* renderer
)
287 m_renderer
= renderer
;
290 virtual ~wxPGCommonValue()
292 m_renderer
->DecRef();
295 virtual wxString
GetEditableText() const { return m_label
; }
296 const wxString
& GetLabel() const { return m_label
; }
297 wxPGCellRenderer
* GetRenderer() const { return m_renderer
; }
301 wxPGCellRenderer
* m_renderer
;
304 // -----------------------------------------------------------------------
306 /** @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
310 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
313 /** Prevents user from leaving property unless value is valid. If this
314 behavior flag is not used, then value change is instead cancelled.
316 wxPG_VFB_STAY_IN_PROPERTY
= 0x01,
318 /** Calls wxBell() on validation failure.
320 wxPG_VFB_BEEP
= 0x02,
322 /** Cell with invalid value will be marked (with red colour).
324 wxPG_VFB_MARK_CELL
= 0x04,
326 /** Display customizable text message explaining the situation.
328 wxPG_VFB_SHOW_MESSAGE
= 0x08,
331 wxPG_VFB_DEFAULT
= wxPG_VFB_STAY_IN_PROPERTY
|wxPG_VFB_BEEP
,
333 /** Only used internally. */
334 wxPG_VFB_UNDEFINED
= 0x80
341 typedef wxByte wxPGVFBFlags
;
346 Used to convey validation information to and from functions that
347 actually perform validation. Mostly used in custom property
350 class WXDLLIMPEXP_PROPGRID wxPGValidationInfo
352 friend class wxPropertyGrid
;
355 @return Returns failure behavior which is a combination of
356 @ref propgrid_vfbflags.
358 wxPGVFBFlags
GetFailureBehavior() const
359 { return m_failureBehavior
; }
362 Returns current failure message.
364 const wxString
& GetFailureMessage() const
365 { return m_failureMessage
; }
368 Returns reference to pending value.
370 const wxVariant
& GetValue() const
376 /** Set validation failure behavior
378 @param failureBehavior
379 Mixture of @ref propgrid_vfbflags.
381 void SetFailureBehavior(wxPGVFBFlags failureBehavior
)
382 { m_failureBehavior
= failureBehavior
; }
385 Set current failure message.
387 void SetFailureMessage(const wxString
& message
)
388 { m_failureMessage
= message
; }
391 /** Value to be validated.
395 /** Message displayed on validation failure.
397 wxString m_failureMessage
;
399 /** Validation failure behavior. Use wxPG_VFB_XXX flags.
401 wxPGVFBFlags m_failureBehavior
;
404 // -----------------------------------------------------------------------
406 /** @section propgrid_pgactions wxPropertyGrid Action Identifiers
408 These are used with wxPropertyGrid::AddActionTrigger() and
409 wxPropertyGrid::ClearActionTriggers().
413 enum wxPG_KEYBOARD_ACTIONS
415 wxPG_ACTION_INVALID
= 0,
416 wxPG_ACTION_NEXT_PROPERTY
,
417 wxPG_ACTION_PREV_PROPERTY
,
418 wxPG_ACTION_EXPAND_PROPERTY
,
419 wxPG_ACTION_COLLAPSE_PROPERTY
,
420 wxPG_ACTION_CANCEL_EDIT
,
421 wxPG_ACTION_PRESS_BUTTON
, // Causes editor button (if any) to be pressed
428 // -----------------------------------------------------------------------
431 // wxPropertyGrid::DoSelectProperty flags (selFlags)
433 // Focuses to created editor
434 #define wxPG_SEL_FOCUS 0x01
435 // Forces deletion and recreation of editor
436 #define wxPG_SEL_FORCE 0x02
437 // For example, doesn't cause EnsureVisible
438 #define wxPG_SEL_NONVISIBLE 0x04
439 // Do not validate editor's value before selecting
440 #define wxPG_SEL_NOVALIDATE 0x08
441 // Property being deselected is about to be deleted
442 #define wxPG_SEL_DELETING 0x10
443 // Property's values was set to unspecified by the user
444 #define wxPG_SEL_SETUNSPEC 0x20
445 // Property's event handler changed the value
446 #define wxPG_SEL_DIALOGVAL 0x40
449 // -----------------------------------------------------------------------
454 #define wxPG_FL_INITIALIZED 0x0001
455 // Set when creating editor controls if it was clicked on.
456 #define wxPG_FL_ACTIVATION_BY_CLICK 0x0002
457 #define wxPG_FL_DONT_CENTER_SPLITTER 0x0004
458 #define wxPG_FL_FOCUSED 0x0008
459 #define wxPG_FL_MOUSE_CAPTURED 0x0010
460 #define wxPG_FL_MOUSE_INSIDE 0x0020
461 #define wxPG_FL_VALUE_MODIFIED 0x0040
462 // don't clear background of m_wndEditor
463 #define wxPG_FL_PRIMARY_FILLS_ENTIRE 0x0080
464 // currently active editor uses custom image
465 #define wxPG_FL_CUR_USES_CUSTOM_IMAGE 0x0100
466 // cell colours override selection colours for selected cell
467 #define wxPG_FL_CELL_OVERRIDES_SEL 0x0200
468 #define wxPG_FL_SCROLLED 0x0400
469 // set when all added/inserted properties get hideable flag
470 #define wxPG_FL_ADDING_HIDEABLES 0x0800
471 // Disables showing help strings on statusbar.
472 #define wxPG_FL_NOSTATUSBARHELP 0x1000
473 // Marks that we created the state, so we have to destroy it too.
474 #define wxPG_FL_CREATEDSTATE 0x2000
475 // Set if scrollbar's existence was detected in last onresize.
476 #define wxPG_FL_SCROLLBAR_DETECTED 0x4000
477 // Set if wxPGMan requires redrawing of description text box.
478 #define wxPG_FL_DESC_REFRESH_REQUIRED 0x8000
479 // Set if contained in wxPropertyGridManager
480 #define wxPG_FL_IN_MANAGER 0x00020000
481 // Set after wxPropertyGrid is shown in its initial good size
482 #define wxPG_FL_GOOD_SIZE_SET 0x00040000
483 // Set when in SelectProperty.
484 #define wxPG_FL_IN_SELECT_PROPERTY 0x00100000
485 // Set when help string is shown in status bar
486 #define wxPG_FL_STRING_IN_STATUSBAR 0x00200000
487 // Splitter position has been custom-set by the user
488 #define wxPG_FL_SPLITTER_PRE_SET 0x00400000
489 // Validation failed. Clear on modify event.
490 #define wxPG_FL_VALIDATION_FAILED 0x00800000
491 // Auto sort is enabled (for categorized mode)
492 #define wxPG_FL_CATMODE_AUTO_SORT 0x01000000
493 // Set after page has been inserted to manager
494 #define wxPG_MAN_FL_PAGE_INSERTED 0x02000000
495 // Active editor control is abnormally large
496 #define wxPG_FL_ABNORMAL_EDITOR 0x04000000
497 // Recursion guard for OnCustomEditorEvent
498 #define wxPG_FL_IN_ONCUSTOMEDITOREVENT 0x08000000
499 #define wxPG_FL_VALUE_CHANGE_IN_EVENT 0x10000000
500 // Editor control width should not change on resize
501 #define wxPG_FL_FIXED_WIDTH_EDITOR 0x20000000
502 // Width of panel can be different than width of grid
503 #define wxPG_FL_HAS_VIRTUAL_WIDTH 0x40000000
504 // Prevents RecalculateVirtualSize re-entrancy
505 #define wxPG_FL_RECALCULATING_VIRTUAL_SIZE 0x80000000
507 #endif // #ifndef SWIG
509 #if !defined(__wxPG_SOURCE_FILE__) && !defined(SWIG)
510 // Reduce compile time, but still include in user app
511 #include "wx/propgrid/props.h"
514 // -----------------------------------------------------------------------
516 /** @class wxPropertyGrid
518 wxPropertyGrid is a specialized grid for editing properties
519 such as strings, numbers, flagsets, fonts, and colours. wxPropertySheet
520 used to do the very same thing, but it hasn't been updated for a while
521 and it is currently deprecated.
523 Please note that most member functions are inherited and as such not
524 documented on this page. This means you will probably also want to read
525 wxPropertyGridInterface class reference.
527 See also @ref overview_propgrid.
529 @section propgrid_window_styles_ Window Styles
531 See @ref propgrid_window_styles.
533 @section propgrid_event_handling Event Handling
535 To process input from a propertygrid control, use these event handler
536 macros to direct input to member functions that take a wxPropertyGridEvent
539 @beginEventTable{wxPropertyGridEvent}
540 @event{EVT_PG_SELECTED (id, func)}
541 Respond to wxEVT_PG_SELECTED event, generated when property value
542 has been changed by user.
543 @event{EVT_PG_CHANGING(id, func)}
544 Respond to wxEVT_PG_CHANGING event, generated when property value
545 is about to be changed by user. Use wxPropertyGridEvent::GetValue()
546 to take a peek at the pending value, and wxPropertyGridEvent::Veto()
547 to prevent change from taking place, if necessary.
548 @event{EVT_PG_HIGHLIGHTED(id, func)}
549 Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
550 moves over a property. Event's property is NULL if hovered area does
551 not belong to any property.
552 @event{EVT_PG_RIGHT_CLICK(id, func)}
553 Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
554 clicked on with right mouse button.
555 @event{EVT_PG_DOUBLE_CLICK(id, func)}
556 Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
557 double-clicked onwith left mouse button.
558 @event{EVT_PG_ITEM_COLLAPSED(id, func)}
559 Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
560 a property or category..
561 @event{EVT_PG_ITEM_EXPANDED(id, func)}
562 Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
563 a property or category..
568 - Use Freeze() and Thaw() respectively to disable and enable drawing. This
569 will also delay sorting etc. miscellaneous calculations to the last
575 class WXDLLIMPEXP_PROPGRID
576 wxPropertyGrid
: public wxScrolledWindow
, public wxPropertyGridInterface
578 friend class wxPropertyGridPageState
;
579 friend class wxPropertyGridInterface
;
580 friend class wxPropertyGridManager
;
581 friend class wxPGCanvas
;
584 DECLARE_DYNAMIC_CLASS(wxPropertyGrid
)
589 %pythonAppend wxPropertyGrid
{
590 self
._setOORInfo(self
)
591 self
.DoDefaultTypeMappings()
592 self
.edited_objects
= {}
593 self
.DoDefaultValueTypeMappings()
594 if not hasattr(self
.__class__
,'_vt2setter'):
595 self
.__class__
._vt2setter
= {}
597 %pythonAppend
wxPropertyGrid() ""
599 wxPropertyGrid( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
600 const wxPoint
& pos
= wxDefaultPosition
,
601 const wxSize
& size
= wxDefaultSize
,
602 long style
= wxPG_DEFAULT_STYLE
,
603 const wxChar
* name
= wxPyPropertyGridNameStr
);
604 %RenameCtor
(PrePropertyGrid
, wxPropertyGrid());
608 Two step constructor.
610 Call Create when this constructor is called to build up the
615 /** The default constructor. The styles to be used are styles valid for
616 the wxWindow and wxScrolledWindow.
618 @see @link wndflags Additional Window Styles @endlink
620 wxPropertyGrid( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
621 const wxPoint
& pos
= wxDefaultPosition
,
622 const wxSize
& size
= wxDefaultSize
,
623 long style
= wxPG_DEFAULT_STYLE
,
624 const wxString
& name
= wxPropertyGridNameStr
);
627 virtual ~wxPropertyGrid();
630 /** Adds given key combination to trigger given action.
633 Which action to trigger. See @link pgactions List of list of
634 wxPropertyGrid actions@endlink.
636 void AddActionTrigger( int action
, int keycode
, int modifiers
= 0 );
639 This static function enables or disables automatic use of
640 wxGetTranslation for following strings: wxEnumProperty list labels,
641 wxFlagsProperty sub-property labels.
645 static void AutoGetTranslation( bool enable
);
648 Changes value of a property, as if from an editor.
650 Use this instead of SetPropertyValue() if you need the value to run
651 through validation process, and also send the property change event.
654 Returns true if value was successfully changed.
656 bool ChangePropertyValue( wxPGPropArg id
, wxVariant newValue
);
659 Centers the splitter.
661 If argument is true, automatic splitter centering is enabled (only
662 applicapple if style wxPG_SPLITTER_AUTO_CENTER was defined).
664 void CenterSplitter( bool enable_auto_centering
= false );
666 /** Deletes all properties.
668 virtual void Clear();
670 /** Clears action triggers for given action.
672 Which action to trigger. See @link pgactions List of list of
673 wxPropertyGrid actions@endlink.
675 void ClearActionTriggers( int action
);
677 /** Forces updating the value of property from the editor control.
679 Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
680 ProcessEvent, meaning your event handlers will be called immediately.
683 Returns true if anything was changed.
685 virtual bool CommitChangesFromEditor( wxUint32 flags
= 0 );
690 Whenever the control is created without any parameters, use Create to
691 actually create it. Don't access the control's public methods before
692 this is called @see @link wndflags Additional Window Styles@endlink
694 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
695 const wxPoint
& pos
= wxDefaultPosition
,
696 const wxSize
& size
= wxDefaultSize
,
697 long style
= wxPG_DEFAULT_STYLE
,
698 const wxString
& name
= wxPropertyGridNameStr
);
701 Call when editor widget's contents is modified.
703 For example, this is called when changes text in wxTextCtrl (used in
704 wxStringProperty and wxIntProperty).
707 This function should only be called by custom properties.
709 @see wxPGProperty::OnEvent()
711 void EditorsValueWasModified() { m_iFlags
|= wxPG_FL_VALUE_MODIFIED
; }
713 /** Reverse of EditorsValueWasModified().
716 This function should only be called by custom properties.
718 void EditorsValueWasNotModified()
720 m_iFlags
&= ~(wxPG_FL_VALUE_MODIFIED
);
724 Enables or disables (shows/hides) categories according to parameter
727 bool EnableCategories( bool enable
);
729 /** Scrolls and/or expands items to ensure that the given item is visible.
730 Returns true if something was actually done.
732 bool EnsureVisible( wxPGPropArg id
);
735 Reduces column sizes to minimum possible that contents are still
736 visibly (naturally some margin space will be applied as well).
739 Minimum size for the grid to still display everything.
742 Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
744 This function only works properly if grid size prior to call was already
747 Note that you can also get calculated column widths by calling
748 GetState->GetColumnWidth() immediately after this function returns.
752 wxSize sz
= m_pState
->DoFitColumns();
757 Returns wxWindow that the properties are painted on, and which should
758 be used as the parent for editor controls.
760 wxPanel
* GetPanel() const
765 /** Returns current category caption background colour. */
766 wxColour
GetCaptionBackgroundColour() const { return m_colCapBack
; }
768 wxFont
& GetCaptionFont() { return m_captionFont
; }
770 const wxFont
& GetCaptionFont() const { return m_captionFont
; }
772 /** Returns current category caption text colour. */
773 wxColour
GetCaptionForegroundColour() const { return m_colCapFore
; }
775 /** Returns current cell background colour. */
776 wxColour
GetCellBackgroundColour() const { return m_colPropBack
; }
778 /** Returns current cell text colour when disabled. */
779 wxColour
GetCellDisabledTextColour() const { return m_colDisPropFore
; }
781 /** Returns current cell text colour. */
782 wxColour
GetCellTextColour() const { return m_colPropFore
; }
785 Returns number of columns currently on grid.
787 unsigned int GetColumnCount() const
789 return (unsigned int) m_pState
->m_colWidths
.size();
792 /** Returns colour of empty space below properties. */
793 wxColour
GetEmptySpaceColour() const { return m_colEmptySpace
; }
795 /** Returns height of highest characters of used font. */
796 int GetFontHeight() const { return m_fontHeight
; }
798 /** Returns pointer to itself. Dummy function that enables same kind
799 of code to use wxPropertyGrid and wxPropertyGridManager.
801 wxPropertyGrid
* GetGrid() { return this; }
803 /** Returns rectangle of custom paint image.
805 wxRect
GetImageRect( wxPGProperty
* p
, int item
) const;
807 /** Returns size of the custom paint image in front of property.
808 If no argument is given, returns preferred size.
810 wxSize
GetImageSize( wxPGProperty
* p
= NULL
, int item
= -1 ) const;
813 /** Returns last item which could be iterated using given flags.
815 See @ref propgrid_iterator_flags.
817 wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
)
819 return m_pState
->GetLastItem(flags
);
822 const wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
) const
824 return m_pState
->GetLastItem(flags
);
828 /** Returns colour of lines between cells. */
829 wxColour
GetLineColour() const { return m_colLine
; }
831 /** Returns background colour of margin. */
832 wxColour
GetMarginColour() const { return m_colMargin
; }
835 Returns most up-to-date value of selected property. This will return
836 value different from GetSelectedProperty()->GetValue() only when text
837 editor is activate and string edited by user represents valid,
838 uncommitted property value.
840 wxVariant
GetUncommittedPropertyValue();
842 /** Returns cell background colour of a property. */
843 wxColour
GetPropertyBackgroundColour( wxPGPropArg id
) const;
845 /** Returns cell background colour of a property. */
846 wxColour
GetPropertyTextColour( wxPGPropArg id
) const;
848 /** Returns "root property". It does not have name, etc. and it is not
849 visible. It is only useful for accessing its children.
851 wxPGProperty
* GetRoot() const { return m_pState
->m_properties
; }
853 /** Returns height of a single grid row (in pixels). */
854 int GetRowHeight() const { return m_lineHeight
; }
856 /** Returns currently selected property. */
857 wxPGProperty
* GetSelectedProperty() const { return GetSelection(); }
859 /** Returns currently selected property. */
860 wxPGProperty
* GetSelection() const
865 /** Returns current selection background colour. */
866 wxColour
GetSelectionBackgroundColour() const { return m_colSelBack
; }
868 /** Returns current selection text colour. */
869 wxColour
GetSelectionForegroundColour() const { return m_colSelFore
; }
871 /** Returns current splitter x position. */
872 int GetSplitterPosition() const
873 { return m_pState
->DoGetSplitterPosition(0); }
875 /** Returns wxTextCtrl active in currently selected property, if any. Takes
876 into account wxOwnerDrawnComboBox.
878 wxTextCtrl
* GetEditorTextCtrl() const;
880 wxPGValidationInfo
& GetValidationInfo()
882 return m_validationInfo
;
885 /** Returns current vertical spacing. */
886 int GetVerticalSpacing() const { return (int)m_vspacing
; }
888 /** Returns true if editor's value was marked modified.
890 bool IsEditorsValueModified() const
891 { return ( m_iFlags
& wxPG_FL_VALUE_MODIFIED
) ? true : false; }
893 /** Returns information about arbitrary position in the grid.
895 For wxPropertyGridHitTestResult definition, see
896 wxPropertyGridPageState::HitTest().
898 wxPropertyGridHitTestResult
HitTest( const wxPoint
& pt
) const;
900 /** Returns true if any property has been modified by the user. */
901 bool IsAnyModified() const { return (m_pState
->m_anyModified
>0); }
904 Returns true if updating is frozen (ie Freeze() called but not yet
907 bool IsFrozen() const { return (m_frozen
>0)?true:false; }
909 /** Redraws given property.
911 virtual void RefreshProperty( wxPGProperty
* p
);
914 /** Registers a new editor class.
916 Pointer to the editor class instance that should be used.
918 static wxPGEditor
* RegisterEditorClass( wxPGEditor
* editor
,
919 bool noDefCheck
= false );
922 /** Resets all colours to the original system values.
928 Editor widget is automatically created, but not focused unless focus is
929 true. This will generate wxEVT_PG_SELECT event.
933 True if selection finished successfully. Usually only fails if
934 current value in editor is not valid.
935 @see wxPropertyGrid::Unselect
937 bool SelectProperty( wxPGPropArg id
, bool focus
= false )
939 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
940 return DoSelectProperty(p
,focus
?wxPG_SEL_FOCUS
:0);
943 /** Sets category caption background colour. */
944 void SetCaptionBackgroundColour(const wxColour
& col
);
946 /** Sets category caption text colour. */
947 void SetCaptionTextColour(const wxColour
& col
);
949 /** Sets default cell background colour - applies to property cells.
950 Note that appearance of editor widgets may not be affected.
952 void SetCellBackgroundColour(const wxColour
& col
);
954 /** Sets cell text colour for disabled properties.
956 void SetCellDisabledTextColour(const wxColour
& col
);
958 /** Sets default cell text colour - applies to property name and value text.
959 Note that appearance of editor widgets may not be affected.
961 void SetCellTextColour(const wxColour
& col
);
963 /** Set number of columns (2 or more).
965 void SetColumnCount( int colCount
)
967 m_pState
->SetColumnCount(colCount
);
972 Sets the 'current' category - Append will add non-category properties
975 void SetCurrentCategory( wxPGPropArg id
)
977 wxPG_PROP_ARG_CALL_PROLOG()
978 wxPropertyCategory
* pc
= wxDynamicCast(p
, wxPropertyCategory
);
980 m_pState
->m_currentCategory
= pc
;
983 /** Sets colour of empty space below properties. */
984 void SetEmptySpaceColour(const wxColour
& col
);
986 /** Sets colour of lines between cells. */
987 void SetLineColour(const wxColour
& col
);
989 /** Sets background colour of margin. */
990 void SetMarginColour(const wxColour
& col
);
993 Sets background colour of property.
996 Property name or pointer.
999 New background colour.
1002 If True, child properties are affected recursively. Property
1003 categories are skipped if this flag is used.
1005 void SetPropertyBackgroundColour( wxPGPropArg id
,
1006 const wxColour
& colour
,
1007 bool recursively
= false);
1009 /** Resets text and background colours of given property.
1011 void SetPropertyColoursToDefault( wxPGPropArg id
);
1013 /** Sets text colour of property and all its children.
1015 void SetPropertyTextColour( wxPGPropArg id
,
1016 const wxColour
& col
,
1017 bool recursively
= true );
1020 Sets selection background colour - applies to selected property name
1023 void SetSelectionBackgroundColour(const wxColour
& col
);
1026 Sets selection foreground colour - applies to selected property name
1029 void SetSelectionTextColour(const wxColour
& col
);
1031 /** Sets x coordinate of the splitter.
1033 Splitter position cannot exceed grid size, and therefore setting it
1034 during form creation may fail as initial grid size is often smaller
1035 than desired splitter position, especially when sizers are being used.
1037 void SetSplitterPosition( int newxpos
, int col
= 0 )
1039 DoSetSplitterPosition_(newxpos
, true, col
);
1040 m_iFlags
|= wxPG_FL_SPLITTER_PRE_SET
;
1043 /** Set virtual width for this particular page. Width -1 indicates that the
1044 virtual width should be disabled. */
1045 void SetVirtualWidth( int width
);
1048 Moves splitter as left as possible, while still allowing all
1049 labels to be shown in full.
1051 @param privateChildrenToo
1052 If @false, will still allow private children to be cropped.
1054 void SetSplitterLeft( bool privateChildrenToo
= false )
1056 m_pState
->SetSplitterLeft(privateChildrenToo
);
1059 /** Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
1060 height. Value of 2 should be default on most platforms.
1062 void SetVerticalSpacing( int vspacing
)
1064 m_vspacing
= (unsigned char)vspacing
;
1065 CalculateFontAndBitmapStuff( vspacing
);
1066 if ( !m_pState
->m_itemsAdded
) Refresh();
1069 /** Shows an brief error message that is related to a property. */
1070 void ShowPropertyError( wxPGPropArg id
, const wxString
& msg
)
1072 wxPG_PROP_ARG_CALL_PROLOG()
1073 DoShowPropertyError(p
, msg
);
1076 /** Sorts all items at all levels (except sub-properties). */
1079 /** Sorts children of a category.
1081 void SortChildren( wxPGPropArg id
);
1083 /////////////////////////////////////////////////////////////////
1085 // Following methods do not need to be (currently) documented
1087 /////////////////////////////////////////////////////////////////
1089 bool HasVirtualWidth() const
1090 { return (m_iFlags
& wxPG_FL_HAS_VIRTUAL_WIDTH
) ? true : false; }
1092 const wxPGCommonValue
* GetCommonValue( unsigned int i
) const
1094 return (wxPGCommonValue
*) m_commonValues
[i
];
1097 /** Returns number of common values.
1099 unsigned int GetCommonValueCount() const
1101 return (unsigned int) m_commonValues
.size();
1104 /** Returns label of given common value.
1106 wxString
GetCommonValueLabel( unsigned int i
) const
1108 wxASSERT( GetCommonValue(i
) );
1109 return GetCommonValue(i
)->GetLabel();
1113 Returns index of common value that will truly change value to
1116 int GetUnspecifiedCommonValue() const { return m_cvUnspecified
; }
1118 /** Set index of common value that will truly change value to unspecified.
1119 Using -1 will set none to have such effect.
1122 void SetUnspecifiedCommonValue( int index
) { m_cvUnspecified
= index
; }
1125 Shortcut for creating dialog-caller button. Used, for example, by
1128 This should only be called by properties.
1130 wxWindow
* GenerateEditorButton( const wxPoint
& pos
, const wxSize
& sz
);
1132 /** Fixes position of wxTextCtrl-like control (wxSpinCtrl usually
1133 fits as one). Call after control has been created (but before
1136 void FixPosForTextCtrl( wxWindow
* ctrl
,
1137 const wxPoint
& offset
= wxPoint(0, 0) );
1139 /** Shortcut for creating text editor widget.
1141 Same as pos given for CreateEditor.
1143 Same as sz given for CreateEditor.
1145 Initial text for wxTextCtrl.
1147 If right-side control, such as button, also created, then create it
1148 first and pass it as this parameter.
1150 Extra style flags to pass for wxTextCtrl.
1152 Note that this should generally be called only by new classes derived
1155 wxWindow
* GenerateEditorTextCtrl( const wxPoint
& pos
,
1157 const wxString
& value
,
1158 wxWindow
* secondary
,
1162 /* Generates both textctrl and button.
1164 wxWindow
* GenerateEditorTextCtrlAndButton( const wxPoint
& pos
,
1165 const wxSize
& sz
, wxWindow
** psecondary
, int limited_editing
,
1166 wxPGProperty
* property
);
1168 /** Generates position for a widget editor dialog box.
1170 Property for which dialog is positioned.
1172 Known or over-approximated size of the dialog.
1174 Position for dialog.
1176 wxPoint
GetGoodEditorDialogPosition( wxPGProperty
* p
,
1179 // Converts escape sequences in src_str to newlines,
1180 // tabs, etc. and copies result to dst_str.
1181 static wxString
& ExpandEscapeSequences( wxString
& dst_str
,
1182 wxString
& src_str
);
1184 // Converts newlines, tabs, etc. in src_str to escape
1185 // sequences, and copies result to dst_str.
1186 static wxString
& CreateEscapeSequences( wxString
& dst_str
,
1187 wxString
& src_str
);
1190 Returns rectangle that fully contains properties between and including
1193 wxRect
GetPropertyRect( const wxPGProperty
* p1
,
1194 const wxPGProperty
* p2
) const;
1196 /** Returns pointer to current active primary editor control (NULL if none).
1198 wxWindow
* GetEditorControl() const;
1200 wxWindow
* GetPrimaryEditor() const
1202 return GetEditorControl();
1206 Returns pointer to current active secondary editor control (NULL if
1209 wxWindow
* GetEditorControlSecondary() const
1211 return m_wndEditor2
;
1217 Generates contents for string dst based on the contents of
1220 Format will be "(preDelim)str1(postDelim) (preDelim)str2(postDelim) and
1221 so on. Set flags to 1 inorder to convert backslashes to double-back-
1222 slashes and "(preDelims)"'s to "(preDelims)".
1224 static void ArrayStringToString( wxString
& dst
, const wxArrayString
& src
,
1225 wxChar preDelim
, wxChar postDelim
,
1228 // Mostly useful for page switching.
1229 void SwitchState( wxPropertyGridPageState
* pNewState
);
1232 When creating custom property editors, connect required editor events to
1233 this function. For instance:
1236 control->Connect(control->GetId(), wxEVT_COMMAND_TEXT_UPDATED,
1237 wxEventHandler(wxPropertyGrid::OnCustomEditorEvent),
1241 @remarks You should never need to call this function directly!
1243 @see wxPGEditor::CreateControls(), wxEvtHandler::Connect()
1245 void OnCustomEditorEvent( wxEvent
&event
);
1247 long GetInternalFlags() const { return m_iFlags
; }
1248 bool HasInternalFlag( long flag
) const
1249 { return (m_iFlags
& flag
) ? true : false; }
1250 void SetInternalFlag( long flag
) { m_iFlags
|= flag
; }
1251 void ClearInternalFlag( long flag
) { m_iFlags
&= ~(flag
); }
1252 void IncFrozen() { m_frozen
++; }
1253 void DecFrozen() { m_frozen
--; }
1255 void OnComboItemPaint( wxPGCustomComboControl
* pCb
,int item
,wxDC
& dc
,
1256 wxRect
& rect
,int flags
);
1258 /** Standardized double-to-string conversion.
1260 static void DoubleToString( wxString
& target
,
1264 wxString
* precTemplate
);
1267 Call this from wxPGProperty::OnEvent() to cause property value to be
1268 changed after the function returns (with true as return value).
1269 ValueChangeInEvent() must be used if you wish the application to be
1270 able to use wxEVT_PG_CHANGING to potentially veto the given value.
1272 void ValueChangeInEvent( wxVariant variant
)
1274 m_changeInEventValue
= variant
;
1275 m_iFlags
|= wxPG_FL_VALUE_CHANGE_IN_EVENT
;
1278 /** Returns true if given event is from first of an array of buttons
1279 (as can be in case when wxPGMultiButton is used).
1281 bool IsMainButtonEvent( const wxEvent
& event
)
1283 return (event
.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED
)
1284 && (m_wndSecId
== event
.GetId());
1287 /** Pending value is expected to be passed in PerformValidation().
1289 virtual bool DoPropertyChanged( wxPGProperty
* p
,
1290 unsigned int selFlags
= 0 );
1292 /** Called when validation for given property fails.
1294 Value which failed in validation.
1296 Return true if user is allowed to change to another property even
1297 if current has invalid value.
1299 To add your own validation failure behavior, override
1300 wxPropertyGrid::DoOnValidationFailure().
1302 bool OnValidationFailure( wxPGProperty
* property
, wxVariant
& invalidValue
)
1304 bool res
= DoOnValidationFailure(property
, invalidValue
);
1305 property
->SetFlag(wxPG_PROP_INVALID_VALUE
);
1309 /** Called to indicate property and editor has valid value now.
1311 void OnValidationFailureReset( wxPGProperty
* property
)
1313 if ( property
&& property
->HasFlag(wxPG_PROP_INVALID_VALUE
) )
1315 DoOnValidationFailureReset(property
);
1316 property
->ClearFlag(wxPG_PROP_INVALID_VALUE
);
1318 m_validationInfo
.m_failureMessage
.clear();
1321 /** Override in derived class to display error messages in custom manner
1322 (these message usually only result from validation failure).
1324 virtual void DoShowPropertyError( wxPGProperty
* property
,
1325 const wxString
& msg
);
1327 /** Override to customize property validation failure behavior.
1329 Value which failed in validation.
1331 Return true if user is allowed to change to another property even
1332 if current has invalid value.
1334 virtual bool DoOnValidationFailure( wxPGProperty
* property
,
1335 wxVariant
& invalidValue
);
1337 /** Override to customize resetting of property validation failure status.
1339 Property is guaranteed to have flag wxPG_PROP_INVALID_VALUE set.
1341 virtual void DoOnValidationFailureReset( wxPGProperty
* property
);
1343 int GetSpacingY() const { return m_spacingy
; }
1346 Must be called in wxPGEditor::CreateControls() if primary editor window
1347 is wxTextCtrl, just before textctrl is created.
1349 Initial text value of created wxTextCtrl.
1351 void SetupTextCtrlValue( const wxString text
) { m_prevTcValue
= text
; }
1354 Unfocuses or closes editor if one was open, but does not deselect
1357 bool UnfocusEditor();
1362 wxPropertyGridPageState used by the grid is created here.
1364 If grid is used in wxPropertyGridManager, there is no point overriding
1365 this - instead, set custom wxPropertyGridPage classes.
1367 virtual wxPropertyGridPageState
* CreateState() const;
1369 enum PerformValidationFlags
1371 SendEvtChanging
= 0x0001,
1372 IsStandaloneValidation
= 0x0002 // Not called in response to event
1376 Runs all validation functionality (includes sending wxEVT_PG_CHANGING).
1377 Returns true if all tests passed. Implement in derived class to
1378 add additional validation behavior.
1380 virtual bool PerformValidation( wxPGProperty
* p
,
1381 wxVariant
& pendingValue
,
1382 int flags
= SendEvtChanging
);
1386 // Control font changer helper.
1387 void SetCurControlBoldFont();
1389 wxPGCell
& GetPropertyDefaultCell()
1391 return m_propertyDefaultCell
;
1394 wxPGCell
& GetCategoryDefaultCell()
1396 return m_categoryDefaultCell
;
1400 // Public methods for semi-public use
1401 // (not protected for optimization)
1403 bool DoSelectProperty( wxPGProperty
* p
, unsigned int flags
= 0 );
1405 // Overridden functions.
1406 virtual bool Destroy();
1407 virtual wxSize
DoGetBestSize() const;
1408 // Returns property at given y coordinate (relative to grid's top left).
1409 wxPGProperty
* GetItemAtY( int y
) const { return DoGetItemAtY(y
); }
1411 virtual void Refresh( bool eraseBackground
= true,
1412 const wxRect
*rect
= (const wxRect
*) NULL
);
1413 virtual bool SetFont( const wxFont
& font
);
1414 #if wxPG_SUPPORT_TOOLTIPS
1415 void SetToolTip( const wxString
& tipString
);
1417 virtual void Freeze();
1418 virtual void SetExtraStyle( long exStyle
);
1419 virtual void Thaw();
1424 #ifndef wxPG_ICON_WIDTH
1425 wxBitmap
*m_expandbmp
, *m_collbmp
;
1428 wxCursor
*m_cursorSizeWE
;
1430 /** wxWindow pointers to editor control(s). */
1431 wxWindow
*m_wndEditor
;
1432 wxWindow
*m_wndEditor2
;
1434 /** wxPGCanvas instance. */
1437 #if wxPG_DOUBLE_BUFFER
1438 wxBitmap
*m_doubleBuffer
;
1441 /** Local time ms when control was created. */
1442 wxLongLong m_timeCreated
;
1444 /** wxPGProperty::OnEvent can change value by setting this. */
1445 wxVariant m_changeInEventValue
;
1447 /** Id of m_wndEditor2, or its first child, if any. */
1450 /** Extra Y spacing between the items. */
1453 /** Control client area width; updated on resize. */
1456 /** Control client area height; updated on resize. */
1459 /** Current non-client width (needed when auto-centering). */
1462 /** Non-client width (auto-centering helper). */
1465 /** Previously recorded scroll start position. */
1469 The gutter spacing in front and back of the image.
1470 This determines the amount of spacing in front of each item
1474 /** Includes separator line. */
1477 /** Gutter*2 + image width. */
1480 // y spacing for expand/collapse button.
1481 int m_buttonSpacingY
;
1483 /** Extra margin for expanded sub-group items. */
1484 int m_subgroup_extramargin
;
1487 The image width of the [+] icon.
1489 This is also calculated in the gutter
1493 #ifndef wxPG_ICON_WIDTH
1496 The image height of the [+] icon.
1498 This is calculated as minimal size and to align
1503 /** Current cursor id. */
1507 This captionFont is made equal to the font of the wxScrolledWindow.
1509 As extra the bold face is set on it when this is wanted by the user
1512 wxFont m_captionFont
;
1514 int m_fontHeight
; // Height of the font.
1516 /** m_splitterx when drag began. */
1517 int m_startingSplitterX
;
1520 Index to splitter currently being dragged (0=one after the first
1523 int m_draggedSplitter
;
1525 /** Changed property, calculated in PerformValidation(). */
1526 wxPGProperty
* m_chgInfo_changedProperty
;
1529 Lowest property for which editing happened, but which does not have
1532 wxPGProperty
* m_chgInfo_baseChangedProperty
;
1534 /** Changed property value, calculated in PerformValidation(). */
1535 wxVariant m_chgInfo_pendingValue
;
1537 /** Passed to SetValue. */
1538 wxVariant m_chgInfo_valueList
;
1540 /** Validation information. */
1541 wxPGValidationInfo m_validationInfo
;
1543 /** Actions and keys that trigger them. */
1544 wxPGHashMapI2I m_actionTriggers
;
1550 /** Bits are used to indicate which colours are customized. */
1551 unsigned short m_coloursCustomized
;
1553 /** x - m_splitterx. */
1554 signed char m_dragOffset
;
1556 /** 0 = not dragging, 1 = drag just started, 2 = drag in progress */
1557 unsigned char m_dragStatus
;
1559 /** 0 = margin, 1 = label, 2 = value. */
1560 unsigned char m_mouseSide
;
1562 /** True when editor control is focused. */
1563 unsigned char m_editorFocused
;
1565 /** 1 if m_latsCaption is also the bottommost caption. */
1566 //unsigned char m_lastCaptionBottomnest;
1568 /** Set to 1 when graphics frozen. */
1569 unsigned char m_frozen
;
1571 unsigned char m_vspacing
;
1573 // Used to track when Alt/Ctrl+Key was consumed.
1574 unsigned char m_keyComboConsumed
;
1576 /** 1 if in DoPropertyChanged() */
1577 unsigned char m_inDoPropertyChanged
;
1579 /** 1 if in CommitChangesFromEditor() */
1580 unsigned char m_inCommitChangesFromEditor
;
1582 /** 1 if in DoSelectProperty() */
1583 unsigned char m_inDoSelectProperty
;
1585 wxPGVFBFlags m_permanentValidationFailureBehavior
; // Set by app
1587 /** Internal flags - see wxPG_FL_XXX constants. */
1590 /** When drawing next time, clear this many item slots at the end. */
1591 int m_clearThisMany
;
1593 /** Pointer to selected property. Note that this is duplicated in
1594 m_state for better transiency between pages so that the selected
1595 item can be retained.
1597 wxPGProperty
* m_selected
;
1599 // pointer to property that has mouse hovering
1600 wxPGProperty
* m_propHover
;
1602 // EventObject for wxPropertyGridEvents
1603 wxWindow
* m_eventObject
;
1605 // What (global) window is currently focused (needed to resolve event
1607 wxWindow
* m_curFocused
;
1610 wxEvtHandler
* m_tlwHandler
;
1615 // y coordinate of property that mouse hovering
1617 // Which column's editor is selected (usually 1)?
1620 // x relative to splitter (needed for resize).
1623 // lines between cells
1625 // property labels and values are written in this colour
1626 wxColour m_colPropFore
;
1627 // or with this colour when disabled
1628 wxColour m_colDisPropFore
;
1629 // background for m_colPropFore
1630 wxColour m_colPropBack
;
1631 // text color for captions
1632 wxColour m_colCapFore
;
1633 // background color for captions
1634 wxColour m_colCapBack
;
1635 // foreground for selected property
1636 wxColour m_colSelFore
;
1637 // background for selected property (actually use background color when
1638 // control out-of-focus)
1639 wxColour m_colSelBack
;
1640 // background colour for margin
1641 wxColour m_colMargin
;
1642 // background colour for empty space below the grid
1643 wxColour m_colEmptySpace
;
1645 // Default property colours
1646 wxPGCell m_propertyDefaultCell
;
1648 // Default property category
1649 wxPGCell m_categoryDefaultCell
;
1651 // Backup of selected property's cells
1652 wxVector
<wxPGCell
> m_propCellsBackup
;
1654 // NB: These *cannot* be moved to globals.
1656 // labels when properties use common values
1657 wxVector
<wxPGCommonValue
*> m_commonValues
;
1659 // Which cv selection really sets value to unspecified?
1660 int m_cvUnspecified
;
1662 // Used to skip excess text editor events
1663 wxString m_prevTcValue
;
1667 // Sets some members to defaults (called constructors).
1670 // Initializes some members (called by Create and complex constructor).
1673 void OnPaint(wxPaintEvent
&event
);
1675 // main event receivers
1676 void OnMouseMove( wxMouseEvent
&event
);
1677 void OnMouseMoveBottom( wxMouseEvent
&event
);
1678 void OnMouseClick( wxMouseEvent
&event
);
1679 void OnMouseRightClick( wxMouseEvent
&event
);
1680 void OnMouseDoubleClick( wxMouseEvent
&event
);
1681 void OnMouseUp( wxMouseEvent
&event
);
1682 void OnKey( wxKeyEvent
&event
);
1683 void OnResize( wxSizeEvent
&event
);
1686 bool HandleMouseMove( int x
, unsigned int y
, wxMouseEvent
&event
);
1687 bool HandleMouseClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1688 bool HandleMouseRightClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1689 bool HandleMouseDoubleClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1690 bool HandleMouseUp( int x
, unsigned int y
, wxMouseEvent
&event
);
1691 void HandleKeyEvent( wxKeyEvent
&event
, bool fromChild
);
1693 void OnMouseEntry( wxMouseEvent
&event
);
1695 void OnIdle( wxIdleEvent
&event
);
1696 void OnFocusEvent( wxFocusEvent
&event
);
1697 void OnChildFocusEvent( wxChildFocusEvent
& event
);
1699 bool OnMouseCommon( wxMouseEvent
&event
, int* px
, int *py
);
1700 bool OnMouseChildCommon( wxMouseEvent
&event
, int* px
, int *py
);
1702 // sub-control event handlers
1703 void OnMouseClickChild( wxMouseEvent
&event
);
1704 void OnMouseRightClickChild( wxMouseEvent
&event
);
1705 void OnMouseMoveChild( wxMouseEvent
&event
);
1706 void OnMouseUpChild( wxMouseEvent
&event
);
1707 void OnChildKeyDown( wxKeyEvent
&event
);
1709 void OnCaptureChange( wxMouseCaptureChangedEvent
&event
);
1711 void OnScrollEvent( wxScrollWinEvent
&event
);
1713 void OnSysColourChanged( wxSysColourChangedEvent
&event
);
1718 Adjust the centering of the bitmap icons (collapse / expand) when the
1719 caption font changes.
1721 They need to be centered in the middle of the font, so a bit of deltaY
1722 adjustment is needed. On entry, m_captionFont must be set to window
1723 font. It will be modified properly.
1725 void CalculateFontAndBitmapStuff( int vspacing
);
1727 wxRect
GetEditorWidgetRect( wxPGProperty
* p
, int column
) const;
1729 void CorrectEditorWidgetSizeX();
1731 /** Called in RecalculateVirtualSize() to reposition control
1732 on virtual height changes.
1734 void CorrectEditorWidgetPosY();
1738 void OnScreenNote( const wxChar
* format
, ... );
1741 /** Deselect current selection, if any. Returns true if success
1742 (ie. validator did not intercept). */
1743 bool DoClearSelection();
1745 int DoDrawItems( wxDC
& dc
,
1746 const wxPGProperty
* first_item
,
1747 const wxPGProperty
* last_item
,
1748 const wxRect
* clip_rect
,
1749 bool isBuffered
) const;
1751 void DoSetPropertyValueUnspecified( wxPGProperty
* p
);
1753 /** Draws an expand/collapse (ie. +/-) button.
1755 virtual void DrawExpanderButton( wxDC
& dc
, const wxRect
& rect
,
1756 wxPGProperty
* property
) const;
1758 /** Draws items from topitemy to bottomitemy */
1759 void DrawItems( wxDC
& dc
, unsigned int topitemy
, unsigned int bottomitemy
,
1760 const wxRect
* clip_rect
= (const wxRect
*) NULL
);
1762 void DrawItems( const wxPGProperty
* p1
, const wxPGProperty
* p2
);
1764 void DrawItem( wxPGProperty
* p
)
1769 virtual void DrawItemAndChildren( wxPGProperty
* p
);
1772 Draws item, children, and consequtive parents as long as category is
1775 void DrawItemAndValueRelated( wxPGProperty
* p
);
1777 // Translate wxKeyEvent to wxPG_ACTION_XXX
1778 int KeyEventToActions(wxKeyEvent
&event
, int* pSecond
) const;
1780 int KeyEventToAction(wxKeyEvent
&event
) const
1782 return KeyEventToActions(event
, NULL
);
1785 void ImprovedClientToScreen( int* px
, int* py
);
1787 // Returns True if editor control has focus
1788 bool IsEditorFocused() const;
1790 // Called by focus event handlers. newFocused is the window that becomes
1792 void HandleFocusChange( wxWindow
* newFocused
);
1794 /** Reloads all non-customized colours from system settings. */
1795 void RegainColours();
1797 bool DoEditorValidate();
1799 wxPGProperty
* DoGetItemAtY( int y
) const;
1801 void DoSetSplitterPosition_( int newxpos
,
1802 bool refresh
= true,
1803 int splitterIndex
= 0,
1804 bool allPages
= false );
1808 virtual bool DoExpand( wxPGProperty
* p
, bool sendEvent
= false );
1810 virtual bool DoCollapse( wxPGProperty
* p
, bool sendEvent
= false );
1812 // Returns nearest paint visible property (such that will be painted unless
1813 // window is scrolled or resized). If given property is paint visible, then
1814 // it itself will be returned.
1815 wxPGProperty
* GetNearestPaintVisible( wxPGProperty
* p
) const;
1817 static void RegisterDefaultEditors();
1819 // Sets up basic event handling for child control
1820 void SetupChildEventHandling( wxWindow
* wnd
);
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 void SetFocusOnCanvas();
1842 bool DoHideProperty( wxPGProperty
* p
, bool hide
, int flags
);
1846 bool ButtonTriggerKeyTest( int action
, wxKeyEvent
& event
);
1848 DECLARE_EVENT_TABLE()
1849 #endif // #ifndef SWIG
1852 // -----------------------------------------------------------------------
1854 // Bunch of inlines that need to resolved after all classes have been defined.
1858 inline bool wxPropertyGridPageState::IsDisplayed() const
1860 return ( this == m_pPropGrid
->GetState() );
1863 inline unsigned int wxPropertyGridPageState::GetActualVirtualHeight() const
1865 return DoGetRoot()->GetChildrenHeight(GetGrid()->GetRowHeight());
1869 inline int wxPGProperty::GetDisplayedCommonValueCount() const
1871 if ( HasFlag(wxPG_PROP_USES_COMMON_VALUE
) )
1873 wxPropertyGrid
* pg
= GetGrid();
1875 return (int) pg
->GetCommonValueCount();
1880 inline void wxPGProperty::SetEditor( const wxString
& editorName
)
1882 m_customEditor
= wxPropertyGridInterface::GetEditorByName(editorName
);
1885 inline void wxPGProperty::SetName( const wxString
& newName
)
1887 GetGrid()->SetPropertyName(this, newName
);
1890 inline bool wxPGProperty::Hide( bool hide
, int flags
)
1892 return GetGrid()->HideProperty(this, hide
, flags
);
1895 inline bool wxPGProperty::SetMaxLength( int maxLen
)
1897 return GetGrid()->SetPropertyMaxLength(this,maxLen
);
1900 // -----------------------------------------------------------------------
1905 #define wxPG_BASE_EVT_PRE_ID 1775
1907 BEGIN_DECLARE_EVENT_TYPES()
1908 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_SELECTED
, wxPG_BASE_EVT_PRE_ID
)
1909 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_CHANGING
, wxPG_BASE_EVT_PRE_ID
+1)
1910 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_CHANGED
, wxPG_BASE_EVT_PRE_ID
+2)
1911 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_HIGHLIGHTED
, wxPG_BASE_EVT_PRE_ID
+3)
1912 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_RIGHT_CLICK
, wxPG_BASE_EVT_PRE_ID
+4)
1913 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_PAGE_CHANGED
, wxPG_BASE_EVT_PRE_ID
+5)
1914 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_ITEM_COLLAPSED
, wxPG_BASE_EVT_PRE_ID
+6)
1915 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_ITEM_EXPANDED
, wxPG_BASE_EVT_PRE_ID
+7)
1916 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_PROPGRID
, wxEVT_PG_DOUBLE_CLICK
, wxPG_BASE_EVT_PRE_ID
+8)
1917 END_DECLARE_EVENT_TYPES()
1920 wxEVT_PG_SELECTED
= wxPG_BASE_EVT_PRE_ID
,
1923 wxEVT_PG_HIGHLIGHTED
,
1924 wxEVT_PG_RIGHT_CLICK
,
1925 wxEVT_PG_PAGE_CHANGED
,
1926 wxEVT_PG_ITEM_COLLAPSED
,
1927 wxEVT_PG_ITEM_EXPANDED
,
1928 wxEVT_PG_DOUBLE_CLICK
1933 #define wxPG_BASE_EVT_TYPE wxEVT_PG_SELECTED
1934 #define wxPG_MAX_EVT_TYPE (wxPG_BASE_EVT_TYPE+30)
1938 typedef void (wxEvtHandler::*wxPropertyGridEventFunction
)(wxPropertyGridEvent
&);
1940 #define EVT_PG_SELECTED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_SELECTED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1941 #define EVT_PG_CHANGING(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGING, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1942 #define EVT_PG_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1943 #define EVT_PG_HIGHLIGHTED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_HIGHLIGHTED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1944 #define EVT_PG_RIGHT_CLICK(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_RIGHT_CLICK, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1945 #define EVT_PG_DOUBLE_CLICK(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_DOUBLE_CLICK, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1946 #define EVT_PG_PAGE_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_PAGE_CHANGED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1947 #define EVT_PG_ITEM_COLLAPSED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_COLLAPSED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1948 #define EVT_PG_ITEM_EXPANDED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_EXPANDED, id, -1, (wxObjectEventFunction) (wxEventFunction) wxStaticCastEvent( wxPropertyGridEventFunction, & fn ), (wxObject *) NULL ),
1950 #define wxPropertyGridEventHandler(A) \
1951 ((wxObjectEventFunction)(wxEventFunction)(wxPropertyGridEventFunction)&A)
1956 /** @class wxPropertyGridEvent
1958 A propertygrid event holds information about events associated with
1959 wxPropertyGrid objects.
1961 @library{wxpropgrid}
1964 class WXDLLIMPEXP_PROPGRID wxPropertyGridEvent
: public wxCommandEvent
1969 wxPropertyGridEvent(wxEventType commandType
=0, int id
=0);
1971 /** Copy constructor. */
1972 wxPropertyGridEvent(const wxPropertyGridEvent
& event
);
1975 ~wxPropertyGridEvent();
1978 virtual wxEvent
* Clone() const;
1980 wxPGProperty
* GetMainParent() const
1982 wxASSERT(m_property
);
1983 return m_property
->GetMainParent();
1986 /** Returns id of associated property. */
1987 wxPGProperty
* GetProperty() const
1992 wxPGValidationInfo
& GetValidationInfo()
1994 wxASSERT(m_validationInfo
);
1995 return *m_validationInfo
;
1998 /** Returns true if you can veto the action that the event is signaling.
2000 bool CanVeto() const { return m_canVeto
; }
2003 Call this from your event handler to veto action that the event is
2006 You can only veto a shutdown if wxPropertyGridEvent::CanVeto returns
2009 Currently only wxEVT_PG_CHANGING supports vetoing.
2011 void Veto( bool veto
= true ) { m_wasVetoed
= veto
; }
2013 /** Returns value that is about to be set for wxEVT_PG_CHANGING.
2015 const wxVariant
& GetValue() const
2017 wxASSERT_MSG( m_validationInfo
,
2018 "Only call GetValue from a handler "
2019 "of event type that supports it" );
2020 return m_validationInfo
->GetValue();
2024 Set override validation failure behavior.
2026 Only effective if Veto was also called, and only allowed if event type
2027 is wxEVT_PG_CHANGING.
2029 void SetValidationFailureBehavior( wxPGVFBFlags flags
)
2031 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2032 m_validationInfo
->SetFailureBehavior( flags
);
2035 /** Sets custom failure message for this time only. Only applies if
2036 wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
2038 void SetValidationFailureMessage( const wxString
& message
)
2040 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2041 m_validationInfo
->SetFailureMessage( message
);
2045 wxPGVFBFlags
GetValidationFailureBehavior() const
2047 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2048 return m_validationInfo
->GetFailureBehavior();
2051 void SetCanVeto( bool canVeto
) { m_canVeto
= canVeto
; }
2052 bool WasVetoed() const { return m_wasVetoed
; }
2054 /** Changes the associated property. */
2055 void SetProperty( wxPGProperty
* p
) { m_property
= p
; }
2057 void SetPropertyGrid( wxPropertyGrid
* pg
) { m_pg
= pg
; }
2059 void SetupValidationInfo()
2062 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2063 m_validationInfo
= &m_pg
->GetValidationInfo();
2068 DECLARE_DYNAMIC_CLASS(wxPropertyGridEvent
)
2070 wxPGProperty
* m_property
;
2071 wxPropertyGrid
* m_pg
;
2072 wxPGValidationInfo
* m_validationInfo
;
2081 // -----------------------------------------------------------------------
2083 /** @class wxPropertyGridPopulator
2085 Allows populating wxPropertyGrid from arbitrary text source.
2087 class WXDLLIMPEXP_PROPGRID wxPropertyGridPopulator
2090 /** Default constructor.
2092 wxPropertyGridPopulator();
2095 virtual ~wxPropertyGridPopulator();
2097 void SetState( wxPropertyGridPageState
* state
);
2099 void SetGrid( wxPropertyGrid
* pg
);
2101 /** Appends a new property under bottommost parent.
2103 Property class as string.
2105 wxPGProperty
* Add( const wxString
& propClass
,
2106 const wxString
& propLabel
,
2107 const wxString
& propName
,
2108 const wxString
* propValue
,
2109 wxPGChoices
* pChoices
= NULL
);
2112 Pushes property to the back of parent array (ie it becomes bottommost
2113 parent), and starts scanning/adding children for it.
2115 When finished, parent array is returned to the original state.
2117 void AddChildren( wxPGProperty
* property
);
2119 /** Adds attribute to the bottommost property.
2121 Allowed values: "string", (same as string), "int", "bool". Empty string
2124 bool AddAttribute( const wxString
& name
,
2125 const wxString
& type
,
2126 const wxString
& value
);
2128 /** Called once in AddChildren.
2130 virtual void DoScanForChildren() = 0;
2133 Returns id of parent property for which children can currently be
2136 wxPGProperty
* GetCurParent() const
2138 return (wxPGProperty
*) m_propHierarchy
[m_propHierarchy
.size()-1];
2141 wxPropertyGridPageState
* GetState() { return m_state
; }
2142 const wxPropertyGridPageState
* GetState() const { return m_state
; }
2144 /** Like wxString::ToLong, except allows N% in addition of N.
2146 static bool ToLongPCT( const wxString
& s
, long* pval
, long max
);
2148 /** Parses strings of format "choice1"[=value1] ... "choiceN"[=valueN] into
2149 wxPGChoices. Registers parsed result using idString (if not empty).
2150 Also, if choices with given id already registered, then don't parse but
2151 return those choices instead.
2153 wxPGChoices
ParseChoices( const wxString
& choicesString
,
2154 const wxString
& idString
);
2156 /** Implement in derived class to do custom process when an error occurs.
2157 Default implementation uses wxLogError.
2159 virtual void ProcessError( const wxString
& msg
);
2163 /** Used property grid. */
2164 wxPropertyGrid
* m_pg
;
2166 /** Used property grid state. */
2167 wxPropertyGridPageState
* m_state
;
2169 /** Tree-hierarchy of added properties (that can have children). */
2170 wxArrayPGProperty m_propHierarchy
;
2172 /** Hashmap for string-id to wxPGChoicesData mapping. */
2173 wxPGHashMapS2P m_dictIdChoices
;
2176 // -----------------------------------------------------------------------
2179 // Undefine macros that are not needed outside propertygrid sources
2181 #ifndef __wxPG_SOURCE_FILE__
2182 #undef wxPG_FL_DESC_REFRESH_REQUIRED
2183 #undef wxPG_FL_SCROLLBAR_DETECTED
2184 #undef wxPG_FL_CREATEDSTATE
2185 #undef wxPG_FL_NOSTATUSBARHELP
2186 #undef wxPG_FL_SCROLLED
2187 #undef wxPG_FL_FOCUS_INSIDE_CHILD
2188 #undef wxPG_FL_FOCUS_INSIDE
2189 #undef wxPG_FL_MOUSE_INSIDE_CHILD
2190 #undef wxPG_FL_CUR_USES_CUSTOM_IMAGE
2191 #undef wxPG_FL_PRIMARY_FILLS_ENTIRE
2192 #undef wxPG_FL_VALUE_MODIFIED
2193 #undef wxPG_FL_MOUSE_INSIDE
2194 #undef wxPG_FL_FOCUSED
2195 #undef wxPG_FL_MOUSE_CAPTURED
2196 #undef wxPG_FL_INITIALIZED
2197 #undef wxPG_FL_ACTIVATION_BY_CLICK
2198 #undef wxPG_FL_DONT_CENTER_SPLITTER
2199 #undef wxPG_SUPPORT_TOOLTIPS
2200 #undef wxPG_DOUBLE_BUFFER
2201 #undef wxPG_ICON_WIDTH
2202 #undef wxPG_USE_RENDERER_NATIVE
2203 // Following are needed by the manager headers
2204 // #undef const wxString&
2207 // -----------------------------------------------------------------------
2211 #endif // _WX_PROPGRID_PROPGRID_H_