phoenix_title wx.propgrid.PropertyGrid

wx.propgrid.PropertyGrid is a specialized grid for editing properties - in other words name = value pairs.

List of ready-to-use property classes include strings, numbers, flag sets, fonts, colours and many others. It is possible, for example, to categorize properties, set up a complete tree-hierarchy, add more than two columns, and set arbitrary per-property attributes.

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 wx.propgrid.PropertyGridInterface class reference.

See also PropertyGrid Overview.

phoenix_title Window Styles

See PropertyGrid Window Styles.

phoenix_title Event Handling

Please see wx.propgrid.PropertyGridEvent for the documentation of all event types you can use with wx.propgrid.PropertyGrid.

Note

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


class_hierarchy Class Hierarchy

Inheritance diagram for class PropertyGrid:

method_summary Methods Summary

__init__

Two step constructor.

AddActionTrigger

Adds given key combination to trigger given action.

AddToSelection

Adds given property into selection.

AdjustScrollbars

AutoGetTranslation

This static function enables or disables automatic use of wx.GetTranslation for following strings: wx.propgrid.EnumProperty list labels, wx.propgrid.FlagsProperty child property labels.

BeginLabelEdit

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

CalcScrolledPosition

Translates the logical coordinates to the device ones.

CalcUnscrolledPosition

Translates the device coordinates to the logical ones.

CenterSplitter

Centers the splitter.

ChangePropertyValue

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

Clear

Deletes all properties.

ClearActionTriggers

Clears action triggers for given action.

CommitChangesFromEditor

Forces updating the value of property from the editor control.

Create

Two step creation.

DedicateKey

Dedicates a specific keycode to wx.propgrid.PropertyGrid.

DisableKeyboardScrolling

Disable use of keyboard keys for scrolling.

DoHidePropertyError

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

DoOnValidationFailure

Override to customize property validation failure behaviour.

DoOnValidationFailureReset

Override to customize resetting of property validation failure status.

DoPrepareDC

Call this function to prepare the device context for drawing a scrolled image.

DoRegisterEditorClass

Registers a new editor class.

DoShowPropertyError

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

DrawItemAndValueRelated

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

EditorsValueWasModified

Call when editor widget’s contents is modified.

EditorsValueWasNotModified

Reverse of EditorsValueWasModified .

EnableCategories

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

EnableScrolling

Enable or disable use of wx.Window.ScrollWindow for scrolling.

EndLabelEdit

Destroys label editor wx.TextCtrl, if any.

EnsureVisible

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

FitColumns

Reduces column sizes to minimum possible, while still retaining fully visible grid contents (labels, images).

GetCaptionBackgroundColour

Returns current category caption background colour.

GetCaptionFont

Returns current category caption font.

GetCaptionForegroundColour

Returns current category caption text colour.

GetCellBackgroundColour

Returns current cell background colour.

GetCellDisabledTextColour

Returns current cell text colour when disabled.

GetCellTextColour

Returns current cell text colour.

GetClassDefaultAttributes

GetColumnCount

Returns number of columns currently on grid.

GetEditorTextCtrl

Returns wx.TextCtrl active in currently selected property, if any.

GetEmptySpaceColour

Returns colour of empty space below properties.

GetFontHeight

Returns height of highest characters of used font.

GetGrid

Returns pointer to itself.

GetImageRect

Returns rectangle of custom paint image.

GetImageSize

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

GetLabelEditor

Returns currently active label editor, None if none.

GetLastItem

Returns last item which could be iterated using given flags.

GetLineColour

Returns colour of lines between cells.

GetMarginColour

Returns background colour of margin.

GetMarginWidth

Returns margin width.

GetPanel

Returns wx.Window that the properties are painted on, and which should be used as the parent for editor controls.

GetRoot

Returns “root property”.

GetRowHeight

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

GetScaleX

GetScaleY

GetScrollLines

GetScrollPageSize

GetScrollPixelsPerUnit

Get the number of pixels per scroll unit (line), in each direction, as set by SetScrollbars .

GetSelectedProperty

Returns currently selected property.

GetSelection

Returns currently selected property.

GetSelectionBackgroundColour

Returns current selection background colour.

GetSelectionForegroundColour

Returns current selection text colour.

GetSizeAvailableForScrollTarget

Function which must be overridden to implement the size available for the scroll target for the given size of the main window.

GetSplitterPosition

Returns current splitter x position.

GetStatusBar

Return wx.StatusBar that is used by this wx.propgrid.PropertyGrid.

GetTargetRect

GetTargetWindow

GetUncommittedPropertyValue

Returns most up-to-date value of selected property.

GetUnspecifiedValueAppearance

Returns current appearance of unspecified value cells.

GetUnspecifiedValueText

Returns (visual) text representation of the unspecified property value.

GetVerticalSpacing

Returns current vertical spacing.

