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

public Class Desktop

extends Object
Class Inheritance
Imports
java.awt.desktop.AboutEvent, .AboutHandler, .OpenFilesHandler, .OpenURIEvent, .OpenURIHandler, .PreferencesEvent, .PreferencesHandler, .PrintFilesHandler, .QuitHandler, .QuitStrategy, .SystemEventListener, java.awt.peer.DesktopPeer, java.io.File, .IOException, java.net.URI, .URISyntaxException, java.util.Objects, javax.swing.JMenuBar, sun.awt.SunToolkit
The Desktop class allows interact with various desktop capabilities.

Supported operations include:

This class provides methods corresponding to these operations. The methods look for the associated application registered on the current platform, and launch it to handle a URI or file. If there is no associated application or the associated application fails to be launched, an exception is thrown. Please see Desktop.Action for the full list of supported operations and capabilities.

An application is registered to a URI or file type. The mechanism of registering, accessing, and launching the associated application is platform-dependent.

Each operation is an action type represented by the Desktop.Action class.

Note

when some action is invoked and the associated application is executed, it will be executed on the same system as the one on which the Java application was launched.

Authors
Armin Chen, George Zhang
Since
1.6
See Also
Action

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
Desktop.Action

Represents an action type.

Field Summary

Modifier and TypeField and Description
private static Desktop
desktop

private DesktopPeer
peer

Constructor Summary

AccessConstructor and Description
private
Desktop()

Suppresses default constructor for noninstantiability.

Method Summary

Modifier and TypeMethod and Description
public void
addAppEventListener(final SystemEventListener
listener
listener)

Adds sub-types of SystemEventListener to listen for notifications from the native system.

public void
browse(URI
the URI to be displayed in the user default browser
uri)

Launches the default browser to display a URI.

public void
browseFileDirectory(File
the file
file)

Opens a folder containing the file and selects it in a default system file manager.

private void
checkActionSupport(Desktop.Action
the action type in question
actionType)

Checks if the action type is supported.

private static void
checkFileValidation(File file)

Checks if the file is a valid file and readable.

public void
disableSuddenTermination()

Prevents this application from being suddenly terminated.

public void
edit(File
the file to be opened for editing
file)

Launches the associated editor application and opens a file for editing.

public void
enableSuddenTermination()

Enables this application to be suddenly terminated.

public static synchronized Desktop

Returns:

the Desktop instance
getDesktop()

Returns the Desktop instance of the current desktop context.

public static boolean

Returns:

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

Tests whether this class is supported on the current platform.

public boolean

Returns:

true if the specified action is supported on the current platform; false otherwise
isSupported(Desktop.Action
the specified Action
action)

Tests whether an action is supported on the current platform.

public void
mail()

Launches the mail composing window of the user default mail client.

public void
mail(URI
the specified mailto: URI
mailtoURI)

Launches the mail composing window of the user default mail client, filling the message fields specified by a mailto: URI.

public boolean

Returns:

returns true if successfully moved the file to the trash.
moveToTrash(File
the file
file)

Moves the specified file to the trash.

public void
open(File
the file to be opened with the associated application
file)

Launches the associated application to open the file.

public void
openHelpViewer()

Opens the native help viewer application.

public void
removeAppEventListener(final SystemEventListener
listener
listener)

Removes sub-types of SystemEventListener to listen for notifications from the native system.

public void
requestForeground(final boolean
if all windows of this application should be moved to the foreground, or only the foremost one
allWindows)

Requests this application to move to the foreground.

public void
setAboutHandler(final AboutHandler
the handler to respond to the java.awt.desktop.AboutHandler#handleAbout(AboutEvent) message
aboutHandler)

Installs a handler to show a custom About window for your application.

public void
setDefaultMenuBar(final JMenuBar
to use when no other frames are active
menuBar)

Sets the default menu bar to use when there are no active frames.

public void
setOpenFileHandler(final OpenFilesHandler
handler
openFileHandler)

