Skip to content

Commit 9db55bd

Browse files
dmikushindmikushin
committed
Adding KDE screenshot by @jinzhongjia 
1 parent a900052 commit 9db55bd

File tree

3 files changed

+128
-126
lines changed

3 files changed

+128
-126
lines changed

Diff for: ‎README.md

+128-126
Original file line numberDiff line numberDiff line change
@@ -1,126 +1,128 @@
1-
# System Tray / Menu Bar / Indicator Icon
2-
3-
![MacOS screenshot](./screenshot_macosx.png)
4-
5-
![Windows screenshot](./screenshot_windows.png)
6-
7-
![Linux screenshot](./screenshot_linux.png)
8-
9-
Cross-platform, super tiny[^1] C99-based implementation of a system tray/menu bar icon with popup menu.
10-
11-
[^1]: It's super tiny on both Mac & Windows.
12-
13-
The optional primary-click callback can hide/show a window while secondary-click shows a menu, or if
14-
no callback is specified, either click will show the menu. The system can be dynamically
15-
updated; icon, tooltip, menu item text and status (checked/unchecked & enabled/disabled) can all be
16-
both queried and changed at runtime.
17-
18-
Code is C++ friendly and will compile fine in C99 or C++98 and up on Windows, Objective-C on Mac but C++20 on Linux.
19-
20-
Focussed PRs are welcome, especially improvements to the Linux implementation. The goal is to
21-
keep the code as simple as possible, so functionality beyond presenting a tray icon and menu is
22-
out of scope.
23-
24-
## Cross-platform
25-
26-
Works well on:
27-
28-
* Windows XP or newer (shellapi.h)
29-
* MacOS (Cocoa/AppKit)
30-
* Linux/Gtk (Qt6)
31-
32-
GNOME has decided to deprecate the tray icon as a concept, except for system indicators. They have
33-
not only deprecated the tray-handling code but removed it entirely. Extensive investigation has
34-
failed to produce a reliable way to display tray icons, even using low-level X11 calls. Qt _has_
35-
worked out a way to do it, so we are currently using their implementation on Linux, which
36-
unfortunately requires C++ and much larger dependencies. All of the Qt code is isolated in the
37-
library, so use of Qt is not required in application code (although it will use the application's
38-
QApplication instance, should one exist).
39-
40-
PRs that resolve this situation are very welcome!
41-
42-
## API
43-
44-
The `tray` structure defines the tray and a nested menu of NULL-terminated array of entries.
45-
`tray_menu_item` defines each menu entry text, menu checked and disabled (grayed) flags.
46-
47-
The `tray` and `tray_menu_item` each have an optional callback if they are selected.
48-
49-
```c
50-
struct tray {
51-
const char *icon_filepath;
52-
char *tooltip;
53-
void (*cb)(struct tray *); // called on left click, leave null to just open menu
54-
struct tray_menu_item *menu; // NULL-terminated array of menu items
55-
};
56-
57-
struct tray_menu_item {
58-
char *text;
59-
int disabled;
60-
int checked;
61-
void (*cb)(struct tray_menu_item *);
62-
struct tray_menu_item *submenu; // NULL-terminated array of submenu items
63-
};
64-
```
65-
66-
* `int tray_init(struct tray *)` - creates tray icon. Returns -1 if tray icon/menu can't be created.
67-
* `struct tray * tray_get_instance()` - returns the tray instance.
68-
* `void tray_update(struct tray *)` - updates tray icon and menu.
69-
* `int tray_loop(int blocking)` - runs one iteration of the UI loop. Returns -1 if `tray_exit()` has been called.
70-
* `void tray_exit()` - terminates UI loop.
71-
72-
All functions are meant to be called from the UI thread only.
73-
74-
Menu arrays must be terminated with a NULL item, e.g. the last item in the
75-
array must have text field set to NULL.
76-
77-
## Icons
78-
79-
Icons are platform-specific but generally should have transparent backgrounds and be simple (since
80-
they are tiny).
81-
82-
Tray does not provide any theming or icon management. It is up to the application to respond
83-
to theme changes and supply appropriate icons e.g. dark mode.
84-
85-
| Platform | Icon format |
86-
|---------|:----------------------------------------------------------------------------------------|
87-
| Windows | .ICO with 16x16 & 32x32 sizes included |
88-
| MacOS | .PNG with a notional 22pt height or vector-based .PDF (recommend black or white images) |
89-
| Linux | .PNG 24x24 pixels |
90-
91-
## Prerequisites
92-
93-
* CMake
94-
* [Ninja](https://ninja-build.org/), in order to have the same build commands on all platforms
95-
* Qt6 on Linux: `sudo apt install build-essential libgl1-mesa-dev qt6-base-dev`
96-
97-
## Building
98-
99-
```
100-
mkdir build
101-
cd build
102-
cmake -G Ninja ..
103-
ninja
104-
```
105-
106-
## Demo
107-
108-
Build & execute the `tray_example` application:
109-
110-
```
111-
./tray_example
112-
```
113-
114-
## History
115-
116-
This fork brings together the [original work of Serge Zaitsev](https://github.com/zserge/tray) and
117-
the most interesting forks and PRs of respectable contributors including:
118-
119-
* Numerous enhancements from [StirlingLabs](https://github.com/StirlingLabs/tray) to make the functionality
120-
available as a library, for use from other languages.
121-
* [Only process messages coming from the tray window on Windows](https://github.com/zserge/tray/pull/18)
122-
* [Become C++-friendly](https://github.com/zserge/tray/pull/16)
123-
* [Fix all menu items have a check box](https://github.com/zserge/tray/pull/11)
124-
* [Add support for tooltip](https://github.com/zserge/tray/pull/11)
125-
* Darwin implementation translated from C to Objective C adapted from [@trevex fork](https://github.com/trevex/tray)
126-
1+
# System Tray / Menu Bar / Indicator Icon
2+
3+
![MacOS screenshot](./screenshot_macosx.png)
4+
5+
![Windows screenshot](./screenshot_windows.png)
6+
7+
![GNOME screenshot](./screenshot_gnome.png)
8+
9+
![KDE screenshot](./screenshot_kde.png)
10+
11+
Cross-platform, super tiny[^1] C99-based implementation of a system tray/menu bar icon with popup menu.
12+
13+
[^1]: It's super tiny on both Mac & Windows.
14+
15+
The optional primary-click callback can hide/show a window while secondary-click shows a menu, or if
16+
no callback is specified, either click will show the menu. The system can be dynamically
17+
updated; icon, tooltip, menu item text and status (checked/unchecked & enabled/disabled) can all be
18+
both queried and changed at runtime.
19+
20+
Code is C++ friendly and will compile fine in C99 or C++98 and up on Windows, Objective-C on Mac but C++20 on Linux.
21+
22+
Focussed PRs are welcome, especially improvements to the Linux implementation. The goal is to
23+
keep the code as simple as possible, so functionality beyond presenting a tray icon and menu is
24+
out of scope.
25+
26+
## Cross-platform
27+
28+
Works well on:
29+
30+
* Windows XP or newer (shellapi.h)
31+
* MacOS (Cocoa/AppKit)
32+
* Linux/Gtk (Qt6)
33+
34+
GNOME has decided to deprecate the tray icon as a concept, except for system indicators. They have
35+
not only deprecated the tray-handling code but removed it entirely. Extensive investigation has
36+
failed to produce a reliable way to display tray icons, even using low-level X11 calls. Qt _has_
37+
worked out a way to do it, so we are currently using their implementation on Linux, which
38+
unfortunately requires C++ and much larger dependencies. All of the Qt code is isolated in the
39+
library, so use of Qt is not required in application code (although it will use the application's
40+
QApplication instance, should one exist).
41+
42+
PRs that resolve this situation are very welcome!
43+
44+
## API
45+
46+
The `tray` structure defines the tray and a nested menu of NULL-terminated array of entries.
47+
`tray_menu_item` defines each menu entry text, menu checked and disabled (grayed) flags.
48+
49+
The `tray` and `tray_menu_item` each have an optional callback if they are selected.
50+
51+
```c
52+
struct tray {
53+
const char *icon_filepath;
54+
char *tooltip;
55+
void (*cb)(struct tray *); // called on left click, leave null to just open menu
56+
struct tray_menu_item *menu; // NULL-terminated array of menu items
57+
};
58+
59+
struct tray_menu_item {
60+
char *text;
61+
int disabled;
62+
int checked;
63+
void (*cb)(struct tray_menu_item *);
64+
struct tray_menu_item *submenu; // NULL-terminated array of submenu items
65+
};
66+
```
67+
68+
* `int tray_init(struct tray *)` - creates tray icon. Returns -1 if tray icon/menu can't be created.
69+
* `struct tray * tray_get_instance()` - returns the tray instance.
70+
* `void tray_update(struct tray *)` - updates tray icon and menu.
71+
* `int tray_loop(int blocking)` - runs one iteration of the UI loop. Returns -1 if `tray_exit()` has been called.
72+
* `void tray_exit()` - terminates UI loop.
73+
74+
All functions are meant to be called from the UI thread only.
75+
76+
Menu arrays must be terminated with a NULL item, e.g. the last item in the
77+
array must have text field set to NULL.
78+
79+
## Icons
80+
81+
Icons are platform-specific but generally should have transparent backgrounds and be simple (since
82+
they are tiny).
83+
84+
Tray does not provide any theming or icon management. It is up to the application to respond
85+
to theme changes and supply appropriate icons e.g. dark mode.
86+
87+
| Platform | Icon format |
88+
|---------|:----------------------------------------------------------------------------------------|
89+
| Windows | .ICO with 16x16 & 32x32 sizes included |
90+
| MacOS | .PNG with a notional 22pt height or vector-based .PDF (recommend black or white images) |
91+
| Linux | .PNG 24x24 pixels |
92+
93+
## Prerequisites
94+
95+
* CMake
96+
* [Ninja](https://ninja-build.org/), in order to have the same build commands on all platforms
97+
* Qt6 on Linux: `sudo apt install build-essential libgl1-mesa-dev qt6-base-dev`
98+
99+
## Building
100+
101+
```
102+
mkdir build
103+
cd build
104+
cmake -G Ninja ..
105+
ninja
106+
```
107+
108+
## Demo
109+
110+
Build & execute the `tray_example` application:
111+
112+
```
113+
./tray_example
114+
```
115+
116+
## History
117+
118+
This fork brings together the [original work of Serge Zaitsev](https://github.com/zserge/tray) and
119+
the most interesting forks and PRs of respectable contributors including:
120+
121+
* Numerous enhancements from [StirlingLabs](https://github.com/StirlingLabs/tray) to make the functionality
122+
available as a library, for use from other languages.
123+
* [Only process messages coming from the tray window on Windows](https://github.com/zserge/tray/pull/18)
124+
* [Become C++-friendly](https://github.com/zserge/tray/pull/16)
125+
* [Fix all menu items have a check box](https://github.com/zserge/tray/pull/11)
126+
* [Add support for tooltip](https://github.com/zserge/tray/pull/11)
127+
* Darwin implementation translated from C to Objective C adapted from [@trevex fork](https://github.com/trevex/tray)
128+

Diff for: ‎screenshot_linux.png renamed to ‎screenshot_gnome.png

File renamed without changes.

Diff for: ‎screenshot_kde.png

29.8 KB
Loading

0 commit comments

Comments
 (0)