GetViewStart

Get the position at which the visible portion of the window starts.

HitTest

Returns information about arbitrary position in the grid.

IsAnyModified

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

IsAutoScrolling

Are we generating the autoscroll events?

IsEditorFocused

Returns True if a property editor control has focus.

IsEditorsValueModified

Returns True if editor’s value was marked modified.

IsFrozen

Returns True if updating is frozen (i.e.

IsRetained

Motif only: True if the window has a backing bitmap.

MakeColumnEditable

Makes given column editable by user.

OnDraw

Called by the default paint event handler to allow the application to define painting behaviour without having to worry about calling DoPrepareDC .

OnTLPChanging

It is recommended that you call this function any time your code causes wx.propgrid.PropertyGrid’s top-level parent to change.

PrepareDC

This function is for backwards compatibility only and simply calls DoPrepareDC now.

RefreshEditor

Refreshes any active editor control.

RefreshProperty

Redraws given property.

RegisterEditorClass

Forwards to DoRegisterEditorClass with empty name.

RemoveFromSelection

Removes given property from selection.

ResetColours

Resets all colours to the original system values.

ResetColumnSizes

Resets column sizes and splitter positions, based on proportions.

Scroll

Scrolls a window so the view start is at the given point.

SelectProperty

Selects a property.

SendAutoScrollEvents

This method can be overridden in a derived class to forbid sending the auto scroll events - note that unlike StopAutoScrolling it doesn’t stop the timer, so it will be called repeatedly and will typically return different values depending on the current mouse position.

SetCaptionBackgroundColour

Sets category caption background colour.

SetCaptionTextColour

Sets category caption text colour.

SetCellBackgroundColour

Sets default cell background colour - applies to property cells.

SetCellDisabledTextColour

Sets cell text colour for disabled properties.

SetCellTextColour

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

SetColumnCount

Set number of columns (2 or more).

SetCurrentCategory

Sets the ‘current’ category - Append will add non-category properties under it.

SetEmptySpaceColour

Sets colour of empty space below properties.

SetLineColour

Sets colour of lines between cells.

SetMarginColour

Sets background colour of margin.

SetScale

SetScrollPageSize

SetScrollRate

Set the horizontal and vertical scrolling increment only.

SetScrollbars

Sets up vertical and/or horizontal scrollbars.

SetSelection

Set entire new selection from given list of properties.

SetSelectionBackgroundColour

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

SetSelectionTextColour

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

SetSplitterLeft

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

SetSplitterPosition

Sets x coordinate of the splitter.

SetTargetRect

SetTargetWindow

Call this function to tell wx.Scrolled to perform the actual scrolling on a different window (and not on itself).

SetUnspecifiedValueAppearance

Sets appearance of value cells representing an unspecified property value.

SetVerticalSpacing

Sets vertical spacing.

SetVirtualWidth

Set virtual width for this particular page.

SetupTextCtrlValue

Must be called in wx.propgrid.PGEditor.CreateControls if primary editor window is wx.TextCtrl, just before textctrl is created.

ShouldScrollToChildOnFocus

This method can be overridden in a derived class to prevent scrolling the child window into view automatically when it gets focus.

ShowPropertyError

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

ShowScrollbars

Set the scrollbar visibility.

StopAutoScrolling

Stop generating the scroll events when mouse is held outside the window.

UnfocusEditor

Unfocuses or closes editor if one was open, but does not deselect property.

ValueChangeInEvent

Call this from wx.propgrid.PGProperty.OnEvent to cause property value to be changed after the function returns (with True as return value).

WasValueChangedInEvent

You can use this member function, for instance, to detect in wx.propgrid.PGProperty.OnEvent if wx.propgrid.PGProperty.SetValueInEvent was already called in wx.propgrid.PGEditor.OnEvent .


property_summary Properties Summary

CaptionBackgroundColour

See GetCaptionBackgroundColour and SetCaptionBackgroundColour

CaptionFont

See GetCaptionFont

CaptionForegroundColour

See GetCaptionForegroundColour

CellBackgroundColour

See GetCellBackgroundColour and SetCellBackgroundColour

CellDisabledTextColour

See GetCellDisabledTextColour and SetCellDisabledTextColour

CellTextColour

See GetCellTextColour and SetCellTextColour

ColumnCount

See GetColumnCount and SetColumnCount

EditorTextCtrl

See GetEditorTextCtrl

EmptySpaceColour

See GetEmptySpaceColour and SetEmptySpaceColour

FontHeight

See GetFontHeight

Grid

See GetGrid

ImageSize

See GetImageSize

LabelEditor

See GetLabelEditor

LastItem

See GetLastItem

LineColour

See GetLineColour and SetLineColour

MarginColour

See GetMarginColour and SetMarginColour

MarginWidth

See GetMarginWidth

Panel

See GetPanel

Root

See GetRoot

RowHeight

See GetRowHeight

ScaleX

See GetScaleX

ScaleY

See GetScaleY

SelectedProperty

See GetSelectedProperty

Selection

See GetSelection and SetSelection

SelectionBackgroundColour

See GetSelectionBackgroundColour and SetSelectionBackgroundColour

SelectionForegroundColour

See GetSelectionForegroundColour

SplitterPosition

See GetSplitterPosition and SetSplitterPosition

StatusBar

See GetStatusBar

TargetRect

See GetTargetRect and SetTargetRect

TargetWindow

See GetTargetWindow and SetTargetWindow

UncommittedPropertyValue

See GetUncommittedPropertyValue

UnspecifiedValueAppearance

See GetUnspecifiedValueAppearance and SetUnspecifiedValueAppearance

UnspecifiedValueText

See GetUnspecifiedValueText

VerticalSpacing

See GetVerticalSpacing and SetVerticalSpacing


api Class API

class wx.propgrid.PropertyGrid(Control, PropertyGridInterface)

Possible constructors:

PropertyGrid()

PropertyGrid(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize,
             style=PG_DEFAULT_STYLE, name=PropertyGridNameStr)

PropertyGrid is a specialized grid for editing properties - in other words name = value pairs.


Methods

__init__(self, *args, **kw)

overload Overloaded Implementations:



__init__ (self)

Two step constructor.

Call Create when this constructor is called to build up the wx.propgrid.PropertyGrid



__init__ (self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=PG_DEFAULT_STYLE, name=PropertyGridNameStr)

Constructor.

The styles to be used are styles valid for the wx.Window.

Parameters

See also

PropertyGrid Window Styles.





AddActionTrigger(self, action, keycode, modifiers=0)

Adds given key combination to trigger given action.

Here is a sample code to make Enter key press move focus to the next property.

propGrid.AddActionTrigger(wx.propgrid.PG_ACTION_NEXT_PROPERTY,
                          wx.WXK_RETURN)
propGrid.DedicateKey(wx.WXK_RETURN)
Parameters
  • action (int) – Which action to trigger. See PropertyGrid Action Identifiers.

  • keycode (int) – Which keycode triggers the action.

  • modifiers (int) – Which key event modifiers, in addition to keycode, are needed to trigger the action.



AddToSelection(self, id)

Adds given property into selection.

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

Parameters

id (wx.propgrid.PGPropArgCls) –

Return type

bool

Note

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.



AdjustScrollbars(self)


static AutoGetTranslation(enable)

This static function enables or disables automatic use of wx.GetTranslation for following strings: wx.propgrid.EnumProperty list labels, wx.propgrid.FlagsProperty child property labels.

Default is False.

Parameters

enable (bool) –



BeginLabelEdit(self, colIndex=0)

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

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

Parameters

colIndex (int) – Which column’s label to edit. Note that you should not use value 1, which is reserved for property value column.



CalcScrolledPosition(self, *args, **kw)

overload Overloaded Implementations:



CalcScrolledPosition (self, x, y)

Translates the logical coordinates to the device ones.

For example, if a window is scrolled 10 pixels to the bottom, the device coordinates of the origin are (0, 0) (as always), but the logical coordinates are (0, 10) and so the call to CalcScrolledPosition(0, 10, xx, yy) will return 0 in yy.



CalcScrolledPosition (self, pt)

Parameters

pt (wx.Point) –

Return type

wx.Point





CalcUnscrolledPosition(self, *args, **kw)

overload Overloaded Implementations:



CalcUnscrolledPosition (self, x, y)

Translates the device coordinates to the logical ones.

For example, if a window is scrolled 10 pixels to the bottom, the device coordinates of the origin are (0, 0) (as always), but the logical coordinates are (0, 10) and so the call to CalcUnscrolledPosition(0, 0, xx, yy) will return 10 in yy.



CalcUnscrolledPosition (self, pt)

Parameters

pt (wx.Point) –

Return type

wx.Point





CenterSplitter(self, enableAutoResizing=False)

Centers the splitter.

Parameters

enableAutoResizing (bool) – If True, automatic column resizing is enabled (only applicable if window style PG_SPLITTER_AUTO_CENTER is used).



ChangePropertyValue(self, id, 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 wxEVT_PG_CHANGED .

Parameters
Return type

bool

Returns

Returns True if value was successfully changed.

Note

Since this function sends wxEVT_PG_CHANGED , it should not be called from EVT_PG_CHANGED handler.



Clear(self)

Deletes all properties.



ClearActionTriggers(self, action)

Clears action triggers for given action.

Parameters

action (int) – Which action to trigger. PropertyGrid Action Identifiers.



CommitChangesFromEditor(self, flags=0)

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.

Parameters

flags (wx.int) –

Return type

bool

Returns

Returns True if anything was changed.



Create(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=PG_DEFAULT_STYLE, name=PropertyGridNameStr)

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

Parameters
Return type

bool

See also

PropertyGrid Window Styles.



DedicateKey(self, keycode)

Dedicates a specific keycode to wx.propgrid.PropertyGrid.

This means that such key presses will not be redirected to editor controls.

Using this function allows, for example, navigation between properties using arrow keys even when the focus is in the editor control.

Parameters

keycode (int) –



DisableKeyboardScrolling(self)

Disable use of keyboard keys for scrolling.

By default cursor movement keys (including Home, End, Page Up and Down) are used to scroll the window appropriately. If the derived class uses these keys for something else, e.g. changing the currently selected item, this function can be used to disable this behaviour as it’s not only not necessary then but can actually be actively harmful if another object forwards a keyboard event corresponding to one of the above keys to us using ProcessWindowEvent() because the event will always be processed which can be undesirable.

New in version 2.9.1.



DoHidePropertyError(self, property)

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

Parameters

property (wx.propgrid.PGProperty) –



DoOnValidationFailure(self, property, invalidValue)

Override to customize property validation failure behaviour.

Parameters
  • property (wx.propgrid.PGProperty) – Property with entered an invalid value

  • invalidValue (PGVariant) – Value which failed in validation.

Return type

bool

Returns

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



DoOnValidationFailureReset(self, property)

Override to customize resetting of property validation failure status.

Parameters

property (wx.propgrid.PGProperty) –

Note

Property is guaranteed to have flag PG_PROP_INVALID_VALUE set.



DoPrepareDC(self, dc)

Call this function to prepare the device context for drawing a scrolled image.

It sets the device origin according to the current scroll position. DoPrepareDC is called automatically within the default wxEVT_PAINT event handler, so your OnDraw override will be passed an already ‘pre-scrolled’ device context. However, if you wish to draw from outside of OnDraw (e.g. from your own wxEVT_PAINT handler), you must call this function yourself.

For example:

def OnEvent(self, event):

    dc = wx.ClientDC(self)
    self.DoPrepareDC(dc)

    dc.SetPen(wx.BLACK_PEN)

    x, y = event.GetPosition()

    if (xpos > -1 and ypos > -1 and event.Dragging()):
        dc.DrawLine(xpos, ypos, x, y)

    xpos = x
    ypos = y

Notice that the function sets the origin by moving it relatively to the current origin position, so you shouldn’t change the origin before calling DoPrepareDC or, if you do, reset it to (0, 0) later. If you call DoPrepareDC immediately after device context creation, as in the example above, this problem doesn’t arise, of course, so it is customary to do it like this.

Parameters

dc (wx.DC) –



static DoRegisterEditorClass(editor, name, noDefCheck=False)

Registers a new editor class.

Parameters
Return type

wx.propgrid.PGEditor

Returns

Returns pointer to the editor class instance that should be used.



DoShowPropertyError(self, property, msg)

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

Parameters

Note

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).



DrawItemAndValueRelated(self, p)

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

Parameters

p (wx.propgrid.PGProperty) –



EditorsValueWasModified(self)

Call when editor widget’s contents is modified.

For example, this is called when changes text in wx.TextCtrl (used in wx.propgrid.StringProperty and wx.propgrid.IntProperty).

Note

This function should only be called by custom properties.



EditorsValueWasNotModified(self)

Reverse of EditorsValueWasModified .

Note

This function should only be called by custom properties.



EnableCategories(self, enable)

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

Parameters

enable (bool) –

Return type

bool

Note

This functions deselects selected property, if any. Validation failure option PG_VFB_STAY_IN_PROPERTY is not respected, i.e. selection is cleared even if editor had invalid value.



EnableScrolling(self, xScrolling, yScrolling)

Enable or disable use of wx.Window.ScrollWindow for scrolling.

By default, when a scrolled window is logically scrolled, wx.Window.ScrollWindow is called on the underlying window which scrolls the window contents and only invalidates the part of the window newly brought into view. If False is passed as an argument, then this “physical scrolling” is disabled and the window is entirely invalidated whenever it is scrolled by calling wx.Window.Refresh .

It should be rarely necessary to disable physical scrolling, so this method shouldn’t be called in normal circumstances.

Parameters
  • xScrolling (bool) – If True, enables physical scrolling in the x direction.

  • yScrolling (bool) – If True, enables physical scrolling in the y direction.



EndLabelEdit(self, commit=True)

Destroys label editor wx.TextCtrl, if any.

Parameters

commit (bool) – Use True (default) to store edited label text in property cell data.



EnsureVisible(self, id)

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

Parameters

id (wx.propgrid.PGPropArgCls) –

Return type

bool

Returns

Returns True if something was actually done.



FitColumns(self)

Reduces column sizes to minimum possible, while still retaining fully visible grid contents (labels, images).

Return type

Size

Returns

Minimum size for the grid to still display everything.

Note

Does not work well with PG_SPLITTER_AUTO_CENTER window style.



GetCaptionBackgroundColour(self)

Returns current category caption background colour.

Return type

Colour



GetCaptionFont(self)

Returns current category caption font.

Return type

Font



GetCaptionForegroundColour(self)

Returns current category caption text colour.

Return type

Colour



GetCellBackgroundColour(self)

Returns current cell background colour.

Return type

Colour



GetCellDisabledTextColour(self)

Returns current cell text colour when disabled.

Return type

Colour



GetCellTextColour(self)

Returns current cell text colour.

Return type

Colour



static GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)
Parameters

