From 8a96bfb7fd2c725f11cef3e7c4f4b106aa4e6a44 Mon Sep 17 00:00:00 2001 From: nathan Date: Wed, 19 Jul 2017 00:57:46 +0200 Subject: [PATCH] Updated Readme --- README.md | 101 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 63 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 0b7cfcb..da8dac1 100644 --- a/README.md +++ b/README.md @@ -3,19 +3,26 @@ SystemTray Professional, cross-platform **SystemTray** support for *Swing/AWT*, *GtkStatusIcon*, and *AppIndicator* system-tray types for java applications on Java 6+. -This library provides **OS Native** menus and **Swing/AWT** menus, depending on the OS and Desktop Environment, and if AutoDetect (the default) is set. Linux/Unix will automatically choose *Native* (*GtkStatusIcon*, and *AppIndicator*) menus, Windows will choose *Swing*, and MacOS will choose *AWT*. - - Please note that the *Native* adn *AWT* menus follow the specified look and feel of that OS and are limited by what is supported on the OS. Consequently they are not consistent across all platforms and environments. +This library provides **OS Native** menus and **Swing/AWT** menus, depending on the OS and Desktop Environment and if AutoDetect (the default) is enabled. + + - Linux/Unix will automatically choose *Native* (*GtkStatusIcon*, and *AppIndicator*) menus, Windows will choose *Swing*, and MacOS will choose *AWT*. + + - Please note that the *Native* and *AWT* menus follow the specified look and feel of that OS and are limited by what is supported on the OS. Consequently they are not consistent across all platforms and environments. + + - In most cases on Linux/Unix, *Native* menus are used. In cases where libraries are missing or there are un-resolvable GTK version conflicts, we try to fallback to using *Swing*.   The following unique problems are also solved by this library: 1. *Sun/Oracle* system-tray icons on gnu/linux **do not** support images with transparent backgrounds - 2. *Sun/Oracle* system-tray and *SWT* system-tray implementations **do not** support app-indicators, which are necessary on different distributions of gnu/linux and unix - 3. *Sun/Oracle* system-tray menus on Windows **look absolutely horrid** - 4. *Sun/Oracle* system-tray icons on Windows are **hard-coded** to a max size of 24x24 (it was last updated in *2006*) - 5. *Sun/Oracle* system-tray menus on MacOS **do not** always respond to both mouse buttons, where Apple menus do - 6. Windows *native* menus **do not** support images attached to menu entries - 7. Windows menus **do not** support a different L&F from the running application + 1. *Sun/Oracle* system-tray and *SWT* system-tray implementations **do not** support app-indicators, which are necessary on different distributions of gnu/linux and unix + 1. *GtkStatusIcons* on GNOME3 desktop environments are hidden by default + 1. *Sun/Oracle* system-tray menus on Windows **look absolutely horrid** + 1. *Sun/Oracle* system-tray icons on Windows are **hard-coded** to a max size of 24x24 (it was last updated in *2006*) + 1. *Sun/Oracle* system-tray menus on MacOS **do not** always respond to both mouse buttons, where Apple menus do + 1. Windows *native* menus **do not** support images attached to menu entries + 1. Windows menus **do not** support a different L&F from the running application + 1. Windows, Linux, and MacOSX menus (native or otherwise) do not support HiDPI configurations @@ -31,7 +38,7 @@ Problems and Restrictions - **SWT** can use *GTK2* or *GTK3*. If you want to use *GTK2* you must force SWT into *GTK2 mode* via `System.setProperty("SWT_GTK3", "0");` before SWT is initialized and only if there are problems with the autodetection, you can also set `SystemTray.FORCE_GTK2=true;`. - - **AppIndicators** under Ubuntu 16.04 (and possibly other distro's) **will not** work as a different user (ie: as a sudo'd user to `root`), since AppIndicators require a dbus connection to the current user's window manager -- and this cannot happen between different user accounts. We attempt to detect this, and fallback to using Swing. + - **AppIndicators** under Ubuntu 16.04 (and possibly other distro's) **will not** work as a different user (ie: as a sudo'd user to `root`), since AppIndicators require a dbus connection to the current user's window manager -- and this cannot happen between different user accounts. We attempt to detect this and fallback to using Swing. - **MacOSX** is a *special snowflake* in how it handles GUI events, and so there are some bizzaro combinations of SWT, JavaFX, and Swing that do not work together (see the `Notes` below for the details.) @@ -43,43 +50,57 @@ Problems and Restrictions - **Linux/Unix Menus** Some linux environments only support right-click to display the menu, and it is not possible to change the behavior. -Compatibility Matrix +AutoDetect Compatibility List ------------------ -`✓`=supported, `-`= not supported - -OS | Java/Swing | JavaFX | SWT ---- | --- | --- | --- | -Arch Linux + Gnome3 | ✓ | ✓ | ✓ | -Debian 8.5 + Gnome3 | - | - | - | -Debian 8.6 + Gnome3 | - | - | - | -Elementary OS 0.3.2 | - | ✓ | ✓ | -Elementary OS 0.4 | - | ✓ | ✓ | -Fedora 23 | ✓ | ✓ | ✓ | -Fedora 24 | ✓ | ✓ | ✓ | -Fedora 25 | ✓ | ✓ | ✓ | -Fedora 25 KDE | ✓ | ✓ | ✓ | -FreeBSD 11 + Gnome3 | ✓ | ✓ | + | -Kali 2016 | ✓ | ✓ | ✓ | -Kali 2017 | ✓ | ✓ | ✓ | -LinuxMint 18 | ✓ | ✓ | ✓ | -Ubuntu 12.04 | ✓ | ✓ | ✓ | -Ubuntu 14.04 | ✓ | ✓ | ✓ | -Ubuntu 16.04 | ✓ | ✓ | ✓ | -UbuntuGnome 16.04 | ✓ | ✓ | ✓ | -UbuntuGnome 17.04 | ✓ | ✓ | ✓ | -XUbuntu 16.04 | ✓ | ✓ | ✓ | -MacOSx | ✓ | ✓ | ✓ | -Win XP | ✓ | ✓ | ✓ | -Win 7 | ✓ | ✓ | ✓ | -Win 8.1 | ✓ | ✓ | ✓ | -Win 10 | ✓ | ✓ | ✓ | + +OS | Supported +--- | --- | +Arch Linux + Gnome3 | ✓ | + | | +Debian 8.5 + Gnome3 | ✓ | +Debian 8.6 + Gnome3 | ✓ | + | | +Elementary OS 0.3.2 | ✓ | +Elementary OS 0.4 | ✓ | + | | +Fedora 23 | ✓ | +Fedora 24 | ✓ | +Fedora 25 | ✓ | +Fedora 25 KDE | ✓ | + | | +FreeBSD 11 + Gnome3 | ✓ | + | | +Kali 2016 | ✓ | +Kali 2017 | ✓ | + | | +LinuxMint 18 | ✓ | + | | +Ubuntu 12.04 | ✓ | +Ubuntu 14.04 | ✓ | +Ubuntu 16.04 | ✓ | +Ubuntu 17.04 | ✓ | +UbuntuGnome 16.04 | ✓ | +UbuntuGnome 17.04 | ✓ | + | | +XUbuntu 16.04 | ✓ | + | | +MacOSx | ✓ | + | | +Windows XP | ✓ | +Windows 7 | ✓ | +Windows 8.1 | ✓ | +Windows 10 | ✓ | Notes: ------- + - The compatibility list only applies while the SystemTray is in `AutoDetect` mode. Not all OSes support forcing a custom tray type. + - Ubuntu 16.04+ with JavaFX require `libappindicator1` because of JavaFX GTK and indicator panel incompatibilities. See [more details](https://github.com/dorkbox/SystemTray/issues/14#issuecomment-248853532). We attempt to fallback to using Swing in this situation. - Ubuntu 17.04+ Java only supports the X11 backend. MIR and Wayland are not supported. + - Debian + GNOME 3, SystemTray works, but will only show in a tray via pressing SUPER+M. + - MacOSX JavaFX (Java7) is incompatible with the SystemTray by default. See [issue details](https://bugs.openjdk.java.net/browse/JDK-8116017). - To fix this do one of the following - Upgrade to Java 8 @@ -102,6 +123,10 @@ SystemTray.AUTO_SIZE (type boolean, default value 'true') SystemTray.FORCE_GTK2 (type boolean, default value 'false') - Forces the system tray to always choose GTK2 (even when GTK3 might be available). + +SystemTray.PREFER_GTK3 (type boolean, default value 'true') + - Prefer to load GTK3 before trying to load GTK2. + SystemTray.FORCE_TRAY_TYPE (type SystemTray.TrayType, default value 'AutoDetect') - Forces the system tray detection to be AutoDetect, GtkStatusIcon, AppIndicator, Swing, or AWT.