Installs the handler which is notified when the application is asked to open a list of files.

public void
setOpenURIHandler(final OpenURIHandler
handler
openURIHandler)

Installs the handler which is notified when the application is asked to open a URL.

public void
setPreferencesHandler(final PreferencesHandler
the handler to respond to the PreferencesHandler#handlePreferences(PreferencesEvent)
preferencesHandler)

Installs a handler to show a custom Preferences window for your application.

public void
setPrintFileHandler(final PrintFilesHandler
handler
printFileHandler)

Installs the handler which is notified when the application is asked to print a list of files.

public void
setQuitHandler(final QuitHandler
the handler that is called when the application is asked to quit
quitHandler)

Installs the handler which determines if the application should quit.

public void
setQuitStrategy(final QuitStrategy
the way this application should be shutdown
strategy)

Sets the default strategy used to quit this application.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

desktopback to summary
private static Desktop desktop
peerback to summary
private DesktopPeer peer

Constructor Detail

Desktopback to summary
private Desktop()

Suppresses default constructor for noninstantiability.

Method Detail

addAppEventListenerback to summary
public void addAppEventListener(final SystemEventListener listener)

Adds sub-types of SystemEventListener to listen for notifications from the native system. Has no effect if SystemEventListener's sub-type is unsupported on the current platform.

Parameters
listener:SystemEventListener

listener

Since
9
See Also
java.awt.desktop.AppForegroundListener, java.awt.desktop.AppHiddenListener, java.awt.desktop.AppReopenedListener, java.awt.desktop.ScreenSleepListener, java.awt.desktop.SystemSleepListener, java.awt.desktop.UserSessionListener
browseback to summary
public void browse(URI uri) throws IOException

Launches the default browser to display a URI. If the default browser is not able to handle the specified URI, the application registered for handling URIs of the specified type is invoked. The application is determined from the protocol and path of the URI, as defined by the URI class.

Parameters
uri:URI

the URI to be displayed in the user default browser

Exceptions
IOException:
if the user default browser is not found, or it fails to be launched, or the default handler application failed to be launched
NullPointerException:
if uri is null
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#BROWSE action
See Also
java.net.URI
browseFileDirectoryback to summary
public void browseFileDirectory(File file)

Opens a folder containing the file and selects it in a default system file manager.

Parameters
file:File

the file

Exceptions
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#BROWSE_FILE_DIR action
NullPointerException:
if file is null
IllegalArgumentException:
if the specified file or its parent doesn't exist
Since
9
checkActionSupportback to summary
private void checkActionSupport(Desktop.Action actionType)

Checks if the action type is supported.

Parameters
actionType:Desktop.Action

the action type in question

Exceptions
UnsupportedOperationException:
if the specified action type is not supported on the current platform
checkFileValidationback to summary
private static void checkFileValidation(File file)

Checks if the file is a valid file and readable.

Exceptions
NullPointerException:
if file is null
IllegalArgumentException:
if file doesn't exist
disableSuddenTerminationback to summary
public void disableSuddenTermination()

Prevents this application from being suddenly terminated. Call this method to indicate that your application has unsaved state, and may not be terminated without notification.

Exceptions
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#APP_SUDDEN_TERMINATION action
Since
9
See Also
enableSuddenTermination()
editback to summary
public void edit(File file) throws IOException

Launches the associated editor application and opens a file for editing.

Parameters
file:File

the file to be opened for editing

Exceptions
IOException:
if the specified file has no associated editor, or the associated application fails to be launched
NullPointerException:
if the specified file is null
IllegalArgumentException:
if the specified file doesn't exist
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#EDIT action
enableSuddenTerminationback to summary
public void enableSuddenTermination()

Enables this application to be suddenly terminated. Call this method to indicate your application's state is saved, and requires no notification to be terminated. Letting your application remain terminatable improves the user experience by avoiding re-paging in your application when it's asked to quit. Note: enabling sudden termination will allow your application to be quit without notifying your QuitHandler, or running any shutdown hooks. E.g. user-initiated Cmd-Q, logout, restart, or shutdown requests will effectively "kill -KILL" your application.

