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

usingOlbrasoft.Linux.SystemTray;usingMicrosoft.Extensions.Logging;// Create logger and icon renderervarloggerFactory=LoggerFactory.Create(builder =>builder.AddConsole());varlogger=loggerFactory.CreateLogger<TrayIcon>();variconRenderer=newIconRenderer(loggerFactory.CreateLogger<IconRenderer>());// Create tray iconvartrayIcon=newTrayIcon(logger,iconRenderer,"my-app");awaittrayIcon.InitializeAsync();// Set icontrayIcon.SetIcon("/path/to/icon.svg","My Application");// Handle clickstrayIcon.Clicked+=(sender,args)=>Console.WriteLine("Icon clicked!");// CleanuptrayIcon.Dispose();

Animated Icon

// Pre-cache animation framesstring[]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 animationtrayIcon.StopAnimation();

Multiple Icons

varmanager=newTrayIconManager(loggerFactory.CreateLogger<TrayIconManager>(),loggerFactory,iconRenderer);// Create left hand iconvarleftIcon=awaitmanager.CreateIconAsync("left-hand","/icons/left-hand.svg","Left Hand Gesture");// Create robot iconvarrobotIcon=awaitmanager.CreateIconAsync("robot","/icons/robot.svg","Main App");// Create right hand iconvarrightIcon=awaitmanager.CreateIconAsync("right-hand","/icons/right-hand.svg","Right Hand Gesture");// Later: remove specific iconmanager.RemoveIcon("left-hand");// Cleanup all iconsmanager.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)