--- /dev/null 2016-01-17 23:41:07.556005236 +0300 +++ new/src/java.desktop/share/classes/java/awt/Taskbar.java 2016-01-17 23:43:14.461205600 +0300 @@ -0,0 +1,442 @@ +/* + * 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; +import java.lang.annotation.Native; + +/** + * 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 1.9
+ */
+
+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.
+ */
+ @Native
+ public static final int STATE_OFF = 0x0;
+
+ /**
+ * The progress indicator displays with normal color and determinate mode.
+ */
+ @Native
+ public static final int STATE_NORMAL = 0x1;
+
+ /**
+ * Shows progress as paused, progress can be resumed by the user.
+ * Switches to the determinate display.
+ */
+ @Native
+ public static final int STATE_PAUSED = 0x2;
+
+ /**
+ * The progress indicator displays activity without specifying what
+ * proportion of the progress is complete.
+ */
+ @Native
+ public static final int STATE_INDETERMINATE = 0x3;
+
+ /**
+ * Shows that an error has occurred.
+ * Switches to the determinate display.
+ */
+ @Native
+ 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
+ * @throws SecurityException if a security manager exists and it denies the
+ * 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
+ * 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
+ * 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
+ * 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
+ * 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
+ * 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
+ * AWTPermission("showWindowWithoutWarningBanner")
permission.
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Taskbar.Feature#ICON_BADGE_NUMBER} 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
+ * 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
+ * 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
+ * AWTPermission("showWindowWithoutWarningBanner")
permission.
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Taskbar.Feature#PROGRESS_STATE_WINDOW} feature
+ * @throws IllegalArgumentException if {@code state} is invalid
+ */
+ 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);
+ }
+ }
+}