======================
User interface widgets
======================

Taurus provides a collection of Qt widgets for displaying, editing, selecting,
and organizing Taurus models. This page is a quick reference to the most common
user interface components and where to find their detailed documentation.

For examples and task-oriented instructions, see :doc:`How-to guides
<../howto/index>`. For the complete Python API, see :doc:`Python API
<api/index>`.

Application and containers
==========================

.. list-table::
    :header-rows: 1
    :widths: 24 50 26

    * - Widget
      - Purpose
      - API
    * - ``TaurusApplication``
      - Taurus-aware Qt application class used to initialize GUI applications.
      - :class:`~taurus.qt.qtgui.application.TaurusApplication`
    * - ``TaurusWidget``
      - General-purpose Taurus-aware widget and base container.
      - :class:`~taurus.qt.qtgui.container.TaurusWidget`
    * - ``TaurusFrame``
      - Frame container that can be associated with a Taurus model.
      - :class:`~taurus.qt.qtgui.container.TaurusFrame`
    * - ``TaurusGroupBox``
      - Group-box container with Taurus model support.
      - :class:`~taurus.qt.qtgui.container.TaurusGroupBox`
    * - ``TaurusMainWindow``
      - Taurus-aware main window with support for persistent configuration.
      - :class:`~taurus.qt.qtgui.container.TaurusMainWindow`
    * - ``TaurusDiagnosticsDialog``
      - Inspects live process, device, attribute, listener, and event information.
      - :class:`API <taurus.qt.qtgui.panel.TaurusDiagnosticsDialog>`;
        :doc:`how-to <../howto/diagnostics>`

Display widgets
===============

.. list-table::
    :header-rows: 1
    :widths: 24 50 26

    * - Widget
      - Purpose
      - API
    * - ``TaurusLabel``
      - Displays a model value, label, state, quality, or other model-related text.
      - :class:`~taurus.qt.qtgui.display.TaurusLabel`
    * - ``TaurusLed``
      - LED-style indicator for boolean or state-like values.
      - :class:`~taurus.qt.qtgui.display.TaurusLed`
    * - ``TaurusLCD``
      - LCD-style numeric display.
      - :class:`~taurus.qt.qtgui.display.TaurusLCD`
    * - ``QPixmapWidget``
      - Displays a pixmap while preserving its aspect ratio.
      - :class:`~taurus.qt.qtgui.display.QPixmapWidget`

Input widgets
=============

.. list-table::
    :header-rows: 1
    :widths: 24 50 26

    * - Widget
      - Purpose
      - API
    * - ``TaurusValueLineEdit``
      - Line editor for writing scalar attribute values.
      - :class:`~taurus.qt.qtgui.input.TaurusValueLineEdit`
    * - ``TaurusValueSpinBox``
      - Spin box for editing numeric attribute values.
      - :class:`~taurus.qt.qtgui.input.TaurusValueSpinBox`
    * - ``TaurusValueCheckBox``
      - Check box for boolean attributes.
      - :class:`~taurus.qt.qtgui.input.TaurusValueCheckBox`
    * - ``TaurusValueComboBox``
      - Combo box for selecting among a predefined set of values.
      - :class:`~taurus.qt.qtgui.input.TaurusValueComboBox`
    * - ``TaurusWheelEdit``
      - Wheel-style editor for numeric values.
      - :class:`~taurus.qt.qtgui.input.TaurusWheelEdit`

Forms and model selection
=========================

.. list-table::
    :header-rows: 1
    :widths: 24 50 26

    * - Widget
      - Purpose
      - Documentation
    * - ``TaurusForm``
      - Dynamically builds a form for a list of Taurus models.
      - :class:`API <taurus.qt.qtgui.panel.TaurusForm>`; :doc:`how-to <../howto/forms>`
    * - ``TaurusValue``
      - Composite row used by forms to present label, read, write, and units widgets.
      - :class:`~taurus.qt.qtgui.panel.TaurusValue`
    * - ``TaurusModelChooser``
      - Lets users browse and select Taurus models.
      - :class:`API <taurus.qt.qtgui.panel.TaurusModelChooser>`; :doc:`how-to <../howto/model_chooser>`
    * - ``TaurusModelList``
      - Displays and edits a list of Taurus model names.
      - :class:`~taurus.qt.qtgui.panel.TaurusModelList`
    * - ``TaurusModelSelectorTree``
      - Tree-based model selector.
      - :class:`~taurus.qt.qtgui.panel.TaurusModelSelectorTree`

Tables and trees
================

.. list-table::
    :header-rows: 1
    :widths: 24 50 26

    * - Widget
      - Purpose
      - Documentation
    * - ``TaurusGrid``
      - Organizes Taurus models in a configurable two-dimensional grid.
      - :class:`API <taurus.qt.qtgui.table.TaurusGrid>`; :doc:`how-to <../howto/taurus_grid>`
    * - ``TaurusValuesTable``
      - Displays Taurus values in a table-oriented view.
      - :class:`~taurus.qt.qtgui.table.TaurusValuesTable`
    * - ``TaurusDbTableWidget``
      - Table view for browsing a Taurus database authority.
      - :class:`~taurus.qt.qtgui.table.TaurusDbTableWidget`
    * - ``TaurusDbTreeWidget``
      - Tree view for browsing a Taurus database authority.
      - :class:`~taurus.qt.qtgui.tree.TaurusDbTreeWidget`

Plotting and images
===================

Plotting widgets are provided through optional Taurus plotting integrations.
Their availability depends on the installed plotting plugins.

.. list-table::
    :header-rows: 1
    :widths: 24 50 26

    * - Widget
      - Purpose
      - Documentation
    * - ``TaurusPlot``
      - Displays one-dimensional Taurus data as curves.
      - :doc:`How-to <../howto/plotting>`; :doc:`concepts <../explanation/plotting>`
    * - ``TaurusTrend``
      - Displays the evolution of scalar Taurus values over time.
      - :doc:`How-to <../howto/trends>`; :doc:`concepts <../explanation/trends>`
    * - ``TaurusImageDialog``
      - Displays two-dimensional image attributes.
      - :doc:`How-to <../howto/images>`; :doc:`concepts <../explanation/images>`
    * - ``TaurusTrend2DDialog``
      - Displays the evolution of one-dimensional data as a two-dimensional trend.
      - :doc:`How-to <../howto/trends>`; :doc:`concepts <../explanation/trends>`

Synoptics and complete GUIs
===========================

.. list-table::
    :header-rows: 1
    :widths: 24 50 26

    * - Widget
      - Purpose
      - Documentation
    * - ``TaurusJDrawSynopticsView``
      - Displays legacy JDraw synoptic files connected to Taurus models.
      - :class:`~taurus.qt.qtgui.graphic.TaurusJDrawSynopticsView`
    * - SVG synoptics
      - Interactive SVG-based synoptics using the external ``svgsynoptic`` integration.
      - :doc:`How-to <../howto/svg_synoptics>`; :doc:`concepts <../explanation/synoptics>`
    * - ``TaurusGui``
      - Framework for assembling configurable Taurus applications from panels and tools.
      - :class:`API <taurus.qt.qtgui.taurusgui.TaurusGui>`; :doc:`concepts <../explanation/taurusgui>`