wx.propgrid.PGProperty is base class for all wx.propgrid.PropertyGrid properties and as such it is not intended to be instantiated directly.
In sections below we cover few related topics.
Here is a list and short description of supplied fully-functional property classes. They are located in either props.h or advprops.h .
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.
Simple string property. Supported special attributes:
PG_STRING_PASSWORD
: Set to True
in order to echo value as asterisks and to use TE_PASSWORD
on the editor ( wx.TextCtrl).
PG_ATTR_AUTOCOMPLETE
: Set to True
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.
See also
PropertyGrid Property Attribute Identifiers
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.
It derives from wx.propgrid.NumericProperty and displays value as a signed long integer. wx.propgrid.IntProperty seamlessly supports 64-bit integers (i.e. LongLong ) on overflow. To safely convert variant to integer, use code like this:
# Thanks to the magic of Python nothing extra needs to be done here.
Getting 64-bit value:
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)
Setting 64-bit value:
self.SetFlag(wx.propgrid.PG_PROP_NO_ESCAPE)
Supported special attributes:
PG_ATTR_MIN
, PG_ATTR_MAX
to specify acceptable value range.
PG_ATTR_SPINCTRL_STEP
, PG_ATTR_SPINCTRL_WRAP
, PG_ATTR_SPINCTRL_MOTION
: Sets SpinCtrl editor parameters.
See also
PropertyGrid Property Attribute Identifiers
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 “$” (apart from edit mode). Like wx.propgrid.IntProperty, wx.propgrid.UIntProperty seamlessly supports 64-bit integers (i.e. ULongLong ). Same Variant safety rules apply. Supported special attributes:
PG_ATTR_MIN
, PG_ATTR_MAX
: Specifies acceptable value range.
PG_UINT_BASE
: Defines base. Valid constants are PG_BASE_OCT
, PG_BASE_DEC
, PG_BASE_HEX
and PG_BASE_HEXL
(lowercase characters). Arbitrary bases are not supported.
PG_UINT_PREFIX
: Defines displayed prefix. Possible values are PG_PREFIX_NONE
, wx.propgrid.PG_PREFIX_0x
and PG_PREFIX_DOLLAR_SIGN
. Only PG_PREFIX_NONE
works with decimal and octal numbers.
PG_ATTR_SPINCTRL_STEP
, PG_ATTR_SPINCTRL_WRAP
, PG_ATTR_SPINCTRL_MOTION
: Sets SpinCtrl editor parameters.
See also
PropertyGrid Property Attribute Identifiers
Note
For example how to use seamless 64-bit integer support, see wx.propgrid.IntProperty documentation (just use ULongLong instead of LongLong ).
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. Supported special attributes:
PG_ATTR_MIN
, PG_ATTR_MAX
: Specifies acceptable value range.
PG_FLOAT_PRECISION
: Sets the (max) precision used when floating point value is rendered as text. The default -1 means shortest floating-point 6-digit representation.
PG_ATTR_SPINCTRL_STEP
, PG_ATTR_SPINCTRL_WRAP
, PG_ATTR_SPINCTRL_MOTION
: Sets SpinCtrl editor parameters.
See also
PropertyGrid Property Attribute Identifiers
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. Supported special attributes:
PG_BOOL_USE_CHECKBOX
: If set to True
uses check box editor instead of combo box.
PG_BOOL_USE_DOUBLE_CLICK_CYCLING
: If set to True
cycles combo box instead showing the list.
See also
PropertyGrid Property Attribute Identifiers
Like wx.propgrid.StringProperty, but has a button that triggers a small text editor dialog. Note that in long string values, some control characters are escaped: tab is represented by “\t”, line break by “\n”, carriage return by “\r” and backslash character by “\”. If another character is preceded by backslash, the backslash is skipped. Note also that depending on the system (port), some sequences of special characters, like e.g. “\r\n”, can be interpreted and presented in a different way in the editor and therefore such sequences may not be the same before and after the edition. To display a custom dialog on button press, you can subclass wx.propgrid.LongStringProperty and override DisplayEditorDialog, like this:
Also, if you wish not to have line breaks and tabs translated to escape sequences, then do following in constructor of your subclass:
Supported special attributes:
PG_DIALOG_TITLE
: Sets a specific title for the text editor dialog.
Like wx.propgrid.LongStringProperty, but the button triggers dir selector instead. Supported special attributes:
PG_DIALOG_TITLE
: Sets specific title for the dir selector.
See also
PropertyGrid Property Attribute Identifiers
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. Supported special attributes:
PG_DIALOG_TITLE
: Sets a specific title for the file dialog.
PG_FILE_DIALOG_STYLE
: Sets a specific wx.FileDialog style for the file dialog.
PG_FILE_WILDCARD
: Sets wildcard (see wx.FileDialog for format details), “All
files…” is default.
- PG_FILE_SHOW_FULL_PATH
: Default True
. When False
, only the file name is shown (i.e. drive and directory are hidden).
- PG_FILE_SHOW_RELATIVE_PATH
: If set, then the filename is shown relative to the given path string.
- PG_FILE_INITIAL_PATH
: Sets the initial path of where to look for files.
See also
PropertyGrid Property Attribute Identifiers
Represents a single selection from a list of choices - wx.adv.OwnerDrawnComboBox is used to edit the value.
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” (i.e. 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.
Property that manages a list of strings. Allows editing of a list of strings in wx.TextCtrl and in a separate dialog. Supported special attributes:
PG_ARRAY_DELIMITER
: Sets string delimiter character.
PG_DIALOG_TITLE
: Sets a specific title for the editor dialog. Default is comma (‘,’).
See also
PropertyGrid Property Attribute Identifiers
Property representing wx.DateTime. Default editor is DatePickerCtrl, although TextCtrl should work as well. Supported special attributes:
PG_DATE_FORMAT
: Determines displayed date format (with wx.DateTime.Format
). Default is recommended as it is locale-dependent.
PG_DATE_PICKER_STYLE
: Determines window style used with wx.adv.DatePickerCtrl. Default is DP_DEFAULT
| DP_SHOWCENTURY
. Using DP_ALLOWNONE
enables additional support for unspecified property value.
See also
PropertyGrid Property Attribute Identifiers
Represents a string that can be freely edited or selected from list of choices - custom combobox control is used to edit the value.
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. Supported special attributes:
PG_ATTR_MULTICHOICE_USERSTRINGMODE
: If > 0, allows user to manually enter strings that are not in the list of choices. If this value is 1, user strings are preferably placed in front of valid choices. If value is 2, then those strings will placed behind valid choices.
PG_DIALOG_TITLE
: Sets a specific title for the editor dialog.
See also
PropertyGrid Property Attribute Identifiers
Property representing image file(name). Like wx.propgrid.FileProperty, but has thumbnail of the image in front of the filename and autogenerates wildcard from available image handlers. Supported special attributes:
PG_DIALOG_TITLE
: Sets a specific title for the file dialog.
PG_FILE_DIALOG_STYLE
: Sets a specific wx.FileDialog style for the file dialog.
PG_FILE_WILDCARD
: Sets wildcard (see wx.FileDialog for format details), “All
files…” is default.
- PG_FILE_SHOW_FULL_PATH
: Default True
. When False
, only the file name is shown (i.e. drive and directory are hidden).
- PG_FILE_SHOW_RELATIVE_PATH
: If set, then the filename is shown relative to the given path string.
- PG_FILE_INITIAL_PATH
: Sets the initial path of where to look for files.
See also
PropertyGrid Property Attribute Identifiers
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. Supported special attributes:
PG_COLOUR_HAS_ALPHA
: If set to True
allows user to edit the alpha colour component.
See also
PropertyGrid Property Attribute Identifiers
Represents wx.Font. Various sub-properties are used to edit individual subvalues. Supported special attributes:
PG_DIALOG_TITLE
: Sets a specific title for the font dialog.
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).
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)
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.
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:
import wx.propgrid as wxpg
class MyProperty(wxpg.PGProperty):
def __init__(self, label=wxpg.PG_LABEL, name=wxpg.PG_LABEL, value=0):
wxpg.PGProperty.__init__(self, label, name)
self.my_value = int(value)
def DoGetEditorClass(self):
"""
Determines what editor should be used for this property type. This
is one way to specify one of the stock editors.
"""
return wxpg.PropertyGridInterface.GetEditorByName("TextCtrl")
def ValueToString(self, value, flags):
"""
Convert the given property value to a string.
"""
return str(value)
def StringToValue(self, st, flags):
"""
Convert a string to the correct type for the property.
If failed, return False or (False, None). If success, return tuple
(True, newValue).
"""
try:
val = int(st)
return (True, val)
except (ValueError, TypeError):
pass
except:
raise
return (False, None)
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: wxVariants are handled internally in wxPython. Conversions are
# implicitly done for those types that wxVariant already knows about, and
# the Raw PyObject is used for those that it doesn't know about.
Note
Uses int value, similar to wx.propgrid.EnumProperty, unless text entered by user is is not in choices (in which case string value is used).
wx.propgrid.BoolProperty, wx.propgrid.DateProperty, wx.propgrid.EditorDialogProperty, wx.propgrid.EnumProperty, wx.propgrid.FlagsProperty, wx.propgrid.NumericProperty, PGRootProperty , wx.propgrid.PropertyCategory, wx.propgrid.StringProperty
Adapts list variant into proper value using consecutive |
|
Append a new choice to property’s list of choices. |
|
Adds a private child property. |
|
Use this member function to add independent (i.e. |
|
Determines, recursively, if all children are not unspecified. |
|
Returns |
|
Sets or clears given property flag. |
|
Called after value of a child property has been altered. |
|
Deletes children of the property. |
|
Removes entry from property’s wx.propgrid.PGChoices and editor control (if it is active). |
|
Returns value of an attribute. |
|
Returns pointer to an instance of used editor. |
|
Returns pointer to the wx.Validator that should be used with the editor of this property ( |
|
Override this to return something else than m_value as the value. |
|
Reimplement this member function to add special handling for attributes of this property. |
|
Enables or disables the property. |
|
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. |
|
Composes text from values of child properties. |
|
Returns property attribute value, null variant if not found. |
|
Returns named attribute, as double, if found. |
|
Returns named attribute, as long, if found. |
|
Returns map-like storage of property’s attributes. |
|
Returns attributes as list Variant . |
|
Returns property’s base name (i.e. |
|
Returns wx.propgrid.PGCell of given column, creating one if necessary. |
|
Returns used wx.propgrid.PGCellRenderer instance for given property column (label=0, value=1). |
|
Returns number of child properties. |
|
Returns height of children, recursively, and by taking expanded/collapsed status into account. |
|
Returns which choice is currently selected. |
|
Returns read-only reference to property’s list of choices. |
|
Gets managed client object of a property. |
|
Alias for |
|
Returns editor used for given column. |
|
Returns common value selected for this property. |
|
Returns property’s default value. |
|
Return number of displayed common values for this property. |
|
Returns property’s displayed text. |
|
Returns wx.propgrid.PGEditor that will be used and created when property becomes selected. |
|
Returns instance of a new wx.propgrid.PGEditorDialogAdapter instance, which is used when user presses the (optional) button next to the editor control;. |
|
Gets flags as a’|’ delimited string. |
|
Returns property grid where property lies. |
|
Returns owner wx.propgrid.PropertyGrid, but only if one is currently on a page displaying this property. |
|
Returns property’s help or description text. |
|
Returns property’s hint text (shown in empty value cell). |
|
Converts image width into full image offset, with margins. |
|
Returns position in parent’s array. |
|
Returns property at given virtual y coordinate. |
|
Returns property’s label. |
|
Returns last visible child property, recursively. |
|
Returns highest level non-category, non-root parent. |
|
Returns maximum allowed length of the text the user can enter in the property text editor. |
|
Returns property’s name with all (non-category, non-root) parents. |
|
Returns wx.propgrid.PGCell of given column, creating one if necessary. |
|
Return parent of property. |
|
Returns (direct) child property with given name (or |
|
Gets assignable version of property’s validator. |
|
Returns property’s value. |
|
Returns text representation of property’s value. |
|
Returns bitmap that appears next to value text. |
|
Returns value type used by this property. |
|
Returns coordinate to the top y of the property. |
|
Returns |
|
Returns |
|
Returns |
|
Hides or reveals the property. |
|
Returns index of given child property. |
|
Use this member function to add independent (i.e. |
|
Inserts a new choice to property’s list of choices. |
|
Converts integer (possibly a choice selection) into Variant value appropriate for this property. |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns |
|
Returns child property at index i. |
|
Returns last sub-property. |
|
Override to paint an image in front of the property value text or drop-down list item (but only if |
|
Events received by editor widgets are processed here. |
|
Returns size of the custom painted image in front of property. |
|
This virtual function is called after m_value has been set. |
|
Called whenever validation has failed with given pending value. |
|
If property’s editor is created this forces its recreation. |
|
Refresh values of child properties. |
|
If property’s editor is active, then update it’s value. |
|
Sets an attribute for this property. |
|
Set the property’s attributes from a Python dictionary. |
|
Set if user can change the property’s value to unspecified by modifying the value of the editor control (usually by clearing it). |
|
Sets property’s background colour. |
|
Sets cell information for given column. |
|
Sets selected choice and changes property value. |
|
Sets new set of choices for the property. |
|
Sets client object of a property. |
|
Alias for |
|
Sets common value selected for this property. |
|
Sets property’s default text and background colours. |
|
Set default value of a property. |
|
Sets editor for a property. |
|
Sets or clears given property flag, recursively. |
|
Sets flags from a ‘|’ delimited string. |
|
Sets property’s help string, which is shown, for example, in wx.propgrid.PropertyGridManager’s description text box. |
|
Sets property’s label. |
|
Set maximum length of the text the user can enter in the text editor. |
|
Sets property’s “is it modified?” flag. |
|
Sets new (base) name for property. |
|
Changes what sort of parent this property is for its children. |
|
Sets property’s text colour. |
|
Sets wx.Validator for a property. |
|
Call this to set value of the property. |
|
Converts integer to a value, and if successful, calls |
|
Converts string to a value, and if successful, calls |
|
Set wx.Bitmap taken from wx.BitmapBundle in front of the value. |
|
Call this function in |
|
Sets property’s value to unspecified (i.e. |
|
Call with |
|
Converts text into Variant value appropriate for this property. |
|
Updates composed values of parent non-category properties, recursively. |
|
Returns |
|
Implement this function in derived class to check the value. |
|
Converts property value into a text representation. |
|
Default constructor. |
A public C++ attribute of type ````. This member is public so scripting language bindings wrapper code can access it freely. |
wx.propgrid.
PGProperty
(Object)¶Possible constructors:
PGProperty()
PGProperty(label, name)
PGProperty is base class for all PropertyGrid properties and as such it is not intended to be instantiated directly.
AdaptListToValue
(self, list, value)¶Adapts list variant into proper value using consecutive ChildChanged
calls.
list (PGVariant) –
value (PGVariant) –
AddChoice
(self, label, value=PG_INVALID_VALUE)¶Append a new choice to property’s list of choices.
label (string) – Label for added choice.
value (int) – Value for new choice. Do not specify if you wish this to equal choice index.
int
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 PG_PROP_AGGREGATE
. In other words, all properties of this property will become private.
prop (wx.propgrid.PGProperty) –
AppendChild
(self, childProperty)¶Use this member function to add independent (i.e.
regular) children to a property.
childProperty (wx.propgrid.PGProperty) –
Appended childProperty.
AreAllChildrenSpecified
(self, pendingList=None)¶Determines, recursively, if all children are not unspecified.
pendingList (PGVariant) – Assumes members in this Variant list as pending replacement values.
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).
bool
ChangeFlag
(self, flag, set)¶Sets or clears given property flag.
Mainly for internal use.
flag (PGPropertyFlags) –
set (bool) –
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 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
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.
PGVariant
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.
index (int) –
DoGetAttribute
(self, name)¶Returns value of an attribute.
Override if custom handling of attributes is needed.
Default implementation simply return None
variant.
name (string) –
PGVariant
DoGetEditorClass
(self)¶Returns pointer to an instance of used editor.
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
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.
PGVariant
DoSetAttribute
(self, name, value)¶Reimplement this member function to add special handling for attributes of this property.
name (string) –
value (PGVariant) –
bool
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.
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.
enable (bool) –
GenerateComposedValue
(self)¶Composes text from values of child properties.
string
GetAttribute
(self, *args, **kw)¶GetAttribute (self, name)
Returns property attribute value, null variant if not found.
name (string) –
PGVariant
Note
For built-in attribute returns null variant if extra style PG_EX_WRITEONLY_BUILTIN_ATTRIBUTES
is set.
GetAttribute (self, name, defVal)
Returns named attribute, as string, if found.
Otherwise defVal is returned.
name (string) –
defVal (string) –
string
Note
For built-in attribute returns defVal if extra style PG_EX_WRITEONLY_BUILTIN_ATTRIBUTES
is set.
GetAttributeAsDouble
(self, name, defVal)¶Returns named attribute, as double, if found.
Otherwise defVal is returned.
name (string) –
defVal (float) –
float
Note
For built-in attribute returns defVal if extra style PG_EX_WRITEONLY_BUILTIN_ATTRIBUTES
is set.
GetAttributeAsLong
(self, name, defVal)¶Returns named attribute, as long, if found.
Otherwise defVal is returned.
name (string) –
defVal (long) –
long
Note
For built-in attribute returns defVal if extra style PG_EX_WRITEONLY_BUILTIN_ATTRIBUTES
is set.
GetAttributes
(self)¶Returns map-like storage of property’s attributes.
PyObject
Note
If extra style PG_EX_WRITEONLY_BUILTIN_ATTRIBUTES
is set, then builtin-attributes are not included in the storage.
GetAttributesAsList
(self)¶Returns attributes as list Variant .
PGVariant
Note
If extra style PG_EX_WRITEONLY_BUILTIN_ATTRIBUTES
is set, then builtin-attributes are not included in the list.
GetBaseName
(self)¶Returns property’s base name (i.e.
parent’s name is not added in any case).
string
GetCell
(self, column)¶Returns wx.propgrid.PGCell of given column, creating one if necessary.
column (int) –
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.
column (int) –
GetChildCount
(self)¶Returns number of child properties.
int
GetChildrenHeight
(self, lh, iMax=-1)¶Returns height of children, recursively, and by taking expanded/collapsed status into account.
lh (int) – Line height. Pass result of GetGrid
.GetRowHeight() here.
iMax (int) – Only used (internally) when finding property y-positions.
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.
int
GetChoices
(self)¶Returns read-only reference to property’s list of choices.
GetClientData
(self)¶Gets managed client object of a property.
ClientData
GetClientObject
(self, n)¶Alias for GetClientData
GetColumnEditor
(self, column)¶Returns editor used for given column.
None
for no editor.
column (int) –
GetCommonValue
(self)¶Returns common value selected for this property.
-1 for none.
int
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.
PGVariant
GetDepth
(self)¶int
GetDisplayedCommonValueCount
(self)¶Return number of displayed common values for this property.
int
GetDisplayedString
(self)¶Returns property’s displayed text.
string
GetEditorClass
(self)¶Returns wx.propgrid.PGEditor that will be used and created when property becomes selected.
Returns more accurate value than DoGetEditorClass
.
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
(i.e. no action is generated when button is pressed).
GetFlagsAsString
(self, flagsMask)¶Gets flags as a’|’ delimited string.
Note that flag names are not prepended with ‘wx``PG_PROP_``’.
flagsMask (FlagType) – String will only be made to include flags combined by this parameter.
string
GetGrid
(self)¶Returns property grid where property lies.
GetGridIfDisplayed
(self)¶Returns owner wx.propgrid.PropertyGrid, but only if one is currently on a page displaying this property.
GetHelpString
(self)¶Returns property’s help or description text.
string
See also
GetHintText
(self)¶Returns property’s hint text (shown in empty value cell).
string
GetImageOffset
(self, imageWidth)¶Converts image width into full image offset, with margins.
imageWidth (int) –
int
GetIndexInParent
(self)¶Returns position in parent’s array.
int
GetItemAtY
(self, y)¶Returns property at given virtual y coordinate.
y (int) –
GetLabel
(self)¶Returns property’s label.
string
GetLastVisibleSubItem
(self)¶Returns last visible child property, recursively.
GetMainParent
(self)¶Returns highest level non-category, non-root parent.
Useful when you have nested properties with children.
Note
If immediate parent is root or category, this will return the property itself.
GetMaxLength
(self)¶Returns maximum allowed length of the text the user can enter in the property text editor.
int
Note
0 is returned if length is not explicitly limited and the text can be as long as it is supported by the underlying native text control widget.
GetName
(self)¶Returns property’s name with all (non-category, non-root) parents.
string
GetOrCreateCell
(self, column)¶Returns wx.propgrid.PGCell of given column, creating one if necessary.
column (int) –
GetParent
(self)¶Return parent of property.
GetPropertyByName
(self, name)¶Returns (direct) child property with given name (or None
if not found).
name (string) – Name of the child property to look for.
GetValidator
(self)¶Gets assignable version of property’s validator.
Validator
GetValue
(self)¶Returns property’s value.
PGVariant
GetValueAsString
(self, argFlags=0)¶Returns text representation of property’s value.
argFlags (int) – If 0 (default value), then displayed string is returned. If PG_FULL_VALUE
is set, returns complete, storable string value instead of displayable. If PG_EDITABLE_VALUE
is set, returns string value that must be editable in textctrl. If PG_COMPOSITE_FRAGMENT
is set, returns text that is appropriate to display as a part of string property’s composite text representation.
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
.
Bitmap
GetValueType
(self)¶Returns value type used by this property.
string
GetY
(self)¶Returns coordinate to the top y of the property.
Note that the position of scrollbars is not taken into account.
int
HasFlag
(self, flag)¶Returns True
if property has given flag set.
flag (PGPropertyFlags) –
bool
See also
propgrid_propflags
HasFlagsExact
(self, flags)¶Returns True
if property has all given flags set.
flags (FlagType) –
bool
HasVisibleChildren
(self)¶Returns True
if property has even one visible child.
bool
Hide
(self, hide, flags=PG_RECURSE)¶Hides or reveals the property.
hide (bool) – True
for hide, False
for reveal.
flags (int) – By default changes are applied recursively. Set this parameter to PG_DONT_RECURSE
to prevent this.
bool
Index
(self, p)¶Returns index of given child property.
wx.NOT_FOUND
if given property is not child of this.
p (wx.propgrid.PGProperty) –
int
InsertChild
(self, index, childProperty)¶Use this member function to add independent (i.e.
regular) children to a property.
index (int) –
childProperty (wx.propgrid.PGProperty) –
Inserted childProperty.
InsertChoice
(self, label, index, value=PG_INVALID_VALUE)¶Inserts a new choice to property’s list of choices.
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.
int
IntToValue
(self, number, argFlags=0)¶Converts integer (possibly a choice selection) into Variant value appropriate for this property.
number (int) – Integer to be translated into variant.
argFlags (int) – If PG_FULL_VALUE
is set, returns complete, storable value instead of displayable one.
tuple
( 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.
bool
IsEnabled
(self)¶Returns True
if property is enabled.
bool
IsExpanded
(self)¶Returns True
if property has visible children.
bool
IsRoot
(self)¶Returns True
if this property is actually a RootProperty.
bool
IsSomeParent
(self, candidateParent)¶Returns True
if candidateParent is some parent of this property.
Use, for example, to detect if item is inside collapsed section.
candidateParent (wx.propgrid.PGProperty) –
bool
IsSubProperty
(self)¶Returns True
if this is a sub-property.
bool
IsTextEditable
(self)¶Returns True
if property has editable wx.TextCtrl when selected.
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.
bool
IsVisible
(self)¶Returns True
if all parents expanded.
bool
Item
(self, i)¶Returns child property at index i.
i (int) –
Last
(self)¶Returns last sub-property.
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+rect.width) 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.
rect (wx.Rect) – Box reserved for custom graphics. Includes surrounding rectangle, if any. If x+width is < 0, then this is a measure item call (see above).
paintdata (wx.propgrid.PGPaintData) – wx.propgrid.PGPaintData structure with much useful data about painted item.
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
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.
propgrid (wx.propgrid.PropertyGrid) –
wnd_primary (wx.Window) –
event (wx.Event) –
return True
if any changes in value should be reported.
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.
item (int) – Normally -1, but can be an index to the property’s list of items.
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 PG_DEFAULT_IMAGE_SIZE
which equals DefaultSize.
OnSetValue
(self)¶This virtual function is called after m_value has been set.
Note
If m_value was set to Null variant (i.e. 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.
pendingValue (PGVariant) –
Note
If you implement this in your custom property class, please remember to call the base implementation as well, since they may use it to revert property into pre-change state.
RecreateEditor
(self)¶If property’s editor is created this forces its recreation.
Useful in SetAttribute etc. Returns True
if actually did anything.
bool
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.
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.
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.
colour (wx.Colour) – Background colour to use.
flags (int) – Default is 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.
Note
Unlike wx.propgrid.PropertyGridInterface.SetPropertyBackgroundColour
, this does not automatically update the display.
SetCell
(self, column, cell)¶Sets cell information for given column.
column (int) –
cell (wx.propgrid.PGCell) –
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.
If newValue is wx.NOT_FOUND
( -1
), then the property’s value is reset to unspecified, as if SetValueToUnspecified
was called.
newValue (int) –
SetChoices
(self, choices)¶Sets new set of choices for the property.
choices (wx.propgrid.PGChoices) –
bool
Note
This operation deselects the property and clears its value.
SetClientData
(self, data)¶Sets client object of a property.
data (ClientData) –
SetClientObject
(self, n, data)¶Alias for SetClientData
SetCommonValue
(self, commonValue)¶Sets common value selected for this property.
-1 for none.
commonValue (int) –
SetDefaultColours
(self, flags=PG_RECURSE)¶Sets property’s default text and background colours.
flags (int) – Default is PG_RECURSE
which causes colours to be set recursively. Omit this flag to only set colours for the property in question and not any of its children.
New in version 4.1/wxWidgets-3.1.0.
Note
Unlike wx.propgrid.PropertyGridInterface.SetPropertyColoursToDefault
, this does not automatically update the display.
SetDefaultValue
(self, value)¶Set default value of a property.
Synonymous to
theProperty.SetAttribute("DefaultValue", value)
value (PGVariant) –
SetEditor
(self, *args, **kw)¶SetEditor (self, editor)
Sets editor for a property.
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.
editorName (string) –
SetExpanded
(self, expanded)¶expanded (bool) –
SetFlagRecursively
(self, flag, set)¶Sets or clears given property flag, recursively.
This function is primarily intended for internal use.
flag (PGPropertyFlags) –
set (bool) –
See also
SetFlagsFromString
(self, str)¶Sets flags from a ‘|’ delimited string.
Note that flag names are not prepended with ‘wx``PG_PROP_``’.
str (string) –
SetHelpString
(self, helpString)¶Sets property’s help string, which is shown, for example, in wx.propgrid.PropertyGridManager’s description text box.
helpString (string) –
SetLabel
(self, label)¶Sets property’s label.
label (string) –
Note
Properties under same parent may have same labels. However, property names must still remain unique.
Unlike wx.propgrid.PropertyGridInterface.SetPropertyLabel
, this does not automatically update the display.
SetMaxLength
(self, maxLen)¶Set maximum length of the text the user can enter in the text editor.
If it is 0, the length is not limited and the text can be as long as it is supported by the underlying native text control widget.
maxLen (int) –
bool
Returns True
if maximum length was set.
SetModifiedStatus
(self, modified)¶Sets property’s “is it modified?” flag.
Affects children recursively.
modified (bool) –
SetName
(self, newName)¶Sets new (base) name for property.
newName (string) –
SetParentalType
(self, flag)¶Changes what sort of parent this property is for its children.
flag (int) – Use one of the following values: PG_PROP_MISC_PARENT
(for generic parents), PG_PROP_CATEGORY
(for categories), or 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.
colour (wx.Colour) – Text colour to use.
flags (int) – Default is 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.
Note
Unlike wx.propgrid.PropertyGridInterface.SetPropertyTextColour
, this does not automatically update the display.
SetValidator
(self, validator)¶Sets wx.Validator for a property.
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.
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) – 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.
value (long) – Int to get the value from.
flags (int) – If has PG_FULL_VALUE
, then the value given is an actual value and not an index.
bool
True
if value was changed.
SetValueFromString
(self, text, flags=PG_PROGRAMMATIC_VALUE)¶Converts string to a value, and if successful, calls SetValue
on it.
Default behaviour is to do nothing.
text (string) – String to get the value from.
flags (int) – If PG_FULL_VALUE
is set, the function sets complete, storable value instead of displayable one (they may be different). PG_PROGRAMMATIC_VALUE
flag is used to indicate that value is being set programmatically (i.e. operation is not caused by user input). If PG_REPORT_ERROR
is set, a special action should be performed if string couldn’t have been successfully converted to the valid value (e.g. a special value can be set in this case).
bool
True
if value was changed.
SetValueImage
(self, bmp)¶Set wx.Bitmap taken from wx.BitmapBundle in front of the value.
This bitmap may be ignored by custom cell renderers.
bmp (wx.BitmapBundle) –
SetValueInEvent
(self, value)¶Call this function in OnEvent
, OnButtonClick() etc.
to change the property value based on user input.
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.
SetValueToUnspecified
(self)¶Sets property’s value to unspecified (i.e.
Null variant).
SetWasModified
(self, set=True)¶Call with False
in OnSetValue
to cancel value changes after all (i.e.
cancel True
returned by StringToValue
or IntToValue
).
set (bool) –
StringToValue
(self, text, argFlags=0)¶Converts text into Variant value appropriate for this property.
text (string) – Text to be translated into variant.
argFlags (int) – If PG_FULL_VALUE
is set, returns complete, storable value instead of displayable one (they may be different). If 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).
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).
( 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.
Note
Must not call SetValue
(as can be called in it).
UsesAutoUnspecified
(self)¶Returns True
if containing grid uses PG_EX_AUTO_UNSPECIFIED_VALUES
.
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.
value (PGVariant) –
validationInfo (wx.propgrid.PGValidationInfo) –
bool
Note
Default implementation always returns True
.
ValueToString
(self, value, argFlags=0)¶Converts property value into a text representation.
value (PGVariant) – Value to be converted.
argFlags (int) – If 0 (default value), then displayed string is returned. If PG_FULL_VALUE
is set, returns complete, storable string value instead of displayable. If PG_EDITABLE_VALUE
is set, returns string value that must be editable in textctrl. If PG_COMPOSITE_FRAGMENT
is set, returns text that is appropriate to display as a part of string property’s composite text representation.
string
Note
Default implementation calls GenerateComposedValue
.
__init__
(self, *args, **kw)¶__init__ (self)
Default constructor.
It is protected because wx.propgrid.PGProperty is only a base class for other property classes.
__init__ (self, label, name)
Constructor.
It is protected because wx.propgrid.PGProperty is only a base class for other property classes. 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)
label (string) –
name (string) –
m_clientData
¶A public C++ attribute of type ````. This member is public so scripting language bindings wrapper code can access it freely.