SVG Widget
**********

The SVG widget allows rendering an SVG file in a taranta dashboard. A Taranta dashboard can include an SVG widget just like any other widget. Using SVG, the user can create custom designs and layouts based on specific needs.
Over time, the user can change the SVG as required. The SVG content can be dynamically changed as needed, either by uploading a file or by providing a URL.

Widget setting 
==============

The following image shows an example of a widget setting.

\ |IMG1|\ 

It is possible to customize the widget settings from the inspector panel (in edit mode), as shown below:

+---------------------+------------------------------------------------------------------------+
|Input value          |Description                                                             |
+=====================+========================================================================+
|Title                |Sets the title displayed for the widget                                 |
+---------------------+------------------------------------------------------------------------+
|Select Source        |Choose the source of the SVG; either SVG File or SVG URL. Based on this | 
|                     |selection, the widget will display the uploaded file or load the SVG    |
|                     |from the specified URL                                                  |
+---------------------+------------------------------------------------------------------------+
|SVG File             |Where you can upload the SVG file. In this case, clicking Browse will   |
|                     |open a window that allows you to upload only SVG files from your file   |
|                     |system. Once uploaded, the name of the loaded file will appear. Only    |
|                     |shown if SVG File is selected as the source                             |
+---------------------+------------------------------------------------------------------------+
|SVG Uploaded         |Shows the name of svg file which is uploaded by user to the widget      |
+---------------------+------------------------------------------------------------------------+
|SVG URL              |Enter the full URL to an external SVG file. This input is shown only    |
|                     |when SVG URL is selected as source                                      |
+---------------------+------------------------------------------------------------------------+
|Custom CSS           |Write custom CSS for the widget container. The syntax is the same as    |
|                     |standard CSS used in HTML files                                         |
+---------------------+------------------------------------------------------------------------+


.. _create-svg-file:

Creating SVG file using Inkscape
--------------------------------

The user can create an SVG file using any SVG editor, in our case it´s :ref:`inkscape-label`.
The created SVG is static, to make it dynamic, the SVG elements need to be linked to tango devices or attributes. This linking process can be done through Inkscape. Follow :ref:`link-devices-on-svg`
for linking devices and attributes to the SVG.  

SVG Widget in run mode
----------------------

Once the SVG file is ready, it can be uploaded from the widget configuration (SVG File). After uploading the file to the
SVG Widget, it will render in the widget area. To see the actual device status and attribute values, the user
has to switch to run mode by clicking the run button. All SVG elements that are linked to a device or device status will
change their color depending on the device status. The mapping of device status to color can be seen
`here <https://tango-controls.readthedocs.io/en/latest/tools-and-extensions/built-in/atk/atk.html#devstate-scalar-attributes>`_,
at present, this is not customizable. SVG elements that are linked to device attributes will
pull real time attribute values and display them as shown below. SVG elements that are not linked to any device will render
as they are.


\ |IMG3|\ 


This widget gives the user capability to create a custom design for the dashboard, hence, the SVG file design can
be as simple or as complex as required. An SVG demonstrating the device status across different devices can be seen below:

\ |IMG4|\ 


.. bottom of content

.. |IMG1| image:: _static/img/svg_widget_inspector.png

.. |IMG3| image:: _static/img/svg-run-mode.png

.. |IMG4| image:: _static/img/svg-example.png