spacr.qt.widgets.hint_bar

Window-level, non-modal hover help for Qt controls.

HintBar keeps four visible lines at a fixed height. Longer help can be scrolled within that space while the pointer is over a widget. On pointer leave, it restores the default message only when that widget’s text is still displayed, avoiding an intermediate reset between adjacent controls.

HintBar.explain() registers either explicit text or the widget’s current tooltip. Successful registration clears the tooltip, supplies the same text as the accessible description only when no accessible description is already present, and installs the bar as an event filter. Source strings are translated when displayed. Widgets without available text are not registered.

Use hint_bar_of() to locate the HintBar in a widget’s top-level window, or explain_through_the_bar() to register a widget only when such a bar exists. The bar retains the registration mapping and event filter for its lifetime.

Classes

HintBar

A fixed help strip and the register of what each widget should say.

Functions

explain_through_the_bar(→ bool)	Register widget with its window's bar. False when there is none.
hint_bar_of(→ Optional[HintBar])	The HintBar belonging to widget's window, if it has one.

Module Contents

class spacr.qt.widgets.hint_bar.HintBar(default: str = DEFAULT_HINT, parent: PySide6.QtWidgets.QWidget | None = None)

Bases: PySide6.QtWidgets.QLabel

A fixed help strip and the register of what each widget should say.

Parameters:

• default – what the line says when nothing is hovered. It is restored whenever a widget with no registered hint takes the pointer, so it should read as a prompt rather than as a blank.

• parent – parent widget.

Build the help strip that replaces per-control tooltips.

Four lines stay visible: moving between controls cannot change the dialog’s layout. Longer or translated help scrolls inside the strip without losing its full text or accessible description.

Parameters:

• default – what to show with nothing hovered.

• parent – parent widget, or None.

changeEvent(event)

Keep the reserved four lines in sync with the painted font.

Parameters:

event – the Qt font or style change event.

Returns:

None.

count() → int

How many controls report to this bar.

eventFilter(obj, event)

Watch the widgets whose hints this bar shows.

Parameters:

• obj – the object the event is for.

• event – the event.

Returns:

True to stop the event going further.

explain(widget: PySide6.QtWidgets.QWidget, text: str = '') → str

Have widget write text here while the pointer is on it.

Parameters:

• widget – the control to watch.

• text – what to say. Empty takes the widget’s own tooltip, which is then cleared – the sentence moves rather than being said twice in two places.

Returns:

the sentence registered, or "" if there was none, in which case nothing is watched: a control with nothing to say should not blank the bar when the pointer crosses it.

explains(widget: PySide6.QtWidgets.QWidget) → str

What widget will write here, or "" if it writes nothing.

Parameters:

widget – a control that may have been registered with explain().

reset() → None

Say the default again.

setText(text: str) → None

Show all help in the fixed strip, scrolling when it exceeds four lines.

Parameters:

text – the complete translated help sentence.

showEvent(event) → None

Restore a saved height after the Preferences layout is measured.

Parameters:

event – the Qt show event.

text() → str

Return the complete sentence currently shown in the strip.

spacr.qt.widgets.hint_bar.explain_through_the_bar(widget: PySide6.QtWidgets.QWidget, text: str = '') → bool

Register widget with its window’s bar. False when there is none.

The caller decides what to do without one – usually leave the tooltip where it is, which is better than a control that explains itself nowhere.

Parameters:

widget – the control to register; its window’s bar is found with hint_bar_of(). Also returns False when the widget has nothing to say.

spacr.qt.widgets.hint_bar.hint_bar_of(widget: PySide6.QtWidgets.QWidget) → HintBar | None

The HintBar belonging to widget’s window, if it has one.

Lets a helper deep in a form hand a sentence to the bar without the caller having to thread it down through every layer.

Parameters:

widget – any widget, or None; its top-level window is searched for a HintBar child.