.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2017 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.propgrid.PGProperty:

==========================================================================================================================================
|phoenix_title|  **wx.propgrid.PGProperty**
==========================================================================================================================================

:ref:`wx.propgrid.PGProperty`  is base class for all :ref:`wx.propgrid.PropertyGrid`  properties.          

In sections below we cover few related topics. 



- :ref:`Supplied Ready-to-use Property Classes <wx.propgrid.PGProperty>`   
- :ref:`Creating Custom Properties <wx.propgrid.PGProperty>` 






|phoenix_title| Supplied Ready-to-use Property Classes
======================================================

Here is a list and short description of supplied fully-functional property classes. They are located in either :ref:`props.h`  or :ref:`advprops.h`. 

- :ref:`wx.propgrid.ArrayStringProperty`   
- :ref:`wx.propgrid.BoolProperty`   
- :ref:`wx.propgrid.ColourProperty`   
- :ref:`wx.propgrid.CursorProperty`   
- :ref:`wx.propgrid.DateProperty`   
- :ref:`wx.propgrid.DirProperty`   
- :ref:`wx.propgrid.EditEnumProperty`   
- :ref:`wx.propgrid.EnumProperty`   
- :ref:`wx.propgrid.FileProperty`   
- :ref:`wx.propgrid.FlagsProperty`   
- :ref:`wx.propgrid.FloatProperty`   
- :ref:`wx.propgrid.FontProperty`   
- :ref:`wx.propgrid.ImageFileProperty`   
- :ref:`wx.propgrid.IntProperty`   
- :ref:`wx.propgrid.LongStringProperty`   
- :ref:`wx.propgrid.MultiChoiceProperty`   
- :ref:`wx.propgrid.PropertyCategory`   
- :ref:`wx.propgrid.StringProperty`   
- :ref:`wx.propgrid.SystemColourProperty`   
- :ref:`wx.propgrid.UIntProperty` 




|phoenix_title| PropertyCategory
================================

Not an actual property per se, but a header for a group of properties. Regardless inherits from :ref:`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 :meth:`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 :ref:`wx.TextCtrl`. ``PG_ATTR_AUTOCOMPLETE`` attribute may be used to enable auto-completion (use a :ref:`ArrayString`  value), and is also supported by any property that happens to use a TextCtrl-based editor.  

|phoenix_title| IntProperty
===========================

