8155083: On Windows, usage of USER_ATTENTION_WINDOW depends on state setting order
Reviewed-by: serb, ssadetsky
/*
* 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.).
*
* <p>
* 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 <a href="https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles">
* https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles</a>
*
* @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.
*
* @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_TEXT} 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);
}
}
}