[Bf-blender-cvs] [78080337f89] master: PyDoc: expanded documentation for bpy_struct.is_property_set
Campbell Barton
noreply at git.blender.org
Tue Dec 8 10:53:18 CET 2020
Commit: 78080337f8994e685c1190190b4e37d8409b31a5
Author: Campbell Barton
Date: Tue Dec 8 20:51:48 2020 +1100
Branches: master
https://developer.blender.org/rB78080337f8994e685c1190190b4e37d8409b31a5
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
===================================================================
A doc/python_api/examples/bpy.types.bpy_struct.is_property_set.py
===================================================================
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.
+"""
More information about the Bf-blender-cvs
mailing list