mirror of
https://github.com/openjdk/jdk.git
synced 2025-09-19 02:24:40 +02:00
484 lines
18 KiB
Java
484 lines
18 KiB
Java
/*
|
|
* 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 RuntimePermission("canProcessApplicationEvents")} permissions.
|
|
*/
|
|
private void checkEventsProcessingPermission(){
|
|
SecurityManager sm = System.getSecurityManager();
|
|
if (sm != null) {
|
|
sm.checkPermission(new RuntimePermission(
|
|
"canProcessApplicationEvents"));
|
|
}
|
|
}
|
|
|
|
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 RuntimePermission("canProcessApplicationEvents")} 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) {
|
|
checkEventsProcessingPermission();
|
|
checkFeatureSupport(Feature.USER_ATTENTION);
|
|
peer.requestUserAttention(enabled, critical);
|
|
}
|
|
|
|
/**
|
|
* Requests user attention to the specified window.
|
|
*
|
|
* Has no effect if a window representation is not displayable in
|
|
* the task area. Whether it is displayable is dependent on all
|
|
* of window type, platform, and implementation.
|
|
*
|
|
* @param w window
|
|
* @throws SecurityException if a security manager exists and it denies the
|
|
* {@code RuntimePermission("canProcessApplicationEvents")} permission.
|
|
* @throws UnsupportedOperationException if the current platform
|
|
* does not support the {@link Taskbar.Feature#USER_ATTENTION_WINDOW} feature
|
|
*/
|
|
public void requestWindowUserAttention(Window w) {
|
|
checkEventsProcessingPermission();
|
|
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 RuntimePermission("canProcessApplicationEvents")} permission.
|
|
* @throws UnsupportedOperationException if the current platform
|
|
* does not support the {@link Taskbar.Feature#MENU} feature
|
|
*/
|
|
public void setMenu(final PopupMenu menu) {
|
|
checkEventsProcessingPermission();
|
|
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 RuntimePermission("canProcessApplicationEvents")} permission.
|
|
* @throws UnsupportedOperationException if the current platform
|
|
* does not support the {@link Taskbar.Feature#MENU} feature
|
|
*/
|
|
public PopupMenu getMenu() {
|
|
checkEventsProcessingPermission();
|
|
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 RuntimePermission("canProcessApplicationEvents")} permission.
|
|
* @throws UnsupportedOperationException if the current platform
|
|
* does not support the {@link Taskbar.Feature#ICON_IMAGE} feature
|
|
*/
|
|
public void setIconImage(final Image image) {
|
|
checkEventsProcessingPermission();
|
|
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 RuntimePermission("canProcessApplicationEvents")} permission.
|
|
* @throws UnsupportedOperationException if the current platform
|
|
* does not support the {@link Taskbar.Feature#ICON_IMAGE} feature
|
|
*/
|
|
public Image getIconImage() {
|
|
checkEventsProcessingPermission();
|
|
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 RuntimePermission("canProcessApplicationEvents")} 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) {
|
|
checkEventsProcessingPermission();
|
|
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.
|
|
*
|
|
* Has no effect if a window representation is not displayable in
|
|
* the task area. Whether it is displayable is dependent on all
|
|
* of window type, platform, and implementation.
|
|
*
|
|
* @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 RuntimePermission("canProcessApplicationEvents")} 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) {
|
|
checkEventsProcessingPermission();
|
|
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 SecurityException if a security manager exists and it denies the
|
|
* {@code RuntimePermission("canProcessApplicationEvents")} permission.
|
|
* @throws UnsupportedOperationException if the current platform
|
|
* does not support the {@link Taskbar.Feature#PROGRESS_VALUE} feature
|
|
*/
|
|
public void setProgressValue(int value) {
|
|
checkEventsProcessingPermission();
|
|
checkFeatureSupport(Feature.PROGRESS_VALUE);
|
|
peer.setProgressValue(value);
|
|
}
|
|
|
|
/**
|
|
* Displays a determinate progress bar in the task area for the specified
|
|
* window.
|
|
*
|
|
* Has no effect if a window representation is not displayable in
|
|
* the task area. Whether it is displayable is dependent on all
|
|
* of window type, platform, and implementation.
|
|
*
|
|
* <br>
|
|
* The visual behavior is platform and {@link State} dependent.
|
|
* <br>
|
|
* This call cancels the {@link State#INDETERMINATE INDETERMINATE} state
|
|
* of the window.
|
|
* <br>
|
|
* Note that when multiple windows is grouped in the task area
|
|
* the behavior is platform specific.
|
|
*
|
|
* @param w window to update
|
|
* @param value from 0 to 100, other to switch to {@link State#OFF} state
|
|
* and disable progress indication
|
|
* @see #setWindowProgressState(java.awt.Window, State)
|
|
* @throws SecurityException if a security manager exists and it denies the
|
|
* {@code RuntimePermission("canProcessApplicationEvents")} 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) {
|
|
checkEventsProcessingPermission();
|
|
checkFeatureSupport(Feature.PROGRESS_VALUE_WINDOW);
|
|
if (w != null) {
|
|
peer.setWindowProgressValue(w, value);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Sets a progress state for a specified window.
|
|
*
|
|
* Has no effect if a window representation is not displayable in
|
|
* the task area. Whether it is displayable is dependent on all
|
|
* of window type, platform, and implementation.
|
|
* <br>
|
|
* Each state displays a progress in a platform-dependent way.
|
|
* <br>
|
|
* Note than switching from {@link State#INDETERMINATE INDETERMINATE} state
|
|
* to any of determinate states may reset value set by
|
|
* {@link #setWindowProgressValue(java.awt.Window, int) setWindowProgressValue}
|
|
*
|
|
* @param w window
|
|
* @param state to change to
|
|
* @see State#OFF
|
|
* @see State#NORMAL
|
|
* @see State#PAUSED
|
|
* @see State#ERROR
|
|
* @see State#INDETERMINATE
|
|
* @see #setWindowProgressValue(java.awt.Window, int)
|
|
* @throws SecurityException if a security manager exists and it denies the
|
|
* {@code RuntimePermission("canProcessApplicationEvents")} 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) {
|
|
checkEventsProcessingPermission();
|
|
checkFeatureSupport(Feature.PROGRESS_STATE_WINDOW);
|
|
if (w != null) {
|
|
peer.setWindowProgressState(w, state);
|
|
}
|
|
}
|
|
}
|