variant (WindowVariant) –

Return type

VisualAttributes



GetColumnCount(self)

Returns number of columns currently on grid.

Return type

int



GetEditorTextCtrl(self)

Returns wx.TextCtrl active in currently selected property, if any.

Takes wx.adv.OwnerDrawnComboBox into account.

Return type

TextCtrl



GetEmptySpaceColour(self)

Returns colour of empty space below properties.

Return type

Colour



GetFontHeight(self)

Returns height of highest characters of used font.

Return type

int



GetGrid(self)

Returns pointer to itself.

Dummy function that enables same kind of code to use wx.propgrid.PropertyGrid and wx.propgrid.PropertyGridManager.

Return type

wx.propgrid.PropertyGrid



GetImageRect(self, property, item)

Returns rectangle of custom paint image.

Parameters
  • property (wx.propgrid.PGProperty) – Return image rectangle for this property.

  • item (int) – Which choice of property to use (each choice may have different image).

Return type

Rect



GetImageSize(self, property=None, item=-1)

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

Parameters
  • property (wx.propgrid.PGProperty) – Return image rectangle for this property. If this argument is None, then preferred size is returned.

  • item (int) – Which choice of property to use (each choice may have different image).

Return type

Size



GetLabelEditor(self)

Returns currently active label editor, None if none.