Exceptions
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#APP_SUDDEN_TERMINATION action
Since
9
See Also
disableSuddenTermination()
getDesktopback to summary
public static synchronized Desktop getDesktop()

Returns the Desktop instance of the current desktop context. On some platforms the Desktop API may not be supported; use the isDesktopSupported method to determine if the current desktop is supported.

Returns:Desktop

the Desktop instance

Exceptions
HeadlessException:
if GraphicsEnvironment#isHeadless() returns true
UnsupportedOperationException:
if this class is not supported on the current platform
See Also
isDesktopSupported(), java.awt.GraphicsEnvironment#isHeadless
isDesktopSupportedback to summary
public static boolean isDesktopSupported()

Tests whether this class is supported on the current platform. If it's supported, use getDesktop() to retrieve an instance.

Returns:boolean

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

See Also
getDesktop()
isSupportedback to summary
public boolean isSupported(Desktop.Action action)

Tests whether an action is supported on the current platform.

Even when the platform supports an action, a file or URI may not have a registered application for the action. For example, most of the platforms support the Desktop.Action#OPEN action. But for a specific file, there may not be an application registered to open it. In this case, isSupported(Action) may return true, but the corresponding action method will throw an IOException.

Parameters
action:Desktop.Action

the specified Action

Returns:boolean

true if the specified action is supported on the current platform; false otherwise

See Also
Desktop.Action
mailback to summary
public void mail() throws IOException

Launches the mail composing window of the user default mail client.

Exceptions
IOException:
if the user default mail client is not found, or it fails to be launched
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#MAIL action
mailback to summary
public void mail(URI mailtoURI) throws IOException

Launches the mail composing window of the user default mail client, filling the message fields specified by a mailto: URI.

A mailto: URI can specify message fields including "to", "cc", "subject", "body", etc. See The mailto URL scheme (RFC 2368) for the mailto: URI specification details.

Parameters
mailtoURI:URI

the specified mailto: URI

Exceptions
IOException:
if the user default mail client is not found or fails to be launched
NullPointerException:
if the specified URI is null
IllegalArgumentException:
if the URI scheme is not "mailto"
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#MAIL action
External Specification
https://www.rfc-editor.org/info/rfc2368
See Also
java.net.URI
moveToTrashback to summary
public boolean moveToTrash(File file)

Moves the specified file to the trash.

Parameters
file:File

the file

Returns:boolean

returns true if successfully moved the file to the trash.

Exceptions
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#MOVE_TO_TRASH action
NullPointerException:
if file is null
IllegalArgumentException:
if the specified file doesn't exist
Since
9
openback to summary
public void open(File file) throws IOException

Launches the associated application to open the file.

If the specified file is a directory, the file manager of the current platform is launched to open it.

Parameters
file:File

the file to be opened with the associated application

Exceptions
IOException:
if the specified file has no associated application or the associated application fails to be launched
NullPointerException:
if file is null
IllegalArgumentException:
if the specified file doesn't exist
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#OPEN action
openHelpViewerback to summary
public void openHelpViewer()

Opens the native help viewer application.

Implementation Note

Please note that for Mac OS, it opens the native help viewer application if a Help Book has been added to the application bundler and registered in the Info.plist with CFBundleHelpBookFolder

Exceptions
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#APP_HELP_VIEWER action
Since
9
printback to summary
public void print(File file) throws IOException

Prints a file with the native desktop printing facility, using the associated application's print command.

Parameters
file:File

the file to be printed

Exceptions
IOException:
if the specified file has no associated application that can be used to print it
NullPointerException:
if the specified file is null
IllegalArgumentException:
if the specified file doesn't exist
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#PRINT action
removeAppEventListenerback to summary
public void removeAppEventListener(final SystemEventListener listener)

Removes sub-types of SystemEventListener to listen for notifications from the native system. Has no effect if SystemEventListener's sub-type is unsupported on the current platform.

