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
159 /** Combines various styles.
161 #define wxPG_DEFAULT_STYLE (0)
163 /** Combines various styles.
165 #define wxPGMAN_DEFAULT_STYLE (0)
170 // -----------------------------------------------------------------------
173 @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
177 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
181 Prevents user from leaving property unless value is valid. If this
182 behavior flag is not used, then value change is instead cancelled.
184 wxPG_VFB_STAY_IN_PROPERTY
= 0x01,
187 Calls wxBell() on validation failure.
189 wxPG_VFB_BEEP
= 0x02,
192 Cell with invalid value will be marked (with red colour).
194 wxPG_VFB_MARK_CELL
= 0x04,
197 Display customizable text message explaining the situation.
199 wxPG_VFB_SHOW_MESSAGE
= 0x08,
204 wxPG_VFB_DEFAULT
= wxPG_VFB_STAY_IN_PROPERTY
|wxPG_VFB_BEEP
,
210 typedef wxByte wxPGVFBFlags
;
215 Used to convey validation information to and from functions that
216 actually perform validation. Mostly used in custom property
219 class wxPGValidationInfo
223 @return Returns failure behavior which is a combination of
224 @ref propgrid_vfbflags.
226 wxPGVFBFlags
GetFailureBehavior();
229 Returns current failure message.
231 const wxString
& GetFailureMessage() const;
234 Returns reference to pending value.
236 const wxVariant
& GetValue() const;
238 /** Set validation failure behavior
240 @param failureBehavior
241 Mixture of @ref propgrid_vfbflags.
243 void SetFailureBehavior(wxPGVFBFlags failureBehavior
);
246 Set current failure message.
248 void SetFailureMessage(const wxString
& message
);
251 // -----------------------------------------------------------------------
254 @section propgrid_keyboard_actions wxPropertyGrid Action Identifiers
255 These are used with wxPropertyGrid::AddActionTrigger() and
256 wxPropertyGrid::ClearActionTriggers().
260 enum wxPG_KEYBOARD_ACTIONS
262 wxPG_ACTION_INVALID
= 0,
263 wxPG_ACTION_NEXT_PROPERTY
,
264 wxPG_ACTION_PREV_PROPERTY
,
265 wxPG_ACTION_EXPAND_PROPERTY
,
266 wxPG_ACTION_COLLAPSE_PROPERTY
,
267 wxPG_ACTION_CANCEL_EDIT
,
277 // -----------------------------------------------------------------------
279 /** @class wxPropertyGrid
281 wxPropertyGrid is a specialized grid for editing properties - in other
282 words name = value pairs. List of ready-to-use property classes include
283 strings, numbers, flag sets, fonts, colours and many others. It is possible,
284 for example, to categorize properties, set up a complete tree-hierarchy,
285 add more than two columns, and set arbitrary per-property attributes.
287 Please note that most member functions are inherited and as such not
288 documented on this page. This means you will probably also want to read
289 wxPropertyGridInterface class reference.
291 See also @ref overview_propgrid.
293 @section propgrid_window_styles_ Window Styles
295 See @ref propgrid_window_styles.
297 @section propgrid_event_handling Event Handling
299 To process input from a property grid control, use these event handler macros
300 to direct input to member functions that take a wxPropertyGridEvent argument.
302 @beginEventTable{wxPropertyGridEvent}
303 @event{EVT_PG_SELECTED (id, func)}
304 Respond to wxEVT_PG_SELECTED event, generated when property value
305 has been changed by user.
306 @event{EVT_PG_CHANGING(id, func)}
307 Respond to wxEVT_PG_CHANGING event, generated when property value
308 is about to be changed by user. Use wxPropertyGridEvent::GetValue()
309 to take a peek at the pending value, and wxPropertyGridEvent::Veto()
310 to prevent change from taking place, if necessary.
311 @event{EVT_PG_HIGHLIGHTED(id, func)}
312 Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
313 moves over a property. Event's property is NULL if hovered area does
314 not belong to any property.
315 @event{EVT_PG_RIGHT_CLICK(id, func)}
316 Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
317 clicked on with right mouse button.
318 @event{EVT_PG_DOUBLE_CLICK(id, func)}
319 Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
320 double-clicked on with left mouse button.
321 @event{EVT_PG_ITEM_COLLAPSED(id, func)}
322 Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
323 a property or category.
324 @event{EVT_PG_ITEM_EXPANDED(id, func)}
325 Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
326 a property or category.
331 - Use Freeze() and Thaw() respectively to disable and enable drawing. This
332 will also delay sorting etc. miscellaneous calculations to the last
338 class wxPropertyGrid
: public wxScrolledWindow
, public wxPropertyGridInterface
343 Two step constructor. Call Create when this constructor is called to
344 build up the wxPropertyGrid
349 Constructor. The styles to be used are styles valid for
350 the wxWindow and wxScrolledWindow.
352 @see @ref propgrid_window_styles.
354 wxPropertyGrid( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
355 const wxPoint
& pos
= wxDefaultPosition
,
356 const wxSize
& size
= wxDefaultSize
,
357 long style
= wxPG_DEFAULT_STYLE
,
358 const wxChar
* name
= wxPropertyGridNameStr
);
361 virtual ~wxPropertyGrid();
364 Adds given key combination to trigger given action.
367 Which action to trigger. See @ref propgrid_keyboard_actions.
370 Which keycode triggers the action.
373 Which key event modifiers, in addition to keycode, are needed to
376 void AddActionTrigger( int action
, int keycode
, int modifiers
= 0 );
379 This static function enables or disables automatic use of
380 wxGetTranslation() for following strings: wxEnumProperty list labels,
381 wxFlagsProperty child property labels.
385 static void AutoGetTranslation( bool enable
);
388 Changes value of a property, as if from an editor. Use this instead of
389 SetPropertyValue() if you need the value to run through validation
390 process, and also send the property change event.
392 @return Returns true if value was successfully changed.
394 bool ChangePropertyValue( wxPGPropArg id
, wxVariant newValue
);
397 Centers the splitter. If argument is true, automatic splitter centering
398 is enabled (only applicable if style wxPG_SPLITTER_AUTO_CENTER was
401 void CenterSplitter( bool enable_auto_centering
= false );
404 Deletes all properties.
406 virtual void Clear();
409 Clears action triggers for given action.
412 Which action to trigger. @ref propgrid_keyboard_actions.
414 void ClearActionTriggers( int action
);
417 Forces updating the value of property from the editor control.
418 Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
419 ProcessEvent, meaning your event handlers will be called immediately.
421 @return Returns @true if anything was changed.
423 virtual bool CommitChangesFromEditor( wxUint32 flags
= 0 );
426 Two step creation. Whenever the control is created without any
427 parameters, use Create to actually create it. Don't access the control's
428 public methods before this is called
430 @see @ref propgrid_window_styles.
432 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
433 const wxPoint
& pos
= wxDefaultPosition
,
434 const wxSize
& size
= wxDefaultSize
,
435 long style
= wxPG_DEFAULT_STYLE
,
436 const wxChar
* name
= wxPropertyGridNameStr
);
439 Call when editor widget's contents is modified. For example, this is
440 called when changes text in wxTextCtrl (used in wxStringProperty and
443 @remarks This function should only be called by custom properties.
445 @see wxPGProperty::OnEvent()
447 void EditorsValueWasModified() { m_iFlags
|= wxPG_FL_VALUE_MODIFIED
; }
450 Reverse of EditorsValueWasModified().
452 @remarks This function should only be called by custom properties.
454 void EditorsValueWasNotModified()
456 m_iFlags
&= ~(wxPG_FL_VALUE_MODIFIED
);
460 Enables or disables (shows/hides) categories according to parameter
463 bool EnableCategories( bool enable
);
466 Scrolls and/or expands items to ensure that the given item is visible.
468 @return Returns @true if something was actually done.
470 bool EnsureVisible( wxPGPropArg id
);
473 Reduces column sizes to minimum possible, while still retaining
474 fully visible grid contents (labels, images).
476 @return Minimum size for the grid to still display everything.
478 @remarks Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
480 This function only works properly if grid size prior to call was
481 already fairly large.
483 Note that you can also get calculated column widths by calling
484 GetState->GetColumnWidth() immediately after this function
490 Returns wxWindow that the properties are painted on, and which should be
491 used as the parent for editor controls.
493 wxPanel
* GetPanel() const;
496 Returns current category caption background colour.
498 wxColour
GetCaptionBackgroundColour() const;
501 Returns current category caption font.
503 wxFont
& GetCaptionFont();
506 Returns current category caption text colour.
508 wxColour
GetCaptionForegroundColour() const;
511 Returns current cell background colour.
513 wxColour
GetCellBackgroundColour() const;
516 Returns current cell text colour when disabled.
518 wxColour
GetCellDisabledTextColour() const;
521 Returns current cell text colour.
523 wxColour
GetCellTextColour() const;
526 Returns number of columns currently on grid.
528 int GetColumnCount() const;
531 Returns colour of empty space below properties.
533 wxColour
GetEmptySpaceColour() const;
536 Returns height of highest characters of used font.
538 int GetFontHeight() const;
541 Returns pointer to itself. Dummy function that enables same kind
542 of code to use wxPropertyGrid and wxPropertyGridManager.
544 wxPropertyGrid
* GetGrid();
547 Returns rectangle of custom paint image.
550 Return image rectangle for this property.
553 Which choice of property to use (each choice may have
556 wxRect
GetImageRect( wxPGProperty
* property
, int item
) const;
559 Returns size of the custom paint image in front of property.
562 Return image rectangle for this property.
563 If this argument is NULL, then preferred size is returned.
566 Which choice of property to use (each choice may have
569 wxSize
GetImageSize( wxPGProperty
* property
= NULL
, int item
= -1 ) const;
572 Returns last item which could be iterated using given flags.
575 See @ref propgrid_iterator_flags.
577 wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
);
580 Returns colour of lines between cells.
582 wxColour
GetLineColour() const;
585 Returns background colour of margin.
587 wxColour
GetMarginColour() const;
590 Returns most up-to-date value of selected property. This will return
591 value different from GetSelectedProperty()->GetValue() only when text
592 editor is activate and string edited by user represents valid,
593 uncommitted property value.
595 wxVariant
GetUncommittedPropertyValue();
598 Returns cell background colour of a property.
600 wxColour
GetPropertyBackgroundColour( wxPGPropArg id
) const;
603 Returns cell background colour of a property.
605 wxColour
GetPropertyTextColour( wxPGPropArg id
) const;
608 Returns "root property". It does not have name, etc. and it is not
609 visible. It is only useful for accessing its children.
611 wxPGProperty
* GetRoot() const;
614 Returns height of a single grid row (in pixels).
616 int GetRowHeight() const;
619 Returns currently selected property.
621 wxPGProperty
* GetSelectedProperty() const;
624 Returns currently selected property.
626 wxPGProperty
* GetSelection() const;
629 Returns current selection background colour.
631 wxColour
GetSelectionBackgroundColour() const;
634 Returns current selection text colour.
636 wxColour
GetSelectionForegroundColour() const;
639 Returns current splitter x position.
641 int GetSplitterPosition() const;
644 Returns wxTextCtrl active in currently selected property, if any. Takes
645 wxOwnerDrawnComboBox into account.
647 wxTextCtrl
* GetEditorTextCtrl() const;
650 Returns current vertical spacing.
652 int GetVerticalSpacing() const { return (int)m_vspacing
; }
655 Returns true if editor's value was marked modified.
657 bool IsEditorsValueModified() const;
660 Returns information about arbitrary position in the grid.
662 wxPropertyGridHitTestResult
HitTest( const wxPoint
& pt
) const;
665 Returns true if any property has been modified by the user.
667 bool IsAnyModified() const;
670 Returns true if updating is frozen (ie. Freeze() called but not
673 bool IsFrozen() const;
676 Redraws given property.
678 virtual void RefreshProperty( wxPGProperty
* p
);
681 Registers a new editor class.
683 @return Returns pointer to the editor class instance that should be used.
685 static wxPGEditor
* RegisterEditorClass( wxPGEditor
* editor
,
686 const wxString
& name
,
687 bool noDefCheck
= false );
690 Resets all colours to the original system values.
695 Selects a property. Editor widget is automatically created, but
696 not focused unless focus is true. This will generate wxEVT_PG_SELECT
700 Property to select (name or pointer).
703 If @true, move keyboard focus to the created editor right away.
705 @return returns @true if selection finished successfully. Usually only
706 fails if current value in editor is not valid.
708 @see wxPropertyGrid::ClearSelection()
710 bool SelectProperty( wxPGPropArg id
, bool focus
= false );
713 Changes keyboard shortcut to push the editor button.
715 @remarks You can set default with keycode 0. Good value for the platform
716 is guessed, but don't expect it to be very accurate.
718 void SetButtonShortcut( int keycode
, bool ctrlDown
= false, bool altDown
= false );
721 Sets category caption background colour.
723 void SetCaptionBackgroundColour(const wxColour
& col
);
726 Sets category caption text colour.
728 void SetCaptionTextColour(const wxColour
& col
);
731 Sets default cell background colour - applies to property cells.
732 Note that appearance of editor widgets may not be affected.
734 void SetCellBackgroundColour(const wxColour
& col
);
737 Sets cell text colour for disabled properties.
739 void SetCellDisabledTextColour(const wxColour
& col
);
742 Sets default cell text colour - applies to property name and value text.
743 Note that appearance of editor widgets may not be affected.
745 void SetCellTextColour(const wxColour
& col
);
748 Set number of columns (2 or more).
750 void SetColumnCount( int colCount
);
753 Sets the 'current' category - Append will add non-category properties
756 void SetCurrentCategory( wxPGPropArg id
);
759 Sets colour of empty space below properties.
761 void SetEmptySpaceColour(const wxColour
& col
);
764 Sets colour of lines between cells.
766 void SetLineColour(const wxColour
& col
);
769 Sets background colour of margin.
771 void SetMarginColour(const wxColour
& col
);
774 Sets background colour of property and all its children. Colours of
775 captions are not affected. Background brush cache is optimized for often
776 set colours to be set last.
778 void SetPropertyBackgroundColour( wxPGPropArg id
, const wxColour
& col
);
781 Resets text and background colours of given property.
783 void SetPropertyColoursToDefault( wxPGPropArg id
);
786 Sets text colour of property and all its children.
788 void SetPropertyTextColour( wxPGPropArg id
, const wxColour
& col
,
789 bool recursively
= true );
791 /** Sets selection background colour - applies to selected property name
793 void SetSelectionBackgroundColour(const wxColour
& col
);
795 /** Sets selection foreground colour - applies to selected property name
797 void SetSelectionTextColour(const wxColour
& col
);
799 /** Sets x coordinate of the splitter.
801 @remarks Splitter position cannot exceed grid size, and therefore setting
802 it during form creation may fail as initial grid size is often
803 smaller than desired splitter position, especially when sizers
806 void SetSplitterPosition( int newxpos
, int col
= 0 );
809 Moves splitter as left as possible, while still allowing all
810 labels to be shown in full.
812 @param privateChildrenToo
813 If @false, will still allow private children to be cropped.
815 void SetSplitterLeft( bool privateChildrenToo
= false )
817 m_pState
->SetSplitterLeft(subProps
);
821 Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
822 height. Value of 2 should be default on most platforms.
824 void SetVerticalSpacing( int vspacing
);
827 Shows an brief error message that is related to a property.
829 void ShowPropertyError( wxPGPropArg id
, const wxString
& msg
);
832 Sorts all items at all levels (except private children).
837 Sorts children of a property.
839 void SortChildren( wxPGPropArg id
);
844 @class wxPropertyGridEvent
846 A property grid event holds information about events associated with
847 wxPropertyGrid objects.
852 class wxPropertyGridEvent
: public wxCommandEvent
857 wxPropertyGridEvent(wxEventType commandType
=0, int id
=0);
859 /** Copy constructor. */
860 wxPropertyGridEvent(const wxPropertyGridEvent
& event
);
863 ~wxPropertyGridEvent();
866 Returns true if you can veto the action that the event is signaling.
868 bool CanVeto() const { return m_canVeto
; }
871 virtual wxEvent
* Clone() const;
874 Returns highest level non-category, non-root parent of property for
875 which event occurred. Useful when you have nested properties with
878 @remarks If immediate parent is root or category, this will return the
881 wxPGProperty
* GetMainParent() const;
884 Returns property associated with this event.
886 wxPGProperty
* GetProperty() const;
889 Returns current validation failure flags.
891 wxPGVFBFlags
GetValidationFailureBehavior() const;
894 Returns value that is about to be set for wxEVT_PG_CHANGING.
896 const wxVariant
& GetValue() const;
899 Set if event can be vetoed.
901 void SetCanVeto( bool canVeto
);
903 /** Changes the property associated with this event. */
904 void SetProperty( wxPGProperty
* p
);
907 Set override validation failure behavior. Only effective if Veto() was
908 also called, and only allowed if event type is wxEVT_PG_CHANGING.
910 void SetValidationFailureBehavior( wxPGVFBFlags flags
);
913 Sets custom failure message for this time only. Only applies if
914 wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
916 void SetValidationFailureMessage( const wxString
& message
);
919 Call this from your event handler to veto action that the event is
920 signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto()
923 @remarks Currently only wxEVT_PG_CHANGING supports vetoing.
925 void Veto( bool veto
= true );
928 Returns @true if event was vetoed.
930 bool WasVetoed() const;