diff options
author | Campbell Barton <ideasman42@gmail.com> | 2020-12-08 12:51:48 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2020-12-08 12:52:31 +0300 |
commit | 78080337f8994e685c1190190b4e37d8409b31a5 (patch) | |
tree | 14f7b8776c39c6aa563ba24fe52ae4be87daf68b | |
parent | 28169cea3d722f699cba2503d3d9d99b096663af (diff) |
PyDoc: expanded documentation for bpy_struct.is_property_set
This patch expands on the `is_property_set` doc-string,
detailing the purpose of the `ghost` argument added in
d3bcbe10c20e8b418659d8fdca98fd6b4bfecdfe.
Reviewed By: sybren
Ref D9780
-rw-r--r-- | doc/python_api/examples/bpy.types.bpy_struct.is_property_set.py | 30 |
1 files changed, 30 insertions, 0 deletions
diff --git a/doc/python_api/examples/bpy.types.bpy_struct.is_property_set.py b/doc/python_api/examples/bpy.types.bpy_struct.is_property_set.py new file mode 100644 index 00000000000..ed566fc3ea8 --- /dev/null +++ b/doc/python_api/examples/bpy.types.bpy_struct.is_property_set.py @@ -0,0 +1,30 @@ +""" +.. note:: + + Properties defined at run-time store the values of the properties as custom-properties. + + This method checks if the underlying data exists, causing the property to be considered *set*. + + A common pattern for operators is to calculate a value for the properties + that have not had their values explicitly set by the caller + (where the caller could be a key-binding, menu-items or Python script for example). + + In the case of executing operators multiple times, values are re-used from the previous execution. + + For example: subdividing a mesh with a smooth value of 1.0 will keep using + that value on subsequent calls to subdivision, unless the operator is called with + that property set to a different value. + + This behavior can be disabled using the ``SKIP_SAVE`` option when the property is declared (see: :mod:`bpy.props`). + + The ``ghost`` argument allows detecting how a value from a previous execution is handled. + + - When true: The property is considered unset even if the value from a previous call is used. + - When false: The existence of any values causes ``is_property_set`` to return true. + + While this argument should typically be omitted, there are times when + it's important to know if a value is anything besides the default. + + For example, the previous value may have been scaled by the scene's unit scale. + In this case scaling the value multiple times would cause problems, so the ``ghost`` argument should be false. +""" |