Like :ref:`wx.propgrid.StringProperty`, but converts text to a signed long integer. :ref:`wx.propgrid.IntProperty`  seamlessly supports 64-bit integers (ie. :ref:`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 :ref:`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 :ref:`wx.propgrid.IntProperty`, :ref:`wx.propgrid.UIntProperty`  seamlessly supports 64-bit  integers (ie. :ref:`ULongLong`). Same :ref:`Variant`  safety rules apply.  

|phoenix_title| FloatProperty
=============================

Like :ref:`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. :ref:`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 :ref:`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 :ref:`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 :ref:`wx.propgrid.LongStringProperty`, but the button triggers dir selector instead. Supported properties (all with string value): ``PG_DIR_DIALOG_MESSAGE``.  

|phoenix_title| FileProperty
============================

Like :ref:`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 :ref:`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 - :ref:`wx.adv.OwnerDrawnComboBox`  is used to edit the value.  

|phoenix_title| FlagsProperty
=============================

Represents a bit set that fits in a long integer. :ref:`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 :ref:`wx.propgrid.FlagsProperty`, you will need to use :meth:`wx.propgrid.PGProperty.SetChoices`   - otherwise they will not get updated properly. :ref:`wx.propgrid.FlagsProperty`  supports the same attributes as :ref:`wx.propgrid.BoolProperty`.  

|phoenix_title| ArrayStringProperty
===================================

Allows editing of a list of strings in :ref:`wx.TextCtrl`  and in a separate dialog. Supports "Delimiter" attribute, which defaults to comma (',').  

|phoenix_title| DateProperty
============================

:ref:`wx.DateTime`  property. Default editor is DatePickerCtrl, although TextCtrl should work as well. ``PG_DATE_FORMAT`` attribute can be used to change string :meth:`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 :ref:`wx.MultiChoiceDialog`. It uses :ref:`ArrayString`  value.  

|phoenix_title| ImageFileProperty
=================================

Like :ref:`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 :ref:`wx.Colour`. :ref:`wx.Button`  is used to trigger a colour picker dialog. There are various sub-classing opportunities with this class. See below in :ref:`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 :ref:`wx.Font`. Various sub-properties are used to edit individual subvalues.  

|phoenix_title| SystemColourProperty
====================================

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



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





|phoenix_title| CursorProperty
==============================

Represents a :ref:`wx.Cursor`. :ref:`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 :ref:`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 :ref:`wx.propgrid.PGProperty`  derives from :ref:`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** :ref:`VariantData` **class for all data types used as property values.**   You can use macros declared in :ref:`wx.propgrid.PropertyGrid`  headers. For instance: ::







.. note:: 

   :ref:`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 :ref:`wx.propgrid.FontProperty`, for instance.  







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>PGProperty</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.propgrid.PGProperty_inheritance.png" alt="Inheritance diagram of PGProperty" usemap="#dummy" class="inheritance"/></center>
   </div>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.Object.html" title="wx.Object" alt="" coords="49,5,131,35"/> <area shape="rect" id="node2" href="wx.propgrid.PGProperty.html" title="wx.propgrid.PGProperty" alt="" coords="5,83,176,112"/> </map> 
   </p>

|


|sub_classes| Known Subclasses
==============================

:ref:`wx.propgrid.ArrayStringProperty`, :ref:`wx.propgrid.BoolProperty`, :ref:`wx.propgrid.DateProperty`, :ref:`wx.propgrid.EnumProperty`, :ref:`wx.propgrid.FileProperty`, :ref:`wx.propgrid.FlagsProperty`, :ref:`wx.propgrid.FloatProperty`, :ref:`wx.propgrid.FontProperty`, :ref:`wx.propgrid.IntProperty`, :ref:`wx.propgrid.LongStringProperty`, :ref:`wx.propgrid.MultiChoiceProperty`, :ref:`wx.propgrid.PropertyCategory`, :ref:`wx.propgrid.StringProperty`, :ref:`wx.propgrid.UIntProperty`

|


|method_summary| Methods Summary
================================

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


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.propgrid.PGProperty.m_value`                                          See :meth:`~wx.propgrid.PGProperty.GetValue` and :meth:`~wx.propgrid.PGProperty.SetValue`
:attr:`~wx.propgrid.PGProperty.m_clientData`                                     A public C++ attribute of type ````.
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.propgrid.PGProperty(Object)

   **Possible constructors**::

       PGProperty()
       
       PGProperty(label, name)
       
   
   PGProperty is base class for all PropertyGrid properties.



   .. method:: __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)
      
                       
      
      
      :param `label`: 
      :type `label`: string
      :param `name`: 
      :type `name`: string
      
      
      
      
      
      
      **~~~**






   .. method:: AdaptListToValue(self, list, value)

      Adapts list variant into proper value using consecutive :meth:`ChildChanged`   calls.                  


      :param `list`: 
      :type `list`: PGVariant
      :param `value`: 
      :type `value`: PGVariant







   .. method:: AddChild(self, prop)

      Adds a private child property.                  



                


      :param `prop`: 
      :type `prop`: wx.propgrid.PGProperty






      .. deprecated:: 4.0.1
         Use :meth:`AddPrivateChild`   instead.   







      .. seealso:: :meth:`AddPrivateChild`     








   .. method:: AddChoice(self, label, value=PG_INVALID_VALUE)

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




      :param `label`: Label for added choice.  
      :type `label`: string
      :param `value`: Value for new choice. Do not specify if you wish this to equal choice index.  
      :type `value`: int








      :rtype: `int`



                  



      :returns: 

         Index to added choice.   








   .. method:: AddPrivateChild(self, prop)

      Adds a private child property.                  

      If you use this instead of :meth:`wx.propgrid.PropertyGridInterface.Insert`   or :meth:`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.                  


      :param `prop`: 
      :type `prop`: wx.propgrid.PGProperty







   .. method:: AppendChild(self, childProperty)

      Use this member function to add independent (ie.                  

      regular) children to a property. 

                


      :param `childProperty`: 
      :type `childProperty`: wx.propgrid.PGProperty




      :rtype: :ref:`wx.propgrid.PGProperty`







      :returns: 

         Appended childProperty.  







      .. note:: 

         :ref:`wx.propgrid.PropertyGrid`  is not automatically refreshed by this function.  







      .. seealso:: :meth:`InsertChild` , :meth:`AddPrivateChild`     








   .. method:: AreAllChildrenSpecified(self, pendingList=None)

      Determines, recursively, if all children are not unspecified.                  




      :param `pendingList`: Assumes members in this :ref:`Variant`  list as pending replacement values.   
      :type `pendingList`: PGVariant






      :rtype: `bool`



                  





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

      :rtype: `bool`








   .. method:: ChangeFlag(self, flag, set)

      Sets or clears given property flag.                  

      Mainly for internal use. 

                


      :param `flag`: 
      :type `flag`: wx.propgrid.PGPropertyFlags
      :param `set`: 
      :type `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 ``wx.propgrid.PG_PROP_DISABLED`` flag.  







      .. seealso:: :meth:`HasFlag` , :meth:`GetFlags`     








   .. method:: 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 :meth:`GetValue`   or m_value should not be relied on. 

      Sample pseudo-code implementation: 

      ::

          # TBW






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










      :rtype: :ref:`PGVariant`



                  



      :returns: 

         Modified value of the whole property.   








   .. method:: DeleteChildren(self)

      Deletes children of the property.                   





   .. method:: DeleteChoice(self, index)

      Removes entry from property's :ref:`wx.propgrid.PGChoices`  and editor control (if it is active).                  

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


      :param `index`: 
      :type `index`: int







   .. method:: DoGetAttribute(self, name)

      Returns value of an attribute.                  

      Override if custom handling of attributes is needed. 

      Default implementation simply return ``None`` variant.                  


      :param `name`: 
      :type `name`: string




      :rtype: :ref:`PGVariant`








   .. method:: DoGetEditorClass(self)

      Returns pointer to an instance of used editor.                  

      :rtype: :ref:`wx.propgrid.PGEditor`








   .. method:: DoGetValidator(self)

      Returns pointer to the :ref:`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



                

      :rtype: :ref:`Validator`







      .. note:: 

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








   .. method:: DoGetValue(self)

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

      :rtype: :ref:`PGVariant`








   .. method:: DoSetAttribute(self, name, value)

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

                


      :param `name`: 
      :type `name`: string
      :param `value`: 
      :type `value`: PGVariant




      :rtype: `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 :meth:`wx.propgrid.PGProperty.SetAttribute`   instead.   








   .. method:: Enable(self, enable=True)

      Enables or disables the property.                  

      Disabled property usually appears as having grey text. 




      :param `enable`: If ``False``, property is disabled instead.  
      :type `enable`: bool




                  



      .. seealso:: :meth:`wx.propgrid.PropertyGridInterface.EnableProperty`     








   .. method:: 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.                  


      :param `enable`: 
      :type `enable`: bool







   .. method:: GenerateComposedValue(self)

      Composes text from values of child properties.                  

      :rtype: `string`








   .. method:: GetAttribute(self, *args, **kw)



      |overload| Overloaded Implementations:

      **~~~**

      
      **GetAttribute** `(self, name)`
      
      Returns property attribute value, null variant if not found.                  
      
      
      :param `name`: 
      :type `name`: string
      
      
      
      
      :rtype: :ref:`PGVariant`
      
      
      
      
      
      
      
      **~~~**

      
      **GetAttribute** `(self, name, defVal)`
      
      Returns named attribute, as string, if found.                  
      
      Otherwise defVal is returned.                  
      
      
      :param `name`: 
      :type `name`: string
      :param `defVal`: 
      :type `defVal`: string
      
      
      
      
      :rtype: `string`
      
      
      
      
      
      
      
      **~~~**






   .. method:: GetAttributeAsDouble(self, name, defVal)

      Returns named attribute, as double, if found.                  

      Otherwise defVal is returned.                  


      :param `name`: 
      :type `name`: string
      :param `defVal`: 
      :type `defVal`: float




      :rtype: `float`








   .. method:: GetAttributeAsLong(self, name, defVal)

      Returns named attribute, as long, if found.                  

      Otherwise defVal is returned.                  


      :param `name`: 
      :type `name`: string
      :param `defVal`: 
      :type `defVal`: long




      :rtype: `long`








   .. method:: GetAttributes(self)

      Return atributes storage map.                  

      :rtype: :ref:`PyObject`








   .. method:: GetAttributesAsList(self)

      Returns attributes as list :ref:`Variant`.                  

      :rtype: :ref:`PGVariant`








   .. method:: GetBaseName(self)

      Returns property's base name (ie.                  

      parent's name is not added in any case)                  

      :rtype: `string`








   .. method:: GetCell(self, column)

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


      :param `column`: 
      :type `column`: int




      :rtype: :ref:`wx.propgrid.PGCell`








   .. method:: GetCellRenderer(self, column)

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

      Default implementation returns editor's renderer for all columns.                  


      :param `column`: 
      :type `column`: int




      :rtype: :ref:`wx.propgrid.PGCellRenderer`








   .. method:: GetChildCount(self)

      Returns number of child properties.                  

      :rtype: `int`








   .. method:: GetChildrenHeight(self, lh, iMax=-1)

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




      :param `lh`: Line height. Pass result of :meth:`GetGrid` .GetRowHeight() here.  
      :type `lh`: int
      :param `iMax`: Only used (internally) when finding property y-positions.   
      :type `iMax`: int








      :rtype: `int`



                  





   .. method:: 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.                  

      :rtype: `int`








   .. method:: GetChoices(self)

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

      :rtype: :ref:`wx.propgrid.PGChoices`








   .. method:: GetClientData(self)

      Sets managed client object of a property.                  

      :rtype: :ref:`ClientData`








   .. method:: GetClientObject(self, n)

      Alias for :meth:`GetClientData`



   .. method:: GetColumnEditor(self, column)

      Returns editor used for given column.                  

      ``None`` for no editor.                  


      :param `column`: 
      :type `column`: int




      :rtype: :ref:`wx.propgrid.PGEditor`








   .. method:: 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.                  

      :rtype: :ref:`PGVariant`








   .. method:: GetDisplayedString(self)

      Returns property's displayed text.                  

      :rtype: `string`








   .. method:: GetEditorClass(self)

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

      Returns more accurate value than :meth:`DoGetEditorClass` .                  

      :rtype: :ref:`wx.propgrid.PGEditor`








   .. method:: GetEditorDialog(self)

      Returns instance of a new :ref:`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).                  

      :rtype: :ref:`wx.propgrid.PGEditorDialogAdapter`








   .. method:: GetFlags(self)

      Returns property flags.                  

      :rtype: :ref:`FlagType`








   .. method:: GetGrid(self)

      Returns property grid where property lies.                  

      :rtype: :ref:`wx.propgrid.PropertyGrid`








   .. method:: GetGridIfDisplayed(self)

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

      :rtype: :ref:`wx.propgrid.PropertyGrid`








   .. method:: GetHelpString(self)

      Returns property's help or description text.                  

                

      :rtype: `string`







      .. seealso:: :meth:`SetHelpString`     








   .. method:: GetIndexInParent(self)

      Returns position in parent's array.                  

      :rtype: `int`








   .. method:: GetLabel(self)

      Returns property's label.                  

      :rtype: `string`








   .. method:: GetLastVisibleSubItem(self)

      Returns last visible child property, recursively.                  

      :rtype: :ref:`wx.propgrid.PGProperty`








   .. method:: GetMainParent(self)

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

      Useful when you have nested properties with children. 

                

      :rtype: :ref:`wx.propgrid.PGProperty`







      .. note:: 

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








   .. method:: GetMaxLength(self)

      Returns maximum allowed length of property's text value.                  

      :rtype: `int`








   .. method:: GetName(self)

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

      :rtype: `string`








   .. method:: GetOrCreateCell(self, column)

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


      :param `column`: 
      :type `column`: int




      :rtype: :ref:`wx.propgrid.PGCell`








   .. method:: GetParent(self)

      Return parent of property.                  

      :rtype: :ref:`wx.propgrid.PGProperty`








   .. method:: GetPropertyByName(self, name)

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


      :param `name`: 
      :type `name`: string




      :rtype: :ref:`wx.propgrid.PGProperty`








   .. method:: GetValidator(self)

      Gets assignable version of property's validator.                  

      :rtype: :ref:`Validator`








   .. method:: GetValue(self)

      Returns property's value.                  

      :rtype: :ref:`PGVariant`








   .. method:: GetValueAsString(self, argFlags=0)

      Returns text representation of property's value.                  




      :param `argFlags`: 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.  
      :type `argFlags`: int






      :rtype: `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 :meth:`ValueToString` , and overriding this function now will result in run-time assertion failure.   








   .. method:: GetValueImage(self)

      Returns bitmap that appears next to value text.                  

      Only returns non-NULL bitmap if one was set with :meth:`SetValueImage` .                  

      :rtype: :ref:`Bitmap`








   .. method:: GetValueString(self, argFlags=0)

      Synonymous to :meth:`GetValueAsString` .                  



                


      :param `argFlags`: 
      :type `argFlags`: int




      :rtype: `string`







      .. deprecated:: 4.0.1
         Use :meth:`GetValueAsString`   instead.   







      .. seealso:: :meth:`GetValueAsString`     








   .. method:: GetValueType(self)

      Returns value type used by this property.                  

      :rtype: `string`








   .. method:: GetY(self)

      Returns coordinate to the top y of the property.                  

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

      :rtype: `int`








   .. method:: HasFlag(self, flag)

      Returns non-zero if property has given flag set.                  

                


      :param `flag`: 
      :type `flag`: wx.propgrid.PGPropertyFlags




      :rtype: :ref:`FlagType`







      .. seealso:: propgrid_propflags   








   .. method:: HasVisibleChildren(self)

      Returns ``True`` if property has even one visible child.                  

      :rtype: `bool`








   .. method:: Hide(self, hide, flags=PG_RECURSE)

      Hides or reveals the property.                  




      :param `hide`: ``True`` for hide, ``False`` for reveal.  
      :type `hide`: bool
      :param `flags`: By default changes are applied recursively. Set this parameter ``wx.propgrid.PG_DONT_RECURSE`` to prevent this.   
      :type `flags`: int








      :rtype: `bool`



                  





   .. method:: Index(self, p)

      Returns index of given child property.                  

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


      :param `p`: 
      :type `p`: wx.propgrid.PGProperty




      :rtype: `int`








   .. method:: InsertChild(self, index, childProperty)

      Use this member function to add independent (ie.                  

      regular) children to a property. 

                


      :param `index`: 
      :type `index`: int
      :param `childProperty`: 
      :type `childProperty`: wx.propgrid.PGProperty




      :rtype: :ref:`wx.propgrid.PGProperty`







      :returns: 

         Inserted childProperty.  







      .. note:: 

         :ref:`wx.propgrid.PropertyGrid`  is not automatically refreshed by this function.  







      .. seealso:: :meth:`AppendChild` , :meth:`AddPrivateChild`     








   .. method:: InsertChoice(self, label, index, value=PG_INVALID_VALUE)

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




      :param `label`: Text for new choice  
      :type `label`: string
      :param `index`: Insertion position. Use ``wx.NOT_FOUND`` to append.  
      :type `index`: int
      :param `value`: Value for new choice. Do not specify if you wish this to equal choice index.   
      :type `value`: int










      :rtype: `int`



                  





   .. method:: IntToValue(self, number, argFlags=0)

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




      :param `number`: Integer to be translated into variant.   
      :type `number`: int
      :param `argFlags`: If ``wx.propgrid.PG_FULL_VALUE`` is set, returns complete, storable value instead of displayable one.  
      :type `argFlags`: int










      :rtype: `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).  











   .. method:: IsCategory(self)

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

      :rtype: `bool`








   .. method:: IsEnabled(self)

      Returns ``True`` if property is enabled.                  

      :rtype: `bool`








   .. method:: IsExpanded(self)

      Returns ``True`` if property has visible children.                  

      :rtype: `bool`








   .. method:: IsRoot(self)

      Returns ``True`` if this property is actually a RootProperty.                  

      :rtype: `bool`








   .. method:: IsSomeParent(self, candidateParent)

      Returns ``True`` if candidateParent is some parent of this property.                  


      :param `candidateParent`: 
      :type `candidateParent`: wx.propgrid.PGProperty




      :rtype: `bool`








   .. method:: IsSubProperty(self)

      Returns ``True`` if this is a sub-property.                  

      :rtype: `bool`








   .. method:: IsTextEditable(self)

      Returns ``True`` if property has editable :ref:`wx.TextCtrl`  when selected.                  

                

      :rtype: `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).   








   .. method:: IsValueUnspecified(self)

      Returns ``True`` if property's value is considered unspecified.                  

      This usually means that value is Null variant.                  

      :rtype: `bool`








   .. method:: IsVisible(self)

      Returns ``True`` if all parents expanded.                  

      :rtype: `bool`








   .. method:: Item(self, i)

      Returns child property at index i.                  


      :param `i`: 
      :type `i`: int




      :rtype: :ref:`wx.propgrid.PGProperty`








   .. method:: 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 :meth:`wx.propgrid.PGProperty.OnMeasureImage`   is overridden as well).                  

      If property's :meth:`OnMeasureImage`   returns size that has height != 0 but less than row height ( < 0 has special meanings), :ref:`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 :meth:`OnMeasureImage`   returned higher height than row height). 

      ``NOTE``: Following applies when :meth:`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. 




      :param `dc`: :ref:`wx.DC`  to paint on.   
      :type `dc`: wx.DC
      :param `rect`: Box reserved for custom graphics. Includes surrounding rectangle, if any. If x is < 0, then this is a measure item call (see above).   
      :type `rect`: wx.Rect
      :param `paintdata`: :ref:`wx.propgrid.PGPaintData`  structure with much useful data about painted item. ::




      :type `paintdata`: wx.propgrid.PGPaintData








                  



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










      .. seealso:: :meth:`ValueToString`     








   .. method:: 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, :ref:`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, :meth:`SetValueInEvent`   should be called to set the new value. 

      The parameter `event`  is the associated :ref:`wx.Event`. 




      :param `propgrid`: 
      :type `propgrid`: wx.propgrid.PropertyGrid
      :param `wnd_primary`: 
      :type `wnd_primary`: wx.Window
      :param `event`: 
      :type `event`: wx.Event




      return ``True`` if any changes in value should be reported. 



      :rtype: `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.  











   .. method:: 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. 




      :param `item`: Normally -1, but can be an index to the property's list of items.  
      :type `item`: int






      :rtype: :ref:`Size`



                  



      .. note:: 

   

         - Default behaviour is to return :ref:`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).  











   .. method:: 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), :meth:`OnSetValue`   will not be called. 
         - m_value may be of any variant type. Typically properties internally support only one variant type, and as such :meth:`OnSetValue`   provides a good opportunity to convert supported values into internal type. 
         - Default implementation does nothing.  











   .. method:: OnValidationFailure(self, pendingValue)

      Called whenever validation has failed with given pending value.                  

                


      :param `pendingValue`: 
      :type `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.   








   .. method:: RefreshChildren(self)

      Refresh values of child properties.                  

      Automatically called after value is set.                   





   .. method:: RefreshEditor(self)

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





   .. method:: SetAttribute(self, name, value)

      Sets an attribute for this property.                  




      :param `name`: Text identifier of attribute. See :ref:`PropertyGrid Property Attribute Identifiers <propertygrid property attribute identifiers>`.  
      :type `name`: string
      :param `value`: Value of attribute.  
      :type `value`: PGVariant






                  



      .. note:: 

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








   .. method:: SetAttributes(self, attributes)

      Set the property's attributes from a Python dictionary.



   .. method:: 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: :ref:`wx.propgrid.IntProperty`, :ref:`wx.propgrid.UIntProperty`, :ref:`wx.propgrid.FloatProperty`, :ref:`wx.propgrid.EditEnumProperty`. 




      :param `enable`: Whether to enable or disable this behaviour (it is disabled by default).   
      :type `enable`: bool




                  





   .. method:: SetBackgroundColour(self, colour, flags=PG_RECURSE)

      Sets property's background colour.                  




      :param `colour`: Background colour to use.  
      :type `colour`: wx.Colour
      :param `flags`: 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.   
      :type `flags`: int






                  





   .. method:: SetCell(self, column, cell)

      Sets cell information for given column.                  


      :param `column`: 
      :type `column`: int
      :param `cell`: 
      :type `cell`: wx.propgrid.PGCell







   .. method:: 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.                  


      :param `newValue`: 
      :type `newValue`: int







   .. method:: SetChoices(self, choices)

      Sets new set of choices for the property.                  

                


      :param `choices`: 
      :type `choices`: wx.propgrid.PGChoices




      :rtype: `bool`







      .. note:: 

         This operation deselects the property and clears its value.   








   .. method:: SetClientData(self, data)

      Returns client object of a property.                  


      :param `data`: 
      :type `data`: ClientData







   .. method:: SetClientObject(self, n, data)

      Alias for :meth:`SetClientData`



   .. method:: SetDefaultValue(self, value)

      Set default value of a property.                  

      Synonymous to 

      ::

          theProperty.SetAttribute("DefaultValue", value)

                 


      :param `value`: 
      :type `value`: PGVariant







   .. method:: SetEditor(self, *args, **kw)



      |overload| Overloaded Implementations:

      **~~~**

      
      **SetEditor** `(self, editor)`
      
      Sets editor for a property.                  
      
      
      
      
      :param `editor`: For builtin editors, use PGEditor_X, where X is builtin editor's name (TextCtrl, Choice, etc. see :ref:`wx.propgrid.PGEditor`  documentation for full list).  
      :type `editor`: wx.propgrid.PGEditor
      
      
      
      
      :meth:`wx.propgrid.PropertyGrid.RegisterEditorClass` .                   
      
      
      
      
      **~~~**

      
      **SetEditor** `(self, editorName)`
      
      Sets editor for a property, by editor name.                  
      
      
      :param `editorName`: 
      :type `editorName`: string
      
      
      
      
      
      
      **~~~**






   .. method:: SetFlagRecursively(self, flag, set)

      Sets or clears given property flag, recursively.                  

      This function is primarily intended for internal use. 

                


      :param `flag`: 
      :type `flag`: wx.propgrid.PGPropertyFlags
      :param `set`: 
      :type `set`: bool






      .. seealso:: :meth:`ChangeFlag`     








   .. method:: SetHelpString(self, helpString)

      Sets property's help string, which is shown, for example, in :ref:`wx.propgrid.PropertyGridManager`'s description text box.                  


      :param `helpString`: 
      :type `helpString`: string







   .. method:: SetLabel(self, label)

      Sets property's label.                  

                


      :param `label`: 
      :type `label`: string






      .. note:: 

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








   .. method:: SetMaxLength(self, maxLen)

      Set max length of text in text editor.                  


      :param `maxLen`: 
      :type `maxLen`: int




      :rtype: `bool`








   .. method:: SetModifiedStatus(self, modified)

      Sets property's "is it modified?" flag.                  

      Affects children recursively.                  


      :param `modified`: 
      :type `modified`: bool







   .. method:: SetName(self, newName)

      Sets new (base) name for property.                  


      :param `newName`: 
      :type `newName`: string







   .. method:: SetParentalType(self, flag)

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




      :param `flag`: 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).  
      :type `flag`: int




                  



      .. note:: 

         You generally do not need to call this function.   








   .. method:: SetTextColour(self, colour, flags=PG_RECURSE)

      Sets property's text colour.                  




      :param `colour`: Text colour to use.  
      :type `colour`: wx.Colour
      :param `flags`: 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.   
      :type `flags`: int






                  





   .. method:: SetValidator(self, validator)

      Sets :ref:`wx.Validator`  for a property.                  


      :param `validator`: 
      :type `validator`: wx.Validator







   .. method:: SetValue(self, value, pList=None, flags=PG_SETVAL_REFRESH_EDITOR)

      Call this to set value of the property.                  

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


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




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








                  



      .. note:: 

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








   .. method:: SetValueFromInt(self, value, flags=0)

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

      Default behaviour is to do nothing. 




      :param `value`: Int to get the value from.   
      :type `value`: long
      :param `flags`: If has ``wx.propgrid.PG_FULL_VALUE``, then the value given is a actual value and not an index.  
      :type `flags`: int








      :rtype: `bool`



                  



      :returns: 

         ``True`` if value was changed.   








   .. method:: SetValueFromString(self, text, flags=0)

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

      Default behaviour is to do nothing. 




      :param `text`: String to get the value from.   
      :type `text`: string
      :param `flags`: 
      :type `flags`: int








      :rtype: `bool`





                 



      :returns: 

         ``True`` if value was changed.   







      .. todo:: docme   








   .. method:: SetValueImage(self, bmp)

      Set :ref:`wx.Bitmap`  in front of the value.                  

      This bitmap may be ignored by custom cell renderers.                  


      :param `bmp`: 
      :type `bmp`: wx.Bitmap







   .. method:: SetValueInEvent(self, value)

      Call this function in :meth:`OnEvent` , OnButtonClick() etc.                  

      to change the property value based on user input. 

                


      :param `value`: 
      :type `value`: PGVariant






      .. note:: 

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








   .. method:: SetValuePlain(self, value)

      Helper for language bindings.                  


      :param `value`: 
      :type `value`: PGVariant







   .. method:: SetValueToUnspecified(self)

      Sets property's value to unspecified (ie.                  

      Null variant).                   





   .. method:: SetWasModified(self, set=True)

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

      cancel ``True`` returned by :meth:`StringToValue`   or :meth:`IntToValue` ).                  


      :param `set`: 
      :type `set`: bool







   .. method:: StringToValue(self, text, argFlags=0)

      Converts text into :ref:`Variant`  value appropriate for this property.                  




      :param `text`: Text to be translated into variant.  
      :type `text`: string
      :param `argFlags`: 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 :meth:`ValueToString`   called with this same flag).  
      :type `argFlags`: int










      :rtype: `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.  








   .. method:: UpdateParentValues(self)

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

      Returns topmost property updated.                  

      :rtype: :ref:`wx.propgrid.PGProperty`








   .. method:: UsesAutoUnspecified(self)

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

      :rtype: `bool`








   .. method:: 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. 

                


      :param `value`: 
      :type `value`: PGVariant
      :param `validationInfo`: 
      :type `validationInfo`: wx.propgrid.PGValidationInfo




      :rtype: `bool`







      .. note:: 

   

         - Default implementation always returns ``True``.  











   .. method:: ValueToString(self, value, argFlags=0)

      Converts property value into a text representation.                  




      :param `value`: Value to be converted.   
      :type `value`: PGVariant
      :param `argFlags`: 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.  
      :type `argFlags`: int








      :rtype: `string`



                  



      .. note:: 

         Default implementation calls :meth:`GenerateComposedValue` .   








   .. attribute:: m_clientData

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


   .. attribute:: m_value

      See :meth:`~wx.propgrid.PGProperty.GetValue` and :meth:`~wx.propgrid.PGProperty.SetValue`

