https://openjdk.java.net/ 
/*
 * 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 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.

Implementation Note: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 java.desktop.appName system property set to this .desktop file name: Exec=java -Djava.desktop.appName=MyApp.desktop -jar /path/to/myapp.jar see 
https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles
Since:9
/**
 * 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 Taskbar.isSupported method to determine if the given feature is supported by the current platform. 
/**
     * 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 Also:
  • setIconBadge(String)
/**
         * Represents a textual icon badge feature.
         * @see #setIconBadge(java.lang.String)
         */
        ICON_BADGE_TEXT,

        
Represents a numerical icon badge feature.

See Also:
  • setIconBadge(String)
/**
         * Represents a numerical icon badge feature.
         * @see #setIconBadge(java.lang.String)
         */
        ICON_BADGE_NUMBER,

        
Represents a graphical icon badge feature for a window.

See Also:
  • setWindowIconBadge(Window, Image)
/**
         * 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 Also:
  • setIconImage(Image)
/**
         * Represents an icon feature.
         * @see #setIconImage(java.awt.Image)
         */
        ICON_IMAGE,

        
Represents a menu feature.

See Also:
/**
         * Represents a menu feature.
         * @see #setMenu(java.awt.PopupMenu)
         * @see #getMenu()
         */
        MENU,

        
Represents a progress state feature for a specified window.

See Also:
  • setWindowProgressState(Window, State)
/**
         * Represents a progress state feature for a specified window.
         * @see #setWindowProgressState(java.awt.Window, State)
         */
        PROGRESS_STATE_WINDOW,

        
Represents a progress value feature.

See Also:
  • setProgressValue(int)
/**
         * Represents a progress value feature.
         * @see #setProgressValue(int)
         */
        PROGRESS_VALUE,

        
Represents a progress value feature for a specified window.

See Also:
  • setWindowProgressValue(Window, int)
/**
         * 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 Also:
  • requestUserAttention(boolean, boolean)
/**
         * Represents a user attention request feature.
         * @see #requestUserAttention(boolean, boolean)
         */
        USER_ATTENTION,

        
Represents a user attention request feature for a specified window.

See Also:
  • requestWindowUserAttention(Window)
/**
         * 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 Also:
  • setWindowProgressState(Window, State)
/**
     * Kinds of available window progress states.
     *
     * @see #setWindowProgressState(java.awt.Window, java.awt.Taskbar.State)
     */
    public static enum State {
        
Stops displaying the progress.

/**
         * Stops displaying the progress.
         */
        OFF,
        
The progress indicator displays with normal color and determinate
mode.

/**
         * 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.

/**
         * 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.

/**
         * 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.

/**
         * Shows that an error has occurred. Switches to the determinate
         * display.
         */
        ERROR
    }

    private TaskbarPeer peer;

    
Tests whether a Feature is supported on the current platform. 
Params:
Returns:true if the specified feature is supported on the current platform
/**
     * 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.

Params:
  • featureType – the action type in question
Throws:
/**
     * 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 RuntimePermission("canProcessApplicationEvents") permissions. 
/**
     *  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 Taskbar instance of the current taskbar context. On some platforms the Taskbar API may not be supported; use the isTaskbarSupported method to determine if the current taskbar is supported. 
Throws:
See Also:
Returns:the Taskbar instance
/**
     * 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 getTaskbar() to retrieve an instance. 
See Also:
Returns:true if this class is supported on the current platform; false otherwise
/**
     * 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 enabled to false. Other platforms may require an additional call requestUserAttention to dismiss this request with enabled parameter set to false. 
Params:
  • enabled – disables this request if false
  • critical – if this is an important request
Throws:
/**
     * 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.

Params:
  • w – window
Throws:
/**
     * 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.

Params:
  • menu – the PopupMenu to attach to this application
Throws:
/**
     * 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.

Throws:
Returns:the PopupMenu
/**
     * 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.

Params:
  • image – to change
Throws:
/**
     * 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.

Throws:
Returns:an image of this application's icon
/**
     * 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 Feature.ICON_BADGE_TEXT and Feature.ICON_BADGE_NUMBER. Passing null as parameter hides the badge. 
Params:
  • badge – label to affix to the icon
Throws:
/**
     * 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.

Params:
  • w – window to update
  • badge – image to affix to the icon
Throws:
/**
     * 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.

Params:
  • value – from 0 to 100, other to disable progress indication
Throws:
/**
     * 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.

 The visual behavior is platform and State dependent. 
 This call cancels the INDETERMINATE state of the window. 

Note that when multiple windows is grouped in the task area
the behavior is platform specific.

Params:
  • w – window to update
  • value – from 0 to 100, other to switch to State.OFF state and disable progress indication
Throws:
See Also:
/**
     * 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.


Each state displays a progress in a platform-dependent way.

 Note than switching from INDETERMINATE state to any of determinate states may reset value set by setWindowProgressValue 
Params:
  • w – window
  • state – to change to
Throws:
See Also:
/**
     * 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);
        }
    }
}