--- /dev/null 2015-11-20 07:55:43.488004899 +0300 +++ new/src/java.desktop/share/classes/java/awt/Taskbar.java 2015-11-20 08:17:47.727845670 +0300 @@ -0,0 +1,393 @@ +/* + * Copyright (c) 2015, 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 + */ + +public class Taskbar { + + /** + * List of provided features. + */ + public static enum Feature { + + /** + * @see #setIconBadge(java.lang.String) + */ + ICON_BADGE_TEXT, + + /** + * @see #setIconBadge(java.lang.String) + */ + ICON_BADGE_NUMBER, + + /** + * @see #setWindowIconBadge(java.awt.Window, java.awt.Image) + */ + ICON_BADGE_IMAGE_WINDOW, + + /** + * @see #setIconImage(java.awt.Image) + */ + ICON_IMAGE, + + /** + * @see #setMenu(java.awt.PopupMenu) + * @see #getMenu() + */ + MENU, + + /** + * @see #setWindowProgressState(java.awt.Window, int) + */ + PROGRESS_STATE_WINDOW, + + /** + * @see #setProgressValue(int) + */ + PROGRESS_VALUE, + + /** + * @see #setWindowProgressValue(java.awt.Window, int) + */ + PROGRESS_VALUE_WINDOW, + + /** + * @see #requestUserAttention(boolean, boolean) + */ + USER_ATTENTION, + + /** + * @see #requestWindowUserAttention(java.awt.Window) + */ + USER_ATTENTION_WINDOW + } + + /** + * Stops displaying the progress. + */ + public static final int STATE_OFF = 0x0; + + /** + * The progress indicator displays with normal color and determinate mode. + */ + public static final int STATE_NORMAL = 0x1; + + /** + * Shows progress as paused, progress can be resumed by the user. + * Switches to the determinate display. + */ + public static final int STATE_PAUSED = 0x2; + + /** + * The progress indicator displays activity without specifying what + * proportion of the progress is complete. + */ + public static final int STATE_INDETERMINATE = 0x3; + + /** + * Shows that an error has occurred. + * Switches to the determinate display. + */ + public static final int STATE_ERROR = 0x4; + + 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 checkPermission method with + * an 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 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 true if this class is supported on the + * current platform; 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 + */ + 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 + */ + 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 + */ + 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 + */ + public PopupMenu getMenu() { + checkAWTPermission(); + checkFeatureSupport(Feature.MENU); + return peer.getMenu(); + } + + /** + * Changes this application's icon to the provided image. + * + * @param image to change + */ + 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 + */ + 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 + */ + 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 + */ + 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 + */ + 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 + */ + 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 + */ + public void setWindowProgressState(Window w, int state) { + checkAWTPermission(); + checkFeatureSupport(Feature.PROGRESS_STATE_WINDOW); + if (state < STATE_OFF && state > STATE_ERROR) { + throw new IllegalArgumentException("Invalid state value"); + } + if (w != null) { + peer.setWindowProgressState(w, state); + } + } + + private native void initIDs(); +}