What is Java MacOS Dock: -Xdock ?

Usage:

This option is only available on MacOS.

• -Xdock:name=<name>: set the name of the application name displayed in the Dock.
• -Xdock:icon=<path>: set the icon displayed in the Dock.

Example:

java -Xdock:name=MyApp -Xdock:icon=Resources/icon.png

Image formats supported are PNG, JPEG and ICNS.

Description:

The -Xdock argument is used to control the name of the application and its principal icon as they appear in the MacOS Dock and also in the task switcher and Mission Control screens.

Since Java 9 the icon can be set programmatically using the new java.awt.Taskbar class and its setIconImage method. On older releases of Java, an internal API com.apple.eawt could be used for the same purpose. However both of these programmatic approaches suffer from not running early enough: the Dock icon for the application will appear in its default form (the Java “coffee cup”) before the code to change the icon is executed. Therefore setting the -Xdock:icon option is preferable since the desired icon is shown immediately. The programmatic API can still be used if the application wishes to modify the icon later, for example to indicate a status change.

Although plain PNG and JPEG files can be used for the icon, for best results use Apple’s ICNS container format. This should contain multiple copies of the icon at different size, to allow the Dock to smoothly scale the image.

Default Value:

If the -Xdock argument is not specified, the application name is displayed as “java” and the default Java icon – the “coffee cup” – is used.

Errors:

If an incorrect icon path is used with -Xdock:icon then no error is printed, but the default Java icon is used.

Arguments Related to -Xdock:

TODO: link to -XstartOnFirstThread

Related Posts:

• Oracle article on bringing Java Applications to MacOS.
• Documentation on the ICNS file format.
• The MacOS Dock (Wikipedia)
• MacOS Mission Control (Wikipedia)

NOTE:

If you have additional comments, interesting experiences or even point of disagreement with this JVM argument description, please leave a comment. Your insights will help the entire 10+ million java developer community to develop one standard source of documentation for all the JVM arguments.