Widgets¶

Subclass the FXMainWindow¶

You can subclass any widgets in the fxwidgets module. Here's a practical example with FXMainWindow:

# Third-party
from qtpy.QtWidgets import QWidget, QVBoxLayout, QPushButton

# Internal
from fxgui import fxwidgets, fxicons


class MyWidget(QWidget):
    def __init__(self, parent=None):
        super().__init__(parent)

        self.add_layout()
        self.add_buttons()

    def add_layout(self):
        """Adds a vertical layout to the main layout of the widget."""

        self.main_layout = QVBoxLayout()
        self.setLayout(self.main_layout)

    def add_buttons(self):
        """Adds buttons to the main layout of the widget."""

        # Use fxicons for theme-aware icons
        home_button = QPushButton("Home")
        fxicons.set_icon(home_button, "home")

        settings_button = QPushButton("Settings")
        fxicons.set_icon(settings_button, "settings")

        self.main_layout.addWidget(home_button)
        self.main_layout.addWidget(settings_button)
        self.main_layout.addStretch()


class MyWindow(fxwidgets.FXMainWindow):
    def __init__(self, parent=None):
        super().__init__(parent)

        self.setCentralWidget(MyWidget(parent=self))
        self.adjustSize()


application = fxwidgets.FXApplication()
window = MyWindow()
window.setWindowTitle("Subclassed FXMainWindow")
window.show()
application.exec()

The Gallery¶

python -m fxgui.examples

A window opens with every public widget, a page per kind: buttons, inputs, display, containers, lists and trees, the timeline, windows and dialogs, and docking. Each box is titled with the class names it shows. Window > Theme switches the theme, so you can see a widget in each. The Docking page needs PySide6-QtAds (see Installation).

Available Widgets¶

The fxwidgets module holds these classes:

fxdocking.FXDockArea docks named panes around a body; it needs PySide6-QtAds (see Installation).

And these functions and constants:

Breadcrumbs¶

from fxgui.fxwidgets import FXBreadcrumb

crumb = FXBreadcrumb(home_icon="", tab_stops=False)
crumb.set_path(["pilot", "sq010", "sh0040", "comp"])
crumb.set_edit_placeholder("Type a shot")

• Every segment but the last is a button: it tints under the pointer and shows a pointing hand. The last one is where the path already is, so it is bold and does nothing.
• The strip behind the segments is a filled field, brighter while the pointer is over it. Double-click it to type a path; a press anywhere outside closes the editor, and so does exit_edit_mode().
• The colours are worked out each time the strip paints, from the theme and from what the breadcrumb sits on: the frame colour on a framed window's toolbar or a band marked with mark_as_frame, the surface anywhere else. The text reads at 4.5:1 on both fills and the edge shows at 1.3:1 against the ground and both fills, in every bundled theme. A theme switch needs no call.
• tab_stops=False takes the segments and the back and forward buttons out of the Tab order. The path editor keeps its stop.

The starting colours are class attributes, so a subclass names its own tokens:

from fxgui.fxwidgets import FXBreadcrumb


class HouseCrumb(FXBreadcrumb):
    STRIP_RESTING_TOKEN = "surface_alt"
    SEGMENT_HOVER_TOKEN = "text_muted"
    SEGMENT_HOVER_ALPHA = 48

Do not point STRIP_RESTING_TOKEN at surface: in every bundled theme that is the window's own colour, so on a plain window the strip disappears.

Your Own Item-Data Roles¶

FXThumbnailDelegate reads item-data roles of its own off the items it paints, from Qt.UserRole + 1 up to FIRST_FREE_ROLE, and FXSortedTreeWidgetItem.SORT_ROLE sits in the same range. A view that puts roles of its own on the same items derives them from FIRST_FREE_ROLE:

from fxgui.fxwidgets import FXThumbnailDelegate

ROW_KIND_ROLE = FXThumbnailDelegate.FIRST_FREE_ROLE
ROW_COLOR_ROLE = FXThumbnailDelegate.FIRST_FREE_ROLE + 1

A role added to the delegate moves FIRST_FREE_ROLE up, and every role derived from it moves too.

Tooltips¶

apply_tip is fxgui's tooltip. It hands Qt's own setToolTip a small HTML string, and sets a markup-free status tip for the window's status bar:

from qtpy.QtWidgets import QPushButton
from fxgui.fxwidgets import apply_tip

save_button = QPushButton("Save")
apply_tip(
    save_button,
    "Save",
    "Write the current scene to disk, overwriting the last version",
    "Ctrl+S",
)

The title is in the theme's primary text, the body dimmed, and the shortcut sits on the right as keycaps, one per key: Ctrl S. The keys of one chord sit close; a second chord (Ctrl+K, Ctrl+S) sits further away. Key names come from QKeySequence, so a Mac shows its own glyphs rather than the word "Ctrl".

The HTML holds the colours of the theme in force, so rebuilding at show time is what makes a tip set in one theme show in the next. Every string is HTML-escaped, so a path holding & or < reaches the user as text, and a newline in the body breaks the line. Qt's rich text draws no rounded background, so a keycap in a tooltip is square.

Two lower-level helpers:

• tip() returns the HTML. Call it when the tip shows: a model returns tip(...) from data() for Qt.ToolTipRole, which Qt asks for on hover.
• keycap() returns a shortcut's keycaps as HTML. A label reads its text once, so a keycap on a window is an FXKeycap instead: a widget, one cap per key, round at the button radius, that follows every theme switch.