spacr.qt.widgets.section

Section — a collapsible group with a header row (chevron + title) and a QFormLayout body that expands/collapses on click. Used by settings screens to group related fields; every section is collapsed by default so users see one row per category instead of a wall of controls.

A HEADING CAN ALSO SAY WHOSE SETTINGS THESE ARE. A module folded into another one keeps its settings and loses its tile, and where the fold made those settings a category rather than a page there is no button left to carry the picture the user learned the module by. It goes on the heading instead — Section.set_source_app(), which draws the module’s own icon at the trailing end of the header row.

Classes

Section

Collapsible section with an animated chevron header + form body.

Functions

module_mark(key)	Return the specific icon for a folded module, if available.
scroll_host(widget)	The QScrollArea widget scrolls inside, or None.

Module Contents

class spacr.qt.widgets.section.Section(title: str, parent=None, expanded: bool = False)

Bases: PySide6.QtWidgets.QFrame

Collapsible section with an animated chevron header + form body.

Parameters:

• title – the heading text, which is also what the hover strip looks this section’s help up by.

• parent – parent widget.

• expanded – whether it opens unfolded. Sections start CLOSED by default because a screen that opens every one of them is a wall of settings before the user has chosen anything.

Build one collapsible settings category.

The title is kept as written and uppercased only on the way to the button, because the translation catalogue is keyed on the written name – looking up an already-uppercased caption finds nothing and leaves the header in English. The & in a name like “Plate Layout & Controls” is escaped for display, since a QToolButton would otherwise read it as a mnemonic and swallow it.

The form’s field-growth policy is named explicitly rather than left to the platform style: a style answering FieldsStayAtSizeHint – valid, and what one reporter’s platform chose – gave a field 108 px in a section that Fusion gives 1,115.

Parameters:

• title – the category name, as written.

• parent – parent widget, or None.

• expanded – open the category immediately.

add_prose(widget: PySide6.QtWidgets.QWidget, *, at_top: bool = False) → None

Add full-width content that is NOT a setting row.

Parameters:

• widget – prose or other non-setting content to add.

• at_top – put it above the section’s controls rather than below.

THE DIFFERENCE FROM add_widget() IS _row_widgets, and it is the whole reason this exists. Every entry there is taken to BE a labelled setting row by tests/qt/test_all_module_smoke.py::_setting_row_contract, which asserts each field carries a settingKey and that its label is a QLabel holding linked API help. A prose box is neither a setting nor labelled, so registering it there would either fail that contract or force a fake settingKey onto a non-setting – which would then be pushed into the tooltip and API-documentation machinery.

add_widget has the same signature and the opposite bookkeeping, and had no caller in the GUI, so nothing had yet exposed the conflation.

add_prose_row(label: str | PySide6.QtWidgets.QWidget, widget: PySide6.QtWidgets.QWidget, *, at_top: bool = False) → None

A labelled row that is NOT a setting.

The difference from add_row() is _row_widgets, for the reason add_prose() gives: every entry there is taken to BE a labelled setting by the module smoke test, which asserts each field carries a settingKey and that its label holds linked API help. A row of Download buttons is neither.

It still goes through the section’s own QFormLayout, so its label sits in the same column and at the same right-aligned edge as every setting above and below it – which is the point: a row of buttons floating in the middle of the section reads as unrelated to the settings it acts on, and one aligned with them reads as part of the same form.

Parameters:

• label – the row label: text (shown elided, with the full text as tooltip) or a ready-made widget.

• widget – the widget placed in the field column of the row.

add_row(label: str | PySide6.QtWidgets.QWidget, widget: PySide6.QtWidgets.QWidget, info_widget: PySide6.QtWidgets.QWidget | None = None, wrap_label: bool = False) → None

Add a labeled row, optionally with an information-link icon.

Parameters:

• label – text or widget shown on the row’s label side.

• widget – setting control shown on the row’s field side.

• wrap_label – build the SettingLabelWithInfo host even with no info widget to put in it. The host is what right-aligns the label against its field; it used to arrive only as a side effect of there being a dot, so removing the dot from the settings form left every label left-aligned and turned half of each row’s width into page showing through rather than category surface. _row_widgets still records the caller’s label, not the host, so anything reading rows back gets the QLabel it passed in.

add_widget(widget: PySide6.QtWidgets.QWidget) → None

Add a full-width (label-less) widget to the section’s form body.

Parameters:

widget – the widget added as a full-width row, coloured by the section’s maturity.

changeEvent(event)

Re-seal the body when the stylesheet or the palette is swapped.

A theme change or a move of the page-opacity slider re-renders surface; the seal is a palette brush this widget owns, so nothing else re-computes it. Only StyleChange is answered – setting the body’s palette posts PaletteChange back here, and answering that one would be a loop.

Parameters:

event – the change event; it is passed to the base class, and a QEvent.StyleChange also re-seals the body.

eventFilter(watched, event)

Swallow the header’s tooltip request; pass everything else on.

The header’s own minimum is re-taken here on the two events that can change what it needs – a new font, and a new style – because both arrive after the button is built. See _sync_header_minimum().

Parameters:

• watched – the object the event is for.

• event – the event.

Returns:

True to stop a tooltip from being shown.

header() → PySide6.QtWidgets.QToolButton

Return the clickable header button (chevron + category title).

Public because a screen needs a precise hover target for the category it represents: the section itself covers the whole form once expanded, so filtering events on it would report the category while the pointer is over one of its settings.

is_expanded() → bool

Return True when the section body is currently visible.

maturity() → str

Return stable, beta or alpha for this section.

set_expanded(on: bool) → None

Expand or collapse the section body programmatically.

Parameters:

on – True to expand the body, False to collapse it.

set_hint(text: str) → None

Attach a hover tooltip to the section’s header.

The tooltip appears when the user hovers the header, whether the section is currently expanded or collapsed — same UX as every other Qt tooltip.

Parameters:

text – tooltip text (plain or HTML; empty clears it).

set_maturity(stage: str) → None

Colour this section and every setting row by maturity stage.

stable/beta/alpha use the exact hues shown in Home’s maturity legend. Unknown values deliberately fall back to stable.

Parameters:

stage – maturity stage, 'stable', 'beta' or 'alpha' (case-insensitive); empty or unknown values are treated as 'stable'.

set_source_app(key: str, name: str = '') → bool

Associate this category with a folded module and display its icon.

The icon is drawn separately from the header button so the collapse chevron and pointer target remain unchanged.

Parameters:

• key – Folded module registry key.

• name – Accessible module name. If empty, key is used.

Returns:

True if a module-specific icon was displayed.

source_app() → str

Return the folded module associated with this category.

source_mark() → PySide6.QtWidgets.QWidget | None

Return the visible source-icon label, or None.

title() → str

Return the section’s header text, un-escaped.

spacr.qt.widgets.section.module_mark(key: str)

Return the specific icon for a folded module, if available.

Generic fallback artwork is not returned because it does not identify the source module.

Parameters:

key – Folded module registry key.

spacr.qt.widgets.section.scroll_host(widget)

The QScrollArea widget scrolls inside, or None.

The confinement belongs on the scroll area and not on the section, because it is the SCROLL AREA’s own size hint changing – when its scrollbar arrives – that carries the relayout past the settings column and into the splitter and the window.

Parameters:

widget – the section being toggled.

Returns:

the enclosing scroll area, or None when the section is mounted without one (a dialog, a test).