.. _icon-guide:

=====
Icons
=====

Applications and widgets commonly need icons to represent standard actions,
applications, places, or states such as "open a file", "desktop", or
"preferences".

Qt (and therefore, Taurus) supports `theme icons`_ for many common cases.
You can access them via the standard :meth:`QIcon.fromTheme` method. Using
theme icons helps your application integrate with the rest of the system. Keep in
mind that different people will see the icons differently depending on their default
theme (so do not use a theme icon for something not related to its `specification`_
just because in *your* theme it happens to look like what you want).

Apart from theme icons, Taurus provides its own icon collections, and additional
collections can be registered (see :mod:`taurus.qt.qtgui.icon`). The paths containing these collections are automatically added to `QDir`'s
search paths under various prefixes when you import `taurus.qt.qtgui` (or any
of its submodules).

The following example shows how to use theme and non-theme icons in your
application:

.. literalinclude:: icon_example.py


.. _icon-catalog:

Taurus icon catalog
-------------------

To explore the icon collections provided by Taurus, use the ``taurus icons``
command.

.. figure:: /_static/taurusiconcatalog-01.png
  :align: center

By clicking on an icon of the catalog, you will obtain a larger view of the icon as well as
detailed information on how to access it from your application.

.. figure:: /_static/taurusiconcatalog-details01.png
  :align: center

.. _theme icons: https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html
.. _specification: https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html