Return type

TextCtrl



GetLastItem(self, flags=PG_ITERATE_DEFAULT)

Returns last item which could be iterated using given flags.

Parameters

flags (int) – See PropertyGridIterator Flags.

Return type

wx.propgrid.PGProperty



GetLineColour(self)

Returns colour of lines between cells.

Return type

Colour



GetMarginColour(self)

Returns background colour of margin.

Return type

Colour



GetMarginWidth(self)

Returns margin width.

Return type

int



GetPanel(self)

Returns wx.Window that the properties are painted on, and which should be used as the parent for editor controls.

Return type

Window



GetRoot(self)

Returns “root property”.

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

Return type

wx.propgrid.PGProperty



GetRowHeight(self)

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

Return type

int



GetScaleX(self)
Return type

float



GetScaleY(self)
Return type

float



GetScrollLines(self, orient)
Parameters

orient (int) –

Return type

int



GetScrollPageSize(self, orient)
Parameters

orient (int) –

Return type

int



GetScrollPixelsPerUnit(self)

Get the number of pixels per scroll unit (line), in each direction, as set by SetScrollbars .

A value of zero indicates no scrolling in that direction.

Return type

tuple



GetSelectedProperty(self)

Returns currently selected property.

Return type

wx.propgrid.PGProperty



