trackerkeeper 0.1.0__py3-none-any.whl

trackerkeeper/top_bar.py

@@ -0,0 +1,154 @@
+"""TopBar — the app's top bar, which doubles as the titlebar in borderless mode.
+
+A compact strip modelled on the dough shell: a hamburger menu + settings on the
+LEFT, then the app title and a status badge; on the right an app-fillable action
+slot, the update chip, and (when trackerkeeper owns the chrome) the minimize /
+maximize / close window controls. Dragging the bar moves the window
+(``startSystemMove``); double-click toggles maximize.
+
+Apps fold their OWN header controls onto this one line instead of a second row:
+``insert_title_widget()`` drops a badge beside the title, ``add_action()`` adds a
+right-side control (a button, a status label), and ``add_menu_action()`` extends
+the hamburger menu. See :class:`~trackerkeeper.dashboard.Dashboard`.
+"""
+
+from __future__ import annotations
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import QHBoxLayout, QLabel
+
+from trackerkeeper import ui_helpers
+from trackerkeeper.bus import AppBus
+from trackerkeeper.design_tokens import TYPE_SUBHEAD, type_qss
+from trackerkeeper.icon_button import IconButton
+from trackerkeeper.icons import icon
+
+
+class TopBar(ui_helpers.CenteredBar):
+    HEIGHT = 44
+    # The chrome-button footprint. Exported so app controls folded onto this bar
+    # (see Dashboard) can match it instead of guessing.
+    BUTTON_SIZE = (30, 26)
+
+    def __init__(self, window, *, titlebar_mode: bool, title: str = "trackerkeeper"):
+        super().__init__(window)
+        self._window = window
+        self._titlebar_mode = titlebar_mode
+        self._menu_actions: list = []
+        self.setFixedHeight(self.HEIGHT)
+        self.setStyleSheet("background: transparent;")
+
+        lay = QHBoxLayout(self)
+        lay.setContentsMargins(8, 5, 8, 5)
+        lay.setSpacing(5)
+
+        # ── left: hamburger menu + settings ──
+        self.menu_btn = self._chrome_button("menu", "Menu")
+        self.menu_btn.clicked.connect(self._open_menu)
+        lay.addWidget(self.menu_btn)
+        self.settings_btn = self._chrome_button("settings", "Settings")
+        self.settings_btn.clicked.connect(lambda: AppBus.get().show_settings.emit())
+        lay.addWidget(self.settings_btn)
+
+        # ── title, then a slot right after it for an app badge (update count) ──
+        self.title = QLabel(title)
+        lay.addWidget(self.title)
+        self._title_slot = QHBoxLayout()
+        self._title_slot.setContentsMargins(4, 0, 0, 0)
+        self._title_slot.setSpacing(6)
+        lay.addLayout(self._title_slot)
+
+        lay.addStretch(1)
+
+        # ── right: an app action slot (buttons / a status label) ──
+        self._action_slot = QHBoxLayout()
+        self._action_slot.setContentsMargins(0, 0, 0, 0)
+        self._action_slot.setSpacing(6)
+        lay.addLayout(self._action_slot)
+
+        # Update-available chip — invisible until trackerkeeper.updates finds a newer
+        # release (AppBus.update_available); Download / What's-new / Dismiss.
+        from trackerkeeper.update_chip import UpdateChip
+
+        self.update_chip = UpdateChip(self)
+        lay.addWidget(self.update_chip)
+
+        # Window controls only when we own the titlebar (borderless / frameless).
+        if titlebar_mode:
+            self.min_btn = self._chrome_button("win_minimize", "Minimize")
+            self.min_btn.clicked.connect(window.showMinimized)
+            self.max_btn = self._chrome_button("win_maximize", "Maximize")
+            self.max_btn.clicked.connect(self._toggle_max)
+            self.close_btn = self._chrome_button("win_close", "Close")
+            self.close_btn.clicked.connect(window.close)
+            for b in (self.min_btn, self.max_btn, self.close_btn):
+                lay.addWidget(b)
+
+        self.restyle()
+
+    # ── the app-fills-the-bar API ──────────────────────────────────────────
+    def insert_title_widget(self, widget) -> None:
+        """Add a widget immediately after the title (e.g. an update-count badge)."""
+        self._title_slot.addWidget(widget)
+
+    def add_action(self, widget) -> None:
+        """Append an app control to the right-side slot — left of the update chip
+        and the window buttons."""
+        self._action_slot.addWidget(widget)
+
+    def add_menu_action(self, label: str, callback) -> None:
+        """Add an entry to the hamburger menu (above the always-present Settings)."""
+        self._menu_actions.append((label, callback))
+
+    def _open_menu(self) -> None:
+        menu = ui_helpers.opaque_menu(self, blur_corner_radius=8)
+        for label, cb in self._menu_actions:
+            menu.addAction(label).triggered.connect(lambda _=False, c=cb: c())
+        if self._menu_actions:
+            menu.addSeparator()
+        menu.addAction("Settings…").triggered.connect(
+            lambda _=False: AppBus.get().show_settings.emit())
+        menu.exec(self.menu_btn.mapToGlobal(self.menu_btn.rect().bottomLeft()))
+
+    # ── chrome ─────────────────────────────────────────────────────────────
+    def _chrome_button(self, icon_name: str, tip: str) -> IconButton:
+        # accessible_name passed explicitly (the preferred pattern) even though
+        # the tooltip would fall back to the same string.
+        b = IconButton(accessible_name=tip)
+        b.setIcon(icon(icon_name))
+        b.setToolTip(tip)
+        b.setFixedSize(*self.BUTTON_SIZE)  # compact, dough-matched (was 36×32)
+        return b
+
+    def restyle(self) -> None:
+        """Re-read theme colors (call on AppBus.theme_changed) + refresh icons."""
+        self.title.setStyleSheet(f"color: {ui_helpers.TEXT}; {type_qss(TYPE_SUBHEAD)}")
+        for name, attr in (
+            ("menu", "menu_btn"),
+            ("settings", "settings_btn"),
+            ("win_minimize", "min_btn"),
+            ("win_maximize", "max_btn"),
+            ("win_close", "close_btn"),
+        ):
+            btn = getattr(self, attr, None)
+            if btn is not None:
+                btn.setIcon(icon(name))
+
+    def _toggle_max(self) -> None:
+        w = self._window
+        w.showNormal() if w.isMaximized() else w.showMaximized()
+
+    # ── Drag-to-move / double-click maximize (titlebar) ────────────────────
+    def mousePressEvent(self, e):
+        if self._titlebar_mode and e.button() == Qt.MouseButton.LeftButton:
+            handle = self._window.windowHandle()
+            if handle is not None:
+                handle.startSystemMove()
+                return
+        super().mousePressEvent(e)
+
+    def mouseDoubleClickEvent(self, e):
+        if self._titlebar_mode and e.button() == Qt.MouseButton.LeftButton:
+            self._toggle_max()
+            return
+        super().mouseDoubleClickEvent(e)

