# Cross-platform Linux/Windows/MacOS Tray

<img src="screenshot_macosx.png">

<img src="screenshot_windows.png">

<img src="screenshot_linux.png">

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

Works well on:

* Linux/Gtk (libappindicator)
* Windows XP or newer (shellapi.h)
* MacOS (Cocoa/AppKit)

The code is C++ friendly and will compile fine in C++98 and up.

This repository started as a fork of the [original work by Serge Zaitsev](https://github.com/zserge/tray), but it is now maintained as a separate continuation. It keeps the small public C API and cross-platform focus, while carrying its own fixes and behavior changes.

Compared to the original upstream, this fork already includes and continues work around:

* improved Windows message handling
* C++-friendly headers and usage
* tooltip support
* checkbox/menu state fixes
* Darwin/AppKit support adapted from the [@trevex fork](https://github.com/trevex/tray)
* support for left-click callbacks
* Windows UTF-8 tray text handling

## Prerequisites

* CMake
* [Ninja](https://ninja-build.org/), in order to have the same build commands on all platforms
* AppIndicator on Linux:

```
sudo apt install libappindicator3-dev
```

## Building

```
mkdir build
cd build
cmake -G Ninja ..
ninja
```

## Demo

Execute the `tray_example` application:

```
./tray_example
```

## API

A tray is defined by an icon, an optional tooltip and a menu.
The menu is a NULL-terminated array of items.
Each menu item can be disabled, checked, represented as a checkbox and invoke a
callback with an optional context pointer.

```c
struct tray {
  const char *icon;
  char *tooltip;
  struct tray_menu *menu;
  void *icon_handle;
  int icon_is_shared;
  void (*left_click_cb)(void *context);
  void *left_click_context;
};

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

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

  struct tray_menu *submenu;
};
```

* `int tray_init(struct tray *)` - creates the tray icon and its menu. Returns `-1` if the tray icon or menu cannot be created.
* `void tray_update(struct tray *)` - updates the tray icon, tooltip and menu state.
* `int tray_loop(int blocking)` - runs one iteration of the UI loop. Returns `-1` after `tray_exit()` has been called.
* `void tray_exit(void)` - terminates the UI loop and cleans up tray resources.

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

Menu arrays must be terminated with a NULL item, i.e. the last item in the
array must have `text == NULL`.

### Notes

* `tooltip` is optional.
* `left_click_cb` and `left_click_context` are optional.
* `icon_handle` and `icon_is_shared` are backend-specific fields used internally by the Windows implementation and should usually be left untouched by callers.
* A separator is created by using `text = "-"`.
* Some behavior may depend on the underlying backend or desktop environment.
  Keep the public API generic and treat platform-specific interaction details as
  backend-specific implementation behavior.

## License

This software is distributed under [MIT license](http://www.opensource.org/licenses/mit-license.php),
 so feel free to integrate it in your commercial products.