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
[];
32 // -----------------------------------------------------------------------
34 // -----------------------------------------------------------------------
38 // This is required for sharing common global variables.
39 class WXDLLIMPEXP_PROPGRID wxPGGlobalVarsClass
43 wxPGGlobalVarsClass();
44 ~wxPGGlobalVarsClass();
46 // Used by advprops, but here to make things easier.
47 wxString m_pDefaultImageWildcard
;
49 // Map of editor class instances (keys are name string).
50 wxPGHashMapS2P m_mapEditorClasses
;
53 wxVector
<wxValidator
*> m_arrValidators
; // These wxValidators need to be freed
56 wxPGHashMapS2P m_dictPropertyClassInfo
; // PropertyName -> ClassInfo
58 wxPGChoices
* m_fontFamilyChoices
;
60 // Replace with your own to affect all properties using default renderer.
61 wxPGCellRenderer
* m_defaultRenderer
;
63 wxPGChoices m_boolChoices
;
65 wxVariant m_vEmptyString
;
67 wxVariant m_vMinusOne
;
71 // Cached constant strings
72 wxPGCachedString m_strstring
;
73 wxPGCachedString m_strlong
;
74 wxPGCachedString m_strbool
;
75 wxPGCachedString m_strlist
;
77 wxPGCachedString m_strDefaultValue
;
78 wxPGCachedString m_strMin
;
79 wxPGCachedString m_strMax
;
80 wxPGCachedString m_strUnits
;
81 wxPGCachedString m_strInlineHelp
;
83 // If true then some things are automatically translated
84 bool m_autoGetTranslation
;
86 // > 0 if errors cannot or should not be shown in statusbar etc.
89 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)
106 // When wxPG is loaded dynamically after the application is already running
107 // then the built-in module system won't pick this one up. Add it manually.
108 WXDLLIMPEXP_PROPGRID
void wxPGInitResourceModule();
112 // -----------------------------------------------------------------------
114 /** @section propgrid_window_styles wxPropertyGrid Window Styles
116 SetWindowStyleFlag method can be used to modify some of these at run-time.
119 enum wxPG_WINDOW_STYLES
122 /** This will cause Sort() automatically after an item is added.
123 When inserting a lot of items in this mode, it may make sense to
124 use Freeze() before operations and Thaw() afterwards to increase
127 wxPG_AUTO_SORT
= 0x00000010,
129 /** Categories are not initially shown (even if added).
130 IMPORTANT NOTE: If you do not plan to use categories, then this
131 style will waste resources.
132 This flag can also be changed using wxPropertyGrid::EnableCategories method.
134 wxPG_HIDE_CATEGORIES
= 0x00000020,
136 /* This style combines non-categoric mode and automatic sorting.
138 wxPG_ALPHABETIC_MODE
= (wxPG_HIDE_CATEGORIES
|wxPG_AUTO_SORT
),
140 /** Modified values are shown in bold font. Changing this requires Refresh()
143 wxPG_BOLD_MODIFIED
= 0x00000040,
145 /** When wxPropertyGrid is resized, splitter moves to the center. This
146 behavior stops once the user manually moves the splitter.
148 wxPG_SPLITTER_AUTO_CENTER
= 0x00000080,
150 /** Display tooltips for cell text that cannot be shown completely. If
151 wxUSE_TOOLTIPS is 0, then this doesn't have any effect.
153 wxPG_TOOLTIPS
= 0x00000100,
155 /** Disables margin and hides all expand/collapse buttons that would appear
156 outside the margin (for sub-properties). Toggling this style automatically
157 expands all collapsed items.
159 wxPG_HIDE_MARGIN
= 0x00000200,
161 /** This style prevents user from moving the splitter.
163 wxPG_STATIC_SPLITTER
= 0x00000400,
165 /** Combination of other styles that make it impossible for user to modify
168 wxPG_STATIC_LAYOUT
= (wxPG_HIDE_MARGIN
|wxPG_STATIC_SPLITTER
),
170 /** Disables wxTextCtrl based editors for properties which
171 can be edited in another way.
173 Equals calling wxPropertyGrid::LimitPropertyEditing for all added
176 wxPG_LIMITED_EDITING
= 0x00000800,
178 /** wxPropertyGridManager only: Show toolbar for mode and page selection. */
179 wxPG_TOOLBAR
= 0x00001000,
181 /** wxPropertyGridManager only: Show adjustable text box showing description
182 or help text, if available, for currently selected property.
184 wxPG_DESCRIPTION
= 0x00002000
188 enum wxPG_EX_WINDOW_STYLES
192 NOTE: wxPG_EX_xxx are extra window styles and must be set using
193 SetExtraStyle() member function.
195 Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if
196 wxPG_HIDE_CATEGORIES is not defined, the non-categorized data storage is
197 not activated, and switching the mode first time becomes somewhat slower.
198 wxPG_EX_INIT_NOCAT activates the non-categorized data storage right away.
199 IMPORTANT NOTE: If you do plan not switching to non-categoric mode, or if
200 you don't plan to use categories at all, then using this style will result
201 in waste of resources.
204 wxPG_EX_INIT_NOCAT
= 0x00001000,
206 /** Extended window style that sets wxPropertyGridManager toolbar to not
209 wxPG_EX_NO_FLAT_TOOLBAR
= 0x00002000,
211 /** Shows alphabetic/categoric mode buttons from toolbar.
213 wxPG_EX_MODE_BUTTONS
= 0x00008000,
215 /** Show property help strings as tool tips instead as text on the status bar.
216 You can set the help strings using SetPropertyHelpString member function.
218 wxPG_EX_HELP_AS_TOOLTIPS
= 0x00010000,
220 /** Prevent TAB from focusing to wxButtons. This behavior was default
221 in version 1.2.0 and earlier.
222 NOTE! Tabbing to button doesn't work yet. Problem seems to be that on wxMSW
223 atleast the button doesn't properly propagate key events (yes, I'm using
226 //wxPG_EX_NO_TAB_TO_BUTTON = 0x00020000,
228 /** Allows relying on native double-buffering.
230 wxPG_EX_NATIVE_DOUBLE_BUFFERING
= 0x00080000,
232 /** Set this style to let user have ability to set values of properties to
233 unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for
236 wxPG_EX_AUTO_UNSPECIFIED_VALUES
= 0x00200000,
239 If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION
240 and wxPG_STRING_PASSWORD) are not stored into property's attribute storage
241 (thus they are not readable).
243 Note that this option is global, and applies to all wxPG property
246 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES
= 0x00400000,
248 /** Hides page selection buttons from toolbar.
250 wxPG_EX_HIDE_PAGE_BUTTONS
= 0x01000000
254 /** Combines various styles.
256 #define wxPG_DEFAULT_STYLE (0)
258 /** Combines various styles.
260 #define wxPGMAN_DEFAULT_STYLE (0)
265 // -----------------------------------------------------------------------
268 // Ids for sub-controls
269 // NB: It should not matter what these are.
270 #define wxPG_SUBID1 2
271 #define wxPG_SUBID2 3
272 #define wxPG_SUBID_TEMP1 4
274 // -----------------------------------------------------------------------
276 /** @class wxPGCommonValue
278 wxPropertyGrid stores information about common values in these
281 NB: Common value feature is not complete, and thus not mentioned in
284 class WXDLLIMPEXP_PROPGRID wxPGCommonValue
288 wxPGCommonValue( const wxString
& label
, wxPGCellRenderer
* renderer
)
291 m_renderer
= renderer
;
294 virtual ~wxPGCommonValue()
296 m_renderer
->DecRef();
299 virtual wxString
GetEditableText() const { return m_label
; }
300 const wxString
& GetLabel() const { return m_label
; }
301 wxPGCellRenderer
* GetRenderer() const { return m_renderer
; }
305 wxPGCellRenderer
* m_renderer
;
308 // -----------------------------------------------------------------------
310 /** @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
314 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
317 /** Prevents user from leaving property unless value is valid. If this
318 behavior flag is not used, then value change is instead cancelled.
320 wxPG_VFB_STAY_IN_PROPERTY
= 0x01,
322 /** Calls wxBell() on validation failure.
324 wxPG_VFB_BEEP
= 0x02,
326 /** Cell with invalid value will be marked (with red colour).
328 wxPG_VFB_MARK_CELL
= 0x04,
330 /** Display customizable text message explaining the situation.
332 wxPG_VFB_SHOW_MESSAGE
= 0x08,
335 wxPG_VFB_DEFAULT
= wxPG_VFB_STAY_IN_PROPERTY
|wxPG_VFB_BEEP
,
337 /** Only used internally. */
338 wxPG_VFB_UNDEFINED
= 0x80
345 typedef wxByte wxPGVFBFlags
;
350 Used to convey validation information to and from functions that
351 actually perform validation. Mostly used in custom property
354 class WXDLLIMPEXP_PROPGRID wxPGValidationInfo
356 friend class wxPropertyGrid
;
359 @return Returns failure behavior which is a combination of
360 @ref propgrid_vfbflags.
362 wxPGVFBFlags
GetFailureBehavior() const
363 { return m_failureBehavior
; }
366 Returns current failure message.
368 const wxString
& GetFailureMessage() const
369 { return m_failureMessage
; }
372 Returns reference to pending value.
374 const wxVariant
& GetValue() const
380 /** Set validation failure behavior
382 @param failureBehavior
383 Mixture of @ref propgrid_vfbflags.
385 void SetFailureBehavior(wxPGVFBFlags failureBehavior
)
386 { m_failureBehavior
= failureBehavior
; }
389 Set current failure message.
391 void SetFailureMessage(const wxString
& message
)
392 { m_failureMessage
= message
; }
395 /** Value to be validated.
399 /** Message displayed on validation failure.
401 wxString m_failureMessage
;
403 /** Validation failure behavior. Use wxPG_VFB_XXX flags.
405 wxPGVFBFlags m_failureBehavior
;
408 // -----------------------------------------------------------------------
410 /** @section propgrid_pgactions wxPropertyGrid Action Identifiers
412 These are used with wxPropertyGrid::AddActionTrigger() and
413 wxPropertyGrid::ClearActionTriggers().
417 enum wxPG_KEYBOARD_ACTIONS
419 wxPG_ACTION_INVALID
= 0,
420 wxPG_ACTION_NEXT_PROPERTY
,
421 wxPG_ACTION_PREV_PROPERTY
,
422 wxPG_ACTION_EXPAND_PROPERTY
,
423 wxPG_ACTION_COLLAPSE_PROPERTY
,
424 wxPG_ACTION_CANCEL_EDIT
,
425 wxPG_ACTION_PRESS_BUTTON
, // Causes editor button (if any) to be pressed
432 // -----------------------------------------------------------------------
435 // wxPropertyGrid::DoSelectProperty flags (selFlags)
437 // Focuses to created editor
438 #define wxPG_SEL_FOCUS 0x01
439 // Forces deletion and recreation of editor
440 #define wxPG_SEL_FORCE 0x02
441 // For example, doesn't cause EnsureVisible
442 #define wxPG_SEL_NONVISIBLE 0x04
443 // Do not validate editor's value before selecting
444 #define wxPG_SEL_NOVALIDATE 0x08
445 // Property being deselected is about to be deleted
446 #define wxPG_SEL_DELETING 0x10
447 // Property's values was set to unspecified by the user
448 #define wxPG_SEL_SETUNSPEC 0x20
449 // Property's event handler changed the value
450 #define wxPG_SEL_DIALOGVAL 0x40
451 // Set to disable sending of wxEVT_PG_SELECTED event
452 #define wxPG_SEL_DONT_SEND_EVENT 0x80
455 // -----------------------------------------------------------------------
460 #define wxPG_FL_INITIALIZED 0x0001
461 // Set when creating editor controls if it was clicked on.
462 #define wxPG_FL_ACTIVATION_BY_CLICK 0x0002
463 #define wxPG_FL_DONT_CENTER_SPLITTER 0x0004
464 #define wxPG_FL_FOCUSED 0x0008
465 #define wxPG_FL_MOUSE_CAPTURED 0x0010
466 #define wxPG_FL_MOUSE_INSIDE 0x0020
467 #define wxPG_FL_VALUE_MODIFIED 0x0040
468 // don't clear background of m_wndEditor
469 #define wxPG_FL_PRIMARY_FILLS_ENTIRE 0x0080
470 // currently active editor uses custom image
471 #define wxPG_FL_CUR_USES_CUSTOM_IMAGE 0x0100
472 // cell colours override selection colours for selected cell
473 #define wxPG_FL_CELL_OVERRIDES_SEL 0x0200
474 #define wxPG_FL_SCROLLED 0x0400
475 // set when all added/inserted properties get hideable flag
476 #define wxPG_FL_ADDING_HIDEABLES 0x0800
477 // Disables showing help strings on statusbar.
478 #define wxPG_FL_NOSTATUSBARHELP 0x1000
479 // Marks that we created the state, so we have to destroy it too.
480 #define wxPG_FL_CREATEDSTATE 0x2000
481 // Set if scrollbar's existence was detected in last onresize.
482 #define wxPG_FL_SCROLLBAR_DETECTED 0x4000
483 // Set if wxPGMan requires redrawing of description text box.
484 #define wxPG_FL_DESC_REFRESH_REQUIRED 0x8000
485 // Set if contained in wxPropertyGridManager
486 #define wxPG_FL_IN_MANAGER 0x00020000
487 // Set after wxPropertyGrid is shown in its initial good size
488 #define wxPG_FL_GOOD_SIZE_SET 0x00040000
489 // Set when in SelectProperty.
490 #define wxPG_FL_IN_SELECT_PROPERTY 0x00100000
491 // Set when help string is shown in status bar
492 #define wxPG_FL_STRING_IN_STATUSBAR 0x00200000
493 // Splitter position has been custom-set by the user
494 #define wxPG_FL_SPLITTER_PRE_SET 0x00400000
495 // Validation failed. Clear on modify event.
496 #define wxPG_FL_VALIDATION_FAILED 0x00800000
497 // Auto sort is enabled (for categorized mode)
498 #define wxPG_FL_CATMODE_AUTO_SORT 0x01000000
499 // Set after page has been inserted to manager
500 #define wxPG_MAN_FL_PAGE_INSERTED 0x02000000
501 // Active editor control is abnormally large
502 #define wxPG_FL_ABNORMAL_EDITOR 0x04000000
503 // Recursion guard for HandleCustomEditorEvent
504 #define wxPG_FL_IN_HANDLECUSTOMEDITOREVENT 0x08000000
505 #define wxPG_FL_VALUE_CHANGE_IN_EVENT 0x10000000
506 // Editor control width should not change on resize
507 #define wxPG_FL_FIXED_WIDTH_EDITOR 0x20000000
508 // Width of panel can be different than width of grid
509 #define wxPG_FL_HAS_VIRTUAL_WIDTH 0x40000000
510 // Prevents RecalculateVirtualSize re-entrancy
511 #define wxPG_FL_RECALCULATING_VIRTUAL_SIZE 0x80000000
513 #endif // #ifndef SWIG
515 #if !defined(__wxPG_SOURCE_FILE__) && !defined(SWIG)
516 // Reduce compile time, but still include in user app
517 #include "wx/propgrid/props.h"
520 // -----------------------------------------------------------------------
522 /** @class wxPropertyGrid
524 wxPropertyGrid is a specialized grid for editing properties
525 such as strings, numbers, flagsets, fonts, and colours. wxPropertySheet
526 used to do the very same thing, but it hasn't been updated for a while
527 and it is currently deprecated.
529 Please note that most member functions are inherited and as such not
530 documented on this page. This means you will probably also want to read
531 wxPropertyGridInterface class reference.
533 See also @ref overview_propgrid.
535 @section propgrid_window_styles_ Window Styles
537 See @ref propgrid_window_styles.
539 @section propgrid_event_handling Event Handling
541 To process input from a propertygrid control, use these event handler
542 macros to direct input to member functions that take a wxPropertyGridEvent
545 @beginEventTable{wxPropertyGridEvent}
546 @event{EVT_PG_SELECTED (id, func)}
547 Respond to wxEVT_PG_SELECTED event, generated when a property selection
548 has been changed, either by user action or by indirect program
549 function. For instance, collapsing a parent property programmatically
550 causes any selected child property to become unselected, and may
551 therefore cause this event to be generated.
552 @event{EVT_PG_CHANGING(id, func)}
553 Respond to wxEVT_PG_CHANGING event, generated when property value
554 is about to be changed by user. Use wxPropertyGridEvent::GetValue()
555 to take a peek at the pending value, and wxPropertyGridEvent::Veto()
556 to prevent change from taking place, if necessary.
557 @event{EVT_PG_HIGHLIGHTED(id, func)}
558 Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
559 moves over a property. Event's property is NULL if hovered area does
560 not belong to any property.
561 @event{EVT_PG_RIGHT_CLICK(id, func)}
562 Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
563 clicked on with right mouse button.
564 @event{EVT_PG_DOUBLE_CLICK(id, func)}
565 Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
566 double-clicked onwith left mouse button.
567 @event{EVT_PG_ITEM_COLLAPSED(id, func)}
568 Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
569 a property or category..
570 @event{EVT_PG_ITEM_EXPANDED(id, func)}
571 Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
572 a property or category..
577 - Use Freeze() and Thaw() respectively to disable and enable drawing. This
578 will also delay sorting etc. miscellaneous calculations to the last
584 class WXDLLIMPEXP_PROPGRID
585 wxPropertyGrid
: public wxScrolledWindow
, public wxPropertyGridInterface
587 friend class wxPropertyGridPageState
;
588 friend class wxPropertyGridInterface
;
589 friend class wxPropertyGridManager
;
590 friend class wxPGCanvas
;
592 DECLARE_DYNAMIC_CLASS(wxPropertyGrid
)
597 Two step constructor.
599 Call Create when this constructor is called to build up the
605 /** The default constructor. The styles to be used are styles valid for
606 the wxWindow and wxScrolledWindow.
608 @see @link wndflags Additional Window Styles @endlink
610 wxPropertyGrid( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
611 const wxPoint
& pos
= wxDefaultPosition
,
612 const wxSize
& size
= wxDefaultSize
,
613 long style
= wxPG_DEFAULT_STYLE
,
614 const wxString
& name
= wxPropertyGridNameStr
);
617 virtual ~wxPropertyGrid();
619 /** Adds given key combination to trigger given action.
622 Which action to trigger. See @link pgactions List of list of
623 wxPropertyGrid actions@endlink.
625 void AddActionTrigger( int action
, int keycode
, int modifiers
= 0 );
628 This static function enables or disables automatic use of
629 wxGetTranslation for following strings: wxEnumProperty list labels,
630 wxFlagsProperty sub-property labels.
634 static void AutoGetTranslation( bool enable
);
637 Changes value of a property, as if from an editor.
639 Use this instead of SetPropertyValue() if you need the value to run
640 through validation process, and also send the property change event.
643 Returns true if value was successfully changed.
645 bool ChangePropertyValue( wxPGPropArg id
, wxVariant newValue
);
648 Centers the splitter.
650 If argument is true, automatic splitter centering is enabled (only
651 applicapple if style wxPG_SPLITTER_AUTO_CENTER was defined).
653 void CenterSplitter( bool enable_auto_centering
= false );
655 /** Deletes all properties.
657 virtual void Clear();
659 /** Clears action triggers for given action.
661 Which action to trigger. See @link pgactions List of list of
662 wxPropertyGrid actions@endlink.
664 void ClearActionTriggers( int action
);
666 /** Forces updating the value of property from the editor control.
668 Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
669 ProcessEvent, meaning your event handlers will be called immediately.
672 Returns true if anything was changed.
674 virtual bool CommitChangesFromEditor( wxUint32 flags
= 0 );
679 Whenever the control is created without any parameters, use Create to
680 actually create it. Don't access the control's public methods before
681 this is called @see @link wndflags Additional Window Styles@endlink
683 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
684 const wxPoint
& pos
= wxDefaultPosition
,
685 const wxSize
& size
= wxDefaultSize
,
686 long style
= wxPG_DEFAULT_STYLE
,
687 const wxString
& name
= wxPropertyGridNameStr
);
690 Call when editor widget's contents is modified.
692 For example, this is called when changes text in wxTextCtrl (used in
693 wxStringProperty and wxIntProperty).
696 This function should only be called by custom properties.
698 @see wxPGProperty::OnEvent()
700 void EditorsValueWasModified() { m_iFlags
|= wxPG_FL_VALUE_MODIFIED
; }
702 /** Reverse of EditorsValueWasModified().
705 This function should only be called by custom properties.
707 void EditorsValueWasNotModified()
709 m_iFlags
&= ~(wxPG_FL_VALUE_MODIFIED
);
713 Enables or disables (shows/hides) categories according to parameter
716 bool EnableCategories( bool enable
);
718 /** Scrolls and/or expands items to ensure that the given item is visible.
719 Returns true if something was actually done.
721 bool EnsureVisible( wxPGPropArg id
);
724 Reduces column sizes to minimum possible that contents are still
725 visibly (naturally some margin space will be applied as well).
728 Minimum size for the grid to still display everything.
731 Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
733 This function only works properly if grid size prior to call was already
736 Note that you can also get calculated column widths by calling
737 GetState->GetColumnWidth() immediately after this function returns.
741 wxSize sz
= m_pState
->DoFitColumns();
746 Returns wxWindow that the properties are painted on, and which should
747 be used as the parent for editor controls.
749 wxPanel
* GetPanel() const
754 /** Returns current category caption background colour. */
755 wxColour
GetCaptionBackgroundColour() const { return m_colCapBack
; }
757 wxFont
& GetCaptionFont() { return m_captionFont
; }
759 const wxFont
& GetCaptionFont() const { return m_captionFont
; }
761 /** Returns current category caption text colour. */
762 wxColour
GetCaptionForegroundColour() const { return m_colCapFore
; }
764 /** Returns current cell background colour. */
765 wxColour
GetCellBackgroundColour() const { return m_colPropBack
; }
767 /** Returns current cell text colour when disabled. */
768 wxColour
GetCellDisabledTextColour() const { return m_colDisPropFore
; }
770 /** Returns current cell text colour. */
771 wxColour
GetCellTextColour() const { return m_colPropFore
; }
774 Returns number of columns currently on grid.
776 unsigned int GetColumnCount() const
778 return (unsigned int) m_pState
->m_colWidths
.size();
781 /** Returns colour of empty space below properties. */
782 wxColour
GetEmptySpaceColour() const { return m_colEmptySpace
; }
784 /** Returns height of highest characters of used font. */
785 int GetFontHeight() const { return m_fontHeight
; }
787 /** Returns pointer to itself. Dummy function that enables same kind
788 of code to use wxPropertyGrid and wxPropertyGridManager.
790 wxPropertyGrid
* GetGrid() { return this; }
792 /** Returns rectangle of custom paint image.
794 wxRect
GetImageRect( wxPGProperty
* p
, int item
) const;
796 /** Returns size of the custom paint image in front of property.
797 If no argument is given, returns preferred size.
799 wxSize
GetImageSize( wxPGProperty
* p
= NULL
, int item
= -1 ) const;
802 /** Returns last item which could be iterated using given flags.
804 See @ref propgrid_iterator_flags.
806 wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
)
808 return m_pState
->GetLastItem(flags
);
811 const wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
) const
813 return m_pState
->GetLastItem(flags
);
817 /** Returns colour of lines between cells. */
818 wxColour
GetLineColour() const { return m_colLine
; }
820 /** Returns background colour of margin. */
821 wxColour
GetMarginColour() const { return m_colMargin
; }
824 Returns most up-to-date value of selected property. This will return
825 value different from GetSelectedProperty()->GetValue() only when text
826 editor is activate and string edited by user represents valid,
827 uncommitted property value.
829 wxVariant
GetUncommittedPropertyValue();
831 /** Returns "root property". It does not have name, etc. and it is not
832 visible. It is only useful for accessing its children.
834 wxPGProperty
* GetRoot() const { return m_pState
->m_properties
; }
836 /** Returns height of a single grid row (in pixels). */
837 int GetRowHeight() const { return m_lineHeight
; }
839 /** Returns currently selected property. */
840 wxPGProperty
* GetSelectedProperty() const { return GetSelection(); }
842 /** Returns currently selected property. */
843 wxPGProperty
* GetSelection() const
848 /** Returns current selection background colour. */
849 wxColour
GetSelectionBackgroundColour() const { return m_colSelBack
; }
851 /** Returns current selection text colour. */
852 wxColour
GetSelectionForegroundColour() const { return m_colSelFore
; }
854 /** Returns current splitter x position. */
855 int GetSplitterPosition() const
856 { return m_pState
->DoGetSplitterPosition(0); }
858 /** Returns wxTextCtrl active in currently selected property, if any. Takes
859 into account wxOwnerDrawnComboBox.
861 wxTextCtrl
* GetEditorTextCtrl() const;
863 wxPGValidationInfo
& GetValidationInfo()
865 return m_validationInfo
;
868 /** Returns current vertical spacing. */
869 int GetVerticalSpacing() const { return (int)m_vspacing
; }
872 Returns @true if a property editor control has focus.
874 bool IsEditorFocused() const;
876 /** Returns true if editor's value was marked modified.
878 bool IsEditorsValueModified() const
879 { return ( m_iFlags
& wxPG_FL_VALUE_MODIFIED
) ? true : false; }
882 Returns information about arbitrary position in the grid.
885 Coordinates in the virtual grid space. You may need to use
886 wxScrolledWindow::CalcScrolledPosition() for translating
887 wxPropertyGrid client coordinates into something this member
890 wxPropertyGridHitTestResult
HitTest( const wxPoint
& pt
) const;
892 /** Returns true if any property has been modified by the user. */
893 bool IsAnyModified() const { return (m_pState
->m_anyModified
>0); }
896 Returns true if updating is frozen (ie Freeze() called but not yet
899 bool IsFrozen() const { return (m_frozen
>0)?true:false; }
902 It is recommended that you call this function any time your code causes
903 wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle()
904 handler should be able to detect most changes, but it is not perfect.
907 New top-level parent that is about to be set. Old top-level parent
908 window should still exist as the current one.
910 @remarks This function is automatically called from wxPropertyGrid::
911 Reparent() and wxPropertyGridManager::Reparent(). You only
912 need to use it if you reparent wxPropertyGrid indirectly.
914 void OnTLPChanging( wxWindow
* newTLP
);
916 /** Redraws given property.
918 virtual void RefreshProperty( wxPGProperty
* p
);
921 /** Registers a new editor class.
923 Pointer to the editor class instance that should be used.
925 static wxPGEditor
* RegisterEditorClass( wxPGEditor
* editor
,
926 bool noDefCheck
= false )
928 return DoRegisterEditorClass(editor
, wxEmptyString
, noDefCheck
);
931 static wxPGEditor
* DoRegisterEditorClass( wxPGEditor
* editorClass
,
932 const wxString
& editorName
,
933 bool noDefCheck
= false );
936 /** Resets all colours to the original system values.
942 Editor widget is automatically created, but not focused unless focus is
949 True if selection finished successfully. Usually only fails if
950 current value in editor is not valid.
952 @remarks In wxPropertyGrid 1.4, this member function used to generate
953 wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer
956 @see wxPropertyGrid::Unselect
958 bool SelectProperty( wxPGPropArg id
, bool focus
= false );
960 /** Sets category caption background colour. */
961 void SetCaptionBackgroundColour(const wxColour
& col
);
963 /** Sets category caption text colour. */
964 void SetCaptionTextColour(const wxColour
& col
);
966 /** Sets default cell background colour - applies to property cells.
967 Note that appearance of editor widgets may not be affected.
969 void SetCellBackgroundColour(const wxColour
& col
);
971 /** Sets cell text colour for disabled properties.
973 void SetCellDisabledTextColour(const wxColour
& col
);
975 /** Sets default cell text colour - applies to property name and value text.
976 Note that appearance of editor widgets may not be affected.
978 void SetCellTextColour(const wxColour
& col
);
980 /** Set number of columns (2 or more).
982 void SetColumnCount( int colCount
)
984 m_pState
->SetColumnCount(colCount
);
989 Sets the 'current' category - Append will add non-category properties
992 void SetCurrentCategory( wxPGPropArg id
)
994 wxPG_PROP_ARG_CALL_PROLOG()
995 wxPropertyCategory
* pc
= wxDynamicCast(p
, wxPropertyCategory
);
997 m_pState
->m_currentCategory
= pc
;
1000 /** Sets colour of empty space below properties. */
1001 void SetEmptySpaceColour(const wxColour
& col
);
1003 /** Sets colour of lines between cells. */
1004 void SetLineColour(const wxColour
& col
);
1006 /** Sets background colour of margin. */
1007 void SetMarginColour(const wxColour
& col
);
1010 Sets selection background colour - applies to selected property name
1013 void SetSelectionBackgroundColour(const wxColour
& col
);
1016 Sets selection foreground colour - applies to selected property name
1019 void SetSelectionTextColour(const wxColour
& col
);
1021 /** Sets x coordinate of the splitter.
1023 Splitter position cannot exceed grid size, and therefore setting it
1024 during form creation may fail as initial grid size is often smaller
1025 than desired splitter position, especially when sizers are being used.
1027 void SetSplitterPosition( int newxpos
, int col
= 0 )
1029 DoSetSplitterPosition_(newxpos
, true, col
);
1030 m_iFlags
|= wxPG_FL_SPLITTER_PRE_SET
;
1034 Sets the property sorting function.
1037 The sorting function to be used. It should return a value greater
1038 than 0 if position of p1 is after p2. So, for instance, when
1039 comparing property names, you can use following implementation:
1042 int MyPropertySortFunction(wxPropertyGrid* propGrid,
1046 return p1->GetBaseName().compare( p2->GetBaseName() );
1051 Default property sort function sorts properties by their labels
1052 (case-insensitively).
1054 @see GetSortFunction, wxPropertyGridInterface::Sort,
1055 wxPropertyGridInterface::SortChildren
1057 void SetSortFunction( wxPGSortCallback sortFunction
)
1059 m_sortFunction
= sortFunction
;
1063 Returns the property sort function (default is @NULL).
1065 @see SetSortFunction
1067 wxPGSortCallback
GetSortFunction() const
1069 return m_sortFunction
;
1072 /** Set virtual width for this particular page. Width -1 indicates that the
1073 virtual width should be disabled. */
1074 void SetVirtualWidth( int width
);
1077 Moves splitter as left as possible, while still allowing all
1078 labels to be shown in full.
1080 @param privateChildrenToo
1081 If @false, will still allow private children to be cropped.
1083 void SetSplitterLeft( bool privateChildrenToo
= false )
1085 m_pState
->SetSplitterLeft(privateChildrenToo
);
1088 /** Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
1089 height. Value of 2 should be default on most platforms.
1091 void SetVerticalSpacing( int vspacing
)
1093 m_vspacing
= (unsigned char)vspacing
;
1094 CalculateFontAndBitmapStuff( vspacing
);
1095 if ( !m_pState
->m_itemsAdded
) Refresh();
1098 /** Shows an brief error message that is related to a property. */
1099 void ShowPropertyError( wxPGPropArg id
, const wxString
& msg
)
1101 wxPG_PROP_ARG_CALL_PROLOG()
1102 DoShowPropertyError(p
, msg
);
1105 /////////////////////////////////////////////////////////////////
1107 // Following methods do not need to be (currently) documented
1109 /////////////////////////////////////////////////////////////////
1111 bool HasVirtualWidth() const
1112 { return (m_iFlags
& wxPG_FL_HAS_VIRTUAL_WIDTH
) ? true : false; }
1114 const wxPGCommonValue
* GetCommonValue( unsigned int i
) const
1116 return (wxPGCommonValue
*) m_commonValues
[i
];
1119 /** Returns number of common values.
1121 unsigned int GetCommonValueCount() const
1123 return (unsigned int) m_commonValues
.size();
1126 /** Returns label of given common value.
1128 wxString
GetCommonValueLabel( unsigned int i
) const
1130 wxASSERT( GetCommonValue(i
) );
1131 return GetCommonValue(i
)->GetLabel();
1135 Returns index of common value that will truly change value to
1138 int GetUnspecifiedCommonValue() const { return m_cvUnspecified
; }
1140 /** Set index of common value that will truly change value to unspecified.
1141 Using -1 will set none to have such effect.
1144 void SetUnspecifiedCommonValue( int index
) { m_cvUnspecified
= index
; }
1147 Shortcut for creating dialog-caller button. Used, for example, by
1150 This should only be called by properties.
1152 wxWindow
* GenerateEditorButton( const wxPoint
& pos
, const wxSize
& sz
);
1154 /** Fixes position of wxTextCtrl-like control (wxSpinCtrl usually
1155 fits as one). Call after control has been created (but before
1158 void FixPosForTextCtrl( wxWindow
* ctrl
,
1159 const wxPoint
& offset
= wxPoint(0, 0) );
1161 /** Shortcut for creating text editor widget.
1163 Same as pos given for CreateEditor.
1165 Same as sz given for CreateEditor.
1167 Initial text for wxTextCtrl.
1169 If right-side control, such as button, also created, then create it
1170 first and pass it as this parameter.
1172 Extra style flags to pass for wxTextCtrl.
1174 Note that this should generally be called only by new classes derived
1177 wxWindow
* GenerateEditorTextCtrl( const wxPoint
& pos
,
1179 const wxString
& value
,
1180 wxWindow
* secondary
,
1184 /* Generates both textctrl and button.
1186 wxWindow
* GenerateEditorTextCtrlAndButton( const wxPoint
& pos
,
1187 const wxSize
& sz
, wxWindow
** psecondary
, int limited_editing
,
1188 wxPGProperty
* property
);
1190 /** Generates position for a widget editor dialog box.
1192 Property for which dialog is positioned.
1194 Known or over-approximated size of the dialog.
1196 Position for dialog.
1198 wxPoint
GetGoodEditorDialogPosition( wxPGProperty
* p
,
1201 // Converts escape sequences in src_str to newlines,
1202 // tabs, etc. and copies result to dst_str.
1203 static wxString
& ExpandEscapeSequences( wxString
& dst_str
,
1204 wxString
& src_str
);
1206 // Converts newlines, tabs, etc. in src_str to escape
1207 // sequences, and copies result to dst_str.
1208 static wxString
& CreateEscapeSequences( wxString
& dst_str
,
1209 wxString
& src_str
);
1212 Returns rectangle that fully contains properties between and including
1215 wxRect
GetPropertyRect( const wxPGProperty
* p1
,
1216 const wxPGProperty
* p2
) const;
1218 /** Returns pointer to current active primary editor control (NULL if none).
1220 wxWindow
* GetEditorControl() const;
1222 wxWindow
* GetPrimaryEditor() const
1224 return GetEditorControl();
1228 Returns pointer to current active secondary editor control (NULL if
1231 wxWindow
* GetEditorControlSecondary() const
1233 return m_wndEditor2
;
1237 Refreshes any active editor control.
1239 void RefreshEditor();
1241 // Events from editor controls are forward to this function
1242 void HandleCustomEditorEvent( wxEvent
&event
);
1247 Generates contents for string dst based on the contents of
1250 Format will be "(preDelim)str1(postDelim) (preDelim)str2(postDelim) and
1251 so on. Set flags to 1 inorder to convert backslashes to double-back-
1252 slashes and "(preDelims)"'s to "(preDelims)".
1254 static void ArrayStringToString( wxString
& dst
, const wxArrayString
& src
,
1255 wxChar preDelim
, wxChar postDelim
,
1258 // Mostly useful for page switching.
1259 void SwitchState( wxPropertyGridPageState
* pNewState
);
1261 long GetInternalFlags() const { return m_iFlags
; }
1262 bool HasInternalFlag( long flag
) const
1263 { return (m_iFlags
& flag
) ? true : false; }
1264 void SetInternalFlag( long flag
) { m_iFlags
|= flag
; }
1265 void ClearInternalFlag( long flag
) { m_iFlags
&= ~(flag
); }
1266 void IncFrozen() { m_frozen
++; }
1267 void DecFrozen() { m_frozen
--; }
1269 void OnComboItemPaint( const wxPGComboBox
* pCb
,
1275 /** Standardized double-to-string conversion.
1277 static void DoubleToString( wxString
& target
,
1281 wxString
* precTemplate
);
1284 Call this from wxPGProperty::OnEvent() to cause property value to be
1285 changed after the function returns (with true as return value).
1286 ValueChangeInEvent() must be used if you wish the application to be
1287 able to use wxEVT_PG_CHANGING to potentially veto the given value.
1289 void ValueChangeInEvent( wxVariant variant
)
1291 m_changeInEventValue
= variant
;
1292 m_iFlags
|= wxPG_FL_VALUE_CHANGE_IN_EVENT
;
1296 You can use this member function, for instance, to detect in
1297 wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was
1298 already called in wxPGEditor::OnEvent(). It really only detects
1299 if was value was changed using wxPGProperty::SetValueInEvent(), which
1300 is usually used when a 'picker' dialog is displayed. If value was
1301 written by "normal means" in wxPGProperty::StringToValue() or
1302 IntToValue(), then this function will return false (on the other hand,
1303 wxPGProperty::OnEvent() is not even called in those cases).
1305 bool WasValueChangedInEvent() const
1307 return (m_iFlags
& wxPG_FL_VALUE_CHANGE_IN_EVENT
) ? true : false;
1310 /** Returns true if given event is from first of an array of buttons
1311 (as can be in case when wxPGMultiButton is used).
1313 bool IsMainButtonEvent( const wxEvent
& event
)
1315 return (event
.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED
)
1316 && (m_wndSecId
== event
.GetId());
1319 /** Pending value is expected to be passed in PerformValidation().
1321 virtual bool DoPropertyChanged( wxPGProperty
* p
,
1322 unsigned int selFlags
= 0 );
1324 /** Called when validation for given property fails.
1326 Value which failed in validation.
1328 Return true if user is allowed to change to another property even
1329 if current has invalid value.
1331 To add your own validation failure behavior, override
1332 wxPropertyGrid::DoOnValidationFailure().
1334 bool OnValidationFailure( wxPGProperty
* property
,
1335 wxVariant
& invalidValue
);
1337 /** Called to indicate property and editor has valid value now.
1339 void OnValidationFailureReset( wxPGProperty
* property
)
1341 if ( property
&& property
->HasFlag(wxPG_PROP_INVALID_VALUE
) )
1343 DoOnValidationFailureReset(property
);
1344 property
->ClearFlag(wxPG_PROP_INVALID_VALUE
);
1346 m_validationInfo
.m_failureMessage
.clear();
1349 /** Override in derived class to display error messages in custom manner
1350 (these message usually only result from validation failure).
1352 virtual void DoShowPropertyError( wxPGProperty
* property
,
1353 const wxString
& msg
);
1355 /** Override to customize property validation failure behavior.
1357 Value which failed in validation.
1359 Return true if user is allowed to change to another property even
1360 if current has invalid value.
1362 virtual bool DoOnValidationFailure( wxPGProperty
* property
,
1363 wxVariant
& invalidValue
);
1365 /** Override to customize resetting of property validation failure status.
1367 Property is guaranteed to have flag wxPG_PROP_INVALID_VALUE set.
1369 virtual void DoOnValidationFailureReset( wxPGProperty
* property
);
1371 int GetSpacingY() const { return m_spacingy
; }
1374 Must be called in wxPGEditor::CreateControls() if primary editor window
1375 is wxTextCtrl, just before textctrl is created.
1377 Initial text value of created wxTextCtrl.
1379 void SetupTextCtrlValue( const wxString text
) { m_prevTcValue
= text
; }
1382 Unfocuses or closes editor if one was open, but does not deselect
1385 bool UnfocusEditor();
1387 virtual void SetWindowStyleFlag( long style
);
1389 void DrawItems( const wxPGProperty
* p1
, const wxPGProperty
* p2
);
1391 void DrawItem( wxPGProperty
* p
)
1396 virtual void DrawItemAndChildren( wxPGProperty
* p
);
1399 Draws item, children, and consequtive parents as long as category is
1402 void DrawItemAndValueRelated( wxPGProperty
* p
);
1407 wxPropertyGridPageState used by the grid is created here.
1409 If grid is used in wxPropertyGridManager, there is no point overriding
1410 this - instead, set custom wxPropertyGridPage classes.
1412 virtual wxPropertyGridPageState
* CreateState() const;
1414 enum PerformValidationFlags
1416 SendEvtChanging
= 0x0001,
1417 IsStandaloneValidation
= 0x0002 // Not called in response to event
1421 Runs all validation functionality (includes sending wxEVT_PG_CHANGING).
1422 Returns true if all tests passed. Implement in derived class to
1423 add additional validation behavior.
1425 virtual bool PerformValidation( wxPGProperty
* p
,
1426 wxVariant
& pendingValue
,
1427 int flags
= SendEvtChanging
);
1431 // Control font changer helper.
1432 void SetCurControlBoldFont();
1434 wxPGCell
& GetPropertyDefaultCell()
1436 return m_propertyDefaultCell
;
1439 wxPGCell
& GetCategoryDefaultCell()
1441 return m_categoryDefaultCell
;
1445 // Public methods for semi-public use
1446 // (not protected for optimization)
1448 bool DoSelectProperty( wxPGProperty
* p
, unsigned int flags
= 0 );
1450 // Overridden functions.
1451 virtual bool Destroy();
1452 // Returns property at given y coordinate (relative to grid's top left).
1453 wxPGProperty
* GetItemAtY( int y
) const { return DoGetItemAtY(y
); }
1455 virtual void Refresh( bool eraseBackground
= true,
1456 const wxRect
*rect
= (const wxRect
*) NULL
);
1457 virtual bool SetFont( const wxFont
& font
);
1458 #if wxPG_SUPPORT_TOOLTIPS
1459 void SetToolTip( const wxString
& tipString
);
1461 virtual void Freeze();
1462 virtual void SetExtraStyle( long exStyle
);
1463 virtual void Thaw();
1464 virtual bool Reparent( wxWindowBase
*newParent
);
1467 virtual wxSize
DoGetBestSize() const;
1469 #ifndef wxPG_ICON_WIDTH
1470 wxBitmap
*m_expandbmp
, *m_collbmp
;
1473 wxCursor
*m_cursorSizeWE
;
1475 /** wxWindow pointers to editor control(s). */
1476 wxWindow
*m_wndEditor
;
1477 wxWindow
*m_wndEditor2
;
1479 /** wxPGCanvas instance. */
1482 #if wxPG_DOUBLE_BUFFER
1483 wxBitmap
*m_doubleBuffer
;
1486 /** Local time ms when control was created. */
1487 wxLongLong m_timeCreated
;
1489 /** wxPGProperty::OnEvent can change value by setting this. */
1490 wxVariant m_changeInEventValue
;
1492 /** Id of m_wndEditor2, or its first child, if any. */
1495 /** Extra Y spacing between the items. */
1498 /** Control client area width; updated on resize. */
1501 /** Control client area height; updated on resize. */
1504 /** Current non-client width (needed when auto-centering). */
1507 /** Non-client width (auto-centering helper). */
1510 /** Previously recorded scroll start position. */
1514 The gutter spacing in front and back of the image.
1515 This determines the amount of spacing in front of each item
1519 /** Includes separator line. */
1522 /** Gutter*2 + image width. */
1525 // y spacing for expand/collapse button.
1526 int m_buttonSpacingY
;
1528 /** Extra margin for expanded sub-group items. */
1529 int m_subgroup_extramargin
;
1532 The image width of the [+] icon.
1534 This is also calculated in the gutter
1538 #ifndef wxPG_ICON_WIDTH
1541 The image height of the [+] icon.
1543 This is calculated as minimal size and to align
1548 /** Current cursor id. */
1552 This captionFont is made equal to the font of the wxScrolledWindow.
1554 As extra the bold face is set on it when this is wanted by the user
1557 wxFont m_captionFont
;
1559 int m_fontHeight
; // Height of the font.
1561 /** m_splitterx when drag began. */
1562 int m_startingSplitterX
;
1565 Index to splitter currently being dragged (0=one after the first
1568 int m_draggedSplitter
;
1570 /** Changed property, calculated in PerformValidation(). */
1571 wxPGProperty
* m_chgInfo_changedProperty
;
1574 Lowest property for which editing happened, but which does not have
1577 wxPGProperty
* m_chgInfo_baseChangedProperty
;
1579 /** Changed property value, calculated in PerformValidation(). */
1580 wxVariant m_chgInfo_pendingValue
;
1582 /** Passed to SetValue. */
1583 wxVariant m_chgInfo_valueList
;
1585 /** Validation information. */
1586 wxPGValidationInfo m_validationInfo
;
1588 /** Actions and keys that trigger them. */
1589 wxPGHashMapI2I m_actionTriggers
;
1595 /** Bits are used to indicate which colours are customized. */
1596 unsigned short m_coloursCustomized
;
1598 /** x - m_splitterx. */
1599 signed char m_dragOffset
;
1601 /** 0 = not dragging, 1 = drag just started, 2 = drag in progress */
1602 unsigned char m_dragStatus
;
1604 /** 0 = margin, 1 = label, 2 = value. */
1605 unsigned char m_mouseSide
;
1607 /** True when editor control is focused. */
1608 unsigned char m_editorFocused
;
1610 /** 1 if m_latsCaption is also the bottommost caption. */
1611 //unsigned char m_lastCaptionBottomnest;
1613 /** Set to 1 when graphics frozen. */
1614 unsigned char m_frozen
;
1616 unsigned char m_vspacing
;
1618 // Used to track when Alt/Ctrl+Key was consumed.
1619 unsigned char m_keyComboConsumed
;
1621 /** 1 if in DoPropertyChanged() */
1622 unsigned char m_inDoPropertyChanged
;
1624 /** 1 if in CommitChangesFromEditor() */
1625 unsigned char m_inCommitChangesFromEditor
;
1627 /** 1 if in DoSelectProperty() */
1628 unsigned char m_inDoSelectProperty
;
1630 wxPGVFBFlags m_permanentValidationFailureBehavior
; // Set by app
1632 /** Internal flags - see wxPG_FL_XXX constants. */
1635 /** When drawing next time, clear this many item slots at the end. */
1636 int m_clearThisMany
;
1638 /** Pointer to selected property. Note that this is duplicated in
1639 m_state for better transiency between pages so that the selected
1640 item can be retained.
1642 wxPGProperty
* m_selected
;
1644 // pointer to property that has mouse hovering
1645 wxPGProperty
* m_propHover
;
1647 // EventObject for wxPropertyGridEvents
1648 wxWindow
* m_eventObject
;
1650 // What (global) window is currently focused (needed to resolve event
1652 wxWindow
* m_curFocused
;
1654 // Last known top-level parent
1657 // Last closed top-level parent
1658 wxWindow
* m_tlpClosed
;
1660 // Local time ms when tlp was closed.
1661 wxLongLong m_tlpClosedTime
;
1664 wxPGSortCallback m_sortFunction
;
1666 // y coordinate of property that mouse hovering
1668 // Which column's editor is selected (usually 1)?
1671 // x relative to splitter (needed for resize).
1674 // lines between cells
1676 // property labels and values are written in this colour
1677 wxColour m_colPropFore
;
1678 // or with this colour when disabled
1679 wxColour m_colDisPropFore
;
1680 // background for m_colPropFore
1681 wxColour m_colPropBack
;
1682 // text color for captions
1683 wxColour m_colCapFore
;
1684 // background color for captions
1685 wxColour m_colCapBack
;
1686 // foreground for selected property
1687 wxColour m_colSelFore
;
1688 // background for selected property (actually use background color when
1689 // control out-of-focus)
1690 wxColour m_colSelBack
;
1691 // background colour for margin
1692 wxColour m_colMargin
;
1693 // background colour for empty space below the grid
1694 wxColour m_colEmptySpace
;
1696 // Default property colours
1697 wxPGCell m_propertyDefaultCell
;
1699 // Default property category
1700 wxPGCell m_categoryDefaultCell
;
1702 // Backup of selected property's cells
1703 wxVector
<wxPGCell
> m_propCellsBackup
;
1705 // NB: These *cannot* be moved to globals.
1707 // labels when properties use common values
1708 wxVector
<wxPGCommonValue
*> m_commonValues
;
1710 // Which cv selection really sets value to unspecified?
1711 int m_cvUnspecified
;
1713 // Used to skip excess text editor events
1714 wxString m_prevTcValue
;
1718 // Sets some members to defaults (called constructors).
1721 // Initializes some members (called by Create and complex constructor).
1724 void OnPaint(wxPaintEvent
&event
);
1726 // main event receivers
1727 void OnMouseMove( wxMouseEvent
&event
);
1728 void OnMouseMoveBottom( wxMouseEvent
&event
);
1729 void OnMouseClick( wxMouseEvent
&event
);
1730 void OnMouseRightClick( wxMouseEvent
&event
);
1731 void OnMouseDoubleClick( wxMouseEvent
&event
);
1732 void OnMouseUp( wxMouseEvent
&event
);
1733 void OnKey( wxKeyEvent
&event
);
1734 void OnResize( wxSizeEvent
&event
);
1737 bool HandleMouseMove( int x
, unsigned int y
, wxMouseEvent
&event
);
1738 bool HandleMouseClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1739 bool HandleMouseRightClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1740 bool HandleMouseDoubleClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1741 bool HandleMouseUp( int x
, unsigned int y
, wxMouseEvent
&event
);
1742 void HandleKeyEvent( wxKeyEvent
&event
, bool fromChild
);
1744 void OnMouseEntry( wxMouseEvent
&event
);
1746 void OnIdle( wxIdleEvent
&event
);
1747 void OnFocusEvent( wxFocusEvent
&event
);
1748 void OnChildFocusEvent( wxChildFocusEvent
& event
);
1750 bool OnMouseCommon( wxMouseEvent
&event
, int* px
, int *py
);
1751 bool OnMouseChildCommon( wxMouseEvent
&event
, int* px
, int *py
);
1753 // sub-control event handlers
1754 void OnMouseClickChild( wxMouseEvent
&event
);
1755 void OnMouseRightClickChild( wxMouseEvent
&event
);
1756 void OnMouseMoveChild( wxMouseEvent
&event
);
1757 void OnMouseUpChild( wxMouseEvent
&event
);
1758 void OnChildKeyDown( wxKeyEvent
&event
);
1760 void OnCaptureChange( wxMouseCaptureChangedEvent
&event
);
1762 void OnScrollEvent( wxScrollWinEvent
&event
);
1764 void OnSysColourChanged( wxSysColourChangedEvent
&event
);
1766 void OnTLPClose( wxCloseEvent
& event
);
1771 Adjust the centering of the bitmap icons (collapse / expand) when the
1772 caption font changes.
1774 They need to be centered in the middle of the font, so a bit of deltaY
1775 adjustment is needed. On entry, m_captionFont must be set to window
1776 font. It will be modified properly.
1778 void CalculateFontAndBitmapStuff( int vspacing
);
1780 wxRect
GetEditorWidgetRect( wxPGProperty
* p
, int column
) const;
1782 void CorrectEditorWidgetSizeX();
1784 /** Called in RecalculateVirtualSize() to reposition control
1785 on virtual height changes.
1787 void CorrectEditorWidgetPosY();
1789 /** Deselect current selection, if any. Returns true if success
1790 (ie. validator did not intercept).
1792 Unlike ClearSelection(), DoClearSelection() sends the
1793 wxEVT_PG_SELECTED event.
1795 bool DoClearSelection();
1797 int DoDrawItems( wxDC
& dc
,
1798 const wxRect
* clipRect
,
1799 bool isBuffered
) const;
1801 /** Draws an expand/collapse (ie. +/-) button.
1803 virtual void DrawExpanderButton( wxDC
& dc
, const wxRect
& rect
,
1804 wxPGProperty
* property
) const;
1806 /** Draws items from topitemy to bottomitemy */
1807 void DrawItems( wxDC
& dc
, unsigned int topitemy
, unsigned int bottomitemy
,
1808 const wxRect
* clip_rect
= (const wxRect
*) NULL
);
1810 // Translate wxKeyEvent to wxPG_ACTION_XXX
1811 int KeyEventToActions(wxKeyEvent
&event
, int* pSecond
) const;
1813 int KeyEventToAction(wxKeyEvent
&event
) const
1815 return KeyEventToActions(event
, NULL
);
1818 void ImprovedClientToScreen( int* px
, int* py
);
1820 // Called by focus event handlers. newFocused is the window that becomes
1822 void HandleFocusChange( wxWindow
* newFocused
);
1824 /** Reloads all non-customized colours from system settings. */
1825 void RegainColours();
1827 bool DoEditorValidate();
1829 wxPGProperty
* DoGetItemAtY( int y
) const;
1831 void DoSetSplitterPosition_( int newxpos
,
1832 bool refresh
= true,
1833 int splitterIndex
= 0,
1834 bool allPages
= false );
1838 virtual bool DoExpand( wxPGProperty
* p
, bool sendEvent
= false );
1840 virtual bool DoCollapse( wxPGProperty
* p
, bool sendEvent
= false );
1842 // Returns nearest paint visible property (such that will be painted unless
1843 // window is scrolled or resized). If given property is paint visible, then
1844 // it itself will be returned.
1845 wxPGProperty
* GetNearestPaintVisible( wxPGProperty
* p
) const;
1847 static void RegisterDefaultEditors();
1849 // Sets up basic event handling for child control
1850 void SetupChildEventHandling( wxWindow
* wnd
);
1852 void CustomSetCursor( int type
, bool override
= false );
1855 Repositions scrollbar and underlying panel according to changed virtual
1858 void RecalculateVirtualSize( int forceXPos
= -1 );
1860 void PrepareAfterItemsAdded();
1862 bool SendEvent( int eventType
,
1864 wxVariant
* pValue
= NULL
,
1865 unsigned int selFlags
= 0 );
1867 void SetFocusOnCanvas();
1869 bool DoHideProperty( wxPGProperty
* p
, bool hide
, int flags
);
1873 bool ButtonTriggerKeyTest( int action
, wxKeyEvent
& event
);
1875 DECLARE_EVENT_TABLE()
1876 #endif // #ifndef SWIG
1879 // -----------------------------------------------------------------------
1881 // Bunch of inlines that need to resolved after all classes have been defined.
1885 inline bool wxPropertyGridPageState::IsDisplayed() const
1887 return ( this == m_pPropGrid
->GetState() );
1890 inline unsigned int wxPropertyGridPageState::GetActualVirtualHeight() const
1892 return DoGetRoot()->GetChildrenHeight(GetGrid()->GetRowHeight());
1896 inline int wxPGProperty::GetDisplayedCommonValueCount() const
1898 if ( HasFlag(wxPG_PROP_USES_COMMON_VALUE
) )
1900 wxPropertyGrid
* pg
= GetGrid();
1902 return (int) pg
->GetCommonValueCount();
1907 inline void wxPGProperty::SetDefaultValue( wxVariant
& value
)
1909 SetAttribute(wxPG_ATTR_DEFAULT_VALUE
, value
);
1912 inline void wxPGProperty::SetEditor( const wxString
& editorName
)
1914 m_customEditor
= wxPropertyGridInterface::GetEditorByName(editorName
);
1917 inline void wxPGProperty::SetName( const wxString
& newName
)
1919 GetGrid()->SetPropertyName(this, newName
);
1922 inline bool wxPGProperty::Hide( bool hide
, int flags
)
1924 return GetGrid()->HideProperty(this, hide
, flags
);
1927 inline bool wxPGProperty::SetMaxLength( int maxLen
)
1929 return GetGrid()->SetPropertyMaxLength(this,maxLen
);
1932 // -----------------------------------------------------------------------
1934 #define wxPG_BASE_EVT_PRE_ID 1775
1938 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_SELECTED
, wxPropertyGridEvent
);
1939 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_CHANGING
, wxPropertyGridEvent
);
1940 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_CHANGED
, wxPropertyGridEvent
);
1941 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_HIGHLIGHTED
, wxPropertyGridEvent
);
1942 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_RIGHT_CLICK
, wxPropertyGridEvent
);
1943 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_PAGE_CHANGED
, wxPropertyGridEvent
);
1944 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_ITEM_COLLAPSED
, wxPropertyGridEvent
);
1945 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_ITEM_EXPANDED
, wxPropertyGridEvent
);
1946 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_DOUBLE_CLICK
, wxPropertyGridEvent
);
1950 wxEVT_PG_SELECTED
= wxPG_BASE_EVT_PRE_ID
,
1953 wxEVT_PG_HIGHLIGHTED
,
1954 wxEVT_PG_RIGHT_CLICK
,
1955 wxEVT_PG_PAGE_CHANGED
,
1956 wxEVT_PG_ITEM_COLLAPSED
,
1957 wxEVT_PG_ITEM_EXPANDED
,
1958 wxEVT_PG_DOUBLE_CLICK
1963 #define wxPG_BASE_EVT_TYPE wxEVT_PG_SELECTED
1964 #define wxPG_MAX_EVT_TYPE (wxPG_BASE_EVT_TYPE+30)
1968 typedef void (wxEvtHandler::*wxPropertyGridEventFunction
)(wxPropertyGridEvent
&);
1970 #define EVT_PG_SELECTED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_SELECTED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
1971 #define EVT_PG_CHANGING(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGING, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
1972 #define EVT_PG_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
1973 #define EVT_PG_HIGHLIGHTED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_HIGHLIGHTED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
1974 #define EVT_PG_RIGHT_CLICK(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_RIGHT_CLICK, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
1975 #define EVT_PG_DOUBLE_CLICK(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_DOUBLE_CLICK, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
1976 #define EVT_PG_PAGE_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_PAGE_CHANGED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
1977 #define EVT_PG_ITEM_COLLAPSED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_COLLAPSED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
1978 #define EVT_PG_ITEM_EXPANDED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_EXPANDED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
1980 #define wxPropertyGridEventHandler(fn) \
1981 wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn )
1986 /** @class wxPropertyGridEvent
1988 A propertygrid event holds information about events associated with
1989 wxPropertyGrid objects.
1991 @library{wxpropgrid}
1994 class WXDLLIMPEXP_PROPGRID wxPropertyGridEvent
: public wxCommandEvent
1999 wxPropertyGridEvent(wxEventType commandType
=0, int id
=0);
2001 /** Copy constructor. */
2002 wxPropertyGridEvent(const wxPropertyGridEvent
& event
);
2005 ~wxPropertyGridEvent();
2008 virtual wxEvent
* Clone() const;
2010 wxPGProperty
* GetMainParent() const
2012 wxASSERT(m_property
);
2013 return m_property
->GetMainParent();
2016 /** Returns id of associated property. */
2017 wxPGProperty
* GetProperty() const
2022 wxPGValidationInfo
& GetValidationInfo()
2024 wxASSERT(m_validationInfo
);
2025 return *m_validationInfo
;
2028 /** Returns true if you can veto the action that the event is signaling.
2030 bool CanVeto() const { return m_canVeto
; }
2033 Call this from your event handler to veto action that the event is
2036 You can only veto a shutdown if wxPropertyGridEvent::CanVeto returns
2039 Currently only wxEVT_PG_CHANGING supports vetoing.
2041 void Veto( bool veto
= true ) { m_wasVetoed
= veto
; }
2043 /** Returns value that is about to be set for wxEVT_PG_CHANGING.
2045 const wxVariant
& GetValue() const
2047 wxASSERT_MSG( m_validationInfo
,
2048 "Only call GetValue from a handler "
2049 "of event type that supports it" );
2050 return m_validationInfo
->GetValue();
2054 Set override validation failure behavior.
2056 Only effective if Veto was also called, and only allowed if event type
2057 is wxEVT_PG_CHANGING.
2059 void SetValidationFailureBehavior( wxPGVFBFlags flags
)
2061 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2062 m_validationInfo
->SetFailureBehavior( flags
);
2065 /** Sets custom failure message for this time only. Only applies if
2066 wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
2068 void SetValidationFailureMessage( const wxString
& message
)
2070 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2071 m_validationInfo
->SetFailureMessage( message
);
2075 wxPGVFBFlags
GetValidationFailureBehavior() const
2077 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2078 return m_validationInfo
->GetFailureBehavior();
2081 void SetCanVeto( bool canVeto
) { m_canVeto
= canVeto
; }
2082 bool WasVetoed() const { return m_wasVetoed
; }
2084 /** Changes the associated property. */
2085 void SetProperty( wxPGProperty
* p
) { m_property
= p
; }
2087 void SetPropertyGrid( wxPropertyGrid
* pg
) { m_pg
= pg
; }
2089 void SetupValidationInfo()
2092 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2093 m_validationInfo
= &m_pg
->GetValidationInfo();
2098 DECLARE_DYNAMIC_CLASS(wxPropertyGridEvent
)
2100 wxPGProperty
* m_property
;
2101 wxPropertyGrid
* m_pg
;
2102 wxPGValidationInfo
* m_validationInfo
;
2111 // -----------------------------------------------------------------------
2113 /** @class wxPropertyGridPopulator
2115 Allows populating wxPropertyGrid from arbitrary text source.
2117 class WXDLLIMPEXP_PROPGRID wxPropertyGridPopulator
2120 /** Default constructor.
2122 wxPropertyGridPopulator();
2125 virtual ~wxPropertyGridPopulator();
2127 void SetState( wxPropertyGridPageState
* state
);
2129 void SetGrid( wxPropertyGrid
* pg
);
2131 /** Appends a new property under bottommost parent.
2133 Property class as string.
2135 wxPGProperty
* Add( const wxString
& propClass
,
2136 const wxString
& propLabel
,
2137 const wxString
& propName
,
2138 const wxString
* propValue
,
2139 wxPGChoices
* pChoices
= NULL
);
2142 Pushes property to the back of parent array (ie it becomes bottommost
2143 parent), and starts scanning/adding children for it.
2145 When finished, parent array is returned to the original state.
2147 void AddChildren( wxPGProperty
* property
);
2149 /** Adds attribute to the bottommost property.
2151 Allowed values: "string", (same as string), "int", "bool". Empty string
2154 bool AddAttribute( const wxString
& name
,
2155 const wxString
& type
,
2156 const wxString
& value
);
2158 /** Called once in AddChildren.
2160 virtual void DoScanForChildren() = 0;
2163 Returns id of parent property for which children can currently be
2166 wxPGProperty
* GetCurParent() const
2168 return (wxPGProperty
*) m_propHierarchy
[m_propHierarchy
.size()-1];
2171 wxPropertyGridPageState
* GetState() { return m_state
; }
2172 const wxPropertyGridPageState
* GetState() const { return m_state
; }
2174 /** Like wxString::ToLong, except allows N% in addition of N.
2176 static bool ToLongPCT( const wxString
& s
, long* pval
, long max
);
2178 /** Parses strings of format "choice1"[=value1] ... "choiceN"[=valueN] into
2179 wxPGChoices. Registers parsed result using idString (if not empty).
2180 Also, if choices with given id already registered, then don't parse but
2181 return those choices instead.
2183 wxPGChoices
ParseChoices( const wxString
& choicesString
,
2184 const wxString
& idString
);
2186 /** Implement in derived class to do custom process when an error occurs.
2187 Default implementation uses wxLogError.
2189 virtual void ProcessError( const wxString
& msg
);
2193 /** Used property grid. */
2194 wxPropertyGrid
* m_pg
;
2196 /** Used property grid state. */
2197 wxPropertyGridPageState
* m_state
;
2199 /** Tree-hierarchy of added properties (that can have children). */
2200 wxArrayPGProperty m_propHierarchy
;
2202 /** Hashmap for string-id to wxPGChoicesData mapping. */
2203 wxPGHashMapS2P m_dictIdChoices
;
2206 // -----------------------------------------------------------------------
2209 // Undefine macros that are not needed outside propertygrid sources
2211 #ifndef __wxPG_SOURCE_FILE__
2212 #undef wxPG_FL_DESC_REFRESH_REQUIRED
2213 #undef wxPG_FL_SCROLLBAR_DETECTED
2214 #undef wxPG_FL_CREATEDSTATE
2215 #undef wxPG_FL_NOSTATUSBARHELP
2216 #undef wxPG_FL_SCROLLED
2217 #undef wxPG_FL_FOCUS_INSIDE_CHILD
2218 #undef wxPG_FL_FOCUS_INSIDE
2219 #undef wxPG_FL_MOUSE_INSIDE_CHILD
2220 #undef wxPG_FL_CUR_USES_CUSTOM_IMAGE
2221 #undef wxPG_FL_PRIMARY_FILLS_ENTIRE
2222 #undef wxPG_FL_VALUE_MODIFIED
2223 #undef wxPG_FL_MOUSE_INSIDE
2224 #undef wxPG_FL_FOCUSED
2225 #undef wxPG_FL_MOUSE_CAPTURED
2226 #undef wxPG_FL_INITIALIZED
2227 #undef wxPG_FL_ACTIVATION_BY_CLICK
2228 #undef wxPG_FL_DONT_CENTER_SPLITTER
2229 #undef wxPG_SUPPORT_TOOLTIPS
2230 #undef wxPG_DOUBLE_BUFFER
2231 #undef wxPG_ICON_WIDTH
2232 #undef wxPG_USE_RENDERER_NATIVE
2233 // Following are needed by the manager headers
2234 // #undef const wxString&
2237 // -----------------------------------------------------------------------
2241 #endif // _WX_PROPGRID_PROPGRID_H_