Overview

About

Cross-platform, super tiny C99 implementation of a system tray icon with a popup menu and notifications.

The code is C++ friendly and will compile fine in C++98 and up. This is a fork of dmikushin/tray and is intended to add additional features required for our own Sunshine project.

This fork adds the following features:

• system tray notifications
• unit tests
• code coverage
• refactored code, e.g., moved source code into the src directory
• doxygen documentation and readthedocs configuration

Screenshots

• Linux
• macOS
• Windows

Supported platforms

• Linux/Qt (Qt5 or Qt6 Widgets)
• Windows XP or newer (shellapi.h)
• MacOS (Cocoa/AppKit)

Prerequisites

• CMake
• Ninja, to have the same build commands on all platforms.

Linux Dependencies

Install either Qt6 or Qt5 development packages. The Linux backend requires Qt Widgets, DBus, and Svg modules.

• Arch

  # Qt6
  sudo pacman -S qt6-base qt6-svg
  
  # Qt5
  sudo pacman -S qt5-base qt5-svg

• Debian/Ubuntu

  # Qt6
  sudo apt install qt6-base-dev qt6-svg-dev
  
  # Qt5
  sudo apt install qtbase5-dev libqt5svg5-dev

• Fedora

  # Qt6
  sudo dnf install qt6-qtbase-devel qt6-qtsvg-devel
  
  # Qt5
  sudo dnf install qt5-qtbase-devel qt5-qtsvg-devel

Building

mkdir -p build
cmake -G Ninja -B build -S .
ninja -C build

Demo

Execute the tray_example application:

./build/tray_example

Tests

Execute the tests application:

./build/tests/test_tray

API

Tray structure defines an icon and a menu. Menu is a NULL-terminated array of items. Menu item defines menu text, menu checked and disabled (grayed) flags and a callback with some optional context pointer.

struct tray {
  char *icon;
  struct tray_menu *menu;
};

struct tray_menu {
  char *text;
  int disabled;
  int checked;

  void (*cb)(struct tray_menu *);
  void *context;

  struct tray_menu *submenu;
};

• int tray_init(struct tray *) - creates tray icon. Returns -1 if tray icon/menu can't be created.
• void tray_update(struct tray *) - updates tray icon and menu.
• int tray_loop(int blocking) - runs one iteration of the UI loop. Returns -1 if tray_exit() has been called.
• void tray_exit() - terminates UI loop.

All functions are meant to be called from the UI thread only.

Menu arrays must be terminated with a NULL item, e.g. the last item in the array must have text field set to NULL.

License

This software is distributed under MIT license, so feel free to integrate it in your commercial products.

[TOC]