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 With this style Validators on properties will work same as in wxPropertyGrid
156 wxPG_EX_LEGACY_VALIDATORS
= 0x00800000,
159 Hides page selection buttons from tool bar.
161 wxPG_EX_HIDE_PAGE_BUTTONS
= 0x01000000
165 /** Combines various styles.
167 #define wxPG_DEFAULT_STYLE (0)
169 /** Combines various styles.
171 #define wxPGMAN_DEFAULT_STYLE (0)
176 // -----------------------------------------------------------------------
179 @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
183 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
187 Prevents user from leaving property unless value is valid. If this
188 behavior flag is not used, then value change is instead cancelled.
190 wxPG_VFB_STAY_IN_PROPERTY
= 0x01,
193 Calls wxBell() on validation failure.
195 wxPG_VFB_BEEP
= 0x02,
198 Cell with invalid value will be marked (with red colour).
200 wxPG_VFB_MARK_CELL
= 0x04,
203 Display customizable text message explaining the situation.
205 wxPG_VFB_SHOW_MESSAGE
= 0x08,
210 wxPG_VFB_DEFAULT
= wxPG_VFB_STAY_IN_PROPERTY
|wxPG_VFB_BEEP
,
216 typedef wxByte wxPGVFBFlags
;
218 // -----------------------------------------------------------------------
221 @section propgrid_keyboard_actions wxPropertyGrid Action Identifiers
222 These are used with wxPropertyGrid::AddActionTrigger() and
223 wxPropertyGrid::ClearActionTriggers().
227 enum wxPG_KEYBOARD_ACTIONS
229 wxPG_ACTION_INVALID
= 0,
230 wxPG_ACTION_NEXT_PROPERTY
,
231 wxPG_ACTION_PREV_PROPERTY
,
232 wxPG_ACTION_EXPAND_PROPERTY
,
233 wxPG_ACTION_COLLAPSE_PROPERTY
,
234 wxPG_ACTION_CANCEL_EDIT
,
244 // -----------------------------------------------------------------------
246 /** @class wxPropertyGrid
248 wxPropertyGrid is a specialized grid for editing properties - in other
249 words name = value pairs. List of ready-to-use property classes include
250 strings, numbers, flag sets, fonts, colours and many others. It is possible,
251 for example, to categorize properties, set up a complete tree-hierarchy,
252 add more than two columns, and set arbitrary per-property attributes.
254 Please note that most member functions are inherited and as such not
255 documented on this page. This means you will probably also want to read
256 wxPropertyGridInterface class reference.
258 See also @ref overview_propgrid.
260 @section propgrid_window_styles_ Window Styles
262 See @ref propgrid_window_styles.
264 @section propgrid_event_handling Event Handling
266 To process input from a property grid control, use these event handler macros
267 to direct input to member functions that take a wxPropertyGridEvent argument.
269 @beginEventTable{wxPropertyGridEvent}
270 @event{EVT_PG_SELECTED (id, func)}
271 Respond to wxEVT_PG_SELECTED event, generated when property value
272 has been changed by user.
273 @event{EVT_PG_CHANGING(id, func)}
274 Respond to wxEVT_PG_CHANGING event, generated when property value
275 is about to be changed by user. Use wxPropertyGridEvent::GetValue()
276 to take a peek at the pending value, and wxPropertyGridEvent::Veto()
277 to prevent change from taking place, if necessary.
278 @event{EVT_PG_HIGHLIGHTED(id, func)}
279 Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
280 moves over a property. Event's property is NULL if hovered area does
281 not belong to any property.
282 @event{EVT_PG_RIGHT_CLICK(id, func)}
283 Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
284 clicked on with right mouse button.
285 @event{EVT_PG_DOUBLE_CLICK(id, func)}
286 Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
287 double-clicked on with left mouse button.
288 @event{EVT_PG_ITEM_COLLAPSED(id, func)}
289 Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
290 a property or category.
291 @event{EVT_PG_ITEM_EXPANDED(id, func)}
292 Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
293 a property or category.
298 - Use Freeze() and Thaw() respectively to disable and enable drawing. This
299 will also delay sorting etc. miscellaneous calculations to the last
305 class wxPropertyGrid
: public wxScrolledWindow
, public wxPropertyGridInterface
310 Two step constructor. Call Create when this constructor is called to
311 build up the wxPropertyGrid
316 Constructor. The styles to be used are styles valid for
317 the wxWindow and wxScrolledWindow.
319 @see @ref propgrid_window_styles.
321 wxPropertyGrid( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
322 const wxPoint
& pos
= wxDefaultPosition
,
323 const wxSize
& size
= wxDefaultSize
,
324 long style
= wxPG_DEFAULT_STYLE
,
325 const wxChar
* name
= wxPropertyGridNameStr
);
328 virtual ~wxPropertyGrid();
331 Adds given key combination to trigger given action.
334 Which action to trigger. See @ref propgrid_keyboard_actions.
337 Which keycode triggers the action.
340 Which key event modifiers, in addition to keycode, are needed to
343 void AddActionTrigger( int action
, int keycode
, int modifiers
= 0 );
346 This static function enables or disables automatic use of
347 wxGetTranslation() for following strings: wxEnumProperty list labels,
348 wxFlagsProperty child property labels.
352 static void AutoGetTranslation( bool enable
);
355 Changes value of a property, as if from an editor. Use this instead of
356 SetPropertyValue() if you need the value to run through validation
357 process, and also send the property change event.
359 @return Returns true if value was successfully changed.
361 bool ChangePropertyValue( wxPGPropArg id
, wxVariant newValue
);
364 Centers the splitter. If argument is true, automatic splitter centering
365 is enabled (only applicable if style wxPG_SPLITTER_AUTO_CENTER was
368 void CenterSplitter( bool enable_auto_centering
= false );
371 Deletes all properties.
373 virtual void Clear();
376 Clears action triggers for given action.
379 Which action to trigger. @ref propgrid_keyboard_actions.
381 void ClearActionTriggers( int action
);
384 Forces updating the value of property from the editor control.
385 Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
386 ProcessEvent, meaning your event handlers will be called immediately.
388 @return Returns @true if anything was changed.
390 virtual bool CommitChangesFromEditor( wxUint32 flags
= 0 );
393 Two step creation. Whenever the control is created without any
394 parameters, use Create to actually create it. Don't access the control's
395 public methods before this is called
397 @see @ref propgrid_window_styles.
399 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
400 const wxPoint
& pos
= wxDefaultPosition
,
401 const wxSize
& size
= wxDefaultSize
,
402 long style
= wxPG_DEFAULT_STYLE
,
403 const wxChar
* name
= wxPropertyGridNameStr
);
406 Call when editor widget's contents is modified. For example, this is
407 called when changes text in wxTextCtrl (used in wxStringProperty and
410 @remarks This function should only be called by custom properties.
412 @see wxPGProperty::OnEvent()
414 void EditorsValueWasModified() { m_iFlags
|= wxPG_FL_VALUE_MODIFIED
; }
417 Reverse of EditorsValueWasModified().
419 @remarks This function should only be called by custom properties.
421 void EditorsValueWasNotModified()
423 m_iFlags
&= ~(wxPG_FL_VALUE_MODIFIED
);
427 Enables or disables (shows/hides) categories according to parameter
430 bool EnableCategories( bool enable
);
433 Scrolls and/or expands items to ensure that the given item is visible.
435 @return Returns @true if something was actually done.
437 bool EnsureVisible( wxPGPropArg id
);
440 Reduces column sizes to minimum possible, while still retaining
441 fully visible grid contents (labels, images).
443 @return Minimum size for the grid to still display everything.
445 @remarks Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
447 This function only works properly if grid size prior to call was
448 already fairly large.
450 Note that you can also get calculated column widths by calling
451 GetState->GetColumnWidth() immediately after this function
457 Returns wxWindow that the properties are painted on, and which should be
458 used as the parent for editor controls.
460 wxPanel
* GetPanel() const;
463 Returns current category caption background colour.
465 wxColour
GetCaptionBackgroundColour() const;
468 Returns current category caption font.
470 wxFont
& GetCaptionFont();
473 Returns current category caption text colour.
475 wxColour
GetCaptionForegroundColour() const;
478 Returns current cell background colour.
480 wxColour
GetCellBackgroundColour() const;
483 Returns current cell text colour when disabled.
485 wxColour
GetCellDisabledTextColour() const;
488 Returns current cell text colour.
490 wxColour
GetCellTextColour() const;
493 Returns number of columns currently on grid.
495 int GetColumnCount() const;
498 Returns colour of empty space below properties.
500 wxColour
GetEmptySpaceColour() const;
503 Returns height of highest characters of used font.
505 int GetFontHeight() const;
508 Returns pointer to itself. Dummy function that enables same kind
509 of code to use wxPropertyGrid and wxPropertyGridManager.
511 wxPropertyGrid
* GetGrid();
514 Returns rectangle of custom paint image.
517 Return image rectangle for this property.
520 Which choice of property to use (each choice may have
523 wxRect
GetImageRect( wxPGProperty
* property
, int item
) const;
526 Returns size of the custom paint image in front of property.
529 Return image rectangle for this property.
530 If this argument is NULL, then preferred size is returned.
533 Which choice of property to use (each choice may have
536 wxSize
GetImageSize( wxPGProperty
* property
= NULL
, int item
= -1 ) const;
539 Returns last item which could be iterated using given flags.
542 See @ref propgrid_iterator_flags.
544 wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
);
547 Returns colour of lines between cells.
549 wxColour
GetLineColour() const;
552 Returns background colour of margin.
554 wxColour
GetMarginColour() const;
557 Returns cell background colour of a property.
559 wxColour
GetPropertyBackgroundColour( wxPGPropArg id
) const;
562 Returns cell background colour of a property.
564 wxColour
GetPropertyTextColour( wxPGPropArg id
) const;
567 Returns "root property". It does not have name, etc. and it is not
568 visible. It is only useful for accessing its children.
570 wxPGProperty
* GetRoot() const;
573 Returns height of a single grid row (in pixels).
575 int GetRowHeight() const;
578 Returns currently selected property.
580 wxPGProperty
* GetSelectedProperty() const;
583 Returns currently selected property.
585 wxPGProperty
* GetSelection() const;
588 Returns current selection background colour.
590 wxColour
GetSelectionBackgroundColour() const;
593 Returns current selection text colour.
595 wxColour
GetSelectionForegroundColour() const;
598 Returns current splitter x position.
600 int GetSplitterPosition() const;
603 Returns wxTextCtrl active in currently selected property, if any. Takes
604 wxOwnerDrawnComboBox into account.
606 wxTextCtrl
* GetEditorTextCtrl() const;
609 Returns current vertical spacing.
611 int GetVerticalSpacing() const { return (int)m_vspacing
; }
614 Returns true if editor's value was marked modified.
616 bool IsEditorsValueModified() const;
619 Returns information about arbitrary position in the grid.
621 wxPropertyGridHitTestResult
HitTest( const wxPoint
& pt
) const;
624 Returns true if any property has been modified by the user.
626 bool IsAnyModified() const;
629 Returns true if updating is frozen (ie. Freeze() called but not
632 bool IsFrozen() const;
635 Redraws given property.
637 virtual void RefreshProperty( wxPGProperty
* p
);
640 Registers a new editor class.
642 @return Returns pointer to the editor class instance that should be used.
644 static wxPGEditor
* RegisterEditorClass( wxPGEditor
* editor
,
645 const wxString
& name
,
646 bool noDefCheck
= false );
649 Resets all colours to the original system values.
654 Selects a property. Editor widget is automatically created, but
655 not focused unless focus is true. This will generate wxEVT_PG_SELECT
659 Property to select (name or pointer).
662 If @true, move keyboard focus to the created editor right away.
664 @return returns @true if selection finished successfully. Usually only
665 fails if current value in editor is not valid.
667 @see wxPropertyGrid::ClearSelection()
669 bool SelectProperty( wxPGPropArg id
, bool focus
= false );
672 Changes keyboard shortcut to push the editor button.
674 @remarks You can set default with keycode 0. Good value for the platform
675 is guessed, but don't expect it to be very accurate.
677 void SetButtonShortcut( int keycode
, bool ctrlDown
= false, bool altDown
= false );
680 Sets category caption background colour.
682 void SetCaptionBackgroundColour(const wxColour
& col
);
685 Sets category caption text colour.
687 void SetCaptionTextColour(const wxColour
& col
);
690 Sets default cell background colour - applies to property cells.
691 Note that appearance of editor widgets may not be affected.
693 void SetCellBackgroundColour(const wxColour
& col
);
696 Sets cell text colour for disabled properties.
698 void SetCellDisabledTextColour(const wxColour
& col
);
701 Sets default cell text colour - applies to property name and value text.
702 Note that appearance of editor widgets may not be affected.
704 void SetCellTextColour(const wxColour
& col
);
707 Set number of columns (2 or more).
709 void SetColumnCount( int colCount
);
712 Sets the 'current' category - Append will add non-category properties
715 void SetCurrentCategory( wxPGPropArg id
);
718 Sets colour of empty space below properties.
720 void SetEmptySpaceColour(const wxColour
& col
);
723 Sets colour of lines between cells.
725 void SetLineColour(const wxColour
& col
);
728 Sets background colour of margin.
730 void SetMarginColour(const wxColour
& col
);
733 Sets background colour of property and all its children. Colours of
734 captions are not affected. Background brush cache is optimized for often
735 set colours to be set last.
737 void SetPropertyBackgroundColour( wxPGPropArg id
, const wxColour
& col
);
740 Resets text and background colours of given property.
742 void SetPropertyColoursToDefault( wxPGPropArg id
);
745 Sets text colour of property and all its children.
747 void SetPropertyTextColour( wxPGPropArg id
, const wxColour
& col
,
748 bool recursively
= true );
750 /** Sets selection background colour - applies to selected property name
752 void SetSelectionBackgroundColour(const wxColour
& col
);
754 /** Sets selection foreground colour - applies to selected property name
756 void SetSelectionTextColour(const wxColour
& col
);
758 /** Sets x coordinate of the splitter.
760 @remarks Splitter position cannot exceed grid size, and therefore setting
761 it during form creation may fail as initial grid size is often
762 smaller than desired splitter position, especially when sizers
765 void SetSplitterPosition( int newxpos
, int col
= 0 );
768 Sets name of a property.
771 Name or pointer of property which name to change.
776 void SetPropertyName( wxPGPropArg id
, const wxString
& newname
);
779 Moves splitter as left as possible, while still allowing all
780 labels to be shown in full.
782 @param privateChildrenToo
783 If @false, will still allow private children to be cropped.
785 void SetSplitterLeft( bool privateChildrenToo
= false )
787 m_pState
->SetSplitterLeft(subProps
);
791 Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
792 height. Value of 2 should be default on most platforms.
794 void SetVerticalSpacing( int vspacing
);
797 Shows an brief error message that is related to a property.
799 void ShowPropertyError( wxPGPropArg id
, const wxString
& msg
);
802 Sorts all items at all levels (except private children).
807 Sorts children of a property.
809 void SortChildren( wxPGPropArg id
);
814 @class wxPropertyGridEvent
816 A property grid event holds information about events associated with
817 wxPropertyGrid objects.
822 class wxPropertyGridEvent
: public wxCommandEvent
827 wxPropertyGridEvent(wxEventType commandType
=0, int id
=0);
829 /** Copy constructor. */
830 wxPropertyGridEvent(const wxPropertyGridEvent
& event
);
833 ~wxPropertyGridEvent();
836 Returns true if you can veto the action that the event is signaling.
838 bool CanVeto() const { return m_canVeto
; }
841 virtual wxEvent
* Clone() const;
844 Returns highest level non-category, non-root parent of property for
845 which event occurred. Useful when you have nested properties with
848 @remarks If immediate parent is root or category, this will return the
851 wxPGProperty
* GetMainParent() const;
854 Returns property associated with this event.
856 wxPGProperty
* GetProperty() const;
859 Returns current validation failure flags.
861 wxPGVFBFlags
GetValidationFailureBehavior() const;
864 Returns value that is about to be set for wxEVT_PG_CHANGING.
866 const wxVariant
& GetValue() const;
869 Set if event can be vetoed.
871 void SetCanVeto( bool canVeto
);
873 /** Changes the property associated with this event. */
874 void SetProperty( wxPGProperty
* p
);
877 Set override validation failure behavior. Only effective if Veto() was
878 also called, and only allowed if event type is wxEVT_PG_CHANGING.
880 void SetValidationFailureBehavior( int flags
);
883 Sets custom failure message for this time only. Only applies if
884 wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
886 void SetValidationFailureMessage( const wxString
& message
);
889 Call this from your event handler to veto action that the event is
890 signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto()
893 @remarks Currently only wxEVT_PG_CHANGING supports vetoing.
895 void Veto( bool veto
= true );
898 Returns @true if event was vetoed.
900 bool WasVetoed() const;