Class Taskbar
java.lang.Object
java.awt.Taskbar
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
Modifier and TypeClassDescriptionstatic enum
List of provided features.static enum
Kinds of available window progress states. -
Method Summary
Modifier and TypeMethodDescriptionObtains an image of this application's icon.getMenu()
Gets PopupMenu used to add items to this application's icon in system task area.static Taskbar
Returns theTaskbar
instance of the current taskbar context.boolean
isSupported
(Taskbar.Feature feature) Tests whether aFeature
is supported on the current platform.static boolean
Tests whether this class is supported on the current platform.void
requestUserAttention
(boolean enabled, boolean critical) Requests user attention to this application.void
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 providedimage
.void
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.
-
Method Details
-
isSupported
Tests whether aFeature
is supported on the current platform.- Parameters:
feature
- the specifiedTaskbar.Feature
- Returns:
- true if the specified feature is supported on the current platform
-
getTaskbar
Returns theTaskbar
instance of the current taskbar context. On some platforms the Taskbar API may not be supported; use theisTaskbarSupported()
method to determine if the current taskbar is supported.- Returns:
- the Taskbar instance
- Throws:
HeadlessException
- ifGraphicsEnvironment.isHeadless()
returnstrue
UnsupportedOperationException
- if this class is not supported on the current platform- See Also:
-
isTaskbarSupported
public static boolean isTaskbarSupported()Tests whether this class is supported on the current platform. If it's supported, usegetTaskbar()
to retrieve an instance.- Returns:
true
if this class is supported on the current platform;false
otherwise- See Also:
-
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 settingenabled
to false. Other platforms may require an additional callrequestUserAttention(boolean, boolean)
to dismiss this request withenabled
parameter set to false.- Parameters:
enabled
- disables this request if falsecritical
- if this is an important request- Throws:
SecurityException
- if a security manager exists and it denies theRuntimePermission("canProcessApplicationEvents")
permission.UnsupportedOperationException
- if the current platform does not support theTaskbar.Feature.USER_ATTENTION
feature
-
requestWindowUserAttention
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 theRuntimePermission("canProcessApplicationEvents")
permission.UnsupportedOperationException
- if the current platform does not support theTaskbar.Feature.USER_ATTENTION_WINDOW
feature
-
setMenu
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 theRuntimePermission("canProcessApplicationEvents")
permission.UnsupportedOperationException
- if the current platform does not support theTaskbar.Feature.MENU
feature
-
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 theRuntimePermission("canProcessApplicationEvents")
permission.UnsupportedOperationException
- if the current platform does not support theTaskbar.Feature.MENU
feature
-
setIconImage
Requests the system to change this application's icon to the providedimage
.- Parameters:
image
- to change- Throws:
SecurityException
- if a security manager exists and it denies theRuntimePermission("canProcessApplicationEvents")
permission.UnsupportedOperationException
- if the current platform does not support theTaskbar.Feature.ICON_IMAGE
feature
-
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 theRuntimePermission("canProcessApplicationEvents")
permission.UnsupportedOperationException
- if the current platform does not support theTaskbar.Feature.ICON_IMAGE
feature
-
setIconBadge
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 byFeature.ICON_BADGE_TEXT
andFeature.ICON_BADGE_NUMBER
. Passingnull
as parameter hides the badge.- Parameters:
badge
- label to affix to the icon- Throws:
SecurityException
- if a security manager exists and it denies theRuntimePermission("canProcessApplicationEvents")
permission.UnsupportedOperationException
- if the current platform does not support theTaskbar.Feature.ICON_BADGE_NUMBER
orTaskbar.Feature.ICON_BADGE_TEXT
feature
-
setWindowIconBadge
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 updatebadge
- image to affix to the icon- Throws:
SecurityException
- if a security manager exists and it denies theRuntimePermission("canProcessApplicationEvents")
permission.UnsupportedOperationException
- if the current platform does not support theTaskbar.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 theRuntimePermission("canProcessApplicationEvents")
permission.UnsupportedOperationException
- if the current platform does not support theTaskbar.Feature.PROGRESS_VALUE
feature
-
setWindowProgressValue
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 andTaskbar.State
dependent.
This call cancels theINDETERMINATE
state of the window.
Note that when multiple windows is grouped in the task area the behavior is platform specific.- Parameters:
w
- window to updatevalue
- from 0 to 100, other to switch toTaskbar.State.OFF
state and disable progress indication- Throws:
SecurityException
- if a security manager exists and it denies theRuntimePermission("canProcessApplicationEvents")
permission.UnsupportedOperationException
- if the current platform does not support theTaskbar.Feature.PROGRESS_VALUE_WINDOW
feature- See Also:
-
setWindowProgressState
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 fromINDETERMINATE
state to any of determinate states may reset value set bysetWindowProgressValue
- Parameters:
w
- windowstate
- to change to- Throws:
SecurityException
- if a security manager exists and it denies theRuntimePermission("canProcessApplicationEvents")
permission.UnsupportedOperationException
- if the current platform does not support theTaskbar.Feature.PROGRESS_STATE_WINDOW
feature- See Also:
-