status-notifier-item
A wrapper over the StatusNotifierItem/libappindicator dbus specification
https://github.com/taffybar/status-notifier-item#readme
| LTS Haskell 24.50: | 0.3.2.15 |
| Stackage Nightly 2026-07-16: | 0.3.2.16 |
| Latest on Hackage: | 0.3.2.16 |
status-notifier-item-0.3.2.16@sha256:cd648b070b77d7f17c4b099d3563187b7c2fb4090935f09c8a5013166846ba03,3113Module documentation for 0.3.2.16
- StatusNotifier
- StatusNotifier.Host
- StatusNotifier.Item
- StatusNotifier.TH
- StatusNotifier.Util
- StatusNotifier.Watcher
status-notifier-item
The status-notifier-item package provides a haskell implementation of the status-notifier-item/app-indicator protocol.
StatusNotifierHost
The host server implementation provided is partial in the sense that it is headless (provides no graphical interface), and it is supposed to be used together with UI code that handles actually displaying a tray. The gtk-sni-tray provides a gtk tray widget that is implemented using the status-notifier-item library. taffybar Uses gtk-sni-tray to provide a tray widget that can be used with the many other widgets it offers.
StatusNotifierWatcher
This package provides a standalone status-notifier-watch binary that can be run on its own to handle the registration of status-notifier-items. By default, it is necessary to run this binary before starting either taffybar or gtk-sni-tray, becuase the trays provided in those binaries do not handle this responsibility. If this is not done, those binaries will fail at startup with this message:
MethodError {methodErrorName = ErrorName "org.freedesktop.DBus.Error.ServiceUnknown", methodErrorSerial = Serial 7, methodErrorSender = Just (BusName "org.freedesktop.DBus"), methodErrorDestination = Just (BusName ":1.549"), methodErrorBody = [Variant "The name org.kde.StatusNotifierWatcher was not provided by any .service files"]}
A client library is also provided for the StatusNotifierWatcher protocol
StatusNotifierItem
This package provides a client library for calling into status notifier items. It also provides a sample implementation of the server side of the StatusNotifierItem protocol as well as a status-notifier-item-static binary that uses this implementation. This binary can be used to test host and watcher implementations, but it mostly just serves as an example of how to implement the protocol using this library, as it does not really do anything useful.
Changes
Changelog for status-notifier-item
Unreleased
0.3.2.16 - 2026-07-15
- Host: normalize the random
Id, item path, and menu path generated by Ayatana StatusNotifierItem implementations when building logical duplicate keys. Multiple instances of the same application now collapse to one tray item even when each instance advertises a different generated identity. - Add regression coverage for generated Ayatana identities while preserving distinct identities for ordinary StatusNotifierItems.
0.3.2.15 - 2026-07-02
- Bound every DBus call made during host and watcher startup with a timeout so
a single unresponsive item (a process that owns its
StatusNotifierItembus name but never services its connection) can no longer hang startup indefinitely. Previously such an item would blockHost.build(and any tray UI built from it) and the watcher’s cache-validation pass forever, since thedbuslibrary does not time out method calls on its own. - Watcher: bound the per-item introspection performed while validating cached items during startup; unresponsive items are dropped instead of blocking the watcher before it exports its object.
- Host: bound the per-item property fetch in
buildItemInfoand theRegisterStatusNotifierHost/RegisteredStatusNotifierItemswatcher calls.
0.3.2.14 - 2026-05-13
- Clean up generated DBus client, service, and watcher code for newer compiler warning compatibility.
- Keep watcher startup behavior unchanged after reverting an experimental synchronous startup path.
0.3.2.13 - 2026-03-30
- Host: suppress no-op property update notifications when a signal arrives but the refreshed item value is unchanged, avoiding redundant tray updates.
- Add a regression test covering unchanged-vs-changed
NewTitleupdates.
0.3.2.12 - 2026-03-30
- Fix the
HostSpectest helper’s overloaded-string inference so the test suite builds cleanly with newer GHC/dbuscombinations, restoring the status-notifier-item Stackage nightly upgrade path.
0.3.2.11 - 2026-03-29
- Watcher: accept explicit SNI registrations initiated from a separate unique bus name owned by the same process, fixing KDE/Qt multi-connection registrations.
- Host: deduplicate logical items across bus-name churn so tray hosts keep a single logical icon when senders change identity.
- Add regression tests for the multi-connection registration and bus-name churn deduplication cases.
0.3.2.10 - 2026-02-17
- Relax upper bounds to restore Stackage nightly compatibility:
optparse-applicative < 0.20andtemplate-haskell < 2.24.
0.3.2.9 - 2026-02-17
- Version bump only; no library changes beyond
0.3.2.8.
0.3.2.8 - 2026-02-17
- Host: eliminate duplicate
ItemAddeddeliveries to newly-registered update handlers by making handler registration + initial replay atomic with respect to item map updates. - Add a deterministic host integration test that reproduces and guards against
duplicate
ItemAddedevents from replay/live-update races.
0.3.2.7 - 2026-02-13
- Watcher: default
--log-levelis now INFO. - Watcher: log item/host registrations at INFO; keep per-request method/property tracing at DEBUG to avoid spamming.
- Host: downgrade noisy INFO/WARNING logs (signal dumps, handler updates, and expected removal/mismatch cases) to DEBUG.
0.3.2.6 - 2026-02-13
- Watcher: persist item/host registrations to an XDG cache JSON file and restore on startup with validation (bus owner + object/interface checks).
- Watcher: keep persisted state in sync across registrations/unregistrations and deduplicate/replace owner-equivalent path registrations.
- Host: reconcile item state when watcher ownership changes so stale items are removed after watcher restarts.
- Add integration tests for cache restore, stale-cache pruning, post-restore deduplication, and host watcher-owner-change reconciliation.
0.3.2.5 - 2026-02-12
- Test suite: start an isolated
dbus-daemonusing a session config shipped alongside thedbus-daemonexecutable when available (fixes Nix sandbox builds where/etc/dbus-1/session.confis absent).
0.3.2.4 - 2026-02-12
- Host: deduplicate items that re-register under a different bus name after a watcher restart (e.g. unique name vs well-known name), preventing duplicate tray icons.
- Add a regression test for watcher-restart re-registration deduplication.
0.3.2.3 - 2026-02-11
- Downgrade unknown-sender update logs from WARNING to DEBUG to avoid noisy false alarms for routine tray signals.
- Treat UnknownMethod property refresh failures as expected optional-property misses (same as InvalidArgs), logging them at DEBUG unless no updater succeeded.
- Add host tests for property update failure log-level classification.
0.3.2.2 - 2026-02-11
- Fix watcher registration ownership checks by requiring explicit service-name registrations to be initiated by the current owner.
- Fix watcher duplicate handling by coalescing path-first and name-first registrations from the same sender/path pair.
- Add an isolated DBus integration test suite covering watcher/host behavior and regression tests for registration ownership and deduplication.
0.3.2.1 - 2026-02-09
- Add name-owner resolution fallback for signal sender identification, fixing noisy errors when items register under well-known bus names.
- Downgrade “Failed to identify sender” log from ERROR to DEBUG when the item simply does not implement the getId method.
- Downgrade “Property update failures” log from ERROR to DEBUG when the failures are InvalidArgs (item does not support optional properties like OverlayIcon).
0.3.2.0 - 2026-02-05
- Report full
bus/pathidentifiers for non-default SNI object paths so hosts can resolve Ayatana items reliably. - Accept
bus/pathidentifiers in watcher/host lookups for compatibility with pathful registrations.