trackerkeeper/tray.py

@@ -0,0 +1,184 @@
+"""The system-tray presence — tracker keeper's resting state.
+
+A watchtower is only useful if it's *watching*, which means living in the tray
+rather than in a window you have to keep open. :class:`AppTray` puts the app
+there: an icon whose tooltip carries the current update count, a menu (Show /
+Check for updates / Settings / Quit), left-click to toggle the window, and an
+optional close-to-tray so the X button hides instead of quitting.
+
+Everything is best-effort and self-disabling: if the desktop has no tray
+(``isSystemTrayAvailable()`` False — headless, some wlroots sessions), nothing
+is created, ``available`` stays False, and the app behaves exactly as before —
+the close button never traps the window in an invisible process.
+
+Preferences live under the documented extension path (``get_settings()._s``), so
+no base settings file is touched:
+``app/show_tray_icon`` and ``app/close_to_tray``.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from PySide6.QtCore import QEvent, QObject
+from PySide6.QtGui import QIcon
+from PySide6.QtWidgets import QApplication, QSystemTrayIcon
+
+from trackerkeeper.bus import AppBus
+from trackerkeeper.settings import get_settings
+
+logger = logging.getLogger(__name__)
+
+_KEY_SHOW = "app/show_tray_icon"
+_KEY_CLOSE = "app/close_to_tray"
+
+
+def _as_bool(val, default: bool) -> bool:
+    if val is None:
+        return default
+    if isinstance(val, bool):
+        return val
+    return str(val).strip().lower() in ("1", "true", "yes", "on")
+
+
+def show_tray_icon() -> bool:
+    return _as_bool(get_settings()._s.value(_KEY_SHOW), True)
+
+
+def set_show_tray_icon(v: bool) -> None:
+    get_settings()._s.setValue(_KEY_SHOW, bool(v))
+
+
+def close_to_tray() -> bool:
+    """Close hides to the tray instead of quitting. On by default for a
+    watchtower — but only ever honoured while a tray icon is actually live."""
+    return _as_bool(get_settings()._s.value(_KEY_CLOSE), True)
+
+
+def set_close_to_tray(v: bool) -> None:
+    get_settings()._s.setValue(_KEY_CLOSE, bool(v))
+
+
+def tooltip_text(app_name: str, n_updates: int) -> str:
+    """The hover text: the fleet's headline, no window needed."""
+    if n_updates <= 0:
+        return f"{app_name} — all current"
+    return f"{app_name} — {n_updates} update{'s' if n_updates != 1 else ''} available"
+
+
+class AppTray(QObject):
+    """The tray icon + its menu. Construct with the main window; call
+    :meth:`set_update_count` whenever the fleet's update total changes."""
+
+    def __init__(self, window, *, app_name: str = "tracker keeper",
+                 on_refresh=None, parent=None):
+        super().__init__(parent or window)
+        self._window = window
+        self._app_name = app_name
+        self._on_refresh = on_refresh
+        self._quitting = False
+        self._icon: QSystemTrayIcon | None = None
+
+        if not (show_tray_icon() and QSystemTrayIcon.isSystemTrayAvailable()):
+            return
+
+        from trackerkeeper.ui_helpers import make_app_icon, opaque_menu
+
+        self._icon = QSystemTrayIcon(QIcon(make_app_icon(64)), self)
+        self._icon.setToolTip(tooltip_text(app_name, 0))
+
+        menu = opaque_menu(window, blur_corner_radius=8)
+        self._show_action = menu.addAction("Show tracker keeper")
+        self._show_action.triggered.connect(lambda _=False: self._toggle_window())
+        if on_refresh is not None:
+            menu.addAction("Check for updates").triggered.connect(
+                lambda _=False: on_refresh())
+        menu.addSeparator()
+        menu.addAction("Settings…").triggered.connect(
+            lambda _=False: AppBus.get().show_settings.emit())
+        menu.addAction("Quit").triggered.connect(lambda _=False: self.quit())
+        self._menu = menu
+        self._icon.setContextMenu(menu)
+        self._icon.activated.connect(self._on_activated)
+        self._icon.show()
+
+        # Hiding the last window must NOT end the process once we live in the
+        # tray — the app's whole point is to keep watching.
+        app = QApplication.instance()
+        if app is not None:
+            app.setQuitOnLastWindowClosed(False)
+        window.installEventFilter(self)
+
+    # ── state ──────────────────────────────────────────────────────────────
+    @property
+    def available(self) -> bool:
+        """True when a tray icon is actually live (desktop supports it and the
+        user hasn't turned it off). Everything else no-ops when False."""
+        return self._icon is not None
+
+    def set_update_count(self, n: int) -> None:
+        """Reflect the fleet's update total in the tooltip."""
+        if self._icon is not None:
+            self._icon.setToolTip(tooltip_text(self._app_name, n))
+
+    def notify(self, title: str, body: str) -> None:
+        """A tray balloon — the fallback when the OS notification backend
+        isn't available."""
+        if self._icon is not None:
+            self._icon.showMessage(title, body, QSystemTrayIcon.MessageIcon.Information)
+
+    # ── actions ────────────────────────────────────────────────────────────
+    def _on_activated(self, reason) -> None:
+        if reason in (QSystemTrayIcon.ActivationReason.Trigger,
+                      QSystemTrayIcon.ActivationReason.DoubleClick):
+            self._toggle_window()
+
+    def _toggle_window(self) -> None:
+        w = self._window
+        if w.isVisible() and not w.isMinimized():
+            self._hide_window()
+        else:
+            from trackerkeeper.single_instance import force_foreground
+
+            w.showNormal()
+            force_foreground(w)
+
+    def _hide_window(self) -> None:
+        # Geometry is normally persisted by the window's closeEvent — hiding
+        # skips that, so save it here or a tray-only session forgets its size.
+        try:
+            get_settings().save_geometry(self._window)
+        except Exception:
+            logger.debug("save_geometry on hide-to-tray failed", exc_info=True)
+        self._window.hide()
+
+    def quit(self) -> None:
+        """Really exit (the tray's Quit) — bypasses close-to-tray."""
+        self._quitting = True
+        try:
+            get_settings().save_geometry(self._window)
+        except Exception:
+            logger.debug("save_geometry on quit failed", exc_info=True)
+        if self._icon is not None:
+            self._icon.hide()
+        app = QApplication.instance()
+        if app is not None:
+            app.quit()
+
+    # ── close-to-tray ──────────────────────────────────────────────────────
+    def eventFilter(self, obj, event):  # noqa: N802 (Qt override)
+        # Guard order matters: bail out on the no-tray / quitting cases BEFORE
+        # touching the event, so the filter is inert (and safe) when there's no
+        # tray to hide into.
+        if (
+            self.available
+            and not self._quitting
+            and obj is self._window
+            and close_to_tray()
+            and event is not None
+            and event.type() == QEvent.Type.Close
+        ):
+            event.ignore()
+            self._hide_window()
+            return True
+        return False