Olbrasoft.SystemTray.Linux

A modern .NET library for creating system tray icons on Linux using the D-Bus StatusNotifierItem protocol.

Features

• ✅ Clean C# API - Hides D-Bus complexity behind simple interfaces
• ✅ Dynamic Icon Changes - Update icons on-the-fly
• ✅ Animations - Frame-based icon animations with customizable intervals
• ✅ Multiple Icons - Display multiple tray icons simultaneously (like GestureEvolution's 3-hand approach)
• ✅ SVG Support - Renders SVG icons to ARGB pixmaps using SkiaSharp
• ✅ Cache Busting - Workarounds for GNOME Shell icon caching issues
• ✅ .NET 10 - Built for the latest .NET

Installation

dotnet add package Olbrasoft.SystemTray.Linux

Quick Start

Single Icon

using Olbrasoft.Linux.SystemTray;
using Microsoft.Extensions.Logging;

// Create logger and icon renderer
var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole());
var logger = loggerFactory.CreateLogger<TrayIcon>();
var iconRenderer = new IconRenderer(loggerFactory.CreateLogger<IconRenderer>());

// Create tray icon
var trayIcon = new TrayIcon(logger, iconRenderer, "my-app");
await trayIcon.InitializeAsync();

// Set icon
trayIcon.SetIcon("/path/to/icon.svg", "My Application");

// Handle clicks
trayIcon.Clicked += (sender, args) => Console.WriteLine("Icon clicked!");

// Cleanup
trayIcon.Dispose();

Animated Icon

// Pre-cache animation frames
string[] frames = new[]
{
    "/path/to/frame1.svg",
    "/path/to/frame2.svg",
    "/path/to/frame3.svg"
};

// Start animation (150ms interval)
trayIcon.StartAnimation(frames, intervalMs: 150, tooltip: "Working...");

// Stop animation
trayIcon.StopAnimation();

Multiple Icons

var manager = new TrayIconManager(
    loggerFactory.CreateLogger<TrayIconManager>(),
    loggerFactory,
    iconRenderer
);

// Create left hand icon
var leftIcon = await manager.CreateIconAsync(
    "left-hand",
    "/icons/left-hand.svg",
    "Left Hand Gesture"
);

// Create robot icon
var robotIcon = await manager.CreateIconAsync(
    "robot",
    "/icons/robot.svg",
    "Main App"
);

// Create right hand icon
var rightIcon = await manager.CreateIconAsync(
    "right-hand",
    "/icons/right-hand.svg",
    "Right Hand Gesture"
);

// Later: remove specific icon
manager.RemoveIcon("left-hand");

// Cleanup all icons
manager.Dispose();

Architecture

This library is based on the D-Bus StatusNotifierItem protocol, which is the modern standard for system tray icons on Linux (replacing the deprecated X11 system tray).

Key Components

• ITrayIcon - Main interface for single tray icon
• ITrayIconManager - Manager for multiple simultaneous icons
• IIconRenderer - SVG to ARGB rendering with caching
• StatusNotifierItemHandler - Internal D-Bus protocol implementation

D-Bus Workarounds

The library implements several workarounds for GNOME Shell icon caching issues:

1. Timestamp in Icon ID - Changes icon ID with timestamp during animations
2. Signal Re-emission - Re-emits D-Bus signals after delays for slow shells
3. Unique Connection Names - Uses D-Bus unique names to avoid duplicate detection

Requirements

• .NET 10 or later
• Linux with D-Bus session bus
• StatusNotifierWatcher service (provided by GNOME Shell, KDE Plasma, or standalone)

Dependencies

• Tmds.DBus.Protocol - D-Bus communication
• SkiaSharp - SVG rendering
• Svg.Skia - SVG loading
• Microsoft.Extensions.Logging - Logging abstraction

Background

This library was extracted from three Olbrasoft projects:

1. PushToTalk - Advanced D-Bus implementation with cache busting
2. VirtualAssistant - GTK/AppIndicator approach
3. GestureEvolution - Multiple simultaneous icons (3 hands/robot)

The goal was to create a reusable NuGet package that other applications can easily integrate without copying D-Bus boilerplate code.

License

MIT

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

Credits

Based on Avalonia's DBusTrayIconImpl:

• https://github.com/AvaloniaUI/Avalonia/blob/master/src/Avalonia.FreeDesktop/DBusTrayIconImpl.cs

Developed by Olbrasoft (https://olbrasoft.cz)