Module java.desktop
Package java.awt

# Class Taskbar

java.lang.Object
java.awt.Taskbar

public class Taskbar extends Object
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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `Taskbar.Feature`
  List of provided features.
  `static enum`
  `Taskbar.State`
  Kinds of available window progress states.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Image`
  `getIconImage()`
  Obtains an image of this application's icon.
  `PopupMenu`
  `getMenu()`
  Gets PopupMenu used to add items to this application's icon in system task area.
  `static Taskbar`
  `getTaskbar()`
  Returns the `Taskbar` instance of the current taskbar context.
  `boolean`
  `isSupported(Taskbar.Feature feature)`
  Tests whether a `Feature` is supported on the current platform.
  `static boolean`
  `isTaskbarSupported()`
  Tests whether this class is supported on the current platform.
  `void`
  `requestUserAttention(boolean enabled, boolean critical)`
  Requests user attention to this application.
  `void`
  `requestWindowUserAttention(Window w)`
  Requests user attention to the specified window.
  `void`
  `setIconBadge(String badge)`
  Affixes a small system-provided badge to this application's icon.
  `void`
  `setIconImage(Image image)`
  Requests the system to change this application's icon to the provided `image`.
  `void`
  `setMenu(PopupMenu menu)`
  Attaches the contents of the provided PopupMenu to the application icon in the task area.
  `void`
  `setProgressValue(int value)`
  Affixes a small system-provided progress bar to this application's icon.
  `void`
  `setWindowIconBadge(Window w, Image badge)`
  Affixes a small badge to this application's icon in the task area for the specified window.
  `void`
  `setWindowProgressState(Window w, Taskbar.State state)`
  Sets a progress state for a specified window.
  `void`
  `setWindowProgressValue(Window w, int value)`
  Displays a determinate progress bar in the task area for the specified window.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### isSupported

    public boolean isSupported(Taskbar.Feature feature)
    Tests whether a `Feature` is supported on the current platform.
    Parameters:
      `feature` - the specified `Taskbar.Feature`
    Returns:
      true if the specified feature is supported on the current platform

  - ### getTaskbar

    public static Taskbar getTaskbar()
    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.
    Returns:
      the Taskbar instance
    Throws:
      `HeadlessException` - if `GraphicsEnvironment.isHeadless()` returns `true`
      `UnsupportedOperationException` - if this class is not supported on the current platform
    See Also:
      - `isTaskbarSupported()`
      - `GraphicsEnvironment.isHeadless()`

  - ### isTaskbarSupported

    public static boolean isTaskbarSupported()
    Tests whether this class is supported on the current platform. If it's supported, use `getTaskbar()` to retrieve an instance.
    Returns:
      `true` if this class is supported on the current platform; `false` otherwise
    See Also:
      - `getTaskbar()`

  - ### requestUserAttention

    public void requestUserAttention(boolean enabled, boolean critical)
    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(boolean, boolean)` to dismiss this request with `enabled` parameter set to false.
    Parameters:
      `enabled` - disables this request if false
      `critical` - if this is an important request
    Throws:
      `SecurityException` - if a security manager exists and it denies the `RuntimePermission("canProcessApplicationEvents")` permission.
      `UnsupportedOperationException` - if the current platform does not support the `Taskbar.Feature.USER_ATTENTION` feature

  - ### requestWindowUserAttention

    public void requestWindowUserAttention(Window w)
    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.
    Parameters:
      `w` - window
    Throws:
      `SecurityException` - if a security manager exists and it denies the `RuntimePermission("canProcessApplicationEvents")` permission.
      `UnsupportedOperationException` - if the current platform does not support the `Taskbar.Feature.USER_ATTENTION_WINDOW` feature

  - ### setMenu

    public void setMenu(PopupMenu menu)
    Attaches the contents of the provided PopupMenu to the application icon in the task area.
    Parameters:
      `menu` - the PopupMenu to attach to this application
    Throws:
      `SecurityException` - if a security manager exists and it denies the `RuntimePermission("canProcessApplicationEvents")` permission.
      `UnsupportedOperationException` - if the current platform does not support the `Taskbar.Feature.MENU` feature

  - ### getMenu

    public PopupMenu getMenu()
    Gets PopupMenu used to add items to this application's icon in system task area.
    Returns:
      the PopupMenu
    Throws:
      `SecurityException` - if a security manager exists and it denies the `RuntimePermission("canProcessApplicationEvents")` permission.
      `UnsupportedOperationException` - if the current platform does not support the `Taskbar.Feature.MENU` feature

  - ### setIconImage

    public void setIconImage(Image image)
    Requests the system to change this application's icon to the provided `image`.
    Parameters:
      `image` - to change
    Throws:
      `SecurityException` - if a security manager exists and it denies the `RuntimePermission("canProcessApplicationEvents")` permission.
      `UnsupportedOperationException` - if the current platform does not support the `Taskbar.Feature.ICON_IMAGE` feature

  - ### getIconImage

    public Image getIconImage()
    Obtains an image of this application's icon.
    API Note:
      The returned icon image may not be equal to an image set by `setIconImage(java.awt.Image)`, but should be visually similar.
    Returns:
      an image of this application's icon
    Throws:
      `SecurityException` - if a security manager exists and it denies the `RuntimePermission("canProcessApplicationEvents")` permission.
      `UnsupportedOperationException` - if the current platform does not support the `Taskbar.Feature.ICON_IMAGE` feature

  - ### setIconBadge

    public void setIconBadge(String badge)
    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.
    Parameters:
      `badge` - label to affix to the icon
    Throws:
      `SecurityException` - if a security manager exists and it denies the `RuntimePermission("canProcessApplicationEvents")` permission.
      `UnsupportedOperationException` - if the current platform does not support the `Taskbar.Feature.ICON_BADGE_NUMBER` or `Taskbar.Feature.ICON_BADGE_TEXT` feature

  - ### setWindowIconBadge

    public void setWindowIconBadge(Window w, Image 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.
    Parameters:
      `w` - window to update
      `badge` - image to affix to the icon
    Throws:
      `SecurityException` - if a security manager exists and it denies the `RuntimePermission("canProcessApplicationEvents")` permission.
      `UnsupportedOperationException` - if the current platform does not support the `Taskbar.Feature.ICON_BADGE_IMAGE_WINDOW` feature

  - ### setProgressValue

    public void setProgressValue(int value)
    Affixes a small system-provided progress bar to this application's icon.
    Parameters:
      `value` - from 0 to 100, other to disable progress indication
    Throws:
      `SecurityException` - if a security manager exists and it denies the `RuntimePermission("canProcessApplicationEvents")` permission.
      `UnsupportedOperationException` - if the current platform does not support the `Taskbar.Feature.PROGRESS_VALUE` feature

  - ### setWindowProgressValue

    public void setWindowProgressValue(Window w, int 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 `Taskbar.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.
    Parameters:
      `w` - window to update
      `value` - from 0 to 100, other to switch to `Taskbar.State.OFF` state and disable progress indication
    Throws:
      `SecurityException` - if a security manager exists and it denies the `RuntimePermission("canProcessApplicationEvents")` permission.
      `UnsupportedOperationException` - if the current platform does not support the `Taskbar.Feature.PROGRESS_VALUE_WINDOW` feature
    See Also:
      - `setWindowProgressState(java.awt.Window, State)`

  - ### setWindowProgressState

    public void setWindowProgressState(Window w, Taskbar.State state)
    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`
    Parameters:
      `w` - window
      `state` - to change to
    Throws:
      `SecurityException` - if a security manager exists and it denies the `RuntimePermission("canProcessApplicationEvents")` permission.
      `UnsupportedOperationException` - if the current platform does not support the `Taskbar.Feature.PROGRESS_STATE_WINDOW` feature
    See Also:
      - `Taskbar.State.OFF`
      - `Taskbar.State.NORMAL`
      - `Taskbar.State.PAUSED`
      - `Taskbar.State.ERROR`
      - `Taskbar.State.INDETERMINATE`
      - `setWindowProgressValue(java.awt.Window, int)`