wxPropertyGrid Class Reference

wxPropertyGrid is a specialized two-column grid for editing properties such as strings, numbers, flagsets, fonts, and colours. More...

#include <propgrid.h>

Inheritance diagram for wxPropertyGrid:

List of all members.

Public Member Functions
void	AddActionTrigger (int action, int keycode, int modifiers=0)
	Adds given key combination to trigger given action.
bool	AddToSelection (wxPGPropArg id)
	Adds given property into selection.
bool	AdjustPosForClipperWindow (wxWindow topCtrlWnd, int x, int *y)
	Adjusts given position if topCtrlWnd is child of clipper window.
void	BeginLabelEdit (unsigned int column=0)
	Creates label editor wxTextCtrl for given column, for property that is currently selected.
bool	CanClose ()
	Returns true if all property grid data changes have been committed.
void	CenterSplitter (bool enableAutoResizing=false)
	Centers the splitter.
bool	ChangePropertyValue (wxPGPropArg id, wxVariant newValue)
	Changes value of a property, as if from an editor.
virtual void	Clear ()
	Deletes all properties.
void	ClearActionTriggers (int action)
	Clears action triggers for given action.
void	ClearInternalFlag (long flag)
void	ClearModifiedStatus ()
	Resets modified status of all properties.
void	ClearModifiedStatus (wxPGPropArg id)
	Resets modified status of a property and all sub-properties.
void	ClearTargetPage ()
	Synonymous to Clear.
virtual bool	CommitChangesFromEditor (wxUint32 flags=0)
	Forces updating the value of property from the editor control.
bool	Create (wxWindow *parent, wxWindowID id=wxID_ANY, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, long style=(0), const wxString &name=wxPropertyGridNameStr)
	Two step creation.
void	DecFrozen ()
virtual void	DoHidePropertyError (wxPGProperty *property)
	Override in derived class to hide an error displayed by DoShowPropertyError().
virtual bool	DoOnValidationFailure (wxPGProperty *property, wxVariant &invalidValue)
	Override to customize property validation failure behavior.
virtual void	DoOnValidationFailureReset (wxPGProperty *property)
	Override to customize resetting of property validation failure status.
virtual bool	DoPropertyChanged (wxPGProperty *p, unsigned int selFlags=0)
	Pending value is expected to be passed in PerformValidation().
virtual void	DoShowPropertyError (wxPGProperty *property, const wxString &msg)
	Override in derived class to display error messages in custom manner (these message usually only result from validation failure).
void	DrawItem (wxPGProperty *p)
virtual void	DrawItemAndChildren (wxPGProperty *p)
void	DrawItemAndValueRelated (wxPGProperty *p)
	Draws item, children, and consequtive parents as long as category is not met.
void	EditorsValueWasModified ()
	Call when editor widget's contents is modified.
void	EditorsValueWasNotModified ()
	Reverse of EditorsValueWasModified().
bool	EditorValidate ()
	Returns true if all property grid data changes have been committed.
bool	EnableCategories (bool enable)
	Enables or disables (shows/hides) categories according to parameter enable.
void	EndLabelEdit (bool commit=true)
	Destroys label editor wxTextCtrl, if any.
bool	EnsureVisible (wxPGPropArg id)
	Scrolls and/or expands items to ensure that the given item is visible.
wxSize	FitColumns ()
	Reduces column sizes to minimum possible that contents are still visibly (naturally some margin space will be applied as well).
void	FixPosForTextCtrl (wxWindow *ctrl, unsigned int forColumn=1, const wxPoint &offset=wxPoint(0, 0))
	Fixes position of wxTextCtrl-like control (wxSpinCtrl usually fits as one).
wxWindow *	GenerateEditorButton (const wxPoint &pos, const wxSize &sz)
	Shortcut for creating dialog-caller button.
wxWindow *	GenerateEditorTextCtrl (const wxPoint &pos, const wxSize &sz, const wxString &value, wxWindow *secondary, int extraStyle=0, int maxLen=0, unsigned int forColumn=1)
	Shortcut for creating text editor widget.
wxWindow *	GenerateEditorTextCtrlAndButton (const wxPoint &pos, const wxSize &sz, wxWindow *psecondary, int limited_editing, wxPGProperty property)
wxColour	GetCaptionBackgroundColour () const
	Returns current category caption background colour.
const wxFont &	GetCaptionFont () const
wxFont &	GetCaptionFont ()
wxColour	GetCaptionForegroundColour () const
	Returns current category caption text colour.
wxColour	GetCellBackgroundColour () const
	Returns current cell background colour.
wxColour	GetCellDisabledTextColour () const
	Returns current cell text colour when disabled.
wxColour	GetCellTextColour () const
	Returns current cell text colour.
unsigned int	GetChildrenCount (wxPGPropArg id) const
	Returns number of children for the property.
unsigned int	GetChildrenCount ()
	Returns number of children of the root property.
unsigned int	GetColumnCount () const
const wxPGCommonValue *	GetCommonValue (unsigned int i) const
unsigned int	GetCommonValueCount () const
	Returns number of common values.
wxString	GetCommonValueLabel (unsigned int i) const
	Returns label of given common value.
wxWindow *	GetEditorControl () const
	Returns pointer to current active primary editor control (NULL if none).
wxWindow *	GetEditorControlSecondary () const
	Returns pointer to current active secondary editor control (NULL if none).
wxTextCtrl *	GetEditorTextCtrl () const
	Returns wxTextCtrl active in currently selected property, if any.
wxColour	GetEmptySpaceColour () const
	Returns colour of empty space below properties.
wxPGProperty *	GetFirstCategory () const
	Returns id of first category (from target page).
wxPGProperty *	GetFirstProperty ()
	Returns id of first property that is not a category.
