composeui 0.1.0__py3-none-any.whl

composeui/qtcore/widgets/qmetric.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Any
+
+from qtpy.QtCore import Qt
+from qtpy.QtWidgets import QVBoxLayout, QWidget
+
+from composeui.qtcore.widgets.qplaintext import plain_label
+
+#: the badge's text color and its tint behind, for a rise and a fall; readable on a light
+#: and a dark palette alike
+_RISE_STYLE = "QLabel { color: #16a34a; background: rgba(22, 163, 74, 0.15); }"
+_FALL_STYLE = "QLabel { color: #dc2626; background: rgba(220, 38, 38, 0.15); }"
+_FLAT_STYLE = "QLabel { background: rgba(128, 128, 128, 0.15); }"
+_BADGE_STYLE = "QLabel { border-radius: 4px; padding: 1px 6px; }"
+
+
+class QMetric(QWidget):
+    """A metric: its label, its value in a large bold font, then its change as a badge."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(0, 0, 0, 0)
+        self.label = plain_label()
+        layout.addWidget(self.label)
+        self.value = plain_label()
+        font = self.value.font()
+        font.setPointSizeF(font.pointSizeF() * 2)
+        font.setBold(True)
+        self.value.setFont(font)
+        layout.addWidget(self.value)
+        self.badge = plain_label()
+        self.badge.setVisible(False)
+        # as wide as its text, not the column
+        layout.addWidget(self.badge, alignment=Qt.AlignmentFlag.AlignLeft)
+        layout.addStretch()
+
+    def set_delta(self, badge: str, sign: int) -> None:
+        """Show `badge`, colored by the `sign` of its change; an empty one hides it."""
+        self.badge.setText(badge)
+        self.badge.setVisible(badge != "")
+        tint = _RISE_STYLE if sign > 0 else _FALL_STYLE if sign < 0 else _FLAT_STYLE
+        self.badge.setStyleSheet(f"{_BADGE_STYLE} {tint}")

composeui/qtcore/widgets/qplaintext.py

@@ -0,0 +1,29 @@
+"""View text that Qt shows as it is, never read as HTML.
+
+A `QLabel` and a tooltip guess their text's format: a text that looks like HTML, such as
+`<b>x</b>`, would show as rich text, its tags hidden and its links clickable.
+"""
+
+from __future__ import annotations
+
+import html
+
+from qtpy.QtCore import Qt
+from qtpy.QtWidgets import QLabel
+
+
+def plain_label() -> QLabel:
+    """Get a label that shows its text as plain text."""
+    label = QLabel()
+    label.setTextFormat(Qt.TextFormat.PlainText)
+    return label
+
+
+def plain_tool_tip(text: str) -> str:
+    """Get `text` as a tooltip that shows it as it is.
+
+    A tooltip has no plain format: a text with a tag is escaped as rich text instead.
+    """
+    if "<" not in text:
+        return text  # no tag: Qt shows it as plain text
+    return "<p>{}</p>".format(html.escape(text, quote=False).replace("\n", "<br>"))

composeui/qtcore/widgets/qradiogroup.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any
+
+from qtpy.QtCore import Signal, Slot
+from qtpy.QtWidgets import (
+    QButtonGroup,
+    QHBoxLayout,
+    QRadioButton,
+    QWidget,
+)
+
+
+class QRadioGroup(QWidget):
+    """Custom signal for the Radio group."""
+
+    value_changed = Signal(object)
+
+    def __init__(self, values: dict[str, Any], *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._layout = QHBoxLayout()
+        self._layout.setContentsMargins(0, 0, 0, 0)
+        # the buttons packed at the start, as on the web, not spread over the row
+        self._layout.addStretch()
+        self.setLayout(self._layout)
+        self._button_group = QButtonGroup(self)
+        self._button_group.setExclusive(True)
+        self._button_group.idClicked.connect(self._emit_value_changed_signal)
+        self._values: dict[str, Any] = {}
+        self.set_values(values)
+
+    def set_values(self, values: dict[str, Any]) -> None:
+        """Rebuild the radio buttons for a new set of options."""
+        for button in self._button_group.buttons():
+            self._button_group.removeButton(button)
+            self._layout.removeWidget(button)
+            # detached at once: `deleteLater` alone leaves it a visible child, drawn
+            # next to the new buttons until the event loop gets to deleting it
+            button.setParent(None)
+            button.deleteLater()
+        self._values = values
+        for i, value_text in enumerate(self._values):
+            button = QRadioButton(value_text)
+            self._layout.insertWidget(self._layout.count() - 1, button)  # before the stretch
+            self._button_group.addButton(button, i)
+
+    def set_value(self, value: Any) -> None:
+        for button_id, value_raw in enumerate(self._values.values()):
+            if value == value_raw:
+                self._button_group.button(button_id).setChecked(True)
+
+    @Slot()
+    def _emit_value_changed_signal(self, button_id: int) -> None:
+        """Emit the value changed signal."""
+        value_text = self._button_group.button(button_id).text()
+        value = self._values[value_text]
+        self.value_changed.emit(value)

composeui/qtcore/widgets/qsidebar.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from typing import Any
+
+from qtpy.QtCore import Qt
+from qtpy.QtCore import Signal as QtSignal
+from qtpy.QtWidgets import (
+    QDockWidget,
+    QHBoxLayout,
+    QMainWindow,
+    QScrollArea,
+    QStyle,
+    QToolButton,
+    QVBoxLayout,
+    QWidget,
+)
+
+from composeui.qtcore.widgets.qplaintext import plain_label
+
+#: pixels a sidebar is wide at least while expanded, e.g. room for a form's fields
+_MINIMUM_WIDTH = 280
+#: Qt's largest widget size, a widget's maximum when nothing limits it
+_QWIDGETSIZE_MAX = 16777215
+
+
+class QSidebar(QDockWidget):
+    """A dock for the window's left: a header, its title and a button, then its content.
+
+    The dock stays where it is: it can't be closed, moved or floated, as the sidebar is
+    part of the app's layout. Its own title bar is left out for the header. The header's
+    button retracts the sidebar to a strip holding only the button, and expands it back;
+    `expanded_changed` reports those clicks, and `set_expanded` is quiet, as is any change
+    while the dock's signals are blocked (the renderers block them while refreshing).
+    """
+
+    #: the user expanded (True) or retracted (False) the sidebar
+    expanded_changed = QtSignal(bool)
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.setFeatures(QDockWidget.DockWidgetFeature.NoDockWidgetFeatures)
+        self.setTitleBarWidget(QWidget())
+        self._width = _MINIMUM_WIDTH
+        body = QWidget()
+        body_layout = self._body_layout = QVBoxLayout(body)
+        body_layout.setContentsMargins(0, 0, 0, 0)
+        body_layout.setSpacing(0)
+        self._header = QHBoxLayout()
+        header = self._header
+        self.title = plain_label()
+        font = self.title.font()
+        font.setBold(True)
+        self.title.setFont(font)
+        header.addWidget(self.title, 1)
+        self.toggle = QToolButton()
+        self.toggle.setAutoRaise(True)
+        self.toggle.clicked.connect(self._on_toggle_clicked)
+        header.addWidget(self.toggle, 0, Qt.AlignmentFlag.AlignTop)
+        body_layout.addLayout(header)
+        content = QWidget()
+        self.content_layout = QVBoxLayout(content)
+        self.content_scroll = QScrollArea()
+        self.content_scroll.setMinimumWidth(_MINIMUM_WIDTH)
+        self.content_scroll.setWidgetResizable(True)
+        self.content_scroll.setFrameShape(QScrollArea.Shape.NoFrame)
+        # as wide as its content: no horizontal scroll bar
+        self.content_scroll.setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOff)
+        self.content_scroll.setWidget(content)
+        body_layout.addWidget(self.content_scroll, 1)
+        # the strip's room below the button, once retracted
+        body_layout.addStretch(0)
+        self.setWidget(body)
+        self._show_expanded(is_expanded=True)
+
+    def finish_content(self) -> None:
+        """Leave the height to spare below the content, once it is added, not between it."""
+        self.content_layout.addStretch()
+
+    def is_expanded(self) -> bool:
+        return self.content_scroll.isVisibleTo(self)
+
+    def set_expanded(self, is_expanded: bool) -> None:
+        self._show_expanded(is_expanded=is_expanded)
+
+    def set_title(self, title: str) -> None:
+        self.title.setText(title)
+        self.title.setVisible(title != "" and self.is_expanded())
+
+    def _show_expanded(self, *, is_expanded: bool) -> None:
+        if not is_expanded and self.content_scroll.isVisibleTo(self):
+            self._width = self.width()  # given back once expanded
+        self.content_scroll.setVisible(is_expanded)
+        self.title.setVisible(is_expanded and self.title.text() != "")
+        # pointing the way the sidebar goes: left to retract it, right to expand it
+        arrow = Qt.ArrowType.LeftArrow if is_expanded else Qt.ArrowType.RightArrow
+        self.toggle.setArrowType(arrow)
+        style = self.style()
+        left = style.pixelMetric(QStyle.PixelMetric.PM_LayoutLeftMargin)
+        right = style.pixelMetric(QStyle.PixelMetric.PM_LayoutRightMargin)
+        top = style.pixelMetric(QStyle.PixelMetric.PM_LayoutTopMargin)
+        # expanded, inset like the rows under it (their column's margin, then their own);
+        # retracted, the strip only as wide as the button and a margin
+        inset = 2 if is_expanded else 1
+        self._header.setContentsMargins(inset * left, top, inset * right, 0)
+        self._body_layout.activate()
+        # a dock keeps the width it has: retracted, as narrow as the strip; expanded, back
+        # to its width before
+        self.setMaximumWidth(_QWIDGETSIZE_MAX if is_expanded else self.minimumSizeHint().width())
+        window = self.parentWidget()
+        if is_expanded and isinstance(window, QMainWindow):
+            window.resizeDocks([self], [self._width], Qt.Orientation.Horizontal)
+
+    def _on_toggle_clicked(self) -> None:
+        is_expanded = not self.is_expanded()
+        self._show_expanded(is_expanded=is_expanded)
+        self.expanded_changed.emit(is_expanded)

composeui/qtcore/widgets/qsourcetable.py

@@ -0,0 +1,216 @@
+"""A large table's widget: a `QTableView` that asks its view for the rows it draws."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional, Protocol, Union
+
+from qtpy.QtCore import (
+    QAbstractTableModel,
+    QModelIndex,
+    QObject,
+    QPersistentModelIndex,
+    Qt,
+    Signal,
+)
+from qtpy.QtGui import QAction, QKeySequence, QPalette
+from qtpy.QtWidgets import (
+    QAbstractItemView,
+    QApplication,
+    QHeaderView,
+    QSizePolicy,
+    QTableView,
+    QToolButton,
+    QVBoxLayout,
+    QWidget,
+)
+
+from composeui.qtcore.widgets.qfiltertable import QTableFilterBar
+from composeui.qtcore.widgets.qplaintext import plain_label
+
+if TYPE_CHECKING:
+    from qtpy.QtGui import QKeyEvent
+
+_Index = Union[QModelIndex, QPersistentModelIndex]
+
+
+class SourceTableLike(Protocol):
+    """What the model reads from a `SourceTableView`."""
+
+    @property
+    def headers(self) -> list[str]: ...
+    @property
+    def row_count(self) -> int: ...
+    def rows(self, start: int, stop: int) -> list[tuple[Any, list[str]]]: ...
+    def is_selected(self, row_id: Any) -> bool: ...
+
+
+class QSourceTableModel(QAbstractTableModel):
+    """The rows of a large table, read from its view as Qt draws them, never all at once.
+
+    Qt asks for the cells it draws, and the view reads them from its source a window at
+    a time. `reset` shows a new order of the rows; `repaint` the same rows, formatted or
+    selected again. The rows' headers are their positions, from 1. A selected row has the
+    palette's highlight colors.
+
+    Qt asks for each cell's text and colors apart: the model keeps the row it read last,
+    so the view formats each row drawn once, not once a cell and a role.
+    """
+
+    def __init__(self, table: SourceTableLike, parent: Optional[QObject] = None) -> None:
+        super().__init__(parent)
+        self._table = table
+        #: the row read last: its position, its id and its cells
+        self._row: Optional[tuple[int, Any, list[str]]] = None
+
+    def reset(self) -> None:
+        self.beginResetModel()
+        self._row = None
+        self.endResetModel()
+
+    def repaint(self) -> None:
+        self._row = None
+        if self.rowCount() > 0 and self.columnCount() > 0:
+            last = self.index(self.rowCount() - 1, self.columnCount() - 1)
+            self.dataChanged.emit(self.index(0, 0), last)
+
+    def rowCount(self, parent: _Index = QModelIndex()) -> int:  # noqa: B008, N802
+        return 0 if parent.isValid() else self._table.row_count
+
+    def columnCount(self, parent: _Index = QModelIndex()) -> int:  # noqa: B008, N802
+        return 0 if parent.isValid() else len(self._table.headers)
+
+    def data(self, index: _Index, role: int = Qt.ItemDataRole.DisplayRole) -> Any:
+        looks: dict[int, QPalette.ColorRole] = {
+            Qt.ItemDataRole.BackgroundRole: QPalette.ColorRole.Highlight,
+            Qt.ItemDataRole.ForegroundRole: QPalette.ColorRole.HighlightedText,
+        }
+        if not index.isValid() or (role != Qt.ItemDataRole.DisplayRole and role not in looks):
+            return None
+        if self._row is None or self._row[0] != index.row():
+            rows = self._table.rows(index.row(), index.row() + 1)
+            if len(rows) == 0:  # rows not shown any longer, the model not reset yet
+                # a paint between the source's change and the model's reset: no test
+                # reaches that moment
+                return None  # pragma: no cover
+            self._row = (index.row(), *rows[0])
+        _position, row_id, cells = self._row
+        if role in looks:
+            is_selected = self._table.is_selected(row_id)
+            return QApplication.palette().brush(looks[role]) if is_selected else None
+        return cells[index.column()] if index.column() < len(cells) else None
+
+    def headerData(  # noqa: N802
+        self, section: int, orientation: Qt.Orientation, role: int = Qt.ItemDataRole.DisplayRole
+    ) -> Any:
+        if role != Qt.ItemDataRole.DisplayRole:
+            return None
+        if orientation == Qt.Orientation.Horizontal:
+            headers = self._table.headers
+            return headers[section] if section < len(headers) else None
+        return f"{section + 1:,}"
+
+
+class QSourceTableView(QTableView):
+    """A large table: as tall as its place, its rows scrolled, each row of the same height.
+
+    The rows all have the height of a line of text, so the scroll bar's place gives the
+    rows shown with no row measured. The columns share the width. `header_clicked` emits
+    the column whose header the user clicked; the header shows the order
+    `set_sort_indicator` gives, the table never sorting its rows itself.
+
+    The table selects no row itself: `row_clicked` emits the position the user clicked,
+    or the current one on Space, and whether Shift extends the selection to it;
+    `row_activated` emits it on a double click, Enter or Return. `copy_requested` emits
+    on the platform's Copy shortcut (Ctrl+C), `export_requested` on `export_action`, in
+    the table's context menu.
+    """
+
+    header_clicked = Signal(int)
+    row_clicked = Signal(int, bool)
+    row_activated = Signal(int)
+    copy_requested = Signal()
+    export_requested = Signal()
+
+    def __init__(self, table: SourceTableLike) -> None:
+        super().__init__()
+        self._sort: Optional[tuple[int, bool]] = None
+        self.data_model = QSourceTableModel(table, self)
+        self.setModel(self.data_model)
+        self.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Expanding)
+        rows = self.verticalHeader()
+        rows.setSectionResizeMode(QHeaderView.ResizeMode.Fixed)
+        rows.setDefaultSectionSize(self.fontMetrics().height() + 10)
+        rows.setDefaultAlignment(Qt.AlignmentFlag.AlignRight | Qt.AlignmentFlag.AlignVCenter)
+        columns = self.horizontalHeader()
+        columns.setSectionResizeMode(QHeaderView.ResizeMode.Stretch)
+        columns.setDefaultAlignment(Qt.AlignmentFlag.AlignLeft | Qt.AlignmentFlag.AlignVCenter)
+        self.setShowGrid(False)
+        self.setAlternatingRowColors(True)
+        self.setSelectionMode(QAbstractItemView.SelectionMode.NoSelection)
+        columns.setSectionsClickable(True)
+        columns.sectionClicked.connect(self._header_clicked)
+        self.clicked.connect(self._row_clicked)
+        self.doubleClicked.connect(lambda index: self.row_activated.emit(index.row()))
+        self.export_action = QAction(self)
+        self.export_action.triggered.connect(self.export_requested.emit)
+        self.setContextMenuPolicy(Qt.ContextMenuPolicy.ActionsContextMenu)
+        self.addAction(self.export_action)
+
+    def keyPressEvent(self, event: QKeyEvent) -> None:  # noqa: N802
+        current = self.currentIndex()
+        if event.matches(QKeySequence.StandardKey.Copy):
+            self.copy_requested.emit()
+        elif current.isValid() and event.key() == Qt.Key.Key_Space:
+            is_extended = bool(event.modifiers() & Qt.KeyboardModifier.ShiftModifier)
+            self.row_clicked.emit(current.row(), is_extended)
+        elif current.isValid() and event.key() in (Qt.Key.Key_Return, Qt.Key.Key_Enter):
+            self.row_activated.emit(current.row())
+        else:
+            super().keyPressEvent(event)
+
+    def _row_clicked(self, index: QModelIndex) -> None:
+        modifiers = QApplication.keyboardModifiers()
+        self.row_clicked.emit(index.row(), bool(modifiers & Qt.KeyboardModifier.ShiftModifier))
+
+    def set_sort_indicator(self, sort: Optional[tuple[int, bool]]) -> None:
+        """Show the order: by a column, descending or not; None for the source's own."""
+        self._sort = sort
+        header = self.horizontalHeader()
+        header.setSortIndicatorShown(sort is not None)
+        if sort is not None:
+            column, is_descending = sort
+            order = Qt.SortOrder.DescendingOrder if is_descending else Qt.SortOrder.AscendingOrder
+            header.setSortIndicator(column, order)
+
+    def _header_clicked(self, column: int) -> None:
+        # the header flips its indicator on a click: the order is the view's to say
+        self.set_sort_indicator(self._sort)
+        self.header_clicked.emit(column)
+
+
+class QDataFilterTable(QWidget):
+    """A large table under its filter bar, which shows only while a column filters.
+
+    `export` shows the table's `export_action` above the rows, at their right, as the
+    web's link: the context menu alone hides it. When the search or the filters hide
+    every row, `empty` says so under the headers.
+    """
+
+    def __init__(self, table: SourceTableLike) -> None:
+        super().__init__()
+        self.bar = QTableFilterBar()
+        self.table = QSourceTableView(table)
+        self.export = QToolButton()
+        self.export.setDefaultAction(self.table.export_action)
+        self.export.setAutoRaise(True)
+        self.empty = plain_label()
+        self.empty.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        self.empty.setVisible(False)
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(0, 0, 0, 0)
+        layout.addWidget(self.bar)
+        layout.addWidget(self.export, 0, Qt.AlignmentFlag.AlignRight)
+        layout.addWidget(self.table, 1)
+        layout.addWidget(self.empty)
+        self.bar.setVisible(False)
+        self.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Expanding)

