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 classes.
218 class wxPGValidationInfo
222 @return Returns failure behavior which is a combination of
223 @ref propgrid_vfbflags.
225 wxPGVFBFlags
GetFailureBehavior();
228 Returns current failure message.
230 const wxString
& GetFailureMessage() const;
233 Returns reference to pending value.
235 const wxVariant
& GetValue() const;
237 /** Set validation failure behavior
239 @param failureBehavior
240 Mixture of @ref propgrid_vfbflags.
242 void SetFailureBehavior(wxPGVFBFlags failureBehavior
);
245 Set current failure message.
247 void SetFailureMessage(const wxString
& message
);
250 // -----------------------------------------------------------------------
253 @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
,
274 /** This callback function is used for sorting properties.
276 Call wxPropertyGrid::SetSortFunction() to set it.
278 Sort function should return a value greater than 0 if position of p1 is
279 after p2. So, for instance, when comparing property names, you can use
280 following implementation:
283 int MyPropertySortFunction(wxPropertyGrid* propGrid,
287 return p1->GetBaseName().compare( p2->GetBaseName() );
291 typedef int (*wxPGSortCallback
)(wxPropertyGrid
* propGrid
,
295 // -----------------------------------------------------------------------
298 @class wxPropertyGrid
300 wxPropertyGrid is a specialized grid for editing properties - in other
301 words name = value pairs. List of ready-to-use property classes include
302 strings, numbers, flag sets, fonts, colours and many others. It is possible,
303 for example, to categorize properties, set up a complete tree-hierarchy,
304 add more than two columns, and set arbitrary per-property attributes.
306 Please note that most member functions are inherited and as such not
307 documented on this page. This means you will probably also want to read
308 wxPropertyGridInterface class reference.
310 See also @ref overview_propgrid.
312 @section propgrid_window_styles_ Window Styles
314 See @ref propgrid_window_styles.
316 @section propgrid_event_handling Event Handling
318 To process input from a property grid control, use these event handler macros
319 to direct input to member functions that take a wxPropertyGridEvent argument.
321 @beginEventEmissionTable{wxPropertyGridEvent}
322 @event{EVT_PG_SELECTED (id, func)}
323 Respond to wxEVT_PG_SELECTED event, generated when property value
324 has been changed by user.
325 @event{EVT_PG_CHANGING(id, func)}
326 Respond to wxEVT_PG_CHANGING event, generated when property value
327 is about to be changed by user. Use wxPropertyGridEvent::GetValue()
328 to take a peek at the pending value, and wxPropertyGridEvent::Veto()
329 to prevent change from taking place, if necessary.
330 @event{EVT_PG_HIGHLIGHTED(id, func)}
331 Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
332 moves over a property. Event's property is NULL if hovered area does
333 not belong to any property.
334 @event{EVT_PG_RIGHT_CLICK(id, func)}
335 Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
336 clicked on with right mouse button.
337 @event{EVT_PG_DOUBLE_CLICK(id, func)}
338 Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
339 double-clicked on with left mouse button.
340 @event{EVT_PG_ITEM_COLLAPSED(id, func)}
341 Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
342 a property or category.
343 @event{EVT_PG_ITEM_EXPANDED(id, func)}
344 Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
345 a property or category.
349 Use Freeze() and Thaw() respectively to disable and enable drawing.
350 This will also delay sorting etc. miscellaneous calculations to the last
355 @appearance{propertygrid.png}
357 class wxPropertyGrid
: public wxScrolledWindow
, public wxPropertyGridInterface
361 Two step constructor.
362 Call Create() when this constructor is called to build up the wxPropertyGrid
368 The styles to be used are styles valid for the wxWindow and wxScrolledWindow.
370 @see @ref propgrid_window_styles.
372 wxPropertyGrid( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
373 const wxPoint
& pos
= wxDefaultPosition
,
374 const wxSize
& size
= wxDefaultSize
,
375 long style
= wxPG_DEFAULT_STYLE
,
376 const wxChar
* name
= wxPropertyGridNameStr
);
379 virtual ~wxPropertyGrid();
382 Adds given key combination to trigger given action.
385 Which action to trigger. See @ref propgrid_keyboard_actions.
387 Which keycode triggers the action.
389 Which key event modifiers, in addition to keycode, are needed to
392 void AddActionTrigger( int action
, int keycode
, int modifiers
= 0 );
395 This static function enables or disables automatic use of
396 wxGetTranslation() for following strings: wxEnumProperty list labels,
397 wxFlagsProperty child property labels.
401 static void AutoGetTranslation( bool enable
);
404 Changes value of a property, as if from an editor. Use this instead of
405 SetPropertyValue() if you need the value to run through validation
406 process, and also send the property change event.
408 @return Returns true if value was successfully changed.
410 bool ChangePropertyValue( wxPGPropArg id
, wxVariant newValue
);
413 Centers the splitter. If argument is true, automatic splitter centering
414 is enabled (only applicable if style wxPG_SPLITTER_AUTO_CENTER was
417 void CenterSplitter( bool enable_auto_centering
= false );
420 Deletes all properties.
422 virtual void Clear();
425 Clears action triggers for given action.
428 Which action to trigger. @ref propgrid_keyboard_actions.
430 void ClearActionTriggers( int action
);
433 Forces updating the value of property from the editor control.
434 Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
435 ProcessEvent, meaning your event handlers will be called immediately.
437 @return Returns @true if anything was changed.
439 virtual bool CommitChangesFromEditor( wxUint32 flags
= 0 );
442 Two step creation. Whenever the control is created without any
443 parameters, use Create to actually create it. Don't access the control's
444 public methods before this is called
446 @see @ref propgrid_window_styles.
448 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
449 const wxPoint
& pos
= wxDefaultPosition
,
450 const wxSize
& size
= wxDefaultSize
,
451 long style
= wxPG_DEFAULT_STYLE
,
452 const wxChar
* name
= wxPropertyGridNameStr
);
455 Enables or disables (shows/hides) categories according to parameter
458 @remarks This functions deselects selected property, if any. Validation
459 failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie.
460 selection is cleared even if editor had invalid value.
462 bool EnableCategories( bool enable
);
465 Scrolls and/or expands items to ensure that the given item is visible.
467 @return Returns @true if something was actually done.
469 bool EnsureVisible( wxPGPropArg id
);
472 Reduces column sizes to minimum possible, while still retaining
473 fully visible grid contents (labels, images).
475 @return Minimum size for the grid to still display everything.
477 @remarks Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
479 This function only works properly if grid size prior to call was
480 already fairly large.
482 Note that you can also get calculated column widths by calling
483 GetState->GetColumnWidth() immediately after this function
489 Returns wxWindow that the properties are painted on, and which should be
490 used as the parent for editor controls.
492 wxPanel
* GetPanel() const;
495 Returns current category caption background colour.
497 wxColour
GetCaptionBackgroundColour() const;
500 Returns current category caption font.
502 wxFont
& GetCaptionFont();
505 Returns current category caption text colour.
507 wxColour
GetCaptionForegroundColour() const;
510 Returns current cell background colour.
512 wxColour
GetCellBackgroundColour() const;
515 Returns current cell text colour when disabled.
517 wxColour
GetCellDisabledTextColour() const;
520 Returns current cell text colour.
522 wxColour
GetCellTextColour() const;
525 Returns number of columns currently on grid.
527 unsigned int GetColumnCount() const;
530 Returns colour of empty space below properties.
532 wxColour
GetEmptySpaceColour() const;
535 Returns height of highest characters of used font.
537 int GetFontHeight() const;
540 Returns pointer to itself. Dummy function that enables same kind
541 of code to use wxPropertyGrid and wxPropertyGridManager.
543 wxPropertyGrid
* GetGrid();
546 Returns rectangle of custom paint image.
549 Return image rectangle for this property.
552 Which choice of property to use (each choice may have
555 wxRect
GetImageRect( wxPGProperty
* property
, int item
) const;
558 Returns size of the custom paint image in front of property.
561 Return image rectangle for this property.
562 If this argument is NULL, then preferred size is returned.
565 Which choice of property to use (each choice may have
568 wxSize
GetImageSize( wxPGProperty
* property
= NULL
, int item
= -1 ) const;
571 Returns last item which could be iterated using given flags.
574 See @ref propgrid_iterator_flags.
576 wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
);
579 Returns colour of lines between cells.
581 wxColour
GetLineColour() const;
584 Returns background colour of margin.
586 wxColour
GetMarginColour() const;
589 Returns "root property". It does not have name, etc. and it is not
590 visible. It is only useful for accessing its children.
592 wxPGProperty
* GetRoot() const;
595 Returns height of a single grid row (in pixels).
597 int GetRowHeight() const;
600 Returns currently selected property.
602 wxPGProperty
* GetSelectedProperty() const;
605 Returns currently selected property.
607 wxPGProperty
* GetSelection() const;
610 Returns current selection background colour.
612 wxColour
GetSelectionBackgroundColour() const;
615 Returns current selection text colour.
617 wxColour
GetSelectionForegroundColour() const;
620 Returns the property sort function (default is @NULL).
624 wxPGSortCallback
GetSortFunction() const;
627 Returns current splitter x position.
629 int GetSplitterPosition() const;
632 Returns wxTextCtrl active in currently selected property, if any. Takes
633 wxOwnerDrawnComboBox into account.
635 wxTextCtrl
* GetEditorTextCtrl() const;
638 Returns current vertical spacing.
640 int GetVerticalSpacing() const;
643 Returns information about arbitrary position in the grid.
646 Coordinates in the virtual grid space. You may need to use
647 wxScrolledWindow::CalcScrolledPosition() for translating
648 wxPropertyGrid client coordinates into something this member
651 wxPropertyGridHitTestResult
HitTest( const wxPoint
& pt
) const;
654 Returns true if any property has been modified by the user.
656 bool IsAnyModified() const;
659 Returns @true if a property editor control has focus.
661 bool IsEditorFocused() const;
664 Returns true if updating is frozen (ie. Freeze() called but not
667 bool IsFrozen() const;
670 It is recommended that you call this function any time your code causes
671 wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle()
672 handler should be able to detect most changes, but it is not perfect.
675 New top-level parent that is about to be set. Old top-level parent
676 window should still exist as the current one.
678 @remarks This function is automatically called from wxPropertyGrid::
679 Reparent() and wxPropertyGridManager::Reparent(). You only
680 need to use it if you reparent wxPropertyGrid indirectly.
682 void OnTLPChanging( wxWindow
* newTLP
);
685 Refreshes any active editor control.
687 void RefreshEditor();
690 Redraws given property.
692 virtual void RefreshProperty( wxPGProperty
* p
);
695 Registers a new editor class.
697 @return Returns pointer to the editor class instance that should be used.
699 static wxPGEditor
* RegisterEditorClass( wxPGEditor
* editor
,
700 const wxString
& name
,
701 bool noDefCheck
= false );
704 Resets all colours to the original system values.
709 Selects a property. Editor widget is automatically created, but
710 not focused unless focus is true. This will generate wxEVT_PG_SELECT
714 Property to select (name or pointer).
717 If @true, move keyboard focus to the created editor right away.
719 @return returns @true if selection finished successfully. Usually only
720 fails if current value in editor is not valid.
722 @see wxPropertyGrid::ClearSelection()
724 bool SelectProperty( wxPGPropArg id
, bool focus
= false );
727 Changes keyboard shortcut to push the editor button.
729 @remarks You can set default with keycode 0. Good value for the platform
730 is guessed, but don't expect it to be very accurate.
732 void SetButtonShortcut( int keycode
, bool ctrlDown
= false, bool altDown
= false );
735 Sets category caption background colour.
737 void SetCaptionBackgroundColour(const wxColour
& col
);
740 Sets category caption text colour.
742 void SetCaptionTextColour(const wxColour
& col
);
745 Sets default cell background colour - applies to property cells.
746 Note that appearance of editor widgets may not be affected.
748 void SetCellBackgroundColour(const wxColour
& col
);
751 Sets cell text colour for disabled properties.
753 void SetCellDisabledTextColour(const wxColour
& col
);
756 Sets default cell text colour - applies to property name and value text.
757 Note that appearance of editor widgets may not be affected.
759 void SetCellTextColour(const wxColour
& col
);
762 Set number of columns (2 or more).
764 void SetColumnCount( int colCount
);
767 Sets the 'current' category - Append will add non-category properties
770 void SetCurrentCategory( wxPGPropArg id
);
773 Sets colour of empty space below properties.
775 void SetEmptySpaceColour(const wxColour
& col
);
778 Sets colour of lines between cells.
780 void SetLineColour(const wxColour
& col
);
783 Sets background colour of margin.
785 void SetMarginColour(const wxColour
& col
);
788 Sets selection background colour - applies to selected property name
791 void SetSelectionBackgroundColour(const wxColour
& col
);
794 Sets selection foreground colour - applies to selected property name text.
796 void SetSelectionTextColour(const wxColour
& col
);
800 Sets the property sorting function.
803 The sorting function to be used. It should return a value greater
804 than 0 if position of p1 is after p2. So, for instance, when
805 comparing property names, you can use following implementation:
808 int MyPropertySortFunction(wxPropertyGrid* propGrid,
812 return p1->GetBaseName().compare( p2->GetBaseName() );
817 Default property sort function sorts properties by their labels
818 (case-insensitively).
820 @see GetSortFunction, wxPropertyGridInterface::Sort,
821 wxPropertyGridInterface::SortChildren
823 void SetSortFunction( wxPGSortCallback sortFunction
);
826 Sets x coordinate of the splitter.
828 @remarks Splitter position cannot exceed grid size, and therefore setting
829 it during form creation may fail as initial grid size is often
830 smaller than desired splitter position, especially when sizers
833 void SetSplitterPosition( int newxpos
, int col
= 0 );
836 Moves splitter as left as possible, while still allowing all
837 labels to be shown in full.
839 @param privateChildrenToo
840 If @false, will still allow private children to be cropped.
842 void SetSplitterLeft( bool privateChildrenToo
= false );
845 Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
846 height. Value of 2 should be default on most platforms.
848 void SetVerticalSpacing( int vspacing
);
852 @name Property development functions
854 These member functions are usually only called when creating custom
860 Call when editor widget's contents is modified. For example, this is
861 called when changes text in wxTextCtrl (used in wxStringProperty and
864 @remarks This function should only be called by custom properties.
866 @see wxPGProperty::OnEvent()
868 void EditorsValueWasModified();
871 Reverse of EditorsValueWasModified().
873 @remarks This function should only be called by custom properties.
875 void EditorsValueWasNotModified();
878 Returns most up-to-date value of selected property. This will return
879 value different from GetSelectedProperty()->GetValue() only when text
880 editor is activate and string edited by user represents valid,
881 uncommitted property value.
883 wxVariant
GetUncommittedPropertyValue();
886 Returns true if editor's value was marked modified.
888 bool IsEditorsValueModified() const;
891 Shows an brief error message that is related to a property.
893 void ShowPropertyError( wxPGPropArg id
, const wxString
& msg
);
896 You can use this member function, for instance, to detect in
897 wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was
898 already called in wxPGEditor::OnEvent(). It really only detects
899 if was value was changed using wxPGProperty::SetValueInEvent(), which
900 is usually used when a 'picker' dialog is displayed. If value was
901 written by "normal means" in wxPGProperty::StringToValue() or
902 IntToValue(), then this function will return false (on the other hand,
903 wxPGProperty::OnEvent() is not even called in those cases).
905 bool WasValueChangedInEvent() const;
912 @class wxPropertyGridEvent
914 A property grid event holds information about events associated with
915 wxPropertyGrid objects.
920 class wxPropertyGridEvent
: public wxCommandEvent
925 wxPropertyGridEvent(wxEventType commandType
=0, int id
=0);
927 /** Copy constructor. */
928 wxPropertyGridEvent(const wxPropertyGridEvent
& event
);
931 ~wxPropertyGridEvent();
934 Returns true if you can veto the action that the event is signaling.
936 bool CanVeto() const;
939 Returns highest level non-category, non-root parent of property for
940 which event occurred. Useful when you have nested properties with
943 @remarks If immediate parent is root or category, this will return the
946 wxPGProperty
* GetMainParent() const;
949 Returns property associated with this event.
951 wxPGProperty
* GetProperty() const;
954 Returns current validation failure flags.
956 wxPGVFBFlags
GetValidationFailureBehavior() const;
959 Returns value that is about to be set for wxEVT_PG_CHANGING.
961 const wxVariant
& GetValue() const;
964 Set if event can be vetoed.
966 void SetCanVeto( bool canVeto
);
968 /** Changes the property associated with this event. */
969 void SetProperty( wxPGProperty
* p
);
972 Set override validation failure behavior. Only effective if Veto() was
973 also called, and only allowed if event type is wxEVT_PG_CHANGING.
975 void SetValidationFailureBehavior( wxPGVFBFlags flags
);
978 Sets custom failure message for this time only. Only applies if
979 wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
981 void SetValidationFailureMessage( const wxString
& message
);
984 Call this from your event handler to veto action that the event is
985 signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto()
988 @remarks Currently only wxEVT_PG_CHANGING supports vetoing.
990 void Veto( bool veto
= true );
993 Returns @true if event was vetoed.
995 bool WasVetoed() const;