.. highlight:: python
   :linenothreshold: 6

.. currentmodule:: taurus.qt.qtgui

.. _examples:

Build your first Taurus GUI in Python
=====================================

This tutorial introduces the basic Taurus GUI building blocks by progressively
creating a small interface for a Tango device. You will start by displaying a
single attribute and then move to editable values and :class:`panel.TaurusForm`.

.. _examples_setup:

Set up the example device
-------------------------

The device server used for the examples can be obtained
:download:`here <../_examples/TaurusTest.py>`.

For the examples to work as provided, create and run a TaurusTest device with
the following configuration:

``Server (ServerName/Instance):``
  TaurusTest/taurustest
``Class:``
  TaurusTest
``Devices:``
  sys/taurustest/1

You can configure it from Jive by going to ``Edit -> Create server`` and
entering the parameters above.

.. _examples_common:

Create the application window
-----------------------------

Start with a minimal Qt application and a horizontal layout::

    import sys
    from taurus.external.qt import Qt
    from taurus.qt.qtgui.application import TaurusApplication

    app = TaurusApplication(sys.argv, cmd_line_parser=None)
    panel = Qt.QWidget()
    layout = Qt.QHBoxLayout()
    panel.setLayout(layout)

The following examples only show the code that changes. Unless otherwise
stated, add the snippets between the code above and this common footer::

    panel.show()
    sys.exit(app.exec_())

.. _examples_display_attribute_value:

Display an attribute value
--------------------------

A :class:`display.TaurusLabel` can display a Tango attribute value. Add the
following code before the common footer::

    from taurus.qt.qtgui.display import TaurusLabel

    w = TaurusLabel()
    layout.addWidget(w)
    w.model = "sys/taurustest/1/position#rvalue.magnitude"

.. image:: /_static/label01.png
   :align: center

If the ``#rvalue.magnitude`` fragment is omitted from the model, the units are
also displayed when they are defined by the attribute.

Add the attribute label
-----------------------

Use the ``#label`` fragment to display the Tango label next to the value::

    from taurus.qt.qtgui.display import TaurusLabel

    w1, w2 = TaurusLabel(), TaurusLabel()
    layout.addWidget(w1)
    layout.addWidget(w2)
    w1.model, w1.bgRole = "sys/taurustest/1/position#label", ""
    w2.model = "sys/taurustest/1/position#rvalue.magnitude"

.. image:: /_static/label02.png
   :align: center

Add separate units
------------------

Taurus model fragments let different widgets display different parts of the
same attribute model. Extend the previous example with a third label::

    from taurus.qt.qtgui.display import TaurusLabel

    w1, w2, w3 = TaurusLabel(), TaurusLabel(), TaurusLabel()
    layout.addWidget(w1)
    layout.addWidget(w2)
    layout.addWidget(w3)

    w1.model, w1.bgRole = "sys/taurustest/1/position#label", ""
    w2.model = "sys/taurustest/1/position#rvalue.magnitude"
    w3.model, w3.bgRole = "sys/taurustest/1/position#rvalue.units", ""

.. image:: /_static/label03.png
   :align: center

The interface now displays the attribute label, its current value, and its
units independently.

Make the value editable
-----------------------

To let the user change the attribute, add a Taurus input widget for the write
value. For example::

    from taurus.qt.qtgui.display import TaurusLabel
    from taurus.qt.qtgui.input import TaurusValueLineEdit

    w1 = TaurusLabel()
    w2 = TaurusLabel()
    w3 = TaurusValueLineEdit()
    w4 = TaurusLabel()

    layout.addWidget(w1)
    layout.addWidget(w2)
    layout.addWidget(w3)
    layout.addWidget(w4)

    w1.model, w1.bgRole = "sys/taurustest/1/position#label", ""
    w2.model = "sys/taurustest/1/position#rvalue.magnitude"
    w3.model = "sys/taurustest/1/position#wvalue.magnitude"
    w4.model, w4.bgRole = "sys/taurustest/1/position#rvalue.units", ""

.. figure:: /_static/edit01.png
   :align: center

   Editing the write value with ``TaurusValueLineEdit``.

Other Taurus input widgets, such as :class:`input.TaurusValueSpinBox` and
:class:`input.TaurusWheelEdit`, can be used in the same way.

Use a TaurusForm for several attributes
---------------------------------------

Creating individual widgets becomes tedious when you need to display many
attributes. :class:`panel.TaurusForm` provides a higher-level interface that
selects suitable widgets for the models it receives.

For this step, replace the generic ``panel`` created earlier with a
``TaurusForm``::

    from taurus.qt.qtgui.panel import TaurusForm

    panel = TaurusForm()
    props = ["state", "status", "position", "velocity", "acceleration"]
    model = ["sys/taurustest/1/%s" % p for p in props]
    panel.setModel(model)

.. image:: /_static/forms01.png
   :align: center

The form aligns the rows, manages write operations, and chooses appropriate
widgets according to each model.

Customize the form
------------------

You can override the automatically selected widgets for individual rows::

    from taurus.qt.qtgui.display import TaurusLabel

    panel[0].readWidgetClass = TaurusLabel
    panel[2].writeWidgetClass = "TaurusWheelEdit"

.. image:: /_static/forms02.png
   :align: center

You can also customize the appearance with Qt stylesheets::

    panel.setStyleSheet("font-size: 40px;")

The recommended way to change the style is to use ``setStyleSheet`` on the
``TaurusForm`` (or another top-level widget). If you need to style a specific
widget inside a ``TaurusValue``, use Qt methods directly::

    from taurus.external.qt import Qt

    for row in panel:
        row.readWidget().setFont(Qt.QFont("Sans Serif", 40))

For more detailed form customization options, see :doc:`../howto/forms`.

Next steps
----------

You now have a small Taurus application that can display and edit live Tango
attributes and can scale from individual widgets to a complete form.

Continue with :doc:`plotting` to add live plots and trends, or see
:doc:`taurusgui` to build a larger application using the TaurusGUI framework.