Parameters
listener:SystemEventListener

listener

Since
9
See Also
java.awt.desktop.AppForegroundListener, java.awt.desktop.AppHiddenListener, java.awt.desktop.AppReopenedListener, java.awt.desktop.ScreenSleepListener, java.awt.desktop.SystemSleepListener, java.awt.desktop.UserSessionListener
requestForegroundback to summary
public void requestForeground(final boolean allWindows)

Requests this application to move to the foreground.

Parameters
allWindows:boolean

if all windows of this application should be moved to the foreground, or only the foremost one

Exceptions
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#APP_REQUEST_FOREGROUND action
Since
9
setAboutHandlerback to summary
public void setAboutHandler(final AboutHandler aboutHandler)

Installs a handler to show a custom About window for your application.

Setting the java.awt.desktop.AboutHandler to null reverts it to the default behavior.

Parameters
aboutHandler:AboutHandler

the handler to respond to the java.awt.desktop.AboutHandler#handleAbout(AboutEvent) message

Exceptions
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#APP_ABOUT action
Since
9
setDefaultMenuBarback to summary
public void setDefaultMenuBar(final JMenuBar menuBar)

Sets the default menu bar to use when there are no active frames.

Parameters
menuBar:JMenuBar

to use when no other frames are active

Exceptions
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#APP_MENU_BAR action
Since
9
setOpenFileHandlerback to summary
public void setOpenFileHandler(final OpenFilesHandler openFileHandler)

Installs the handler which is notified when the application is asked to open a list of files.

Implementation Note

Please note that for macOS, notifications are only sent if the Java app is a bundled application, with a CFBundleDocumentTypes array present in its Info.plist. Check the Apple Developer Documentation for more information about Info.plist.

Parameters
openFileHandler:OpenFilesHandler

handler

Exceptions
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#APP_OPEN_FILE action
Since
9
setOpenURIHandlerback to summary
public void setOpenURIHandler(final OpenURIHandler openURIHandler)

Installs the handler which is notified when the application is asked to open a URL. Setting the handler to null causes all OpenURIHandler#openURI(OpenURIEvent) requests to be enqueued until another handler is set.

Implementation Note

Please note that for macOS, notifications are only sent if the Java app is a bundled application, with a CFBundleURLTypes array present in its Info.plist. Check the Apple Developer Documentation for more information about Info.plist.

Parameters
openURIHandler:OpenURIHandler

handler

Exceptions
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#APP_OPEN_URI action
Since
9
setPreferencesHandlerback to summary
public void setPreferencesHandler(final PreferencesHandler preferencesHandler)

Installs a handler to show a custom Preferences window for your application.

Setting the PreferencesHandler to null reverts it to the default behavior

Parameters
preferencesHandler:PreferencesHandler

the handler to respond to the PreferencesHandler#handlePreferences(PreferencesEvent)

Exceptions
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#APP_PREFERENCES action
Since
9
setPrintFileHandlerback to summary
public void setPrintFileHandler(final PrintFilesHandler printFileHandler)

Installs the handler which is notified when the application is asked to print a list of files.

Implementation Note

Please note that for macOS, notifications are only sent if the Java app is a bundled application, with a CFBundleDocumentTypes array present in its Info.plist. Check the Apple Developer Documentation for more information about Info.plist.

Parameters
printFileHandler:PrintFilesHandler

handler

Exceptions
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#APP_PRINT_FILE action
Since
9
setQuitHandlerback to summary
public void setQuitHandler(final QuitHandler quitHandler)

Installs the handler which determines if the application should quit. The handler is passed a one-shot java.awt.desktop.QuitResponse which can cancel or proceed with the quit. Setting the handler to null causes all quit requests to directly perform the default QuitStrategy.

Parameters
quitHandler:QuitHandler

the handler that is called when the application is asked to quit

