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,
94 /** wxPropertyGridManager only: don't show an internal border around the
95 property grid. Recommended if you use a header.
97 wxPG_NO_INTERNAL_BORDER
= 0x00004000
101 enum wxPG_EX_WINDOW_STYLES
105 NOTE: wxPG_EX_xxx are extra window styles and must be set using SetExtraStyle()
108 Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if
109 wxPG_HIDE_CATEGORIES is not defined, the non-categorized data storage is not
110 activated, and switching the mode first time becomes somewhat slower.
111 wxPG_EX_INIT_NOCAT activates the non-categorized data storage right away.
113 NOTE: If you do plan not switching to non-categoric mode, or if
114 you don't plan to use categories at all, then using this style will result
115 in waste of resources.
117 wxPG_EX_INIT_NOCAT
= 0x00001000,
120 Extended window style that sets wxPropertyGridManager tool bar to not
123 wxPG_EX_NO_FLAT_TOOLBAR
= 0x00002000,
126 Shows alphabetic/categoric mode buttons from tool bar.
128 wxPG_EX_MODE_BUTTONS
= 0x00008000,
131 Show property help strings as tool tips instead as text on the status bar.
132 You can set the help strings using SetPropertyHelpString member function.
134 wxPG_EX_HELP_AS_TOOLTIPS
= 0x00010000,
137 Allows relying on native double-buffering.
139 wxPG_EX_NATIVE_DOUBLE_BUFFERING
= 0x00080000,
142 Set this style to let user have ability to set values of properties to
143 unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for
146 wxPG_EX_AUTO_UNSPECIFIED_VALUES
= 0x00200000,
149 If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION and
150 wxPG_STRING_PASSWORD) are not stored into property's attribute storage (thus
151 they are not readable).
153 Note that this option is global, and applies to all wxPG property containers.
155 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES
= 0x00400000,
158 Hides page selection buttons from tool bar.
160 wxPG_EX_HIDE_PAGE_BUTTONS
= 0x01000000,
162 /** Allows multiple properties to be selected by user (by pressing SHIFT
163 when clicking on a property, or by dragging with left mouse button
166 You can get array of selected properties with
167 wxPropertyGridInterface::GetSelectedProperties(). In multiple selection
168 mode wxPropertyGridInterface::GetSelection() returns
169 property which has editor active (usually the first one
170 selected). Other useful member functions are ClearSelection(),
171 AddToSelection() and RemoveFromSelection().
173 wxPG_EX_MULTIPLE_SELECTION
= 0x02000000,
176 This enables top-level window tracking which allows wxPropertyGrid to
177 notify the application of last-minute property value changes by user.
179 This style is not enabled by default because it may cause crashes when
180 wxPropertyGrid is used in with wxAUI or similar system.
182 @remarks If you are not in fact using any system that may change
183 wxPropertyGrid's top-level parent window on its own, then you
184 are recommended to enable this style.
186 wxPG_EX_ENABLE_TLP_TRACKING
= 0x04000000,
188 /** Don't show divider above toolbar, on Windows.
190 wxPG_EX_NO_TOOLBAR_DIVIDER
= 0x04000000,
192 /** Show a separator below the toolbar.
194 wxPG_EX_TOOLBAR_SEPARATOR
= 0x08000000
198 /** Combines various styles.
200 #define wxPG_DEFAULT_STYLE (0)
202 /** Combines various styles.
204 #define wxPGMAN_DEFAULT_STYLE (0)
209 // -----------------------------------------------------------------------
212 @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
216 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
220 Prevents user from leaving property unless value is valid. If this
221 behavior flag is not used, then value change is instead cancelled.
223 wxPG_VFB_STAY_IN_PROPERTY
= 0x01,
226 Calls wxBell() on validation failure.
228 wxPG_VFB_BEEP
= 0x02,
231 Cell with invalid value will be marked (with red colour).
233 wxPG_VFB_MARK_CELL
= 0x04,
236 Display customizable text message explaining the situation.
238 wxPG_VFB_SHOW_MESSAGE
= 0x08,
243 wxPG_VFB_DEFAULT
= wxPG_VFB_STAY_IN_PROPERTY
|wxPG_VFB_BEEP
,
249 typedef wxByte wxPGVFBFlags
;
254 Used to convey validation information to and from functions that
255 actually perform validation. Mostly used in custom property classes.
257 class wxPGValidationInfo
261 @return Returns failure behavior which is a combination of
262 @ref propgrid_vfbflags.
264 wxPGVFBFlags
GetFailureBehavior();
267 Returns current failure message.
269 const wxString
& GetFailureMessage() const;
272 Returns reference to pending value.
274 wxVariant
& GetValue();
276 /** Set validation failure behavior
278 @param failureBehavior
279 Mixture of @ref propgrid_vfbflags.
281 void SetFailureBehavior(wxPGVFBFlags failureBehavior
);
284 Set current failure message.
286 void SetFailureMessage(const wxString
& message
);
289 // -----------------------------------------------------------------------
292 @section propgrid_keyboard_actions wxPropertyGrid Action Identifiers
294 These are used with wxPropertyGrid::AddActionTrigger() and
295 wxPropertyGrid::ClearActionTriggers().
299 enum wxPG_KEYBOARD_ACTIONS
301 wxPG_ACTION_INVALID
= 0,
302 wxPG_ACTION_NEXT_PROPERTY
,
303 wxPG_ACTION_PREV_PROPERTY
,
304 wxPG_ACTION_EXPAND_PROPERTY
,
305 wxPG_ACTION_COLLAPSE_PROPERTY
,
306 wxPG_ACTION_CANCEL_EDIT
,
313 /** This callback function is used for sorting properties.
315 Call wxPropertyGrid::SetSortFunction() to set it.
317 Sort function should return a value greater than 0 if position of p1 is
318 after p2. So, for instance, when comparing property names, you can use
319 following implementation:
322 int MyPropertySortFunction(wxPropertyGrid* propGrid,
326 return p1->GetBaseName().compare( p2->GetBaseName() );
330 typedef int (*wxPGSortCallback
)(wxPropertyGrid
* propGrid
,
334 // -----------------------------------------------------------------------
337 @class wxPropertyGrid
339 wxPropertyGrid is a specialized grid for editing properties - in other
340 words name = value pairs. List of ready-to-use property classes include
341 strings, numbers, flag sets, fonts, colours and many others. It is possible,
342 for example, to categorize properties, set up a complete tree-hierarchy,
343 add more than two columns, and set arbitrary per-property attributes.
345 Please note that most member functions are inherited and as such not
346 documented on this page. This means you will probably also want to read
347 wxPropertyGridInterface class reference.
349 See also @ref overview_propgrid.
351 @section propgrid_window_styles_ Window Styles
353 See @ref propgrid_window_styles.
355 @section propgrid_event_handling Event Handling
357 To process input from a property grid control, use these event handler macros
358 to direct input to member functions that take a wxPropertyGridEvent argument.
360 @beginEventEmissionTable{wxPropertyGridEvent}
361 @event{EVT_PG_SELECTED (id, func)}
362 Respond to wxEVT_PG_SELECTED event, generated when a property selection
363 has been changed, either by user action or by indirect program
364 function. For instance, collapsing a parent property programmatically
365 causes any selected child property to become unselected, and may
366 therefore cause this event to be generated.
367 @event{EVT_PG_CHANGED(id, func)}
368 Respond to wxEVT_PG_CHANGED event, generated when property value
369 has been changed by the user.
370 @event{EVT_PG_CHANGING(id, func)}
371 Respond to wxEVT_PG_CHANGING event, generated when property value
372 is about to be changed by user. Use wxPropertyGridEvent::GetValue()
373 to take a peek at the pending value, and wxPropertyGridEvent::Veto()
374 to prevent change from taking place, if necessary.
375 @event{EVT_PG_HIGHLIGHTED(id, func)}
376 Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
377 moves over a property. Event's property is NULL if hovered area does
378 not belong to any property.
379 @event{EVT_PG_RIGHT_CLICK(id, func)}
380 Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
381 clicked on with right mouse button.
382 @event{EVT_PG_DOUBLE_CLICK(id, func)}
383 Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
384 double-clicked on with left mouse button.
385 @event{EVT_PG_ITEM_COLLAPSED(id, func)}
386 Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
387 a property or category.
388 @event{EVT_PG_ITEM_EXPANDED(id, func)}
389 Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
390 a property or category.
391 @event{EVT_PG_LABEL_EDIT_BEGIN(id, func)}
392 Respond to wxEVT_PG_LABEL_EDIT_BEGIN event, generated when user is
393 about to begin editing a property label. You can veto this event to
395 @event{EVT_PG_LABEL_EDIT_ENDING(id, func)}
396 Respond to wxEVT_PG_LABEL_EDIT_ENDING event, generated when user is
397 about to end editing of a property label. You can veto this event to
399 @event{EVT_PG_COL_BEGIN_DRAG(id, func)}
400 Respond to wxEVT_PG_COL_BEGIN_DRAG event, generated when user
401 starts resizing a column - can be vetoed.
402 @event{EVT_PG_COL_DRAGGING,(id, func)}
403 Respond to wxEVT_PG_COL_DRAGGING, event, generated when a
404 column resize by user is in progress. This event is also generated
405 when user double-clicks the splitter in order to recenter
407 @event{EVT_PG_COL_END_DRAG(id, func)}
408 Respond to wxEVT_PG_COL_END_DRAG event, generated after column
409 resize by user has finished.
413 Use Freeze() and Thaw() respectively to disable and enable drawing.
414 This will also delay sorting etc. miscellaneous calculations to the last
419 @appearance{propertygrid.png}
421 class wxPropertyGrid
: public wxScrolledWindow
, public wxPropertyGridInterface
425 Two step constructor.
426 Call Create() when this constructor is called to build up the wxPropertyGrid
432 The styles to be used are styles valid for the wxWindow and wxScrolledWindow.
434 @see @ref propgrid_window_styles.
436 wxPropertyGrid( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
437 const wxPoint
& pos
= wxDefaultPosition
,
438 const wxSize
& size
= wxDefaultSize
,
439 long style
= wxPG_DEFAULT_STYLE
,
440 const wxChar
* name
= wxPropertyGridNameStr
);
443 virtual ~wxPropertyGrid();
446 Adds given key combination to trigger given action.
449 Which action to trigger. See @ref propgrid_keyboard_actions.
451 Which keycode triggers the action.
453 Which key event modifiers, in addition to keycode, are needed to
456 void AddActionTrigger( int action
, int keycode
, int modifiers
= 0 );
459 Adds given property into selection. If wxPG_EX_MULTIPLE_SELECTION
460 extra style is not used, then this has same effect as
461 calling SelectProperty().
463 @remarks Multiple selection is not supported for categories. This
464 means that if you have properties selected, you cannot
465 add category to selection, and also if you have category
466 selected, you cannot add other properties to selection.
467 This member function will fail silently in these cases,
470 bool AddToSelection( wxPGPropArg id
);
473 This static function enables or disables automatic use of
474 wxGetTranslation() for following strings: wxEnumProperty list labels,
475 wxFlagsProperty child property labels.
479 static void AutoGetTranslation( bool enable
);
482 Creates label editor wxTextCtrl for given column, for property
483 that is currently selected. When multiple selection is
484 enabled, this applies to whatever property GetSelection()
488 Which column's label to edit. Note that you should not
489 use value 1, which is reserved for property value
492 @see EndLabelEdit(), MakeColumnEditable()
494 void BeginLabelEdit( unsigned int column
= 0 );
497 Changes value of a property, as if from an editor. Use this instead of
498 SetPropertyValue() if you need the value to run through validation
499 process, and also send the property change event.
501 @return Returns true if value was successfully changed.
503 bool ChangePropertyValue( wxPGPropArg id
, wxVariant newValue
);
506 Centers the splitter. If argument is true, automatic splitter centering
507 is enabled (only applicable if style wxPG_SPLITTER_AUTO_CENTER was
510 void CenterSplitter( bool enable_auto_centering
= false );
513 Deletes all properties.
515 virtual void Clear();
518 Clears action triggers for given action.
521 Which action to trigger. @ref propgrid_keyboard_actions.
523 void ClearActionTriggers( int action
);
526 Forces updating the value of property from the editor control.
527 Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
528 ProcessEvent, meaning your event handlers will be called immediately.
530 @return Returns @true if anything was changed.
532 virtual bool CommitChangesFromEditor( wxUint32 flags
= 0 );
535 Two step creation. Whenever the control is created without any
536 parameters, use Create to actually create it. Don't access the control's
537 public methods before this is called
539 @see @ref propgrid_window_styles.
541 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
542 const wxPoint
& pos
= wxDefaultPosition
,
543 const wxSize
& size
= wxDefaultSize
,
544 long style
= wxPG_DEFAULT_STYLE
,
545 const wxChar
* name
= wxPropertyGridNameStr
);
548 Enables or disables (shows/hides) categories according to parameter
551 @remarks This functions deselects selected property, if any. Validation
552 failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie.
553 selection is cleared even if editor had invalid value.
555 bool EnableCategories( bool enable
);
558 Destroys label editor wxTextCtrl, if any.
561 Use @true (default) to store edited label text in
564 @see BeginLabelEdit(), MakeColumnEditable()
566 void EndLabelEdit( bool commit
= true );
569 Scrolls and/or expands items to ensure that the given item is visible.
571 @return Returns @true if something was actually done.
573 bool EnsureVisible( wxPGPropArg id
);
576 Reduces column sizes to minimum possible, while still retaining
577 fully visible grid contents (labels, images).
579 @return Minimum size for the grid to still display everything.
581 @remarks Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
583 This function only works properly if grid size prior to call was
584 already fairly large.
586 Note that you can also get calculated column widths by calling
587 GetState->GetColumnWidth() immediately after this function
593 Returns currently active label editor, NULL if none.
595 wxTextCtrl
* GetLabelEditor() const;
598 Returns wxWindow that the properties are painted on, and which should be
599 used as the parent for editor controls.
601 wxWindow
* GetPanel();
604 Returns current category caption background colour.
606 wxColour
GetCaptionBackgroundColour() const;
609 Returns current category caption font.
611 wxFont
& GetCaptionFont();
614 Returns current category caption text colour.
616 wxColour
GetCaptionForegroundColour() const;
619 Returns current cell background colour.
621 wxColour
GetCellBackgroundColour() const;
624 Returns current cell text colour when disabled.
626 wxColour
GetCellDisabledTextColour() const;
629 Returns current cell text colour.
631 wxColour
GetCellTextColour() const;
634 Returns number of columns currently on grid.
636 unsigned int GetColumnCount() const;
639 Returns colour of empty space below properties.
641 wxColour
GetEmptySpaceColour() const;
644 Returns height of highest characters of used font.
646 int GetFontHeight() const;
649 Returns pointer to itself. Dummy function that enables same kind
650 of code to use wxPropertyGrid and wxPropertyGridManager.
652 wxPropertyGrid
* GetGrid();
655 Returns rectangle of custom paint image.
658 Return image rectangle for this property.
661 Which choice of property to use (each choice may have
664 wxRect
GetImageRect( wxPGProperty
* property
, int item
) const;
667 Returns size of the custom paint image in front of property.
670 Return image rectangle for this property.
671 If this argument is NULL, then preferred size is returned.
674 Which choice of property to use (each choice may have
677 wxSize
GetImageSize( wxPGProperty
* property
= NULL
, int item
= -1 ) const;
680 Returns last item which could be iterated using given flags.
683 See @ref propgrid_iterator_flags.
685 wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
);
688 Returns colour of lines between cells.
690 wxColour
GetLineColour() const;
693 Returns background colour of margin.
695 wxColour
GetMarginColour() const;
698 Returns "root property". It does not have name, etc. and it is not
699 visible. It is only useful for accessing its children.
701 wxPGProperty
* GetRoot() const;
704 Returns height of a single grid row (in pixels).
706 int GetRowHeight() const;
709 Returns currently selected property.
711 wxPGProperty
* GetSelectedProperty() const;
714 Returns currently selected property.
716 wxPGProperty
* GetSelection() const;
719 Returns current selection background colour.
721 wxColour
GetSelectionBackgroundColour() const;
724 Returns current selection text colour.
726 wxColour
GetSelectionForegroundColour() const;
729 Returns the property sort function (default is @NULL).
733 wxPGSortCallback
GetSortFunction() const;
736 Returns current splitter x position.
738 int GetSplitterPosition() const;
741 Returns wxTextCtrl active in currently selected property, if any. Takes
742 wxOwnerDrawnComboBox into account.
744 wxTextCtrl
* GetEditorTextCtrl() const;
747 Returns current appearance of unspecified value cells.
749 @see SetUnspecifiedValueAppearance()
751 const wxPGCell
& GetUnspecifiedValueAppearance() const;
754 Returns (visual) text representation of the unspecified
757 @param argFlags For internal use only.
759 wxString
GetUnspecifiedValueText( int argFlags
= 0 ) const;
762 Returns current vertical spacing.
764 int GetVerticalSpacing() const;
767 Returns information about arbitrary position in the grid.
770 Coordinates in the virtual grid space. You may need to use
771 wxScrolledWindow::CalcScrolledPosition() for translating
772 wxPropertyGrid client coordinates into something this member
775 wxPropertyGridHitTestResult
HitTest( const wxPoint
& pt
) const;
778 Returns true if any property has been modified by the user.
780 bool IsAnyModified() const;
783 Returns @true if a property editor control has focus.
785 bool IsEditorFocused() const;
788 Returns true if updating is frozen (ie. Freeze() called but not
791 bool IsFrozen() const;
794 Makes given column editable by user.
797 Using @false here will disable column from being editable.
799 @see BeginLabelEdit(), EndLabelEdit()
801 void MakeColumnEditable( unsigned int column
, bool editable
= true );
804 It is recommended that you call this function any time your code causes
805 wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle()
806 handler should be able to detect most changes, but it is not perfect.
809 New top-level parent that is about to be set. Old top-level parent
810 window should still exist as the current one.
812 @remarks This function is automatically called from wxPropertyGrid::
813 Reparent() and wxPropertyGridManager::Reparent(). You only
814 need to use it if you reparent wxPropertyGrid indirectly.
816 void OnTLPChanging( wxWindow
* newTLP
);
819 Refreshes any active editor control.
821 void RefreshEditor();
824 Redraws given property.
826 virtual void RefreshProperty( wxPGProperty
* p
);
829 Registers a new editor class.
831 @return Returns pointer to the editor class instance that should be used.
833 static wxPGEditor
* RegisterEditorClass( wxPGEditor
* editor
,
834 const wxString
& name
,
835 bool noDefCheck
= false );
838 Resets all colours to the original system values.
843 Removes given property from selection. If property is not selected,
844 an assertion failure will occur.
846 bool RemoveFromSelection( wxPGPropArg id
);
849 Selects a property. Editor widget is automatically created, but
850 not focused unless focus is true.
853 Property to select (name or pointer).
856 If @true, move keyboard focus to the created editor right away.
858 @return returns @true if selection finished successfully. Usually only
859 fails if current value in editor is not valid.
861 @remarks In wxPropertyGrid 1.4, this member function used to generate
862 wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer
865 @remarks This clears any previous selection.
867 @see wxPropertyGridInterface::ClearSelection()
869 bool SelectProperty( wxPGPropArg id
, bool focus
= false );
872 Changes keyboard shortcut to push the editor button.
874 @remarks You can set default with keycode 0. Good value for the platform
875 is guessed, but don't expect it to be very accurate.
877 void SetButtonShortcut( int keycode
, bool ctrlDown
= false, bool altDown
= false );
880 Sets category caption background colour.
882 void SetCaptionBackgroundColour(const wxColour
& col
);
885 Sets category caption text colour.
887 void SetCaptionTextColour(const wxColour
& col
);
890 Sets default cell background colour - applies to property cells.
891 Note that appearance of editor widgets may not be affected.
893 void SetCellBackgroundColour(const wxColour
& col
);
896 Sets cell text colour for disabled properties.
898 void SetCellDisabledTextColour(const wxColour
& col
);
901 Sets default cell text colour - applies to property name and value text.
902 Note that appearance of editor widgets may not be affected.
904 void SetCellTextColour(const wxColour
& col
);
907 Set number of columns (2 or more).
909 void SetColumnCount( int colCount
);
912 Sets the 'current' category - Append will add non-category properties
915 void SetCurrentCategory( wxPGPropArg id
);
918 Sets colour of empty space below properties.
920 void SetEmptySpaceColour(const wxColour
& col
);
923 Sets colour of lines between cells.
925 void SetLineColour(const wxColour
& col
);
928 Sets background colour of margin.
930 void SetMarginColour(const wxColour
& col
);
933 Set entire new selection from given list of properties.
935 void SetSelection( const wxArrayPGProperty
& newSelection
);
938 Sets selection background colour - applies to selected property name
941 void SetSelectionBackgroundColour(const wxColour
& col
);
944 Sets selection foreground colour - applies to selected property name text.
946 void SetSelectionTextColour(const wxColour
& col
);
950 Sets the property sorting function.
953 The sorting function to be used. It should return a value greater
954 than 0 if position of p1 is after p2. So, for instance, when
955 comparing property names, you can use following implementation:
958 int MyPropertySortFunction(wxPropertyGrid* propGrid,
962 return p1->GetBaseName().compare( p2->GetBaseName() );
967 Default property sort function sorts properties by their labels
968 (case-insensitively).
970 @see GetSortFunction, wxPropertyGridInterface::Sort,
971 wxPropertyGridInterface::SortChildren
973 void SetSortFunction( wxPGSortCallback sortFunction
);
976 Sets x coordinate of the splitter.
978 @remarks Splitter position cannot exceed grid size, and therefore setting
979 it during form creation may fail as initial grid size is often
980 smaller than desired splitter position, especially when sizers
983 void SetSplitterPosition( int newxpos
, int col
= 0 );
986 Moves splitter as left as possible, while still allowing all
987 labels to be shown in full.
989 @param privateChildrenToo
990 If @false, will still allow private children to be cropped.
992 void SetSplitterLeft( bool privateChildrenToo
= false );
995 Sets appearance of value cells representing an unspecified property
996 value. Default appearance is blank.
998 @remarks If you set the unspecified value to have any
999 textual representation, then that will override
1000 "InlineHelp" attribute.
1002 @see wxPGProperty::SetValueToUnspecified(),
1003 wxPGProperty::IsValueUnspecified()
1005 void SetUnspecifiedValueAppearance( const wxPGCell
& cell
);
1008 Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
1009 height. Value of 2 should be default on most platforms.
1011 void SetVerticalSpacing( int vspacing
);
1015 @name Property development functions
1017 These member functions are usually only called when creating custom
1023 Call when editor widget's contents is modified. For example, this is
1024 called when changes text in wxTextCtrl (used in wxStringProperty and
1027 @remarks This function should only be called by custom properties.
1029 @see wxPGProperty::OnEvent()
1031 void EditorsValueWasModified();
1034 Reverse of EditorsValueWasModified().
1036 @remarks This function should only be called by custom properties.
1038 void EditorsValueWasNotModified();
1041 Returns most up-to-date value of selected property. This will return
1042 value different from GetSelectedProperty()->GetValue() only when text
1043 editor is activate and string edited by user represents valid,
1044 uncommitted property value.
1046 wxVariant
GetUncommittedPropertyValue();
1049 Returns true if editor's value was marked modified.
1051 bool IsEditorsValueModified() const;
1054 Shows an brief error message that is related to a property.
1056 void ShowPropertyError( wxPGPropArg id
, const wxString
& msg
);
1059 You can use this member function, for instance, to detect in
1060 wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was
1061 already called in wxPGEditor::OnEvent(). It really only detects
1062 if was value was changed using wxPGProperty::SetValueInEvent(), which
1063 is usually used when a 'picker' dialog is displayed. If value was
1064 written by "normal means" in wxPGProperty::StringToValue() or
1065 IntToValue(), then this function will return false (on the other hand,
1066 wxPGProperty::OnEvent() is not even called in those cases).
1068 bool WasValueChangedInEvent() const;
1075 @class wxPropertyGridEvent
1077 A property grid event holds information about events associated with
1078 wxPropertyGrid objects.
1080 @library{wxpropgrid}
1083 class wxPropertyGridEvent
: public wxCommandEvent
1088 wxPropertyGridEvent(wxEventType commandType
=0, int id
=0);
1090 /** Copy constructor. */
1091 wxPropertyGridEvent(const wxPropertyGridEvent
& event
);
1094 ~wxPropertyGridEvent();
1097 Returns true if you can veto the action that the event is signaling.
1099 bool CanVeto() const;
1102 Returns the column index associated with this event.
1103 For the column dragging events, it is the column to the left
1104 of the splitter being dragged
1106 unsigned int GetColumn() const;
1109 Returns highest level non-category, non-root parent of property for
1110 which event occurred. Useful when you have nested properties with
1113 @remarks If immediate parent is root or category, this will return the
1116 wxPGProperty
* GetMainParent() const;
1119 Returns property associated with this event.
1121 wxPGProperty
* GetProperty() const;
1124 Returns current validation failure flags.
1126 wxPGVFBFlags
GetValidationFailureBehavior() const;
1129 Returns name of the associated property.
1131 @remarks Property name is stored in event, so it remains
1132 accessible even after the associated property or
1133 the property grid has been deleted.
1135 wxString
GetPropertyName() const;
1138 Returns value of the associated property. Works for all event
1139 types, but for wxEVT_PG_CHANGING this member function returns
1140 the value that is pending, so you can call Veto() if the
1141 value is not satisfactory.
1143 @remarks Property value is stored in event, so it remains
1144 accessible even after the associated property or
1145 the property grid has been deleted.
1147 wxVariant
GetPropertyValue() const
1150 @see GetPropertyValue()
1152 wxVariant
GetValue() const;
1155 Set if event can be vetoed.
1157 void SetCanVeto( bool canVeto
);
1159 /** Changes the property associated with this event. */
1160 void SetProperty( wxPGProperty
* p
);
1163 Set override validation failure behavior. Only effective if Veto() was
1164 also called, and only allowed if event type is wxEVT_PG_CHANGING.
1166 void SetValidationFailureBehavior( wxPGVFBFlags flags
);
1169 Sets custom failure message for this time only. Only applies if
1170 wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
1172 void SetValidationFailureMessage( const wxString
& message
);
1175 Call this from your event handler to veto action that the event is
1176 signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto()
1179 @remarks Currently only wxEVT_PG_CHANGING supports vetoing.
1181 void Veto( bool veto
= true );
1184 Returns @true if event was vetoed.
1186 bool WasVetoed() const;