GetSelection(self)

Returns currently selected property.

Return type

wx.propgrid.PGProperty



GetSelectionBackgroundColour(self)

Returns current selection background colour.

Return type

Colour



GetSelectionForegroundColour(self)

Returns current selection text colour.

Return type

Colour



GetSizeAvailableForScrollTarget(self, size)

Function which must be overridden to implement the size available for the scroll target for the given size of the main window.

This method must be overridden if SetTargetWindow is used (it is never called otherwise). The implementation should decrease the size to account for the size of the non-scrollable parts of the main window and return only the size available for the scrollable window itself. E.g. in the example given in SetTargetWindow documentation the function would subtract the height of the header window from the vertical component of size.

Parameters

size (wx.Size) –

Return type

wx.Size



GetSplitterPosition(self, splitterIndex=0)

Returns current splitter x position.

Parameters

splitterIndex (int) –

Return type

int



GetStatusBar(self)

Return wx.StatusBar that is used by this wx.propgrid.PropertyGrid.

You can reimplement this member function in derived class to override the default behaviour of using the top-level wx.Frame’s status bar, if any.

Return type

StatusBar



GetTargetRect(self)
Return type

wx.Rect



GetTargetWindow(self)
Return type

wx.Window



GetUncommittedPropertyValue(self)

Returns most up-to-date value of selected property.

This will return value different from GetSelectedProperty .GetValue() only when text editor is activate and string edited by user represents valid, uncommitted property value.

Return type

PGVariant



GetUnspecifiedValueAppearance(self)

Returns current appearance of unspecified value cells.

Return type

