spacr.qt.widgets.api_help_label

Labels with hover-accessible links to spaCR API documentation.

Classes

ApiHelpLabel

Display descriptive text with an API link in its hover help.

Module Contents

class spacr.qt.widgets.api_help_label.ApiHelpLabel(text: str = '', app_key: str = '', parent: PySide6.QtWidgets.QWidget | None = None)

Bases: PySide6.QtWidgets.QLabel

Display descriptive text with an API link in its hover help.

The link follows the active module and interface language. Labels without an application key retain their description but omit the documentation link. Hover content is also exposed through the Qt accessibility tree.

IT ELIDES RATHER THAN CLIPS, which is the difference between a sentence the reader can SEE is unfinished and one that simply stops. This label is the module masthead’s blurb, and the masthead deliberately keeps it to one line that “may shrink below its ideal width rather than force the window wider” – so being cut short is designed, and the hover help is where the rest is meant to live.

A wordWrap(False) QLabel gives none of that away: Qt paints as many characters as fit and stops, with no ellipsis and no hint there is more. Measured on Classify in German, where the blurb is 1,354 px of text on a 1,281 px line – 73 px, about six characters, gone without a mark. English fits, which is why it was invisible until a second locale was measured.

Parameters:

• text – the blurb to show, and what the label falls back to when no translation is loaded.

• app_key – which module’s API page the link opens. Empty means no link at all, which is how a caption outside a module screen is drawn.

• parent – parent widget.

Build a label whose hover help links into the module’s API docs.

Parameters:

• text – the description shown, and the body of the help.

• app_key – the module the help links to; without one the label still shows its description but links nowhere.

• parent – parent widget, or None.

full_text() → str

The complete description, however much is being painted.

help_html() → str

Return the rich-text help used for hover and accessibility.

minimumSizeHint() → PySide6.QtCore.QSize

Ask the layout for one word, not for the whole sentence.

THE MASTHEAD ALREADY SAID THIS AND QT WAS NOT LISTENING. It builds this label with setSizePolicy(QSizePolicy.Maximum, ...) and setMinimumWidth(0) and documents the intent – the blurb “may shrink below its ideal width rather than force the window wider”. Neither call achieves it: qSmartMinSize takes a shrinkable widget’s minimum from minimumSizeHint(), which for a non-wrapping QLabel is the width of the ENTIRE sentence, and it only lets an explicit minimumWidth override that when the value is greater than zero. So the one control on the masthead that can lose text harmlessly was the one control that refused to give any width up.

TWO THINGS FOLLOWED, both measured on the Power screen in Icelandic at the largest font scale preferences offers:

• THE MODULE TITLE WAS WHAT GOT CUT. The header needed 1274 px and had 1168, and every one of those 106 px came off the title – ‘Tölfræðilegt afl / hönnun’ painted in 577 px of a 683 px hint – while the blurb sat at its full width beside it. A module name cut mid-word, next to a sentence that had room to spare and a hover copy of itself.

• AND IT SET THE FLOOR UNDER EVERY MODULE SCREEN. The masthead’s minimum was 1166 px at 100 %, which is most of the ~1198 px minimum the whole screen reported – so this label, alone, was why a module page could not be shown narrow.

ONE WORD PLUS THE ELLIPSIS, rather than a constant: it is measured in the label’s own font, so it tracks the font scale without being told about it, and at its narrowest the blurb still says what it is about instead of collapsing to a dot. Never wider than the sentence itself, so a short description keeps behaving exactly as it did.

Only when the label does not wrap. A wrapping label trades width for HEIGHT, and Qt’s own minimum already knows how.

resizeEvent(event)

Re-elide for the width just granted.

Parameters:

event – the resize event, passed to the base class; the text is then elided to the label’s new width.

retranslate_dynamic_content(language: object) → None

Rebuild translated hover content and its documentation link.

Parameters:

language – the language to translate the hover help into, converted to a string; a falsy value clears it. Any set_url() override is dropped.

setText(text: str) → None

Remember the whole sentence, then paint as much of it as fits.

Parameters:

text – the full description; None becomes "". It is kept whole and painted elided to fit.

set_api_app_key(app_key: str) → None

Set the module whose API documentation is linked.

Parameters:

app_key – the module whose API page is linked; None or empty means no link. Any set_url() override is dropped.

set_url(url: str) → None

Override the documentation URL while preserving the description.

Parameters:

url – the documentation URL to link instead of the module’s API page; empty removes the override.

url() → str

Return the documentation URL in the current hover content.