composeui/qtcore/widgets/qsplitter.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from qtpy.QtCore import Qt
+from qtpy.QtCore import Signal as QtSignal
+from qtpy.QtGui import QPainter, QPalette
+from qtpy.QtWidgets import QSplitter, QSplitterHandle
+
+if TYPE_CHECKING:
+    from qtpy.QtGui import QKeyEvent, QMouseEvent, QPaintEvent
+
+#: pixels an arrow key moves a focused handle by, as on the web
+KEY_STEP = 16
+
+
+class QSplitterBorder(QSplitterHandle):
+    """A splitter's handle the keyboard reaches too: the arrow keys move it once focused.
+
+    Qt's own handles take no focus, so only the mouse moves them.
+    """
+
+    def __init__(self, orientation: Qt.Orientation, parent: QComposeSplitter) -> None:
+        super().__init__(orientation, parent)
+        self.setFocusPolicy(Qt.FocusPolicy.StrongFocus)
+
+    def keyPressEvent(self, event: QKeyEvent) -> None:  # noqa: N802
+        if self.orientation() == Qt.Orientation.Vertical:
+            steps = {Qt.Key.Key_Up: -KEY_STEP, Qt.Key.Key_Down: KEY_STEP}
+            position = self.y()
+        else:
+            steps = {Qt.Key.Key_Left: -KEY_STEP, Qt.Key.Key_Right: KEY_STEP}
+            position = self.x()
+        step = steps.get(Qt.Key(event.key()))
+        if step is None:
+            super().keyPressEvent(event)
+            return
+        self.moveSplitter(position + step)
+        self._splitter().moved_by_user.emit()
+
+    def mouseReleaseEvent(self, event: QMouseEvent) -> None:  # noqa: N802
+        super().mouseReleaseEvent(event)
+        if event.button() == Qt.MouseButton.LeftButton:
+            self._splitter().moved_by_user.emit()
+
+    def paintEvent(self, event: QPaintEvent) -> None:  # noqa: N802
+        super().paintEvent(event)
+        if self.hasFocus():  # Qt's style draws no focus on a handle
+            painter = QPainter(self)
+            painter.fillRect(self.rect(), self.palette().color(QPalette.ColorRole.Highlight))
+
+    def _splitter(self) -> QComposeSplitter:
+        splitter = self.splitter()
+        assert isinstance(splitter, QComposeSplitter)
+        return splitter
+
+
+class QComposeSplitter(QSplitter):
+    """A splitter whose handles the keyboard moves too, telling once the user moved one.
+
+    `moved_by_user` reports the end of a drag, or a key's move, rather than each step
+    of a drag as `splitterMoved` does; never a change of `setSizes`.
+    """
+
+    #: the user dropped a handle they dragged, or moved one with a key
+    moved_by_user = QtSignal()
+
+    def createHandle(self) -> QSplitterHandle:  # noqa: N802
+        return QSplitterBorder(self.orientation(), self)