.. _blender props:

Interactive plotting and Blender properties
===========================================

Suppose we want to control parameters with Blender's GUI instead of code.
Here is the most basic example:

.. literalinclude:: ../../../../examples/blender/docs/props_basic.py

If we adjust any of the *Blender properties* `a`, `b`, `c`, `d`, Blender will execute the callback `print_props`, which just prints their values to the console.

For more interesting examples involving geometric objects, we could replace `print_props` by a function that links Blender objects.
Instead, we will do something more sophisticated to ensure caching of the possibly expensive callback.

First we write a function `blender_objects` that returns a *sequence of unlinked Blender objects*.
This means that we need to pass `link=False` to `to_blender_object`.

.. literalinclude:: ../../../../examples/blender/docs/props.py
   :lines: 1-31

Then we add the properties.

.. literalinclude:: ../../../../examples/blender/docs/props.py
   :lines: 34, 43-50

The `callback` function will link the output of `blender_objects` to a Blender collection named `"construction"`.
This collection will also serve as a cache which you can clear at will.
Alternatively, `callback` could clear the collection before linking new objects:

.. literalinclude:: ../../../../examples/blender/docs/props.py
   :lines: 47, 43-50

Or overwrite the collection:

.. literalinclude:: ../../../../examples/blender/docs/props.py
   :lines: 41, 43-50

It is possible to switch callbacks on the fly.
Simply run `add_props_with_callback` with a new callback.

Saving and reloading .blend files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Since closing Blender loses all Python state, the callback will no longer exist after saving and reloading a .blend file.
To fix this, run the script again.
Afterwards the callback will work as expected.

Animating properties
~~~~~~~~~~~~~~~~~~~~

Properties can be keyframed and interpolated.
Since animations are likely to be replayed multiple times, it is highly recommended to use `hide_callback` or `overwrite_callback` to cache the results.

.. _advanced props:

Finer control over properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you want to set the description, minimum or maximum value of a property and more, you'll have to define the properties yourself:

.. literalinclude:: ../../../../examples/blender/docs/props.py
   :lines: 52-62

Consult the Blender documentation for all the options.
The callback code remains the same.