1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxPropertyGrid
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
11 @section propgrid_window_styles wxPropertyGrid Window Styles
13 SetWindowStyleFlag method can be used to modify some of these at run-time.
16 enum wxPG_WINDOW_STYLES
20 This will cause Sort() automatically after an item is added.
21 When inserting a lot of items in this mode, it may make sense to
22 use Freeze() before operations and Thaw() afterwards to increase
25 wxPG_AUTO_SORT
= 0x00000010,
28 Categories are not initially shown (even if added).
29 IMPORTANT NOTE: If you do not plan to use categories, then this
30 style will waste resources.
31 This flag can also be changed using wxPropertyGrid::EnableCategories method.
33 wxPG_HIDE_CATEGORIES
= 0x00000020,
36 This style combines non-categoric mode and automatic sorting.
38 wxPG_ALPHABETIC_MODE
= (wxPG_HIDE_CATEGORIES
|wxPG_AUTO_SORT
),
41 Modified values are shown in bold font. Changing this requires Refresh()
44 wxPG_BOLD_MODIFIED
= 0x00000040,
47 When wxPropertyGrid is resized, splitter moves to the center. This
48 behavior stops once the user manually moves the splitter.
50 wxPG_SPLITTER_AUTO_CENTER
= 0x00000080,
53 Display tool tips for cell text that cannot be shown completely. If
54 wxUSE_TOOLTIPS is 0, then this doesn't have any effect.
56 wxPG_TOOLTIPS
= 0x00000100,
59 Disables margin and hides all expand/collapse buttons that would appear
60 outside the margin (for sub-properties). Toggling this style automatically
61 expands all collapsed items.
63 wxPG_HIDE_MARGIN
= 0x00000200,
66 This style prevents user from moving the splitter.
68 wxPG_STATIC_SPLITTER
= 0x00000400,
71 Combination of other styles that make it impossible for user to modify
74 wxPG_STATIC_LAYOUT
= (wxPG_HIDE_MARGIN
|wxPG_STATIC_SPLITTER
),
77 Disables wxTextCtrl based editors for properties which
78 can be edited in another way. Equals calling
79 wxPropertyGrid::LimitPropertyEditing() for all added properties.
81 wxPG_LIMITED_EDITING
= 0x00000800,
84 wxPropertyGridManager only: Show tool bar for mode and page selection.
86 wxPG_TOOLBAR
= 0x00001000,
89 wxPropertyGridManager only: Show adjustable text box showing description
90 or help text, if available, for currently selected property.
92 wxPG_DESCRIPTION
= 0x00002000
96 enum wxPG_EX_WINDOW_STYLES
100 NOTE: wxPG_EX_xxx are extra window styles and must be set using SetExtraStyle()
103 Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if
104 wxPG_HIDE_CATEGORIES is not defined, the non-categorized data storage is not
105 activated, and switching the mode first time becomes somewhat slower.
106 wxPG_EX_INIT_NOCAT activates the non-categorized data storage right away.
108 NOTE: If you do plan not switching to non-categoric mode, or if
109 you don't plan to use categories at all, then using this style will result
110 in waste of resources.
112 wxPG_EX_INIT_NOCAT
= 0x00001000,
115 Extended window style that sets wxPropertyGridManager tool bar to not
118 wxPG_EX_NO_FLAT_TOOLBAR
= 0x00002000,
121 Shows alphabetic/categoric mode buttons from tool bar.
123 wxPG_EX_MODE_BUTTONS
= 0x00008000,
126 Show property help strings as tool tips instead as text on the status bar.
127 You can set the help strings using SetPropertyHelpString member function.
129 wxPG_EX_HELP_AS_TOOLTIPS
= 0x00010000,
132 Allows relying on native double-buffering.
134 wxPG_EX_NATIVE_DOUBLE_BUFFERING
= 0x00080000,
137 Set this style to let user have ability to set values of properties to
138 unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for
141 wxPG_EX_AUTO_UNSPECIFIED_VALUES
= 0x00200000,
144 If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION and
145 wxPG_STRING_PASSWORD) are not stored into property's attribute storage (thus
146 they are not readable).
148 Note that this option is global, and applies to all wxPG property containers.
150 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES
= 0x00400000,
153 Hides page selection buttons from tool bar.
155 wxPG_EX_HIDE_PAGE_BUTTONS
= 0x01000000,
157 /** Allows multiple properties to be selected by user (by pressing SHIFT
158 when clicking on a property, or by dragging with left mouse button
161 You can get array of selected properties with
162 wxPropertyGridInterface::GetSelectedProperties(). In multiple selection
163 mode wxPropertyGridInterface::GetSelection() returns
164 property which has editor active (usually the first one
165 selected). Other useful member functions are ClearSelection(),
166 AddToSelection() and RemoveFromSelection().
168 wxPG_EX_MULTIPLE_SELECTION
= 0x02000000,
171 This enables top-level window tracking which allows wxPropertyGrid to
172 notify the application of last-minute property value changes by user.
174 This style is not enabled by default because it may cause crashes when
175 wxPropertyGrid is used in with wxAUI or similar system.
177 @remarks If you are not in fact using any system that may change
178 wxPropertyGrid's top-level parent window on its own, then you
179 are recommended to enable this style.
181 wxPG_EX_ENABLE_TLP_TRACKING
= 0x04000000
185 /** Combines various styles.
187 #define wxPG_DEFAULT_STYLE (0)
189 /** Combines various styles.
191 #define wxPGMAN_DEFAULT_STYLE (0)
196 // -----------------------------------------------------------------------
199 @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
203 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
207 Prevents user from leaving property unless value is valid. If this
208 behavior flag is not used, then value change is instead cancelled.
210 wxPG_VFB_STAY_IN_PROPERTY
= 0x01,
213 Calls wxBell() on validation failure.
215 wxPG_VFB_BEEP
= 0x02,
218 Cell with invalid value will be marked (with red colour).
220 wxPG_VFB_MARK_CELL
= 0x04,
223 Display customizable text message explaining the situation.
225 wxPG_VFB_SHOW_MESSAGE
= 0x08,
230 wxPG_VFB_DEFAULT
= wxPG_VFB_STAY_IN_PROPERTY
|wxPG_VFB_BEEP
,
236 typedef wxByte wxPGVFBFlags
;
241 Used to convey validation information to and from functions that
242 actually perform validation. Mostly used in custom property classes.
244 class wxPGValidationInfo
248 @return Returns failure behavior which is a combination of
249 @ref propgrid_vfbflags.
251 wxPGVFBFlags
GetFailureBehavior();
254 Returns current failure message.
256 const wxString
& GetFailureMessage() const;
259 Returns reference to pending value.
261 const wxVariant
& GetValue() const;
263 /** Set validation failure behavior
265 @param failureBehavior
266 Mixture of @ref propgrid_vfbflags.
268 void SetFailureBehavior(wxPGVFBFlags failureBehavior
);
271 Set current failure message.
273 void SetFailureMessage(const wxString
& message
);
276 // -----------------------------------------------------------------------
279 @section propgrid_keyboard_actions wxPropertyGrid Action Identifiers
281 These are used with wxPropertyGrid::AddActionTrigger() and
282 wxPropertyGrid::ClearActionTriggers().
286 enum wxPG_KEYBOARD_ACTIONS
288 wxPG_ACTION_INVALID
= 0,
289 wxPG_ACTION_NEXT_PROPERTY
,
290 wxPG_ACTION_PREV_PROPERTY
,
291 wxPG_ACTION_EXPAND_PROPERTY
,
292 wxPG_ACTION_COLLAPSE_PROPERTY
,
293 wxPG_ACTION_CANCEL_EDIT
,
300 /** This callback function is used for sorting properties.
302 Call wxPropertyGrid::SetSortFunction() to set it.
304 Sort function should return a value greater than 0 if position of p1 is
305 after p2. So, for instance, when comparing property names, you can use
306 following implementation:
309 int MyPropertySortFunction(wxPropertyGrid* propGrid,
313 return p1->GetBaseName().compare( p2->GetBaseName() );
317 typedef int (*wxPGSortCallback
)(wxPropertyGrid
* propGrid
,
321 // -----------------------------------------------------------------------
324 @class wxPropertyGrid
326 wxPropertyGrid is a specialized grid for editing properties - in other
327 words name = value pairs. List of ready-to-use property classes include
328 strings, numbers, flag sets, fonts, colours and many others. It is possible,
329 for example, to categorize properties, set up a complete tree-hierarchy,
330 add more than two columns, and set arbitrary per-property attributes.
332 Please note that most member functions are inherited and as such not
333 documented on this page. This means you will probably also want to read
334 wxPropertyGridInterface class reference.
336 See also @ref overview_propgrid.
338 @section propgrid_window_styles_ Window Styles
340 See @ref propgrid_window_styles.
342 @section propgrid_event_handling Event Handling
344 To process input from a property grid control, use these event handler macros
345 to direct input to member functions that take a wxPropertyGridEvent argument.
347 @beginEventEmissionTable{wxPropertyGridEvent}
348 @event{EVT_PG_SELECTED (id, func)}
349 Respond to wxEVT_PG_SELECTED event, generated when a property selection
350 has been changed, either by user action or by indirect program
351 function. For instance, collapsing a parent property programmatically
352 causes any selected child property to become unselected, and may
353 therefore cause this event to be generated.
354 @event{EVT_PG_CHANGING(id, func)}
355 Respond to wxEVT_PG_CHANGING event, generated when property value
356 is about to be changed by user. Use wxPropertyGridEvent::GetValue()
357 to take a peek at the pending value, and wxPropertyGridEvent::Veto()
358 to prevent change from taking place, if necessary.
359 @event{EVT_PG_HIGHLIGHTED(id, func)}
360 Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
361 moves over a property. Event's property is NULL if hovered area does
362 not belong to any property.
363 @event{EVT_PG_RIGHT_CLICK(id, func)}
364 Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
365 clicked on with right mouse button.
366 @event{EVT_PG_DOUBLE_CLICK(id, func)}
367 Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
368 double-clicked on with left mouse button.
369 @event{EVT_PG_ITEM_COLLAPSED(id, func)}
370 Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
371 a property or category.
372 @event{EVT_PG_ITEM_EXPANDED(id, func)}
373 Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
374 a property or category.
375 @event{EVT_PG_LABEL_EDIT_BEGIN(id, func)}
376 Respond to wxEVT_PG_LABEL_EDIT_BEGIN event, generated when is about to
377 begin editing a property label. You can veto this event to prevent the
379 @event{EVT_PG_LABEL_EDIT_ENDING(id, func)}
380 Respond to wxEVT_PG_LABEL_EDIT_ENDING event, generated when is about to
381 end editing of a property label. You can veto this event to prevent the
386 Use Freeze() and Thaw() respectively to disable and enable drawing.
387 This will also delay sorting etc. miscellaneous calculations to the last
392 @appearance{propertygrid.png}
394 class wxPropertyGrid
: public wxScrolledWindow
, public wxPropertyGridInterface
398 Two step constructor.
399 Call Create() when this constructor is called to build up the wxPropertyGrid
405 The styles to be used are styles valid for the wxWindow and wxScrolledWindow.
407 @see @ref propgrid_window_styles.
409 wxPropertyGrid( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
410 const wxPoint
& pos
= wxDefaultPosition
,
411 const wxSize
& size
= wxDefaultSize
,
412 long style
= wxPG_DEFAULT_STYLE
,
413 const wxChar
* name
= wxPropertyGridNameStr
);
416 virtual ~wxPropertyGrid();
419 Adds given key combination to trigger given action.
422 Which action to trigger. See @ref propgrid_keyboard_actions.
424 Which keycode triggers the action.
426 Which key event modifiers, in addition to keycode, are needed to
429 void AddActionTrigger( int action
, int keycode
, int modifiers
= 0 );
432 Adds given property into selection. If wxPG_EX_MULTIPLE_SELECTION
433 extra style is not used, then this has same effect as
434 calling SelectProperty().
436 @remarks Multiple selection is not supported for categories. This
437 means that if you have properties selected, you cannot
438 add category to selection, and also if you have category
439 selected, you cannot add other properties to selection.
440 This member function will fail silently in these cases,
443 bool AddToSelection( wxPGPropArg id
);
446 This static function enables or disables automatic use of
447 wxGetTranslation() for following strings: wxEnumProperty list labels,
448 wxFlagsProperty child property labels.
452 static void AutoGetTranslation( bool enable
);
455 Creates label editor wxTextCtrl for given column, for property
456 that is currently selected. When multiple selection is
457 enabled, this applies to whatever property GetSelection()
461 Which column's label to edit. Note that you should not
462 use value 1, which is reserved for property value
465 @see EndLabelEdit(), MakeColumnEditable()
467 void BeginLabelEdit( unsigned int column
= 0 );
470 Changes value of a property, as if from an editor. Use this instead of
471 SetPropertyValue() if you need the value to run through validation
472 process, and also send the property change event.
474 @return Returns true if value was successfully changed.
476 bool ChangePropertyValue( wxPGPropArg id
, wxVariant newValue
);
479 Centers the splitter. If argument is true, automatic splitter centering
480 is enabled (only applicable if style wxPG_SPLITTER_AUTO_CENTER was
483 void CenterSplitter( bool enable_auto_centering
= false );
486 Deletes all properties.
488 virtual void Clear();
491 Clears action triggers for given action.
494 Which action to trigger. @ref propgrid_keyboard_actions.
496 void ClearActionTriggers( int action
);
499 Forces updating the value of property from the editor control.
500 Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
501 ProcessEvent, meaning your event handlers will be called immediately.
503 @return Returns @true if anything was changed.
505 virtual bool CommitChangesFromEditor( wxUint32 flags
= 0 );
508 Two step creation. Whenever the control is created without any
509 parameters, use Create to actually create it. Don't access the control's
510 public methods before this is called
512 @see @ref propgrid_window_styles.
514 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
515 const wxPoint
& pos
= wxDefaultPosition
,
516 const wxSize
& size
= wxDefaultSize
,
517 long style
= wxPG_DEFAULT_STYLE
,
518 const wxChar
* name
= wxPropertyGridNameStr
);
521 Enables or disables (shows/hides) categories according to parameter
524 @remarks This functions deselects selected property, if any. Validation
525 failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie.
526 selection is cleared even if editor had invalid value.
528 bool EnableCategories( bool enable
);
531 Destroys label editor wxTextCtrl, if any.
534 Use @true (default) to store edited label text in
537 @see BeginLabelEdit(), MakeColumnEditable()
539 void EndLabelEdit( bool commit
= true );
542 Scrolls and/or expands items to ensure that the given item is visible.
544 @return Returns @true if something was actually done.
546 bool EnsureVisible( wxPGPropArg id
);
549 Reduces column sizes to minimum possible, while still retaining
550 fully visible grid contents (labels, images).
552 @return Minimum size for the grid to still display everything.
554 @remarks Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
556 This function only works properly if grid size prior to call was
557 already fairly large.
559 Note that you can also get calculated column widths by calling
560 GetState->GetColumnWidth() immediately after this function
566 Returns currently active label editor, NULL if none.
568 wxTextCtrl
* GetLabelEditor() const;
571 Returns wxWindow that the properties are painted on, and which should be
572 used as the parent for editor controls.
574 wxPanel
* GetPanel() const;
577 Returns current category caption background colour.
579 wxColour
GetCaptionBackgroundColour() const;
582 Returns current category caption font.
584 wxFont
& GetCaptionFont();
587 Returns current category caption text colour.
589 wxColour
GetCaptionForegroundColour() const;
592 Returns current cell background colour.
594 wxColour
GetCellBackgroundColour() const;
597 Returns current cell text colour when disabled.
599 wxColour
GetCellDisabledTextColour() const;
602 Returns current cell text colour.
604 wxColour
GetCellTextColour() const;
607 Returns number of columns currently on grid.
609 unsigned int GetColumnCount() const;
612 Returns colour of empty space below properties.
614 wxColour
GetEmptySpaceColour() const;
617 Returns height of highest characters of used font.
619 int GetFontHeight() const;
622 Returns pointer to itself. Dummy function that enables same kind
623 of code to use wxPropertyGrid and wxPropertyGridManager.
625 wxPropertyGrid
* GetGrid();
628 Returns rectangle of custom paint image.
631 Return image rectangle for this property.
634 Which choice of property to use (each choice may have
637 wxRect
GetImageRect( wxPGProperty
* property
, int item
) const;
640 Returns size of the custom paint image in front of property.
643 Return image rectangle for this property.
644 If this argument is NULL, then preferred size is returned.
647 Which choice of property to use (each choice may have
650 wxSize
GetImageSize( wxPGProperty
* property
= NULL
, int item
= -1 ) const;
653 Returns last item which could be iterated using given flags.
656 See @ref propgrid_iterator_flags.
658 wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
);
661 Returns colour of lines between cells.
663 wxColour
GetLineColour() const;
666 Returns background colour of margin.
668 wxColour
GetMarginColour() const;
671 Returns "root property". It does not have name, etc. and it is not
672 visible. It is only useful for accessing its children.
674 wxPGProperty
* GetRoot() const;
677 Returns height of a single grid row (in pixels).
679 int GetRowHeight() const;
682 Returns currently selected property.
684 wxPGProperty
* GetSelectedProperty() const;
687 Returns currently selected property.
689 wxPGProperty
* GetSelection() const;
692 Returns current selection background colour.
694 wxColour
GetSelectionBackgroundColour() const;
697 Returns current selection text colour.
699 wxColour
GetSelectionForegroundColour() const;
702 Returns the property sort function (default is @NULL).
706 wxPGSortCallback
GetSortFunction() const;
709 Returns current splitter x position.
711 int GetSplitterPosition() const;
714 Returns wxTextCtrl active in currently selected property, if any. Takes
715 wxOwnerDrawnComboBox into account.
717 wxTextCtrl
* GetEditorTextCtrl() const;
720 Returns current vertical spacing.
722 int GetVerticalSpacing() const;
725 Returns information about arbitrary position in the grid.
728 Coordinates in the virtual grid space. You may need to use
729 wxScrolledWindow::CalcScrolledPosition() for translating
730 wxPropertyGrid client coordinates into something this member
733 wxPropertyGridHitTestResult
HitTest( const wxPoint
& pt
) const;
736 Returns true if any property has been modified by the user.
738 bool IsAnyModified() const;
741 Returns @true if a property editor control has focus.
743 bool IsEditorFocused() const;
746 Returns true if updating is frozen (ie. Freeze() called but not
749 bool IsFrozen() const;
752 Makes given column editable by user.
754 @see BeginLabelEdit(), EndLabelEdit()
756 void MakeColumnEditable( unsigned int column
);
759 It is recommended that you call this function any time your code causes
760 wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle()
761 handler should be able to detect most changes, but it is not perfect.
764 New top-level parent that is about to be set. Old top-level parent
765 window should still exist as the current one.
767 @remarks This function is automatically called from wxPropertyGrid::
768 Reparent() and wxPropertyGridManager::Reparent(). You only
769 need to use it if you reparent wxPropertyGrid indirectly.
771 void OnTLPChanging( wxWindow
* newTLP
);
774 Refreshes any active editor control.
776 void RefreshEditor();
779 Redraws given property.
781 virtual void RefreshProperty( wxPGProperty
* p
);
784 Registers a new editor class.
786 @return Returns pointer to the editor class instance that should be used.
788 static wxPGEditor
* RegisterEditorClass( wxPGEditor
* editor
,
789 const wxString
& name
,
790 bool noDefCheck
= false );
793 Resets all colours to the original system values.
798 Removes given property from selection. If property is not selected,
799 an assertion failure will occur.
801 bool RemoveFromSelection( wxPGPropArg id
);
804 Selects a property. Editor widget is automatically created, but
805 not focused unless focus is true.
808 Property to select (name or pointer).
811 If @true, move keyboard focus to the created editor right away.
813 @return returns @true if selection finished successfully. Usually only
814 fails if current value in editor is not valid.
816 @remarks In wxPropertyGrid 1.4, this member function used to generate
817 wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer
820 @remarks This clears any previous selection.
822 @see wxPropertyGridInterface::ClearSelection()
824 bool SelectProperty( wxPGPropArg id
, bool focus
= false );
827 Changes keyboard shortcut to push the editor button.
829 @remarks You can set default with keycode 0. Good value for the platform
830 is guessed, but don't expect it to be very accurate.
832 void SetButtonShortcut( int keycode
, bool ctrlDown
= false, bool altDown
= false );
835 Sets category caption background colour.
837 void SetCaptionBackgroundColour(const wxColour
& col
);
840 Sets category caption text colour.
842 void SetCaptionTextColour(const wxColour
& col
);
845 Sets default cell background colour - applies to property cells.
846 Note that appearance of editor widgets may not be affected.
848 void SetCellBackgroundColour(const wxColour
& col
);
851 Sets cell text colour for disabled properties.
853 void SetCellDisabledTextColour(const wxColour
& col
);
856 Sets default cell text colour - applies to property name and value text.
857 Note that appearance of editor widgets may not be affected.
859 void SetCellTextColour(const wxColour
& col
);
862 Set number of columns (2 or more).
864 void SetColumnCount( int colCount
);
867 Sets the 'current' category - Append will add non-category properties
870 void SetCurrentCategory( wxPGPropArg id
);
873 Sets colour of empty space below properties.
875 void SetEmptySpaceColour(const wxColour
& col
);
878 Sets colour of lines between cells.
880 void SetLineColour(const wxColour
& col
);
883 Sets background colour of margin.
885 void SetMarginColour(const wxColour
& col
);
888 Set entire new selection from given list of properties.
890 void SetSelection( const wxArrayPGProperty
& newSelection
);
893 Sets selection background colour - applies to selected property name
896 void SetSelectionBackgroundColour(const wxColour
& col
);
899 Sets selection foreground colour - applies to selected property name text.
901 void SetSelectionTextColour(const wxColour
& col
);
905 Sets the property sorting function.
908 The sorting function to be used. It should return a value greater
909 than 0 if position of p1 is after p2. So, for instance, when
910 comparing property names, you can use following implementation:
913 int MyPropertySortFunction(wxPropertyGrid* propGrid,
917 return p1->GetBaseName().compare( p2->GetBaseName() );
922 Default property sort function sorts properties by their labels
923 (case-insensitively).
925 @see GetSortFunction, wxPropertyGridInterface::Sort,
926 wxPropertyGridInterface::SortChildren
928 void SetSortFunction( wxPGSortCallback sortFunction
);
931 Sets x coordinate of the splitter.
933 @remarks Splitter position cannot exceed grid size, and therefore setting
934 it during form creation may fail as initial grid size is often
935 smaller than desired splitter position, especially when sizers
938 void SetSplitterPosition( int newxpos
, int col
= 0 );
941 Moves splitter as left as possible, while still allowing all
942 labels to be shown in full.
944 @param privateChildrenToo
945 If @false, will still allow private children to be cropped.
947 void SetSplitterLeft( bool privateChildrenToo
= false );
950 Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
951 height. Value of 2 should be default on most platforms.
953 void SetVerticalSpacing( int vspacing
);
957 @name Property development functions
959 These member functions are usually only called when creating custom
965 Call when editor widget's contents is modified. For example, this is
966 called when changes text in wxTextCtrl (used in wxStringProperty and
969 @remarks This function should only be called by custom properties.
971 @see wxPGProperty::OnEvent()
973 void EditorsValueWasModified();
976 Reverse of EditorsValueWasModified().
978 @remarks This function should only be called by custom properties.
980 void EditorsValueWasNotModified();
983 Returns most up-to-date value of selected property. This will return
984 value different from GetSelectedProperty()->GetValue() only when text
985 editor is activate and string edited by user represents valid,
986 uncommitted property value.
988 wxVariant
GetUncommittedPropertyValue();
991 Returns true if editor's value was marked modified.
993 bool IsEditorsValueModified() const;
996 Shows an brief error message that is related to a property.
998 void ShowPropertyError( wxPGPropArg id
, const wxString
& msg
);
1001 You can use this member function, for instance, to detect in
1002 wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was
1003 already called in wxPGEditor::OnEvent(). It really only detects
1004 if was value was changed using wxPGProperty::SetValueInEvent(), which
1005 is usually used when a 'picker' dialog is displayed. If value was
1006 written by "normal means" in wxPGProperty::StringToValue() or
1007 IntToValue(), then this function will return false (on the other hand,
1008 wxPGProperty::OnEvent() is not even called in those cases).
1010 bool WasValueChangedInEvent() const;
1017 @class wxPropertyGridEvent
1019 A property grid event holds information about events associated with
1020 wxPropertyGrid objects.
1022 @library{wxpropgrid}
1025 class wxPropertyGridEvent
: public wxCommandEvent
1030 wxPropertyGridEvent(wxEventType commandType
=0, int id
=0);
1032 /** Copy constructor. */
1033 wxPropertyGridEvent(const wxPropertyGridEvent
& event
);
1036 ~wxPropertyGridEvent();
1039 Returns true if you can veto the action that the event is signaling.
1041 bool CanVeto() const;
1044 Returns highest level non-category, non-root parent of property for
1045 which event occurred. Useful when you have nested properties with
1048 @remarks If immediate parent is root or category, this will return the
1051 wxPGProperty
* GetMainParent() const;
1054 Returns property associated with this event.
1056 wxPGProperty
* GetProperty() const;
1059 Returns current validation failure flags.
1061 wxPGVFBFlags
GetValidationFailureBehavior() const;
1064 Returns value that is about to be set for wxEVT_PG_CHANGING.
1066 const wxVariant
& GetValue() const;
1069 Set if event can be vetoed.
1071 void SetCanVeto( bool canVeto
);
1073 /** Changes the property associated with this event. */
1074 void SetProperty( wxPGProperty
* p
);
1077 Set override validation failure behavior. Only effective if Veto() was
1078 also called, and only allowed if event type is wxEVT_PG_CHANGING.
1080 void SetValidationFailureBehavior( wxPGVFBFlags flags
);
1083 Sets custom failure message for this time only. Only applies if
1084 wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
1086 void SetValidationFailureMessage( const wxString
& message
);
1089 Call this from your event handler to veto action that the event is
1090 signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto()
1093 @remarks Currently only wxEVT_PG_CHANGING supports vetoing.
1095 void Veto( bool veto
= true );
1098 Returns @true if event was vetoed.
1100 bool WasVetoed() const;