.. _howto_svg_synoptics:

Create a basic SVG synoptic
===========================

SVG synoptics provide an interactive graphical representation of a control
system. Taurus can be connected to SVG synoptics through the external
`svgsynoptic <https://gitlab.com/MaxIV/lib-maxiv-svgsynoptic>`_ library.

This guide shows the minimum setup for displaying Taurus models in an SVG
synoptic. For a conceptual introduction, see :doc:`../explanation/synoptics`.

Install the requirements
------------------------

You need Taurus, a Qt binding, and ``svgsynoptic``. Inkscape is also useful for
editing SVG files, although any SVG editor can be used.

Create the synoptic widget
--------------------------

A Taurus-aware synoptic is based on ``TaurusSynopticWidget``. The widget model
is the HTML page that hosts the SVG::

    import os

    from taurus.external.qt import Qt
    from svgsynoptic2.taurussynoptic import TaurusSynopticWidget


    class ExampleSynopticWidget(TaurusSynopticWidget):
        pass


    app = Qt.QApplication([])
    path = os.path.dirname(__file__)

    widget = ExampleSynopticWidget()
    widget.setModel(os.path.join(path, "index.html"))
    widget.resize(1000, 700)
    widget.show()

    app.exec_()

The exact import path may depend on the installed ``svgsynoptic`` version. See
its documentation if ``TaurusSynopticWidget`` is exposed from a different
module.

Associate SVG elements with Taurus models
-----------------------------------------

Edit the SVG with Inkscape and add a model to the object's description using
this syntax::

    model=sys/tg_test/1

or, for an attribute::

    model=sys/tg_test/1/double_scalar

The library stores this information in the SVG ``<desc>`` element and uses it
to connect the graphical object to the Taurus model.

Typical behavior is:

* a text element with an attribute model displays the live attribute value;
* an element with a Tango device model is colored according to the device
  state;
* scalar attribute values, qualities, and boolean values can be represented
  using CSS styles;
* right-clicking a device normally opens a ``TaurusDevicePanel``.

Since the models are normal Taurus models, other schemes can also be used. For
example, an evaluated model can combine two attributes::

    model=eval:{sys/tg_test/1/float_scalar} + {sys/tg_test/1/short_scalar}

See :doc:`evaluated_models` for more information about ``eval:`` models.

Style live values with CSS
--------------------------

The synoptic applies CSS classes and data attributes according to model values
and qualities. This makes it possible to change appearance without modifying
the Python application.

For example, a CSS class can define a fill color::

    .red {
        fill: red;
    }

Avoid hard-coding a fill color directly on SVG elements that should be styled
from CSS, because an inline SVG style may override the CSS rule.

Customize interactions
----------------------

``TaurusSynopticWidget`` provides default interaction with Taurus models. For
example, device models can open a generic device panel on right click.

For application-specific behavior, subclass the widget and override the
relevant handlers. The training material includes examples for custom click
handlers, Tango commands, and custom device popups.

Further training
----------------

The `Taurus training SVG synoptic material
<https://gitlab.com/taurus-org/taurus-training>`_ contains a complete hands-on
workshop covering:

* HTML/SVG/CSS structure;
* live updates and interactions;
* Tango devices and attributes;
* custom device widgets;
* layers and zoom levels;
* groups and clones;
* larger production-style examples.

For general information about synoptics in Taurus and TaurusGUI, see
:doc:`../explanation/synoptics` and :doc:`taurusgui`.