APIdia Launch Partner
Top Description Inners Fields Constructors Methods
java.awt

public Class Taskbar

extends Object
Class Inheritance
Imports
java.awt.peer.TaskbarPeer, 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

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
Taskbar.Feature

List of provided features.

public static enum
Taskbar.State

Kinds of available window progress states.

Field Summary

Modifier and TypeField and Description
private TaskbarPeer
peer

private static volatile Taskbar
taskbar

Constructor Summary

AccessConstructor and Description
private
Taskbar()

Method Summary

Modifier and TypeMethod and Description
private void
checkFeatureSupport(Taskbar.Feature
the action type in question
featureType)

Checks if the feature type is supported.

public Image

Returns:

an image of this application's icon
getIconImage()

Obtains an image of this application's icon.

public PopupMenu

Returns:

the PopupMenu
getMenu()

Gets PopupMenu used to add items to this application's icon in system task area.

public static synchronized Taskbar

Returns:

the Taskbar instance
getTaskbar()

Returns the Taskbar instance of the current taskbar context.

public boolean

Returns:

true if the specified feature is supported on the current platform
isSupported(Taskbar.Feature
the specified Feature
feature)

Tests whether a Feature is supported on the current platform.

public static boolean

Returns:

true if this class is supported on the current platform; false otherwise
isTaskbarSupported()

Tests whether this class is supported on the current platform.

public void
requestUserAttention(final boolean
disables this request if false
enabled, final boolean
if this is an important request
critical)

Requests user attention to this application.

public void
requestWindowUserAttention(Window
window
w)

Requests user attention to the specified window.

public void
setIconBadge(final String
label to affix to the icon
badge)

Affixes a small system-provided badge to this application's icon.

public void
setIconImage(final Image
to change
image)

Requests the system to change this application's icon to the provided image.

public void
setMenu(final PopupMenu
the PopupMenu to attach to this application
menu)

Attaches the contents of the provided PopupMenu to the application icon in the task area.

public void
setProgressValue(int
from 0 to 100, other to disable progress indication
value)

Affixes a small system-provided progress bar to this application's icon.

public void
setWindowIconBadge(Window
window to update
w, final Image
image to affix to the icon
badge)

Affixes a small badge to this application's icon in the task area for the specified window.

public void
setWindowProgressState(Window
window
w, Taskbar.State
to change to
state)

Sets a progress state for a specified window.

public void
setWindowProgressValue(Window
window to update
w, int
from 0 to 100, other to switch to State#OFF state and disable progress indication
value)

Displays a determinate progress bar in the task area for the specified window.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

peerback to summary
private TaskbarPeer peer
taskbarback to summary
private static volatile Taskbar taskbar

Constructor Detail

Taskbarback to summary
private Taskbar()

Method Detail

checkFeatureSupportback to summary
private void checkFeatureSupport(Taskbar.Feature featureType)

Checks if the feature type is supported.

Parameters
featureType:Taskbar.Feature

the action type in question

Exceptions
UnsupportedOperationException:
if the specified action type is not supported on the current platform
getIconImageback to summary
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 java.awt.Taskbar#setIconImage, but should be visually similar.

Returns:Image

an image of this application's icon

Exceptions
UnsupportedOperationException:
if the current platform does not support the Taskbar.Feature#ICON_IMAGE feature
getMenuback to summary
public PopupMenu getMenu()

Gets PopupMenu used to add items to this application's icon in system task area.

Returns:PopupMenu

the PopupMenu

Exceptions
UnsupportedOperationException:
if the current platform does not support the Taskbar.Feature#MENU feature
getTaskbarback to summary
public static synchronized 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:Taskbar

the Taskbar instance

Exceptions
HeadlessException:
if GraphicsEnvironment#isHeadless() returns true
UnsupportedOperationException:
if this class is not supported on the current platform
See Also
isTaskbarSupported(), java.awt.GraphicsEnvironment#isHeadless
isSupportedback to summary
public boolean isSupported(Taskbar.Feature feature)

Tests whether a Feature is supported on the current platform.

Parameters
feature:Taskbar.Feature

the specified Feature

Returns:boolean

