.. include:: ../../../_includes/_warning_banner.rst

.. SPDX-FileCopyrightText: 2026 James Turner <james@flightgear.org>
.. SPDX-License-Identifier: GPL-2.0-or-later

========
Tooltips
========

Tooltips are shown as part of a ``knob`` or ``slider`` animation, or
a ``tooltip`` animation.

Tooltips are actually an instance of a ``popup``, which are temporary
on-screen notifications that are *not* associated with a visual location
(unlike tooltips which typically are). Triggering a popup (eg by pressing
pause) clears any active tooltip.

Note that **behavioural** aspects of the tooltip are controlled by
centralized properties, so that a user can configure them according to
their preferences and accessibility needs. For example disabling them
entirely, or increasing the hysteresis or timeout.

Translation
===========

In the near future, it will become possible to use a translation ID
in tooltips, probably by specifying a ``label-id``` property which will
be looked up as described :ref:`here <translation infrastructure>`, translated, and formatting
of substitution elements applied.

Tooltip Commands
================

``set-tooltip``
    Sets the current tooltip. This does *not* show the tooltip, but resets or
    updates the show timer, based on the ``tooltip-id``.


Tooltip Command Properties
==========================

Possible arguments to setting a tooltip.

``tooltip-id``
    Defines a unique internal name for the tooltip. This is used to distuinguish
    an existing tooltip being updated vs a new tooltip being shown.

``label``
    Defines the main text shown in the tooltip. It can contain substitution elements,
    currently formatted via `sprintf`, but this syntax will likely change to `fmt`
    syntax in the near future.

``property``
    One or more properties to display in the tooltip. The value of the property
    is formatted as a string based on the ``mapping`` property.

    A listener is attached to each property, so that live changes are reflected in the
    tooltip automatically. This is especially relevant for live feedback during
    continuous updates.

``mapping``
    Defines how property values are mapped to strings. Possible values are:

    ``percent``
        The value is multiplied by 100 and rounded to an integer

    ``heading``
        The value is normalized to 1..360 and rounded to an integer

    ``nasal``
        The ``<script>`` child of the node is evaluated each time a property changes,
        and its result is used as the displayed value

    ``on-off``
        Value is mapped to a boolean and shown as the strings 'ON' or 'OFF'

    ``arm-disarm``
        Value is mapped to a boolean and shown as the strings 'ARMED' or 'DISARMED'

    ``open-closed``
        Value is mapped to a boolean and shown as the strings 'OPEN' (true) or 'CLOSED' (false)

    ``closed-open``
        Value is mapped to a boolean and shown as the strings 'OPEN' (false) or 'CLOSED' (true)

    Adding additional format modes is easily done via Nasal.