.. |parameter-button| image:: /medias/desktop/choregraphe/parameter_button.png
   :class: img-inline


.. _choregraphe-reference:
.. _choregraphe-reference-loading-unloading:

Loading, unloading, starting and stopping a behavior, a box, a diagram or a timeline
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Behavior
   When a :ref:`behavior <choregraphe-reference-behavior>` is **loaded**:

   #. All :ref:`boxes <choregraphe-reference-box>` contained in the behavior are **constructed**.
      So the constructor of each box ``__init__`` is called.
   #. Its :ref:`diagram <choregraphe-reference-box-flow-diagram>` is **loaded**.

   When it is **unloaded**:

   #. Its :ref:`diagram <choregraphe-reference-box-flow-diagram>` is **unloaded**.
   #. All :ref:`boxes <choregraphe-reference-box>` contained in the behavior are **destroyed**.

   When it is **started** (or **played**):

   #. The behavior is **loaded**.
   #. Its **onStart** :ref:`input <choregraphe-reference-box-input>` is **stimulated**.

   When it is **stopped**, it is **unloaded**.

Box
   When a :ref:`box <choregraphe-reference-box>` is **loaded**, the ``onLoad`` function of its :ref:`script <choregraphe-reference-box-script>` is called.
   For further details about this kind of built-in functions, see the section: :ref:`choregraphe-reference-box-script-built-in-functions`.

   When it is **unloaded**:

   #. The ``onUnload`` function of its :ref:`script <choregraphe-reference-box-script>` is called.
   #. Its :ref:`diagram <choregraphe-reference-box-flow-diagram>` or its :ref:`timeline <choregraphe-reference-box-timeline>` is **unloaded**.

   When it is **started** (with an **onStart** :ref:`input <choregraphe-reference-box-input>`):

   #. The ``onInput_<input_name>`` function of its :ref:`script <choregraphe-reference-box-script>` is called.
   #. Its :ref:`diagram <choregraphe-reference-box-flow-diagram>` or its :ref:`timeline <choregraphe-reference-box-timeline>` is **loaded**.
   #. If it is a :ref:`flow diagram box <choregraphe-reference-box-type-flow-diagram>`, then the signal received on the **onStart** input is transmitted to the :ref:`diagram <choregraphe-reference-box-flow-diagram>` of the box.

      If it is a :ref:`timeline box <choregraphe-reference-box-type-timeline>`, then its :ref:`time cursor <choregraphe-reference-box-timeline-time-cursor>` is played.
      So it starts being regularly incremented.

   When it is **started** but its :ref:`resources <choregraphe-reference-box-resource>` are not available and even after the timeout specified they are still unavailable:

   * If a function named ``onResourceError`` is defined in the :ref:`box script <choregraphe-reference-box-script>`, it is called.
   * Else, the :ref:`output <choregraphe-reference-box-output>` named ``onStopped`` is stimulated (if any).

   When it is **stopped** with an **onStop** :ref:`input <choregraphe-reference-box-input>`:

   #. The ``onInput_<input_name>`` function of its :ref:`script <choregraphe-reference-box-script>` is called.
   #. Its :ref:`diagram <choregraphe-reference-box-flow-diagram>` or its :ref:`timeline <choregraphe-reference-box-timeline>` is **unloaded**.

   When it is **stopped** with an **onStopped** :ref:`output <choregraphe-reference-box-output>`:

   #. Its :ref:`diagram <choregraphe-reference-box-flow-diagram>` or its :ref:`timeline <choregraphe-reference-box-timeline>` is **unloaded**.
   #. The signal received on the **onStopped** output is transmitted to the parent :ref:`diagram <choregraphe-reference-box-flow-diagram>`.

   When it is **stopped** because its :ref:`resources <choregraphe-reference-box-resource>` are set to **Stop on demand** and they are asked by another box:

   #. If a function named ``onResourceLost`` is defined in the :ref:`box script <choregraphe-reference-box-script>`, it is called.
   #. The :ref:`diagram <choregraphe-reference-box-flow-diagram>` or the :ref:`timeline <choregraphe-reference-box-timeline>` of the box is **unloaded**.
   #. If there was no ``onResourceLost`` function defined in the script, the :ref:`output <choregraphe-reference-box-output>` named ``onStopped`` is stimulated (if any).

   .. note::
      Sometimes it can take some time for a behavior to stop.
      For instance, if NAO is walking, the "Walk" behavior you want to stop will wait for NAO's feet to be stable before stopping, so that the robot doesn't fall down.

Flow diagram
   When a :ref:`diagram <choregraphe-reference-box-flow-diagram>` is **loaded**:

   #. The :ref:`boxes <choregraphe-reference-box>` within the diagram are **loaded**.
   #. The **links** between these boxes are activated.
      Note that before this step the stimulation of any :abbr:`I/O (input/output)` within the diagram would be unefficient.
   #. The **onLoad** :ref:`input <choregraphe-reference-box-input>` of the diagram (if any) is stimulated.

   When it is **unloaded**:

   #. The **links** between the :ref:`boxes <choregraphe-reference-box>` within the diagram are broken.
      Note that after this step the stimulation of any :abbr:`I/O (input/output)` within the diagram would be unefficient.
   #. These boxes are **unloaded**.

Timeline
   When a :ref:`timeline <choregraphe-reference-box-timeline>` is **loaded**:

   #. The :ref:`time cursor <choregraphe-reference-box-timeline-time-cursor>` is set to the :ref:`start frame <choregraphe-reference-box-frame-start>`.
   #. The :ref:`diagrams <choregraphe-reference-box-flow-diagram>` of the :ref:`behavior keyframes <choregraphe-reference-box-behavior-keyframe>` present on this frame are **loaded**.

   When it is **unloaded**:

   #. The :ref:`time cursor <choregraphe-reference-box-timeline-time-cursor>` is paused.
      So it stops being incremented.
   #. The :ref:`diagrams <choregraphe-reference-box-flow-diagram>` of the :ref:`behavior keyframes <choregraphe-reference-box-behavior-keyframe>` present on this frame are **unloaded**.
   #. The :ref:`time cursor <choregraphe-reference-box-timeline-time-cursor>` is set to -1.