true if the specified feature is supported on the current platform

isTaskbarSupportedback to summary
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:boolean

true if this class is supported on the current platform; false otherwise

See Also
getTaskbar()
requestUserAttentionback to summary
public void requestUserAttention(final boolean enabled, final 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 to dismiss this request with enabled parameter set to false.

Parameters
enabled:boolean

disables this request if false

critical:boolean

if this is an important request

Exceptions
UnsupportedOperationException:
if the current platform does not support the Taskbar.Feature#USER_ATTENTION feature
requestWindowUserAttentionback to summary
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

window

Exceptions
UnsupportedOperationException:
if the current platform does not support the Taskbar.Feature#USER_ATTENTION_WINDOW feature
setIconBadgeback to summary
public void setIconBadge(final 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:String

label to affix to the icon

Exceptions
UnsupportedOperationException:
if the current platform does not support the Taskbar.Feature#ICON_BADGE_NUMBER or Taskbar.Feature#ICON_BADGE_TEXT feature
setIconImageback to summary
public void setIconImage(final Image image)

Requests the system to change this application's icon to the provided image.

Parameters
image:Image

to change

Exceptions
UnsupportedOperationException:
if the current platform does not support the Taskbar.Feature#ICON_IMAGE feature
setMenuback to summary
public void setMenu(final PopupMenu menu)

Attaches the contents of the provided PopupMenu to the application icon in the task area.

Parameters
menu:PopupMenu

the PopupMenu to attach to this application

Exceptions
UnsupportedOperationException:
if the current platform does not support the Taskbar.Feature#MENU feature
setProgressValueback to summary
public void setProgressValue(int value)

Affixes a small system-provided progress bar to this application's icon.

Parameters
value:int

from 0 to 100, other to disable progress indication

Exceptions
UnsupportedOperationException:
if the current platform does not support the Taskbar.Feature#PROGRESS_VALUE feature
setWindowIconBadgeback to summary
public void setWindowIconBadge(Window w, final 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

window to update

badge:Image

image to affix to the icon

Exceptions
UnsupportedOperationException:
if the current platform does not support the Taskbar.Feature#ICON_BADGE_IMAGE_WINDOW feature
setWindowProgressStateback to summary
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

window

state:Taskbar.State

to change to

Exceptions
UnsupportedOperationException:
if the current platform does not support the Taskbar.Feature#PROGRESS_STATE_WINDOW feature
See Also
State#OFF, State#NORMAL, State#PAUSED, State#ERROR, State#INDETERMINATE, setWindowProgressValue(java.awt.Window, int)
setWindowProgressValueback to summary
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 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

window to update

value:int

from 0 to 100, other to switch to State#OFF state and disable progress indication

Exceptions
UnsupportedOperationException:
if the current platform does not support the Taskbar.Feature#PROGRESS_VALUE_WINDOW feature
See Also
setWindowProgressState(java.awt.Window, State)
java.awt back to summary

public final Enum Taskbar.Feature

extends Enum<Taskbar.Feature>
Class Inheritance
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.

Field Summary

Modifier and TypeField and Description
public static final Taskbar.Feature
ICON_BADGE_IMAGE_WINDOW

Represents a graphical icon badge feature for a window.

public static final Taskbar.Feature
ICON_BADGE_NUMBER

Represents a numerical icon badge feature.

public static final Taskbar.Feature
ICON_BADGE_TEXT

Represents a textual icon badge feature.

public static final Taskbar.Feature
ICON_IMAGE

Represents an icon feature.

public static final Taskbar.Feature
MENU

Represents a menu feature.

public static final Taskbar.Feature
PROGRESS_STATE_WINDOW

Represents a progress state feature for a specified window.

public static final Taskbar.Feature
PROGRESS_VALUE

Represents a progress value feature.

public static final Taskbar.Feature
PROGRESS_VALUE_WINDOW

Represents a progress value feature for a specified window.

public static final Taskbar.Feature
USER_ATTENTION

Represents a user attention request feature.

public static final Taskbar.Feature
USER_ATTENTION_WINDOW

Represents a user attention request feature for a specified window.

Constructor Summary

AccessConstructor and Description
private
Feature()

Method Summary

Modifier and TypeMethod and Description
public static Taskbar.Feature
valueOf(String name)

public static Taskbar.Feature[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

ICON_BADGE_IMAGE_WINDOWback to summary
public static final Taskbar.Feature ICON_BADGE_IMAGE_WINDOW

Represents a graphical icon badge feature for a window.

See Also
setWindowIconBadge(java.awt.Window, java.awt.Image)
ICON_BADGE_NUMBERback to summary
public static final Taskbar.Feature ICON_BADGE_NUMBER

Represents a numerical icon badge feature.

See Also
setIconBadge(java.lang.String)
ICON_BADGE_TEXTback to summary
public static final Taskbar.Feature ICON_BADGE_TEXT

Represents a textual icon badge feature.

See Also
setIconBadge(java.lang.String)
ICON_IMAGEback to summary
public static final Taskbar.Feature ICON_IMAGE

Represents an icon feature.

See Also
setIconImage(java.awt.Image)
MENUback to summary
public static final Taskbar.Feature MENU

Represents a menu feature.

See Also
setMenu(java.awt.PopupMenu), getMenu()
PROGRESS_STATE_WINDOWback to summary
public static final Taskbar.Feature PROGRESS_STATE_WINDOW

Represents a progress state feature for a specified window.

See Also
setWindowProgressState(java.awt.Window, State)
PROGRESS_VALUEback to summary
public static final Taskbar.Feature PROGRESS_VALUE

Represents a progress value feature.

See Also
setProgressValue(int)
PROGRESS_VALUE_WINDOWback to summary
public static final Taskbar.Feature PROGRESS_VALUE_WINDOW

Represents a progress value feature for a specified window.

See Also
setWindowProgressValue(java.awt.Window, int)
USER_ATTENTIONback to summary
public static final Taskbar.Feature USER_ATTENTION

Represents a user attention request feature.

See Also
requestUserAttention(boolean, boolean)
USER_ATTENTION_WINDOWback to summary
public static final Taskbar.Feature USER_ATTENTION_WINDOW

Represents a user attention request feature for a specified window.

See Also
requestWindowUserAttention(java.awt.Window)

Constructor Detail

Featureback to summary
private Feature()

Method Detail

valueOfback to summary
public static Taskbar.Feature valueOf(String name)
valuesback to summary
public static Taskbar.Feature[] values()
java.awt back to summary

public final Enum Taskbar.State

extends Enum<Taskbar.State>
Class Inheritance
Kinds of available window progress states.
See Also
setWindowProgressState(java.awt.Window, java.awt.Taskbar.State)

Field Summary

Modifier and TypeField and Description
public static final Taskbar.State
ERROR

Shows that an error has occurred.

public static final Taskbar.State
INDETERMINATE

The progress indicator displays activity without specifying what proportion of the progress is complete.

public static final Taskbar.State
NORMAL

The progress indicator displays with normal color and determinate mode.

public static final Taskbar.State
OFF

Stops displaying the progress.

public static final Taskbar.State
PAUSED

Shows progress as paused, progress can be resumed by the user.

Constructor Summary

AccessConstructor and Description
private
State()

Method Summary

Modifier and TypeMethod and Description
public static Taskbar.State
valueOf(String name)

public static Taskbar.State[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

ERRORback to summary
public static final Taskbar.State ERROR

Shows that an error has occurred. Switches to the determinate display.

INDETERMINATEback to summary
public static final Taskbar.State INDETERMINATE

The progress indicator displays activity without specifying what proportion of the progress is complete.

NORMALback to summary
public static final Taskbar.State NORMAL

The progress indicator displays with normal color and determinate mode.

OFFback to summary
public static final Taskbar.State OFF

Stops displaying the progress.

PAUSEDback to summary
public static final Taskbar.State PAUSED

Shows progress as paused, progress can be resumed by the user. Switches to the determinate display.

Constructor Detail

Stateback to summary
private State()

Method Detail

valueOfback to summary
public static Taskbar.State valueOf(String name)
valuesback to summary
public static Taskbar.State[] values()