Phoenix Logo

phoenix_title wx.propgrid.PGProperty

wx.propgrid.PGProperty is base class for all wx.propgrid.PropertyGrid properties.

In sections below we cover few related topics.

phoenix_title PropertyCategory

Not an actual property per se, but a header for a group of properties. Regardless inherits from wx.propgrid.PGProperty, and supports displaying ‘labels’ for columns other than the first one. Easiest way to set category’s label for second column is to call wx.propgrid.PGProperty.SetValue with string argument.

phoenix_title StringProperty

Simple string property. PG_STRING_PASSWORD attribute may be used to echo value as asterisks and use wx.TE_PASSWORD for wx.TextCtrl. PG_ATTR_AUTOCOMPLETE attribute may be used to enable auto-completion (use a list of strings value), and is also supported by any property that happens to use a TextCtrl-based editor.

phoenix_title IntProperty

Like wx.propgrid.StringProperty, but converts text to a signed long integer. wx.propgrid.IntProperty seamlessly supports 64-bit integers (ie. LongLong ). To safely convert variant to integer, use code like this:

# Thanks to the magic of Python nothing extra needs to be done here.

phoenix_title UIntProperty

Like wx.propgrid.IntProperty, but displays value as int. To set the prefix used globally, manipulate PG_UINT_PREFIX string attribute. To set the globally used base, manipulate PG_UINT_BASE int attribute. Regardless of current prefix, understands (hex) values starting with both “0x” and “$”. Like wx.propgrid.IntProperty, wx.propgrid.UIntProperty seamlessly supports 64-bit integers (ie. ULongLong ). Same Variant safety rules apply.

phoenix_title FloatProperty

Like wx.propgrid.StringProperty, but converts text to a double-precision floating point. Default float-to-text precision is 6 decimals, but this can be changed by modifying PG_FLOAT_PRECISION attribute. Note that when displaying the value, sign is omitted if the resulting textual representation is effectively zero (for example, -0.0001 with precision of 3 will become 0.0 instead of -0.0). This behaviour is unlike what C standard library does, but should result in better end-user experience in almost all cases.

phoenix_title BoolProperty

Represents a boolean value. wx.Choice is used as editor control, by the default. PG_BOOL_USE_CHECKBOX attribute can be set to True in order to use check box instead.

phoenix_title LongStringProperty

Like wx.propgrid.StringProperty, but has a button that triggers a small text editor dialog. Note that in long string values, tabs are represented by “\t” and line break by “\n”. To display custom dialog on button press, you can subclass wx.propgrid.LongStringProperty and implement OnButtonClick, like this:

def OnButtonClick(self, propGrid, value):
    dlgSize = wx.Size(... size of your dialog ...)
    dlgPos = propGrid.GetGoodEditorDialogPosition(self, dlgSize)

    # Create dialog dlg at dlgPos. Use value as initial string
    # value.
    with MyCustomDialog(None, title, pos=dlgPos, size=dlgSize) as dlg:
        if dlg.ShowModal() == wx.ID_OK:
            value = dlg.GetStringValue()
            return (True, value)
        return (False, value)

Also, if you wish not to have line breaks and tabs translated to escape sequences, then do following in constructor of your subclass:

self.SetFlag(wx.propgrid.PG_PROP_NO_ESCAPE)

phoenix_title DirProperty

Like wx.propgrid.LongStringProperty, but the button triggers dir selector instead. Supported properties (all with string value): PG_DIR_DIALOG_MESSAGE.

phoenix_title FileProperty

Like wx.propgrid.LongStringProperty, but the button triggers file selector instead. Default wildcard is “All files...” but this can be changed by setting PG_FILE_WILDCARD attribute (see wx.FileDialog for format details). Attribute PG_FILE_SHOW_FULL_PATH can be set to False in order to show only the filename, not the entire path.

phoenix_title EnumProperty

Represents a single selection from a list of choices - wx.adv.OwnerDrawnComboBox is used to edit the value.

phoenix_title FlagsProperty

Represents a bit set that fits in a long integer. wx.propgrid.BoolProperty sub- properties are created for editing individual bits. Textctrl is created to manually edit the flags as a text; a continuous sequence of spaces, commas and semicolons are considered as a flag id separator. Note: When changing “choices” (ie. flag labels) of wx.propgrid.FlagsProperty, you will need to use wx.propgrid.PGProperty.SetChoices - otherwise they will not get updated properly. wx.propgrid.FlagsProperty supports the same attributes as wx.propgrid.BoolProperty.

phoenix_title ArrayStringProperty

Allows editing of a list of strings in wx.TextCtrl and in a separate dialog. Supports “Delimiter” attribute, which defaults to comma (‘,’).

phoenix_title DateProperty

wx.DateTime property. Default editor is DatePickerCtrl, although TextCtrl should work as well. PG_DATE_FORMAT attribute can be used to change string wx.DateTime.Format uses (although default is recommended as it is locale-dependent), and PG_DATE_PICKER_STYLE allows changing window style given to DatePickerCtrl (default is DP_DEFAULT|wxDP_SHOWCENTURY). Using wx.adv.DP_ALLOWNONE will enable better unspecified value support.

phoenix_title EditEnumProperty

Represents a string that can be freely edited or selected from list of choices - custom combobox control is used to edit the value.

phoenix_title MultiChoiceProperty

Allows editing a multiple selection from a list of strings. This is property is pretty much built around concept of wx.MultiChoiceDialog. It uses list of strings value.

