/* * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.awt; import java.awt.peer.TaskbarPeer; import sun.awt.SunToolkit; /** * The {@code Taskbar} class allows a Java application to interact with * the system task area (taskbar, Dock, etc.). * *

* There are a variety of interactions depending on the current platform such as * displaying progress of some task, appending user-specified menu to the application * icon context menu, etc. * * @implNote Linux support is currently limited to Unity. However to make these * features work on Unity, the app should be run from a .desktop file with * specified {@code java.desktop.appName} system property set to this .desktop * file name: * {@code Exec=java -Djava.desktop.appName=MyApp.desktop -jar /path/to/myapp.jar} * see * https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles * * @since 9 */ public class Taskbar { /** * List of provided features. Each platform supports a different * set of features. You may use the {@link Taskbar#isSupported} * method to determine if the given feature is supported by the * current platform. */ public static enum Feature { /** * Represents a textual icon badge feature. * @see #setIconBadge(java.lang.String) */ ICON_BADGE_TEXT, /** * Represents a numerical icon badge feature. * @see #setIconBadge(java.lang.String) */ ICON_BADGE_NUMBER, /** * Represents a graphical icon badge feature for a window. * @see #setWindowIconBadge(java.awt.Window, java.awt.Image) */ ICON_BADGE_IMAGE_WINDOW, /** * Represents an icon feature. * @see #setIconImage(java.awt.Image) */ ICON_IMAGE, /** * Represents a menu feature. * @see #setMenu(java.awt.PopupMenu) * @see #getMenu() */ MENU, /** * Represents a progress state feature for a specified window. * @see #setWindowProgressState(java.awt.Window, State) */ PROGRESS_STATE_WINDOW, /** * Represents a progress value feature. * @see #setProgressValue(int) */ PROGRESS_VALUE, /** * Represents a progress value feature for a specified window. * @see #setWindowProgressValue(java.awt.Window, int) */ PROGRESS_VALUE_WINDOW, /** * Represents a user attention request feature. * @see #requestUserAttention(boolean, boolean) */ USER_ATTENTION, /** * Represents a user attention request feature for a specified window. * @see #requestWindowUserAttention(java.awt.Window) */ USER_ATTENTION_WINDOW } /** * Kinds of available window progress states. * * @see #setWindowProgressState(java.awt.Window, java.awt.Taskbar.State) */ public static enum State { /** * Stops displaying the progress. */ OFF, /** * The progress indicator displays with normal color and determinate * mode. */ NORMAL, /** * Shows progress as paused, progress can be resumed by the user. * Switches to the determinate display. */ PAUSED, /** * The progress indicator displays activity without specifying what * proportion of the progress is complete. */ INDETERMINATE, /** * Shows that an error has occurred. Switches to the determinate * display. */ ERROR } private TaskbarPeer peer; /** * Tests whether a {@code Feature} is supported on the current platform. * @param feature the specified {@link Feature} * @return true if the specified feature is supported on the current platform */ public boolean isSupported(Feature feature) { return peer.isSupported(feature); } /** * Checks if the feature type is supported. * * @param featureType the action type in question * @throws UnsupportedOperationException if the specified action type is not * supported on the current platform */ private void checkFeatureSupport(Feature featureType){ if (!isSupported(featureType)) { throw new UnsupportedOperationException("The " + featureType.name() + " feature is not supported on the current platform!"); } } /** * Calls to the security manager's {@code checkPermission} method with * an {@code AWTPermission("showWindowWithoutWarningBanner")} * permission. */ private void checkAWTPermission(){ SecurityManager sm = System.getSecurityManager(); if (sm != null) { sm.checkPermission(new AWTPermission( "showWindowWithoutWarningBanner")); } } private Taskbar() { Toolkit defaultToolkit = Toolkit.getDefaultToolkit(); if (defaultToolkit instanceof SunToolkit) { peer = ((SunToolkit) defaultToolkit).createTaskbarPeer(this); } } /** * Returns the {@code Taskbar} instance of the current * taskbar context. On some platforms the Taskbar API may not be * supported; use the {@link #isTaskbarSupported} method to * determine if the current taskbar is supported. * @return the Taskbar instance * @throws HeadlessException if {@link * GraphicsEnvironment#isHeadless()} returns {@code true} * @throws UnsupportedOperationException if this class is not * supported on the current platform * @see #isTaskbarSupported() * @see java.awt.GraphicsEnvironment#isHeadless */ public static synchronized Taskbar getTaskbar(){ if (GraphicsEnvironment.isHeadless()) throw new HeadlessException(); if (!Taskbar.isTaskbarSupported()) { throw new UnsupportedOperationException("Taskbar API is not " + "supported on the current platform"); } sun.awt.AppContext context = sun.awt.AppContext.getAppContext(); Taskbar taskbar = (Taskbar)context.get(Taskbar.class); if (taskbar == null) { taskbar = new Taskbar(); context.put(Taskbar.class, taskbar); } return taskbar; } /** * Tests whether this class is supported on the current platform. * If it's supported, use {@link #getTaskbar()} to retrieve an * instance. * * @return {@code true} if this class is supported on the * current platform; {@code false} otherwise * @see #getTaskbar() */ public static boolean isTaskbarSupported(){ Toolkit defaultToolkit = Toolkit.getDefaultToolkit(); if (defaultToolkit instanceof SunToolkit) { return ((SunToolkit)defaultToolkit).isTaskbarSupported(); } return false; } /** * Requests user attention to this application. * * Depending on the platform, this may be visually indicated by a bouncing * or flashing icon in the task area. It may have no effect on an already active * application. * * On some platforms (e.g. Mac OS) this effect may disappear upon app activation * and cannot be dismissed by setting {@code enabled} to false. * Other platforms may require an additional call * {@link #requestUserAttention} to dismiss this request * with {@code enabled} parameter set to false. * * @param enabled disables this request if false * @param critical if this is an important request * @throws SecurityException if a security manager exists and it denies the * {@code AWTPermission("showWindowWithoutWarningBanner")} permission. * @throws UnsupportedOperationException if the current platform * does not support the {@link Taskbar.Feature#USER_ATTENTION} feature */ public void requestUserAttention(final boolean enabled, final boolean critical) { checkAWTPermission(); checkFeatureSupport(Feature.USER_ATTENTION); peer.requestUserAttention(enabled, critical); } /** * Requests user attention to the specified window until it is activated. * * On an already active window requesting attention does nothing. * * @param w window * @throws SecurityException if a security manager exists and it denies the * {@code AWTPermission("showWindowWithoutWarningBanner")} permission. * @throws UnsupportedOperationException if the current platform * does not support the {@link Taskbar.Feature#USER_ATTENTION_WINDOW} feature */ public void requestWindowUserAttention(Window w) { checkAWTPermission(); checkFeatureSupport(Feature.USER_ATTENTION_WINDOW); peer.requestWindowUserAttention(w); } /** * Attaches the contents of the provided PopupMenu to the application icon * in the task area. * * @param menu the PopupMenu to attach to this application * @throws SecurityException if a security manager exists and it denies the * {@code AWTPermission("showWindowWithoutWarningBanner")} permission. * @throws UnsupportedOperationException if the current platform * does not support the {@link Taskbar.Feature#MENU} feature */ public void setMenu(final PopupMenu menu) { checkAWTPermission(); checkFeatureSupport(Feature.MENU); peer.setMenu(menu); } /** * Gets PopupMenu used to add items to this application's icon in system task area. * * @return the PopupMenu * @throws SecurityException if a security manager exists and it denies the * {@code AWTPermission("showWindowWithoutWarningBanner")} permission. * @throws UnsupportedOperationException if the current platform * does not support the {@link Taskbar.Feature#MENU} feature */ public PopupMenu getMenu() { checkAWTPermission(); checkFeatureSupport(Feature.MENU); return peer.getMenu(); } /** * Changes this application's icon to the provided image. * * @param image to change * @throws SecurityException if a security manager exists and it denies the * {@code AWTPermission("showWindowWithoutWarningBanner")} permission. * @throws UnsupportedOperationException if the current platform * does not support the {@link Taskbar.Feature#ICON_IMAGE} feature */ public void setIconImage(final Image image) { checkAWTPermission(); checkFeatureSupport(Feature.ICON_IMAGE); peer.setIconImage(image); } /** * Obtains an image of this application's icon. * * @return an image of this application's icon * @throws SecurityException if a security manager exists and it denies the * {@code AWTPermission("showWindowWithoutWarningBanner")} permission. * @throws UnsupportedOperationException if the current platform * does not support the {@link Taskbar.Feature#ICON_IMAGE} feature */ public Image getIconImage() { checkAWTPermission(); checkFeatureSupport(Feature.ICON_IMAGE); return peer.getIconImage(); } /** * Affixes a small system-provided badge to this application's icon. * Usually a number. * * Some platforms do not support string values and accept only integer * values. In this case, pass an integer represented as a string as parameter. * This can be tested by {@code Feature.ICON_BADGE_STRING} and * {@code Feature.ICON_BADGE_NUMBER}. * * Passing {@code null} as parameter hides the badge. * @param badge label to affix to the icon * @throws SecurityException if a security manager exists and it denies the * {@code AWTPermission("showWindowWithoutWarningBanner")} permission. * @throws UnsupportedOperationException if the current platform * does not support the {@link Taskbar.Feature#ICON_BADGE_NUMBER} * or {@link Taskbar.Feature#ICON_BADGE_TEXT} feature */ public void setIconBadge(final String badge) { checkAWTPermission(); checkFeatureSupport(Feature.ICON_BADGE_NUMBER); peer.setIconBadge(badge); } /** * Affixes a small badge to this application's icon in the task area * for the specified window. * It may be disabled by system settings. * * @param w window to update * @param badge image to affix to the icon * @throws SecurityException if a security manager exists and it denies the * {@code AWTPermission("showWindowWithoutWarningBanner")} permission. * @throws UnsupportedOperationException if the current platform * does not support the {@link Taskbar.Feature#ICON_BADGE_IMAGE_WINDOW} feature */ public void setWindowIconBadge(Window w, final Image badge) { checkAWTPermission(); checkFeatureSupport(Feature.ICON_BADGE_IMAGE_WINDOW); if (w != null) { peer.setWindowIconBadge(w, badge); } } /** * Affixes a small system-provided progress bar to this application's icon. * * @param value from 0 to 100, other to disable progress indication * @throws UnsupportedOperationException if the current platform * does not support the {@link Taskbar.Feature#PROGRESS_VALUE} feature */ public void setProgressValue(int value) { checkAWTPermission(); checkFeatureSupport(Feature.PROGRESS_VALUE); peer.setProgressValue(value); } /** * Displays progress for specified window. * * @param w window to update * @param value from 0 to 100, other to disable progress indication * @throws SecurityException if a security manager exists and it denies the * {@code AWTPermission("showWindowWithoutWarningBanner")} permission. * @throws UnsupportedOperationException if the current platform * does not support the {@link Taskbar.Feature#PROGRESS_VALUE_WINDOW} feature */ public void setWindowProgressValue(Window w, int value) { checkAWTPermission(); checkFeatureSupport(Feature.PROGRESS_VALUE_WINDOW); if (w != null) { peer.setWindowProgressValue(w, value); } } /** * Sets a progress state for a specified window. * * @param w window * @param state to change to * @see State#OFF * @see State#NORMAL * @see State#PAUSED * @see State#INDETERMINATE * @see State#ERROR * @throws SecurityException if a security manager exists and it denies the * {@code AWTPermission("showWindowWithoutWarningBanner")} permission. * @throws UnsupportedOperationException if the current platform * does not support the {@link Taskbar.Feature#PROGRESS_STATE_WINDOW} feature */ public void setWindowProgressState(Window w, State state) { checkAWTPermission(); checkFeatureSupport(Feature.PROGRESS_STATE_WINDOW); if (w != null) { peer.setWindowProgressState(w, state); } } }