wxPGProperty *	GetFirstVisible ()
const wxPGProperty *	GetFirstVisible () const
	Returns id of first visible item, whether it is a category or property.
int	GetFontHeight () const
	Returns height of highest characters of used font.
wxPoint	GetGoodEditorDialogPosition (wxPGProperty *p, const wxSize &sz)
	Generates position for a widget editor dialog box.
wxPropertyGrid *	GetGrid ()
	Returns pointer to itself.
wxRect	GetImageRect (wxPGProperty *p, int item) const
wxSize	GetImageSize (wxPGProperty *p=NULL, int item=-1) const
	Returns size of the custom paint image in front of property.
long	GetInternalFlags () const
wxPGProperty *	GetItemAtY (int y) const
	Returns GetCustomPaintWidth for odcombo, GetImageSize(GetSelection()) otherwise.
wxTextCtrl *	GetLabelEditor () const
	Returns currently active label editor, NULL if none.
wxPGProperty *	GetLastChild (wxPGPropArg id)
	Returns id of last child of given property.
const wxPGProperty *	GetLastItem (int flags=wxPG_ITERATE_DEFAULT) const
wxPGProperty *	GetLastItem (int flags=wxPG_ITERATE_DEFAULT)
	Returns last item which could be iterated using given flags.
wxPGProperty *	GetLastProperty ()
	Returns id of last item.
wxPGProperty *	GetLastVisible ()
	Returns id of last visible item.
wxColour	GetLineColour () const
	Returns colour of lines between cells.
wxColour	GetMarginColour () const
	Returns background colour of margin.
wxPGProperty *	GetNextCategory (wxPGPropArg id) const
	Returns id of next category after a given property (which does not have to be category).
wxPGProperty *	GetNextProperty (wxPGPropArg id)
	Returns id of next property.
wxPGProperty *	GetNextVisible (wxPGPropArg id) const
	Returns id of next visible item.
wxPanel *	GetPanel () const
	Returns wxWindow that the properties are painted on, and which should be used as the parent for editor controls.
wxPGProperty *	GetPrevProperty (wxPGPropArg id)
	Returns id of previous property.
wxPGProperty *	GetPrevSiblingProperty (wxPGPropArg id)
	Returns id of previous item under the same parent.
wxPGProperty *	GetPrevVisible (wxPGPropArg id)
	Returns id of previous visible property.
wxWindow *	GetPrimaryEditor () const
wxColour	GetPropertyBackgroundColour (wxPGPropArg id) const
	Returns cell background colour of a property.
wxPGProperty *	GetPropertyByLabel (const wxString &name) const
	Returns id of property with given label (case-sensitive).
wxColour	GetPropertyColour (wxPGPropArg id) const
	Returns cell background colour of a property.
wxRect	GetPropertyRect (const wxPGProperty p1, const wxPGProperty p2) const
	Returns rectangle that fully contains properties between and including p1 and p2.
wxColour	GetPropertyTextColour (wxPGPropArg id) const
	Returns cell background colour of a property.
wxPGProperty *	GetRoot () const
	Returns "root property".
int	GetRowHeight () const
	Returns height of a single grid row (in pixels).
wxPGProperty *	GetSelectedProperty () const
wxColour	GetSelectionBackgroundColour () const
	Returns current selection background colour.
wxColour	GetSelectionForegroundColour () const
	Returns current selection text colour.
wxPGSortCallback	GetSortFunction () const
	Returns the property sort function (NULL is default).
int	GetSpacingY () const
int	GetSplitterPosition () const
	Returns current splitter x position.
int	GetUnspecifiedCommonValue () const
	Returns index of common value that will truly change value to unspecified.
const wxPGCell &	GetUnspecifiedValueAppearance () const
	Returns current appearance of unspecified value cells.
wxString	GetUnspecifiedValueText (int argFlags=0) const
	Returns (visual) text representation of the unspecified property value.
wxPGValidationInfo &	GetValidationInfo ()
int	GetVerticalSpacing () const
	Returns current vertical spacing.
bool	HasInternalFlag (long flag) const
bool	HasSelection () const
	Returns true if a property is selected.
bool	HasVirtualWidth () const
wxPropertyGridHitTestResult	HitTest (const wxPoint &pt) const
	Returns information about arbitrary position in the grid.
void	IncFrozen ()
bool	IsAnyModified () const
	Returns true if any property has been modified by the user.
bool	IsEditorFocused () const
	Returns if editor control has focus.
bool	IsEditorsValueModified () const
	Returns true if editor's value was marked modified.
