2014-11-03 02:10:18 +01:00
SystemTray
==========
2014-11-04 12:32:04 +01:00
Cross-platform **SystemTray** and **AppIndicator** support for java applications.
2014-11-03 02:10:18 +01:00
2014-11-03 02:18:28 +01:00
This libraries only purpose is to show *reasonably* decent system-tray icons and app-indicators with a simple popup-menu.
2014-11-03 02:10:18 +01:00
2014-11-04 12:32:04 +01:00
There are a number of problems on Linux with the Swing (and SWT) system-tray icons, namely that:
1. Swing system-tray icons on linux **do not** support transparent backgrounds (they have a white background)
2015-10-28 16:34:27 +01:00
2. Swing/SWT **do not** support app-indicators, which are necessary on more recent versions of gnu/linux distros.
2015-11-09 16:13:57 +01:00
3. Swing popup menus look like crap
2015-08-19 16:06:30 +02:00
- swing-based system-tray uses a JMenuPopup, which looks nicer than the java 'regular' one.
2015-10-28 16:34:27 +01:00
- app-indicators use native popups.
- gtk-indicators use native popups.
2014-11-04 12:32:04 +01:00
2014-11-03 02:10:18 +01:00
2014-11-04 12:32:04 +01:00
This is for cross-platform use, specifically - linux 32/64, mac 32/64, and windows 32/64. Java 6+
2014-11-03 02:10:18 +01:00
2015-11-15 14:51:47 +01:00
We also cater to the *lowest-common-denominator* when it comes to system-tray/indicator functionality, and there are some features that we don't support.
2016-02-13 15:06:19 +01:00
Specifically: **tooltips** . Rather a stupid decision, IMHO, but for more information why, ask Mark Shuttleworth.
2015-11-15 14:51:47 +01:00
See: https://bugs.launchpad.net/indicator-application/+bug/527458/comments/12
2016-02-13 17:47:18 +01:00
Please be aware: JavaFX uses **GTK2** , and so `GtkSupport.FORCE_GTK2` should be enabled if you plan on using this + javaFX.
2015-01-23 02:52:09 +01:00
```
2015-10-28 16:34:27 +01:00
Customization parameters:
2015-11-20 12:25:30 +01:00
SystemTrayMenuPopup.POPUP_HIDE_DELAY (type long, default value '1000L')
2015-10-28 16:34:27 +01:00
- Allows you to customize the delay (for hiding the popup) when the cursor is "moused out" of the popup menu
2015-10-29 02:26:01 +01:00
2015-10-28 16:34:27 +01:00
GnomeShellExtension.ENABLE_SHELL_RESTART (type boolean, default value 'true')
- Permit the gnome-shell to be restarted when the extension is installed.
GnomeShellExtension.SHELL_RESTART_TIMEOUT_MILLIS (type long, default value '5000L')
- Default timeout to wait for the gnome-shell to completely restart. This is a best-guess estimate.
GnomeShellExtension.SHELL_RESTART_COMMAND (type String, default value 'gnome-shell --replace & ')
- Command to restart the gnome-shell. It is recommended to start it in the background (hence '& ')
SystemTray.TRAY_SIZE (type int, default value '24')
2015-11-09 16:13:57 +01:00
- Size of the tray, so that the icon can properly scale based on OS. (if it's not exact). This only applies for Swing tray icons.
2015-10-28 16:34:27 +01:00
- NOTE: Must be set after any other customization options, as a static call to SystemTray will cause initialization of the library.
2016-02-13 15:06:19 +01:00
2016-02-13 17:39:10 +01:00
GtkSupport.FORCE_GTK2 (type boolean, default value 'false')
2016-02-13 17:47:18 +01:00
- Forces the system to always choose GTK2 (even when GTK3 might be available). JavaFX uses GTK2!
2015-11-09 20:06:06 +01:00
```
2015-01-23 02:52:09 +01:00
2015-01-31 01:52:27 +01:00
2015-11-09 20:06:06 +01:00
The test application is [on GitHub ](https://github.com/dorkbox/SystemTray/blob/master/test/dorkbox/TestTray.java ), and a *simple* example is as follows:
```
2016-02-12 02:30:33 +01:00
this.systemTray = SystemTray.getSystemTray();
if (systemTray == null) {
throw new RuntimeException("Unable to load SystemTray!");
}
2015-06-28 01:50:27 +02:00
2016-02-12 02:30:33 +01:00
try {
this.systemTray.setIcon("grey_icon.png");
} catch (IOException e) {
e.printStackTrace();
}
2015-01-31 01:52:27 +01:00
2015-11-09 18:30:44 +01:00
this.systemTray.setStatus("Not Running");
2015-01-31 01:52:27 +01:00
this.systemTray.addMenuEntry("Quit", new SystemTrayMenuAction() {
2015-11-09 16:20:59 +01:00
@Override
public
void onClick(final SystemTray systemTray, final MenuEntry menuEntry) {
System.exit(0);
}
});
2015-01-23 02:52:09 +01:00
```
2015-12-13 21:04:31 +01:00
```
2015-10-29 02:26:01 +01:00
Note: This project was heavily influenced by the excellent Lantern project,
2014-11-03 02:10:18 +01:00
*Many* thanks to them for figuring out AppIndicators via JNA.
https://github.com/getlantern/lantern
```
2015-10-28 16:34:27 +01:00
```
2015-11-09 16:20:59 +01:00
Note: Gnome-shell users will experience an extension install to support this
2015-10-28 16:34:27 +01:00
functionality. Additionally, a shell restart is necessary for the extension
2015-11-15 14:51:47 +01:00
to be registered by the shell. You can disable the restart behavior if you
like, and the 'system tray' functionality will be picked up on log out/in,
or a system restart.
2015-10-28 16:34:27 +01:00
Also, screw you gnome-project leads, for making it such a pain-in-the-ass
to do something so incredibly simple and basic.
2015-11-09 16:20:59 +01:00
2016-02-13 15:06:19 +01:00
Note: Some desktop environments might use a dated version of libappindicator3, when
icon support in menus was removed, then put back.
2015-11-15 14:51:47 +01:00
This library will try to load a GTK indicator instead when it can, or will
try to load libappindicator1 first. Thank you RedHat for putting it back.
ISSUES:
'Trying to remove a child that doesn't believe we're it's parent.'
This is a known appindicator bug, and is rather old. Some distributions use
an OLD version of libappindicator, and will see this error.
See: https://github.com/ValveSoftware/steam-for-linux/issues/1077
'gsignal.c: signal 'child-added' is invalid for instance 'xyz' of type 'GtkMenu''
This is a known appindicator bug, and is rather old. Some distributions use an
OLD version of libappindicator, and will see this error.
The fallout from this issue (ie: menu entries not displaying) has been
*worked around* , so the menus should still show correctly.
See: https://askubuntu.com/questions/364594/has-the-appindicator-or-gtkmenu-api-changed-in-saucy
2015-10-28 16:34:27 +01:00
```
2015-12-13 21:04:31 +01:00
< h4 > We now release to maven!< / h4 >
2015-12-15 01:31:30 +01:00
There is a hard dependency in the POM file for the utilities library, which is an extremely small subset of a much larger library; including only what is *necessary* for this particular project to function.
2015-12-13 21:04:31 +01:00
This project is **kept in sync** with the utilities library, so "jar hell" is not an issue. Please note that the util library (in it's entirety) is not added since there are **many** dependencies that are not *necessary* for this project. No reason to require a massive amount of dependencies for one or two classes/methods.
```
< dependency >
< groupId > com.dorkbox< / groupId >
< artifactId > SystemTray< / artifactId >
2016-02-13 18:51:13 +01:00
< version > 2.4< / version >
2015-12-13 21:04:31 +01:00
< / dependency >
```
2015-12-22 10:17:05 +01:00
Or if you don't want to use Maven, you can access the files directly here:
https://oss.sonatype.org/content/repositories/releases/com/dorkbox/SystemTray/
https://oss.sonatype.org/content/repositories/releases/com/dorkbox/SystemTray-Dorkbox-Util/
https://maven.java.net/content/repositories/releases/net/java/dev/jna/jna/
https://maven.java.net/content/repositories/releases/net/java/dev/jna/jna-platform/
2015-12-13 21:04:31 +01:00
2016-02-10 00:40:38 +01:00
https://repo1.maven.org/maven2/org/slf4j/slf4j-api/
2016-02-09 23:35:49 +01:00
2015-12-13 21:04:31 +01:00
2016-02-10 00:40:38 +01:00
< h2 > License< / h2 >
2014-11-04 12:32:04 +01:00
2016-02-10 00:40:38 +01:00
This project is distributed under the terms of the Apache v2.0 License. See file "LICENSE" for further references.
2016-02-12 01:51:15 +01:00