1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/propgrid/propgrid.h
3 // Purpose: wxPropertyGrid
4 // Author: Jaakko Salli
8 // Copyright: (c) Jaakko Salli
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_PROPGRID_PROPGRID_H_
13 #define _WX_PROPGRID_PROPGRID_H_
19 #include "wx/thread.h"
20 #include "wx/dcclient.h"
21 #include "wx/control.h"
22 #include "wx/scrolwin.h"
23 #include "wx/tooltip.h"
24 #include "wx/datetime.h"
25 #include "wx/recguard.h"
27 #include "wx/propgrid/property.h"
28 #include "wx/propgrid/propgridiface.h"
32 extern WXDLLIMPEXP_DATA_PROPGRID(const char) wxPropertyGridNameStr
[];
38 class WXDLLIMPEXP_FWD_CORE wxStatusBar
;
41 // -----------------------------------------------------------------------
43 // -----------------------------------------------------------------------
45 // This is required for sharing common global variables.
46 class WXDLLIMPEXP_PROPGRID wxPGGlobalVarsClass
50 wxPGGlobalVarsClass();
51 ~wxPGGlobalVarsClass();
54 // Critical section for handling the globals. Generally it is not needed
55 // since GUI code is supposed to be in single thread. However,
56 // we do want the user to be able to convey wxPropertyGridEvents to other
58 wxCriticalSection m_critSect
;
61 // Used by advprops, but here to make things easier.
62 wxString m_pDefaultImageWildcard
;
64 // Map of editor class instances (keys are name string).
65 wxPGHashMapS2P m_mapEditorClasses
;
68 wxVector
<wxValidator
*> m_arrValidators
; // These wxValidators need to be freed
71 wxPGHashMapS2P m_dictPropertyClassInfo
; // PropertyName -> ClassInfo
73 wxPGChoices
* m_fontFamilyChoices
;
75 // Replace with your own to affect all properties using default renderer.
76 wxPGCellRenderer
* m_defaultRenderer
;
78 wxPGChoices m_boolChoices
;
80 wxVariant m_vEmptyString
;
82 wxVariant m_vMinusOne
;
86 // Cached constant strings
87 wxPGCachedString m_strstring
;
88 wxPGCachedString m_strlong
;
89 wxPGCachedString m_strbool
;
90 wxPGCachedString m_strlist
;
92 wxPGCachedString m_strDefaultValue
;
93 wxPGCachedString m_strMin
;
94 wxPGCachedString m_strMax
;
95 wxPGCachedString m_strUnits
;
96 wxPGCachedString m_strHint
;
97 #if wxPG_COMPATIBILITY_1_4
98 wxPGCachedString m_strInlineHelp
;
101 // If true then some things are automatically translated
102 bool m_autoGetTranslation
;
104 // > 0 if errors cannot or should not be shown in statusbar etc.
107 int m_extraStyle
; // global extra style
111 int HasExtraStyle( int style
) const { return (m_extraStyle
& style
); }
114 extern WXDLLIMPEXP_DATA_PROPGRID(wxPGGlobalVarsClass
*) wxPGGlobalVars
;
116 #define wxPGVariant_EmptyString (wxPGGlobalVars->m_vEmptyString)
117 #define wxPGVariant_Zero (wxPGGlobalVars->m_vZero)
118 #define wxPGVariant_MinusOne (wxPGGlobalVars->m_vMinusOne)
119 #define wxPGVariant_True (wxPGGlobalVars->m_vTrue)
120 #define wxPGVariant_False (wxPGGlobalVars->m_vFalse)
122 #define wxPGVariant_Bool(A) (A?wxPGVariant_True:wxPGVariant_False)
124 // When wxPG is loaded dynamically after the application is already running
125 // then the built-in module system won't pick this one up. Add it manually.
126 WXDLLIMPEXP_PROPGRID
void wxPGInitResourceModule();
128 // -----------------------------------------------------------------------
130 /** @section propgrid_window_styles wxPropertyGrid Window Styles
132 SetWindowStyleFlag method can be used to modify some of these at run-time.
135 enum wxPG_WINDOW_STYLES
138 /** This will cause Sort() automatically after an item is added.
139 When inserting a lot of items in this mode, it may make sense to
140 use Freeze() before operations and Thaw() afterwards to increase
143 wxPG_AUTO_SORT
= 0x00000010,
145 /** Categories are not initially shown (even if added).
146 IMPORTANT NOTE: If you do not plan to use categories, then this
147 style will waste resources.
148 This flag can also be changed using wxPropertyGrid::EnableCategories method.
150 wxPG_HIDE_CATEGORIES
= 0x00000020,
152 /* This style combines non-categoric mode and automatic sorting.
154 wxPG_ALPHABETIC_MODE
= (wxPG_HIDE_CATEGORIES
|wxPG_AUTO_SORT
),
156 /** Modified values are shown in bold font. Changing this requires Refresh()
159 wxPG_BOLD_MODIFIED
= 0x00000040,
161 /** Using this style, the column splitters move automatically based on column
162 proportions (default is equal proportion for every column). This behavior
163 stops once the user manually moves a splitter, and returns when a
164 splitter is double-clicked.
166 @see wxPropertyGridInterface::SetColumnProportion().
168 wxPG_SPLITTER_AUTO_CENTER
= 0x00000080,
170 /** Display tooltips for cell text that cannot be shown completely. If
171 wxUSE_TOOLTIPS is 0, then this doesn't have any effect.
173 wxPG_TOOLTIPS
= 0x00000100,
175 /** Disables margin and hides all expand/collapse buttons that would appear
176 outside the margin (for sub-properties). Toggling this style automatically
177 expands all collapsed items.
179 wxPG_HIDE_MARGIN
= 0x00000200,
181 /** This style prevents user from moving the splitter.
183 wxPG_STATIC_SPLITTER
= 0x00000400,
185 /** Combination of other styles that make it impossible for user to modify
188 wxPG_STATIC_LAYOUT
= (wxPG_HIDE_MARGIN
|wxPG_STATIC_SPLITTER
),
190 /** Disables wxTextCtrl based editors for properties which
191 can be edited in another way.
193 Equals calling wxPropertyGrid::LimitPropertyEditing for all added
196 wxPG_LIMITED_EDITING
= 0x00000800,
198 /** wxPropertyGridManager only: Show toolbar for mode and page selection. */
199 wxPG_TOOLBAR
= 0x00001000,
201 /** wxPropertyGridManager only: Show adjustable text box showing description
202 or help text, if available, for currently selected property.
204 wxPG_DESCRIPTION
= 0x00002000,
206 /** wxPropertyGridManager only: don't show an internal border around the
207 property grid. Recommended if you use a header.
209 wxPG_NO_INTERNAL_BORDER
= 0x00004000
212 #if wxPG_COMPATIBILITY_1_4
213 // In wxPG 1.4 this was used to enable now-default theme border support
214 // in wxPropertyGridManager.
215 #define wxPG_THEME_BORDER 0x00000000
219 enum wxPG_EX_WINDOW_STYLES
223 NOTE: wxPG_EX_xxx are extra window styles and must be set using
224 SetExtraStyle() member function.
226 Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if
227 wxPG_HIDE_CATEGORIES is not defined, the non-categorized data storage is
228 not activated, and switching the mode first time becomes somewhat slower.
229 wxPG_EX_INIT_NOCAT activates the non-categorized data storage right away.
230 IMPORTANT NOTE: If you do plan not switching to non-categoric mode, or if
231 you don't plan to use categories at all, then using this style will result
232 in waste of resources.
235 wxPG_EX_INIT_NOCAT
= 0x00001000,
237 /** Extended window style that sets wxPropertyGridManager toolbar to not
240 wxPG_EX_NO_FLAT_TOOLBAR
= 0x00002000,
242 /** Shows alphabetic/categoric mode buttons from toolbar.
244 wxPG_EX_MODE_BUTTONS
= 0x00008000,
246 /** Show property help strings as tool tips instead as text on the status bar.
247 You can set the help strings using SetPropertyHelpString member function.
249 wxPG_EX_HELP_AS_TOOLTIPS
= 0x00010000,
251 /** Prevent TAB from focusing to wxButtons. This behavior was default
252 in version 1.2.0 and earlier.
253 NOTE! Tabbing to button doesn't work yet. Problem seems to be that on wxMSW
254 atleast the button doesn't properly propagate key events (yes, I'm using
257 //wxPG_EX_NO_TAB_TO_BUTTON = 0x00020000,
259 /** Allows relying on native double-buffering.
261 wxPG_EX_NATIVE_DOUBLE_BUFFERING
= 0x00080000,
263 /** Set this style to let user have ability to set values of properties to
264 unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for
267 wxPG_EX_AUTO_UNSPECIFIED_VALUES
= 0x00200000,
270 If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION
271 and wxPG_STRING_PASSWORD) are not stored into property's attribute storage
272 (thus they are not readable).
274 Note that this option is global, and applies to all wxPG property
277 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES
= 0x00400000,
279 /** Hides page selection buttons from toolbar.
281 wxPG_EX_HIDE_PAGE_BUTTONS
= 0x01000000,
283 /** Allows multiple properties to be selected by user (by pressing SHIFT
284 when clicking on a property, or by dragging with left mouse button
287 You can get array of selected properties with
288 wxPropertyGridInterface::GetSelectedProperties(). In multiple selection
289 mode wxPropertyGridInterface::GetSelection() returns
290 property which has editor active (usually the first one
291 selected). Other useful member functions are ClearSelection(),
292 AddToSelection() and RemoveFromSelection().
294 wxPG_EX_MULTIPLE_SELECTION
= 0x02000000,
297 This enables top-level window tracking which allows wxPropertyGrid to
298 notify the application of last-minute property value changes by user.
300 This style is not enabled by default because it may cause crashes when
301 wxPropertyGrid is used in with wxAUI or similar system.
303 @remarks If you are not in fact using any system that may change
304 wxPropertyGrid's top-level parent window on its own, then you
305 are recommended to enable this style.
307 wxPG_EX_ENABLE_TLP_TRACKING
= 0x04000000,
309 /** Don't show divider above toolbar, on Windows.
311 wxPG_EX_NO_TOOLBAR_DIVIDER
= 0x08000000,
313 /** Show a separator below the toolbar.
315 wxPG_EX_TOOLBAR_SEPARATOR
= 0x10000000
319 #if wxPG_COMPATIBILITY_1_4
320 #define wxPG_EX_DISABLE_TLP_TRACKING 0x00000000
323 /** Combines various styles.
325 #define wxPG_DEFAULT_STYLE (0)
327 /** Combines various styles.
329 #define wxPGMAN_DEFAULT_STYLE (0)
334 // -----------------------------------------------------------------------
337 // Ids for sub-controls
338 // NB: It should not matter what these are.
339 #define wxPG_SUBID1 2
340 #define wxPG_SUBID2 3
341 #define wxPG_SUBID_TEMP1 4
343 // -----------------------------------------------------------------------
345 /** @class wxPGCommonValue
347 wxPropertyGrid stores information about common values in these
350 NB: Common value feature is not complete, and thus not mentioned in
353 class WXDLLIMPEXP_PROPGRID wxPGCommonValue
357 wxPGCommonValue( const wxString
& label
, wxPGCellRenderer
* renderer
)
360 m_renderer
= renderer
;
363 virtual ~wxPGCommonValue()
365 m_renderer
->DecRef();
368 virtual wxString
GetEditableText() const { return m_label
; }
369 const wxString
& GetLabel() const { return m_label
; }
370 wxPGCellRenderer
* GetRenderer() const { return m_renderer
; }
374 wxPGCellRenderer
* m_renderer
;
377 // -----------------------------------------------------------------------
379 /** @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
383 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
386 /** Prevents user from leaving property unless value is valid. If this
387 behavior flag is not used, then value change is instead cancelled.
389 wxPG_VFB_STAY_IN_PROPERTY
= 0x01,
391 /** Calls wxBell() on validation failure.
393 wxPG_VFB_BEEP
= 0x02,
395 /** Cell with invalid value will be marked (with red colour).
397 wxPG_VFB_MARK_CELL
= 0x04,
400 Display a text message explaining the situation.
402 To customize the way the message is displayed, you need to
403 reimplement wxPropertyGrid::DoShowPropertyError() in a
404 derived class. Default behavior is to display the text on
405 the top-level frame's status bar, if present, and otherwise
408 wxPG_VFB_SHOW_MESSAGE
= 0x08,
411 Similar to wxPG_VFB_SHOW_MESSAGE, except always displays the
412 message using wxMessageBox.
414 wxPG_VFB_SHOW_MESSAGEBOX
= 0x10,
417 Similar to wxPG_VFB_SHOW_MESSAGE, except always displays the
418 message on the status bar (when present - you can reimplement
419 wxPropertyGrid::GetStatusBar() in a derived class to specify
422 wxPG_VFB_SHOW_MESSAGE_ON_STATUSBAR
= 0x20,
425 wxPG_VFB_DEFAULT
= wxPG_VFB_MARK_CELL
|
426 wxPG_VFB_SHOW_MESSAGEBOX
,
428 /** Only used internally. */
429 wxPG_VFB_UNDEFINED
= 0x80
436 // Having this as define instead of wxByte typedef makes things easier for
437 // wxPython bindings (ignoring and redefining it in SWIG interface file
438 // seemed rather tricky)
439 #define wxPGVFBFlags unsigned char
444 Used to convey validation information to and from functions that
445 actually perform validation. Mostly used in custom property
448 class WXDLLIMPEXP_PROPGRID wxPGValidationInfo
450 friend class wxPropertyGrid
;
454 m_failureBehavior
= 0;
458 ~wxPGValidationInfo()
463 @return Returns failure behavior which is a combination of
464 @ref propgrid_vfbflags.
466 wxPGVFBFlags
GetFailureBehavior() const
467 { return m_failureBehavior
; }
470 Returns current failure message.
472 const wxString
& GetFailureMessage() const
473 { return m_failureMessage
; }
476 Returns reference to pending value.
478 wxVariant
& GetValue()
484 /** Set validation failure behavior
486 @param failureBehavior
487 Mixture of @ref propgrid_vfbflags.
489 void SetFailureBehavior(wxPGVFBFlags failureBehavior
)
490 { m_failureBehavior
= failureBehavior
; }
493 Set current failure message.
495 void SetFailureMessage(const wxString
& message
)
496 { m_failureMessage
= message
; }
499 /** Value to be validated.
503 /** Message displayed on validation failure.
505 wxString m_failureMessage
;
507 /** Validation failure behavior. Use wxPG_VFB_XXX flags.
509 wxPGVFBFlags m_failureBehavior
;
511 // True when validation is currently failing.
515 // -----------------------------------------------------------------------
517 /** @section propgrid_pgactions wxPropertyGrid Action Identifiers
519 These are used with wxPropertyGrid::AddActionTrigger() and
520 wxPropertyGrid::ClearActionTriggers().
524 enum wxPG_KEYBOARD_ACTIONS
526 wxPG_ACTION_INVALID
= 0,
528 /** Select the next property. */
529 wxPG_ACTION_NEXT_PROPERTY
,
531 /** Select the previous property. */
532 wxPG_ACTION_PREV_PROPERTY
,
534 /** Expand the selected property, if it has child items. */
535 wxPG_ACTION_EXPAND_PROPERTY
,
537 /** Collapse the selected property, if it has child items. */
538 wxPG_ACTION_COLLAPSE_PROPERTY
,
540 /** Cancel and undo any editing done in the currently active property
543 wxPG_ACTION_CANCEL_EDIT
,
545 /** Move focus to the editor control of the currently selected
550 /** Causes editor's button (if any) to be pressed. */
551 wxPG_ACTION_PRESS_BUTTON
,
559 // -----------------------------------------------------------------------
562 // wxPropertyGrid::DoSelectProperty flags (selFlags)
564 // Focuses to created editor
565 #define wxPG_SEL_FOCUS 0x0001
566 // Forces deletion and recreation of editor
567 #define wxPG_SEL_FORCE 0x0002
568 // For example, doesn't cause EnsureVisible
569 #define wxPG_SEL_NONVISIBLE 0x0004
570 // Do not validate editor's value before selecting
571 #define wxPG_SEL_NOVALIDATE 0x0008
572 // Property being deselected is about to be deleted
573 #define wxPG_SEL_DELETING 0x0010
574 // Property's values was set to unspecified by the user
575 #define wxPG_SEL_SETUNSPEC 0x0020
576 // Property's event handler changed the value
577 #define wxPG_SEL_DIALOGVAL 0x0040
578 // Set to disable sending of wxEVT_PG_SELECTED event
579 #define wxPG_SEL_DONT_SEND_EVENT 0x0080
580 // Don't make any graphics updates
581 #define wxPG_SEL_NO_REFRESH 0x0100
583 // -----------------------------------------------------------------------
585 // DoSetSplitterPosition() flags
587 enum wxPG_SET_SPLITTER_POSITION_SPLITTER_FLAGS
589 wxPG_SPLITTER_REFRESH
= 0x0001,
590 wxPG_SPLITTER_ALL_PAGES
= 0x0002,
591 wxPG_SPLITTER_FROM_EVENT
= 0x0004,
592 wxPG_SPLITTER_FROM_AUTO_CENTER
= 0x0008
596 // -----------------------------------------------------------------------
599 #define wxPG_FL_INITIALIZED 0x0001
600 // Set when creating editor controls if it was clicked on.
601 #define wxPG_FL_ACTIVATION_BY_CLICK 0x0002
602 #define wxPG_FL_DONT_CENTER_SPLITTER 0x0004
603 #define wxPG_FL_FOCUSED 0x0008
604 #define wxPG_FL_MOUSE_CAPTURED 0x0010
605 #define wxPG_FL_MOUSE_INSIDE 0x0020
606 #define wxPG_FL_VALUE_MODIFIED 0x0040
607 // don't clear background of m_wndEditor
608 #define wxPG_FL_PRIMARY_FILLS_ENTIRE 0x0080
609 // currently active editor uses custom image
610 #define wxPG_FL_CUR_USES_CUSTOM_IMAGE 0x0100
611 // cell colours override selection colours for selected cell
612 #define wxPG_FL_CELL_OVERRIDES_SEL 0x0200
613 #define wxPG_FL_SCROLLED 0x0400
614 // set when all added/inserted properties get hideable flag
615 #define wxPG_FL_ADDING_HIDEABLES 0x0800
616 // Disables showing help strings on statusbar.
617 #define wxPG_FL_NOSTATUSBARHELP 0x1000
618 // Marks that we created the state, so we have to destroy it too.
619 #define wxPG_FL_CREATEDSTATE 0x2000
620 // Set if scrollbar's existence was detected in last onresize.
621 #define wxPG_FL_SCROLLBAR_DETECTED 0x4000
622 // Set if wxPGMan requires redrawing of description text box.
623 #define wxPG_FL_DESC_REFRESH_REQUIRED 0x8000
624 // Set if contained in wxPropertyGridManager
625 #define wxPG_FL_IN_MANAGER 0x00020000
626 // Set after wxPropertyGrid is shown in its initial good size
627 #define wxPG_FL_GOOD_SIZE_SET 0x00040000
628 // Set when in SelectProperty.
629 #define wxPG_FL_IN_SELECT_PROPERTY 0x00100000
630 // Set when help string is shown in status bar
631 #define wxPG_FL_STRING_IN_STATUSBAR 0x00200000
632 // Auto sort is enabled (for categorized mode)
633 #define wxPG_FL_CATMODE_AUTO_SORT 0x01000000
634 // Set after page has been inserted to manager
635 #define wxPG_MAN_FL_PAGE_INSERTED 0x02000000
636 // Active editor control is abnormally large
637 #define wxPG_FL_ABNORMAL_EDITOR 0x04000000
638 // Recursion guard for HandleCustomEditorEvent
639 #define wxPG_FL_IN_HANDLECUSTOMEDITOREVENT 0x08000000
640 #define wxPG_FL_VALUE_CHANGE_IN_EVENT 0x10000000
641 // Editor control width should not change on resize
642 #define wxPG_FL_FIXED_WIDTH_EDITOR 0x20000000
643 // Width of panel can be different than width of grid
644 #define wxPG_FL_HAS_VIRTUAL_WIDTH 0x40000000
645 // Prevents RecalculateVirtualSize re-entrancy
646 #define wxPG_FL_RECALCULATING_VIRTUAL_SIZE 0x80000000
648 #if !defined(__wxPG_SOURCE_FILE__)
649 // Reduce compile time, but still include in user app
650 #include "wx/propgrid/props.h"
653 // -----------------------------------------------------------------------
655 /** @class wxPropertyGrid
657 wxPropertyGrid is a specialized grid for editing properties
658 such as strings, numbers, flagsets, fonts, and colours. wxPropertySheet
659 used to do the very same thing, but it hasn't been updated for a while
660 and it is currently deprecated.
662 Please note that most member functions are inherited and as such not
663 documented on this page. This means you will probably also want to read
664 wxPropertyGridInterface class reference.
666 See also @ref overview_propgrid.
668 @section propgrid_window_styles_ Window Styles
670 See @ref propgrid_window_styles.
672 @section propgrid_event_handling Event Handling
674 To process input from a propertygrid control, use these event handler
675 macros to direct input to member functions that take a wxPropertyGridEvent
678 @beginEventTable{wxPropertyGridEvent}
679 @event{EVT_PG_SELECTED (id, func)}
680 Respond to wxEVT_PG_SELECTED event, generated when a property selection
681 has been changed, either by user action or by indirect program
682 function. For instance, collapsing a parent property programmatically
683 causes any selected child property to become unselected, and may
684 therefore cause this event to be generated.
685 @event{EVT_PG_CHANGING(id, func)}
686 Respond to wxEVT_PG_CHANGING event, generated when property value
687 is about to be changed by user. Use wxPropertyGridEvent::GetValue()
688 to take a peek at the pending value, and wxPropertyGridEvent::Veto()
689 to prevent change from taking place, if necessary.
690 @event{EVT_PG_HIGHLIGHTED(id, func)}
691 Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
692 moves over a property. Event's property is NULL if hovered area does
693 not belong to any property.
694 @event{EVT_PG_RIGHT_CLICK(id, func)}
695 Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
696 clicked on with right mouse button.
697 @event{EVT_PG_DOUBLE_CLICK(id, func)}
698 Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
699 double-clicked onwith left mouse button.
700 @event{EVT_PG_ITEM_COLLAPSED(id, func)}
701 Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
702 a property or category..
703 @event{EVT_PG_ITEM_EXPANDED(id, func)}
704 Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
705 a property or category..
706 @event{EVT_PG_LABEL_EDIT_BEGIN(id, func)}
707 Respond to wxEVT_PG_LABEL_EDIT_BEGIN event, generated when is about to
708 begin editing a property label. You can veto this event to prevent the
710 @event{EVT_PG_LABEL_EDIT_ENDING(id, func)}
711 Respond to wxEVT_PG_LABEL_EDIT_ENDING event, generated when is about to
712 end editing of a property label. You can veto this event to prevent the
714 @event{EVT_PG_COL_BEGIN_DRAG(id, func)}
715 Respond to wxEVT_PG_COL_BEGIN_DRAG event, generated when user
716 starts resizing a column - can be vetoed.
717 @event{EVT_PG_COL_DRAGGING,(id, func)}
718 Respond to wxEVT_PG_COL_DRAGGING, event, generated when a
719 column resize by user is in progress. This event is also generated
720 when user double-clicks the splitter in order to recenter
722 @event{EVT_PG_COL_END_DRAG(id, func)}
723 Respond to wxEVT_PG_COL_END_DRAG event, generated after column
724 resize by user has finished.
729 - Use Freeze() and Thaw() respectively to disable and enable drawing. This
730 will also delay sorting etc. miscellaneous calculations to the last
736 class WXDLLIMPEXP_PROPGRID wxPropertyGrid
: public wxControl
,
737 public wxScrollHelper
,
738 public wxPropertyGridInterface
740 friend class wxPropertyGridEvent
;
741 friend class wxPropertyGridPageState
;
742 friend class wxPropertyGridInterface
;
743 friend class wxPropertyGridManager
;
744 friend class wxPGHeaderCtrl
;
746 DECLARE_DYNAMIC_CLASS(wxPropertyGrid
)
751 Two step constructor.
753 Call Create when this constructor is called to build up the
759 /** The default constructor. The styles to be used are styles valid for
762 @see @link wndflags Additional Window Styles @endlink
764 wxPropertyGrid( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
765 const wxPoint
& pos
= wxDefaultPosition
,
766 const wxSize
& size
= wxDefaultSize
,
767 long style
= wxPG_DEFAULT_STYLE
,
768 const wxString
& name
= wxPropertyGridNameStr
);
771 virtual ~wxPropertyGrid();
773 /** Adds given key combination to trigger given action.
775 Here is a sample code to make Enter key press move focus to
779 propGrid->AddActionTrigger(wxPG_ACTION_NEXT_PROPERTY,
781 propGrid->DedicateKey(WXK_RETURN);
785 Which action to trigger. See @ref propgrid_keyboard_actions.
787 Which keycode triggers the action.
789 Which key event modifiers, in addition to keycode, are needed to
792 void AddActionTrigger( int action
, int keycode
, int modifiers
= 0 );
795 Dedicates a specific keycode to wxPropertyGrid. This means that such
796 key presses will not be redirected to editor controls.
798 Using this function allows, for example, navigation between
799 properties using arrow keys even when the focus is in the editor
802 void DedicateKey( int keycode
)
804 m_dedicatedKeys
.push_back(keycode
);
808 This static function enables or disables automatic use of
809 wxGetTranslation for following strings: wxEnumProperty list labels,
810 wxFlagsProperty sub-property labels.
814 static void AutoGetTranslation( bool enable
);
817 Changes value of a property, as if from an editor.
819 Use this instead of SetPropertyValue() if you need the value to run
820 through validation process, and also send the property change event.
823 Returns true if value was successfully changed.
825 bool ChangePropertyValue( wxPGPropArg id
, wxVariant newValue
);
828 Centers the splitter.
830 @param enableAutoResizing
831 If @true, automatic column resizing is enabled (only applicapple
832 if window style wxPG_SPLITTER_AUTO_CENTER is used).
834 void CenterSplitter( bool enableAutoResizing
= false );
836 /** Deletes all properties.
838 virtual void Clear();
840 /** Clears action triggers for given action.
842 Which action to trigger. See @link pgactions List of list of
843 wxPropertyGrid actions@endlink.
845 void ClearActionTriggers( int action
);
847 /** Forces updating the value of property from the editor control.
849 Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
850 ProcessEvent, meaning your event handlers will be called immediately.
853 Returns true if anything was changed.
855 virtual bool CommitChangesFromEditor( wxUint32 flags
= 0 );
860 Whenever the control is created without any parameters, use Create to
861 actually create it. Don't access the control's public methods before
862 this is called @see @link wndflags Additional Window Styles@endlink
864 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
865 const wxPoint
& pos
= wxDefaultPosition
,
866 const wxSize
& size
= wxDefaultSize
,
867 long style
= wxPG_DEFAULT_STYLE
,
868 const wxString
& name
= wxPropertyGridNameStr
);
871 Call when editor widget's contents is modified.
873 For example, this is called when changes text in wxTextCtrl (used in
874 wxStringProperty and wxIntProperty).
877 This function should only be called by custom properties.
879 @see wxPGProperty::OnEvent()
881 void EditorsValueWasModified() { m_iFlags
|= wxPG_FL_VALUE_MODIFIED
; }
883 /** Reverse of EditorsValueWasModified().
886 This function should only be called by custom properties.
888 void EditorsValueWasNotModified()
890 m_iFlags
&= ~(wxPG_FL_VALUE_MODIFIED
);
894 Enables or disables (shows/hides) categories according to parameter
897 bool EnableCategories( bool enable
);
899 /** Scrolls and/or expands items to ensure that the given item is visible.
900 Returns true if something was actually done.
902 bool EnsureVisible( wxPGPropArg id
);
905 Reduces column sizes to minimum possible that contents are still
906 visibly (naturally some margin space will be applied as well).
909 Minimum size for the grid to still display everything.
912 Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
914 This function only works properly if grid size prior to call was already
917 Note that you can also get calculated column widths by calling
918 GetState->GetColumnWidth() immediately after this function returns.
922 wxSize sz
= m_pState
->DoFitColumns();
927 Returns wxWindow that the properties are painted on, and which should
928 be used as the parent for editor controls.
935 /** Returns current category caption background colour. */
936 wxColour
GetCaptionBackgroundColour() const { return m_colCapBack
; }
938 wxFont
& GetCaptionFont() { return m_captionFont
; }
940 const wxFont
& GetCaptionFont() const { return m_captionFont
; }
942 /** Returns current category caption text colour. */
943 wxColour
GetCaptionForegroundColour() const { return m_colCapFore
; }
945 /** Returns current cell background colour. */
946 wxColour
GetCellBackgroundColour() const { return m_colPropBack
; }
948 /** Returns current cell text colour when disabled. */
949 wxColour
GetCellDisabledTextColour() const { return m_colDisPropFore
; }
951 /** Returns current cell text colour. */
952 wxColour
GetCellTextColour() const { return m_colPropFore
; }
955 Returns number of columns currently on grid.
957 unsigned int GetColumnCount() const
959 return (unsigned int) m_pState
->m_colWidths
.size();
962 /** Returns colour of empty space below properties. */
963 wxColour
GetEmptySpaceColour() const { return m_colEmptySpace
; }
965 /** Returns height of highest characters of used font. */
966 int GetFontHeight() const { return m_fontHeight
; }
968 /** Returns pointer to itself. Dummy function that enables same kind
969 of code to use wxPropertyGrid and wxPropertyGridManager.
971 wxPropertyGrid
* GetGrid() { return this; }
973 /** Returns rectangle of custom paint image.
975 wxRect
GetImageRect( wxPGProperty
* p
, int item
) const;
977 /** Returns size of the custom paint image in front of property.
978 If no argument is given, returns preferred size.
980 wxSize
GetImageSize( wxPGProperty
* p
= NULL
, int item
= -1 ) const;
983 /** Returns last item which could be iterated using given flags.
985 See @ref propgrid_iterator_flags.
987 wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
)
989 return m_pState
->GetLastItem(flags
);
992 const wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
) const
994 return m_pState
->GetLastItem(flags
);
998 /** Returns colour of lines between cells. */
999 wxColour
GetLineColour() const { return m_colLine
; }
1001 /** Returns background colour of margin. */
1002 wxColour
GetMarginColour() const { return m_colMargin
; }
1004 /** Returns margin width. */
1005 int GetMarginWidth() const { return m_marginWidth
; }
1008 Returns most up-to-date value of selected property. This will return
1009 value different from GetSelectedProperty()->GetValue() only when text
1010 editor is activate and string edited by user represents valid,
1011 uncommitted property value.
1013 wxVariant
GetUncommittedPropertyValue();
1015 /** Returns "root property". It does not have name, etc. and it is not
1016 visible. It is only useful for accessing its children.
1018 wxPGProperty
* GetRoot() const { return m_pState
->m_properties
; }
1020 /** Returns height of a single grid row (in pixels). */
1021 int GetRowHeight() const { return m_lineHeight
; }
1023 /** Returns currently selected property. */
1024 wxPGProperty
* GetSelectedProperty() const { return GetSelection(); }
1026 /** Returns current selection background colour. */
1027 wxColour
GetSelectionBackgroundColour() const { return m_colSelBack
; }
1029 /** Returns current selection text colour. */
1030 wxColour
GetSelectionForegroundColour() const { return m_colSelFore
; }
1033 Returns current splitter x position.
1035 int GetSplitterPosition( unsigned int splitterIndex
= 0 ) const
1037 return m_pState
->DoGetSplitterPosition(splitterIndex
);
1040 /** Returns wxTextCtrl active in currently selected property, if any. Takes
1041 into account wxOwnerDrawnComboBox.
1043 wxTextCtrl
* GetEditorTextCtrl() const;
1045 wxPGValidationInfo
& GetValidationInfo()
1047 return m_validationInfo
;
1050 /** Returns current vertical spacing. */
1051 int GetVerticalSpacing() const { return (int)m_vspacing
; }
1054 Returns @true if a property editor control has focus.
1056 bool IsEditorFocused() const;
1058 /** Returns true if editor's value was marked modified.
1060 bool IsEditorsValueModified() const
1061 { return ( m_iFlags
& wxPG_FL_VALUE_MODIFIED
) ? true : false; }
1064 Returns information about arbitrary position in the grid.
1067 Coordinates in the virtual grid space. You may need to use
1068 wxScrolled<T>::CalcScrolledPosition() for translating
1069 wxPropertyGrid client coordinates into something this member
1072 wxPropertyGridHitTestResult
HitTest( const wxPoint
& pt
) const;
1074 /** Returns true if any property has been modified by the user. */
1075 bool IsAnyModified() const { return (m_pState
->m_anyModified
>0); }
1078 Returns true if updating is frozen (ie Freeze() called but not yet
1081 bool IsFrozen() const { return (m_frozen
>0)?true:false; }
1084 It is recommended that you call this function any time your code causes
1085 wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle()
1086 handler should be able to detect most changes, but it is not perfect.
1089 New top-level parent that is about to be set. Old top-level parent
1090 window should still exist as the current one.
1092 @remarks This function is automatically called from wxPropertyGrid::
1093 Reparent() and wxPropertyGridManager::Reparent(). You only
1094 need to use it if you reparent wxPropertyGrid indirectly.
1096 void OnTLPChanging( wxWindow
* newTLP
);
1098 /** Redraws given property.
1100 virtual void RefreshProperty( wxPGProperty
* p
);
1102 /** Registers a new editor class.
1104 Pointer to the editor class instance that should be used.
1106 static wxPGEditor
* RegisterEditorClass( wxPGEditor
* editor
,
1107 bool noDefCheck
= false )
1109 return DoRegisterEditorClass(editor
, wxEmptyString
, noDefCheck
);
1112 static wxPGEditor
* DoRegisterEditorClass( wxPGEditor
* editorClass
,
1113 const wxString
& editorName
,
1114 bool noDefCheck
= false );
1116 /** Resets all colours to the original system values.
1118 void ResetColours();
1121 Resets column sizes and splitter positions, based on proportions.
1123 @param enableAutoResizing
1124 If @true, automatic column resizing is enabled (only applicapple
1125 if window style wxPG_SPLITTER_AUTO_CENTER is used).
1127 @see wxPropertyGridInterface::SetColumnProportion()
1129 void ResetColumnSizes( bool enableAutoResizing
= false );
1133 Editor widget is automatically created, but not focused unless focus is
1140 True if selection finished successfully. Usually only fails if
1141 current value in editor is not valid.
1143 @remarks In wxPropertyGrid 1.4, this member function used to generate
1144 wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer
1147 @remarks This clears any previous selection.
1149 bool SelectProperty( wxPGPropArg id
, bool focus
= false );
1152 Set entire new selection from given list of properties.
1154 void SetSelection( const wxArrayPGProperty
& newSelection
)
1156 DoSetSelection( newSelection
, wxPG_SEL_DONT_SEND_EVENT
);
1160 Adds given property into selection. If wxPG_EX_MULTIPLE_SELECTION
1161 extra style is not used, then this has same effect as
1162 calling SelectProperty().
1164 @remarks Multiple selection is not supported for categories. This
1165 means that if you have properties selected, you cannot
1166 add category to selection, and also if you have category
1167 selected, you cannot add other properties to selection.
1168 This member function will fail silently in these cases,
1169 even returning true.
1171 bool AddToSelection( wxPGPropArg id
)
1173 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
1174 return DoAddToSelection(p
, wxPG_SEL_DONT_SEND_EVENT
);
1178 Removes given property from selection. If property is not selected,
1179 an assertion failure will occur.
1181 bool RemoveFromSelection( wxPGPropArg id
)
1183 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
1184 return DoRemoveFromSelection(p
, wxPG_SEL_DONT_SEND_EVENT
);
1188 Makes given column editable by user.
1191 Using @false here will disable column from being editable.
1193 void MakeColumnEditable( unsigned int column
, bool editable
= true );
1196 Creates label editor wxTextCtrl for given column, for property
1197 that is currently selected. When multiple selection is
1198 enabled, this applies to whatever property GetSelection()
1202 Which column's label to edit. Note that you should not
1203 use value 1, which is reserved for property value
1206 @see EndLabelEdit(), MakeColumnEditable()
1208 void BeginLabelEdit( unsigned int column
= 0 )
1210 DoBeginLabelEdit(column
, wxPG_SEL_DONT_SEND_EVENT
);
1214 Destroys label editor wxTextCtrl, if any.
1217 Use @true (default) to store edited label text in
1220 @see BeginLabelEdit(), MakeColumnEditable()
1222 void EndLabelEdit( bool commit
= true )
1224 DoEndLabelEdit(commit
, wxPG_SEL_DONT_SEND_EVENT
);
1228 Returns currently active label editor, NULL if none.
1230 wxTextCtrl
* GetLabelEditor() const
1232 return m_labelEditor
;
1235 /** Sets category caption background colour. */
1236 void SetCaptionBackgroundColour(const wxColour
& col
);
1238 /** Sets category caption text colour. */
1239 void SetCaptionTextColour(const wxColour
& col
);
1241 /** Sets default cell background colour - applies to property cells.
1242 Note that appearance of editor widgets may not be affected.
1244 void SetCellBackgroundColour(const wxColour
& col
);
1246 /** Sets cell text colour for disabled properties.
1248 void SetCellDisabledTextColour(const wxColour
& col
);
1250 /** Sets default cell text colour - applies to property name and value text.
1251 Note that appearance of editor widgets may not be affected.
1253 void SetCellTextColour(const wxColour
& col
);
1255 /** Set number of columns (2 or more).
1257 void SetColumnCount( int colCount
)
1259 m_pState
->SetColumnCount(colCount
);
1264 Sets the 'current' category - Append will add non-category properties
1267 void SetCurrentCategory( wxPGPropArg id
)
1269 wxPG_PROP_ARG_CALL_PROLOG()
1270 wxPropertyCategory
* pc
= wxDynamicCast(p
, wxPropertyCategory
);
1272 m_pState
->m_currentCategory
= pc
;
1275 /** Sets colour of empty space below properties. */
1276 void SetEmptySpaceColour(const wxColour
& col
);
1278 /** Sets colour of lines between cells. */
1279 void SetLineColour(const wxColour
& col
);
1281 /** Sets background colour of margin. */
1282 void SetMarginColour(const wxColour
& col
);
1285 Sets selection background colour - applies to selected property name
1288 void SetSelectionBackgroundColour(const wxColour
& col
);
1291 Sets selection foreground colour - applies to selected property name
1294 void SetSelectionTextColour(const wxColour
& col
);
1296 /** Sets x coordinate of the splitter.
1298 Splitter position cannot exceed grid size, and therefore setting it
1299 during form creation may fail as initial grid size is often smaller
1300 than desired splitter position, especially when sizers are being used.
1302 void SetSplitterPosition( int newXPos
, int col
= 0 )
1304 DoSetSplitterPosition(newXPos
, col
, wxPG_SPLITTER_REFRESH
);
1308 Sets the property sorting function.
1311 The sorting function to be used. It should return a value greater
1312 than 0 if position of p1 is after p2. So, for instance, when
1313 comparing property names, you can use following implementation:
1316 int MyPropertySortFunction(wxPropertyGrid* propGrid,
1320 return p1->GetBaseName().compare( p2->GetBaseName() );
1325 Default property sort function sorts properties by their labels
1326 (case-insensitively).
1328 @see GetSortFunction, wxPropertyGridInterface::Sort,
1329 wxPropertyGridInterface::SortChildren
1331 void SetSortFunction( wxPGSortCallback sortFunction
)
1333 m_sortFunction
= sortFunction
;
1337 Returns the property sort function (default is @NULL).
1339 @see SetSortFunction
1341 wxPGSortCallback
GetSortFunction() const
1343 return m_sortFunction
;
1347 Sets appearance of value cells representing an unspecified property
1348 value. Default appearance is blank.
1350 @remarks If you set the unspecified value to have any
1351 textual representation, then that will override
1352 "InlineHelp" attribute.
1354 @see wxPGProperty::SetValueToUnspecified(),
1355 wxPGProperty::IsValueUnspecified()
1357 void SetUnspecifiedValueAppearance( const wxPGCell
& cell
)
1359 m_unspecifiedAppearance
= m_propertyDefaultCell
;
1360 m_unspecifiedAppearance
.MergeFrom(cell
);
1364 Returns current appearance of unspecified value cells.
1366 @see SetUnspecifiedValueAppearance()
1368 const wxPGCell
& GetUnspecifiedValueAppearance() const
1370 return m_unspecifiedAppearance
;
1374 Returns (visual) text representation of the unspecified
1377 @param argFlags For internal use only.
1379 wxString
GetUnspecifiedValueText( int argFlags
= 0 ) const;
1381 /** Set virtual width for this particular page. Width -1 indicates that the
1382 virtual width should be disabled. */
1383 void SetVirtualWidth( int width
);
1386 Moves splitter as left as possible, while still allowing all
1387 labels to be shown in full.
1389 @param privateChildrenToo
1390 If @false, will still allow private children to be cropped.
1392 void SetSplitterLeft( bool privateChildrenToo
= false )
1394 m_pState
->SetSplitterLeft(privateChildrenToo
);
1397 /** Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
1398 height. Value of 2 should be default on most platforms.
1400 void SetVerticalSpacing( int vspacing
)
1402 m_vspacing
= (unsigned char)vspacing
;
1403 CalculateFontAndBitmapStuff( vspacing
);
1404 if ( !m_pState
->m_itemsAdded
) Refresh();
1407 /** Shows an brief error message that is related to a property. */
1408 void ShowPropertyError( wxPGPropArg id
, const wxString
& msg
)
1410 wxPG_PROP_ARG_CALL_PROLOG()
1411 DoShowPropertyError(p
, msg
);
1414 /////////////////////////////////////////////////////////////////
1416 // Following methods do not need to be (currently) documented
1418 /////////////////////////////////////////////////////////////////
1420 bool HasVirtualWidth() const
1421 { return (m_iFlags
& wxPG_FL_HAS_VIRTUAL_WIDTH
) ? true : false; }
1423 const wxPGCommonValue
* GetCommonValue( unsigned int i
) const
1425 return (wxPGCommonValue
*) m_commonValues
[i
];
1428 /** Returns number of common values.
1430 unsigned int GetCommonValueCount() const
1432 return (unsigned int) m_commonValues
.size();
1435 /** Returns label of given common value.
1437 wxString
GetCommonValueLabel( unsigned int i
) const
1439 wxASSERT( GetCommonValue(i
) );
1440 return GetCommonValue(i
)->GetLabel();
1444 Returns index of common value that will truly change value to
1447 int GetUnspecifiedCommonValue() const { return m_cvUnspecified
; }
1449 /** Set index of common value that will truly change value to unspecified.
1450 Using -1 will set none to have such effect.
1453 void SetUnspecifiedCommonValue( int index
) { m_cvUnspecified
= index
; }
1456 Shortcut for creating dialog-caller button. Used, for example, by
1459 This should only be called by properties.
1461 wxWindow
* GenerateEditorButton( const wxPoint
& pos
, const wxSize
& sz
);
1463 /** Fixes position of wxTextCtrl-like control (wxSpinCtrl usually
1464 fits as one). Call after control has been created (but before
1467 void FixPosForTextCtrl( wxWindow
* ctrl
,
1468 unsigned int forColumn
= 1,
1469 const wxPoint
& offset
= wxPoint(0, 0) );
1471 /** Shortcut for creating text editor widget.
1473 Same as pos given for CreateEditor.
1475 Same as sz given for CreateEditor.
1477 Initial text for wxTextCtrl.
1479 If right-side control, such as button, also created, then create it
1480 first and pass it as this parameter.
1482 Extra style flags to pass for wxTextCtrl.
1484 Note that this should generally be called only by new classes derived
1487 wxWindow
* GenerateEditorTextCtrl( const wxPoint
& pos
,
1489 const wxString
& value
,
1490 wxWindow
* secondary
,
1493 unsigned int forColumn
= 1 );
1495 /* Generates both textctrl and button.
1497 wxWindow
* GenerateEditorTextCtrlAndButton( const wxPoint
& pos
,
1498 const wxSize
& sz
, wxWindow
** psecondary
, int limited_editing
,
1499 wxPGProperty
* property
);
1501 /** Generates position for a widget editor dialog box.
1503 Property for which dialog is positioned.
1505 Known or over-approximated size of the dialog.
1507 Position for dialog.
1509 wxPoint
GetGoodEditorDialogPosition( wxPGProperty
* p
,
1512 // Converts escape sequences in src_str to newlines,
1513 // tabs, etc. and copies result to dst_str.
1514 static wxString
& ExpandEscapeSequences( wxString
& dst_str
,
1515 wxString
& src_str
);
1517 // Converts newlines, tabs, etc. in src_str to escape
1518 // sequences, and copies result to dst_str.
1519 static wxString
& CreateEscapeSequences( wxString
& dst_str
,
1520 wxString
& src_str
);
1523 Returns rectangle that fully contains properties between and including
1524 p1 and p2. Rectangle is in virtual scrolled window coordinates.
1526 wxRect
GetPropertyRect( const wxPGProperty
* p1
,
1527 const wxPGProperty
* p2
) const;
1529 /** Returns pointer to current active primary editor control (NULL if none).
1531 wxWindow
* GetEditorControl() const;
1533 wxWindow
* GetPrimaryEditor() const
1535 return GetEditorControl();
1539 Returns pointer to current active secondary editor control (NULL if
1542 wxWindow
* GetEditorControlSecondary() const
1544 return m_wndEditor2
;
1548 Refreshes any active editor control.
1550 void RefreshEditor();
1552 // Events from editor controls are forward to this function
1553 bool HandleCustomEditorEvent( wxEvent
&event
);
1555 // Mostly useful for page switching.
1556 void SwitchState( wxPropertyGridPageState
* pNewState
);
1558 long GetInternalFlags() const { return m_iFlags
; }
1559 bool HasInternalFlag( long flag
) const
1560 { return (m_iFlags
& flag
) ? true : false; }
1561 void SetInternalFlag( long flag
) { m_iFlags
|= flag
; }
1562 void ClearInternalFlag( long flag
) { m_iFlags
&= ~(flag
); }
1563 void IncFrozen() { m_frozen
++; }
1564 void DecFrozen() { m_frozen
--; }
1566 void OnComboItemPaint( const wxPGComboBox
* pCb
,
1572 /** Standardized double-to-string conversion.
1574 static const wxString
& DoubleToString( wxString
& target
,
1578 wxString
* precTemplate
= NULL
);
1581 Call this from wxPGProperty::OnEvent() to cause property value to be
1582 changed after the function returns (with true as return value).
1583 ValueChangeInEvent() must be used if you wish the application to be
1584 able to use wxEVT_PG_CHANGING to potentially veto the given value.
1586 void ValueChangeInEvent( wxVariant variant
)
1588 m_changeInEventValue
= variant
;
1589 m_iFlags
|= wxPG_FL_VALUE_CHANGE_IN_EVENT
;
1593 You can use this member function, for instance, to detect in
1594 wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was
1595 already called in wxPGEditor::OnEvent(). It really only detects
1596 if was value was changed using wxPGProperty::SetValueInEvent(), which
1597 is usually used when a 'picker' dialog is displayed. If value was
1598 written by "normal means" in wxPGProperty::StringToValue() or
1599 IntToValue(), then this function will return false (on the other hand,
1600 wxPGProperty::OnEvent() is not even called in those cases).
1602 bool WasValueChangedInEvent() const
1604 return (m_iFlags
& wxPG_FL_VALUE_CHANGE_IN_EVENT
) ? true : false;
1607 /** Returns true if given event is from first of an array of buttons
1608 (as can be in case when wxPGMultiButton is used).
1610 bool IsMainButtonEvent( const wxEvent
& event
)
1612 return (event
.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED
)
1613 && (m_wndSecId
== event
.GetId());
1616 /** Pending value is expected to be passed in PerformValidation().
1618 virtual bool DoPropertyChanged( wxPGProperty
* p
,
1619 unsigned int selFlags
= 0 );
1621 /** Called when validation for given property fails.
1623 Value which failed in validation.
1625 Return true if user is allowed to change to another property even
1626 if current has invalid value.
1628 To add your own validation failure behavior, override
1629 wxPropertyGrid::DoOnValidationFailure().
1631 bool OnValidationFailure( wxPGProperty
* property
,
1632 wxVariant
& invalidValue
);
1634 /** Called to indicate property and editor has valid value now.
1636 void OnValidationFailureReset( wxPGProperty
* property
)
1638 if ( property
&& property
->HasFlag(wxPG_PROP_INVALID_VALUE
) )
1640 DoOnValidationFailureReset(property
);
1641 property
->ClearFlag(wxPG_PROP_INVALID_VALUE
);
1643 m_validationInfo
.m_failureMessage
.clear();
1647 Override in derived class to display error messages in custom manner
1648 (these message usually only result from validation failure).
1650 @remarks If you implement this, then you also need to implement
1651 DoHidePropertyError() - possibly to do nothing, if error
1652 does not need hiding (e.g. it was logged or shown in a
1655 @see DoHidePropertyError()
1657 virtual void DoShowPropertyError( wxPGProperty
* property
,
1658 const wxString
& msg
);
1661 Override in derived class to hide an error displayed by
1662 DoShowPropertyError().
1664 @see DoShowPropertyError()
1666 virtual void DoHidePropertyError( wxPGProperty
* property
);
1670 Return wxStatusBar that is used by this wxPropertyGrid. You can
1671 reimplement this member function in derived class to override
1672 the default behavior of using the top-level wxFrame's status
1675 virtual wxStatusBar
* GetStatusBar();
1678 /** Override to customize property validation failure behavior.
1680 Value which failed in validation.
1682 Return true if user is allowed to change to another property even
1683 if current has invalid value.
1685 virtual bool DoOnValidationFailure( wxPGProperty
* property
,
1686 wxVariant
& invalidValue
);
1688 /** Override to customize resetting of property validation failure status.
1690 Property is guaranteed to have flag wxPG_PROP_INVALID_VALUE set.
1692 virtual void DoOnValidationFailureReset( wxPGProperty
* property
);
1694 int GetSpacingY() const { return m_spacingy
; }
1697 Must be called in wxPGEditor::CreateControls() if primary editor window
1698 is wxTextCtrl, just before textctrl is created.
1700 Initial text value of created wxTextCtrl.
1702 void SetupTextCtrlValue( const wxString text
) { m_prevTcValue
= text
; }
1705 Unfocuses or closes editor if one was open, but does not deselect
1708 bool UnfocusEditor();
1710 virtual void SetWindowStyleFlag( long style
);
1712 void DrawItems( const wxPGProperty
* p1
, const wxPGProperty
* p2
);
1714 void DrawItem( wxPGProperty
* p
)
1719 virtual void DrawItemAndChildren( wxPGProperty
* p
);
1722 Draws item, children, and consequtive parents as long as category is
1725 void DrawItemAndValueRelated( wxPGProperty
* p
);
1730 wxPropertyGridPageState used by the grid is created here.
1732 If grid is used in wxPropertyGridManager, there is no point overriding
1733 this - instead, set custom wxPropertyGridPage classes.
1735 virtual wxPropertyGridPageState
* CreateState() const;
1737 enum PerformValidationFlags
1739 SendEvtChanging
= 0x0001,
1740 IsStandaloneValidation
= 0x0002 // Not called in response to event
1744 Runs all validation functionality (includes sending wxEVT_PG_CHANGING).
1745 Returns true if all tests passed. Implement in derived class to
1746 add additional validation behavior.
1748 virtual bool PerformValidation( wxPGProperty
* p
,
1749 wxVariant
& pendingValue
,
1750 int flags
= SendEvtChanging
);
1754 // Control font changer helper.
1755 void SetCurControlBoldFont();
1757 wxPGCell
& GetPropertyDefaultCell()
1759 return m_propertyDefaultCell
;
1762 wxPGCell
& GetCategoryDefaultCell()
1764 return m_categoryDefaultCell
;
1768 // Public methods for semi-public use
1770 bool DoSelectProperty( wxPGProperty
* p
, unsigned int flags
= 0 );
1772 // Overridden functions.
1773 virtual bool Destroy();
1774 // Returns property at given y coordinate (relative to grid's top left).
1775 wxPGProperty
* GetItemAtY( int y
) const { return DoGetItemAtY(y
); }
1777 virtual void Refresh( bool eraseBackground
= true,
1778 const wxRect
*rect
= (const wxRect
*) NULL
);
1779 virtual bool SetFont( const wxFont
& font
);
1780 virtual void Freeze();
1781 virtual void SetExtraStyle( long exStyle
);
1782 virtual void Thaw();
1783 virtual bool Reparent( wxWindowBase
*newParent
);
1786 virtual wxSize
DoGetBestSize() const;
1788 #ifndef wxPG_ICON_WIDTH
1789 wxBitmap
*m_expandbmp
, *m_collbmp
;
1792 wxCursor
*m_cursorSizeWE
;
1794 /** wxWindow pointers to editor control(s). */
1795 wxWindow
*m_wndEditor
;
1796 wxWindow
*m_wndEditor2
;
1798 #if wxPG_DOUBLE_BUFFER
1799 wxBitmap
*m_doubleBuffer
;
1802 /** Local time ms when control was created. */
1803 wxLongLong m_timeCreated
;
1805 /** wxPGProperty::OnEvent can change value by setting this. */
1806 wxVariant m_changeInEventValue
;
1808 /** Id of m_wndEditor2, or its first child, if any. */
1811 /** Extra Y spacing between the items. */
1814 /** Control client area width; updated on resize. */
1817 /** Control client area height; updated on resize. */
1820 /** Current non-client width (needed when auto-centering). */
1823 /** Non-client width (auto-centering helper). */
1826 /** Previously recorded scroll start position. */
1830 The gutter spacing in front and back of the image.
1831 This determines the amount of spacing in front of each item
1835 /** Includes separator line. */
1838 /** Gutter*2 + image width. */
1841 // y spacing for expand/collapse button.
1842 int m_buttonSpacingY
;
1844 /** Extra margin for expanded sub-group items. */
1845 int m_subgroup_extramargin
;
1848 The image width of the [+] icon.
1850 This is also calculated in the gutter
1854 #ifndef wxPG_ICON_WIDTH
1857 The image height of the [+] icon.
1859 This is calculated as minimal size and to align
1864 /** Current cursor id. */
1867 // Caption font. Same as normal font plus bold style.
1868 wxFont m_captionFont
;
1870 int m_fontHeight
; // Height of the font.
1872 /** m_splitterx when drag began. */
1873 int m_startingSplitterX
;
1876 Index to splitter currently being dragged (0=one after the first
1879 int m_draggedSplitter
;
1881 /** Changed property, calculated in PerformValidation(). */
1882 wxPGProperty
* m_chgInfo_changedProperty
;
1885 Lowest property for which editing happened, but which does not have
1888 wxPGProperty
* m_chgInfo_baseChangedProperty
;
1890 /** Changed property value, calculated in PerformValidation(). */
1891 wxVariant m_chgInfo_pendingValue
;
1893 /** Passed to SetValue. */
1894 wxVariant m_chgInfo_valueList
;
1896 /** Validation information. */
1897 wxPGValidationInfo m_validationInfo
;
1899 /** Actions and keys that trigger them. */
1900 wxPGHashMapI2I m_actionTriggers
;
1902 /** Appearance of currently active editor. */
1903 wxPGCell m_editorAppearance
;
1905 /** Appearance of a unspecified value cell. */
1906 wxPGCell m_unspecifiedAppearance
;
1908 /** List of properties to be deleted/removed in idle event handler. */
1909 wxArrayPGProperty m_deletedProperties
;
1910 wxArrayPGProperty m_removedProperties
;
1912 /** List of key codes that will not be handed over to editor controls. */
1913 // FIXME: Make this a hash set once there is template-based wxHashSet.
1914 wxVector
<int> m_dedicatedKeys
;
1920 /** Bits are used to indicate which colours are customized. */
1921 unsigned short m_coloursCustomized
;
1923 /** x - m_splitterx. */
1924 signed char m_dragOffset
;
1926 /** 0 = not dragging, 1 = drag just started, 2 = drag in progress */
1927 unsigned char m_dragStatus
;
1929 /** 0 = margin, 1 = label, 2 = value. */
1930 unsigned char m_mouseSide
;
1932 /** True when editor control is focused. */
1933 unsigned char m_editorFocused
;
1935 /** 1 if m_latsCaption is also the bottommost caption. */
1936 //unsigned char m_lastCaptionBottomnest;
1938 /** Set to 1 when graphics frozen. */
1939 unsigned char m_frozen
;
1941 unsigned char m_vspacing
;
1943 // Used to track when Alt/Ctrl+Key was consumed.
1944 unsigned char m_keyComboConsumed
;
1946 /** 1 if in DoPropertyChanged() */
1947 bool m_inDoPropertyChanged
;
1949 /** 1 if in CommitChangesFromEditor() */
1950 bool m_inCommitChangesFromEditor
;
1952 /** 1 if in DoSelectProperty() */
1953 bool m_inDoSelectProperty
;
1955 bool m_inOnValidationFailure
;
1957 wxPGVFBFlags m_permanentValidationFailureBehavior
; // Set by app
1959 // DoEditorValidate() recursion guard
1960 wxRecursionGuardFlag m_validatingEditor
;
1962 /** Internal flags - see wxPG_FL_XXX constants. */
1965 /** When drawing next time, clear this many item slots at the end. */
1966 int m_clearThisMany
;
1968 // Mouse is hovering over this column (index)
1969 unsigned int m_colHover
;
1971 // pointer to property that has mouse hovering
1972 wxPGProperty
* m_propHover
;
1974 // Active label editor
1975 wxTextCtrl
* m_labelEditor
;
1977 // For which property the label editor is active
1978 wxPGProperty
* m_labelEditorProperty
;
1980 // EventObject for wxPropertyGridEvents
1981 wxWindow
* m_eventObject
;
1983 // What (global) window is currently focused (needed to resolve event
1985 wxWindow
* m_curFocused
;
1987 // Event currently being sent - NULL if none at the moment
1988 wxPropertyGridEvent
* m_processedEvent
;
1990 // Last known top-level parent
1993 // Last closed top-level parent
1994 wxWindow
* m_tlpClosed
;
1996 // Local time ms when tlp was closed.
1997 wxLongLong m_tlpClosedTime
;
2000 wxPGSortCallback m_sortFunction
;
2002 // y coordinate of property that mouse hovering
2005 // Which column's editor is selected (usually 1)?
2006 unsigned int m_selColumn
;
2008 // x relative to splitter (needed for resize).
2011 // lines between cells
2013 // property labels and values are written in this colour
2014 wxColour m_colPropFore
;
2015 // or with this colour when disabled
2016 wxColour m_colDisPropFore
;
2017 // background for m_colPropFore
2018 wxColour m_colPropBack
;
2019 // text color for captions
2020 wxColour m_colCapFore
;
2021 // background color for captions
2022 wxColour m_colCapBack
;
2023 // foreground for selected property
2024 wxColour m_colSelFore
;
2025 // background for selected property (actually use background color when
2026 // control out-of-focus)
2027 wxColour m_colSelBack
;
2028 // background colour for margin
2029 wxColour m_colMargin
;
2030 // background colour for empty space below the grid
2031 wxColour m_colEmptySpace
;
2033 // Default property colours
2034 wxPGCell m_propertyDefaultCell
;
2036 // Default property category
2037 wxPGCell m_categoryDefaultCell
;
2039 // Backup of selected property's cells
2040 wxVector
<wxPGCell
> m_propCellsBackup
;
2042 // NB: These *cannot* be moved to globals.
2044 // labels when properties use common values
2045 wxVector
<wxPGCommonValue
*> m_commonValues
;
2047 // array of live events
2048 wxVector
<wxPropertyGridEvent
*> m_liveEvents
;
2050 // Which cv selection really sets value to unspecified?
2051 int m_cvUnspecified
;
2053 // Used to skip excess text editor events
2054 wxString m_prevTcValue
;
2058 // Sets some members to defaults (called constructors).
2061 // Initializes some members (called by Create and complex constructor).
2064 void OnPaint(wxPaintEvent
&event
);
2066 // main event receivers
2067 void OnMouseMove( wxMouseEvent
&event
);
2068 void OnMouseClick( wxMouseEvent
&event
);
2069 void OnMouseRightClick( wxMouseEvent
&event
);
2070 void OnMouseDoubleClick( wxMouseEvent
&event
);
2071 void OnMouseUp( wxMouseEvent
&event
);
2072 void OnKey( wxKeyEvent
&event
);
2073 void OnResize( wxSizeEvent
&event
);
2076 bool HandleMouseMove( int x
, unsigned int y
, wxMouseEvent
&event
);
2077 bool HandleMouseClick( int x
, unsigned int y
, wxMouseEvent
&event
);
2078 bool HandleMouseRightClick( int x
, unsigned int y
, wxMouseEvent
&event
);
2079 bool HandleMouseDoubleClick( int x
, unsigned int y
, wxMouseEvent
&event
);
2080 bool HandleMouseUp( int x
, unsigned int y
, wxMouseEvent
&event
);
2081 void HandleKeyEvent( wxKeyEvent
&event
, bool fromChild
);
2083 void OnMouseEntry( wxMouseEvent
&event
);
2085 void OnIdle( wxIdleEvent
&event
);
2086 void OnFocusEvent( wxFocusEvent
&event
);
2087 void OnChildFocusEvent( wxChildFocusEvent
& event
);
2089 bool OnMouseCommon( wxMouseEvent
&event
, int* px
, int *py
);
2090 bool OnMouseChildCommon( wxMouseEvent
&event
, int* px
, int *py
);
2092 // sub-control event handlers
2093 void OnMouseClickChild( wxMouseEvent
&event
);
2094 void OnMouseRightClickChild( wxMouseEvent
&event
);
2095 void OnMouseMoveChild( wxMouseEvent
&event
);
2096 void OnMouseUpChild( wxMouseEvent
&event
);
2097 void OnChildKeyDown( wxKeyEvent
&event
);
2099 void OnCaptureChange( wxMouseCaptureChangedEvent
&event
);
2101 void OnScrollEvent( wxScrollWinEvent
&event
);
2103 void OnSysColourChanged( wxSysColourChangedEvent
&event
);
2105 void OnTLPClose( wxCloseEvent
& event
);
2109 bool AddToSelectionFromInputEvent( wxPGProperty
* prop
,
2110 unsigned int colIndex
,
2111 wxMouseEvent
* event
= NULL
,
2115 Adjust the centering of the bitmap icons (collapse / expand) when the
2116 caption font changes.
2118 They need to be centered in the middle of the font, so a bit of deltaY
2119 adjustment is needed. On entry, m_captionFont must be set to window
2120 font. It will be modified properly.
2122 void CalculateFontAndBitmapStuff( int vspacing
);
2124 wxRect
GetEditorWidgetRect( wxPGProperty
* p
, int column
) const;
2126 void CorrectEditorWidgetSizeX();
2128 /** Called in RecalculateVirtualSize() to reposition control
2129 on virtual height changes.
2131 void CorrectEditorWidgetPosY();
2133 int DoDrawItems( wxDC
& dc
,
2134 const wxRect
* itemsRect
,
2135 bool isBuffered
) const;
2137 /** Draws an expand/collapse (ie. +/-) button.
2139 virtual void DrawExpanderButton( wxDC
& dc
, const wxRect
& rect
,
2140 wxPGProperty
* property
) const;
2142 /** Draws items from topitemy to bottomitemy */
2143 void DrawItems( wxDC
& dc
,
2144 unsigned int topItemY
,
2145 unsigned int bottomItemY
,
2146 const wxRect
* itemsRect
= NULL
);
2148 // Translate wxKeyEvent to wxPG_ACTION_XXX
2149 int KeyEventToActions(wxKeyEvent
&event
, int* pSecond
) const;
2151 int KeyEventToAction(wxKeyEvent
&event
) const
2153 return KeyEventToActions(event
, NULL
);
2156 void ImprovedClientToScreen( int* px
, int* py
);
2158 // Called by focus event handlers. newFocused is the window that becomes
2160 void HandleFocusChange( wxWindow
* newFocused
);
2162 /** Reloads all non-customized colours from system settings. */
2163 void RegainColours();
2165 virtual bool DoEditorValidate();
2167 // Similar to DoSelectProperty() but also works on columns
2168 // other than 1. Does not active editor if column is not
2170 bool DoSelectAndEdit( wxPGProperty
* prop
,
2171 unsigned int colIndex
,
2172 unsigned int selFlags
);
2174 void DoSetSelection( const wxArrayPGProperty
& newSelection
,
2177 void DoSetSplitterPosition( int newxpos
,
2178 int splitterIndex
= 0,
2179 int flags
= wxPG_SPLITTER_REFRESH
);
2181 bool DoAddToSelection( wxPGProperty
* prop
,
2184 bool DoRemoveFromSelection( wxPGProperty
* prop
,
2187 void DoBeginLabelEdit( unsigned int colIndex
, int selFlags
= 0 );
2188 void DoEndLabelEdit( bool commit
, int selFlags
= 0 );
2189 void OnLabelEditorEnterPress( wxCommandEvent
& event
);
2190 void OnLabelEditorKeyPress( wxKeyEvent
& event
);
2192 wxPGProperty
* DoGetItemAtY( int y
) const;
2194 void DestroyEditorWnd( wxWindow
* wnd
);
2197 virtual bool DoExpand( wxPGProperty
* p
, bool sendEvent
= false );
2199 virtual bool DoCollapse( wxPGProperty
* p
, bool sendEvent
= false );
2201 // Returns nearest paint visible property (such that will be painted unless
2202 // window is scrolled or resized). If given property is paint visible, then
2203 // it itself will be returned.
2204 wxPGProperty
* GetNearestPaintVisible( wxPGProperty
* p
) const;
2206 static void RegisterDefaultEditors();
2208 // Sets up basic event handling for child control
2209 void SetupChildEventHandling( wxWindow
* wnd
);
2211 void CustomSetCursor( int type
, bool override
= false );
2214 Repositions scrollbar and underlying panel according to changed virtual
2217 void RecalculateVirtualSize( int forceXPos
= -1 );
2219 void SetEditorAppearance( const wxPGCell
& cell
,
2220 bool unspecified
= false );
2222 void ResetEditorAppearance()
2225 cell
.SetEmptyData();
2226 SetEditorAppearance(cell
, false);
2229 void PrepareAfterItemsAdded();
2232 Send event from the property grid.
2234 Omit the wxPG_SEL_NOVALIDATE flag to allow vetoing the event
2236 bool SendEvent( int eventType
, wxPGProperty
* p
,
2237 wxVariant
* pValue
= NULL
,
2238 unsigned int selFlags
= wxPG_SEL_NOVALIDATE
,
2239 unsigned int column
= 1 );
2241 // This function only moves focus to the wxPropertyGrid if it already
2242 // was on one of its child controls.
2243 void SetFocusOnCanvas();
2245 bool DoHideProperty( wxPGProperty
* p
, bool hide
, int flags
);
2249 bool ButtonTriggerKeyTest( int action
, wxKeyEvent
& event
);
2251 DECLARE_EVENT_TABLE()
2254 // -----------------------------------------------------------------------
2256 // Bunch of inlines that need to resolved after all classes have been defined.
2259 inline bool wxPropertyGridPageState::IsDisplayed() const
2261 return ( this == m_pPropGrid
->GetState() );
2264 inline unsigned int wxPropertyGridPageState::GetActualVirtualHeight() const
2266 return DoGetRoot()->GetChildrenHeight(GetGrid()->GetRowHeight());
2269 inline wxString
wxPGProperty::GetHintText() const
2271 wxVariant vHintText
= GetAttribute(wxPGGlobalVars
->m_strHint
);
2273 #if wxPG_COMPATIBILITY_1_4
2274 // Try the old, deprecated "InlineHelp"
2275 if ( vHintText
.IsNull() )
2276 vHintText
= GetAttribute(wxPGGlobalVars
->m_strInlineHelp
);
2279 if ( !vHintText
.IsNull() )
2280 return vHintText
.GetString();
2282 return wxEmptyString
;
2285 inline int wxPGProperty::GetDisplayedCommonValueCount() const
2287 if ( HasFlag(wxPG_PROP_USES_COMMON_VALUE
) )
2289 wxPropertyGrid
* pg
= GetGrid();
2291 return (int) pg
->GetCommonValueCount();
2296 inline void wxPGProperty::SetDefaultValue( wxVariant
& value
)
2298 SetAttribute(wxPG_ATTR_DEFAULT_VALUE
, value
);
2301 inline void wxPGProperty::SetEditor( const wxString
& editorName
)
2303 m_customEditor
= wxPropertyGridInterface::GetEditorByName(editorName
);
2306 inline bool wxPGProperty::SetMaxLength( int maxLen
)
2308 return GetGrid()->SetPropertyMaxLength(this,maxLen
);
2311 // -----------------------------------------------------------------------
2313 #define wxPG_BASE_EVT_PRE_ID 1775
2317 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_SELECTED
, wxPropertyGridEvent
);
2318 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_CHANGING
, wxPropertyGridEvent
);
2319 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_CHANGED
, wxPropertyGridEvent
);
2320 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_HIGHLIGHTED
, wxPropertyGridEvent
);
2321 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_RIGHT_CLICK
, wxPropertyGridEvent
);
2322 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_PAGE_CHANGED
, wxPropertyGridEvent
);
2323 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_ITEM_COLLAPSED
, wxPropertyGridEvent
);
2324 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_ITEM_EXPANDED
, wxPropertyGridEvent
);
2325 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_DOUBLE_CLICK
, wxPropertyGridEvent
);
2326 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
,
2327 wxEVT_PG_LABEL_EDIT_BEGIN
, wxPropertyGridEvent
);
2328 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
,
2329 wxEVT_PG_LABEL_EDIT_ENDING
, wxPropertyGridEvent
);
2330 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
,
2331 wxEVT_PG_COL_BEGIN_DRAG
, wxPropertyGridEvent
);
2332 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
,
2333 wxEVT_PG_COL_DRAGGING
, wxPropertyGridEvent
);
2334 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
,
2335 wxEVT_PG_COL_END_DRAG
, wxPropertyGridEvent
);
2339 wxEVT_PG_SELECTED
= wxPG_BASE_EVT_PRE_ID
,
2342 wxEVT_PG_HIGHLIGHTED
,
2343 wxEVT_PG_RIGHT_CLICK
,
2344 wxEVT_PG_PAGE_CHANGED
,
2345 wxEVT_PG_ITEM_COLLAPSED
,
2346 wxEVT_PG_ITEM_EXPANDED
,
2347 wxEVT_PG_DOUBLE_CLICK
,
2348 wxEVT_PG_LABEL_EDIT_BEGIN
,
2349 wxEVT_PG_LABEL_EDIT_ENDING
,
2350 wxEVT_PG_COL_BEGIN_DRAG
,
2351 wxEVT_PG_COL_DRAGGING
,
2352 wxEVT_PG_COL_END_DRAG
2357 #define wxPG_BASE_EVT_TYPE wxEVT_PG_SELECTED
2358 #define wxPG_MAX_EVT_TYPE (wxPG_BASE_EVT_TYPE+30)
2362 typedef void (wxEvtHandler::*wxPropertyGridEventFunction
)(wxPropertyGridEvent
&);
2364 #define EVT_PG_SELECTED(id, fn) wxDECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_SELECTED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2365 #define EVT_PG_CHANGING(id, fn) wxDECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGING, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2366 #define EVT_PG_CHANGED(id, fn) wxDECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2367 #define EVT_PG_HIGHLIGHTED(id, fn) wxDECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_HIGHLIGHTED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2368 #define EVT_PG_RIGHT_CLICK(id, fn) wxDECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_RIGHT_CLICK, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2369 #define EVT_PG_DOUBLE_CLICK(id, fn) wxDECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_DOUBLE_CLICK, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2370 #define EVT_PG_PAGE_CHANGED(id, fn) wxDECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_PAGE_CHANGED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2371 #define EVT_PG_ITEM_COLLAPSED(id, fn) wxDECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_COLLAPSED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2372 #define EVT_PG_ITEM_EXPANDED(id, fn) wxDECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_EXPANDED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2373 #define EVT_PG_LABEL_EDIT_BEGIN(id, fn) wxDECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_LABEL_EDIT_BEGIN, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2374 #define EVT_PG_LABEL_EDIT_ENDING(id, fn) wxDECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_LABEL_EDIT_ENDING, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2375 #define EVT_PG_COL_BEGIN_DRAG(id, fn) wxDECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_COL_BEGIN_DRAG, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2376 #define EVT_PG_COL_DRAGGING(id, fn) wxDECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_COL_DRAGGING, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2377 #define EVT_PG_COL_END_DRAG(id, fn) wxDECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_COL_END_DRAG, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2379 #define wxPropertyGridEventHandler(fn) \
2380 wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn )
2385 /** @class wxPropertyGridEvent
2387 A propertygrid event holds information about events associated with
2388 wxPropertyGrid objects.
2390 @library{wxpropgrid}
2393 class WXDLLIMPEXP_PROPGRID wxPropertyGridEvent
: public wxCommandEvent
2398 wxPropertyGridEvent(wxEventType commandType
=0, int id
=0);
2400 /** Copy constructor. */
2401 wxPropertyGridEvent(const wxPropertyGridEvent
& event
);
2404 ~wxPropertyGridEvent();
2407 virtual wxEvent
* Clone() const;
2410 Returns the column index associated with this event.
2411 For the column dragging events, it is the column to the left
2412 of the splitter being dragged
2414 unsigned int GetColumn() const
2419 wxPGProperty
* GetMainParent() const
2421 wxASSERT(m_property
);
2422 return m_property
->GetMainParent();
2425 /** Returns id of associated property. */
2426 wxPGProperty
* GetProperty() const
2431 wxPGValidationInfo
& GetValidationInfo()
2433 wxASSERT(m_validationInfo
);
2434 return *m_validationInfo
;
2437 /** Returns true if you can veto the action that the event is signaling.
2439 bool CanVeto() const { return m_canVeto
; }
2442 Call this from your event handler to veto action that the event is
2445 You can only veto a shutdown if wxPropertyGridEvent::CanVeto returns
2448 Currently only wxEVT_PG_CHANGING supports vetoing.
2450 void Veto( bool veto
= true ) { m_wasVetoed
= veto
; }
2453 Returns name of the associated property.
2455 @remarks Property name is stored in event, so it remains
2456 accessible even after the associated property or
2457 the property grid has been deleted.
2459 wxString
GetPropertyName() const
2461 return m_propertyName
;
2465 Returns value of the associated property. Works for all event
2466 types, but for wxEVT_PG_CHANGING this member function returns
2467 the value that is pending, so you can call Veto() if the
2468 value is not satisfactory.
2470 @remarks Property value is stored in event, so it remains
2471 accessible even after the associated property or
2472 the property grid has been deleted.
2474 wxVariant
GetPropertyValue() const
2476 if ( m_validationInfo
)
2477 return m_validationInfo
->GetValue();
2482 Returns value of the associated property.
2484 @see GetPropertyValue
2486 wxVariant
GetValue() const
2488 return GetPropertyValue();
2492 Set override validation failure behavior.
2494 Only effective if Veto was also called, and only allowed if event type
2495 is wxEVT_PG_CHANGING.
2497 void SetValidationFailureBehavior( wxPGVFBFlags flags
)
2499 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2500 m_validationInfo
->SetFailureBehavior( flags
);
2503 /** Sets custom failure message for this time only. Only applies if
2504 wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
2506 void SetValidationFailureMessage( const wxString
& message
)
2508 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2509 m_validationInfo
->SetFailureMessage( message
);
2512 wxPGVFBFlags
GetValidationFailureBehavior() const
2514 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2515 return m_validationInfo
->GetFailureBehavior();
2518 void SetColumn( unsigned int column
)
2523 void SetCanVeto( bool canVeto
) { m_canVeto
= canVeto
; }
2524 bool WasVetoed() const { return m_wasVetoed
; }
2526 /** Changes the associated property. */
2527 void SetProperty( wxPGProperty
* p
)
2531 m_propertyName
= p
->GetName();
2534 void SetPropertyValue( wxVariant value
)
2539 void SetPropertyGrid( wxPropertyGrid
* pg
)
2542 OnPropertyGridSet();
2545 void SetupValidationInfo()
2548 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2549 m_validationInfo
= &m_pg
->GetValidationInfo();
2550 m_value
= m_validationInfo
->GetValue();
2555 void OnPropertyGridSet();
2556 DECLARE_DYNAMIC_CLASS(wxPropertyGridEvent
)
2558 wxPGProperty
* m_property
;
2559 wxPropertyGrid
* m_pg
;
2560 wxPGValidationInfo
* m_validationInfo
;
2562 wxString m_propertyName
;
2565 unsigned int m_column
;
2572 // -----------------------------------------------------------------------
2574 /** @class wxPropertyGridPopulator
2576 Allows populating wxPropertyGrid from arbitrary text source.
2578 class WXDLLIMPEXP_PROPGRID wxPropertyGridPopulator
2581 /** Default constructor.
2583 wxPropertyGridPopulator();
2586 virtual ~wxPropertyGridPopulator();
2588 void SetState( wxPropertyGridPageState
* state
);
2590 void SetGrid( wxPropertyGrid
* pg
);
2592 /** Appends a new property under bottommost parent.
2594 Property class as string.
2596 wxPGProperty
* Add( const wxString
& propClass
,
2597 const wxString
& propLabel
,
2598 const wxString
& propName
,
2599 const wxString
* propValue
,
2600 wxPGChoices
* pChoices
= NULL
);
2603 Pushes property to the back of parent array (ie it becomes bottommost
2604 parent), and starts scanning/adding children for it.
2606 When finished, parent array is returned to the original state.
2608 void AddChildren( wxPGProperty
* property
);
2610 /** Adds attribute to the bottommost property.
2612 Allowed values: "string", (same as string), "int", "bool". Empty string
2615 bool AddAttribute( const wxString
& name
,
2616 const wxString
& type
,
2617 const wxString
& value
);
2619 /** Called once in AddChildren.
2621 virtual void DoScanForChildren() = 0;
2624 Returns id of parent property for which children can currently be
2627 wxPGProperty
* GetCurParent() const
2629 return (wxPGProperty
*) m_propHierarchy
[m_propHierarchy
.size()-1];
2632 wxPropertyGridPageState
* GetState() { return m_state
; }
2633 const wxPropertyGridPageState
* GetState() const { return m_state
; }
2635 /** Like wxString::ToLong, except allows N% in addition of N.
2637 static bool ToLongPCT( const wxString
& s
, long* pval
, long max
);
2639 /** Parses strings of format "choice1"[=value1] ... "choiceN"[=valueN] into
2640 wxPGChoices. Registers parsed result using idString (if not empty).
2641 Also, if choices with given id already registered, then don't parse but
2642 return those choices instead.
2644 wxPGChoices
ParseChoices( const wxString
& choicesString
,
2645 const wxString
& idString
);
2647 /** Implement in derived class to do custom process when an error occurs.
2648 Default implementation uses wxLogError.
2650 virtual void ProcessError( const wxString
& msg
);
2654 /** Used property grid. */
2655 wxPropertyGrid
* m_pg
;
2657 /** Used property grid state. */
2658 wxPropertyGridPageState
* m_state
;
2660 /** Tree-hierarchy of added properties (that can have children). */
2661 wxArrayPGProperty m_propHierarchy
;
2663 /** Hashmap for string-id to wxPGChoicesData mapping. */
2664 wxPGHashMapS2P m_dictIdChoices
;
2667 // -----------------------------------------------------------------------
2670 // Undefine macros that are not needed outside propertygrid sources
2672 #ifndef __wxPG_SOURCE_FILE__
2673 #undef wxPG_FL_DESC_REFRESH_REQUIRED
2674 #undef wxPG_FL_SCROLLBAR_DETECTED
2675 #undef wxPG_FL_CREATEDSTATE
2676 #undef wxPG_FL_NOSTATUSBARHELP
2677 #undef wxPG_FL_SCROLLED
2678 #undef wxPG_FL_FOCUS_INSIDE_CHILD
2679 #undef wxPG_FL_FOCUS_INSIDE
2680 #undef wxPG_FL_MOUSE_INSIDE_CHILD
2681 #undef wxPG_FL_CUR_USES_CUSTOM_IMAGE
2682 #undef wxPG_FL_PRIMARY_FILLS_ENTIRE
2683 #undef wxPG_FL_VALUE_MODIFIED
2684 #undef wxPG_FL_MOUSE_INSIDE
2685 #undef wxPG_FL_FOCUSED
2686 #undef wxPG_FL_MOUSE_CAPTURED
2687 #undef wxPG_FL_INITIALIZED
2688 #undef wxPG_FL_ACTIVATION_BY_CLICK
2689 #undef wxPG_SUPPORT_TOOLTIPS
2690 #undef wxPG_DOUBLE_BUFFER
2691 #undef wxPG_ICON_WIDTH
2692 #undef wxPG_USE_RENDERER_NATIVE
2693 // Following are needed by the manager headers
2694 // #undef const wxString&
2697 // -----------------------------------------------------------------------
2701 #endif // _WX_PROPGRID_PROPGRID_H_