Exceptions
UnsupportedOperationException:
if the current platform does not support the Desktop.Action#APP_QUIT_HANDLER action
Since
9
setQuitStrategyback to summary
public void setQuitStrategy(final QuitStrategy strategy)

Sets the default strategy used to quit this application. The default is calling SYSTEM_EXIT_0.

Parameters
strategy:QuitStrategy

the way this application should be shutdown

Since
9
See Also
QuitStrategy
java.awt back to summary

public final Enum Desktop.Action

extends Enum<Desktop.Action>
Class Inheritance
Represents an action type. Each platform supports a different set of actions. You may use the Desktop#isSupported method to determine if the given action is supported by the current platform.
Since
1.6
See Also
java.awt.Desktop#isSupported(java.awt.Desktop.Action)

Field Summary

Modifier and TypeField and Description
public static final Desktop.Action
APP_ABOUT

Represents an AboutHandler

public static final Desktop.Action
APP_EVENT_FOREGROUND

Represents an AppForegroundListener

public static final Desktop.Action
APP_EVENT_HIDDEN

Represents an AppHiddenListener

public static final Desktop.Action
APP_EVENT_REOPENED

Represents an AppReopenedListener

public static final Desktop.Action
APP_EVENT_SCREEN_SLEEP

Represents a ScreenSleepListener

public static final Desktop.Action
APP_EVENT_SYSTEM_SLEEP

Represents a SystemSleepListener

public static final Desktop.Action
APP_EVENT_USER_SESSION

Represents a UserSessionListener

public static final Desktop.Action
APP_HELP_VIEWER

Represents a HelpViewer

public static final Desktop.Action
APP_MENU_BAR

Represents a menu bar

public static final Desktop.Action
APP_OPEN_FILE

Represents an OpenFilesHandler

public static final Desktop.Action
APP_OPEN_URI

Represents an OpenURIHandler

public static final Desktop.Action
APP_PREFERENCES

Represents a PreferencesHandler

public static final Desktop.Action
APP_PRINT_FILE

Represents a PrintFilesHandler

public static final Desktop.Action
APP_QUIT_HANDLER

Represents a QuitHandler

public static final Desktop.Action
APP_QUIT_STRATEGY

Represents a QuitStrategy

public static final Desktop.Action
APP_REQUEST_FOREGROUND

Represents a requestForeground

public static final Desktop.Action
APP_SUDDEN_TERMINATION

Represents a SuddenTermination

public static final Desktop.Action
BROWSE

Represents a "browse" action.

public static final Desktop.Action
BROWSE_FILE_DIR

Represents a browse file directory

public static final Desktop.Action
EDIT

Represents an "edit" action.

public static final Desktop.Action
MAIL

Represents a "mail" action.

public static final Desktop.Action
MOVE_TO_TRASH

Represents a move to trash

public static final Desktop.Action
OPEN

Represents an "open" action.

public static final Desktop.Action
PRINT

Represents a "print" action.

Constructor Summary

AccessConstructor and Description
private
Action()

Method Summary

Modifier and TypeMethod and Description
public static Desktop.Action
valueOf(String name)