wx.propgrid.PGCell



GetUnspecifiedValueText(self, argFlags=0)

Returns (visual) text representation of the unspecified property value.

Parameters

argFlags (int) – For internal use only.

Return type

string



GetVerticalSpacing(self)

Returns current vertical spacing.

Return type

int



GetViewStart(self)

Get the position at which the visible portion of the window starts.

Return type

tuple



HitTest(self, pt)

Returns information about arbitrary position in the grid.

Parameters

pt (wx.Point) – Coordinates in the virtual grid space. You may need to use wx.Scrolled.CalcScrolledPosition for translating wx.propgrid.PropertyGrid client coordinates into something this member function can use.

Return type

wx.propgrid.PropertyGridHitTestResult



IsAnyModified(self)

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

Return type

bool



IsAutoScrolling(self)

Are we generating the autoscroll events?

Return type

bool



IsEditorFocused(self)

Returns True if a property editor control has focus.

Return type

bool



IsEditorsValueModified(self)

Returns True if editor’s value was marked modified.

Return type

bool



IsFrozen(self)

Returns True if updating is frozen (i.e.

Freeze called but not yet Thaw ).

Return type

bool



IsRetained(self)

Motif only: True if the window has a backing bitmap.

Return type

bool



MakeColumnEditable(self, column, editable=True)

Makes given column editable by user.

Parameters
  • column (int) – The index of the column to make editable.

  • editable (bool) – Using False here will disable column from being editable.

column must not be equal to 1, as the second column is always editable and can be made read-only only on cell-by-cell basis using:

property.ChangeFlag(wx.propgrid.PG_PROP_READONLY, True)


OnDraw(self, dc)

Called by the default paint event handler to allow the application to define painting behaviour without having to worry about calling DoPrepareDC .

Instead of overriding this function you may also just process the paint event in the derived class as usual, but then you will have to call DoPrepareDC yourself.

Parameters

dc (wx.DC) –



OnTLPChanging(self, newTLP)

It is recommended that you call this function any time your code causes wx.propgrid.PropertyGrid’s top-level parent to change.

wx.propgrid.PropertyGrid’s OnIdle() handler should be able to detect most changes, but it is not perfect.

Parameters

newTLP (wx.Window) – New top-level parent that is about to be set. Old top-level parent window should still exist as the current one.

Note

This function is automatically called from wx.propgrid.PropertyGrid:: Reparent and wx.propgrid.PropertyGridManager.Reparent . You only need to use it if you reparent wx.propgrid.PropertyGrid indirectly.



PrepareDC(self, dc)

This function is for backwards compatibility only and simply calls DoPrepareDC now.

Notice that it is not called by the default paint event handle ( DoPrepareDC is), so overriding this method in your derived class is useless.

Parameters

dc (wx.DC) –



RefreshEditor(self)

Refreshes any active editor control.



RefreshProperty(self, p)

Redraws given property.

Parameters

p (wx.propgrid.PGProperty) –



static RegisterEditorClass(editor, noDefCheck=False)

Forwards to DoRegisterEditorClass with empty name.

Parameters
Return type

wx.propgrid.PGEditor



RemoveFromSelection(self, id)

Removes given property from selection.

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

Parameters

id (wx.propgrid.PGPropArgCls) –

Return type

bool



ResetColours(self)

Resets all colours to the original system values.



ResetColumnSizes(self, enableAutoResizing=False)

Resets column sizes and splitter positions, based on proportions.

Parameters

enableAutoResizing (bool) – If True, automatic column resizing is enabled (only applicable if window style PG_SPLITTER_AUTO_CENTER is used).



Scroll(self, *args, **kw)

overload Overloaded Implementations:



Scroll (self, x, y)

Scrolls a window so the view start is at the given point.

Parameters
  • x (int) – The x position to scroll to, in scroll units.

  • y (int) – The y position to scroll to, in scroll units.

Note

The positions are in scroll units, not pixels, so to convert to pixels you will have to multiply by the number of pixels per scroll increment. If either parameter is wx.DefaultCoord (-1), that position will be ignored (no change in that direction).



Scroll (self, pt)

This is an overload of Scroll ; see that function for more info.

Parameters

pt (wx.Point) –





SelectProperty(self, id, focus=False)

Selects a property.

Editor widget is automatically created, but not focused unless focus is True.

Parameters
  • id (wx.propgrid.PGPropArgCls) – Property to select (name or pointer).

  • focus (bool) – If True, move keyboard focus to the created editor right away.

Return type

bool

Returns

returns True if selection finished successfully. Usually only fails if current value in editor is not valid.

Note

In wxWidgets 2.9 and later, this function no longer sends wxEVT_PG_SELECTED .

Note

This clears any previous selection.



SendAutoScrollEvents(self, event)