phoenix_title ImageFileProperty

Like wx.propgrid.FileProperty, but has thumbnail of the image in front of the filename and autogenerates wildcard from available image handlers.

phoenix_title ColourProperty

Useful alternate editor: Choice. Represents wx.Colour. wx.Button is used to trigger a colour picker dialog. There are various sub-classing opportunities with this class. See below in wx.propgrid.SystemColourProperty section for details. Setting “HasAlpha” attribute to True for this property allows user to edit the alpha colour component.

phoenix_title FontProperty

Represents wx.Font. Various sub-properties are used to edit individual subvalues.

phoenix_title SystemColourProperty

Represents wx.Colour and a system colour index. wx.Choice is used to edit the value. Drop-down list has color images. Note that value type is wx.propgrid.ColourPropertyValue instead of wx.Colour (which wx.propgrid.ColourProperty uses).

in wx.propgrid.SystemColourProperty, and its derived class wx.propgrid.ColourProperty, there are various sub-classing features. To set a basic list of colour names, call wx.propgrid.PGProperty.SetChoices .

|phoenix_title| CursorProperty

Represents a wx.Cursor. wx.Choice is used to edit the value. Drop-down list has cursor images under some (wxMSW) platforms.

phoenix_title Creating Custom Properties

New properties can be created by subclassing wx.propgrid.PGProperty or one of the provided property classes, and (re)implementing necessary member functions. Below, each virtual member function has ample documentation about its purpose and any odd details which to keep in mind. Here is a very simple ‘template’ code:

class MyProperty(wx.propgrid.PGProperty):
    # All arguments of this ctor should have a default value -
    # use wx.propgrid.PG_LABEL for label and name
    def __init__(self,
                 label = wx.propgrid.PG_LABEL,
                 name = wx.propgrid.PG_LABEL,
                 value = ""):
        wx.propgrid.PGProperty.__init__(label, name)
        self.value = value

    def DoGetEditorClass(self):
        # Determines editor used by property.
        # You can replace 'TextCtrl' below with any of these
        # builtin-in property editor identifiers: Choice, ComboBox,
        # TextCtrlAndButton, ChoiceAndButton, CheckBox, SpinCtrl,
        # DatePickerCtrl.
        return wx.PGEditor_TextCtrl

    def ValueToString(self, value, argFlags):
        # TODO: Convert given property value to a string and return it
        return ""

    def StringToValue(self, text, argFlags):
        # TODO: Adapt string to property value and return it
        value = do_something(text)
        return (True, value)

Since wx.propgrid.PGProperty derives from wx.Object, you can use standard DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS macros. From the above example they were omitted for sake of simplicity, and besides, they are only really needed if you need to use RTTI with your property class. You can change the ‘value type’ of a property by simply assigning different type of variant with SetValue. It is mandatory to implement VariantData class for all data types used as property values. You can use macros declared in wx.propgrid.PropertyGrid headers. For instance:

.. note::
wx.propgrid.StringProperty has a special trait: if it has value of “<composed>”, and also has child properties, then its displayed value becomes composition of child property values, similar as with wx.propgrid.FontProperty, for instance.

class_hierarchy Class Hierarchy

Inheritance diagram for class PGProperty:


method_summary Methods Summary

