.. _taurusgrid-howto:

Organize models in a TaurusGrid
===============================

:class:`TaurusGrid` displays a collection of Taurus models in a two-dimensional
layout. Rows and columns are defined using matching rules, and each model is
placed in the first row and column whose rule matches it.

This is useful when several devices expose similar attributes and you want to
present them in a compact matrix instead of a form.

Create a grid
-------------

The following example displays four attributes of ``sys/tg_test/1``::

    from taurus.external.qt import Qt
    from taurus.qt.qtgui.application import TaurusApplication
    from taurus.qt.qtgui.table import TaurusGrid

    app = TaurusApplication(cmd_line_parser=None)
    grid = TaurusGrid()

    grid.setRowLabels("TangoTest:sys/tg_test/1")

    grid.setColumnLabels(
        "Double:double_scalar,"
        "Long:long_scalar,"
        "String:string_scalar,"
        "Boolean:boolean_scalar"
    )

    grid.setModel([
        "sys/tg_test/1/double_scalar",
        "sys/tg_test/1/long_scalar",
        "sys/tg_test/1/string_scalar",
        "sys/tg_test/1/boolean_scalar",
    ])

    grid.resize(900, 250)
    grid.show()

    app.exec()

The resulting layout is conceptually equivalent to::

                 Double          Long          String          Boolean
    TangoTest    double_scalar   long_scalar   string_scalar   boolean_scalar

Define rows and columns
-----------------------

:meth:`TaurusGrid.setRowLabels` and :meth:`TaurusGrid.setColumnLabels` accept
comma-separated rules using the form::

    LABEL:REGEXP

``LABEL`` is the text shown in the row or column header. ``REGEXP`` is matched
against each complete model name to decide where that model belongs.

For example::

    grid.setRowLabels(
        "Test 1:sys/tg_test/1,"
        "Test 2:sys/tg_test/2"
    )

creates two rows. A model containing ``sys/tg_test/1`` is assigned to the
``Test 1`` row, while a model containing ``sys/tg_test/2`` is assigned to
``Test 2``.

Column rules work in exactly the same way::

    grid.setColumnLabels(
        "Scalars:.*_scalar,"
        "Spectra:.*_spectrum"
    )

Here, the visible column names are ``Scalars`` and ``Spectra`` and the second
part of each rule is the regular expression used for classification.

Set the models
--------------

:meth:`TaurusGrid.setModel` provides the actual Taurus models that the grid
will display::

    grid.setModel([
        "sys/tg_test/1/double_scalar",
        "sys/tg_test/1/string_scalar",
    ])

Each model is matched independently against the row rules and the column rules.
The corresponding cell contains a :class:`TaurusValue` connected to that
model.

Matching rules
--------------

Keep the following details in mind when defining row and column rules:

* Matching is case-insensitive.
* TaurusGrid searches the complete model name, so a rule does not need to
  match from the beginning of the string.
* ``*`` is accepted as a convenience wildcard and is converted to ``.*`` when
  needed.
* The first matching rule wins, so put more specific rules before more general
  ones when they overlap.
* Models that do not match any row or column rule are assigned to an
  ``Others`` row or column.

For example, prefer::

    grid.setColumnLabels(
        "Double:double_scalar,"
        "All scalars:scalar"
    )

over the reverse order if ``double_scalar`` should appear specifically in the
``Double`` column.

Show or hide attribute labels
-----------------------------

Each model is represented by a :class:`TaurusValue`, so attribute labels and
units can be shown or hidden independently::

    grid.showAttributeLabels(False)
    grid.showAttributeUnits(False)

The row and column headers remain available to describe the organization of the
grid.

See also
--------

* :class:`TaurusGrid` API reference
* :ref:`forms` for displaying models in a form instead of a matrix
* :ref:`modelchooser` for interactively selecting Taurus models