This method can be overridden in a derived class to forbid sending the auto scroll events - note that unlike StopAutoScrolling it doesn’t stop the timer, so it will be called repeatedly and will typically return different values depending on the current mouse position.

The base class version just returns True.

Parameters

event (wx.ScrollWinEvent) –

Return type

bool



SetCaptionBackgroundColour(self, col)

Sets category caption background colour.

Parameters

col (wx.Colour) –



SetCaptionTextColour(self, col)

Sets category caption text colour.

Parameters

col (wx.Colour) –



SetCellBackgroundColour(self, col)

Sets default cell background colour - applies to property cells.

Note that appearance of editor widgets may not be affected.

Parameters

col (wx.Colour) –



SetCellDisabledTextColour(self, col)

Sets cell text colour for disabled properties.

Parameters

col (wx.Colour) –



SetCellTextColour(self, col)

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

Note that appearance of editor widgets may not be affected.

Parameters

col (wx.Colour) –



SetColumnCount(self, colCount)

Set number of columns (2 or more).

Parameters

colCount (int) –



SetCurrentCategory(self, id)

Sets the ‘current’ category - Append will add non-category properties under it.

Parameters

id (wx.propgrid.PGPropArgCls) –



SetEmptySpaceColour(self, col)

Sets colour of empty space below properties.

Parameters

col (wx.Colour) –



SetLineColour(self, col)

Sets colour of lines between cells.

Parameters

col (wx.Colour) –



SetMarginColour(self, col)

Sets background colour of margin.

Parameters

col (wx.Colour) –



SetScale(self, xs, ys)
Parameters
  • xs (float) –

  • ys (float) –



SetScrollPageSize(self, orient, pageSize)
Parameters
  • orient (int) –

  • pageSize (int) –



SetScrollRate(self, xstep, ystep)

Set the horizontal and vertical scrolling increment only.

See the pixelsPerUnit parameter in SetScrollbars .

Parameters
  • xstep (int) –

  • ystep (int) –



SetScrollbars(self, pixelsPerUnitX, pixelsPerUnitY, noUnitsX, noUnitsY, xPos=0, yPos=0, noRefresh=False)

Sets up vertical and/or horizontal scrollbars.

The first pair of parameters give the number of pixels per ‘scroll step’, i.e. amount moved when the up or down scroll arrows are pressed. The second pair gives the length of scrollbar in scroll steps, which sets the size of the virtual window.

xPos and yPos optionally specify a position to scroll to immediately.

For example, the following gives a window horizontal and vertical scrollbars with 20 pixels per scroll step, and a size of 50 steps (1000 pixels) in each direction:

window.SetScrollbars(20, 20, 50, 50)

wx.Scrolled manages the page size itself, using the current client window size as the page size.

Note that for more sophisticated scrolling applications, for example where scroll steps may be variable according to the position in the document, it will be necessary to derive a new class from wx.Window, overriding OnSize() and adjusting the scrollbars appropriately.

Parameters
  • pixelsPerUnitX (int) – Pixels per scroll unit in the horizontal direction.

  • pixelsPerUnitY (int) – Pixels per scroll unit in the vertical direction.

  • noUnitsX (int) – Number of units in the horizontal direction.

  • noUnitsY (int) – Number of units in the vertical direction.

  • xPos (int) – Position to initialize the scrollbars in the horizontal direction, in scroll units.

  • yPos (int) – Position to initialize the scrollbars in the vertical direction, in scroll units.

  • noRefresh (bool) – Will not refresh window if True.



SetSelection(self, newSelection)

Set entire new selection from given list of properties.

Parameters

newSelection (ArrayPGProperty) –



SetSelectionBackgroundColour(self, col)

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

Parameters

col (wx.Colour) –



SetSelectionTextColour(self, col)

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

Parameters

col (wx.Colour) –



SetSplitterLeft(self, privateChildrenToo=False)

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

Parameters

privateChildrenToo (bool) – If False, will still allow private children to be cropped.



SetSplitterPosition(self, newxpos, col=0)

Sets x coordinate of the splitter.

Parameters
  • newxpos (int) –

  • col (int) –

Note

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.



SetTargetRect(self, rect)
Parameters

rect (wx.Rect) –



SetTargetWindow(self, window)

Call this function to tell wx.Scrolled to perform the actual scrolling on a different window (and not on itself).

This method is useful when only a part of the window should be scrolled. A typical example is a control consisting of a fixed header and the scrollable contents window: the scrollbars are attached to the main window itself, hence it, and not the contents window must be derived from wx.Scrolled, but only the contents window scrolls when the scrollbars are used. To implement such setup, you need to call this method with the contents window as argument.

Notice that if this method is used, GetSizeAvailableForScrollTarget method must be overridden.

Parameters

window (wx.Window) –



SetUnspecifiedValueAppearance(self, cell)

Sets appearance of value cells representing an unspecified property value.

Default appearance is blank.

Parameters

