.. |parameter-button| image:: /medias/desktop/choregraphe/parameter_button.png :class: img-inline .. _choregraphe-reference-box: Box ==== What is a box ------------- .. image:: /medias/desktop/choregraphe/box.png A box is a fundamental object in Choregraphe as everything you manipulate with this software rests on boxes. A box can be a **simple elementary action** (Say box for example) as well as a **very complex application** (room exploration for example). However it is the **basic element** to create :ref:`behaviors `. .. note:: You can have a **description** and some tips about a box in the lower part of the box library panel when you select the box in the :ref:`choregraphe-overview-box-libary-panel` or in a tooltip displayed by passing above the box in the :ref:`choregraphe-overview-flow-diagram-panel`. Inputs/outputs ++++++++++++++++ In order to **communicate** with other boxes and to be **started** or **stopped**, a box has :ref:`inputs ` (on the left side) and :ref:`outputs ` (on the right). The inputs and outputs of boxes are then connected through **links** on an event based communication logic. 3 types of boxes ++++++++++++++++ There are three different **types of box**: * :ref:`choregraphe-reference-box-type-script` which includes a :ref:`script `. * :ref:`choregraphe-reference-box-type-flow-diagram` which includes a :ref:`script ` and a :ref:`flow diagram `. * :ref:`choregraphe-reference-box-type-timeline` which includes a :ref:`script ` and a :ref:`timeline `. Optional components ++++++++++++++++++++ If you want to change or create some settings about the action made by a box, it may be useful to have a look at its :ref:`parameters `. For example, the ``Say`` box has a voice shape parameter which changes the voice used by NAO to say the text. A box may need some additional files (a music for a dance for example). In order to package the box with its needed files, you can :ref:`attach them ` to the box. A box may also use :ref:`resources ` to **manage conflicts** with other boxes which could use the same resources. For example a box to walk and a box to dance both use NAO's legs. Finally a box can have a :ref:`plugin ` which basically enables you to make actions directly on the frontage of the box. .. TODO Add a page about standard coding conventions for Choregraphe/boxes .. _choregraphe-detailed-interface-box-edition: Box Edition widget ------------------- When you **edit** or **create** a :ref:`box `, the following widget is displayed: .. image:: /medias/desktop/choregraphe/chore_edit_box.png You can here set: * the **name** of your box. * the brief **description** of what it does in the field **Tooltip**. .. note:: This description will appear in the **lower part of the box library panel** when you select the box in the box library or in a tooltip displayed by **passing above the box** in the flow diagram. * its **image** in the field **Image** by clicking on **Edit** and selecting one or several images for your box. The image will then be displayed on the front of your box in the flow diagram. .. note:: You can choose several images to have a complete graphical description of what it does. But you should know that only the first image will be displayed beside the box name in a box library. You can also **add**, **edit** or **remove** :ref:`inputs `, :ref:`outputs ` and :ref:`parameters ` to the box: .. list-table:: :widths: 5 100 * - .. image:: /medias/desktop/choregraphe/del.png - **Remove** the selected input, output or parameter. * - .. image:: /medias/desktop/choregraphe/edit.png - **Edit** the selected input, output or parameter. This action will open an :ref:`input, output or parameter edition widget ` where you will be able to set the properties of the input, output or parameter. * - .. image:: /medias/desktop/choregraphe/add.png - **Add** a new input, output or parameter. This action will open an :ref:`input, output or parameter edition widget ` where you will be able to set the properties of the input, output or parameter. Finally you can choose the **type** of your box: :ref:`Script `, :ref:`Timeline ` or :ref:`Flow diagram `. On the top right of the widget, a second tab named **Advanced** enables you to access to **advanced options** for the box. You can there choose a :ref:`plugin ` for your box.