bool	IsFrozen () const
	Returns true if updating is frozen (ie.
bool	IsMainButtonEvent (const wxEvent &event)
	Returns true if given event is from first of an array of buttons (as can be in case when wxPGMultiButton is used).
void	MakeColumnEditable (unsigned int column, bool editable=true)
	Makes given column editable by user.
void	OnComboItemPaint (wxPGCustomComboControl *pCb, int item, wxDC &dc, wxRect &rect, int flags)
void	OnCustomEditorEvent (wxCommandEvent &event)
	Pass this function to Connect calls in propertyclass::CreateEditor.
void	OnTLPChanging (wxWindow *newTLP)
	It is recommended that you call this function any time your code causes wxPropertyGrid's top-level parent to change.
bool	OnValidationFailure (wxPGProperty *property, wxVariant &invalidValue)
	Called when validation for given property fails.
void	OnValidationFailureReset (wxPGProperty *property)
	Called to indicate property and editor has valid value now.
virtual bool	PerformValidation (wxPGProperty *p, wxVariant &pendingValue)
	Runs all validation functionality (includes sending wxEVT_PG_CHANGING).
void	RefreshEditor ()
	If selected property's editor is active, then update it's value.
virtual void	RefreshProperty (wxPGProperty *p)
bool	RemoveFromSelection (wxPGPropArg id)
	Removes given property from selection.
void	ResetColours ()
	Resets all colours to the original system values.
void	ResetColumnSizes (bool enableAutoResizing=false)
	Resets column sizes and splitter positions, based on proportions.
bool	SelectProperty (wxPGPropArg id, bool focus=false)
	Selects a property.
void	SendNavigationKeyEvent (int dir)
void	SetButtonShortcut (int keycode, bool ctrlDown=false, bool altDown=false)
	Changes keyboard shortcut to push the editor button.
void	SetCaptionBackgroundColour (const wxColour &col)
	Sets category caption background colour.
void	SetCaptionForegroundColour (const wxColour &col)
	Sets category caption text colour.
void	SetCaptionTextColour (wxPGPropArg id, const wxColour &col)
	Sets text colour of a category caption (but not it's children).
void	SetCellBackgroundColour (const wxColour &col)
	Sets default cell background colour - applies to property cells.
void	SetCellDisabledTextColour (const wxColour &col)
	Sets cell text colour for disabled properties.
void	SetCellTextColour (const wxColour &col)
	Sets default cell text colour - applies to property name and value text.
void	SetColumnCount (int colCount)
	Set number of columns (2+).
void	SetCurrentCategory (wxPGPropArg id)
	Sets the current category - Append will add non-categories under this one.
void	SetEmptySpaceColour (const wxColour &col)
	Sets colour of empty space below properties.
void	SetInternalFlag (long flag)
void	SetLineColour (const wxColour &col)
	Sets colour of lines between cells.
void	SetMarginColour (const wxColour &col)
	Sets background colour of margin.
void	SetPropertyAttributeAll (const wxString &attrName, wxVariant value)
	Sets property attribute for all applicapple properties.
void	SetPropertyBackgroundColour (wxPGPropArg id, const wxColour &col, int flags=wxPG_RECURSE)
	Sets background colour of property and all its children.
void	SetPropertyColour (wxPGPropArg id, const wxColour &col)
	Sets background colour of property and all its children.
void	SetPropertyColourToDefault (wxPGPropArg id)
	Sets background and text colour of property and all its children to the default.
void	SetPropertyName (wxPGPropArg id, const wxString &newname)
	Sets name of a property.
void	SetPropertyTextColour (wxPGPropArg id, const wxColour &col, int flags=wxPG_RECURSE)
	Sets text colour of property and all its children.
void	SetSelection (const wxArrayPGProperty &newSelection)
	Set entire new selection from given list of properties.
void	SetSelectionBackground (const wxColour &col)
	Sets selection background colour - applies to selected property name background.
void	SetSelectionForeground (const wxColour &col)
	Sets selection foreground colour - applies to selected property name text.
void	SetSortFunction (wxPGSortCallback sortFunction)
	Sets the property sorting function.
void	SetSplitterLeft (bool subProps=false)
	Moves splitter as left as possible, while still allowing all labels to be shown in full.
void	SetSplitterPosition (int newxpos, bool refresh=true)
	Sets x coordinate of the splitter.
void	SetUnspecifiedCommonValue (int index)
	Set index of common value that will truly change value to unspecified.
void	SetUnspecifiedValueAppearance (const wxPGCell &cell)
	Sets appearance of value cells representing an unspecified property value.
void	SetupTextCtrlValue (const wxString text)
	Must be called in wxPGEditor::CreateControls() if primary editor window is wxTextCtrl, just before textctrl is created.
void	SetVerticalSpacing (int vspacing)
	Sets vertical spacing.
void	SetVirtualWidth (int width)
	Set virtual width for this particular page.
virtual void	SetWindowStyleFlag (long style)
	Overridden function.
void	ShowPropertyError (wxPGPropArg id, const wxString &msg)
	Shows an brief error message that is related to a property.
void	Sort (wxPGPropArg id)
	Sorts children of a category.
void	Sort ()
	Sorts all items at all levels (except sub-properties).
void	SwitchState (wxPropertyGridState *pNewState)
	Mostly useful for page switching.
bool	UnfocusEditor ()
	Unfocuses or closes editor if one was open, but does not deselect property.
void	ValueChangeInEvent (wxVariant variant)
	Call this from wxPGProperty::OnEvent() to cause property value to be changed after the function returns (with true as return value).
bool	WasValueChangedInEvent () const
	You can use this member function, for instance, to detect in wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was already called in wxPGEditor::OnEvent().
	wxPropertyGrid (wxWindow *parent, wxWindowID id=wxID_ANY, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, long style=(0), const wxString &name=wxPropertyGridNameStr)
	The default constructor.
	wxPropertyGrid ()
	Two step constructor.
virtual	~wxPropertyGrid ()
	Destructor.
Static Public Member Functions
static void	ArrayStringToString (wxString &dst, const wxArrayString &src, wxChar preDelim, wxChar postDelim, int flags)
	Generates contents for string dst based on the convetents of wxArrayString src.
static void	AutoGetTranslation (bool enable)
	This static function enables or disables automatic use of wxGetTranslation for following strings: wxEnumProperty list labels, wxFlagsProperty sub-property labels.
static wxString &	CreateEscapeSequences (wxString &dst_str, wxString &src_str)
static void	DoubleToString (wxString &target, double value, int precision, bool removeZeroes, wxString *precTemplate)
	Standardized double-to-string conversion.
static wxString &	ExpandEscapeSequences (wxString &dst_str, wxString &src_str)
static wxPGEditor *	RegisterEditorClass (wxPGEditor *editor, const wxString &name, bool noDefCheck=false)
	Registers a new editor class.
Protected Member Functions
virtual wxPropertyGridState *	CreateState () const
	wxPropertyGridState used by the grid is created here.

Detailed Description

wxPropertyGrid is a specialized two-column grid for editing properties such as strings, numbers, flagsets, fonts, and colours.

wxPropertySheet used to do the very same thing, but it hasn't been updated for a while and it is currently deprecated.

Please note that most member functions are inherited and as such not documented on this page. This means you will probably also want to read wxPropertyGridInterface class reference.

Derived from

wxPropertyGridInterface
wxScrolledWindow
wxPanel
wxWindow
wxEvtHandler
wxObject

Include files

Window styles

Additional Window Styles

Event handling

To process input from a propertygrid control, use these event handler macros to direct input to member functions that take a wxPropertyGridEvent argument.

EVT_PG_SELECTED (id, func)	Property is selected.
EVT_PG_CHANGED (id, func)	Property value is modified.
EVT_PG_CHANGING (id, func)	Property value is about to be changed. Use wxPropertyGridEvent::GetValue() to take a peek at the pending value, and wxPropertyGridEvent::Veto() to prevent change from taking place, if necessary.
EVT_PG_HIGHLIGHTED (id, func)	Mouse moves over property. Event's property is NULL if hovered on area that is not a property.
EVT_PG_RIGHT_CLICK (id, func)	Mouse right-clicked on a property.
EVT_PG_DOUBLE_CLICK (id, func)	Mouse double-clicked on a property.
EVT_PG_ITEM_COLLAPSED (id, func)	User collapses a property or category.
EVT_PG_ITEM_EXPANDED (id, func)	User expands a property or category.
EVT_PG_LABEL_EDIT_BEGIN (id, func)	User is about to begin editing a property label. You can veto this event to prevent the action.
EVT_PG_LABEL_EDIT_ENDING (id, func)	User is about to end editing of a property label. You can veto this event to prevent the action.
EVT_BUTTON (id, func)	Button in a property editor was clicked. Only occurs if the property doesn't handle button clicks itself.
EVT_TEXT (id, func)	wxTextCtrl based editor was updated (but property value was not yet modified)

See also:: wxPropertyGridEvent

Remarks:

Following functions do not automatically update the screen: Append. You probably need to explicitly call Refresh() if you called one of these functions outside parent window constructor.

Use Freeze() and Thaw() respectively to disable and enable drawing. This will also delay sorting etc. miscellaneous calculations to the last possible moment.

For code examples, see the main page.

Constructor & Destructor Documentation

wxPropertyGrid::wxPropertyGrid ( )

Two step constructor.

Call Create when this constructor is called to build up the wxPropertyGrid

wxPropertyGrid::wxPropertyGrid	(	wxWindow *	parent,
		wxWindowID	id = `wxID_ANY`,
		const wxPoint &	pos = `wxDefaultPosition`,
		const wxSize &	size = `wxDefaultSize`,
		long	style = `(0)`,
		const wxString &	name = `wxPropertyGridNameStr`
	)

The default constructor.

The styles to be used are styles valid for the wxWindow and wxScrolledWindow.

See also:: Additional Window Styles

Member Function Documentation

void wxPropertyGrid::AddActionTrigger	(	int	action,
		int	keycode,
		int	modifiers = `0`
	)

Adds given key combination to trigger given action.

Parameters:

action

Which action to trigger. See List of list of wxPropertyGrid actions.

bool wxPropertyGrid::AddToSelection ( wxPGPropArg id )

Adds given property into selection.

If wxPG_EX_MULTIPLE_SELECTION extra style is not used, then this has same effect as calling SelectProperty().

Remarks:: Multiple selection is not supported for categories. This means that if you have properties selected, you cannot add category to selection, and also if you have category selected, you cannot add other properties to selection. This member function will fail silently in these cases, even returning true.

static void wxPropertyGrid::ArrayStringToString	(	wxString &	dst,
		const wxArrayString &	src,
		wxChar	preDelim,
		wxChar	postDelim,
		int	flags
	)			`[static]`

Generates contents for string dst based on the convetents of wxArrayString src.

Format will be "(preDelim)str1(postDelim) (preDelim)str2(postDelim) and so on. Set flags to 1 inorder to convert backslashes to double-back- slashes and "(preDelims)"'s to "(preDelims)".

static void wxPropertyGrid::AutoGetTranslation ( bool enable ) [static]

This static function enables or disables automatic use of wxGetTranslation for following strings: wxEnumProperty list labels, wxFlagsProperty sub-property labels.

Default is false.

void wxPropertyGrid::BeginLabelEdit ( unsigned int column = 0 )

Creates label editor wxTextCtrl for given column, for property that is currently selected.

When multiple selection is enabled, this applies to whatever property GetSelection() returns.

Parameters:

colIndex

Which column's label to edit. Note that you should not use value 1, which is reserved for property value column.

bool wxPropertyGrid::CanClose ( )

Returns true if all property grid data changes have been committed.

Usually only returns false if value in active editor has been invalidated by a wxValidator.

void wxPropertyGrid::CenterSplitter ( bool enableAutoResizing = false )

Centers the splitter.

Parameters:

enableAutoResizing

If , automatic column resizing is enabled (only applicapple if window style wxPG_SPLITTER_AUTO_CENTER is used).

bool wxPropertyGrid::ChangePropertyValue	(	wxPGPropArg	id,
		wxVariant	newValue
	)

Changes value of a property, as if from an editor.

Use this instead of SetPropertyValue() if you need the value to run through validation process, and also send the property change event.

Return values:

Returns

true if value was succesfully changed.

Reimplemented from wxPropertyGridInterface.

virtual void wxPropertyGrid::Clear ( ) [virtual]

Deletes all properties.

Does not free memory allocated for arrays etc. This should *not* be called in wxPropertyGridManager.

Implements wxPropertyGridInterface.

void wxPropertyGrid::ClearActionTriggers ( int action )

Clears action triggers for given action.

Parameters:

action

Which action to trigger. See List of list of wxPropertyGrid actions.

void wxPropertyGrid::ClearTargetPage ( )

Synonymous to Clear.

Deprecated:: Since version 1.3.

virtual bool wxPropertyGrid::CommitChangesFromEditor ( wxUint32 flags = 0 ) [virtual]

Forces updating the value of property from the editor control.

Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using ProcessEvent, meaning your event handlers will be called immediately.

Return values:

Returns

true if anything was changed.

bool wxPropertyGrid::Create	(	wxWindow *	parent,
		wxWindowID	id = `wxID_ANY`,
		const wxPoint &	pos = `wxDefaultPosition`,
		const wxSize &	size = `wxDefaultSize`,
		long	style = `(0)`,
		const wxString &	name = `wxPropertyGridNameStr`
	)

Two step creation.

Whenever the control is created without any parameters, use Create to actually create it. Don't access the control's public methods before this is called

See also:: Additional Window Styles

virtual wxPropertyGridState* wxPropertyGrid::CreateState ( ) const [protected, virtual]

wxPropertyGridState used by the grid is created here.

If grid is used in wxPropertyGridManager, there is no point overriding this - instead, set custom wxPropertyGridPage classes.

virtual void wxPropertyGrid::DoHidePropertyError ( wxPGProperty * property ) [virtual]

Override in derived class to hide an error displayed by DoShowPropertyError().

See also:: DoShowPropertyError()

virtual bool wxPropertyGrid::DoOnValidationFailure	(	wxPGProperty *	property,
		wxVariant &	invalidValue
	)			`[virtual]`

Override to customize property validation failure behavior.

Parameters:

invalidValue

Value which failed in validation.

Return values:

Return

true if user is allowed to change to another property even if current has invalid value.

virtual void wxPropertyGrid::DoOnValidationFailureReset ( wxPGProperty * property ) [virtual]

Override to customize resetting of property validation failure status.

Remarks:: Property is guaranteed to have flag wxPG_PROP_INVALID_VALUE set.

virtual void wxPropertyGrid::DoShowPropertyError	(	wxPGProperty *	property,
		const wxString &	msg
	)			`[virtual]`

Override in derived class to display error messages in custom manner (these message usually only result from validation failure).

Remarks:: If you implement this, then you also need to implement DoHidePropertyError() - possibly to do nothing, if error does not need hiding (e.g. it was logged or shown in a message box).

See also:: DoHidePropertyError()

void wxPropertyGrid::DrawItemAndValueRelated ( wxPGProperty * p )

Draws item, children, and consequtive parents as long as category is not met.

void wxPropertyGrid::EditorsValueWasModified ( )

Call when editor widget's contents is modified.

For example, this is called when changes text in wxTextCtrl (used in wxStringProperty and wxIntProperty).

Remarks:: This should only be called by properties.

See also:: wxPGProperty::OnEvent

void wxPropertyGrid::EditorsValueWasNotModified ( )

Reverse of EditorsValueWasModified().

bool wxPropertyGrid::EditorValidate ( )

Returns true if all property grid data changes have been committed.

Usually only returns false if value in active editor has been invalidated by a wxValidator.

bool wxPropertyGrid::EnableCategories ( bool enable )

Enables or disables (shows/hides) categories according to parameter enable.

void wxPropertyGrid::EndLabelEdit ( bool commit = true )

Destroys label editor wxTextCtrl, if any.

Parameters:

commit

Use (default) to store edited label text in property cell data.

bool wxPropertyGrid::EnsureVisible ( wxPGPropArg id )

Scrolls and/or expands items to ensure that the given item is visible.

Returns true if something was actually done.

wxSize wxPropertyGrid::FitColumns ( )

Reduces column sizes to minimum possible that contents are still visibly (naturally some margin space will be applied as well).

Return values:

Minimum

size for the grid to still display everything.

Remarks:: Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.

This function only works properly if grid size prior to call was already fairly large.

Note that you can also get calculated column widths by calling GetState->GetColumnWidth() immediately after this function returns.

void wxPropertyGrid::FixPosForTextCtrl	(	wxWindow *	ctrl,
		unsigned int	forColumn = `1`,
		const wxPoint &	offset = `wxPoint(0, 0)`
	)

Fixes position of wxTextCtrl-like control (wxSpinCtrl usually fits as one).

Call after control has been created (but before shown).

wxWindow* wxPropertyGrid::GenerateEditorButton	(	const wxPoint &	pos,
		const wxSize &	sz
	)

Shortcut for creating dialog-caller button.

Used, for example, by wxFontProperty.

Remarks:: This should only be called by properties.

wxWindow* wxPropertyGrid::GenerateEditorTextCtrl	(	const wxPoint &	pos,
		const wxSize &	sz,
		const wxString &	value,
		wxWindow *	secondary,
		int	extraStyle = `0`,
		int	maxLen = `0`,
		unsigned int	forColumn = `1`
	)

Shortcut for creating text editor widget.

Parameters:

	pos	Same as pos given for CreateEditor.
	sz	Same as sz given for CreateEditor.
	value	Initial text for wxTextCtrl.
	secondary	If right-side control, such as button, also created, then create it first and pass it as this parameter.
	extraStyle	Extra style flags to pass for wxTextCtrl.

Remarks:: Note that this should generally be called only by new classes derived from wxPGProperty.

wxColour wxPropertyGrid::GetCaptionBackgroundColour ( ) const

Returns current category caption background colour.

wxColour wxPropertyGrid::GetCaptionForegroundColour ( ) const

Returns current category caption text colour.

wxColour wxPropertyGrid::GetCellBackgroundColour ( ) const

Returns current cell background colour.

wxColour wxPropertyGrid::GetCellDisabledTextColour ( ) const

Returns current cell text colour when disabled.

wxColour wxPropertyGrid::GetCellTextColour ( ) const

Returns current cell text colour.

unsigned int wxPropertyGrid::GetChildrenCount ( wxPGPropArg id ) const

Returns number of children for the property.

NB: Cannot be in container methods class due to name hiding.

wxWindow* wxPropertyGrid::GetEditorControl ( ) const

Returns pointer to current active primary editor control (NULL if none).

If editor uses clipper window, pointer is returned to the actual editor, not the clipper.

wxTextCtrl* wxPropertyGrid::GetEditorTextCtrl ( ) const

Returns wxTextCtrl active in currently selected property, if any.

Takes into account wxOwnerDrawnComboBox.

wxColour wxPropertyGrid::GetEmptySpaceColour ( ) const

Returns colour of empty space below properties.

wxPGProperty* wxPropertyGrid::GetFirstCategory ( ) const

Returns id of first category (from target page).

Deprecated:: Since version 1.3. Use wxPropertyGridInterface::GetIterator() instead.

wxPGProperty* wxPropertyGrid::GetFirstProperty ( )

Returns id of first property that is not a category.

Deprecated:: Since version 1.3. Use wxPropertyGridInterface::GetIterator() instead.

const wxPGProperty* wxPropertyGrid::GetFirstVisible ( ) const

Returns id of first visible item, whether it is a category or property.

Note that visible item means category, property, or sub-property which user can see when control is scrolled properly. It does not only mean items that are actually painted on the screen.

Deprecated:: Since version 1.3. Use wxPropertyGridInterface::GetIterator() instead.

int wxPropertyGrid::GetFontHeight ( ) const

Returns height of highest characters of used font.

wxPoint wxPropertyGrid::GetGoodEditorDialogPosition	(	wxPGProperty *	p,
		const wxSize &	sz
	)

Generates position for a widget editor dialog box.

Parameters:

	p	Property for which dialog is positioned.
	sz	Known or over-approximated size of the dialog.

Return values:

Position

for dialog.

wxPropertyGrid* wxPropertyGrid::GetGrid ( )

Returns pointer to itself.

Dummy function that enables same kind of code to use wxPropertyGrid and wxPropertyGridManager.

wxSize wxPropertyGrid::GetImageSize	(	wxPGProperty *	p = `NULL`,
		int	item = `-1`
	)			const

Returns size of the custom paint image in front of property.

If no argument is given, returns preferred size.

wxPGProperty* wxPropertyGrid::GetItemAtY ( int y ) const

Returns GetCustomPaintWidth for odcombo, GetImageSize(GetSelection()) otherwise.

Returns property (or category) at given y coordinate (relative to control's top left).

wxPGProperty* wxPropertyGrid::GetLastChild ( wxPGPropArg id )

Returns id of last child of given property.

Remarks:: Returns even sub-properties.

Deprecated:: Since version 1.3. Use wxPropertyGridInterface::GetIterator() instead.

wxPGProperty* wxPropertyGrid::GetLastItem ( int flags = wxPG_ITERATE_DEFAULT )

Returns last item which could be iterated using given flags.

Parameters:

flags

List of iterator flags

wxPGProperty* wxPropertyGrid::GetLastProperty ( )

Returns id of last item.

Ignores categories and sub-properties.

Deprecated:: Since version 1.3. Use wxPropertyGridInterface::GetIterator() instead.

wxPGProperty* wxPropertyGrid::GetLastVisible ( )

Returns id of last visible item.

Does not ignore categories sub-properties.

Deprecated:: Since version 1.3. Use wxPropertyGridInterface::GetIterator() instead.

wxColour wxPropertyGrid::GetLineColour ( ) const

Returns colour of lines between cells.

wxColour wxPropertyGrid::GetMarginColour ( ) const

Returns background colour of margin.

wxPGProperty* wxPropertyGrid::GetNextCategory ( wxPGPropArg id ) const

Returns id of next category after a given property (which does not have to be category).

Deprecated:: Since version 1.3. Use wxPropertyGridInterface::GetIterator() instead.

wxPGProperty* wxPropertyGrid::GetNextProperty ( wxPGPropArg id )

Returns id of next property.

This does not iterate to sub-properties or categories, unlike GetNextVisible.

Deprecated:: Since version 1.3. Use wxPropertyGridInterface::GetIterator() instead.

wxPGProperty* wxPropertyGrid::GetNextVisible ( wxPGPropArg id ) const

Returns id of next visible item.

Note that visible item means category, property, or sub-property which user can see when control is scrolled properly. It does not only mean items that are actually painted on the screen.

Deprecated:: Since version 1.3. Use wxPropertyGridInterface::GetIterator() instead.

wxPGProperty* wxPropertyGrid::GetPrevProperty ( wxPGPropArg id )

Returns id of previous property.

Unlike GetPrevVisible, this skips categories and sub-properties.

Deprecated:: Since version 1.3. Use wxPropertyGridInterface::GetIterator() instead.

wxPGProperty* wxPropertyGrid::GetPrevSiblingProperty ( wxPGPropArg id )

Returns id of previous item under the same parent.

Deprecated:: Since version 1.3. Use wxPropertyGridInterface::GetIterator() instead.

wxPGProperty* wxPropertyGrid::GetPrevVisible ( wxPGPropArg id )

Returns id of previous visible property.

Deprecated:: Since version 1.3. Use wxPropertyGridInterface::GetIterator() instead.

wxColour wxPropertyGrid::GetPropertyBackgroundColour ( wxPGPropArg id ) const

Returns cell background colour of a property.

wxPGProperty* wxPropertyGrid::GetPropertyByLabel ( const wxString & name ) const

Returns id of property with given label (case-sensitive).

If there is no property with such label, returned property id is invalid ( i.e. it will return false with IsOk method). If there are multiple properties with identical name, most recent added is returned.

wxColour wxPropertyGrid::GetPropertyColour ( wxPGPropArg id ) const

Returns cell background colour of a property.

wxColour wxPropertyGrid::GetPropertyTextColour ( wxPGPropArg id ) const

Returns cell background colour of a property.

wxPGProperty* wxPropertyGrid::GetRoot ( ) const

Returns "root property".

It does not have name, etc. and it is not visible. It is only useful for accessing its children.

int wxPropertyGrid::GetRowHeight ( ) const

Returns height of a single grid row (in pixels).

wxColour wxPropertyGrid::GetSelectionBackgroundColour ( ) const

Returns current selection background colour.

wxColour wxPropertyGrid::GetSelectionForegroundColour ( ) const

Returns current selection text colour.

int wxPropertyGrid::GetSplitterPosition ( ) const

Returns current splitter x position.

const wxPGCell& wxPropertyGrid::GetUnspecifiedValueAppearance ( ) const

Returns current appearance of unspecified value cells.

Remarks:: If you set the unspecified value to have any textual representation, then that will override "InlineHelp" attribute.

See also:: SetUnspecifiedValueAppearance()

int wxPropertyGrid::GetVerticalSpacing ( ) const

Returns current vertical spacing.

bool wxPropertyGrid::HasSelection ( ) const

Returns true if a property is selected.

bool wxPropertyGrid::IsAnyModified ( ) const

Returns true if any property has been modified by the user.

bool wxPropertyGrid::IsEditorsValueModified ( ) const

Returns true if editor's value was marked modified.

bool wxPropertyGrid::IsFrozen ( ) const

Returns true if updating is frozen (ie.

Freeze() called but not yet Thaw() ).

void wxPropertyGrid::MakeColumnEditable	(	unsigned int	column,
		bool	editable = `true`
	)

Makes given column editable by user.

Parameters:

editable

Using here will disable column from being editable.

void wxPropertyGrid::OnTLPChanging ( wxWindow * newTLP )

It is recommended that you call this function any time your code causes wxPropertyGrid's top-level parent to change.

wxPropertyGrid's OnIdle() handler should be able to detect most changes, but it is not perfect.

Parameters:

newTLP

New top-level parent that is about to be set. Old one should still exist as the current one.

Remarks:: This function is automatically called from wxPropertyGrid:: Reparent() and wxPropertyGridManager::Reparent().

bool wxPropertyGrid::OnValidationFailure	(	wxPGProperty *	property,
		wxVariant &	invalidValue
	)

Called when validation for given property fails.

Parameters:

invalidValue

Value which failed in validation.

Return values:

Return

true if user is allowed to change to another property even if current has invalid value.

Remarks:: To add your own validation failure behavior, override wxPropertyGrid::DoOnValidationFailure().

virtual bool wxPropertyGrid::PerformValidation	(	wxPGProperty *	p,
		wxVariant &	pendingValue
	)			`[virtual]`

Runs all validation functionality (includes sending wxEVT_PG_CHANGING).

Returns true if all tests passed.

static wxPGEditor* wxPropertyGrid::RegisterEditorClass	(	wxPGEditor *	editor,
		const wxString &	name,
		bool	noDefCheck = `false`
	)			`[static]`

Registers a new editor class.

Return values:

Pointer

to the editor class instance that should be used.

bool wxPropertyGrid::RemoveFromSelection ( wxPGPropArg id )

Removes given property from selection.

If property is not selected, an assertion failure will occur.

void wxPropertyGrid::ResetColumnSizes ( bool enableAutoResizing = false )

Resets column sizes and splitter positions, based on proportions.

Parameters:

enableAutoResizing

If , automatic column resizing is enabled (only applicapple if window style wxPG_SPLITTER_AUTO_CENTER is used).

See also:: wxPropertyGridInterface::SetColumnProportion()

bool wxPropertyGrid::SelectProperty	(	wxPGPropArg	id,
		bool	focus = `false`
	)

Selects a property.

Editor widget is automatically created, but not focused unless focus is true. This will generate wxEVT_PG_SELECT event.

Parameters:

id

Id to property to select.

Return values:

True

if selection finished succesfully. Usually only fails if current value in editor is not valid.

Remarks:: This clears any previous selection.

See also:: wxPropertyGridInterface::ClearSelection()

void wxPropertyGrid::SetButtonShortcut	(	int	keycode,
		bool	ctrlDown = `false`,
		bool	altDown = `false`
	)

Changes keyboard shortcut to push the editor button.

Remarks:: You can set default with keycode 0. Good value for the platform is guessed, but don't expect it to be very accurate.

void wxPropertyGrid::SetCaptionBackgroundColour ( const wxColour & col )

Sets category caption background colour.

void wxPropertyGrid::SetCaptionForegroundColour ( const wxColour & col )

Sets category caption text colour.

void wxPropertyGrid::SetCellBackgroundColour ( const wxColour & col )

Sets default cell background colour - applies to property cells.

Note that appearance of editor widgets may not be affected.

void wxPropertyGrid::SetCellTextColour ( const wxColour & col )

Sets default cell text colour - applies to property name and value text.

Note that appearance of editor widgets may not be affected.

void wxPropertyGrid::SetEmptySpaceColour ( const wxColour & col )

Sets colour of empty space below properties.

void wxPropertyGrid::SetLineColour ( const wxColour & col )

Sets colour of lines between cells.

void wxPropertyGrid::SetMarginColour ( const wxColour & col )

Sets background colour of margin.

void wxPropertyGrid::SetPropertyAttributeAll	(	const wxString &	attrName,
		wxVariant	value
	)

Sets property attribute for all applicapple properties.

Be sure to use this method after all properties have been added to the grid.

void wxPropertyGrid::SetPropertyBackgroundColour	(	wxPGPropArg	id,
		const wxColour &	col,
		int	flags = `wxPG_RECURSE`
	)

Sets background colour of property and all its children.

Colours of captions are not affected. Background brush cache is optimized for often set colours to be set last.

Parameters:

flags

Default is wxPG_RECURSE which causes colour to be set recursively. Omit this flag to only set colour for the property in question and not any of its children.

void wxPropertyGrid::SetPropertyColour	(	wxPGPropArg	id,
		const wxColour &	col
	)

Sets background colour of property and all its children.

Colours of captions are not affected. Background brush cache is optimized for often set colours to be set last.

Deprecated:: Since version 1.3. Use SetPropertyBackgroundColour instead.

void wxPropertyGrid::SetPropertyColourToDefault ( wxPGPropArg id )

Sets background and text colour of property and all its children to the default.

void wxPropertyGrid::SetPropertyName	(	wxPGPropArg	id,
		const wxString &	newname
	)

Sets name of a property.

Parameters:

	id	Id of a property.
	newname	New name.

void wxPropertyGrid::SetPropertyTextColour	(	wxPGPropArg	id,
		const wxColour &	col,
		int	flags = `wxPG_RECURSE`
	)

Sets text colour of property and all its children.

Parameters:

flags

Default is wxPG_RECURSE which causes colour to be set recursively. Omit this flag to only set colour for the property in question and not any of its children.

void wxPropertyGrid::SetSelectionBackground ( const wxColour & col )

Sets selection background colour - applies to selected property name background.

void wxPropertyGrid::SetSelectionForeground ( const wxColour & col )

Sets selection foreground colour - applies to selected property name text.

void wxPropertyGrid::SetSortFunction ( wxPGSortCallback sortFunction )

Sets the property sorting function.

Parameters:

sortFunction

The sorting function to be used. It should return a value greater than 0 if position of p1 is after p2. So, for instance, when comparing property names, you can use following implementation:

                int MyPropertySortFunction(wxPropertyGrid* propGrid,
                                           wxPGProperty* p1,
                                           wxPGProperty* p2)
                {
                    return p1->GetBaseName().compare( p2->GetBaseName() );
                }

Remarks:: Default property sort function sorts properties by their labels.

void wxPropertyGrid::SetSplitterLeft ( bool subProps = false )

Moves splitter as left as possible, while still allowing all labels to be shown in full.

Parameters:

subProps

If false, will still allow sub-properties (ie. properties which parent is not root or category) to be cropped.

void wxPropertyGrid::SetSplitterPosition	(	int	newxpos,
		bool	refresh = `true`
	)

Sets x coordinate of the splitter.

Remarks:: Splitter position cannot exceed grid size, and therefore setting it during form creation may fail as initial grid size is often smaller than desired splitter position, especially when sizers are being used.

void wxPropertyGrid::SetUnspecifiedCommonValue ( int index )

Set index of common value that will truly change value to unspecified.

Using -1 will set none to have such effect. Default is 0.

void wxPropertyGrid::SetUnspecifiedValueAppearance ( const wxPGCell & cell )

Sets appearance of value cells representing an unspecified property value.

Default appearance is blank.

See also:: wxPGProperty::SetValueToUnspecified(), wxPGProperty::IsValueUnspecified(),

void wxPropertyGrid::SetupTextCtrlValue ( const wxString text )

Must be called in wxPGEditor::CreateControls() if primary editor window is wxTextCtrl, just before textctrl is created.

Parameters:

text

Initial text value of created wxTextCtrl.

void wxPropertyGrid::SetVerticalSpacing ( int vspacing )

Sets vertical spacing.

Can be 1, 2, or 3 - a value relative to font height. Value of 2 should be default on most platforms.

Remarks:: On wxMSW, wxComboBox, when used as property editor widget, will spill out with anything less than 3.

void wxPropertyGrid::SetVirtualWidth ( int width )

Set virtual width for this particular page.

Width -1 indicates that the virtual width should be disabled.

virtual void wxPropertyGrid::SetWindowStyleFlag ( long style ) [virtual]

Overridden function.

See also:: Additional Window Styles

void wxPropertyGrid::ShowPropertyError	(	wxPGPropArg	id,
		const wxString &	msg
	)

Shows an brief error message that is related to a property.

void wxPropertyGrid::Sort ( )

Sorts all items at all levels (except sub-properties).

void wxPropertyGrid::ValueChangeInEvent ( wxVariant variant )

Call this from wxPGProperty::OnEvent() to cause property value to be changed after the function returns (with true as return value).

ValueChangeInEvent() must be used if you wish the application to be able to use wxEVT_PG_CHANGING to potentially veto the given value.

bool wxPropertyGrid::WasValueChangedInEvent ( ) const

You can use this member function, for instance, to detect in wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was already called in wxPGEditor::OnEvent().

It really only detects if was value was changed using wxPGProperty::SetValueInEvent(), which is usually used when a 'picker' dialog is displayed. If value was written by "normal means" in wxPGProperty::StringToValue() or IntToValue(), then this function will return false (on the other hand, wxPGProperty::OnEvent() is not even called in those cases).

The documentation for this class was generated from the following file:

propgrid.h

wxPropertyGrid Class Reference

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Derived from

Include files

Window styles

Event handling

Constructor & Destructor Documentation

Member Function Documentation