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 a text message explaining the situation.
238 To customize the way the message is displayed, you need to
239 reimplement wxPropertyGrid::DoShowPropertyError() in a
240 derived class. Default behavior is to display the text on
241 the top-level frame's status bar, if present, and otherwise
244 wxPG_VFB_SHOW_MESSAGE
= 0x08,
247 Similar to wxPG_VFB_SHOW_MESSAGE, except always displays the
248 message using wxMessageBox.
250 wxPG_VFB_SHOW_MESSAGEBOX
= 0x10,
253 Similar to wxPG_VFB_SHOW_MESSAGE, except always displays the
254 message on the status bar (when present - you can reimplement
255 wxPropertyGrid::GetStatusBar() in a derived class to specify
258 wxPG_VFB_SHOW_MESSAGE_ON_STATUSBAR
= 0x20,
263 wxPG_VFB_DEFAULT
= wxPG_VFB_MARK_CELL
|
264 wxPG_VFB_SHOW_MESSAGEBOX
,
270 typedef wxByte wxPGVFBFlags
;
275 Used to convey validation information to and from functions that
276 actually perform validation. Mostly used in custom property classes.
278 class wxPGValidationInfo
282 @return Returns failure behavior which is a combination of
283 @ref propgrid_vfbflags.
285 wxPGVFBFlags
GetFailureBehavior();
288 Returns current failure message.
290 const wxString
& GetFailureMessage() const;
293 Returns reference to pending value.
295 wxVariant
& GetValue();
297 /** Set validation failure behavior
299 @param failureBehavior
300 Mixture of @ref propgrid_vfbflags.
302 void SetFailureBehavior(wxPGVFBFlags failureBehavior
);
305 Set current failure message.
307 void SetFailureMessage(const wxString
& message
);
310 // -----------------------------------------------------------------------
313 @section propgrid_keyboard_actions wxPropertyGrid Action Identifiers
315 These are used with wxPropertyGrid::AddActionTrigger() and
316 wxPropertyGrid::ClearActionTriggers().
320 enum wxPG_KEYBOARD_ACTIONS
322 wxPG_ACTION_INVALID
= 0,
323 wxPG_ACTION_NEXT_PROPERTY
,
324 wxPG_ACTION_PREV_PROPERTY
,
325 wxPG_ACTION_EXPAND_PROPERTY
,
326 wxPG_ACTION_COLLAPSE_PROPERTY
,
327 wxPG_ACTION_CANCEL_EDIT
,
334 /** This callback function is used for sorting properties.
336 Call wxPropertyGrid::SetSortFunction() to set it.
338 Sort function should return a value greater than 0 if position of p1 is
339 after p2. So, for instance, when comparing property names, you can use
340 following implementation:
343 int MyPropertySortFunction(wxPropertyGrid* propGrid,
347 return p1->GetBaseName().compare( p2->GetBaseName() );
351 typedef int (*wxPGSortCallback
)(wxPropertyGrid
* propGrid
,
355 // -----------------------------------------------------------------------
358 @class wxPropertyGrid
360 wxPropertyGrid is a specialized grid for editing properties - in other
361 words name = value pairs. List of ready-to-use property classes include
362 strings, numbers, flag sets, fonts, colours and many others. It is possible,
363 for example, to categorize properties, set up a complete tree-hierarchy,
364 add more than two columns, and set arbitrary per-property attributes.
366 Please note that most member functions are inherited and as such not
367 documented on this page. This means you will probably also want to read
368 wxPropertyGridInterface class reference.
370 See also @ref overview_propgrid.
372 @section propgrid_window_styles_ Window Styles
374 See @ref propgrid_window_styles.
376 @section propgrid_event_handling Event Handling
378 To process input from a property grid control, use these event handler macros
379 to direct input to member functions that take a wxPropertyGridEvent argument.
381 @beginEventEmissionTable{wxPropertyGridEvent}
382 @event{EVT_PG_SELECTED (id, func)}
383 Respond to wxEVT_PG_SELECTED event, generated when a property selection
384 has been changed, either by user action or by indirect program
385 function. For instance, collapsing a parent property programmatically
386 causes any selected child property to become unselected, and may
387 therefore cause this event to be generated.
388 @event{EVT_PG_CHANGED(id, func)}
389 Respond to wxEVT_PG_CHANGED event, generated when property value
390 has been changed by the user.
391 @event{EVT_PG_CHANGING(id, func)}
392 Respond to wxEVT_PG_CHANGING event, generated when property value
393 is about to be changed by user. Use wxPropertyGridEvent::GetValue()
394 to take a peek at the pending value, and wxPropertyGridEvent::Veto()
395 to prevent change from taking place, if necessary.
396 @event{EVT_PG_HIGHLIGHTED(id, func)}
397 Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
398 moves over a property. Event's property is NULL if hovered area does
399 not belong to any property.
400 @event{EVT_PG_RIGHT_CLICK(id, func)}
401 Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
402 clicked on with right mouse button.
403 @event{EVT_PG_DOUBLE_CLICK(id, func)}
404 Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
405 double-clicked on with left mouse button.
406 @event{EVT_PG_ITEM_COLLAPSED(id, func)}
407 Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
408 a property or category.
409 @event{EVT_PG_ITEM_EXPANDED(id, func)}
410 Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
411 a property or category.
412 @event{EVT_PG_LABEL_EDIT_BEGIN(id, func)}
413 Respond to wxEVT_PG_LABEL_EDIT_BEGIN event, generated when user is
414 about to begin editing a property label. You can veto this event to
416 @event{EVT_PG_LABEL_EDIT_ENDING(id, func)}
417 Respond to wxEVT_PG_LABEL_EDIT_ENDING event, generated when user is
418 about to end editing of a property label. You can veto this event to
420 @event{EVT_PG_COL_BEGIN_DRAG(id, func)}
421 Respond to wxEVT_PG_COL_BEGIN_DRAG event, generated when user
422 starts resizing a column - can be vetoed.
423 @event{EVT_PG_COL_DRAGGING,(id, func)}
424 Respond to wxEVT_PG_COL_DRAGGING, event, generated when a
425 column resize by user is in progress. This event is also generated
426 when user double-clicks the splitter in order to recenter
428 @event{EVT_PG_COL_END_DRAG(id, func)}
429 Respond to wxEVT_PG_COL_END_DRAG event, generated after column
430 resize by user has finished.
434 Use Freeze() and Thaw() respectively to disable and enable drawing.
435 This will also delay sorting etc. miscellaneous calculations to the last
440 @appearance{propertygrid.png}
442 class wxPropertyGrid
: public wxScrolledWindow
, public wxPropertyGridInterface
446 Two step constructor.
447 Call Create() when this constructor is called to build up the wxPropertyGrid
453 The styles to be used are styles valid for the wxWindow and wxScrolledWindow.
455 @see @ref propgrid_window_styles.
457 wxPropertyGrid( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
458 const wxPoint
& pos
= wxDefaultPosition
,
459 const wxSize
& size
= wxDefaultSize
,
460 long style
= wxPG_DEFAULT_STYLE
,
461 const wxChar
* name
= wxPropertyGridNameStr
);
464 virtual ~wxPropertyGrid();
467 Adds given key combination to trigger given action.
469 Here is a sample code to make Enter key press move focus to
473 propGrid->AddActionTrigger(wxPG_ACTION_NEXT_PROPERTY,
475 propGrid->DedicateKey(WXK_RETURN);
479 Which action to trigger. See @ref propgrid_keyboard_actions.
481 Which keycode triggers the action.
483 Which key event modifiers, in addition to keycode, are needed to
486 void AddActionTrigger( int action
, int keycode
, int modifiers
= 0 );
489 Adds given property into selection. If wxPG_EX_MULTIPLE_SELECTION
490 extra style is not used, then this has same effect as
491 calling SelectProperty().
493 @remarks Multiple selection is not supported for categories. This
494 means that if you have properties selected, you cannot
495 add category to selection, and also if you have category
496 selected, you cannot add other properties to selection.
497 This member function will fail silently in these cases,
500 bool AddToSelection( wxPGPropArg id
);
503 This static function enables or disables automatic use of
504 wxGetTranslation() for following strings: wxEnumProperty list labels,
505 wxFlagsProperty child property labels.
509 static void AutoGetTranslation( bool enable
);
512 Creates label editor wxTextCtrl for given column, for property
513 that is currently selected. When multiple selection is
514 enabled, this applies to whatever property GetSelection()
518 Which column's label to edit. Note that you should not
519 use value 1, which is reserved for property value
522 @see EndLabelEdit(), MakeColumnEditable()
524 void BeginLabelEdit( unsigned int colIndex
= 0 );
527 Changes value of a property, as if from an editor. Use this instead of
528 SetPropertyValue() if you need the value to run through validation
529 process, and also send the property change event.
531 @return Returns true if value was successfully changed.
533 bool ChangePropertyValue( wxPGPropArg id
, wxVariant newValue
);
536 Centers the splitter.
538 @param enableAutoResizing
539 If @true, automatic column resizing is enabled (only applicapple
540 if window style wxPG_SPLITTER_AUTO_CENTER is used).
542 void CenterSplitter( bool enableAutoResizing
= false );
545 Deletes all properties.
547 virtual void Clear();
550 Clears action triggers for given action.
553 Which action to trigger. @ref propgrid_keyboard_actions.
555 void ClearActionTriggers( int action
);
558 Forces updating the value of property from the editor control.
559 Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
560 ProcessEvent, meaning your event handlers will be called immediately.
562 @return Returns @true if anything was changed.
564 virtual bool CommitChangesFromEditor( wxUint32 flags
= 0 );
567 Two step creation. Whenever the control is created without any
568 parameters, use Create to actually create it. Don't access the control's
569 public methods before this is called
571 @see @ref propgrid_window_styles.
573 bool Create( wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
574 const wxPoint
& pos
= wxDefaultPosition
,
575 const wxSize
& size
= wxDefaultSize
,
576 long style
= wxPG_DEFAULT_STYLE
,
577 const wxChar
* name
= wxPropertyGridNameStr
);
580 Dedicates a specific keycode to wxPropertyGrid. This means that such
581 key presses will not be redirected to editor controls.
583 Using this function allows, for example, navigation between
584 properties using arrow keys even when the focus is in the editor
587 void DedicateKey( int keycode
);
590 Enables or disables (shows/hides) categories according to parameter
593 @remarks This functions deselects selected property, if any. Validation
594 failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie.
595 selection is cleared even if editor had invalid value.
597 bool EnableCategories( bool enable
);
600 Destroys label editor wxTextCtrl, if any.
603 Use @true (default) to store edited label text in
606 @see BeginLabelEdit(), MakeColumnEditable()
608 void EndLabelEdit( bool commit
= true );
611 Scrolls and/or expands items to ensure that the given item is visible.
613 @return Returns @true if something was actually done.
615 bool EnsureVisible( wxPGPropArg id
);
618 Reduces column sizes to minimum possible, while still retaining
619 fully visible grid contents (labels, images).
621 @return Minimum size for the grid to still display everything.
623 @remarks Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
625 This function only works properly if grid size prior to call was
626 already fairly large.
628 Note that you can also get calculated column widths by calling
629 GetState->GetColumnWidth() immediately after this function
635 Returns currently active label editor, NULL if none.
637 wxTextCtrl
* GetLabelEditor() const;
640 Returns wxWindow that the properties are painted on, and which should be
641 used as the parent for editor controls.
643 wxWindow
* GetPanel();
646 Returns current category caption background colour.
648 wxColour
GetCaptionBackgroundColour() const;
651 Returns current category caption font.
653 wxFont
& GetCaptionFont();
656 Returns current category caption text colour.
658 wxColour
GetCaptionForegroundColour() const;
661 Returns current cell background colour.
663 wxColour
GetCellBackgroundColour() const;
666 Returns current cell text colour when disabled.
668 wxColour
GetCellDisabledTextColour() const;
671 Returns current cell text colour.
673 wxColour
GetCellTextColour() const;
676 Returns number of columns currently on grid.
678 unsigned int GetColumnCount() const;
681 Returns colour of empty space below properties.
683 wxColour
GetEmptySpaceColour() const;
686 Returns height of highest characters of used font.
688 int GetFontHeight() const;
691 Returns pointer to itself. Dummy function that enables same kind
692 of code to use wxPropertyGrid and wxPropertyGridManager.
694 wxPropertyGrid
* GetGrid();
697 Returns rectangle of custom paint image.
700 Return image rectangle for this property.
703 Which choice of property to use (each choice may have
706 wxRect
GetImageRect( wxPGProperty
* property
, int item
) const;
709 Returns size of the custom paint image in front of property.
712 Return image rectangle for this property.
713 If this argument is NULL, then preferred size is returned.
716 Which choice of property to use (each choice may have
719 wxSize
GetImageSize( wxPGProperty
* property
= NULL
, int item
= -1 ) const;
722 Returns last item which could be iterated using given flags.
725 See @ref propgrid_iterator_flags.
727 wxPGProperty
* GetLastItem( int flags
= wxPG_ITERATE_DEFAULT
);
730 Returns colour of lines between cells.
732 wxColour
GetLineColour() const;
735 Returns background colour of margin.
737 wxColour
GetMarginColour() const;
740 Returns "root property". It does not have name, etc. and it is not
741 visible. It is only useful for accessing its children.
743 wxPGProperty
* GetRoot() const;
746 Returns height of a single grid row (in pixels).
748 int GetRowHeight() const;
751 Returns currently selected property.
753 wxPGProperty
* GetSelectedProperty() const;
756 Returns currently selected property.
758 wxPGProperty
* GetSelection() const;
761 Returns current selection background colour.
763 wxColour
GetSelectionBackgroundColour() const;
766 Returns current selection text colour.
768 wxColour
GetSelectionForegroundColour() const;
771 Returns the property sort function (default is @NULL).
775 wxPGSortCallback
GetSortFunction() const;
778 Returns current splitter x position.
780 int GetSplitterPosition( unsigned int splitterIndex
= 0 ) const;
783 Returns wxTextCtrl active in currently selected property, if any. Takes
784 wxOwnerDrawnComboBox into account.
786 wxTextCtrl
* GetEditorTextCtrl() const;
789 Returns current appearance of unspecified value cells.
791 @see SetUnspecifiedValueAppearance()
793 const wxPGCell
& GetUnspecifiedValueAppearance() const;
796 Returns (visual) text representation of the unspecified
799 @param argFlags For internal use only.
801 wxString
GetUnspecifiedValueText( int argFlags
= 0 ) const;
804 Returns current vertical spacing.
806 int GetVerticalSpacing() const;
809 Returns information about arbitrary position in the grid.
812 Coordinates in the virtual grid space. You may need to use
813 wxScrolledWindow::CalcScrolledPosition() for translating
814 wxPropertyGrid client coordinates into something this member
817 wxPropertyGridHitTestResult
HitTest( const wxPoint
& pt
) const;
820 Returns true if any property has been modified by the user.
822 bool IsAnyModified() const;
825 Returns @true if a property editor control has focus.
827 bool IsEditorFocused() const;
830 Returns true if updating is frozen (ie. Freeze() called but not
833 bool IsFrozen() const;
836 Makes given column editable by user.
839 The index of the column to make editable.
841 Using @false here will disable column from being editable.
843 @see BeginLabelEdit(), EndLabelEdit()
845 void MakeColumnEditable( unsigned int column
, bool editable
= true );
848 It is recommended that you call this function any time your code causes
849 wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle()
850 handler should be able to detect most changes, but it is not perfect.
853 New top-level parent that is about to be set. Old top-level parent
854 window should still exist as the current one.
856 @remarks This function is automatically called from wxPropertyGrid::
857 Reparent() and wxPropertyGridManager::Reparent(). You only
858 need to use it if you reparent wxPropertyGrid indirectly.
860 void OnTLPChanging( wxWindow
* newTLP
);
863 Refreshes any active editor control.
865 void RefreshEditor();
868 Redraws given property.
870 virtual void RefreshProperty( wxPGProperty
* p
);
873 Registers a new editor class.
875 @return Returns pointer to the editor class instance that should be used.
877 static wxPGEditor
* RegisterEditorClass( wxPGEditor
* editor
,
878 const wxString
& name
,
879 bool noDefCheck
= false );
882 Resets all colours to the original system values.
887 Resets column sizes and splitter positions, based on proportions.
889 @param enableAutoResizing
890 If @true, automatic column resizing is enabled (only applicapple
891 if window style wxPG_SPLITTER_AUTO_CENTER is used).
893 @see wxPropertyGridInterface::SetColumnProportion()
895 void ResetColumnSizes( bool enableAutoResizing
= false );
898 Removes given property from selection. If property is not selected,
899 an assertion failure will occur.
901 bool RemoveFromSelection( wxPGPropArg id
);
904 Selects a property. Editor widget is automatically created, but
905 not focused unless focus is true.
908 Property to select (name or pointer).
911 If @true, move keyboard focus to the created editor right away.
913 @return returns @true if selection finished successfully. Usually only
914 fails if current value in editor is not valid.
916 @remarks In wxPropertyGrid 1.4, this member function used to generate
917 wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer
920 @remarks This clears any previous selection.
922 @see wxPropertyGridInterface::ClearSelection()
924 bool SelectProperty( wxPGPropArg id
, bool focus
= false );
927 Changes keyboard shortcut to push the editor button.
929 @remarks You can set default with keycode 0. Good value for the platform
930 is guessed, but don't expect it to be very accurate.
932 void SetButtonShortcut( int keycode
, bool ctrlDown
= false, bool altDown
= false );
935 Sets category caption background colour.
937 void SetCaptionBackgroundColour(const wxColour
& col
);
940 Sets category caption text colour.
942 void SetCaptionTextColour(const wxColour
& col
);
945 Sets default cell background colour - applies to property cells.
946 Note that appearance of editor widgets may not be affected.
948 void SetCellBackgroundColour(const wxColour
& col
);
951 Sets cell text colour for disabled properties.
953 void SetCellDisabledTextColour(const wxColour
& col
);
956 Sets default cell text colour - applies to property name and value text.
957 Note that appearance of editor widgets may not be affected.
959 void SetCellTextColour(const wxColour
& col
);
962 Set number of columns (2 or more).
964 void SetColumnCount( int colCount
);
967 Sets the 'current' category - Append will add non-category properties
970 void SetCurrentCategory( wxPGPropArg id
);
973 Sets colour of empty space below properties.
975 void SetEmptySpaceColour(const wxColour
& col
);
978 Sets colour of lines between cells.
980 void SetLineColour(const wxColour
& col
);
983 Sets background colour of margin.
985 void SetMarginColour(const wxColour
& col
);
988 Set entire new selection from given list of properties.
990 void SetSelection( const wxArrayPGProperty
& newSelection
);
993 Sets selection background colour - applies to selected property name
996 void SetSelectionBackgroundColour(const wxColour
& col
);
999 Sets selection foreground colour - applies to selected property name text.
1001 void SetSelectionTextColour(const wxColour
& col
);
1005 Sets the property sorting function.
1008 The sorting function to be used. It should return a value greater
1009 than 0 if position of p1 is after p2. So, for instance, when
1010 comparing property names, you can use following implementation:
1013 int MyPropertySortFunction(wxPropertyGrid* propGrid,
1017 return p1->GetBaseName().compare( p2->GetBaseName() );
1022 Default property sort function sorts properties by their labels
1023 (case-insensitively).
1025 @see GetSortFunction, wxPropertyGridInterface::Sort,
1026 wxPropertyGridInterface::SortChildren
1028 void SetSortFunction( wxPGSortCallback sortFunction
);
1031 Sets x coordinate of the splitter.
1033 @remarks Splitter position cannot exceed grid size, and therefore setting
1034 it during form creation may fail as initial grid size is often
1035 smaller than desired splitter position, especially when sizers
1038 void SetSplitterPosition( int newxpos
, int col
= 0 );
1041 Moves splitter as left as possible, while still allowing all
1042 labels to be shown in full.
1044 @param privateChildrenToo
1045 If @false, will still allow private children to be cropped.
1047 void SetSplitterLeft( bool privateChildrenToo
= false );
1050 Sets appearance of value cells representing an unspecified property
1051 value. Default appearance is blank.
1053 @remarks If you set the unspecified value to have any
1054 textual representation, then that will override
1055 "InlineHelp" attribute.
1057 @see wxPGProperty::SetValueToUnspecified(),
1058 wxPGProperty::IsValueUnspecified()
1060 void SetUnspecifiedValueAppearance( const wxPGCell
& cell
);
1063 Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
1064 height. Value of 2 should be default on most platforms.
1066 void SetVerticalSpacing( int vspacing
);
1069 @name wxPropertyGrid customization
1071 Reimplement these member functions in derived class for better
1072 control over wxPropertyGrid behavior.
1077 Override in derived class to display error messages in custom manner
1078 (these message usually only result from validation failure).
1080 @remarks If you implement this, then you also need to implement
1081 DoHidePropertyError() - possibly to do nothing, if error
1082 does not need hiding (e.g. it was logged or shown in a
1085 @see DoHidePropertyError()
1087 virtual void DoShowPropertyError( wxPGProperty
* property
,
1088 const wxString
& msg
);
1091 Override in derived class to hide an error displayed by
1092 DoShowPropertyError().
1094 @see DoShowPropertyError()
1096 virtual void DoHidePropertyError( wxPGProperty
* property
);
1099 Return wxStatusBar that is used by this wxPropertyGrid. You can
1100 reimplement this member function in derived class to override
1101 the default behavior of using the top-level wxFrame's status
1104 virtual wxStatusBar
* GetStatusBar();
1109 @name Property development functions
1111 These member functions are usually only called when creating custom
1117 Call when editor widget's contents is modified. For example, this is
1118 called when changes text in wxTextCtrl (used in wxStringProperty and
1121 @remarks This function should only be called by custom properties.
1123 @see wxPGProperty::OnEvent()
1125 void EditorsValueWasModified();
1128 Reverse of EditorsValueWasModified().
1130 @remarks This function should only be called by custom properties.
1132 void EditorsValueWasNotModified();
1135 Returns most up-to-date value of selected property. This will return
1136 value different from GetSelectedProperty()->GetValue() only when text
1137 editor is activate and string edited by user represents valid,
1138 uncommitted property value.
1140 wxVariant
GetUncommittedPropertyValue();
1143 Returns true if editor's value was marked modified.
1145 bool IsEditorsValueModified() const;
1148 Shows an brief error message that is related to a property.
1150 void ShowPropertyError( wxPGPropArg id
, const wxString
& msg
);
1153 You can use this member function, for instance, to detect in
1154 wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was
1155 already called in wxPGEditor::OnEvent(). It really only detects
1156 if was value was changed using wxPGProperty::SetValueInEvent(), which
1157 is usually used when a 'picker' dialog is displayed. If value was
1158 written by "normal means" in wxPGProperty::StringToValue() or
1159 IntToValue(), then this function will return false (on the other hand,
1160 wxPGProperty::OnEvent() is not even called in those cases).
1162 bool WasValueChangedInEvent() const;
1169 @class wxPropertyGridEvent
1171 A property grid event holds information about events associated with
1172 wxPropertyGrid objects.
1174 @library{wxpropgrid}
1177 class wxPropertyGridEvent
: public wxCommandEvent
1182 wxPropertyGridEvent(wxEventType commandType
=0, int id
=0);
1184 /** Copy constructor. */
1185 wxPropertyGridEvent(const wxPropertyGridEvent
& event
);
1188 ~wxPropertyGridEvent();
1191 Returns true if you can veto the action that the event is signaling.
1193 bool CanVeto() const;
1196 Returns the column index associated with this event.
1197 For the column dragging events, it is the column to the left
1198 of the splitter being dragged
1200 unsigned int GetColumn() const;
1203 Returns highest level non-category, non-root parent of property for
1204 which event occurred. Useful when you have nested properties with
1207 @remarks If immediate parent is root or category, this will return the
1210 wxPGProperty
* GetMainParent() const;
1213 Returns property associated with this event.
1215 @remarks You should assume that this property can always be NULL.
1216 For instance, wxEVT_PG_SELECTED is emitted not only when
1217 a new property is selected, but also when selection is
1218 cleared by user activity.
1220 wxPGProperty
* GetProperty() const;
1223 Returns current validation failure flags.
1225 wxPGVFBFlags
GetValidationFailureBehavior() const;
1228 Returns name of the associated property.
1230 @remarks Property name is stored in event, so it remains
1231 accessible even after the associated property or
1232 the property grid has been deleted.
1234 wxString
GetPropertyName() const;
1237 Returns value of the associated property. Works for all event
1238 types, but for wxEVT_PG_CHANGING this member function returns
1239 the value that is pending, so you can call Veto() if the
1240 value is not satisfactory.
1242 @remarks Property value is stored in event, so it remains
1243 accessible even after the associated property or
1244 the property grid has been deleted.
1246 wxVariant
GetPropertyValue() const
1249 @see GetPropertyValue()
1251 wxVariant
GetValue() const;
1254 Set if event can be vetoed.
1256 void SetCanVeto( bool canVeto
);
1258 /** Changes the property associated with this event. */
1259 void SetProperty( wxPGProperty
* p
);
1262 Set override validation failure behavior. Only effective if Veto() was
1263 also called, and only allowed if event type is wxEVT_PG_CHANGING.
1265 void SetValidationFailureBehavior( wxPGVFBFlags flags
);
1268 Sets custom failure message for this time only. Only applies if
1269 wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
1271 void SetValidationFailureMessage( const wxString
& message
);
1274 Call this from your event handler to veto action that the event is
1275 signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto()
1278 @remarks Currently only wxEVT_PG_CHANGING supports vetoing.
1280 void Veto( bool veto
= true );
1283 Returns @true if event was vetoed.
1285 bool WasVetoed() const;