public static Desktop.Action[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

APP_ABOUTback to summary
public static final Desktop.Action APP_ABOUT

Represents an AboutHandler

Since
9
See Also
setAboutHandler(java.awt.desktop.AboutHandler)
APP_EVENT_FOREGROUNDback to summary
public static final Desktop.Action APP_EVENT_FOREGROUND

Represents an AppForegroundListener

Since
9
See Also
java.awt.desktop.AppForegroundListener
APP_EVENT_HIDDENback to summary
public static final Desktop.Action APP_EVENT_HIDDEN

Represents an AppHiddenListener

Since
9
See Also
java.awt.desktop.AppHiddenListener
APP_EVENT_REOPENEDback to summary
public static final Desktop.Action APP_EVENT_REOPENED

Represents an AppReopenedListener

Since
9
See Also
java.awt.desktop.AppReopenedListener
APP_EVENT_SCREEN_SLEEPback to summary
public static final Desktop.Action APP_EVENT_SCREEN_SLEEP

Represents a ScreenSleepListener

Since
9
See Also
java.awt.desktop.ScreenSleepListener
APP_EVENT_SYSTEM_SLEEPback to summary
public static final Desktop.Action APP_EVENT_SYSTEM_SLEEP

Represents a SystemSleepListener

Since
9
See Also
java.awt.desktop.SystemSleepListener
APP_EVENT_USER_SESSIONback to summary
public static final Desktop.Action APP_EVENT_USER_SESSION

Represents a UserSessionListener

Since
9
See Also
java.awt.desktop.UserSessionListener
APP_HELP_VIEWERback to summary
public static final Desktop.Action APP_HELP_VIEWER

Represents a HelpViewer

Since
9
See Also
openHelpViewer()
APP_MENU_BARback to summary
public static final Desktop.Action APP_MENU_BAR

Represents a menu bar

Since
9
See Also
setDefaultMenuBar(javax.swing.JMenuBar)
APP_OPEN_FILEback to summary
public static final Desktop.Action APP_OPEN_FILE

Represents an OpenFilesHandler

Since
9
See Also
setOpenFileHandler(java.awt.desktop.OpenFilesHandler)
APP_OPEN_URIback to summary
public static final Desktop.Action APP_OPEN_URI

Represents an OpenURIHandler

Since
9
See Also
setOpenURIHandler(java.awt.desktop.OpenURIHandler)
APP_PREFERENCESback to summary
public static final Desktop.Action APP_PREFERENCES

Represents a PreferencesHandler

Since
9
See Also
setPreferencesHandler(java.awt.desktop.PreferencesHandler)
APP_PRINT_FILEback to summary
public static final Desktop.Action APP_PRINT_FILE

Represents a PrintFilesHandler

Since
9
See Also
setPrintFileHandler(java.awt.desktop.PrintFilesHandler)
APP_QUIT_HANDLERback to summary
public static final Desktop.Action APP_QUIT_HANDLER

Represents a QuitHandler

Since
9
See Also
setQuitHandler(java.awt.desktop.QuitHandler)
APP_QUIT_STRATEGYback to summary
public static final Desktop.Action APP_QUIT_STRATEGY

Represents a QuitStrategy

Since
9
See Also
setQuitStrategy(java.awt.desktop.QuitStrategy)
APP_REQUEST_FOREGROUNDback to summary
public static final Desktop.Action APP_REQUEST_FOREGROUND

Represents a requestForeground

Since
9
See Also
requestForeground(boolean)
APP_SUDDEN_TERMINATIONback to summary
public static final Desktop.Action APP_SUDDEN_TERMINATION

Represents a SuddenTermination

Since
9
See Also
enableSuddenTermination()
BROWSEback to summary
public static final Desktop.Action BROWSE

Represents a "browse" action.

See Also
Desktop#browse(java.net.URI)
BROWSE_FILE_DIRback to summary
public static final Desktop.Action BROWSE_FILE_DIR

Represents a browse file directory

Since
9
See Also
browseFileDirectory(java.io.File)
EDITback to summary
public static final Desktop.Action EDIT

Represents an "edit" action.

See Also
Desktop#edit(java.io.File)
MAILback to summary
public static final Desktop.Action MAIL

Represents a "mail" action.

See Also
Desktop#mail(), Desktop#mail(java.net.URI)
MOVE_TO_TRASHback to summary
public static final Desktop.Action MOVE_TO_TRASH

Represents a move to trash

Since
9
See Also
moveToTrash(java.io.File)
OPENback to summary
public static final Desktop.Action OPEN

Represents an "open" action.

See Also
Desktop#open(java.io.File)
PRINTback to summary
public static final Desktop.Action PRINT

Represents a "print" action.

See Also
Desktop#print(java.io.File)

Constructor Detail

Actionback to summary
private Action()

Method Detail

valueOfback to summary
public static Desktop.Action valueOf(String name)
valuesback to summary
public static Desktop.Action[] values()