tips

_tips

Rich tooltips built on Qt's own setToolTip.

This is the everyday path for tooltips in fxgui. A bare setToolTip("Refresh") restates the label and teaches nothing; a useful tooltip answers three things at once, what the control is, what it does to the user's data, and how to reach it without the mouse. Every string goes through tip, so no call site invents its own layout and the wording stays consistent: title in the theme's primary text, body dimmed, shortcut on the right as a keycap.

Reach for FXTooltip instead when native tooltips cannot do the job: hosting live widgets (images, action buttons), staying up while the pointer is over the tooltip itself, or arrow-anchored placement. Everything else belongs here.

Qt renders a tooltip through QTextDocument, which supports a small subset of HTML: b, span style (color, background, font), br and tables. It has no flexbox, no gap, and it ignores border-radius on inline spans, which is why the keycap is a background-tinted span inside a table cell rather than a rounded pill. The keycap sits in a right-aligned cell of a full-width table because that is the only way Qt's rich text will push part of a line to the right edge.

There is deliberately no width cap here. Qt ignores max-width, and the one width it does honour, a table width attribute, it applies as a fixed width rather than a maximum, which puts a short tooltip in an oversized box. It is not needed either: the tooltip popup word-wraps itself, measured at 192px for a short body, 224px for a full sentence, and saturating at 440px however long the body gets, so a tooltip never stretches across a monitor on its own.

Colors are read from the active theme on every call rather than baked in, so these tooltips follow a theme switch and a studio's custom theme without any extra wiring. The surface they land on is styled by the QToolTip rule in qss/style.qss, from the same tokens.

Functions:

Name	Description
apply_tip	Set a rich tooltip on widget, plus a markup-free status tip.
example	Show a window whose controls carry native rich tooltips.
keycap	Render one keyboard shortcut as a key.
tip	Build the HTML for a rich tooltip.

Functions:

apply_tip

apply_tip(
    widget: QWidget, title: str, body: str = "", shortcut: str = ""
) -> None

Set a rich tooltip on widget, plus a markup-free status tip.

Parameters:

Name	Type	Description	Default
widget	QWidget	The widget to annotate.	required
title	str	What the control is, in a couple of words.	required
body	str	What the control does. Defaults to "".	''
shortcut	str	A Qt key sequence, such as "Ctrl+S". Defaults to "".	''

Examples:

>>> apply_tip(
...     button,
...     "Save",
...     "Write the scene to disk",
...     "Ctrl+S",
... )

Note

The status tip carries the same words without markup. Qt shows it in the window's status bar on hover, which is where a person looks for "what is this" before a tooltip has had time to appear. Widgets without setStatusTip only get the tooltip.

example

example() -> None

Show a window whose controls carry native rich tooltips.

keycap

keycap(keys: str) -> str

Render one keyboard shortcut as a key.

Parameters:

Name	Type	Description	Default
keys	str	A Qt key sequence, such as "Ctrl+S", "F5" or "Ctrl+Shift+E".	required

Returns:

Name	Type	Description
str	str	HTML for the keycap, or an empty string when keys is empty.

Examples:

>>> button.setToolTip(f"Save {keycap('Ctrl+S')}")

Note

The sequence is run through QKeySequence so a Mac shows the platform glyphs rather than the literal "Ctrl". Sequences Qt cannot parse fall back to the raw string.

tip

tip(title: str, body: str = '', shortcut: str = '') -> str

Build the HTML for a rich tooltip.

Parameters:

Name	Type	Description	Default
title	str	What the control is, in a couple of words. Sentence case, no trailing period, it is a label and not a sentence.	required
body	str	What the control does, or why it is unavailable. One sentence. Defaults to "".	''
shortcut	str	A Qt key sequence, such as "Ctrl+S". Defaults to "".	''

Returns:

Name	Type	Description
str	str	HTML to hand to setToolTip. An empty string when all three arguments are empty, so a caller can pass a missing value through without producing an empty floating box.

Examples:

>>> tip("", "", "")
''
>>> button.setToolTip(
...     tip("Save", "Write the scene to disk", "Ctrl+S")
... )

Note

Every caller string is HTML-escaped, so a path or a name holding & or < reaches the user as text instead of corrupting the markup.