__init__ Default constructor.
AdaptListToValue Adapts list variant into proper value using consecutive ChildChanged calls.
AddChild Adds a private child property.
AddChoice Append a new choice to property’s list of choices.
AddPrivateChild Adds a private child property.
AppendChild Use this member function to add independent (ie.
AreAllChildrenSpecified Determines, recursively, if all children are not unspecified.
AreChildrenComponents Returns True if children of this property are component values (for instance, points size, face name, and is_underlined are component values of a font).
ChangeFlag Sets or clears given property flag.
ChildChanged Called after value of a child property has been altered.
DeleteChildren Deletes children of the property.
DeleteChoice Removes entry from property’s wx.propgrid.PGChoices and editor control (if it is active).
DoGetAttribute Returns value of an attribute.
DoGetEditorClass Returns pointer to an instance of used editor.
DoGetValidator Returns pointer to the wx.Validator that should be used with the editor of this property (None for no validator).
DoGetValue Override this to return something else than m_value as the value.
DoSetAttribute Reimplement this member function to add special handling for attributes of this property.
Enable Enables or disables the property.
EnableCommonValue Call to enable or disable usage of common value (integer value that can be selected for properties instead of their normal values) for this property.
GenerateComposedValue Composes text from values of child properties.
GetAttribute Returns property attribute value, null variant if not found.
GetAttributeAsDouble Returns named attribute, as double, if found.
GetAttributeAsLong Returns named attribute, as long, if found.
GetAttributes Return atributes storage map.
GetAttributesAsList Returns attributes as list Variant .
GetBaseName Returns property’s base name (ie.
GetCell Returns wx.propgrid.PGCell of given column, creating one if necessary.
GetCellRenderer Returns used wx.propgrid.PGCellRenderer instance for given property column (label=0, value=1).
GetChildCount Returns number of child properties.
GetChildrenHeight Returns height of children, recursively, and by taking expanded/collapsed status into account.
GetChoiceSelection Returns which choice is currently selected.
GetChoices Returns read-only reference to property’s list of choices.
GetClientData Returns client data (void) of a property.
GetClientObject Sets managed client object of a property.
GetColumnEditor Returns editor used for given column.
GetDefaultValue Returns property’s default value.
GetDisplayedString Returns property’s displayed text.
GetEditorClass Returns wx.propgrid.PGEditor that will be used and created when property becomes selected.
GetEditorDialog Returns instance of a new wx.propgrid.PGEditorDialogAdapter instance, which is used when user presses the (optional) button next to the editor control;.
GetFlags Returns property flags.
GetGrid Returns property grid where property lies.
GetGridIfDisplayed Returns owner wx.propgrid.PropertyGrid, but only if one is currently on a page displaying this property.
GetHelpString Returns property’s help or description text.
GetIndexInParent Returns position in parent’s array.
GetLabel Returns property’s label.
GetLastVisibleSubItem Returns last visible child property, recursively.
GetMainParent Returns highest level non-category, non-root parent.
GetMaxLength Returns maximum allowed length of property’s text value.
GetName Returns property’s name with all (non-category, non-root) parents.
GetOrCreateCell Returns wx.propgrid.PGCell of given column, creating one if necessary.
GetParent Return parent of property.
GetPropertyByName Returns (direct) child property with given name (or None if not found).
GetValidator Gets assignable version of property’s validator.
GetValue Returns property’s value.
GetValueAsString Returns text representation of property’s value.
GetValueImage Returns bitmap that appears next to value text.
GetValueString Synonymous to GetValueAsString .
GetValueType Returns value type used by this property.
GetY Returns coordinate to the top y of the property.
HasFlag Returns non-zero if property has given flag set.
HasVisibleChildren Returns True if property has even one visible child.
Hide Hides or reveals the property.
Index Returns index of given child property.
InsertChild Use this member function to add independent (ie.
InsertChoice Inserts a new choice to property’s list of choices.
IntToValue Converts integer (possibly a choice selection) into Variant value appropriate for this property.
IsCategory Returns True if this property is actually a wx.propgrid.PropertyCategory.
IsEnabled Returns True if property is enabled.
IsExpanded Returns True if property has visible children.
IsRoot Returns True if this property is actually a RootProperty.
IsSomeParent Returns True if candidateParent is some parent of this property.
IsSubProperty Returns True if this is a sub-property.
IsTextEditable Returns True if property has editable wx.TextCtrl when selected.
IsValueUnspecified Returns True if property’s value is considered unspecified.
IsVisible Returns True if all parents expanded.
Item Returns child property at index i.
OnCustomPaint Override to paint an image in front of the property value text or drop-down list item (but only if wx.propgrid.PGProperty.OnMeasureImage is overridden as well).
OnEvent Events received by editor widgets are processed here.
OnMeasureImage Returns size of the custom painted image in front of property.
OnSetValue This virtual function is called after m_value has been set.
OnValidationFailure Called whenever validation has failed with given pending value.
RefreshChildren Refresh values of child properties.
RefreshEditor If property’s editor is active, then update it’s value.
SetAttribute Sets an attribute for this property.
SetAttributes Set the property’s attributes from a Python dictionary.
SetAutoUnspecified Set if user can change the property’s value to unspecified by modifying the value of the editor control (usually by clearing it).
SetBackgroundColour Sets property’s background colour.
SetCell Sets cell information for given column.
SetChoiceSelection Sets selected choice and changes property value.
SetChoices Sets new set of choices for the property.
SetClientData Sets client data (void) of a property.
SetClientObject Returns client object of a property.
SetDefaultValue Set default value of a property.
SetEditor Sets editor for a property.
SetFlagRecursively Sets or clears given property flag, recursively.
SetHelpString Sets property’s help string, which is shown, for example, in wx.propgrid.PropertyGridManager‘s description text box.
SetLabel Sets property’s label.
SetMaxLength Set max length of text in text editor.
SetModifiedStatus Sets property’s “is it modified?” flag.
SetName Sets new (base) name for property.
SetParentalType Changes what sort of parent this property is for its children.
SetTextColour Sets property’s text colour.
SetValidator Sets wx.Validator for a property.
SetValue Call this to set value of the property.
SetValueFromInt Converts integer to a value, and if successful, calls SetValue on it.
SetValueFromString Converts string to a value, and if successful, calls SetValue on it.
SetValueImage Set wx.Bitmap in front of the value.
SetValueInEvent Call this function in OnEvent , OnButtonClick() etc.
SetValuePlain Helper for language bindings.
SetValueToUnspecified Sets property’s value to unspecified (ie.
SetWasModified Call with False in OnSetValue to cancel value changes after all (ie.
StringToValue Converts text into Variant value appropriate for this property.
UpdateParentValues Updates composed values of parent non-category properties, recursively.
UsesAutoUnspecified Returns True if containing grid uses wx.propgrid.PG_EX_AUTO_UNSPECIFIED_VALUES.
ValidateValue Implement this function in derived class to check the value.
ValueToString Converts property value into a text representation.

api Class API



class wx.propgrid.PGProperty(Object)

Possible constructors:

PGProperty()

PGProperty(label, name)

PGProperty is base class for all PropertyGrid properties.


Methods



__init__(self, *args, **kw)

overload Overloaded Implementations:



__init__ (self)

Default constructor.



__init__ (self, label, name)

Constructor.

Non-abstract property classes should have constructor of this style:

class MyProperty(wx.propgrid.PGProperty):
    def __init__(self, label, name, value):
        wx.propgrid.PGProperty.__init__(self, label, name)
        self.SetValue(value)
Parameters:
  • label (string) –
  • name (string) –





AdaptListToValue(self, list, value)

Adapts list variant into proper value using consecutive ChildChanged calls.

Parameters:
  • list (PGVariant) –
  • value (PGVariant) –


AddChild(self, prop)

Adds a private child property.

Parameters:prop (wx.propgrid.PGProperty) –

Deprecated since version 4.0.0: Use AddPrivateChild instead.

See also

AddPrivateChild



AddChoice(self, label, value=PG_INVALID_VALUE)

Append a new choice to property’s list of choices.

Parameters:
  • label (string) – Label for added choice.
  • value (int) – Value for new choice. Do not specify if you wish this to equal choice index.
Return type:

int

Returns:

Index to added choice.



AddPrivateChild(self, prop)

Adds a private child property.

If you use this instead of wx.propgrid.PropertyGridInterface.Insert or wx.propgrid.PropertyGridInterface.AppendIn , then property’s parental type will automatically be set up to wx.propgrid.PG_PROP_AGGREGATE. In other words, all properties of this property will become private.

Parameters:prop (wx.propgrid.PGProperty) –


AppendChild(self, childProperty)

Use this member function to add independent (ie.

regular) children to a property.

Parameters:childProperty (wx.propgrid.PGProperty) –
Return type: wx.propgrid.PGProperty
Returns:Appended childProperty.

Note

wx.propgrid.PropertyGrid is not automatically refreshed by this function.



AreAllChildrenSpecified(self, pendingList=None)

Determines, recursively, if all children are not unspecified.

Parameters:pendingList (PGVariant) – Assumes members in this Variant list as pending replacement values.
Return type:bool


AreChildrenComponents(self)

Returns True if children of this property are component values (for instance, points size, face name, and is_underlined are component values of a font).

Return type:bool


ChangeFlag(self, flag, set)

Sets or clears given property flag.

Mainly for internal use.

Parameters:

Note

Setting a property flag never has any side-effect, and is intended almost exclusively for internal use. So, for example, if you want to disable a property, call Enable(false) instead of setting wx.propgrid.PG_PROP_DISABLED flag.

See also

HasFlag , GetFlags



ChildChanged(self, thisValue, childIndex, childValue)

Called after value of a child property has been altered.

Must return new value of the whole property (after any alterations warranted by child’s new value).

Note that this function is usually called at the time that value of this property, or given child property, is still pending for change, and as such, result of GetValue or m_value should not be relied on.

Sample pseudo-code implementation:

# TBW
Parameters:
  • thisValue (PGVariant) – Value of this property. Changed value should be returned (in previous versions of wx.propgrid.PropertyGrid it was only necessary to write value back to this argument).
  • childIndex (int) – Index of child changed (you can use Item(childIndex) to get child property).
  • childValue (PGVariant) – (Pending) value of the child property.
Return type:

PGVariant

Returns:

Modified value of the whole property.



DeleteChildren(self)

Deletes children of the property.



DeleteChoice(self, index)

Removes entry from property’s wx.propgrid.PGChoices and editor control (if it is active).

If selected item is deleted, then the value is set to unspecified.

Parameters:index (int) –


DoGetAttribute(self, name)

Returns value of an attribute.

Override if custom handling of attributes is needed.

Default implementation simply return None variant.

Parameters:name (string) –
Return type:PGVariant


DoGetEditorClass(self)

Returns pointer to an instance of used editor.

Return type: wx.propgrid.PGEditor


DoGetValidator(self)

Returns pointer to the wx.Validator that should be used with the editor of this property (None for no validator).

Setting validator explicitly via SetPropertyValidator will override this.

In most situations, code like this should work well (macros are used to maintain one actual validator instance, so on the second call the function exits within the first macro):

class MyPropertyClass(wx.propgrid.PGProperty):
    ...
    def DoGetValidator(self):
        validator = MyValidator(...)

        ... prepare validator...

        return validator
Return type:Validator

Note

You can get common filename validator by returning wx.propgrid.FileProperty.GetClassValidator . wx.propgrid.DirProperty, for example, uses it.



DoGetValue(self)

Override this to return something else than m_value as the value.

Return type:PGVariant


DoSetAttribute(self, name, value)

Reimplement this member function to add special handling for attributes of this property.

Parameters:
  • name (string) –
  • value (PGVariant) –
Return type:

bool

Returns:

Return False to have the attribute automatically stored in m_attributes. Default implementation simply does that and nothing else.

Note

To actually set property attribute values from the application, use wx.propgrid.PGProperty.SetAttribute instead.



Enable(self, enable=True)

Enables or disables the property.

Disabled property usually appears as having grey text.

Parameters:enable (bool) – If False, property is disabled instead.


EnableCommonValue(self, enable=True)

Call to enable or disable usage of common value (integer value that can be selected for properties instead of their normal values) for this property.

Common values are disabled by the default for all properties.

Parameters:enable (bool) –


GenerateComposedValue(self)

Composes text from values of child properties.

Return type:string


GetAttribute(self, *args, **kw)

overload Overloaded Implementations:



GetAttribute (self, name)

Returns property attribute value, null variant if not found.

Parameters:name (string) –
Return type:PGVariant



GetAttribute (self, name, defVal)

Returns named attribute, as string, if found.

Otherwise defVal is returned.

Parameters:
  • name (string) –
  • defVal (string) –
Return type:

string





GetAttributeAsDouble(self, name, defVal)

Returns named attribute, as double, if found.

Otherwise defVal is returned.

Parameters:
  • name (string) –
  • defVal (float) –
Return type:

float



GetAttributeAsLong(self, name, defVal)

Returns named attribute, as long, if found.

Otherwise defVal is returned.

Parameters:
  • name (string) –
  • defVal (long) –
Return type:

long



GetAttributes(self)

Return atributes storage map.

Return type:PyObject


GetAttributesAsList(self)

Returns attributes as list Variant .

Return type:PGVariant


GetBaseName(self)

Returns property’s base name (ie.

parent’s name is not added in any case)

Return type:string


GetCell(self, column)

Returns wx.propgrid.PGCell of given column, creating one if necessary.

Parameters:column (int) –
Return type: wx.propgrid.PGCell


GetCellRenderer(self, column)

Returns used wx.propgrid.PGCellRenderer instance for given property column (label=0, value=1).

Default implementation returns editor’s renderer for all columns.

Parameters:column (int) –
Return type: wx.propgrid.PGCellRenderer


GetChildCount(self)

Returns number of child properties.

Return type:int


GetChildrenHeight(self, lh, iMax=-1)

Returns height of children, recursively, and by taking expanded/collapsed status into account.

Parameters:
  • lh (int) – Line height. Pass result of GetGrid .GetRowHeight() here.
  • iMax (int) – Only used (internally) when finding property y-positions.
Return type:

int



GetChoiceSelection(self)

Returns which choice is currently selected.

Only applies to properties which have choices.

Needs to reimplemented in derived class if property value does not map directly to a choice. Integer as index, bool, and string usually do.

Return type:int


GetChoices(self)

Returns read-only reference to property’s list of choices.

Return type: wx.propgrid.PGChoices


GetClientData(self)

Returns client data (void) of a property.



GetClientObject(self)

Sets managed client object of a property.

Return type:ClientData


GetColumnEditor(self, column)

Returns editor used for given column.

None for no editor.

Parameters:column (int) –
Return type: wx.propgrid.PGEditor


GetDefaultValue(self)

Returns property’s default value.

If property’s value type is not a built-in one, and “DefaultValue” attribute is not defined, then this function usually returns Null variant.

Return type:PGVariant


GetDisplayedString(self)

Returns property’s displayed text.

Return type:string


GetEditorClass(self)

Returns wx.propgrid.PGEditor that will be used and created when property becomes selected.

Returns more accurate value than DoGetEditorClass .

Return type: wx.propgrid.PGEditor


GetEditorDialog(self)

Returns instance of a new wx.propgrid.PGEditorDialogAdapter instance, which is used when user presses the (optional) button next to the editor control;.

Default implementation returns None (ie. no action is generated when button is pressed).

Return type: wx.propgrid.PGEditorDialogAdapter


GetFlags(self)

Returns property flags.

Return type:FlagType


GetGrid(self)

Returns property grid where property lies.

Return type: wx.propgrid.PropertyGrid


GetGridIfDisplayed(self)

Returns owner wx.propgrid.PropertyGrid, but only if one is currently on a page displaying this property.

Return type: wx.propgrid.PropertyGrid


GetHelpString(self)

Returns property’s help or description text.

Return type:string

See also

SetHelpString



GetIndexInParent(self)

Returns position in parent’s array.

Return type:int


GetLabel(self)

Returns property’s label.

Return type:string


GetLastVisibleSubItem(self)

Returns last visible child property, recursively.

Return type: wx.propgrid.PGProperty


GetMainParent(self)

Returns highest level non-category, non-root parent.

Useful when you have nested properties with children.

Return type: wx.propgrid.PGProperty

Note

If immediate parent is root or category, this will return the property itself.



GetMaxLength(self)

Returns maximum allowed length of property’s text value.

Return type:int


GetName(self)

Returns property’s name with all (non-category, non-root) parents.

Return type:string


GetOrCreateCell(self, column)

Returns wx.propgrid.PGCell of given column, creating one if necessary.

Parameters:column (int) –
Return type: wx.propgrid.PGCell


GetParent(self)

Return parent of property.

Return type: wx.propgrid.PGProperty


GetPropertyByName(self, name)

Returns (direct) child property with given name (or None if not found).

Parameters:name (string) –
Return type: wx.propgrid.PGProperty


GetValidator(self)

Gets assignable version of property’s validator.

Return type:Validator


GetValue(self)

Returns property’s value.

Return type:PGVariant


GetValueAsString(self, argFlags=0)

Returns text representation of property’s value.

Parameters:argFlags (int) – If 0 (default value), then displayed string is returned. If wx.propgrid.PG_FULL_VALUE is set, returns complete, storable string value instead of displayable. If wx.propgrid.PG_EDITABLE_VALUE is set, returns string value that must be editable in textctrl. If wx.propgrid.PG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to display as a part of string property’s composite text representation.
Return type:string

Note

In older versions, this function used to be overridden to convert property’s value into a string representation. This function is now handled by ValueToString , and overriding this function now will result in run-time assertion failure.



GetValueImage(self)

Returns bitmap that appears next to value text.

Only returns not None bitmap if one was set with SetValueImage .

Return type:Bitmap


GetValueString(self, argFlags=0)

Synonymous to GetValueAsString .

Parameters:argFlags (int) –
Return type:string

Deprecated since version 4.0.0: Use GetValueAsString instead.

See also

GetValueAsString



GetValueType(self)

Returns value type used by this property.

Return type:string


GetY(self)

Returns coordinate to the top y of the property.

Note that the position of scrollbars is not taken into account.

Return type:int


HasFlag(self, flag)

Returns non-zero if property has given flag set.

Parameters:flag (PGPropertyFlags) –
Return type:FlagType

See also

propgrid_propflags



HasVisibleChildren(self)

Returns True if property has even one visible child.

Return type:bool


Hide(self, hide, flags=PG_RECURSE)

Hides or reveals the property.

Parameters:
  • hide (bool) – True for hide, False for reveal.
  • flags (int) – By default changes are applied recursively. Set this parameter wx.propgrid.PG_DONT_RECURSE to prevent this.
Return type:

bool



Index(self, p)

Returns index of given child property.

wx.NOT_FOUND if given property is not child of this.

Parameters:p (wx.propgrid.PGProperty) –
Return type:int


InsertChild(self, index, childProperty)

Use this member function to add independent (ie.

regular) children to a property.

Parameters:
Return type:

wx.propgrid.PGProperty

Returns:

Inserted childProperty.

Note

wx.propgrid.PropertyGrid is not automatically refreshed by this function.



InsertChoice(self, label, index, value=PG_INVALID_VALUE)

Inserts a new choice to property’s list of choices.

Parameters:
  • label (string) – Text for new choice
  • index (int) – Insertion position. Use wx.NOT_FOUND to append.
  • value (int) – Value for new choice. Do not specify if you wish this to equal choice index.
Return type:

int



IntToValue(self, number, argFlags=0)

Converts integer (possibly a choice selection) into Variant value appropriate for this property.

Parameters:
  • number (int) – Integer to be translated into variant.
  • argFlags (int) – If wx.propgrid.PG_FULL_VALUE is set, returns complete, storable value instead of displayable one.
Return type:

tuple

Returns:

( bool, variant )

Note

  • If property is not supposed to use choice or spinctrl or other editor with int-based value, it is not necessary to implement this method.
  • Default implementation simply assign given int to m_value.
  • If property uses choice control, and displays a dialog on some choice items, then it is preferred to display that dialog in IntToValue instead of OnEvent.
  • You might want to take into account that m_value is Mull variant if property value is unspecified (which is usually only case if you explicitly enabled that sort behaviour).


IsCategory(self)

Returns True if this property is actually a wx.propgrid.PropertyCategory.

Return type:bool


IsEnabled(self)

Returns True if property is enabled.

Return type:bool


IsExpanded(self)

Returns True if property has visible children.

Return type:bool


IsRoot(self)

Returns True if this property is actually a RootProperty.

Return type:bool


IsSomeParent(self, candidateParent)

Returns True if candidateParent is some parent of this property.

Parameters:candidateParent (wx.propgrid.PGProperty) –
Return type:bool


IsSubProperty(self)

Returns True if this is a sub-property.

Return type:bool


IsTextEditable(self)

Returns True if property has editable wx.TextCtrl when selected.

Return type:bool

Note

Although disabled properties do not displayed editor, they still return True here as being disabled is considered a temporary condition (unlike being read-only or having limited editing enabled).



IsValueUnspecified(self)

Returns True if property’s value is considered unspecified.

This usually means that value is Null variant.

Return type:bool


IsVisible(self)

Returns True if all parents expanded.

Return type:bool


Item(self, i)

Returns child property at index i.

Parameters:i (int) –
Return type: wx.propgrid.PGProperty


OnCustomPaint(self, dc, rect, paintdata)

Override to paint an image in front of the property value text or drop-down list item (but only if wx.propgrid.PGProperty.OnMeasureImage is overridden as well).

If property’s OnMeasureImage returns size that has height != 0 but less than row height ( < 0 has special meanings), wx.propgrid.PropertyGrid calls this method to draw a custom image in a limited area in front of the editor control or value text/graphics, and if control has drop-down list, then the image is drawn there as well (even in the case OnMeasureImage returned higher height than row height).

NOTE: Following applies when OnMeasureImage returns a “flexible” height ( using PG_FLEXIBLE_SIZE(W,H) macro), which implies variable height items: If rect.x is < 0, then this is a measure item call, which means that dc is invalid and only thing that should be done is to set paintdata.m_drawnHeight to the height of the image of item at index paintdata.m_choiceItem. This call may be done even as often as once every drop-down popup show.

Parameters:

Note

  • You can actually exceed rect width, but if you do so then paintdata.m_drawnWidth must be set to the full width drawn in pixels.
  • Due to technical reasons, rect’s height will be default even if custom height was reported during measure call.
  • Brush is guaranteed to be default background colour. It has been already used to clear the background of area being painted. It can be modified.
  • Pen is guaranteed to be 1-wide ‘black’ (or whatever is the proper colour) pen for drawing framing rectangle. It can be changed as well.

See also

ValueToString



OnEvent(self, propgrid, wnd_primary, event)

Events received by editor widgets are processed here.

Note that editor class usually processes most events. Some, such as button press events of TextCtrlAndButton class, can be handled here. Also, if custom handling for regular events is desired, then that can also be done (for example, wx.propgrid.SystemColourProperty custom handles wxEVT_CHOICE to display colour picker dialog when ‘custom’ selection is made).

If the event causes value to be changed, SetValueInEvent should be called to set the new value.

The parameter event is the associated wx.Event.

Parameters:

return True if any changes in value should be reported.

Return type:bool

Note

  • If property uses choice control, and displays a dialog on some choice items, then it is preferred to display that dialog in IntToValue instead of OnEvent.


OnMeasureImage(self, item=-1)

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

This method must be overridden to return non-default value if OnCustomPaint is to be called.

Parameters:item (int) – Normally -1, but can be an index to the property’s list of items.
Return type:Size

Note

  • Default behaviour is to return wx.Size, which means no image.
  • Default image width or height is indicated with dimension -1.
  • You can also return wx.propgrid.PG_DEFAULT_IMAGE_SIZE which equals :ref:`wx.Size`(-1, -1).


OnSetValue(self)

This virtual function is called after m_value has been set.

Note

  • If m_value was set to Null variant (ie. unspecified value), OnSetValue will not be called.
  • m_value may be of any variant type. Typically properties internally support only one variant type, and as such OnSetValue provides a good opportunity to convert supported values into internal type.
  • Default implementation does nothing.


OnValidationFailure(self, pendingValue)

Called whenever validation has failed with given pending value.

Parameters:pendingValue (PGVariant) –

Note

If you implement this in your custom property class, please remember to call the baser implementation as well, since they may use it to revert property into pre-change state.



RefreshChildren(self)

Refresh values of child properties.

Automatically called after value is set.



RefreshEditor(self)

If property’s editor is active, then update it’s value.



SetAttribute(self, name, value)

Sets an attribute for this property.

Parameters:
  • name (string) – Text identifier of attribute. See PropertyGrid Property Attribute Identifiers.
  • value (PGVariant) – Value of attribute.

Note

Setting attribute’s value to Null variant will simply remove it from property’s set of attributes.



SetAttributes(self, attributes)

Set the property’s attributes from a Python dictionary.



SetAutoUnspecified(self, enable=True)

Set if user can change the property’s value to unspecified by modifying the value of the editor control (usually by clearing it).

Currently, this can work with following properties: wx.propgrid.IntProperty, wx.propgrid.UIntProperty, wx.propgrid.FloatProperty, wx.propgrid.EditEnumProperty.

Parameters:enable (bool) – Whether to enable or disable this behaviour (it is disabled by default).


SetBackgroundColour(self, colour, flags=PG_RECURSE)

Sets property’s background colour.

Parameters:
  • colour (wx.Colour) – Background colour to use.
  • flags (int) – Default is wx.propgrid.PG_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.


SetCell(self, column, cell)

Sets cell information for given column.

Parameters:


SetChoiceSelection(self, newValue)

Sets selected choice and changes property value.

Tries to retain value type, although currently if it is not string, then it is forced to integer.

Parameters:newValue (int) –


SetChoices(self, choices)

Sets new set of choices for the property.

Parameters:choices (wx.propgrid.PGChoices) –
Return type:bool

Note

This operation deselects the property and clears its value.



SetClientData(self, clientData)

Sets client data (void) of a property.

Parameters:clientData

Note

This untyped client data has to be deleted manually.



SetClientObject(self, clientObject)

Returns client object of a property.

Parameters:clientObject (ClientData) –


SetDefaultValue(self, value)

Set default value of a property.

Synonymous to

theProperty.SetAttribute("DefaultValue", value)
Parameters:value (PGVariant) –


SetEditor(self, *args, **kw)

overload Overloaded Implementations:



SetEditor (self, editor)

Sets editor for a property.

Parameters:editor (wx.propgrid.PGEditor) – For builtin editors, use PGEditor_X, where X is builtin editor’s name (TextCtrl, Choice, etc. see wx.propgrid.PGEditor documentation for full list).

wx.propgrid.PropertyGrid.RegisterEditorClass .



SetEditor (self, editorName)

Sets editor for a property, by editor name.

Parameters:editorName (string) –





SetFlagRecursively(self, flag, set)

Sets or clears given property flag, recursively.

This function is primarily intended for internal use.

Parameters:

See also

ChangeFlag



SetHelpString(self, helpString)

Sets property’s help string, which is shown, for example, in wx.propgrid.PropertyGridManager‘s description text box.

Parameters:helpString (string) –


SetLabel(self, label)

Sets property’s label.

Parameters:label (string) –

Note

Properties under same parent may have same labels. However, property names must still remain unique.



SetMaxLength(self, maxLen)

Set max length of text in text editor.

Parameters:maxLen (int) –
Return type:bool


SetModifiedStatus(self, modified)

Sets property’s “is it modified?” flag.

Affects children recursively.

Parameters:modified (bool) –


SetName(self, newName)

Sets new (base) name for property.

Parameters:newName (string) –


SetParentalType(self, flag)

Changes what sort of parent this property is for its children.

Parameters:flag (int) – Use one of the following values: wx.propgrid.PG_PROP_MISC_PARENT (for generic parents), wx.propgrid.PG_PROP_CATEGORY (for categories), or wx.propgrid.PG_PROP_AGGREGATE (for derived property classes with private children).

Note

You generally do not need to call this function.



SetTextColour(self, colour, flags=PG_RECURSE)

Sets property’s text colour.

Parameters:
  • colour (wx.Colour) – Text colour to use.
  • flags (int) – Default is wx.propgrid.PG_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.


SetValidator(self, validator)

Sets wx.Validator for a property.

Parameters:validator (wx.Validator) –


SetValue(self, value, pList=None, flags=PG_SETVAL_REFRESH_EDITOR)

Call this to set value of the property.

Unlike methods in wx.propgrid.PropertyGrid, this does not automatically update the display.

If you need to change property value in event, based on user input, use SetValueInEvent instead.

Parameters:
  • value (PGVariant) – The value to set.
  • pList (PGVariant) – Pointer to list variant that contains child values. Used to indicate which children should be marked as modified. Usually you just use None.
  • flags (int) – wx.propgrid.PG_SETVAL_REFRESH_EDITOR is set by default, to refresh editor and redraw properties.

Note

Use wx.propgrid.PropertyGrid.ChangePropertyValue instead if you need to run through validation process and send property change event.



SetValueFromInt(self, value, flags=0)

Converts integer to a value, and if successful, calls SetValue on it.

Default behaviour is to do nothing.

Parameters:
  • value (long) – Int to get the value from.
  • flags (int) – If has wx.propgrid.PG_FULL_VALUE, then the value given is a actual value and not an index.
Return type:

bool

Returns:

True if value was changed.



SetValueFromString(self, text, flags=0)

Converts string to a value, and if successful, calls SetValue on it.

Default behaviour is to do nothing.

Parameters:
  • text (string) – String to get the value from.
  • flags (int) –
Return type:

bool

Returns:

True if value was changed.

Todo

docme



SetValueImage(self, bmp)

Set wx.Bitmap in front of the value.

This bitmap may be ignored by custom cell renderers.

Parameters:bmp (wx.Bitmap) –


SetValueInEvent(self, value)

Call this function in OnEvent , OnButtonClick() etc.

to change the property value based on user input.

Parameters:value (PGVariant) –

Note

This method is since it doesn’t actually modify value, but posts given variant as pending value, stored in wx.propgrid.PropertyGrid.



SetValuePlain(self, value)

Helper for language bindings.

Parameters:value (PGVariant) –


SetValueToUnspecified(self)

Sets property’s value to unspecified (ie.

Null variant).



SetWasModified(self, set=True)

Call with False in OnSetValue to cancel value changes after all (ie.

cancel True returned by StringToValue or IntToValue ).

Parameters:set (bool) –


StringToValue(self, text, argFlags=0)

Converts text into Variant value appropriate for this property.

Parameters:
  • text (string) – Text to be translated into variant.
  • argFlags (int) – If wx.propgrid.PG_FULL_VALUE is set, returns complete, storable value instead of displayable one (they may be different). If wx.propgrid.PG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of composite property string value (as generated by ValueToString called with this same flag).
Return type:

tuple

You might want to take into account that m_value is Null variant if property value is unspecified (which is usually only case if you explicitly enabled that sort behaviour).

Returns:( bool, variant )

Note

Default implementation converts semicolon delimited tokens into child values. Only works for properties with children.



UpdateParentValues(self)

Updates composed values of parent non-category properties, recursively.

Returns topmost property updated.

Return type: wx.propgrid.PGProperty


UsesAutoUnspecified(self)

Returns True if containing grid uses wx.propgrid.PG_EX_AUTO_UNSPECIFIED_VALUES.

Return type:bool


ValidateValue(self, value, validationInfo)

Implement this function in derived class to check the value.

Return True if it is ok. Returning False prevents property change events from occurring.

Parameters:
Return type:

bool

Note

  • Default implementation always returns True.


ValueToString(self, value, argFlags=0)

Converts property value into a text representation.

Parameters:
  • value (PGVariant) – Value to be converted.
  • argFlags (int) – If 0 (default value), then displayed string is returned. If wx.propgrid.PG_FULL_VALUE is set, returns complete, storable string value instead of displayable. If wx.propgrid.PG_EDITABLE_VALUE is set, returns string value that must be editable in textctrl. If wx.propgrid.PG_COMPOSITE_FRAGMENT is set, returns text that is appropriate to display as a part of string property’s composite text representation.
Return type:

string

Note

Default implementation calls GenerateComposedValue .


Properties



Attributes

See GetAttributes and SetAttributes



AttributesAsList

See GetAttributesAsList



BaseName

See GetBaseName



ChildCount

See GetChildCount



ChoiceSelection

See GetChoiceSelection and SetChoiceSelection



Choices

See GetChoices and SetChoices



ClientData

See GetClientData and SetClientData



ClientObject

See GetClientObject and SetClientObject



DefaultValue

See GetDefaultValue and SetDefaultValue



DisplayedString

See GetDisplayedString



EditorClass

See GetEditorClass



EditorDialog

See GetEditorDialog



Flags

See GetFlags



Grid

See GetGrid



GridIfDisplayed

See GetGridIfDisplayed



HelpString

See GetHelpString and SetHelpString



IndexInParent

See GetIndexInParent



Label

See GetLabel and SetLabel



LastVisibleSubItem

See GetLastVisibleSubItem



MainParent

See GetMainParent



MaxLength

See GetMaxLength and SetMaxLength



Name

See GetName and SetName



Parent

See GetParent



Validator

See GetValidator and SetValidator



Value

See GetValue and SetValue



ValueAsString

See GetValueAsString



ValueImage

See GetValueImage and SetValueImage



ValueString

See GetValueString



ValueType

See GetValueType



Y

See GetY



m_clientData

A public C++ attribute of type ````.