cell (wx.propgrid.PGCell) –

Note

If you set the unspecified value to have any textual representation, then that will override “InlineHelp” attribute.



SetVerticalSpacing(self, 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.

Parameters

vspacing (int) –



SetVirtualWidth(self, width)

Set virtual width for this particular page.

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

Parameters

width (int) –



SetupTextCtrlValue(self, text)

Must be called in wx.propgrid.PGEditor.CreateControls if primary editor window is wx.TextCtrl, just before textctrl is created.

Parameters

text (string) – Initial text value of created wx.TextCtrl.



ShouldScrollToChildOnFocus(self, child)

This method can be overridden in a derived class to prevent scrolling the child window into view automatically when it gets focus.

The default behaviour is to scroll this window to show its currently focused child automatically, to ensure that the user can interact with it. This is usually helpful, but can be undesirable for some windows, in which case this method can be overridden to return False for them to prevent any scrolling from taking place when such windows get focus.

Parameters

child (wx.Window) –

Return type

bool

New in version 4.1/wxWidgets-3.1.3.



ShowPropertyError(self, id, msg)

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

Parameters


ShowScrollbars(self, horz, vert)

Set the scrollbar visibility.

By default the scrollbar in the corresponding direction is only shown if it is needed, i.e. if the virtual size of the scrolled window in this direction is greater than the current physical window size. Using this function the scrollbar visibility can be changed to be:

  • wx.SHOW_SB_ALWAYS: To always show the scrollbar, even if it is not needed currently (wx``wx.ALWAYS_SHOW_SB`` style can be used during the window creation to achieve the same effect but it applies in both directions).

  • wx.SHOW_SB_NEVER: To never show the scrollbar at all. In this case the program should presumably provide some other way for the user to scroll the window.

  • wx.SHOW_SB_DEFAULT: To restore the default behaviour described above.

Note that the window must be created before calling this method.

Parameters

New in version 2.9.0.



StopAutoScrolling(self)

Stop generating the scroll events when mouse is held outside the window.



UnfocusEditor(self)

Unfocuses or closes editor if one was open, but does not deselect property.

Return type

bool



ValueChangeInEvent(self, variant)

Call this from wx.propgrid.PGProperty.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.

Parameters

variant (PGVariant) –



WasValueChangedInEvent(self)

You can use this member function, for instance, to detect in wx.propgrid.PGProperty.OnEvent if wx.propgrid.PGProperty.SetValueInEvent was already called in wx.propgrid.PGEditor.OnEvent .

It really only detects if was value was changed using wx.propgrid.PGProperty.SetValueInEvent , which is usually used when a ‘picker’ dialog is displayed. If value was written by “normal means” in wx.propgrid.PGProperty.StringToValue or IntToValue(), then this function will return False (on the other hand, wx.propgrid.PGProperty.OnEvent is not even called in those cases).

Return type

bool


Properties

CaptionBackgroundColour

See GetCaptionBackgroundColour and SetCaptionBackgroundColour



CaptionFont

See GetCaptionFont



CaptionForegroundColour

See GetCaptionForegroundColour



CellBackgroundColour

See GetCellBackgroundColour and SetCellBackgroundColour



CellDisabledTextColour

See GetCellDisabledTextColour and SetCellDisabledTextColour



CellTextColour

See GetCellTextColour and SetCellTextColour



ColumnCount

See GetColumnCount and SetColumnCount



EditorTextCtrl

See GetEditorTextCtrl



EmptySpaceColour

See GetEmptySpaceColour and SetEmptySpaceColour



FontHeight

See GetFontHeight



Grid

See GetGrid



ImageSize

See GetImageSize



LabelEditor

See GetLabelEditor



LastItem

See GetLastItem



LineColour

See GetLineColour and SetLineColour



MarginColour

See GetMarginColour and SetMarginColour



MarginWidth

See GetMarginWidth



Panel

See GetPanel



Root

See GetRoot



RowHeight

See GetRowHeight



ScaleX

See GetScaleX



ScaleY

See GetScaleY



SelectedProperty

See GetSelectedProperty



Selection

See GetSelection and SetSelection



SelectionBackgroundColour

See GetSelectionBackgroundColour and SetSelectionBackgroundColour



SelectionForegroundColour

See GetSelectionForegroundColour



SplitterPosition

See GetSplitterPosition and SetSplitterPosition



StatusBar

See GetStatusBar



TargetRect

See GetTargetRect and SetTargetRect



TargetWindow

See GetTargetWindow and SetTargetWindow



UncommittedPropertyValue

See GetUncommittedPropertyValue



UnspecifiedValueAppearance

See GetUnspecifiedValueAppearance and SetUnspecifiedValueAppearance



UnspecifiedValueText

See GetUnspecifiedValueText



VerticalSpacing

See GetVerticalSpacing and SetVerticalSpacing