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/thread.h"
18 #include "wx/dcclient.h"
19 #include "wx/scrolwin.h"
20 #include "wx/tooltip.h"
21 #include "wx/datetime.h"
23 #include "wx/propgrid/property.h"
24 #include "wx/propgrid/propgridiface.h"
28 extern WXDLLIMPEXP_DATA_PROPGRID(const char) wxPropertyGridNameStr
[];
33 // -----------------------------------------------------------------------
35 // -----------------------------------------------------------------------
37 // This is required for sharing common global variables.
38 class WXDLLIMPEXP_PROPGRID wxPGGlobalVarsClass
42 wxPGGlobalVarsClass();
43 ~wxPGGlobalVarsClass();
46 // Critical section for handling the globals. Generally it is not needed
47 // since GUI code is supposed to be in single thread. However,
48 // we do want the user to be able to convey wxPropertyGridEvents to other
50 wxCriticalSection m_critSect
;
53 // Used by advprops, but here to make things easier.
54 wxString m_pDefaultImageWildcard
;
56 // Map of editor class instances (keys are name string).
57 wxPGHashMapS2P m_mapEditorClasses
;
60 wxVector
<wxValidator
*> m_arrValidators
; // These wxValidators need to be freed
63 wxPGHashMapS2P m_dictPropertyClassInfo
; // PropertyName -> ClassInfo
65 wxPGChoices
* m_fontFamilyChoices
;
67 // Replace with your own to affect all properties using default renderer.
68 wxPGCellRenderer
* m_defaultRenderer
;
70 wxPGChoices m_boolChoices
;
72 wxVariant m_vEmptyString
;
74 wxVariant m_vMinusOne
;
78 // Cached constant strings
79 wxPGCachedString m_strstring
;
80 wxPGCachedString m_strlong
;
81 wxPGCachedString m_strbool
;
82 wxPGCachedString m_strlist
;
84 wxPGCachedString m_strDefaultValue
;
85 wxPGCachedString m_strMin
;
86 wxPGCachedString m_strMax
;
87 wxPGCachedString m_strUnits
;
88 wxPGCachedString m_strHint
;
89 #if wxPG_COMPATIBILITY_1_4
90 wxPGCachedString m_strInlineHelp
;
93 // If true then some things are automatically translated
94 bool m_autoGetTranslation
;
96 // > 0 if errors cannot or should not be shown in statusbar etc.
99 int m_extraStyle
; // global extra style
103 int HasExtraStyle( int style
) const { return (m_extraStyle
& style
); }
106 extern WXDLLIMPEXP_DATA_PROPGRID(wxPGGlobalVarsClass
*) wxPGGlobalVars
;
108 #define wxPGVariant_EmptyString (wxPGGlobalVars->m_vEmptyString)
109 #define wxPGVariant_Zero (wxPGGlobalVars->m_vZero)
110 #define wxPGVariant_MinusOne (wxPGGlobalVars->m_vMinusOne)
111 #define wxPGVariant_True (wxPGGlobalVars->m_vTrue)
112 #define wxPGVariant_False (wxPGGlobalVars->m_vFalse)
114 #define wxPGVariant_Bool(A) (A?wxPGVariant_True:wxPGVariant_False)
116 // When wxPG is loaded dynamically after the application is already running
117 // then the built-in module system won't pick this one up. Add it manually.
118 WXDLLIMPEXP_PROPGRID
void wxPGInitResourceModule();
120 // -----------------------------------------------------------------------
122 /** @section propgrid_window_styles wxPropertyGrid Window Styles
124 SetWindowStyleFlag method can be used to modify some of these at run-time.
127 enum wxPG_WINDOW_STYLES
130 /** This will cause Sort() automatically after an item is added.
131 When inserting a lot of items in this mode, it may make sense to
132 use Freeze() before operations and Thaw() afterwards to increase
135 wxPG_AUTO_SORT
= 0x00000010,
137 /** Categories are not initially shown (even if added).
138 IMPORTANT NOTE: If you do not plan to use categories, then this
139 style will waste resources.
140 This flag can also be changed using wxPropertyGrid::EnableCategories method.
142 wxPG_HIDE_CATEGORIES
= 0x00000020,
144 /* This style combines non-categoric mode and automatic sorting.
146 wxPG_ALPHABETIC_MODE
= (wxPG_HIDE_CATEGORIES
|wxPG_AUTO_SORT
),
148 /** Modified values are shown in bold font. Changing this requires Refresh()
151 wxPG_BOLD_MODIFIED
= 0x00000040,
153 /** Using this style, the column splitters move automatically based on column
154 proportions (default is equal proportion for every column). This behavior
155 stops once the user manually moves a splitter, and returns when a
156 splitter is double-clicked.
158 @see wxPropertyGridInterface::SetColumnProportion().
160 wxPG_SPLITTER_AUTO_CENTER
= 0x00000080,
162 /** Display tooltips for cell text that cannot be shown completely. If
163 wxUSE_TOOLTIPS is 0, then this doesn't have any effect.
165 wxPG_TOOLTIPS
= 0x00000100,
167 /** Disables margin and hides all expand/collapse buttons that would appear
168 outside the margin (for sub-properties). Toggling this style automatically
169 expands all collapsed items.
171 wxPG_HIDE_MARGIN
= 0x00000200,
173 /** This style prevents user from moving the splitter.
175 wxPG_STATIC_SPLITTER
= 0x00000400,
177 /** Combination of other styles that make it impossible for user to modify
180 wxPG_STATIC_LAYOUT
= (wxPG_HIDE_MARGIN
|wxPG_STATIC_SPLITTER
),
182 /** Disables wxTextCtrl based editors for properties which
183 can be edited in another way.
185 Equals calling wxPropertyGrid::LimitPropertyEditing for all added
188 wxPG_LIMITED_EDITING
= 0x00000800,
190 /** wxPropertyGridManager only: Show toolbar for mode and page selection. */
191 wxPG_TOOLBAR
= 0x00001000,
193 /** wxPropertyGridManager only: Show adjustable text box showing description
194 or help text, if available, for currently selected property.
196 wxPG_DESCRIPTION
= 0x00002000,
198 /** wxPropertyGridManager only: don't show an internal border around the
199 property grid. Recommended if you use a header.
201 wxPG_NO_INTERNAL_BORDER
= 0x00004000
204 #if wxPG_COMPATIBILITY_1_4
205 // In wxPG 1.4 this was used to enable now-default theme border support
206 // in wxPropertyGridManager.
207 #define wxPG_THEME_BORDER 0x00000000
211 enum wxPG_EX_WINDOW_STYLES
215 NOTE: wxPG_EX_xxx are extra window styles and must be set using
216 SetExtraStyle() member function.
218 Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if
219 wxPG_HIDE_CATEGORIES is not defined, the non-categorized data storage is
220 not activated, and switching the mode first time becomes somewhat slower.
221 wxPG_EX_INIT_NOCAT activates the non-categorized data storage right away.
222 IMPORTANT NOTE: If you do plan not switching to non-categoric mode, or if
223 you don't plan to use categories at all, then using this style will result
224 in waste of resources.
227 wxPG_EX_INIT_NOCAT
= 0x00001000,
229 /** Extended window style that sets wxPropertyGridManager toolbar to not
232 wxPG_EX_NO_FLAT_TOOLBAR
= 0x00002000,
234 /** Shows alphabetic/categoric mode buttons from toolbar.
236 wxPG_EX_MODE_BUTTONS
= 0x00008000,
238 /** Show property help strings as tool tips instead as text on the status bar.
239 You can set the help strings using SetPropertyHelpString member function.
241 wxPG_EX_HELP_AS_TOOLTIPS
= 0x00010000,
243 /** Prevent TAB from focusing to wxButtons. This behavior was default
244 in version 1.2.0 and earlier.
245 NOTE! Tabbing to button doesn't work yet. Problem seems to be that on wxMSW
246 atleast the button doesn't properly propagate key events (yes, I'm using
249 //wxPG_EX_NO_TAB_TO_BUTTON = 0x00020000,
251 /** Allows relying on native double-buffering.
253 wxPG_EX_NATIVE_DOUBLE_BUFFERING
= 0x00080000,
255 /** Set this style to let user have ability to set values of properties to
256 unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for
259 wxPG_EX_AUTO_UNSPECIFIED_VALUES
= 0x00200000,
262 If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION
263 and wxPG_STRING_PASSWORD) are not stored into property's attribute storage
264 (thus they are not readable).
266 Note that this option is global, and applies to all wxPG property
269 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES
= 0x00400000,
271 /** Hides page selection buttons from toolbar.
273 wxPG_EX_HIDE_PAGE_BUTTONS
= 0x01000000,
275 /** Allows multiple properties to be selected by user (by pressing SHIFT
276 when clicking on a property, or by dragging with left mouse button
279 You can get array of selected properties with
280 wxPropertyGridInterface::GetSelectedProperties(). In multiple selection
281 mode wxPropertyGridInterface::GetSelection() returns
282 property which has editor active (usually the first one
283 selected). Other useful member functions are ClearSelection(),
284 AddToSelection() and RemoveFromSelection().
286 wxPG_EX_MULTIPLE_SELECTION
= 0x02000000,
289 This enables top-level window tracking which allows wxPropertyGrid to
290 notify the application of last-minute property value changes by user.
292 This style is not enabled by default because it may cause crashes when
293 wxPropertyGrid is used in with wxAUI or similar system.
295 @remarks If you are not in fact using any system that may change
296 wxPropertyGrid's top-level parent window on its own, then you
297 are recommended to enable this style.
299 wxPG_EX_ENABLE_TLP_TRACKING
= 0x04000000,
301 /** Don't show divider above toolbar, on Windows.
303 wxPG_EX_NO_TOOLBAR_DIVIDER
= 0x08000000,
305 /** Show a separator below the toolbar.
307 wxPG_EX_TOOLBAR_SEPARATOR
= 0x10000000
311 #if wxPG_COMPATIBILITY_1_4
312 #define wxPG_EX_DISABLE_TLP_TRACKING 0x00000000
315 /** Combines various styles.
317 #define wxPG_DEFAULT_STYLE (0)
319 /** Combines various styles.
321 #define wxPGMAN_DEFAULT_STYLE (0)
326 // -----------------------------------------------------------------------
329 // Ids for sub-controls
330 // NB: It should not matter what these are.
331 #define wxPG_SUBID1 2
332 #define wxPG_SUBID2 3
333 #define wxPG_SUBID_TEMP1 4
335 // -----------------------------------------------------------------------
337 /** @class wxPGCommonValue
339 wxPropertyGrid stores information about common values in these
342 NB: Common value feature is not complete, and thus not mentioned in
345 class WXDLLIMPEXP_PROPGRID wxPGCommonValue
349 wxPGCommonValue( const wxString
& label
, wxPGCellRenderer
* renderer
)
352 m_renderer
= renderer
;
355 virtual ~wxPGCommonValue()
357 m_renderer
->DecRef();
360 virtual wxString
GetEditableText() const { return m_label
; }
361 const wxString
& GetLabel() const { return m_label
; }
362 wxPGCellRenderer
* GetRenderer() const { return m_renderer
; }
366 wxPGCellRenderer
* m_renderer
;
369 // -----------------------------------------------------------------------
371 /** @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
375 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
378 /** Prevents user from leaving property unless value is valid. If this
379 behavior flag is not used, then value change is instead cancelled.
381 wxPG_VFB_STAY_IN_PROPERTY
= 0x01,
383 /** Calls wxBell() on validation failure.
385 wxPG_VFB_BEEP
= 0x02,
387 /** Cell with invalid value will be marked (with red colour).
389 wxPG_VFB_MARK_CELL
= 0x04,
391 /** Display customizable text message explaining the situation.
393 wxPG_VFB_SHOW_MESSAGE
= 0x08,
396 wxPG_VFB_DEFAULT
= wxPG_VFB_STAY_IN_PROPERTY
|wxPG_VFB_BEEP
,
398 /** Only used internally. */
399 wxPG_VFB_UNDEFINED
= 0x80
406 typedef wxByte wxPGVFBFlags
;
411 Used to convey validation information to and from functions that
412 actually perform validation. Mostly used in custom property
415 class WXDLLIMPEXP_PROPGRID wxPGValidationInfo
417 friend class wxPropertyGrid
;
420 @return Returns failure behavior which is a combination of
421 @ref propgrid_vfbflags.
423 wxPGVFBFlags
GetFailureBehavior() const
424 { return m_failureBehavior
; }
427 Returns current failure message.
429 const wxString
& GetFailureMessage() const
430 { return m_failureMessage
; }
433 Returns reference to pending value.
435 wxVariant
& GetValue()
441 /** Set validation failure behavior
443 @param failureBehavior
444 Mixture of @ref propgrid_vfbflags.
446 void SetFailureBehavior(wxPGVFBFlags failureBehavior
)
447 { m_failureBehavior
= failureBehavior
; }
450 Set current failure message.
452 void SetFailureMessage(const wxString
& message
)
453 { m_failureMessage
= message
; }
456 /** Value to be validated.
460 /** Message displayed on validation failure.
462 wxString m_failureMessage
;
464 /** Validation failure behavior. Use wxPG_VFB_XXX flags.
466 wxPGVFBFlags m_failureBehavior
;
469 // -----------------------------------------------------------------------
471 /** @section propgrid_pgactions wxPropertyGrid Action Identifiers
473 These are used with wxPropertyGrid::AddActionTrigger() and
474 wxPropertyGrid::ClearActionTriggers().
478 enum wxPG_KEYBOARD_ACTIONS
480 wxPG_ACTION_INVALID
= 0,
481 wxPG_ACTION_NEXT_PROPERTY
,
482 wxPG_ACTION_PREV_PROPERTY
,
483 wxPG_ACTION_EXPAND_PROPERTY
,
484 wxPG_ACTION_COLLAPSE_PROPERTY
,
485 wxPG_ACTION_CANCEL_EDIT
,
486 wxPG_ACTION_PRESS_BUTTON
, // Causes editor button (if any) to be pressed
493 // -----------------------------------------------------------------------
496 // wxPropertyGrid::DoSelectProperty flags (selFlags)
498 // Focuses to created editor
499 #define wxPG_SEL_FOCUS 0x0001
500 // Forces deletion and recreation of editor
501 #define wxPG_SEL_FORCE 0x0002
502 // For example, doesn't cause EnsureVisible
503 #define wxPG_SEL_NONVISIBLE 0x0004
504 // Do not validate editor's value before selecting
505 #define wxPG_SEL_NOVALIDATE 0x0008
506 // Property being deselected is about to be deleted
507 #define wxPG_SEL_DELETING 0x0010
508 // Property's values was set to unspecified by the user
509 #define wxPG_SEL_SETUNSPEC 0x0020
510 // Property's event handler changed the value
511 #define wxPG_SEL_DIALOGVAL 0x0040
512 // Set to disable sending of wxEVT_PG_SELECTED event
513 #define wxPG_SEL_DONT_SEND_EVENT 0x0080
514 // Don't make any graphics updates
515 #define wxPG_SEL_NO_REFRESH 0x0100
517 // -----------------------------------------------------------------------
519 // DoSetSplitterPosition() flags
521 enum wxPG_SET_SPLITTER_POSITION_SPLITTER_FLAGS
523 wxPG_SPLITTER_REFRESH
= 0x0001,
524 wxPG_SPLITTER_ALL_PAGES
= 0x0002,
525 wxPG_SPLITTER_FROM_EVENT
= 0x0004,
526 wxPG_SPLITTER_FROM_AUTO_CENTER
= 0x0008
530 // -----------------------------------------------------------------------
533 #define wxPG_FL_INITIALIZED 0x0001
534 // Set when creating editor controls if it was clicked on.
535 #define wxPG_FL_ACTIVATION_BY_CLICK 0x0002
536 #define wxPG_FL_DONT_CENTER_SPLITTER 0x0004
537 #define wxPG_FL_FOCUSED 0x0008
538 #define wxPG_FL_MOUSE_CAPTURED 0x0010
539 #define wxPG_FL_MOUSE_INSIDE 0x0020
540 #define wxPG_FL_VALUE_MODIFIED 0x0040
541 // don't clear background of m_wndEditor
542 #define wxPG_FL_PRIMARY_FILLS_ENTIRE 0x0080
543 // currently active editor uses custom image
544 #define wxPG_FL_CUR_USES_CUSTOM_IMAGE 0x0100
545 // cell colours override selection colours for selected cell
546 #define wxPG_FL_CELL_OVERRIDES_SEL 0x0200
547 #define wxPG_FL_SCROLLED 0x0400
548 // set when all added/inserted properties get hideable flag
549 #define wxPG_FL_ADDING_HIDEABLES 0x0800
550 // Disables showing help strings on statusbar.
551 #define wxPG_FL_NOSTATUSBARHELP 0x1000
552 // Marks that we created the state, so we have to destroy it too.
553 #define wxPG_FL_CREATEDSTATE 0x2000
554 // Set if scrollbar's existence was detected in last onresize.
555 #define wxPG_FL_SCROLLBAR_DETECTED 0x4000
556 // Set if wxPGMan requires redrawing of description text box.
557 #define wxPG_FL_DESC_REFRESH_REQUIRED 0x8000
558 // Set if contained in wxPropertyGridManager
559 #define wxPG_FL_IN_MANAGER 0x00020000
560 // Set after wxPropertyGrid is shown in its initial good size
561 #define wxPG_FL_GOOD_SIZE_SET 0x00040000
562 // Set when in SelectProperty.
563 #define wxPG_FL_IN_SELECT_PROPERTY 0x00100000
564 // Set when help string is shown in status bar
565 #define wxPG_FL_STRING_IN_STATUSBAR 0x00200000
566 // Validation failed. Clear on modify event.
567 #define wxPG_FL_VALIDATION_FAILED 0x00800000
568 // Auto sort is enabled (for categorized mode)
569 #define wxPG_FL_CATMODE_AUTO_SORT 0x01000000
570 // Set after page has been inserted to manager
571 #define wxPG_MAN_FL_PAGE_INSERTED 0x02000000
572 // Active editor control is abnormally large
573 #define wxPG_FL_ABNORMAL_EDITOR 0x04000000
574 // Recursion guard for HandleCustomEditorEvent
575 #define wxPG_FL_IN_HANDLECUSTOMEDITOREVENT 0x08000000
576 #define wxPG_FL_VALUE_CHANGE_IN_EVENT 0x10000000
577 // Editor control width should not change on resize
578 #define wxPG_FL_FIXED_WIDTH_EDITOR 0x20000000
579 // Width of panel can be different than width of grid
580 #define wxPG_FL_HAS_VIRTUAL_WIDTH 0x40000000
581 // Prevents RecalculateVirtualSize re-entrancy
582 #define wxPG_FL_RECALCULATING_VIRTUAL_SIZE 0x80000000
584 #if !defined(__wxPG_SOURCE_FILE__)
585 // Reduce compile time, but still include in user app
586 #include "wx/propgrid/props.h"
589 // -----------------------------------------------------------------------
591 /** @class wxPropertyGrid
593 wxPropertyGrid is a specialized grid for editing properties
594 such as strings, numbers, flagsets, fonts, and colours. wxPropertySheet
595 used to do the very same thing, but it hasn't been updated for a while
596 and it is currently deprecated.
598 Please note that most member functions are inherited and as such not
599 documented on this page. This means you will probably also want to read
600 wxPropertyGridInterface class reference.
602 See also @ref overview_propgrid.
604 @section propgrid_window_styles_ Window Styles
606 See @ref propgrid_window_styles.
608 @section propgrid_event_handling Event Handling
610 To process input from a propertygrid control, use these event handler
611 macros to direct input to member functions that take a wxPropertyGridEvent
614 @beginEventTable{wxPropertyGridEvent}
615 @event{EVT_PG_SELECTED (id, func)}
616 Respond to wxEVT_PG_SELECTED event, generated when a property selection
617 has been changed, either by user action or by indirect program
618 function. For instance, collapsing a parent property programmatically
619 causes any selected child property to become unselected, and may
620 therefore cause this event to be generated.
621 @event{EVT_PG_CHANGING(id, func)}
622 Respond to wxEVT_PG_CHANGING event, generated when property value
623 is about to be changed by user. Use wxPropertyGridEvent::GetValue()
624 to take a peek at the pending value, and wxPropertyGridEvent::Veto()
625 to prevent change from taking place, if necessary.
626 @event{EVT_PG_HIGHLIGHTED(id, func)}
627 Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
628 moves over a property. Event's property is NULL if hovered area does
629 not belong to any property.
630 @event{EVT_PG_RIGHT_CLICK(id, func)}
631 Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
632 clicked on with right mouse button.
633 @event{EVT_PG_DOUBLE_CLICK(id, func)}
634 Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
635 double-clicked onwith left mouse button.
636 @event{EVT_PG_ITEM_COLLAPSED(id, func)}
637 Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
638 a property or category..
639 @event{EVT_PG_ITEM_EXPANDED(id, func)}
640 Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
641 a property or category..
642 @event{EVT_PG_LABEL_EDIT_BEGIN(id, func)}
643 Respond to wxEVT_PG_LABEL_EDIT_BEGIN event, generated when is about to
644 begin editing a property label. You can veto this event to prevent the
646 @event{EVT_PG_LABEL_EDIT_ENDING(id, func)}
647 Respond to wxEVT_PG_LABEL_EDIT_ENDING event, generated when is about to
648 end editing of a property label. You can veto this event to prevent the
650 @event{EVT_PG_COL_BEGIN_DRAG(id, func)}
651 Respond to wxEVT_PG_COL_BEGIN_DRAG event, generated when user
652 starts resizing a column - can be vetoed.
653 @event{EVT_PG_COL_DRAGGING,(id, func)}
654 Respond to wxEVT_PG_COL_DRAGGING, event, generated when a
655 column resize by user is in progress. This event is also generated
656 when user double-clicks the splitter in order to recenter
658 @event{EVT_PG_COL_END_DRAG(id, func)}
659 Respond to wxEVT_PG_COL_END_DRAG event, generated after column
660 resize by user has finished.
665 - Use Freeze() and Thaw() respectively to disable and enable drawing. This
666 will also delay sorting etc. miscellaneous calculations to the last
672 class WXDLLIMPEXP_PROPGRID
673 wxPropertyGrid
: public wxScrolledWindow
, public wxPropertyGridInterface
675 friend class wxPropertyGridEvent
;
676 friend class wxPropertyGridPageState
;
677 friend class wxPropertyGridInterface
;
678 friend class wxPropertyGridManager
;
679 friend class wxPGHeaderCtrl
;
681 DECLARE_DYNAMIC_CLASS(wxPropertyGrid
)
686 Two step constructor.
688 Call Create when this constructor is called to build up the
694 /** The default constructor. The styles to be used are styles valid for
695 the wxWindow and wxScrolledWindow.
697 @see @link wndflags Additional Window Styles @endlink
699 wxPropertyGrid( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
700 const wxPoint
& pos
= wxDefaultPosition
,
701 const wxSize
& size
= wxDefaultSize
,
702 long style
= wxPG_DEFAULT_STYLE
,
703 const wxString
& name
= wxPropertyGridNameStr
);
706 virtual ~wxPropertyGrid();
708 /** Adds given key combination to trigger given action.
711 Which action to trigger. See @link pgactions List of list of
712 wxPropertyGrid actions@endlink.
714 void AddActionTrigger( int action
, int keycode
, int modifiers
= 0 );
717 This static function enables or disables automatic use of
718 wxGetTranslation for following strings: wxEnumProperty list labels,
719 wxFlagsProperty sub-property labels.
723 static void AutoGetTranslation( bool enable
);
726 Changes value of a property, as if from an editor.
728 Use this instead of SetPropertyValue() if you need the value to run
729 through validation process, and also send the property change event.
732 Returns true if value was successfully changed.
734 bool ChangePropertyValue( wxPGPropArg id
, wxVariant newValue
);
737 Centers the splitter.
739 If argument is true, automatic splitter centering is enabled (only
740 applicapple if style wxPG_SPLITTER_AUTO_CENTER was defined).
742 void CenterSplitter( bool enable_auto_centering
= false );
744 /** Deletes all properties.
746 virtual void Clear();
748 /** Clears action triggers for given action.
750 Which action to trigger. See @link pgactions List of list of
751 wxPropertyGrid actions@endlink.
753 void ClearActionTriggers( int action
);
755 /** Forces updating the value of property from the editor control.
757 Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
758 ProcessEvent, meaning your event handlers will be called immediately.
761 Returns true if anything was changed.
763 virtual bool CommitChangesFromEditor( wxUint32 flags
= 0 );
768 Whenever the control is created without any parameters, use Create to
769 actually create it. Don't access the control's public methods before
770 this is called @see @link wndflags Additional Window Styles@endlink
772 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
773 const wxPoint
& pos
= wxDefaultPosition
,
774 const wxSize
& size
= wxDefaultSize
,
775 long style
= wxPG_DEFAULT_STYLE
,
776 const wxString
& name
= wxPropertyGridNameStr
);
779 Call when editor widget's contents is modified.
781 For example, this is called when changes text in wxTextCtrl (used in
782 wxStringProperty and wxIntProperty).
785 This function should only be called by custom properties.
787 @see wxPGProperty::OnEvent()
789 void EditorsValueWasModified() { m_iFlags
|= wxPG_FL_VALUE_MODIFIED
; }
791 /** Reverse of EditorsValueWasModified().
794 This function should only be called by custom properties.
796 void EditorsValueWasNotModified()
798 m_iFlags
&= ~(wxPG_FL_VALUE_MODIFIED
);
802 Enables or disables (shows/hides) categories according to parameter
805 bool EnableCategories( bool enable
);
807 /** Scrolls and/or expands items to ensure that the given item is visible.
808 Returns true if something was actually done.
810 bool EnsureVisible( wxPGPropArg id
);
813 Reduces column sizes to minimum possible that contents are still
814 visibly (naturally some margin space will be applied as well).
817 Minimum size for the grid to still display everything.
820 Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
822 This function only works properly if grid size prior to call was already
825 Note that you can also get calculated column widths by calling
826 GetState->GetColumnWidth() immediately after this function returns.
830 wxSize sz
= m_pState
->DoFitColumns();
835 Returns wxWindow that the properties are painted on, and which should
836 be used as the parent for editor controls.
843 /** Returns current category caption background colour. */
844 wxColour
GetCaptionBackgroundColour() const { return m_colCapBack
; }
846 wxFont
& GetCaptionFont() { return m_captionFont
; }
848 const wxFont
& GetCaptionFont() const { return m_captionFont
; }
850 /** Returns current category caption text colour. */
851 wxColour
GetCaptionForegroundColour() const { return m_colCapFore
; }
853 /** Returns current cell background colour. */
854 wxColour
GetCellBackgroundColour() const { return m_colPropBack
; }
856 /** Returns current cell text colour when disabled. */
857 wxColour
GetCellDisabledTextColour() const { return m_colDisPropFore
; }
859 /** Returns current cell text colour. */
860 wxColour
GetCellTextColour() const { return m_colPropFore
; }
863 Returns number of columns currently on grid.
865 unsigned int GetColumnCount() const
867 return (unsigned int) m_pState
->m_colWidths
.size();
870 /** Returns colour of empty space below properties. */
871 wxColour
GetEmptySpaceColour() const { return m_colEmptySpace
; }
873 /** Returns height of highest characters of used font. */
874 int GetFontHeight() const { return m_fontHeight
; }
876 /** Returns pointer to itself. Dummy function that enables same kind
877 of code to use wxPropertyGrid and wxPropertyGridManager.
879 wxPropertyGrid
* GetGrid() { return this; }
881 /** Returns rectangle of custom paint image.
883 wxRect
GetImageRect( wxPGProperty
* p
, int item
) const;
885 /** Returns size of the custom paint image in front of property.
886 If no argument is given, returns preferred size.
888 wxSize
GetImageSize( wxPGProperty
* p
= NULL
, int item
= -1 ) const;
891 /** Returns last item which could be iterated using given flags.
893 See @ref propgrid_iterator_flags.
895 wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
)
897 return m_pState
->GetLastItem(flags
);
900 const wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
) const
902 return m_pState
->GetLastItem(flags
);
906 /** Returns colour of lines between cells. */
907 wxColour
GetLineColour() const { return m_colLine
; }
909 /** Returns background colour of margin. */
910 wxColour
GetMarginColour() const { return m_colMargin
; }
912 /** Returns margin width. */
913 int GetMarginWidth() const { return m_marginWidth
; }
916 Returns most up-to-date value of selected property. This will return
917 value different from GetSelectedProperty()->GetValue() only when text
918 editor is activate and string edited by user represents valid,
919 uncommitted property value.
921 wxVariant
GetUncommittedPropertyValue();
923 /** Returns "root property". It does not have name, etc. and it is not
924 visible. It is only useful for accessing its children.
926 wxPGProperty
* GetRoot() const { return m_pState
->m_properties
; }
928 /** Returns height of a single grid row (in pixels). */
929 int GetRowHeight() const { return m_lineHeight
; }
931 /** Returns currently selected property. */
932 wxPGProperty
* GetSelectedProperty() const { return GetSelection(); }
934 /** Returns current selection background colour. */
935 wxColour
GetSelectionBackgroundColour() const { return m_colSelBack
; }
937 /** Returns current selection text colour. */
938 wxColour
GetSelectionForegroundColour() const { return m_colSelFore
; }
940 /** Returns current splitter x position. */
941 int GetSplitterPosition() const
942 { return m_pState
->DoGetSplitterPosition(0); }
944 /** Returns wxTextCtrl active in currently selected property, if any. Takes
945 into account wxOwnerDrawnComboBox.
947 wxTextCtrl
* GetEditorTextCtrl() const;
949 wxPGValidationInfo
& GetValidationInfo()
951 return m_validationInfo
;
954 /** Returns current vertical spacing. */
955 int GetVerticalSpacing() const { return (int)m_vspacing
; }
958 Returns @true if a property editor control has focus.
960 bool IsEditorFocused() const;
962 /** Returns true if editor's value was marked modified.
964 bool IsEditorsValueModified() const
965 { return ( m_iFlags
& wxPG_FL_VALUE_MODIFIED
) ? true : false; }
968 Returns information about arbitrary position in the grid.
971 Coordinates in the virtual grid space. You may need to use
972 wxScrolledWindow::CalcScrolledPosition() for translating
973 wxPropertyGrid client coordinates into something this member
976 wxPropertyGridHitTestResult
HitTest( const wxPoint
& pt
) const;
978 /** Returns true if any property has been modified by the user. */
979 bool IsAnyModified() const { return (m_pState
->m_anyModified
>0); }
982 Returns true if updating is frozen (ie Freeze() called but not yet
985 bool IsFrozen() const { return (m_frozen
>0)?true:false; }
988 It is recommended that you call this function any time your code causes
989 wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle()
990 handler should be able to detect most changes, but it is not perfect.
993 New top-level parent that is about to be set. Old top-level parent
994 window should still exist as the current one.
996 @remarks This function is automatically called from wxPropertyGrid::
997 Reparent() and wxPropertyGridManager::Reparent(). You only
998 need to use it if you reparent wxPropertyGrid indirectly.
1000 void OnTLPChanging( wxWindow
* newTLP
);
1002 /** Redraws given property.
1004 virtual void RefreshProperty( wxPGProperty
* p
);
1006 /** Registers a new editor class.
1008 Pointer to the editor class instance that should be used.
1010 static wxPGEditor
* RegisterEditorClass( wxPGEditor
* editor
,
1011 bool noDefCheck
= false )
1013 return DoRegisterEditorClass(editor
, wxEmptyString
, noDefCheck
);
1016 static wxPGEditor
* DoRegisterEditorClass( wxPGEditor
* editorClass
,
1017 const wxString
& editorName
,
1018 bool noDefCheck
= false );
1020 /** Resets all colours to the original system values.
1022 void ResetColours();
1026 Editor widget is automatically created, but not focused unless focus is
1033 True if selection finished successfully. Usually only fails if
1034 current value in editor is not valid.
1036 @remarks In wxPropertyGrid 1.4, this member function used to generate
1037 wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer
1040 @remarks This clears any previous selection.
1042 bool SelectProperty( wxPGPropArg id
, bool focus
= false );
1045 Set entire new selection from given list of properties.
1047 void SetSelection( const wxArrayPGProperty
& newSelection
)
1049 DoSetSelection( newSelection
, wxPG_SEL_DONT_SEND_EVENT
);
1053 Adds given property into selection. If wxPG_EX_MULTIPLE_SELECTION
1054 extra style is not used, then this has same effect as
1055 calling SelectProperty().
1057 @remarks Multiple selection is not supported for categories. This
1058 means that if you have properties selected, you cannot
1059 add category to selection, and also if you have category
1060 selected, you cannot add other properties to selection.
1061 This member function will fail silently in these cases,
1062 even returning true.
1064 bool AddToSelection( wxPGPropArg id
)
1066 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
1067 return DoAddToSelection(p
, wxPG_SEL_DONT_SEND_EVENT
);
1071 Removes given property from selection. If property is not selected,
1072 an assertion failure will occur.
1074 bool RemoveFromSelection( wxPGPropArg id
)
1076 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
1077 return DoRemoveFromSelection(p
, wxPG_SEL_DONT_SEND_EVENT
);
1081 Makes given column editable by user.
1084 Using @false here will disable column from being editable.
1086 void MakeColumnEditable( unsigned int column
, bool editable
= true );
1089 Creates label editor wxTextCtrl for given column, for property
1090 that is currently selected. When multiple selection is
1091 enabled, this applies to whatever property GetSelection()
1095 Which column's label to edit. Note that you should not
1096 use value 1, which is reserved for property value
1099 @see EndLabelEdit(), MakeColumnEditable()
1101 void BeginLabelEdit( unsigned int column
= 0 )
1103 DoBeginLabelEdit(column
, wxPG_SEL_DONT_SEND_EVENT
);
1107 Destroys label editor wxTextCtrl, if any.
1110 Use @true (default) to store edited label text in
1113 @see BeginLabelEdit(), MakeColumnEditable()
1115 void EndLabelEdit( bool commit
= true )
1117 DoEndLabelEdit(commit
, wxPG_SEL_DONT_SEND_EVENT
);
1121 Returns currently active label editor, NULL if none.
1123 wxTextCtrl
* GetLabelEditor() const
1125 return m_labelEditor
;
1128 /** Sets category caption background colour. */
1129 void SetCaptionBackgroundColour(const wxColour
& col
);
1131 /** Sets category caption text colour. */
1132 void SetCaptionTextColour(const wxColour
& col
);
1134 /** Sets default cell background colour - applies to property cells.
1135 Note that appearance of editor widgets may not be affected.
1137 void SetCellBackgroundColour(const wxColour
& col
);
1139 /** Sets cell text colour for disabled properties.
1141 void SetCellDisabledTextColour(const wxColour
& col
);
1143 /** Sets default cell text colour - applies to property name and value text.
1144 Note that appearance of editor widgets may not be affected.
1146 void SetCellTextColour(const wxColour
& col
);
1148 /** Set number of columns (2 or more).
1150 void SetColumnCount( int colCount
)
1152 m_pState
->SetColumnCount(colCount
);
1157 Sets the 'current' category - Append will add non-category properties
1160 void SetCurrentCategory( wxPGPropArg id
)
1162 wxPG_PROP_ARG_CALL_PROLOG()
1163 wxPropertyCategory
* pc
= wxDynamicCast(p
, wxPropertyCategory
);
1165 m_pState
->m_currentCategory
= pc
;
1168 /** Sets colour of empty space below properties. */
1169 void SetEmptySpaceColour(const wxColour
& col
);
1171 /** Sets colour of lines between cells. */
1172 void SetLineColour(const wxColour
& col
);
1174 /** Sets background colour of margin. */
1175 void SetMarginColour(const wxColour
& col
);
1178 Sets selection background colour - applies to selected property name
1181 void SetSelectionBackgroundColour(const wxColour
& col
);
1184 Sets selection foreground colour - applies to selected property name
1187 void SetSelectionTextColour(const wxColour
& col
);
1189 /** Sets x coordinate of the splitter.
1191 Splitter position cannot exceed grid size, and therefore setting it
1192 during form creation may fail as initial grid size is often smaller
1193 than desired splitter position, especially when sizers are being used.
1195 void SetSplitterPosition( int newXPos
, int col
= 0 )
1197 DoSetSplitterPosition(newXPos
, col
, wxPG_SPLITTER_REFRESH
);
1201 Sets the property sorting function.
1204 The sorting function to be used. It should return a value greater
1205 than 0 if position of p1 is after p2. So, for instance, when
1206 comparing property names, you can use following implementation:
1209 int MyPropertySortFunction(wxPropertyGrid* propGrid,
1213 return p1->GetBaseName().compare( p2->GetBaseName() );
1218 Default property sort function sorts properties by their labels
1219 (case-insensitively).
1221 @see GetSortFunction, wxPropertyGridInterface::Sort,
1222 wxPropertyGridInterface::SortChildren
1224 void SetSortFunction( wxPGSortCallback sortFunction
)
1226 m_sortFunction
= sortFunction
;
1230 Returns the property sort function (default is @NULL).
1232 @see SetSortFunction
1234 wxPGSortCallback
GetSortFunction() const
1236 return m_sortFunction
;
1240 Sets appearance of value cells representing an unspecified property
1241 value. Default appearance is blank.
1243 @remarks If you set the unspecified value to have any
1244 textual representation, then that will override
1245 "InlineHelp" attribute.
1247 @see wxPGProperty::SetValueToUnspecified(),
1248 wxPGProperty::IsValueUnspecified()
1250 void SetUnspecifiedValueAppearance( const wxPGCell
& cell
)
1252 m_unspecifiedAppearance
= m_propertyDefaultCell
;
1253 m_unspecifiedAppearance
.MergeFrom(cell
);
1257 Returns current appearance of unspecified value cells.
1259 @see SetUnspecifiedValueAppearance()
1261 const wxPGCell
& GetUnspecifiedValueAppearance() const
1263 return m_unspecifiedAppearance
;
1267 Returns (visual) text representation of the unspecified
1270 @param argFlags For internal use only.
1272 wxString
GetUnspecifiedValueText( int argFlags
= 0 ) const;
1274 /** Set virtual width for this particular page. Width -1 indicates that the
1275 virtual width should be disabled. */
1276 void SetVirtualWidth( int width
);
1279 Moves splitter as left as possible, while still allowing all
1280 labels to be shown in full.
1282 @param privateChildrenToo
1283 If @false, will still allow private children to be cropped.
1285 void SetSplitterLeft( bool privateChildrenToo
= false )
1287 m_pState
->SetSplitterLeft(privateChildrenToo
);
1290 /** Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
1291 height. Value of 2 should be default on most platforms.
1293 void SetVerticalSpacing( int vspacing
)
1295 m_vspacing
= (unsigned char)vspacing
;
1296 CalculateFontAndBitmapStuff( vspacing
);
1297 if ( !m_pState
->m_itemsAdded
) Refresh();
1300 /** Shows an brief error message that is related to a property. */
1301 void ShowPropertyError( wxPGPropArg id
, const wxString
& msg
)
1303 wxPG_PROP_ARG_CALL_PROLOG()
1304 DoShowPropertyError(p
, msg
);
1307 /////////////////////////////////////////////////////////////////
1309 // Following methods do not need to be (currently) documented
1311 /////////////////////////////////////////////////////////////////
1313 bool HasVirtualWidth() const
1314 { return (m_iFlags
& wxPG_FL_HAS_VIRTUAL_WIDTH
) ? true : false; }
1316 const wxPGCommonValue
* GetCommonValue( unsigned int i
) const
1318 return (wxPGCommonValue
*) m_commonValues
[i
];
1321 /** Returns number of common values.
1323 unsigned int GetCommonValueCount() const
1325 return (unsigned int) m_commonValues
.size();
1328 /** Returns label of given common value.
1330 wxString
GetCommonValueLabel( unsigned int i
) const
1332 wxASSERT( GetCommonValue(i
) );
1333 return GetCommonValue(i
)->GetLabel();
1337 Returns index of common value that will truly change value to
1340 int GetUnspecifiedCommonValue() const { return m_cvUnspecified
; }
1342 /** Set index of common value that will truly change value to unspecified.
1343 Using -1 will set none to have such effect.
1346 void SetUnspecifiedCommonValue( int index
) { m_cvUnspecified
= index
; }
1349 Shortcut for creating dialog-caller button. Used, for example, by
1352 This should only be called by properties.
1354 wxWindow
* GenerateEditorButton( const wxPoint
& pos
, const wxSize
& sz
);
1356 /** Fixes position of wxTextCtrl-like control (wxSpinCtrl usually
1357 fits as one). Call after control has been created (but before
1360 void FixPosForTextCtrl( wxWindow
* ctrl
,
1361 unsigned int forColumn
= 1,
1362 const wxPoint
& offset
= wxPoint(0, 0) );
1364 /** Shortcut for creating text editor widget.
1366 Same as pos given for CreateEditor.
1368 Same as sz given for CreateEditor.
1370 Initial text for wxTextCtrl.
1372 If right-side control, such as button, also created, then create it
1373 first and pass it as this parameter.
1375 Extra style flags to pass for wxTextCtrl.
1377 Note that this should generally be called only by new classes derived
1380 wxWindow
* GenerateEditorTextCtrl( const wxPoint
& pos
,
1382 const wxString
& value
,
1383 wxWindow
* secondary
,
1386 unsigned int forColumn
= 1 );
1388 /* Generates both textctrl and button.
1390 wxWindow
* GenerateEditorTextCtrlAndButton( const wxPoint
& pos
,
1391 const wxSize
& sz
, wxWindow
** psecondary
, int limited_editing
,
1392 wxPGProperty
* property
);
1394 /** Generates position for a widget editor dialog box.
1396 Property for which dialog is positioned.
1398 Known or over-approximated size of the dialog.
1400 Position for dialog.
1402 wxPoint
GetGoodEditorDialogPosition( wxPGProperty
* p
,
1405 // Converts escape sequences in src_str to newlines,
1406 // tabs, etc. and copies result to dst_str.
1407 static wxString
& ExpandEscapeSequences( wxString
& dst_str
,
1408 wxString
& src_str
);
1410 // Converts newlines, tabs, etc. in src_str to escape
1411 // sequences, and copies result to dst_str.
1412 static wxString
& CreateEscapeSequences( wxString
& dst_str
,
1413 wxString
& src_str
);
1416 Returns rectangle that fully contains properties between and including
1419 wxRect
GetPropertyRect( const wxPGProperty
* p1
,
1420 const wxPGProperty
* p2
) const;
1422 /** Returns pointer to current active primary editor control (NULL if none).
1424 wxWindow
* GetEditorControl() const;
1426 wxWindow
* GetPrimaryEditor() const
1428 return GetEditorControl();
1432 Returns pointer to current active secondary editor control (NULL if
1435 wxWindow
* GetEditorControlSecondary() const
1437 return m_wndEditor2
;
1441 Refreshes any active editor control.
1443 void RefreshEditor();
1445 // Events from editor controls are forward to this function
1446 void HandleCustomEditorEvent( wxEvent
&event
);
1449 Generates contents for string dst based on the contents of
1452 Format will be "(preDelim)str1(postDelim) (preDelim)str2(postDelim) and
1453 so on. Set flags to 1 inorder to convert backslashes to double-back-
1454 slashes and "(preDelims)"'s to "(preDelims)".
1456 static void ArrayStringToString( wxString
& dst
, const wxArrayString
& src
,
1457 wxChar preDelim
, wxChar postDelim
,
1460 // Mostly useful for page switching.
1461 void SwitchState( wxPropertyGridPageState
* pNewState
);
1463 long GetInternalFlags() const { return m_iFlags
; }
1464 bool HasInternalFlag( long flag
) const
1465 { return (m_iFlags
& flag
) ? true : false; }
1466 void SetInternalFlag( long flag
) { m_iFlags
|= flag
; }
1467 void ClearInternalFlag( long flag
) { m_iFlags
&= ~(flag
); }
1468 void IncFrozen() { m_frozen
++; }
1469 void DecFrozen() { m_frozen
--; }
1471 void OnComboItemPaint( const wxPGComboBox
* pCb
,
1477 /** Standardized double-to-string conversion.
1479 static void DoubleToString( wxString
& target
,
1483 wxString
* precTemplate
);
1486 Call this from wxPGProperty::OnEvent() to cause property value to be
1487 changed after the function returns (with true as return value).
1488 ValueChangeInEvent() must be used if you wish the application to be
1489 able to use wxEVT_PG_CHANGING to potentially veto the given value.
1491 void ValueChangeInEvent( wxVariant variant
)
1493 m_changeInEventValue
= variant
;
1494 m_iFlags
|= wxPG_FL_VALUE_CHANGE_IN_EVENT
;
1498 You can use this member function, for instance, to detect in
1499 wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was
1500 already called in wxPGEditor::OnEvent(). It really only detects
1501 if was value was changed using wxPGProperty::SetValueInEvent(), which
1502 is usually used when a 'picker' dialog is displayed. If value was
1503 written by "normal means" in wxPGProperty::StringToValue() or
1504 IntToValue(), then this function will return false (on the other hand,
1505 wxPGProperty::OnEvent() is not even called in those cases).
1507 bool WasValueChangedInEvent() const
1509 return (m_iFlags
& wxPG_FL_VALUE_CHANGE_IN_EVENT
) ? true : false;
1512 /** Returns true if given event is from first of an array of buttons
1513 (as can be in case when wxPGMultiButton is used).
1515 bool IsMainButtonEvent( const wxEvent
& event
)
1517 return (event
.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED
)
1518 && (m_wndSecId
== event
.GetId());
1521 /** Pending value is expected to be passed in PerformValidation().
1523 virtual bool DoPropertyChanged( wxPGProperty
* p
,
1524 unsigned int selFlags
= 0 );
1526 /** Called when validation for given property fails.
1528 Value which failed in validation.
1530 Return true if user is allowed to change to another property even
1531 if current has invalid value.
1533 To add your own validation failure behavior, override
1534 wxPropertyGrid::DoOnValidationFailure().
1536 bool OnValidationFailure( wxPGProperty
* property
,
1537 wxVariant
& invalidValue
);
1539 /** Called to indicate property and editor has valid value now.
1541 void OnValidationFailureReset( wxPGProperty
* property
)
1543 if ( property
&& property
->HasFlag(wxPG_PROP_INVALID_VALUE
) )
1545 DoOnValidationFailureReset(property
);
1546 property
->ClearFlag(wxPG_PROP_INVALID_VALUE
);
1548 m_validationInfo
.m_failureMessage
.clear();
1551 /** Override in derived class to display error messages in custom manner
1552 (these message usually only result from validation failure).
1554 virtual void DoShowPropertyError( wxPGProperty
* property
,
1555 const wxString
& msg
);
1557 /** Override to customize property validation failure behavior.
1559 Value which failed in validation.
1561 Return true if user is allowed to change to another property even
1562 if current has invalid value.
1564 virtual bool DoOnValidationFailure( wxPGProperty
* property
,
1565 wxVariant
& invalidValue
);
1567 /** Override to customize resetting of property validation failure status.
1569 Property is guaranteed to have flag wxPG_PROP_INVALID_VALUE set.
1571 virtual void DoOnValidationFailureReset( wxPGProperty
* property
);
1573 int GetSpacingY() const { return m_spacingy
; }
1576 Must be called in wxPGEditor::CreateControls() if primary editor window
1577 is wxTextCtrl, just before textctrl is created.
1579 Initial text value of created wxTextCtrl.
1581 void SetupTextCtrlValue( const wxString text
) { m_prevTcValue
= text
; }
1584 Unfocuses or closes editor if one was open, but does not deselect
1587 bool UnfocusEditor();
1589 virtual void SetWindowStyleFlag( long style
);
1591 void DrawItems( const wxPGProperty
* p1
, const wxPGProperty
* p2
);
1593 void DrawItem( wxPGProperty
* p
)
1598 virtual void DrawItemAndChildren( wxPGProperty
* p
);
1601 Draws item, children, and consequtive parents as long as category is
1604 void DrawItemAndValueRelated( wxPGProperty
* p
);
1609 wxPropertyGridPageState used by the grid is created here.
1611 If grid is used in wxPropertyGridManager, there is no point overriding
1612 this - instead, set custom wxPropertyGridPage classes.
1614 virtual wxPropertyGridPageState
* CreateState() const;
1616 enum PerformValidationFlags
1618 SendEvtChanging
= 0x0001,
1619 IsStandaloneValidation
= 0x0002 // Not called in response to event
1623 Runs all validation functionality (includes sending wxEVT_PG_CHANGING).
1624 Returns true if all tests passed. Implement in derived class to
1625 add additional validation behavior.
1627 virtual bool PerformValidation( wxPGProperty
* p
,
1628 wxVariant
& pendingValue
,
1629 int flags
= SendEvtChanging
);
1633 // Control font changer helper.
1634 void SetCurControlBoldFont();
1636 wxPGCell
& GetPropertyDefaultCell()
1638 return m_propertyDefaultCell
;
1641 wxPGCell
& GetCategoryDefaultCell()
1643 return m_categoryDefaultCell
;
1647 // Public methods for semi-public use
1649 bool DoSelectProperty( wxPGProperty
* p
, unsigned int flags
= 0 );
1651 // Overridden functions.
1652 virtual bool Destroy();
1653 // Returns property at given y coordinate (relative to grid's top left).
1654 wxPGProperty
* GetItemAtY( int y
) const { return DoGetItemAtY(y
); }
1656 virtual void Refresh( bool eraseBackground
= true,
1657 const wxRect
*rect
= (const wxRect
*) NULL
);
1658 virtual bool SetFont( const wxFont
& font
);
1659 #if wxPG_SUPPORT_TOOLTIPS
1660 void SetToolTip( const wxString
& tipString
);
1662 virtual void Freeze();
1663 virtual void SetExtraStyle( long exStyle
);
1664 virtual void Thaw();
1665 virtual bool Reparent( wxWindowBase
*newParent
);
1668 virtual wxSize
DoGetBestSize() const;
1670 #ifndef wxPG_ICON_WIDTH
1671 wxBitmap
*m_expandbmp
, *m_collbmp
;
1674 wxCursor
*m_cursorSizeWE
;
1676 /** wxWindow pointers to editor control(s). */
1677 wxWindow
*m_wndEditor
;
1678 wxWindow
*m_wndEditor2
;
1680 #if wxPG_DOUBLE_BUFFER
1681 wxBitmap
*m_doubleBuffer
;
1684 /** Local time ms when control was created. */
1685 wxLongLong m_timeCreated
;
1687 /** wxPGProperty::OnEvent can change value by setting this. */
1688 wxVariant m_changeInEventValue
;
1690 /** Id of m_wndEditor2, or its first child, if any. */
1693 /** Extra Y spacing between the items. */
1696 /** Control client area width; updated on resize. */
1699 /** Control client area height; updated on resize. */
1702 /** Current non-client width (needed when auto-centering). */
1705 /** Non-client width (auto-centering helper). */
1708 /** Previously recorded scroll start position. */
1712 The gutter spacing in front and back of the image.
1713 This determines the amount of spacing in front of each item
1717 /** Includes separator line. */
1720 /** Gutter*2 + image width. */
1723 // y spacing for expand/collapse button.
1724 int m_buttonSpacingY
;
1726 /** Extra margin for expanded sub-group items. */
1727 int m_subgroup_extramargin
;
1730 The image width of the [+] icon.
1732 This is also calculated in the gutter
1736 #ifndef wxPG_ICON_WIDTH
1739 The image height of the [+] icon.
1741 This is calculated as minimal size and to align
1746 /** Current cursor id. */
1750 This captionFont is made equal to the font of the wxScrolledWindow.
1752 As extra the bold face is set on it when this is wanted by the user
1755 wxFont m_captionFont
;
1757 int m_fontHeight
; // Height of the font.
1759 /** m_splitterx when drag began. */
1760 int m_startingSplitterX
;
1763 Index to splitter currently being dragged (0=one after the first
1766 int m_draggedSplitter
;
1768 /** Changed property, calculated in PerformValidation(). */
1769 wxPGProperty
* m_chgInfo_changedProperty
;
1772 Lowest property for which editing happened, but which does not have
1775 wxPGProperty
* m_chgInfo_baseChangedProperty
;
1777 /** Changed property value, calculated in PerformValidation(). */
1778 wxVariant m_chgInfo_pendingValue
;
1780 /** Passed to SetValue. */
1781 wxVariant m_chgInfo_valueList
;
1783 /** Validation information. */
1784 wxPGValidationInfo m_validationInfo
;
1786 /** Actions and keys that trigger them. */
1787 wxPGHashMapI2I m_actionTriggers
;
1789 /** Appearance of currently active editor. */
1790 wxPGCell m_editorAppearance
;
1792 /** Appearance of a unspecified value cell. */
1793 wxPGCell m_unspecifiedAppearance
;
1799 /** Bits are used to indicate which colours are customized. */
1800 unsigned short m_coloursCustomized
;
1802 /** x - m_splitterx. */
1803 signed char m_dragOffset
;
1805 /** 0 = not dragging, 1 = drag just started, 2 = drag in progress */
1806 unsigned char m_dragStatus
;
1808 /** 0 = margin, 1 = label, 2 = value. */
1809 unsigned char m_mouseSide
;
1811 /** True when editor control is focused. */
1812 unsigned char m_editorFocused
;
1814 /** 1 if m_latsCaption is also the bottommost caption. */
1815 //unsigned char m_lastCaptionBottomnest;
1817 /** Set to 1 when graphics frozen. */
1818 unsigned char m_frozen
;
1820 unsigned char m_vspacing
;
1822 // Used to track when Alt/Ctrl+Key was consumed.
1823 unsigned char m_keyComboConsumed
;
1825 /** 1 if in DoPropertyChanged() */
1826 unsigned char m_inDoPropertyChanged
;
1828 /** 1 if in CommitChangesFromEditor() */
1829 unsigned char m_inCommitChangesFromEditor
;
1831 /** 1 if in DoSelectProperty() */
1832 unsigned char m_inDoSelectProperty
;
1834 wxPGVFBFlags m_permanentValidationFailureBehavior
; // Set by app
1836 /** Internal flags - see wxPG_FL_XXX constants. */
1839 /** When drawing next time, clear this many item slots at the end. */
1840 int m_clearThisMany
;
1842 // Mouse is hovering over this column (index)
1843 unsigned int m_colHover
;
1845 // pointer to property that has mouse hovering
1846 wxPGProperty
* m_propHover
;
1848 // Active label editor
1849 wxTextCtrl
* m_labelEditor
;
1851 // For which property the label editor is active
1852 wxPGProperty
* m_labelEditorProperty
;
1854 // EventObject for wxPropertyGridEvents
1855 wxWindow
* m_eventObject
;
1857 // What (global) window is currently focused (needed to resolve event
1859 wxWindow
* m_curFocused
;
1861 // Event currently being sent - NULL if none at the moment
1862 wxPropertyGridEvent
* m_processedEvent
;
1864 // Last known top-level parent
1867 // Last closed top-level parent
1868 wxWindow
* m_tlpClosed
;
1870 // Local time ms when tlp was closed.
1871 wxLongLong m_tlpClosedTime
;
1874 wxPGSortCallback m_sortFunction
;
1876 // y coordinate of property that mouse hovering
1879 // Which column's editor is selected (usually 1)?
1880 unsigned int m_selColumn
;
1882 // x relative to splitter (needed for resize).
1885 // lines between cells
1887 // property labels and values are written in this colour
1888 wxColour m_colPropFore
;
1889 // or with this colour when disabled
1890 wxColour m_colDisPropFore
;
1891 // background for m_colPropFore
1892 wxColour m_colPropBack
;
1893 // text color for captions
1894 wxColour m_colCapFore
;
1895 // background color for captions
1896 wxColour m_colCapBack
;
1897 // foreground for selected property
1898 wxColour m_colSelFore
;
1899 // background for selected property (actually use background color when
1900 // control out-of-focus)
1901 wxColour m_colSelBack
;
1902 // background colour for margin
1903 wxColour m_colMargin
;
1904 // background colour for empty space below the grid
1905 wxColour m_colEmptySpace
;
1907 // Default property colours
1908 wxPGCell m_propertyDefaultCell
;
1910 // Default property category
1911 wxPGCell m_categoryDefaultCell
;
1913 // Backup of selected property's cells
1914 wxVector
<wxPGCell
> m_propCellsBackup
;
1916 // NB: These *cannot* be moved to globals.
1918 // labels when properties use common values
1919 wxVector
<wxPGCommonValue
*> m_commonValues
;
1921 // array of live events
1922 wxVector
<wxPropertyGridEvent
*> m_liveEvents
;
1924 // Which cv selection really sets value to unspecified?
1925 int m_cvUnspecified
;
1927 // Used to skip excess text editor events
1928 wxString m_prevTcValue
;
1932 // Sets some members to defaults (called constructors).
1935 // Initializes some members (called by Create and complex constructor).
1938 void OnPaint(wxPaintEvent
&event
);
1940 // main event receivers
1941 void OnMouseMove( wxMouseEvent
&event
);
1942 void OnMouseClick( wxMouseEvent
&event
);
1943 void OnMouseRightClick( wxMouseEvent
&event
);
1944 void OnMouseDoubleClick( wxMouseEvent
&event
);
1945 void OnMouseUp( wxMouseEvent
&event
);
1946 void OnKey( wxKeyEvent
&event
);
1947 void OnResize( wxSizeEvent
&event
);
1950 bool HandleMouseMove( int x
, unsigned int y
, wxMouseEvent
&event
);
1951 bool HandleMouseClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1952 bool HandleMouseRightClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1953 bool HandleMouseDoubleClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1954 bool HandleMouseUp( int x
, unsigned int y
, wxMouseEvent
&event
);
1955 void HandleKeyEvent( wxKeyEvent
&event
, bool fromChild
);
1957 void OnMouseEntry( wxMouseEvent
&event
);
1959 void OnIdle( wxIdleEvent
&event
);
1960 void OnFocusEvent( wxFocusEvent
&event
);
1961 void OnChildFocusEvent( wxChildFocusEvent
& event
);
1963 bool OnMouseCommon( wxMouseEvent
&event
, int* px
, int *py
);
1964 bool OnMouseChildCommon( wxMouseEvent
&event
, int* px
, int *py
);
1966 // sub-control event handlers
1967 void OnMouseClickChild( wxMouseEvent
&event
);
1968 void OnMouseRightClickChild( wxMouseEvent
&event
);
1969 void OnMouseMoveChild( wxMouseEvent
&event
);
1970 void OnMouseUpChild( wxMouseEvent
&event
);
1971 void OnChildKeyDown( wxKeyEvent
&event
);
1973 void OnCaptureChange( wxMouseCaptureChangedEvent
&event
);
1975 void OnScrollEvent( wxScrollWinEvent
&event
);
1977 void OnSysColourChanged( wxSysColourChangedEvent
&event
);
1979 void OnTLPClose( wxCloseEvent
& event
);
1983 bool AddToSelectionFromInputEvent( wxPGProperty
* prop
,
1984 unsigned int colIndex
,
1985 wxMouseEvent
* event
= NULL
,
1989 Adjust the centering of the bitmap icons (collapse / expand) when the
1990 caption font changes.
1992 They need to be centered in the middle of the font, so a bit of deltaY
1993 adjustment is needed. On entry, m_captionFont must be set to window
1994 font. It will be modified properly.
1996 void CalculateFontAndBitmapStuff( int vspacing
);
1998 wxRect
GetEditorWidgetRect( wxPGProperty
* p
, int column
) const;
2000 void CorrectEditorWidgetSizeX();
2002 /** Called in RecalculateVirtualSize() to reposition control
2003 on virtual height changes.
2005 void CorrectEditorWidgetPosY();
2007 int DoDrawItems( wxDC
& dc
,
2008 const wxRect
* drawRect
,
2009 bool isBuffered
) const;
2011 /** Draws an expand/collapse (ie. +/-) button.
2013 virtual void DrawExpanderButton( wxDC
& dc
, const wxRect
& rect
,
2014 wxPGProperty
* property
) const;
2016 /** Draws items from topitemy to bottomitemy */
2017 void DrawItems( wxDC
& dc
,
2018 unsigned int topItemY
,
2019 unsigned int bottomItemY
,
2020 const wxRect
* drawRect
= NULL
);
2022 // Translate wxKeyEvent to wxPG_ACTION_XXX
2023 int KeyEventToActions(wxKeyEvent
&event
, int* pSecond
) const;
2025 int KeyEventToAction(wxKeyEvent
&event
) const
2027 return KeyEventToActions(event
, NULL
);
2030 void ImprovedClientToScreen( int* px
, int* py
);
2032 // Called by focus event handlers. newFocused is the window that becomes
2034 void HandleFocusChange( wxWindow
* newFocused
);
2036 /** Reloads all non-customized colours from system settings. */
2037 void RegainColours();
2039 bool DoEditorValidate();
2041 // Similar to DoSelectProperty() but also works on columns
2042 // other than 1. Does not active editor if column is not
2044 bool DoSelectAndEdit( wxPGProperty
* prop
,
2045 unsigned int colIndex
,
2046 unsigned int selFlags
);
2048 void DoSetSelection( const wxArrayPGProperty
& newSelection
,
2051 void DoSetSplitterPosition( int newxpos
,
2052 int splitterIndex
= 0,
2053 int flags
= wxPG_SPLITTER_REFRESH
);
2055 bool DoAddToSelection( wxPGProperty
* prop
,
2058 bool DoRemoveFromSelection( wxPGProperty
* prop
,
2061 void DoBeginLabelEdit( unsigned int colIndex
, int selFlags
= 0 );
2062 void DoEndLabelEdit( bool commit
, int selFlags
= 0 );
2063 void OnLabelEditorEnterPress( wxCommandEvent
& event
);
2064 void OnLabelEditorKeyPress( wxKeyEvent
& event
);
2066 wxPGProperty
* DoGetItemAtY( int y
) const;
2068 void DestroyEditorWnd( wxWindow
* wnd
);
2071 virtual bool DoExpand( wxPGProperty
* p
, bool sendEvent
= false );
2073 virtual bool DoCollapse( wxPGProperty
* p
, bool sendEvent
= false );
2075 // Returns nearest paint visible property (such that will be painted unless
2076 // window is scrolled or resized). If given property is paint visible, then
2077 // it itself will be returned.
2078 wxPGProperty
* GetNearestPaintVisible( wxPGProperty
* p
) const;
2080 static void RegisterDefaultEditors();
2082 // Sets up basic event handling for child control
2083 void SetupChildEventHandling( wxWindow
* wnd
);
2085 void CustomSetCursor( int type
, bool override
= false );
2088 Repositions scrollbar and underlying panel according to changed virtual
2091 void RecalculateVirtualSize( int forceXPos
= -1 );
2093 void SetEditorAppearance( const wxPGCell
& cell
,
2094 bool unspecified
= false );
2096 void ResetEditorAppearance()
2099 cell
.SetEmptyData();
2100 SetEditorAppearance(cell
, false);
2103 void PrepareAfterItemsAdded();
2106 Send event from the property grid.
2108 Omit the wxPG_SEL_NOVALIDATE flag to allow vetoing the event
2110 bool SendEvent( int eventType
, wxPGProperty
* p
,
2111 wxVariant
* pValue
= NULL
,
2112 unsigned int selFlags
= wxPG_SEL_NOVALIDATE
,
2113 unsigned int column
= 1 );
2115 void SetFocusOnCanvas();
2117 bool DoHideProperty( wxPGProperty
* p
, bool hide
, int flags
);
2121 bool ButtonTriggerKeyTest( int action
, wxKeyEvent
& event
);
2123 DECLARE_EVENT_TABLE()
2126 // -----------------------------------------------------------------------
2128 // Bunch of inlines that need to resolved after all classes have been defined.
2131 inline bool wxPropertyGridPageState::IsDisplayed() const
2133 return ( this == m_pPropGrid
->GetState() );
2136 inline unsigned int wxPropertyGridPageState::GetActualVirtualHeight() const
2138 return DoGetRoot()->GetChildrenHeight(GetGrid()->GetRowHeight());
2141 inline wxString
wxPGProperty::GetHintText() const
2143 wxVariant vHintText
= GetAttribute(wxPGGlobalVars
->m_strHint
);
2145 #if wxPG_COMPATIBILITY_1_4
2146 // Try the old, deprecated "InlineHelp"
2147 if ( vHintText
.IsNull() )
2148 vHintText
= GetAttribute(wxPGGlobalVars
->m_strInlineHelp
);
2151 if ( !vHintText
.IsNull() )
2152 return vHintText
.GetString();
2154 return wxEmptyString
;
2157 inline int wxPGProperty::GetDisplayedCommonValueCount() const
2159 if ( HasFlag(wxPG_PROP_USES_COMMON_VALUE
) )
2161 wxPropertyGrid
* pg
= GetGrid();
2163 return (int) pg
->GetCommonValueCount();
2168 inline void wxPGProperty::SetDefaultValue( wxVariant
& value
)
2170 SetAttribute(wxPG_ATTR_DEFAULT_VALUE
, value
);
2173 inline void wxPGProperty::SetEditor( const wxString
& editorName
)
2175 m_customEditor
= wxPropertyGridInterface::GetEditorByName(editorName
);
2178 inline bool wxPGProperty::Hide( bool hide
, int flags
)
2180 return GetGrid()->HideProperty(this, hide
, flags
);
2183 inline bool wxPGProperty::SetMaxLength( int maxLen
)
2185 return GetGrid()->SetPropertyMaxLength(this,maxLen
);
2188 // -----------------------------------------------------------------------
2190 #define wxPG_BASE_EVT_PRE_ID 1775
2194 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_SELECTED
, wxPropertyGridEvent
);
2195 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_CHANGING
, wxPropertyGridEvent
);
2196 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_CHANGED
, wxPropertyGridEvent
);
2197 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_HIGHLIGHTED
, wxPropertyGridEvent
);
2198 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_RIGHT_CLICK
, wxPropertyGridEvent
);
2199 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_PAGE_CHANGED
, wxPropertyGridEvent
);
2200 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_ITEM_COLLAPSED
, wxPropertyGridEvent
);
2201 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_ITEM_EXPANDED
, wxPropertyGridEvent
);
2202 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_DOUBLE_CLICK
, wxPropertyGridEvent
);
2203 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
,
2204 wxEVT_PG_LABEL_EDIT_BEGIN
, wxPropertyGridEvent
);
2205 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
,
2206 wxEVT_PG_LABEL_EDIT_ENDING
, wxPropertyGridEvent
);
2207 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
,
2208 wxEVT_PG_COL_BEGIN_DRAG
, wxPropertyGridEvent
);
2209 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
,
2210 wxEVT_PG_COL_DRAGGING
, wxPropertyGridEvent
);
2211 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
,
2212 wxEVT_PG_COL_END_DRAG
, wxPropertyGridEvent
);
2216 wxEVT_PG_SELECTED
= wxPG_BASE_EVT_PRE_ID
,
2219 wxEVT_PG_HIGHLIGHTED
,
2220 wxEVT_PG_RIGHT_CLICK
,
2221 wxEVT_PG_PAGE_CHANGED
,
2222 wxEVT_PG_ITEM_COLLAPSED
,
2223 wxEVT_PG_ITEM_EXPANDED
,
2224 wxEVT_PG_DOUBLE_CLICK
,
2225 wxEVT_PG_LABEL_EDIT_BEGIN
,
2226 wxEVT_PG_LABEL_EDIT_ENDING
,
2227 wxEVT_PG_COL_BEGIN_DRAG
,
2228 wxEVT_PG_COL_DRAGGING
,
2229 wxEVT_PG_COL_END_DRAG
2234 #define wxPG_BASE_EVT_TYPE wxEVT_PG_SELECTED
2235 #define wxPG_MAX_EVT_TYPE (wxPG_BASE_EVT_TYPE+30)
2239 typedef void (wxEvtHandler::*wxPropertyGridEventFunction
)(wxPropertyGridEvent
&);
2241 #define EVT_PG_SELECTED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_SELECTED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2242 #define EVT_PG_CHANGING(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGING, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2243 #define EVT_PG_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2244 #define EVT_PG_HIGHLIGHTED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_HIGHLIGHTED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2245 #define EVT_PG_RIGHT_CLICK(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_RIGHT_CLICK, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2246 #define EVT_PG_DOUBLE_CLICK(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_DOUBLE_CLICK, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2247 #define EVT_PG_PAGE_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_PAGE_CHANGED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2248 #define EVT_PG_ITEM_COLLAPSED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_COLLAPSED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2249 #define EVT_PG_ITEM_EXPANDED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_EXPANDED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2250 #define EVT_PG_LABEL_EDIT_BEGIN(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_LABEL_EDIT_BEGIN, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2251 #define EVT_PG_LABEL_EDIT_ENDING(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_LABEL_EDIT_ENDING, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2252 #define EVT_PG_COL_BEGIN_DRAG(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_COL_BEGIN_DRAG, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2253 #define EVT_PG_COL_DRAGGING(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_COL_DRAGGING, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2254 #define EVT_PG_COL_END_DRAG(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_COL_END_DRAG, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2256 #define wxPropertyGridEventHandler(fn) \
2257 wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn )
2262 /** @class wxPropertyGridEvent
2264 A propertygrid event holds information about events associated with
2265 wxPropertyGrid objects.
2267 @library{wxpropgrid}
2270 class WXDLLIMPEXP_PROPGRID wxPropertyGridEvent
: public wxCommandEvent
2275 wxPropertyGridEvent(wxEventType commandType
=0, int id
=0);
2277 /** Copy constructor. */
2278 wxPropertyGridEvent(const wxPropertyGridEvent
& event
);
2281 ~wxPropertyGridEvent();
2284 virtual wxEvent
* Clone() const;
2287 Returns the column index associated with this event.
2288 For the column dragging events, it is the column to the left
2289 of the splitter being dragged
2291 unsigned int GetColumn() const
2296 wxPGProperty
* GetMainParent() const
2298 wxASSERT(m_property
);
2299 return m_property
->GetMainParent();
2302 /** Returns id of associated property. */
2303 wxPGProperty
* GetProperty() const
2308 wxPGValidationInfo
& GetValidationInfo()
2310 wxASSERT(m_validationInfo
);
2311 return *m_validationInfo
;
2314 /** Returns true if you can veto the action that the event is signaling.
2316 bool CanVeto() const { return m_canVeto
; }
2319 Call this from your event handler to veto action that the event is
2322 You can only veto a shutdown if wxPropertyGridEvent::CanVeto returns
2325 Currently only wxEVT_PG_CHANGING supports vetoing.
2327 void Veto( bool veto
= true ) { m_wasVetoed
= veto
; }
2330 Returns name of the associated property.
2332 @remarks Property name is stored in event, so it remains
2333 accessible even after the associated property or
2334 the property grid has been deleted.
2336 wxString
GetPropertyName() const
2338 return m_propertyName
;
2342 Returns value of the associated property. Works for all event
2343 types, but for wxEVT_PG_CHANGING this member function returns
2344 the value that is pending, so you can call Veto() if the
2345 value is not satisfactory.
2347 @remarks Property value is stored in event, so it remains
2348 accessible even after the associated property or
2349 the property grid has been deleted.
2351 wxVariant
GetPropertyValue() const
2353 if ( m_validationInfo
)
2354 return m_validationInfo
->GetValue();
2359 Returns value of the associated property.
2361 @see GetPropertyValue
2363 wxVariant
GetValue() const
2365 return GetPropertyValue();
2369 Set override validation failure behavior.
2371 Only effective if Veto was also called, and only allowed if event type
2372 is wxEVT_PG_CHANGING.
2374 void SetValidationFailureBehavior( wxPGVFBFlags flags
)
2376 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2377 m_validationInfo
->SetFailureBehavior( flags
);
2380 /** Sets custom failure message for this time only. Only applies if
2381 wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
2383 void SetValidationFailureMessage( const wxString
& message
)
2385 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2386 m_validationInfo
->SetFailureMessage( message
);
2389 wxPGVFBFlags
GetValidationFailureBehavior() const
2391 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2392 return m_validationInfo
->GetFailureBehavior();
2395 void SetColumn( unsigned int column
)
2400 void SetCanVeto( bool canVeto
) { m_canVeto
= canVeto
; }
2401 bool WasVetoed() const { return m_wasVetoed
; }
2403 /** Changes the associated property. */
2404 void SetProperty( wxPGProperty
* p
)
2408 m_propertyName
= p
->GetName();
2411 void SetPropertyValue( wxVariant value
)
2416 void SetPropertyGrid( wxPropertyGrid
* pg
)
2419 OnPropertyGridSet();
2422 void SetupValidationInfo()
2425 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2426 m_validationInfo
= &m_pg
->GetValidationInfo();
2427 m_value
= m_validationInfo
->GetValue();
2432 void OnPropertyGridSet();
2433 DECLARE_DYNAMIC_CLASS(wxPropertyGridEvent
)
2435 wxPGProperty
* m_property
;
2436 wxPropertyGrid
* m_pg
;
2437 wxPGValidationInfo
* m_validationInfo
;
2439 wxString m_propertyName
;
2442 unsigned int m_column
;
2449 // -----------------------------------------------------------------------
2451 /** @class wxPropertyGridPopulator
2453 Allows populating wxPropertyGrid from arbitrary text source.
2455 class WXDLLIMPEXP_PROPGRID wxPropertyGridPopulator
2458 /** Default constructor.
2460 wxPropertyGridPopulator();
2463 virtual ~wxPropertyGridPopulator();
2465 void SetState( wxPropertyGridPageState
* state
);
2467 void SetGrid( wxPropertyGrid
* pg
);
2469 /** Appends a new property under bottommost parent.
2471 Property class as string.
2473 wxPGProperty
* Add( const wxString
& propClass
,
2474 const wxString
& propLabel
,
2475 const wxString
& propName
,
2476 const wxString
* propValue
,
2477 wxPGChoices
* pChoices
= NULL
);
2480 Pushes property to the back of parent array (ie it becomes bottommost
2481 parent), and starts scanning/adding children for it.
2483 When finished, parent array is returned to the original state.
2485 void AddChildren( wxPGProperty
* property
);
2487 /** Adds attribute to the bottommost property.
2489 Allowed values: "string", (same as string), "int", "bool". Empty string
2492 bool AddAttribute( const wxString
& name
,
2493 const wxString
& type
,
2494 const wxString
& value
);
2496 /** Called once in AddChildren.
2498 virtual void DoScanForChildren() = 0;
2501 Returns id of parent property for which children can currently be
2504 wxPGProperty
* GetCurParent() const
2506 return (wxPGProperty
*) m_propHierarchy
[m_propHierarchy
.size()-1];
2509 wxPropertyGridPageState
* GetState() { return m_state
; }
2510 const wxPropertyGridPageState
* GetState() const { return m_state
; }
2512 /** Like wxString::ToLong, except allows N% in addition of N.
2514 static bool ToLongPCT( const wxString
& s
, long* pval
, long max
);
2516 /** Parses strings of format "choice1"[=value1] ... "choiceN"[=valueN] into
2517 wxPGChoices. Registers parsed result using idString (if not empty).
2518 Also, if choices with given id already registered, then don't parse but
2519 return those choices instead.
2521 wxPGChoices
ParseChoices( const wxString
& choicesString
,
2522 const wxString
& idString
);
2524 /** Implement in derived class to do custom process when an error occurs.
2525 Default implementation uses wxLogError.
2527 virtual void ProcessError( const wxString
& msg
);
2531 /** Used property grid. */
2532 wxPropertyGrid
* m_pg
;
2534 /** Used property grid state. */
2535 wxPropertyGridPageState
* m_state
;
2537 /** Tree-hierarchy of added properties (that can have children). */
2538 wxArrayPGProperty m_propHierarchy
;
2540 /** Hashmap for string-id to wxPGChoicesData mapping. */
2541 wxPGHashMapS2P m_dictIdChoices
;
2544 // -----------------------------------------------------------------------
2547 // Undefine macros that are not needed outside propertygrid sources
2549 #ifndef __wxPG_SOURCE_FILE__
2550 #undef wxPG_FL_DESC_REFRESH_REQUIRED
2551 #undef wxPG_FL_SCROLLBAR_DETECTED
2552 #undef wxPG_FL_CREATEDSTATE
2553 #undef wxPG_FL_NOSTATUSBARHELP
2554 #undef wxPG_FL_SCROLLED
2555 #undef wxPG_FL_FOCUS_INSIDE_CHILD
2556 #undef wxPG_FL_FOCUS_INSIDE
2557 #undef wxPG_FL_MOUSE_INSIDE_CHILD
2558 #undef wxPG_FL_CUR_USES_CUSTOM_IMAGE
2559 #undef wxPG_FL_PRIMARY_FILLS_ENTIRE
2560 #undef wxPG_FL_VALUE_MODIFIED
2561 #undef wxPG_FL_MOUSE_INSIDE
2562 #undef wxPG_FL_FOCUSED
2563 #undef wxPG_FL_MOUSE_CAPTURED
2564 #undef wxPG_FL_INITIALIZED
2565 #undef wxPG_FL_ACTIVATION_BY_CLICK
2566 #undef wxPG_SUPPORT_TOOLTIPS
2567 #undef wxPG_DOUBLE_BUFFER
2568 #undef wxPG_ICON_WIDTH
2569 #undef wxPG_USE_RENDERER_NATIVE
2570 // Following are needed by the manager headers
2571 // #undef const wxString&
2574 // -----------------------------------------------------------------------
2578 #endif // _WX_PROPGRID_PROPGRID_H_