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 // -----------------------------------------------------------------------
39 // This is required for sharing common global variables.
40 class WXDLLIMPEXP_PROPGRID wxPGGlobalVarsClass
44 wxPGGlobalVarsClass();
45 ~wxPGGlobalVarsClass();
48 // Critical section for handling the globals. Generally it is not needed
49 // since GUI code is supposed to be in single thread. However,
50 // we do want the user to be able to convey wxPropertyGridEvents to other
52 wxCriticalSection m_critSect
;
55 // Used by advprops, but here to make things easier.
56 wxString m_pDefaultImageWildcard
;
58 // Map of editor class instances (keys are name string).
59 wxPGHashMapS2P m_mapEditorClasses
;
62 wxVector
<wxValidator
*> m_arrValidators
; // These wxValidators need to be freed
65 wxPGHashMapS2P m_dictPropertyClassInfo
; // PropertyName -> ClassInfo
67 wxPGChoices
* m_fontFamilyChoices
;
69 // Replace with your own to affect all properties using default renderer.
70 wxPGCellRenderer
* m_defaultRenderer
;
72 wxPGChoices m_boolChoices
;
74 wxVariant m_vEmptyString
;
76 wxVariant m_vMinusOne
;
80 // Cached constant strings
81 wxPGCachedString m_strstring
;
82 wxPGCachedString m_strlong
;
83 wxPGCachedString m_strbool
;
84 wxPGCachedString m_strlist
;
86 wxPGCachedString m_strDefaultValue
;
87 wxPGCachedString m_strMin
;
88 wxPGCachedString m_strMax
;
89 wxPGCachedString m_strUnits
;
90 wxPGCachedString m_strInlineHelp
;
92 // If true then some things are automatically translated
93 bool m_autoGetTranslation
;
95 // > 0 if errors cannot or should not be shown in statusbar etc.
98 int m_extraStyle
; // global extra style
102 int HasExtraStyle( int style
) const { return (m_extraStyle
& style
); }
105 extern WXDLLIMPEXP_PROPGRID wxPGGlobalVarsClass
* wxPGGlobalVars
;
107 #define wxPGVariant_EmptyString (wxPGGlobalVars->m_vEmptyString)
108 #define wxPGVariant_Zero (wxPGGlobalVars->m_vZero)
109 #define wxPGVariant_MinusOne (wxPGGlobalVars->m_vMinusOne)
110 #define wxPGVariant_True (wxPGGlobalVars->m_vTrue)
111 #define wxPGVariant_False (wxPGGlobalVars->m_vFalse)
113 #define wxPGVariant_Bool(A) (A?wxPGVariant_True:wxPGVariant_False)
115 // When wxPG is loaded dynamically after the application is already running
116 // then the built-in module system won't pick this one up. Add it manually.
117 WXDLLIMPEXP_PROPGRID
void wxPGInitResourceModule();
121 // -----------------------------------------------------------------------
123 /** @section propgrid_window_styles wxPropertyGrid Window Styles
125 SetWindowStyleFlag method can be used to modify some of these at run-time.
128 enum wxPG_WINDOW_STYLES
131 /** This will cause Sort() automatically after an item is added.
132 When inserting a lot of items in this mode, it may make sense to
133 use Freeze() before operations and Thaw() afterwards to increase
136 wxPG_AUTO_SORT
= 0x00000010,
138 /** Categories are not initially shown (even if added).
139 IMPORTANT NOTE: If you do not plan to use categories, then this
140 style will waste resources.
141 This flag can also be changed using wxPropertyGrid::EnableCategories method.
143 wxPG_HIDE_CATEGORIES
= 0x00000020,
145 /* This style combines non-categoric mode and automatic sorting.
147 wxPG_ALPHABETIC_MODE
= (wxPG_HIDE_CATEGORIES
|wxPG_AUTO_SORT
),
149 /** Modified values are shown in bold font. Changing this requires Refresh()
152 wxPG_BOLD_MODIFIED
= 0x00000040,
154 /** When wxPropertyGrid is resized, splitter moves to the center. This
155 behavior stops once the user manually moves the splitter.
157 wxPG_SPLITTER_AUTO_CENTER
= 0x00000080,
159 /** Display tooltips for cell text that cannot be shown completely. If
160 wxUSE_TOOLTIPS is 0, then this doesn't have any effect.
162 wxPG_TOOLTIPS
= 0x00000100,
164 /** Disables margin and hides all expand/collapse buttons that would appear
165 outside the margin (for sub-properties). Toggling this style automatically
166 expands all collapsed items.
168 wxPG_HIDE_MARGIN
= 0x00000200,
170 /** This style prevents user from moving the splitter.
172 wxPG_STATIC_SPLITTER
= 0x00000400,
174 /** Combination of other styles that make it impossible for user to modify
177 wxPG_STATIC_LAYOUT
= (wxPG_HIDE_MARGIN
|wxPG_STATIC_SPLITTER
),
179 /** Disables wxTextCtrl based editors for properties which
180 can be edited in another way.
182 Equals calling wxPropertyGrid::LimitPropertyEditing for all added
185 wxPG_LIMITED_EDITING
= 0x00000800,
187 /** wxPropertyGridManager only: Show toolbar for mode and page selection. */
188 wxPG_TOOLBAR
= 0x00001000,
190 /** wxPropertyGridManager only: Show adjustable text box showing description
191 or help text, if available, for currently selected property.
193 wxPG_DESCRIPTION
= 0x00002000,
195 /** wxPropertyGridManager only: don't show an internal border around the
196 property grid. Recommended if you use a header.
198 wxPG_NO_INTERNAL_BORDER
= 0x00004000
201 #if wxPG_COMPATIBILITY_1_4
202 // In wxPG 1.4 this was used to enable now-default theme border support
203 // in wxPropertyGridManager.
204 #define wxPG_THEME_BORDER 0x00000000
208 enum wxPG_EX_WINDOW_STYLES
212 NOTE: wxPG_EX_xxx are extra window styles and must be set using
213 SetExtraStyle() member function.
215 Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if
216 wxPG_HIDE_CATEGORIES is not defined, the non-categorized data storage is
217 not activated, and switching the mode first time becomes somewhat slower.
218 wxPG_EX_INIT_NOCAT activates the non-categorized data storage right away.
219 IMPORTANT NOTE: If you do plan not switching to non-categoric mode, or if
220 you don't plan to use categories at all, then using this style will result
221 in waste of resources.
224 wxPG_EX_INIT_NOCAT
= 0x00001000,
226 /** Extended window style that sets wxPropertyGridManager toolbar to not
229 wxPG_EX_NO_FLAT_TOOLBAR
= 0x00002000,
231 /** Shows alphabetic/categoric mode buttons from toolbar.
233 wxPG_EX_MODE_BUTTONS
= 0x00008000,
235 /** Show property help strings as tool tips instead as text on the status bar.
236 You can set the help strings using SetPropertyHelpString member function.
238 wxPG_EX_HELP_AS_TOOLTIPS
= 0x00010000,
240 /** Prevent TAB from focusing to wxButtons. This behavior was default
241 in version 1.2.0 and earlier.
242 NOTE! Tabbing to button doesn't work yet. Problem seems to be that on wxMSW
243 atleast the button doesn't properly propagate key events (yes, I'm using
246 //wxPG_EX_NO_TAB_TO_BUTTON = 0x00020000,
248 /** Allows relying on native double-buffering.
250 wxPG_EX_NATIVE_DOUBLE_BUFFERING
= 0x00080000,
252 /** Set this style to let user have ability to set values of properties to
253 unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for
256 wxPG_EX_AUTO_UNSPECIFIED_VALUES
= 0x00200000,
259 If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION
260 and wxPG_STRING_PASSWORD) are not stored into property's attribute storage
261 (thus they are not readable).
263 Note that this option is global, and applies to all wxPG property
266 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES
= 0x00400000,
268 /** Hides page selection buttons from toolbar.
270 wxPG_EX_HIDE_PAGE_BUTTONS
= 0x01000000,
272 /** Allows multiple properties to be selected by user (by pressing SHIFT
273 when clicking on a property, or by dragging with left mouse button
276 You can get array of selected properties with
277 wxPropertyGridInterface::GetSelectedProperties(). In multiple selection
278 mode wxPropertyGridInterface::GetSelection() returns
279 property which has editor active (usually the first one
280 selected). Other useful member functions are ClearSelection(),
281 AddToSelection() and RemoveFromSelection().
283 wxPG_EX_MULTIPLE_SELECTION
= 0x02000000,
286 This enables top-level window tracking which allows wxPropertyGrid to
287 notify the application of last-minute property value changes by user.
289 This style is not enabled by default because it may cause crashes when
290 wxPropertyGrid is used in with wxAUI or similar system.
292 @remarks If you are not in fact using any system that may change
293 wxPropertyGrid's top-level parent window on its own, then you
294 are recommended to enable this style.
296 wxPG_EX_ENABLE_TLP_TRACKING
= 0x04000000,
298 /** Don't show divider above toolbar, on Windows.
300 wxPG_EX_NO_TOOLBAR_DIVIDER
= 0x08000000,
302 /** Show a separator below the toolbar.
304 wxPG_EX_TOOLBAR_SEPARATOR
= 0x10000000
308 #if wxPG_COMPATIBILITY_1_4
309 #define wxPG_EX_DISABLE_TLP_TRACKING 0x00000000
312 /** Combines various styles.
314 #define wxPG_DEFAULT_STYLE (0)
316 /** Combines various styles.
318 #define wxPGMAN_DEFAULT_STYLE (0)
323 // -----------------------------------------------------------------------
326 // Ids for sub-controls
327 // NB: It should not matter what these are.
328 #define wxPG_SUBID1 2
329 #define wxPG_SUBID2 3
330 #define wxPG_SUBID_TEMP1 4
332 // -----------------------------------------------------------------------
334 /** @class wxPGCommonValue
336 wxPropertyGrid stores information about common values in these
339 NB: Common value feature is not complete, and thus not mentioned in
342 class WXDLLIMPEXP_PROPGRID wxPGCommonValue
346 wxPGCommonValue( const wxString
& label
, wxPGCellRenderer
* renderer
)
349 m_renderer
= renderer
;
352 virtual ~wxPGCommonValue()
354 m_renderer
->DecRef();
357 virtual wxString
GetEditableText() const { return m_label
; }
358 const wxString
& GetLabel() const { return m_label
; }
359 wxPGCellRenderer
* GetRenderer() const { return m_renderer
; }
363 wxPGCellRenderer
* m_renderer
;
366 // -----------------------------------------------------------------------
368 /** @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
372 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
375 /** Prevents user from leaving property unless value is valid. If this
376 behavior flag is not used, then value change is instead cancelled.
378 wxPG_VFB_STAY_IN_PROPERTY
= 0x01,
380 /** Calls wxBell() on validation failure.
382 wxPG_VFB_BEEP
= 0x02,
384 /** Cell with invalid value will be marked (with red colour).
386 wxPG_VFB_MARK_CELL
= 0x04,
388 /** Display customizable text message explaining the situation.
390 wxPG_VFB_SHOW_MESSAGE
= 0x08,
393 wxPG_VFB_DEFAULT
= wxPG_VFB_STAY_IN_PROPERTY
|wxPG_VFB_BEEP
,
395 /** Only used internally. */
396 wxPG_VFB_UNDEFINED
= 0x80
403 typedef wxByte wxPGVFBFlags
;
408 Used to convey validation information to and from functions that
409 actually perform validation. Mostly used in custom property
412 class WXDLLIMPEXP_PROPGRID wxPGValidationInfo
414 friend class wxPropertyGrid
;
417 @return Returns failure behavior which is a combination of
418 @ref propgrid_vfbflags.
420 wxPGVFBFlags
GetFailureBehavior() const
421 { return m_failureBehavior
; }
424 Returns current failure message.
426 const wxString
& GetFailureMessage() const
427 { return m_failureMessage
; }
430 Returns reference to pending value.
432 wxVariant
& GetValue()
438 /** Set validation failure behavior
440 @param failureBehavior
441 Mixture of @ref propgrid_vfbflags.
443 void SetFailureBehavior(wxPGVFBFlags failureBehavior
)
444 { m_failureBehavior
= failureBehavior
; }
447 Set current failure message.
449 void SetFailureMessage(const wxString
& message
)
450 { m_failureMessage
= message
; }
453 /** Value to be validated.
457 /** Message displayed on validation failure.
459 wxString m_failureMessage
;
461 /** Validation failure behavior. Use wxPG_VFB_XXX flags.
463 wxPGVFBFlags m_failureBehavior
;
466 // -----------------------------------------------------------------------
468 /** @section propgrid_pgactions wxPropertyGrid Action Identifiers
470 These are used with wxPropertyGrid::AddActionTrigger() and
471 wxPropertyGrid::ClearActionTriggers().
475 enum wxPG_KEYBOARD_ACTIONS
477 wxPG_ACTION_INVALID
= 0,
478 wxPG_ACTION_NEXT_PROPERTY
,
479 wxPG_ACTION_PREV_PROPERTY
,
480 wxPG_ACTION_EXPAND_PROPERTY
,
481 wxPG_ACTION_COLLAPSE_PROPERTY
,
482 wxPG_ACTION_CANCEL_EDIT
,
483 wxPG_ACTION_PRESS_BUTTON
, // Causes editor button (if any) to be pressed
490 // -----------------------------------------------------------------------
493 // wxPropertyGrid::DoSelectProperty flags (selFlags)
495 // Focuses to created editor
496 #define wxPG_SEL_FOCUS 0x0001
497 // Forces deletion and recreation of editor
498 #define wxPG_SEL_FORCE 0x0002
499 // For example, doesn't cause EnsureVisible
500 #define wxPG_SEL_NONVISIBLE 0x0004
501 // Do not validate editor's value before selecting
502 #define wxPG_SEL_NOVALIDATE 0x0008
503 // Property being deselected is about to be deleted
504 #define wxPG_SEL_DELETING 0x0010
505 // Property's values was set to unspecified by the user
506 #define wxPG_SEL_SETUNSPEC 0x0020
507 // Property's event handler changed the value
508 #define wxPG_SEL_DIALOGVAL 0x0040
509 // Set to disable sending of wxEVT_PG_SELECTED event
510 #define wxPG_SEL_DONT_SEND_EVENT 0x0080
511 // Don't make any graphics updates
512 #define wxPG_SEL_NO_REFRESH 0x0100
514 // -----------------------------------------------------------------------
516 // DoSetSplitterPosition() flags
518 enum wxPG_SET_SPLITTER_POSITION_SPLITTER_FLAGS
520 wxPG_SPLITTER_REFRESH
= 0x0001,
521 wxPG_SPLITTER_ALL_PAGES
= 0x0002,
522 wxPG_SPLITTER_FROM_EVENT
= 0x0004,
523 wxPG_SPLITTER_FROM_AUTO_CENTER
= 0x0008
527 // -----------------------------------------------------------------------
532 #define wxPG_FL_INITIALIZED 0x0001
533 // Set when creating editor controls if it was clicked on.
534 #define wxPG_FL_ACTIVATION_BY_CLICK 0x0002
535 #define wxPG_FL_DONT_CENTER_SPLITTER 0x0004
536 #define wxPG_FL_FOCUSED 0x0008
537 #define wxPG_FL_MOUSE_CAPTURED 0x0010
538 #define wxPG_FL_MOUSE_INSIDE 0x0020
539 #define wxPG_FL_VALUE_MODIFIED 0x0040
540 // don't clear background of m_wndEditor
541 #define wxPG_FL_PRIMARY_FILLS_ENTIRE 0x0080
542 // currently active editor uses custom image
543 #define wxPG_FL_CUR_USES_CUSTOM_IMAGE 0x0100
544 // cell colours override selection colours for selected cell
545 #define wxPG_FL_CELL_OVERRIDES_SEL 0x0200
546 #define wxPG_FL_SCROLLED 0x0400
547 // set when all added/inserted properties get hideable flag
548 #define wxPG_FL_ADDING_HIDEABLES 0x0800
549 // Disables showing help strings on statusbar.
550 #define wxPG_FL_NOSTATUSBARHELP 0x1000
551 // Marks that we created the state, so we have to destroy it too.
552 #define wxPG_FL_CREATEDSTATE 0x2000
553 // Set if scrollbar's existence was detected in last onresize.
554 #define wxPG_FL_SCROLLBAR_DETECTED 0x4000
555 // Set if wxPGMan requires redrawing of description text box.
556 #define wxPG_FL_DESC_REFRESH_REQUIRED 0x8000
557 // Set if contained in wxPropertyGridManager
558 #define wxPG_FL_IN_MANAGER 0x00020000
559 // Set after wxPropertyGrid is shown in its initial good size
560 #define wxPG_FL_GOOD_SIZE_SET 0x00040000
561 // Set when in SelectProperty.
562 #define wxPG_FL_IN_SELECT_PROPERTY 0x00100000
563 // Set when help string is shown in status bar
564 #define wxPG_FL_STRING_IN_STATUSBAR 0x00200000
565 // Validation failed. Clear on modify event.
566 #define wxPG_FL_VALIDATION_FAILED 0x00800000
567 // Auto sort is enabled (for categorized mode)
568 #define wxPG_FL_CATMODE_AUTO_SORT 0x01000000
569 // Set after page has been inserted to manager
570 #define wxPG_MAN_FL_PAGE_INSERTED 0x02000000
571 // Active editor control is abnormally large
572 #define wxPG_FL_ABNORMAL_EDITOR 0x04000000
573 // Recursion guard for HandleCustomEditorEvent
574 #define wxPG_FL_IN_HANDLECUSTOMEDITOREVENT 0x08000000
575 #define wxPG_FL_VALUE_CHANGE_IN_EVENT 0x10000000
576 // Editor control width should not change on resize
577 #define wxPG_FL_FIXED_WIDTH_EDITOR 0x20000000
578 // Width of panel can be different than width of grid
579 #define wxPG_FL_HAS_VIRTUAL_WIDTH 0x40000000
580 // Prevents RecalculateVirtualSize re-entrancy
581 #define wxPG_FL_RECALCULATING_VIRTUAL_SIZE 0x80000000
583 #endif // #ifndef SWIG
585 #if !defined(__wxPG_SOURCE_FILE__) && !defined(SWIG)
586 // Reduce compile time, but still include in user app
587 #include "wx/propgrid/props.h"
590 // -----------------------------------------------------------------------
592 /** @class wxPropertyGrid
594 wxPropertyGrid is a specialized grid for editing properties
595 such as strings, numbers, flagsets, fonts, and colours. wxPropertySheet
596 used to do the very same thing, but it hasn't been updated for a while
597 and it is currently deprecated.
599 Please note that most member functions are inherited and as such not
600 documented on this page. This means you will probably also want to read
601 wxPropertyGridInterface class reference.
603 See also @ref overview_propgrid.
605 @section propgrid_window_styles_ Window Styles
607 See @ref propgrid_window_styles.
609 @section propgrid_event_handling Event Handling
611 To process input from a propertygrid control, use these event handler
612 macros to direct input to member functions that take a wxPropertyGridEvent
615 @beginEventTable{wxPropertyGridEvent}
616 @event{EVT_PG_SELECTED (id, func)}
617 Respond to wxEVT_PG_SELECTED event, generated when a property selection
618 has been changed, either by user action or by indirect program
619 function. For instance, collapsing a parent property programmatically
620 causes any selected child property to become unselected, and may
621 therefore cause this event to be generated.
622 @event{EVT_PG_CHANGING(id, func)}
623 Respond to wxEVT_PG_CHANGING event, generated when property value
624 is about to be changed by user. Use wxPropertyGridEvent::GetValue()
625 to take a peek at the pending value, and wxPropertyGridEvent::Veto()
626 to prevent change from taking place, if necessary.
627 @event{EVT_PG_HIGHLIGHTED(id, func)}
628 Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
629 moves over a property. Event's property is NULL if hovered area does
630 not belong to any property.
631 @event{EVT_PG_RIGHT_CLICK(id, func)}
632 Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
633 clicked on with right mouse button.
634 @event{EVT_PG_DOUBLE_CLICK(id, func)}
635 Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
636 double-clicked onwith left mouse button.
637 @event{EVT_PG_ITEM_COLLAPSED(id, func)}
638 Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
639 a property or category..
640 @event{EVT_PG_ITEM_EXPANDED(id, func)}
641 Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
642 a property or category..
643 @event{EVT_PG_LABEL_EDIT_BEGIN(id, func)}
644 Respond to wxEVT_PG_LABEL_EDIT_BEGIN event, generated when is about to
645 begin editing a property label. You can veto this event to prevent the
647 @event{EVT_PG_LABEL_EDIT_ENDING(id, func)}
648 Respond to wxEVT_PG_LABEL_EDIT_ENDING event, generated when is about to
649 end editing of a property label. You can veto this event to prevent the
651 @event{EVT_PG_COL_BEGIN_DRAG(id, func)}
652 Respond to wxEVT_PG_COL_BEGIN_DRAG event, generated when user
653 starts resizing a column - can be vetoed.
654 @event{EVT_PG_COL_DRAGGING,(id, func)}
655 Respond to wxEVT_PG_COL_DRAGGING, event, generated when a
656 column resize by user is in progress. This event is also generated
657 when user double-clicks the splitter in order to recenter
659 @event{EVT_PG_COL_END_DRAG(id, func)}
660 Respond to wxEVT_PG_COL_END_DRAG event, generated after column
661 resize by user has finished.
666 - Use Freeze() and Thaw() respectively to disable and enable drawing. This
667 will also delay sorting etc. miscellaneous calculations to the last
673 class WXDLLIMPEXP_PROPGRID
674 wxPropertyGrid
: public wxScrolledWindow
, public wxPropertyGridInterface
676 friend class wxPropertyGridEvent
;
677 friend class wxPropertyGridPageState
;
678 friend class wxPropertyGridInterface
;
679 friend class wxPropertyGridManager
;
680 friend class wxPGHeaderCtrl
;
682 DECLARE_DYNAMIC_CLASS(wxPropertyGrid
)
687 Two step constructor.
689 Call Create when this constructor is called to build up the
695 /** The default constructor. The styles to be used are styles valid for
696 the wxWindow and wxScrolledWindow.
698 @see @link wndflags Additional Window Styles @endlink
700 wxPropertyGrid( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
701 const wxPoint
& pos
= wxDefaultPosition
,
702 const wxSize
& size
= wxDefaultSize
,
703 long style
= wxPG_DEFAULT_STYLE
,
704 const wxString
& name
= wxPropertyGridNameStr
);
707 virtual ~wxPropertyGrid();
709 /** Adds given key combination to trigger given action.
712 Which action to trigger. See @link pgactions List of list of
713 wxPropertyGrid actions@endlink.
715 void AddActionTrigger( int action
, int keycode
, int modifiers
= 0 );
718 This static function enables or disables automatic use of
719 wxGetTranslation for following strings: wxEnumProperty list labels,
720 wxFlagsProperty sub-property labels.
724 static void AutoGetTranslation( bool enable
);
727 Changes value of a property, as if from an editor.
729 Use this instead of SetPropertyValue() if you need the value to run
730 through validation process, and also send the property change event.
733 Returns true if value was successfully changed.
735 bool ChangePropertyValue( wxPGPropArg id
, wxVariant newValue
);
738 Centers the splitter.
740 If argument is true, automatic splitter centering is enabled (only
741 applicapple if style wxPG_SPLITTER_AUTO_CENTER was defined).
743 void CenterSplitter( bool enable_auto_centering
= false );
745 /** Deletes all properties.
747 virtual void Clear();
749 /** Clears action triggers for given action.
751 Which action to trigger. See @link pgactions List of list of
752 wxPropertyGrid actions@endlink.
754 void ClearActionTriggers( int action
);
756 /** Forces updating the value of property from the editor control.
758 Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
759 ProcessEvent, meaning your event handlers will be called immediately.
762 Returns true if anything was changed.
764 virtual bool CommitChangesFromEditor( wxUint32 flags
= 0 );
769 Whenever the control is created without any parameters, use Create to
770 actually create it. Don't access the control's public methods before
771 this is called @see @link wndflags Additional Window Styles@endlink
773 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
774 const wxPoint
& pos
= wxDefaultPosition
,
775 const wxSize
& size
= wxDefaultSize
,
776 long style
= wxPG_DEFAULT_STYLE
,
777 const wxString
& name
= wxPropertyGridNameStr
);
780 Call when editor widget's contents is modified.
782 For example, this is called when changes text in wxTextCtrl (used in
783 wxStringProperty and wxIntProperty).
786 This function should only be called by custom properties.
788 @see wxPGProperty::OnEvent()
790 void EditorsValueWasModified() { m_iFlags
|= wxPG_FL_VALUE_MODIFIED
; }
792 /** Reverse of EditorsValueWasModified().
795 This function should only be called by custom properties.
797 void EditorsValueWasNotModified()
799 m_iFlags
&= ~(wxPG_FL_VALUE_MODIFIED
);
803 Enables or disables (shows/hides) categories according to parameter
806 bool EnableCategories( bool enable
);
808 /** Scrolls and/or expands items to ensure that the given item is visible.
809 Returns true if something was actually done.
811 bool EnsureVisible( wxPGPropArg id
);
814 Reduces column sizes to minimum possible that contents are still
815 visibly (naturally some margin space will be applied as well).
818 Minimum size for the grid to still display everything.
821 Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
823 This function only works properly if grid size prior to call was already
826 Note that you can also get calculated column widths by calling
827 GetState->GetColumnWidth() immediately after this function returns.
831 wxSize sz
= m_pState
->DoFitColumns();
836 Returns wxWindow that the properties are painted on, and which should
837 be used as the parent for editor controls.
844 /** Returns current category caption background colour. */
845 wxColour
GetCaptionBackgroundColour() const { return m_colCapBack
; }
847 wxFont
& GetCaptionFont() { return m_captionFont
; }
849 const wxFont
& GetCaptionFont() const { return m_captionFont
; }
851 /** Returns current category caption text colour. */
852 wxColour
GetCaptionForegroundColour() const { return m_colCapFore
; }
854 /** Returns current cell background colour. */
855 wxColour
GetCellBackgroundColour() const { return m_colPropBack
; }
857 /** Returns current cell text colour when disabled. */
858 wxColour
GetCellDisabledTextColour() const { return m_colDisPropFore
; }
860 /** Returns current cell text colour. */
861 wxColour
GetCellTextColour() const { return m_colPropFore
; }
864 Returns number of columns currently on grid.
866 unsigned int GetColumnCount() const
868 return (unsigned int) m_pState
->m_colWidths
.size();
871 /** Returns colour of empty space below properties. */
872 wxColour
GetEmptySpaceColour() const { return m_colEmptySpace
; }
874 /** Returns height of highest characters of used font. */
875 int GetFontHeight() const { return m_fontHeight
; }
877 /** Returns pointer to itself. Dummy function that enables same kind
878 of code to use wxPropertyGrid and wxPropertyGridManager.
880 wxPropertyGrid
* GetGrid() { return this; }
882 /** Returns rectangle of custom paint image.
884 wxRect
GetImageRect( wxPGProperty
* p
, int item
) const;
886 /** Returns size of the custom paint image in front of property.
887 If no argument is given, returns preferred size.
889 wxSize
GetImageSize( wxPGProperty
* p
= NULL
, int item
= -1 ) const;
892 /** Returns last item which could be iterated using given flags.
894 See @ref propgrid_iterator_flags.
896 wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
)
898 return m_pState
->GetLastItem(flags
);
901 const wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
) const
903 return m_pState
->GetLastItem(flags
);
907 /** Returns colour of lines between cells. */
908 wxColour
GetLineColour() const { return m_colLine
; }
910 /** Returns background colour of margin. */
911 wxColour
GetMarginColour() const { return m_colMargin
; }
913 /** Returns margin width. */
914 int GetMarginWidth() const { return m_marginWidth
; }
917 Returns most up-to-date value of selected property. This will return
918 value different from GetSelectedProperty()->GetValue() only when text
919 editor is activate and string edited by user represents valid,
920 uncommitted property value.
922 wxVariant
GetUncommittedPropertyValue();
924 /** Returns "root property". It does not have name, etc. and it is not
925 visible. It is only useful for accessing its children.
927 wxPGProperty
* GetRoot() const { return m_pState
->m_properties
; }
929 /** Returns height of a single grid row (in pixels). */
930 int GetRowHeight() const { return m_lineHeight
; }
932 /** Returns currently selected property. */
933 wxPGProperty
* GetSelectedProperty() const { return GetSelection(); }
935 /** Returns current selection background colour. */
936 wxColour
GetSelectionBackgroundColour() const { return m_colSelBack
; }
938 /** Returns current selection text colour. */
939 wxColour
GetSelectionForegroundColour() const { return m_colSelFore
; }
941 /** Returns current splitter x position. */
942 int GetSplitterPosition() const
943 { return m_pState
->DoGetSplitterPosition(0); }
945 /** Returns wxTextCtrl active in currently selected property, if any. Takes
946 into account wxOwnerDrawnComboBox.
948 wxTextCtrl
* GetEditorTextCtrl() const;
950 wxPGValidationInfo
& GetValidationInfo()
952 return m_validationInfo
;
955 /** Returns current vertical spacing. */
956 int GetVerticalSpacing() const { return (int)m_vspacing
; }
959 Returns @true if a property editor control has focus.
961 bool IsEditorFocused() const;
963 /** Returns true if editor's value was marked modified.
965 bool IsEditorsValueModified() const
966 { return ( m_iFlags
& wxPG_FL_VALUE_MODIFIED
) ? true : false; }
969 Returns information about arbitrary position in the grid.
972 Coordinates in the virtual grid space. You may need to use
973 wxScrolledWindow::CalcScrolledPosition() for translating
974 wxPropertyGrid client coordinates into something this member
977 wxPropertyGridHitTestResult
HitTest( const wxPoint
& pt
) const;
979 /** Returns true if any property has been modified by the user. */
980 bool IsAnyModified() const { return (m_pState
->m_anyModified
>0); }
983 Returns true if updating is frozen (ie Freeze() called but not yet
986 bool IsFrozen() const { return (m_frozen
>0)?true:false; }
989 It is recommended that you call this function any time your code causes
990 wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle()
991 handler should be able to detect most changes, but it is not perfect.
994 New top-level parent that is about to be set. Old top-level parent
995 window should still exist as the current one.
997 @remarks This function is automatically called from wxPropertyGrid::
998 Reparent() and wxPropertyGridManager::Reparent(). You only
999 need to use it if you reparent wxPropertyGrid indirectly.
1001 void OnTLPChanging( wxWindow
* newTLP
);
1003 /** Redraws given property.
1005 virtual void RefreshProperty( wxPGProperty
* p
);
1008 /** Registers a new editor class.
1010 Pointer to the editor class instance that should be used.
1012 static wxPGEditor
* RegisterEditorClass( wxPGEditor
* editor
,
1013 bool noDefCheck
= false )
1015 return DoRegisterEditorClass(editor
, wxEmptyString
, noDefCheck
);
1018 static wxPGEditor
* DoRegisterEditorClass( wxPGEditor
* editorClass
,
1019 const wxString
& editorName
,
1020 bool noDefCheck
= false );
1023 /** Resets all colours to the original system values.
1025 void ResetColours();
1029 Editor widget is automatically created, but not focused unless focus is
1036 True if selection finished successfully. Usually only fails if
1037 current value in editor is not valid.
1039 @remarks In wxPropertyGrid 1.4, this member function used to generate
1040 wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer
1043 @remarks This clears any previous selection.
1045 bool SelectProperty( wxPGPropArg id
, bool focus
= false );
1048 Set entire new selection from given list of properties.
1050 void SetSelection( const wxArrayPGProperty
& newSelection
)
1052 DoSetSelection( newSelection
, wxPG_SEL_DONT_SEND_EVENT
);
1056 Adds given property into selection. If wxPG_EX_MULTIPLE_SELECTION
1057 extra style is not used, then this has same effect as
1058 calling SelectProperty().
1060 @remarks Multiple selection is not supported for categories. This
1061 means that if you have properties selected, you cannot
1062 add category to selection, and also if you have category
1063 selected, you cannot add other properties to selection.
1064 This member function will fail silently in these cases,
1065 even returning true.
1067 bool AddToSelection( wxPGPropArg id
)
1069 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
1070 return DoAddToSelection(p
, wxPG_SEL_DONT_SEND_EVENT
);
1074 Removes given property from selection. If property is not selected,
1075 an assertion failure will occur.
1077 bool RemoveFromSelection( wxPGPropArg id
)
1079 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
1080 return DoRemoveFromSelection(p
, wxPG_SEL_DONT_SEND_EVENT
);
1084 Makes given column editable by user.
1087 Using @false here will disable column from being editable.
1089 void MakeColumnEditable( unsigned int column
, bool editable
= true );
1092 Creates label editor wxTextCtrl for given column, for property
1093 that is currently selected. When multiple selection is
1094 enabled, this applies to whatever property GetSelection()
1098 Which column's label to edit. Note that you should not
1099 use value 1, which is reserved for property value
1102 @see EndLabelEdit(), MakeColumnEditable()
1104 void BeginLabelEdit( unsigned int column
= 0 )
1106 DoBeginLabelEdit(column
, wxPG_SEL_DONT_SEND_EVENT
);
1110 Destroys label editor wxTextCtrl, if any.
1113 Use @true (default) to store edited label text in
1116 @see BeginLabelEdit(), MakeColumnEditable()
1118 void EndLabelEdit( bool commit
= true )
1120 DoEndLabelEdit(commit
, wxPG_SEL_DONT_SEND_EVENT
);
1124 Returns currently active label editor, NULL if none.
1126 wxTextCtrl
* GetLabelEditor() const
1128 return m_labelEditor
;
1131 /** Sets category caption background colour. */
1132 void SetCaptionBackgroundColour(const wxColour
& col
);
1134 /** Sets category caption text colour. */
1135 void SetCaptionTextColour(const wxColour
& col
);
1137 /** Sets default cell background colour - applies to property cells.
1138 Note that appearance of editor widgets may not be affected.
1140 void SetCellBackgroundColour(const wxColour
& col
);
1142 /** Sets cell text colour for disabled properties.
1144 void SetCellDisabledTextColour(const wxColour
& col
);
1146 /** Sets default cell text colour - applies to property name and value text.
1147 Note that appearance of editor widgets may not be affected.
1149 void SetCellTextColour(const wxColour
& col
);
1151 /** Set number of columns (2 or more).
1153 void SetColumnCount( int colCount
)
1155 m_pState
->SetColumnCount(colCount
);
1160 Sets the 'current' category - Append will add non-category properties
1163 void SetCurrentCategory( wxPGPropArg id
)
1165 wxPG_PROP_ARG_CALL_PROLOG()
1166 wxPropertyCategory
* pc
= wxDynamicCast(p
, wxPropertyCategory
);
1168 m_pState
->m_currentCategory
= pc
;
1171 /** Sets colour of empty space below properties. */
1172 void SetEmptySpaceColour(const wxColour
& col
);
1174 /** Sets colour of lines between cells. */
1175 void SetLineColour(const wxColour
& col
);
1177 /** Sets background colour of margin. */
1178 void SetMarginColour(const wxColour
& col
);
1181 Sets selection background colour - applies to selected property name
1184 void SetSelectionBackgroundColour(const wxColour
& col
);
1187 Sets selection foreground colour - applies to selected property name
1190 void SetSelectionTextColour(const wxColour
& col
);
1192 /** Sets x coordinate of the splitter.
1194 Splitter position cannot exceed grid size, and therefore setting it
1195 during form creation may fail as initial grid size is often smaller
1196 than desired splitter position, especially when sizers are being used.
1198 void SetSplitterPosition( int newXPos
, int col
= 0 )
1200 DoSetSplitterPosition(newXPos
, col
, wxPG_SPLITTER_REFRESH
);
1204 Sets the property sorting function.
1207 The sorting function to be used. It should return a value greater
1208 than 0 if position of p1 is after p2. So, for instance, when
1209 comparing property names, you can use following implementation:
1212 int MyPropertySortFunction(wxPropertyGrid* propGrid,
1216 return p1->GetBaseName().compare( p2->GetBaseName() );
1221 Default property sort function sorts properties by their labels
1222 (case-insensitively).
1224 @see GetSortFunction, wxPropertyGridInterface::Sort,
1225 wxPropertyGridInterface::SortChildren
1227 void SetSortFunction( wxPGSortCallback sortFunction
)
1229 m_sortFunction
= sortFunction
;
1233 Returns the property sort function (default is @NULL).
1235 @see SetSortFunction
1237 wxPGSortCallback
GetSortFunction() const
1239 return m_sortFunction
;
1243 Sets appearance of value cells representing an unspecified property
1244 value. Default appearance is blank.
1246 @remarks If you set the unspecified value to have any
1247 textual representation, then that will override
1248 "InlineHelp" attribute.
1250 @see wxPGProperty::SetValueToUnspecified(),
1251 wxPGProperty::IsValueUnspecified()
1253 void SetUnspecifiedValueAppearance( const wxPGCell
& cell
)
1255 m_unspecifiedAppearance
= m_propertyDefaultCell
;
1256 m_unspecifiedAppearance
.MergeFrom(cell
);
1260 Returns current appearance of unspecified value cells.
1262 @see SetUnspecifiedValueAppearance()
1264 const wxPGCell
& GetUnspecifiedValueAppearance() const
1266 return m_unspecifiedAppearance
;
1270 Returns (visual) text representation of the unspecified
1273 @param argFlags For internal use only.
1275 wxString
GetUnspecifiedValueText( int argFlags
= 0 ) const;
1277 /** Set virtual width for this particular page. Width -1 indicates that the
1278 virtual width should be disabled. */
1279 void SetVirtualWidth( int width
);
1282 Moves splitter as left as possible, while still allowing all
1283 labels to be shown in full.
1285 @param privateChildrenToo
1286 If @false, will still allow private children to be cropped.
1288 void SetSplitterLeft( bool privateChildrenToo
= false )
1290 m_pState
->SetSplitterLeft(privateChildrenToo
);
1293 /** Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
1294 height. Value of 2 should be default on most platforms.
1296 void SetVerticalSpacing( int vspacing
)
1298 m_vspacing
= (unsigned char)vspacing
;
1299 CalculateFontAndBitmapStuff( vspacing
);
1300 if ( !m_pState
->m_itemsAdded
) Refresh();
1303 /** Shows an brief error message that is related to a property. */
1304 void ShowPropertyError( wxPGPropArg id
, const wxString
& msg
)
1306 wxPG_PROP_ARG_CALL_PROLOG()
1307 DoShowPropertyError(p
, msg
);
1310 /////////////////////////////////////////////////////////////////
1312 // Following methods do not need to be (currently) documented
1314 /////////////////////////////////////////////////////////////////
1316 bool HasVirtualWidth() const
1317 { return (m_iFlags
& wxPG_FL_HAS_VIRTUAL_WIDTH
) ? true : false; }
1319 const wxPGCommonValue
* GetCommonValue( unsigned int i
) const
1321 return (wxPGCommonValue
*) m_commonValues
[i
];
1324 /** Returns number of common values.
1326 unsigned int GetCommonValueCount() const
1328 return (unsigned int) m_commonValues
.size();
1331 /** Returns label of given common value.
1333 wxString
GetCommonValueLabel( unsigned int i
) const
1335 wxASSERT( GetCommonValue(i
) );
1336 return GetCommonValue(i
)->GetLabel();
1340 Returns index of common value that will truly change value to
1343 int GetUnspecifiedCommonValue() const { return m_cvUnspecified
; }
1345 /** Set index of common value that will truly change value to unspecified.
1346 Using -1 will set none to have such effect.
1349 void SetUnspecifiedCommonValue( int index
) { m_cvUnspecified
= index
; }
1352 Shortcut for creating dialog-caller button. Used, for example, by
1355 This should only be called by properties.
1357 wxWindow
* GenerateEditorButton( const wxPoint
& pos
, const wxSize
& sz
);
1359 /** Fixes position of wxTextCtrl-like control (wxSpinCtrl usually
1360 fits as one). Call after control has been created (but before
1363 void FixPosForTextCtrl( wxWindow
* ctrl
,
1364 unsigned int forColumn
= 1,
1365 const wxPoint
& offset
= wxPoint(0, 0) );
1367 /** Shortcut for creating text editor widget.
1369 Same as pos given for CreateEditor.
1371 Same as sz given for CreateEditor.
1373 Initial text for wxTextCtrl.
1375 If right-side control, such as button, also created, then create it
1376 first and pass it as this parameter.
1378 Extra style flags to pass for wxTextCtrl.
1380 Note that this should generally be called only by new classes derived
1383 wxWindow
* GenerateEditorTextCtrl( const wxPoint
& pos
,
1385 const wxString
& value
,
1386 wxWindow
* secondary
,
1389 unsigned int forColumn
= 1 );
1391 /* Generates both textctrl and button.
1393 wxWindow
* GenerateEditorTextCtrlAndButton( const wxPoint
& pos
,
1394 const wxSize
& sz
, wxWindow
** psecondary
, int limited_editing
,
1395 wxPGProperty
* property
);
1397 /** Generates position for a widget editor dialog box.
1399 Property for which dialog is positioned.
1401 Known or over-approximated size of the dialog.
1403 Position for dialog.
1405 wxPoint
GetGoodEditorDialogPosition( wxPGProperty
* p
,
1408 // Converts escape sequences in src_str to newlines,
1409 // tabs, etc. and copies result to dst_str.
1410 static wxString
& ExpandEscapeSequences( wxString
& dst_str
,
1411 wxString
& src_str
);
1413 // Converts newlines, tabs, etc. in src_str to escape
1414 // sequences, and copies result to dst_str.
1415 static wxString
& CreateEscapeSequences( wxString
& dst_str
,
1416 wxString
& src_str
);
1419 Returns rectangle that fully contains properties between and including
1422 wxRect
GetPropertyRect( const wxPGProperty
* p1
,
1423 const wxPGProperty
* p2
) const;
1425 /** Returns pointer to current active primary editor control (NULL if none).
1427 wxWindow
* GetEditorControl() const;
1429 wxWindow
* GetPrimaryEditor() const
1431 return GetEditorControl();
1435 Returns pointer to current active secondary editor control (NULL if
1438 wxWindow
* GetEditorControlSecondary() const
1440 return m_wndEditor2
;
1444 Refreshes any active editor control.
1446 void RefreshEditor();
1448 // Events from editor controls are forward to this function
1449 void HandleCustomEditorEvent( wxEvent
&event
);
1454 Generates contents for string dst based on the contents of
1457 Format will be "(preDelim)str1(postDelim) (preDelim)str2(postDelim) and
1458 so on. Set flags to 1 inorder to convert backslashes to double-back-
1459 slashes and "(preDelims)"'s to "(preDelims)".
1461 static void ArrayStringToString( wxString
& dst
, const wxArrayString
& src
,
1462 wxChar preDelim
, wxChar postDelim
,
1465 // Mostly useful for page switching.
1466 void SwitchState( wxPropertyGridPageState
* pNewState
);
1468 long GetInternalFlags() const { return m_iFlags
; }
1469 bool HasInternalFlag( long flag
) const
1470 { return (m_iFlags
& flag
) ? true : false; }
1471 void SetInternalFlag( long flag
) { m_iFlags
|= flag
; }
1472 void ClearInternalFlag( long flag
) { m_iFlags
&= ~(flag
); }
1473 void IncFrozen() { m_frozen
++; }
1474 void DecFrozen() { m_frozen
--; }
1476 void OnComboItemPaint( const wxPGComboBox
* pCb
,
1482 /** Standardized double-to-string conversion.
1484 static void DoubleToString( wxString
& target
,
1488 wxString
* precTemplate
);
1491 Call this from wxPGProperty::OnEvent() to cause property value to be
1492 changed after the function returns (with true as return value).
1493 ValueChangeInEvent() must be used if you wish the application to be
1494 able to use wxEVT_PG_CHANGING to potentially veto the given value.
1496 void ValueChangeInEvent( wxVariant variant
)
1498 m_changeInEventValue
= variant
;
1499 m_iFlags
|= wxPG_FL_VALUE_CHANGE_IN_EVENT
;
1503 You can use this member function, for instance, to detect in
1504 wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was
1505 already called in wxPGEditor::OnEvent(). It really only detects
1506 if was value was changed using wxPGProperty::SetValueInEvent(), which
1507 is usually used when a 'picker' dialog is displayed. If value was
1508 written by "normal means" in wxPGProperty::StringToValue() or
1509 IntToValue(), then this function will return false (on the other hand,
1510 wxPGProperty::OnEvent() is not even called in those cases).
1512 bool WasValueChangedInEvent() const
1514 return (m_iFlags
& wxPG_FL_VALUE_CHANGE_IN_EVENT
) ? true : false;
1517 /** Returns true if given event is from first of an array of buttons
1518 (as can be in case when wxPGMultiButton is used).
1520 bool IsMainButtonEvent( const wxEvent
& event
)
1522 return (event
.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED
)
1523 && (m_wndSecId
== event
.GetId());
1526 /** Pending value is expected to be passed in PerformValidation().
1528 virtual bool DoPropertyChanged( wxPGProperty
* p
,
1529 unsigned int selFlags
= 0 );
1531 /** Called when validation for given property fails.
1533 Value which failed in validation.
1535 Return true if user is allowed to change to another property even
1536 if current has invalid value.
1538 To add your own validation failure behavior, override
1539 wxPropertyGrid::DoOnValidationFailure().
1541 bool OnValidationFailure( wxPGProperty
* property
,
1542 wxVariant
& invalidValue
);
1544 /** Called to indicate property and editor has valid value now.
1546 void OnValidationFailureReset( wxPGProperty
* property
)
1548 if ( property
&& property
->HasFlag(wxPG_PROP_INVALID_VALUE
) )
1550 DoOnValidationFailureReset(property
);
1551 property
->ClearFlag(wxPG_PROP_INVALID_VALUE
);
1553 m_validationInfo
.m_failureMessage
.clear();
1556 /** Override in derived class to display error messages in custom manner
1557 (these message usually only result from validation failure).
1559 virtual void DoShowPropertyError( wxPGProperty
* property
,
1560 const wxString
& msg
);
1562 /** Override to customize property validation failure behavior.
1564 Value which failed in validation.
1566 Return true if user is allowed to change to another property even
1567 if current has invalid value.
1569 virtual bool DoOnValidationFailure( wxPGProperty
* property
,
1570 wxVariant
& invalidValue
);
1572 /** Override to customize resetting of property validation failure status.
1574 Property is guaranteed to have flag wxPG_PROP_INVALID_VALUE set.
1576 virtual void DoOnValidationFailureReset( wxPGProperty
* property
);
1578 int GetSpacingY() const { return m_spacingy
; }
1581 Must be called in wxPGEditor::CreateControls() if primary editor window
1582 is wxTextCtrl, just before textctrl is created.
1584 Initial text value of created wxTextCtrl.
1586 void SetupTextCtrlValue( const wxString text
) { m_prevTcValue
= text
; }
1589 Unfocuses or closes editor if one was open, but does not deselect
1592 bool UnfocusEditor();
1594 virtual void SetWindowStyleFlag( long style
);
1596 void DrawItems( const wxPGProperty
* p1
, const wxPGProperty
* p2
);
1598 void DrawItem( wxPGProperty
* p
)
1603 virtual void DrawItemAndChildren( wxPGProperty
* p
);
1606 Draws item, children, and consequtive parents as long as category is
1609 void DrawItemAndValueRelated( wxPGProperty
* p
);
1614 wxPropertyGridPageState used by the grid is created here.
1616 If grid is used in wxPropertyGridManager, there is no point overriding
1617 this - instead, set custom wxPropertyGridPage classes.
1619 virtual wxPropertyGridPageState
* CreateState() const;
1621 enum PerformValidationFlags
1623 SendEvtChanging
= 0x0001,
1624 IsStandaloneValidation
= 0x0002 // Not called in response to event
1628 Runs all validation functionality (includes sending wxEVT_PG_CHANGING).
1629 Returns true if all tests passed. Implement in derived class to
1630 add additional validation behavior.
1632 virtual bool PerformValidation( wxPGProperty
* p
,
1633 wxVariant
& pendingValue
,
1634 int flags
= SendEvtChanging
);
1638 // Control font changer helper.
1639 void SetCurControlBoldFont();
1641 wxPGCell
& GetPropertyDefaultCell()
1643 return m_propertyDefaultCell
;
1646 wxPGCell
& GetCategoryDefaultCell()
1648 return m_categoryDefaultCell
;
1652 // Public methods for semi-public use
1654 bool DoSelectProperty( wxPGProperty
* p
, unsigned int flags
= 0 );
1656 // Overridden functions.
1657 virtual bool Destroy();
1658 // Returns property at given y coordinate (relative to grid's top left).
1659 wxPGProperty
* GetItemAtY( int y
) const { return DoGetItemAtY(y
); }
1661 virtual void Refresh( bool eraseBackground
= true,
1662 const wxRect
*rect
= (const wxRect
*) NULL
);
1663 virtual bool SetFont( const wxFont
& font
);
1664 #if wxPG_SUPPORT_TOOLTIPS
1665 void SetToolTip( const wxString
& tipString
);
1667 virtual void Freeze();
1668 virtual void SetExtraStyle( long exStyle
);
1669 virtual void Thaw();
1670 virtual bool Reparent( wxWindowBase
*newParent
);
1673 virtual wxSize
DoGetBestSize() const;
1675 #ifndef wxPG_ICON_WIDTH
1676 wxBitmap
*m_expandbmp
, *m_collbmp
;
1679 wxCursor
*m_cursorSizeWE
;
1681 /** wxWindow pointers to editor control(s). */
1682 wxWindow
*m_wndEditor
;
1683 wxWindow
*m_wndEditor2
;
1685 #if wxPG_DOUBLE_BUFFER
1686 wxBitmap
*m_doubleBuffer
;
1689 /** Local time ms when control was created. */
1690 wxLongLong m_timeCreated
;
1692 /** wxPGProperty::OnEvent can change value by setting this. */
1693 wxVariant m_changeInEventValue
;
1695 /** Id of m_wndEditor2, or its first child, if any. */
1698 /** Extra Y spacing between the items. */
1701 /** Control client area width; updated on resize. */
1704 /** Control client area height; updated on resize. */
1707 /** Current non-client width (needed when auto-centering). */
1710 /** Non-client width (auto-centering helper). */
1713 /** Previously recorded scroll start position. */
1717 The gutter spacing in front and back of the image.
1718 This determines the amount of spacing in front of each item
1722 /** Includes separator line. */
1725 /** Gutter*2 + image width. */
1728 // y spacing for expand/collapse button.
1729 int m_buttonSpacingY
;
1731 /** Extra margin for expanded sub-group items. */
1732 int m_subgroup_extramargin
;
1735 The image width of the [+] icon.
1737 This is also calculated in the gutter
1741 #ifndef wxPG_ICON_WIDTH
1744 The image height of the [+] icon.
1746 This is calculated as minimal size and to align
1751 /** Current cursor id. */
1755 This captionFont is made equal to the font of the wxScrolledWindow.
1757 As extra the bold face is set on it when this is wanted by the user
1760 wxFont m_captionFont
;
1762 int m_fontHeight
; // Height of the font.
1764 /** m_splitterx when drag began. */
1765 int m_startingSplitterX
;
1768 Index to splitter currently being dragged (0=one after the first
1771 int m_draggedSplitter
;
1773 /** Changed property, calculated in PerformValidation(). */
1774 wxPGProperty
* m_chgInfo_changedProperty
;
1777 Lowest property for which editing happened, but which does not have
1780 wxPGProperty
* m_chgInfo_baseChangedProperty
;
1782 /** Changed property value, calculated in PerformValidation(). */
1783 wxVariant m_chgInfo_pendingValue
;
1785 /** Passed to SetValue. */
1786 wxVariant m_chgInfo_valueList
;
1788 /** Validation information. */
1789 wxPGValidationInfo m_validationInfo
;
1791 /** Actions and keys that trigger them. */
1792 wxPGHashMapI2I m_actionTriggers
;
1794 /** Appearance of currently active editor. */
1795 wxPGCell m_editorAppearance
;
1797 /** Appearance of a unspecified value cell. */
1798 wxPGCell m_unspecifiedAppearance
;
1804 /** Bits are used to indicate which colours are customized. */
1805 unsigned short m_coloursCustomized
;
1807 /** x - m_splitterx. */
1808 signed char m_dragOffset
;
1810 /** 0 = not dragging, 1 = drag just started, 2 = drag in progress */
1811 unsigned char m_dragStatus
;
1813 /** 0 = margin, 1 = label, 2 = value. */
1814 unsigned char m_mouseSide
;
1816 /** True when editor control is focused. */
1817 unsigned char m_editorFocused
;
1819 /** 1 if m_latsCaption is also the bottommost caption. */
1820 //unsigned char m_lastCaptionBottomnest;
1822 /** Set to 1 when graphics frozen. */
1823 unsigned char m_frozen
;
1825 unsigned char m_vspacing
;
1827 // Used to track when Alt/Ctrl+Key was consumed.
1828 unsigned char m_keyComboConsumed
;
1830 /** 1 if in DoPropertyChanged() */
1831 unsigned char m_inDoPropertyChanged
;
1833 /** 1 if in CommitChangesFromEditor() */
1834 unsigned char m_inCommitChangesFromEditor
;
1836 /** 1 if in DoSelectProperty() */
1837 unsigned char m_inDoSelectProperty
;
1839 wxPGVFBFlags m_permanentValidationFailureBehavior
; // Set by app
1841 /** Internal flags - see wxPG_FL_XXX constants. */
1844 /** When drawing next time, clear this many item slots at the end. */
1845 int m_clearThisMany
;
1847 // Mouse is hovering over this column (index)
1848 unsigned int m_colHover
;
1850 // pointer to property that has mouse hovering
1851 wxPGProperty
* m_propHover
;
1853 // Active label editor
1854 wxTextCtrl
* m_labelEditor
;
1856 // For which property the label editor is active
1857 wxPGProperty
* m_labelEditorProperty
;
1859 // EventObject for wxPropertyGridEvents
1860 wxWindow
* m_eventObject
;
1862 // What (global) window is currently focused (needed to resolve event
1864 wxWindow
* m_curFocused
;
1866 // Event currently being sent - NULL if none at the moment
1867 wxPropertyGridEvent
* m_processedEvent
;
1869 // Last known top-level parent
1872 // Last closed top-level parent
1873 wxWindow
* m_tlpClosed
;
1875 // Local time ms when tlp was closed.
1876 wxLongLong m_tlpClosedTime
;
1879 wxPGSortCallback m_sortFunction
;
1881 // y coordinate of property that mouse hovering
1884 // Which column's editor is selected (usually 1)?
1885 unsigned int m_selColumn
;
1887 // x relative to splitter (needed for resize).
1890 // lines between cells
1892 // property labels and values are written in this colour
1893 wxColour m_colPropFore
;
1894 // or with this colour when disabled
1895 wxColour m_colDisPropFore
;
1896 // background for m_colPropFore
1897 wxColour m_colPropBack
;
1898 // text color for captions
1899 wxColour m_colCapFore
;
1900 // background color for captions
1901 wxColour m_colCapBack
;
1902 // foreground for selected property
1903 wxColour m_colSelFore
;
1904 // background for selected property (actually use background color when
1905 // control out-of-focus)
1906 wxColour m_colSelBack
;
1907 // background colour for margin
1908 wxColour m_colMargin
;
1909 // background colour for empty space below the grid
1910 wxColour m_colEmptySpace
;
1912 // Default property colours
1913 wxPGCell m_propertyDefaultCell
;
1915 // Default property category
1916 wxPGCell m_categoryDefaultCell
;
1918 // Backup of selected property's cells
1919 wxVector
<wxPGCell
> m_propCellsBackup
;
1921 // NB: These *cannot* be moved to globals.
1923 // labels when properties use common values
1924 wxVector
<wxPGCommonValue
*> m_commonValues
;
1926 // array of live events
1927 wxVector
<wxPropertyGridEvent
*> m_liveEvents
;
1929 // Which cv selection really sets value to unspecified?
1930 int m_cvUnspecified
;
1932 // Used to skip excess text editor events
1933 wxString m_prevTcValue
;
1937 // Sets some members to defaults (called constructors).
1940 // Initializes some members (called by Create and complex constructor).
1943 void OnPaint(wxPaintEvent
&event
);
1945 // main event receivers
1946 void OnMouseMove( wxMouseEvent
&event
);
1947 void OnMouseClick( wxMouseEvent
&event
);
1948 void OnMouseRightClick( wxMouseEvent
&event
);
1949 void OnMouseDoubleClick( wxMouseEvent
&event
);
1950 void OnMouseUp( wxMouseEvent
&event
);
1951 void OnKey( wxKeyEvent
&event
);
1952 void OnResize( wxSizeEvent
&event
);
1955 bool HandleMouseMove( int x
, unsigned int y
, wxMouseEvent
&event
);
1956 bool HandleMouseClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1957 bool HandleMouseRightClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1958 bool HandleMouseDoubleClick( int x
, unsigned int y
, wxMouseEvent
&event
);
1959 bool HandleMouseUp( int x
, unsigned int y
, wxMouseEvent
&event
);
1960 void HandleKeyEvent( wxKeyEvent
&event
, bool fromChild
);
1962 void OnMouseEntry( wxMouseEvent
&event
);
1964 void OnIdle( wxIdleEvent
&event
);
1965 void OnFocusEvent( wxFocusEvent
&event
);
1966 void OnChildFocusEvent( wxChildFocusEvent
& event
);
1968 bool OnMouseCommon( wxMouseEvent
&event
, int* px
, int *py
);
1969 bool OnMouseChildCommon( wxMouseEvent
&event
, int* px
, int *py
);
1971 // sub-control event handlers
1972 void OnMouseClickChild( wxMouseEvent
&event
);
1973 void OnMouseRightClickChild( wxMouseEvent
&event
);
1974 void OnMouseMoveChild( wxMouseEvent
&event
);
1975 void OnMouseUpChild( wxMouseEvent
&event
);
1976 void OnChildKeyDown( wxKeyEvent
&event
);
1978 void OnCaptureChange( wxMouseCaptureChangedEvent
&event
);
1980 void OnScrollEvent( wxScrollWinEvent
&event
);
1982 void OnSysColourChanged( wxSysColourChangedEvent
&event
);
1984 void OnTLPClose( wxCloseEvent
& event
);
1988 bool AddToSelectionFromInputEvent( wxPGProperty
* prop
,
1989 unsigned int colIndex
,
1990 wxMouseEvent
* event
= NULL
,
1994 Adjust the centering of the bitmap icons (collapse / expand) when the
1995 caption font changes.
1997 They need to be centered in the middle of the font, so a bit of deltaY
1998 adjustment is needed. On entry, m_captionFont must be set to window
1999 font. It will be modified properly.
2001 void CalculateFontAndBitmapStuff( int vspacing
);
2003 wxRect
GetEditorWidgetRect( wxPGProperty
* p
, int column
) const;
2005 void CorrectEditorWidgetSizeX();
2007 /** Called in RecalculateVirtualSize() to reposition control
2008 on virtual height changes.
2010 void CorrectEditorWidgetPosY();
2012 int DoDrawItems( wxDC
& dc
,
2013 const wxRect
* drawRect
,
2014 bool isBuffered
) const;
2016 /** Draws an expand/collapse (ie. +/-) button.
2018 virtual void DrawExpanderButton( wxDC
& dc
, const wxRect
& rect
,
2019 wxPGProperty
* property
) const;
2021 /** Draws items from topitemy to bottomitemy */
2022 void DrawItems( wxDC
& dc
,
2023 unsigned int topItemY
,
2024 unsigned int bottomItemY
,
2025 const wxRect
* drawRect
= NULL
);
2027 // Translate wxKeyEvent to wxPG_ACTION_XXX
2028 int KeyEventToActions(wxKeyEvent
&event
, int* pSecond
) const;
2030 int KeyEventToAction(wxKeyEvent
&event
) const
2032 return KeyEventToActions(event
, NULL
);
2035 void ImprovedClientToScreen( int* px
, int* py
);
2037 // Called by focus event handlers. newFocused is the window that becomes
2039 void HandleFocusChange( wxWindow
* newFocused
);
2041 /** Reloads all non-customized colours from system settings. */
2042 void RegainColours();
2044 bool DoEditorValidate();
2046 // Similar to DoSelectProperty() but also works on columns
2047 // other than 1. Does not active editor if column is not
2049 bool DoSelectAndEdit( wxPGProperty
* prop
,
2050 unsigned int colIndex
,
2051 unsigned int selFlags
);
2053 void DoSetSelection( const wxArrayPGProperty
& newSelection
,
2056 void DoSetSplitterPosition( int newxpos
,
2057 int splitterIndex
= 0,
2058 int flags
= wxPG_SPLITTER_REFRESH
);
2060 bool DoAddToSelection( wxPGProperty
* prop
,
2063 bool DoRemoveFromSelection( wxPGProperty
* prop
,
2066 void DoBeginLabelEdit( unsigned int colIndex
, int selFlags
= 0 );
2067 void DoEndLabelEdit( bool commit
, int selFlags
= 0 );
2068 void OnLabelEditorEnterPress( wxCommandEvent
& event
);
2069 void OnLabelEditorKeyPress( wxKeyEvent
& event
);
2071 wxPGProperty
* DoGetItemAtY( int y
) const;
2073 void DestroyEditorWnd( wxWindow
* wnd
);
2076 virtual bool DoExpand( wxPGProperty
* p
, bool sendEvent
= false );
2078 virtual bool DoCollapse( wxPGProperty
* p
, bool sendEvent
= false );
2080 // Returns nearest paint visible property (such that will be painted unless
2081 // window is scrolled or resized). If given property is paint visible, then
2082 // it itself will be returned.
2083 wxPGProperty
* GetNearestPaintVisible( wxPGProperty
* p
) const;
2085 static void RegisterDefaultEditors();
2087 // Sets up basic event handling for child control
2088 void SetupChildEventHandling( wxWindow
* wnd
);
2090 void CustomSetCursor( int type
, bool override
= false );
2093 Repositions scrollbar and underlying panel according to changed virtual
2096 void RecalculateVirtualSize( int forceXPos
= -1 );
2098 void SetEditorAppearance( const wxPGCell
& cell
,
2099 bool unspecified
= false );
2101 void ResetEditorAppearance()
2104 cell
.SetEmptyData();
2105 SetEditorAppearance(cell
, false);
2108 void PrepareAfterItemsAdded();
2111 Send event from the property grid.
2113 Omit the wxPG_SEL_NOVALIDATE flag to allow vetoing the event
2115 bool SendEvent( int eventType
, wxPGProperty
* p
,
2116 wxVariant
* pValue
= NULL
,
2117 unsigned int selFlags
= wxPG_SEL_NOVALIDATE
,
2118 unsigned int column
= 1 );
2120 void SetFocusOnCanvas();
2122 bool DoHideProperty( wxPGProperty
* p
, bool hide
, int flags
);
2126 bool ButtonTriggerKeyTest( int action
, wxKeyEvent
& event
);
2128 DECLARE_EVENT_TABLE()
2129 #endif // #ifndef SWIG
2132 // -----------------------------------------------------------------------
2134 // Bunch of inlines that need to resolved after all classes have been defined.
2138 inline bool wxPropertyGridPageState::IsDisplayed() const
2140 return ( this == m_pPropGrid
->GetState() );
2143 inline unsigned int wxPropertyGridPageState::GetActualVirtualHeight() const
2145 return DoGetRoot()->GetChildrenHeight(GetGrid()->GetRowHeight());
2149 inline int wxPGProperty::GetDisplayedCommonValueCount() const
2151 if ( HasFlag(wxPG_PROP_USES_COMMON_VALUE
) )
2153 wxPropertyGrid
* pg
= GetGrid();
2155 return (int) pg
->GetCommonValueCount();
2160 inline void wxPGProperty::SetDefaultValue( wxVariant
& value
)
2162 SetAttribute(wxPG_ATTR_DEFAULT_VALUE
, value
);
2165 inline void wxPGProperty::SetEditor( const wxString
& editorName
)
2167 m_customEditor
= wxPropertyGridInterface::GetEditorByName(editorName
);
2170 inline bool wxPGProperty::Hide( bool hide
, int flags
)
2172 return GetGrid()->HideProperty(this, hide
, flags
);
2175 inline bool wxPGProperty::SetMaxLength( int maxLen
)
2177 return GetGrid()->SetPropertyMaxLength(this,maxLen
);
2180 // -----------------------------------------------------------------------
2182 #define wxPG_BASE_EVT_PRE_ID 1775
2186 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_SELECTED
, wxPropertyGridEvent
);
2187 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_CHANGING
, wxPropertyGridEvent
);
2188 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_CHANGED
, wxPropertyGridEvent
);
2189 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_HIGHLIGHTED
, wxPropertyGridEvent
);
2190 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_RIGHT_CLICK
, wxPropertyGridEvent
);
2191 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_PAGE_CHANGED
, wxPropertyGridEvent
);
2192 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_ITEM_COLLAPSED
, wxPropertyGridEvent
);
2193 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_ITEM_EXPANDED
, wxPropertyGridEvent
);
2194 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
, wxEVT_PG_DOUBLE_CLICK
, wxPropertyGridEvent
);
2195 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
,
2196 wxEVT_PG_LABEL_EDIT_BEGIN
, wxPropertyGridEvent
);
2197 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
,
2198 wxEVT_PG_LABEL_EDIT_ENDING
, wxPropertyGridEvent
);
2199 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
,
2200 wxEVT_PG_COL_BEGIN_DRAG
, wxPropertyGridEvent
);
2201 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
,
2202 wxEVT_PG_COL_DRAGGING
, wxPropertyGridEvent
);
2203 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_PROPGRID
,
2204 wxEVT_PG_COL_END_DRAG
, wxPropertyGridEvent
);
2208 wxEVT_PG_SELECTED
= wxPG_BASE_EVT_PRE_ID
,
2211 wxEVT_PG_HIGHLIGHTED
,
2212 wxEVT_PG_RIGHT_CLICK
,
2213 wxEVT_PG_PAGE_CHANGED
,
2214 wxEVT_PG_ITEM_COLLAPSED
,
2215 wxEVT_PG_ITEM_EXPANDED
,
2216 wxEVT_PG_DOUBLE_CLICK
,
2217 wxEVT_PG_LABEL_EDIT_BEGIN
,
2218 wxEVT_PG_LABEL_EDIT_ENDING
,
2219 wxEVT_PG_COL_BEGIN_DRAG
,
2220 wxEVT_PG_COL_DRAGGING
,
2221 wxEVT_PG_COL_END_DRAG
2226 #define wxPG_BASE_EVT_TYPE wxEVT_PG_SELECTED
2227 #define wxPG_MAX_EVT_TYPE (wxPG_BASE_EVT_TYPE+30)
2231 typedef void (wxEvtHandler::*wxPropertyGridEventFunction
)(wxPropertyGridEvent
&);
2233 #define EVT_PG_SELECTED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_SELECTED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2234 #define EVT_PG_CHANGING(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGING, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2235 #define EVT_PG_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_CHANGED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2236 #define EVT_PG_HIGHLIGHTED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_HIGHLIGHTED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2237 #define EVT_PG_RIGHT_CLICK(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_RIGHT_CLICK, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2238 #define EVT_PG_DOUBLE_CLICK(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_DOUBLE_CLICK, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2239 #define EVT_PG_PAGE_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_PAGE_CHANGED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2240 #define EVT_PG_ITEM_COLLAPSED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_COLLAPSED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2241 #define EVT_PG_ITEM_EXPANDED(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_ITEM_EXPANDED, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2242 #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 ),
2243 #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 ),
2244 #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 ),
2245 #define EVT_PG_COL_DRAGGING(id, fn) DECLARE_EVENT_TABLE_ENTRY( wxEVT_PG_COL_DRAGGING, id, -1, wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn ), NULL ),
2246 #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 ),
2248 #define wxPropertyGridEventHandler(fn) \
2249 wxEVENT_HANDLER_CAST( wxPropertyGridEventFunction, fn )
2254 /** @class wxPropertyGridEvent
2256 A propertygrid event holds information about events associated with
2257 wxPropertyGrid objects.
2259 @library{wxpropgrid}
2262 class WXDLLIMPEXP_PROPGRID wxPropertyGridEvent
: public wxCommandEvent
2267 wxPropertyGridEvent(wxEventType commandType
=0, int id
=0);
2269 /** Copy constructor. */
2270 wxPropertyGridEvent(const wxPropertyGridEvent
& event
);
2273 ~wxPropertyGridEvent();
2276 virtual wxEvent
* Clone() const;
2279 Returns the column index associated with this event.
2280 For the column dragging events, it is the column to the left
2281 of the splitter being dragged
2283 unsigned int GetColumn() const
2288 wxPGProperty
* GetMainParent() const
2290 wxASSERT(m_property
);
2291 return m_property
->GetMainParent();
2294 /** Returns id of associated property. */
2295 wxPGProperty
* GetProperty() const
2300 wxPGValidationInfo
& GetValidationInfo()
2302 wxASSERT(m_validationInfo
);
2303 return *m_validationInfo
;
2306 /** Returns true if you can veto the action that the event is signaling.
2308 bool CanVeto() const { return m_canVeto
; }
2311 Call this from your event handler to veto action that the event is
2314 You can only veto a shutdown if wxPropertyGridEvent::CanVeto returns
2317 Currently only wxEVT_PG_CHANGING supports vetoing.
2319 void Veto( bool veto
= true ) { m_wasVetoed
= veto
; }
2322 Returns name of the associated property.
2324 @remarks Property name is stored in event, so it remains
2325 accessible even after the associated property or
2326 the property grid has been deleted.
2328 wxString
GetPropertyName() const
2330 return m_propertyName
;
2334 Returns value of the associated property. Works for all event
2335 types, but for wxEVT_PG_CHANGING this member function returns
2336 the value that is pending, so you can call Veto() if the
2337 value is not satisfactory.
2339 @remarks Property value is stored in event, so it remains
2340 accessible even after the associated property or
2341 the property grid has been deleted.
2343 wxVariant
GetPropertyValue() const
2345 if ( m_validationInfo
)
2346 return m_validationInfo
->GetValue();
2351 Returns value of the associated property.
2353 @see GetPropertyValue
2355 wxVariant
GetValue() const
2357 return GetPropertyValue();
2361 Set override validation failure behavior.
2363 Only effective if Veto was also called, and only allowed if event type
2364 is wxEVT_PG_CHANGING.
2366 void SetValidationFailureBehavior( wxPGVFBFlags flags
)
2368 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2369 m_validationInfo
->SetFailureBehavior( flags
);
2372 /** Sets custom failure message for this time only. Only applies if
2373 wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
2375 void SetValidationFailureMessage( const wxString
& message
)
2377 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2378 m_validationInfo
->SetFailureMessage( message
);
2382 wxPGVFBFlags
GetValidationFailureBehavior() const
2384 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2385 return m_validationInfo
->GetFailureBehavior();
2388 void SetColumn( unsigned int column
)
2393 void SetCanVeto( bool canVeto
) { m_canVeto
= canVeto
; }
2394 bool WasVetoed() const { return m_wasVetoed
; }
2396 /** Changes the associated property. */
2397 void SetProperty( wxPGProperty
* p
)
2401 m_propertyName
= p
->GetName();
2404 void SetPropertyValue( wxVariant value
)
2409 void SetPropertyGrid( wxPropertyGrid
* pg
)
2412 OnPropertyGridSet();
2415 void SetupValidationInfo()
2418 wxASSERT( GetEventType() == wxEVT_PG_CHANGING
);
2419 m_validationInfo
= &m_pg
->GetValidationInfo();
2420 m_value
= m_validationInfo
->GetValue();
2425 void OnPropertyGridSet();
2426 DECLARE_DYNAMIC_CLASS(wxPropertyGridEvent
)
2428 wxPGProperty
* m_property
;
2429 wxPropertyGrid
* m_pg
;
2430 wxPGValidationInfo
* m_validationInfo
;
2432 wxString m_propertyName
;
2435 unsigned int m_column
;
2444 // -----------------------------------------------------------------------
2446 /** @class wxPropertyGridPopulator
2448 Allows populating wxPropertyGrid from arbitrary text source.
2450 class WXDLLIMPEXP_PROPGRID wxPropertyGridPopulator
2453 /** Default constructor.
2455 wxPropertyGridPopulator();
2458 virtual ~wxPropertyGridPopulator();
2460 void SetState( wxPropertyGridPageState
* state
);
2462 void SetGrid( wxPropertyGrid
* pg
);
2464 /** Appends a new property under bottommost parent.
2466 Property class as string.
2468 wxPGProperty
* Add( const wxString
& propClass
,
2469 const wxString
& propLabel
,
2470 const wxString
& propName
,
2471 const wxString
* propValue
,
2472 wxPGChoices
* pChoices
= NULL
);
2475 Pushes property to the back of parent array (ie it becomes bottommost
2476 parent), and starts scanning/adding children for it.
2478 When finished, parent array is returned to the original state.
2480 void AddChildren( wxPGProperty
* property
);
2482 /** Adds attribute to the bottommost property.
2484 Allowed values: "string", (same as string), "int", "bool". Empty string
2487 bool AddAttribute( const wxString
& name
,
2488 const wxString
& type
,
2489 const wxString
& value
);
2491 /** Called once in AddChildren.
2493 virtual void DoScanForChildren() = 0;
2496 Returns id of parent property for which children can currently be
2499 wxPGProperty
* GetCurParent() const
2501 return (wxPGProperty
*) m_propHierarchy
[m_propHierarchy
.size()-1];
2504 wxPropertyGridPageState
* GetState() { return m_state
; }
2505 const wxPropertyGridPageState
* GetState() const { return m_state
; }
2507 /** Like wxString::ToLong, except allows N% in addition of N.
2509 static bool ToLongPCT( const wxString
& s
, long* pval
, long max
);
2511 /** Parses strings of format "choice1"[=value1] ... "choiceN"[=valueN] into
2512 wxPGChoices. Registers parsed result using idString (if not empty).
2513 Also, if choices with given id already registered, then don't parse but
2514 return those choices instead.
2516 wxPGChoices
ParseChoices( const wxString
& choicesString
,
2517 const wxString
& idString
);
2519 /** Implement in derived class to do custom process when an error occurs.
2520 Default implementation uses wxLogError.
2522 virtual void ProcessError( const wxString
& msg
);
2526 /** Used property grid. */
2527 wxPropertyGrid
* m_pg
;
2529 /** Used property grid state. */
2530 wxPropertyGridPageState
* m_state
;
2532 /** Tree-hierarchy of added properties (that can have children). */
2533 wxArrayPGProperty m_propHierarchy
;
2535 /** Hashmap for string-id to wxPGChoicesData mapping. */
2536 wxPGHashMapS2P m_dictIdChoices
;
2539 // -----------------------------------------------------------------------
2542 // Undefine macros that are not needed outside propertygrid sources
2544 #ifndef __wxPG_SOURCE_FILE__
2545 #undef wxPG_FL_DESC_REFRESH_REQUIRED
2546 #undef wxPG_FL_SCROLLBAR_DETECTED
2547 #undef wxPG_FL_CREATEDSTATE
2548 #undef wxPG_FL_NOSTATUSBARHELP
2549 #undef wxPG_FL_SCROLLED
2550 #undef wxPG_FL_FOCUS_INSIDE_CHILD
2551 #undef wxPG_FL_FOCUS_INSIDE
2552 #undef wxPG_FL_MOUSE_INSIDE_CHILD
2553 #undef wxPG_FL_CUR_USES_CUSTOM_IMAGE
2554 #undef wxPG_FL_PRIMARY_FILLS_ENTIRE
2555 #undef wxPG_FL_VALUE_MODIFIED
2556 #undef wxPG_FL_MOUSE_INSIDE
2557 #undef wxPG_FL_FOCUSED
2558 #undef wxPG_FL_MOUSE_CAPTURED
2559 #undef wxPG_FL_INITIALIZED
2560 #undef wxPG_FL_ACTIVATION_BY_CLICK
2561 #undef wxPG_SUPPORT_TOOLTIPS
2562 #undef wxPG_DOUBLE_BUFFER
2563 #undef wxPG_ICON_WIDTH
2564 #undef wxPG_USE_RENDERER_NATIVE
2565 // Following are needed by the manager headers
2566 // #undef const wxString&
2569 // -----------------------------------------------------------------------
2573 #endif // _WX_PROPGRID_PROPGRID_H_