8.6.8.13. pymodaq_gui.utils.status_palette module

8.6.8.13.1. PyMoDAQ Status Color Palette

Proposal for a community-wide color convention for status indicators (LEDs, icons, status bars) across all PyMoDAQ modules and plugins.

8.6.8.13.1.1. Rationale

Instrument control software exposes users to many concurrent status indicators. When each component chooses its own colors the user must re-learn the meaning of each indicator. A shared vocabulary lets users read the state of the system at a glance.

Colors are resolved from the active qt_themes theme so that they adapt to the user’s chosen dark or light theme. Hex fallbacks are provided for headless contexts or when a theme attribute is absent.

The six states cover the full lifecycle of a PyMoDAQ module or operation. The upper three states (warning / error / critical) align deliberately with Python’s logging severity levels so that the visual vocabulary is familiar to developers.

8.6.8.13.1.2. Color Definitions

State	Color	logging analogy	Meaning
off	grey	—	Module absent, not initialized, or hardware not yet connected.
idle	green	—	Initialized and ready — waiting for a command or trigger.
running	blue	—	A command is in flight: moving, acquiring, or processing data. Hex fallback: blue #0078d4.
warning	yellow	logging.WARNING	A non-fatal issue. Still functional; user attention advised. Fallback: amber #ccaa00.
error	orange	logging.ERROR	An operation failed. Module may still recover. Fallback: #dc6400.
critical	red	logging.CRITICAL	Unrecoverable fault. Timeout, hardware error, or fatal exception.

8.6.8.13.1.3. Usage with MultistateLED

from pymodaq_gui.utils.status_palette import StatusPalette
from pymodaq_gui.utils.widgets.multistate_led import MultistateLED

# Full six-state indicator
led = MultistateLED(states=StatusPalette.as_states())

# Subset — e.g. a connection indicator without 'warning'
led = MultistateLED(states=StatusPalette.subset('off', 'idle', 'error'))
# ... or, equivalently, using the Status StrEnum
led = MultistateLED(states=StatusPalette.subset(Status.OFF, Status.IDLE, Status.ERROR))

8.6.8.13.1.4. Usage in a parameter tree

from pymodaq_gui.utils.status_palette import StatusPalette

params = [
    {'name': 'acq_status', 'type': 'action_multistate_led',
     'value': 'off',
     'states': StatusPalette.as_states()},
]

class pymodaq_gui.utils.status_palette.Status(*values)

Bases: StrEnum

The six canonical PyMoDAQ status states (see module docstring).

Members behave as plain str (e.g. Status.IDLE == 'idle'), so they can be passed anywhere a state-name string is expected — including StatusPalette.subset() and MultistateLED.

CRITICAL = 'critical'

ERROR = 'error'

IDLE = 'idle'

OFF = 'off'

RUNNING = 'running'

WARNING = 'warning'

class pymodaq_gui.utils.status_palette.StatusPalette

Bases: object

Standard status color definitions for PyMoDAQ.

Colors are drawn from the active qt_themes theme so they adapt to dark / light modes. Each entry resolves to a (name, QColor) pair compatible with MultistateLED.

The states are ordered from least active to most severe.

Methods

as_states()	Return all five states with theme-resolved colors.
color(name)	Return the theme-resolved QColor for a single state name.
subset(*names)	Return a subset of states in canonical order with theme-resolved colors.

classmethod as_states()

Return all five states with theme-resolved colors.

Return type:

list[tuple[str, QColor]]

classmethod color(name)

Return the theme-resolved QColor for a single state name.

Useful when you need just the color, e.g. for an icon or stylesheet.

Return type:

QColor

classmethod subset(*names)

Return a subset of states in canonical order with theme-resolved colors.

Parameters:

*names (str) – State names to include: 'off', 'idle', 'running', 'warning', 'error'.

Raises:

ValueError – If an unknown name is requested.

Return type:

list[tuple[str, QColor]]

Example

>>> StatusPalette.subset('off', 'idle', 'error')
[('off', QColor(...)), ('idle', QColor(...)), ('error', QColor(...))]