public class Desktop extends Object
Desktop
class allows interact with various desktop capabilities. Supported operations include:
mailto
URI; 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.
Modifier and Type | Class | Description |
---|---|---|
static enum |
Desktop.Action |
Represents an action type. |
Modifier and Type | Method | Description |
---|---|---|
void |
addAppEventListener |
Adds sub-types of SystemEventListener to listen for notifications from the native system. |
void |
browse |
Launches the default browser to display a URI . |
void |
browseFileDirectory |
Opens a folder containing the file and selects it in a default system file manager. |
void |
disableSuddenTermination() |
Prevents this application from being suddenly terminated. |
void |
edit |
Launches the associated editor application and opens a file for editing. |
void |
enableSuddenTermination() |
Enables this application to be suddenly terminated. |
static Desktop |
getDesktop() |
Returns the Desktop instance of the current desktop context. |
static boolean |
isDesktopSupported() |
Tests whether this class is supported on the current platform. |
boolean |
isSupported |
Tests whether an action is supported on the current platform. |
void |
mail() |
Launches the mail composing window of the user default mail client. |
void |
mail |
Launches the mail composing window of the user default mail client, filling the message fields specified by a
mailto: URI. |
boolean |
moveToTrash |
Moves the specified file to the trash. |
void |
open |
Launches the associated application to open the file. |
void |
openHelpViewer() |
Opens the native help viewer application. |
void |
print |
Prints a file with the native desktop printing facility, using the associated application's print command. |
void |
removeAppEventListener |
Removes sub-types of SystemEventListener to listen for notifications from the native system. |
void |
requestForeground |
Requests this application to move to the foreground. |
void |
setAboutHandler |
Installs a handler to show a custom About window for your application. |
void |
setDefaultMenuBar |
Sets the default menu bar to use when there are no active frames. |
void |
setOpenFileHandler |
Installs the handler which is notified when the application is asked to open a list of files. |
void |
setOpenURIHandler |
Installs the handler which is notified when the application is asked to open a URL. |
void |
setPreferencesHandler |
Installs a handler to show a custom Preferences window for your application. |
void |
setPrintFileHandler |
Installs the handler which is notified when the application is asked to print a list of files. |
void |
setQuitHandler |
Installs the handler which determines if the application should quit. |
void |
setQuitStrategy |
Sets the default strategy used to quit this application. |
public static Desktop getDesktop()
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.HeadlessException
- if GraphicsEnvironment.isHeadless()
returns true
UnsupportedOperationException
- if this class is not supported on the current platformpublic static boolean isDesktopSupported()
getDesktop()
to retrieve an instance.true
if this class is supported on the current platform; false
otherwisepublic boolean isSupported(Desktop.Action action)
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
.
action
- the specified Desktop.Action
true
if the specified action is supported on the current platform; false
otherwisepublic void open(File file) throws IOException
If the specified file is a directory, the file manager of the current platform is launched to open it.
file
- the file to be opened with the associated applicationNullPointerException
- if file
is null
IllegalArgumentException
- if the specified file doesn't existUnsupportedOperationException
- if the current platform does not support the Desktop.Action.OPEN
actionIOException
- if the specified file has no associated application or the associated application fails to be launchedSecurityException
- if a security manager exists and its SecurityManager.checkRead(java.lang.String)
method denies read access to the file, or it denies the AWTPermission("showWindowWithoutWarningBanner")
permission, or the calling thread is not allowed to create a subprocesspublic void edit(File file) throws IOException
file
- the file to be opened for editingNullPointerException
- if the specified file is null
IllegalArgumentException
- if the specified file doesn't existUnsupportedOperationException
- if the current platform does not support the Desktop.Action.EDIT
actionIOException
- if the specified file has no associated editor, or the associated application fails to be launchedSecurityException
- if a security manager exists and its SecurityManager.checkRead(java.lang.String)
method denies read access to the file, or SecurityManager.checkWrite(java.lang.String)
method denies write access to the file, or it denies the AWTPermission("showWindowWithoutWarningBanner")
permission, or the calling thread is not allowed to create a subprocesspublic void print(File file) throws IOException
file
- the file to be printedNullPointerException
- if the specified file is
null
IllegalArgumentException
- if the specified file doesn't existUnsupportedOperationException
- if the current platform does not support the Desktop.Action.PRINT
actionIOException
- if the specified file has no associated application that can be used to print itSecurityException
- if a security manager exists and its SecurityManager.checkRead(java.lang.String)
method denies read access to the file, or its SecurityManager.checkPrintJobAccess()
method denies the permission to print the file, or the calling thread is not allowed to create a subprocesspublic void browse(URI uri) throws IOException
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.uri
- the URI to be displayed in the user default browserNullPointerException
- if uri
is null
UnsupportedOperationException
- if the current platform does not support the Desktop.Action.BROWSE
actionIOException
- if the user default browser is not found, or it fails to be launched, or the default handler application failed to be launchedSecurityException
- if a security manager exists and it denies the AWTPermission("showWindowWithoutWarningBanner")
permission, or the calling thread is not allowed to create a subprocesspublic void mail() throws IOException
UnsupportedOperationException
- if the current platform does not support the Desktop.Action.MAIL
actionIOException
- if the user default mail client is not found, or it fails to be launchedSecurityException
- if a security manager exists and it denies the AWTPermission("showWindowWithoutWarningBanner")
permission, or the calling thread is not allowed to create a subprocesspublic void mail(URI mailtoURI) throws IOException
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.
mailtoURI
- the specified mailto:
URINullPointerException
- 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
actionIOException
- if the user default mail client is not found or fails to be launchedSecurityException
- if a security manager exists and it denies the AWTPermission("showWindowWithoutWarningBanner")
permission, or the calling thread is not allowed to create a subprocesspublic void addAppEventListener(SystemEventListener listener)
SystemEventListener
to listen for notifications from the native system. Has no effect if SystemEventListener's sub-type is unsupported on the current platform.listener
- listenerSecurityException
- if a security manager exists and it denies the RuntimePermission("canProcessApplicationEvents")
permissionpublic void removeAppEventListener(SystemEventListener listener)
SystemEventListener
to listen for notifications from the native system. Has no effect if SystemEventListener's sub-type is unsupported on the current platform.listener
- listenerSecurityException
- if a security manager exists and it denies the RuntimePermission("canProcessApplicationEvents")
permissionpublic void setAboutHandler(AboutHandler aboutHandler)
Setting the AboutHandler
to null
reverts it to the default behavior.
aboutHandler
- the handler to respond to the AboutHandler.handleAbout(AboutEvent)
messageSecurityException
- if a security manager exists and it denies the RuntimePermission("canProcessApplicationEvents")
permissionUnsupportedOperationException
- if the current platform does not support the Desktop.Action.APP_ABOUT
actionpublic void setPreferencesHandler(PreferencesHandler preferencesHandler)
Setting the PreferencesHandler
to null
reverts it to the default behavior
preferencesHandler
- the handler to respond to the PreferencesHandler.handlePreferences(PreferencesEvent)
SecurityException
- if a security manager exists and it denies the RuntimePermission("canProcessApplicationEvents")
permissionUnsupportedOperationException
- if the current platform does not support the Desktop.Action.APP_PREFERENCES
actionpublic void setOpenFileHandler(OpenFilesHandler openFileHandler)
CFBundleDocumentTypes
array present in its Info.plist
. Check the Apple Developer Documentation for more information about Info.plist
.openFileHandler
- handlerSecurityException
- if a security manager exists and its SecurityManager.checkRead(java.lang.String)
method denies read access to the files, or it denies the RuntimePermission("canProcessApplicationEvents")
permission, or the calling thread is not allowed to create a subprocessUnsupportedOperationException
- if the current platform does not support the Desktop.Action.APP_OPEN_FILE
actionpublic void setPrintFileHandler(PrintFilesHandler printFileHandler)
CFBundleDocumentTypes
array present in its Info.plist
. Check the Apple Developer Documentation for more information about Info.plist
.printFileHandler
- handlerSecurityException
- if a security manager exists and its SecurityManager.checkPrintJobAccess()
method denies the permission to print or it denies the RuntimePermission("canProcessApplicationEvents")
permissionUnsupportedOperationException
- if the current platform does not support the Desktop.Action.APP_PRINT_FILE
actionpublic void setOpenURIHandler(OpenURIHandler openURIHandler)
null
causes all OpenURIHandler.openURI(OpenURIEvent)
requests to be enqueued until another handler is set.CFBundleDocumentTypes
array present in its Info.plist
. Check the Apple Developer Documentation for more information about Info.plist
.openURIHandler
- handler RuntimePermission("canProcessApplicationEvents")
permission, or the calling thread is not allowed to create a subprocessUnsupportedOperationException
- if the current platform does not support the Desktop.Action.APP_OPEN_URI
actionpublic void setQuitHandler(QuitHandler quitHandler)
QuitResponse
which can cancel or proceed with the quit. Setting the handler to null
causes all quit requests to directly perform the default QuitStrategy
.quitHandler
- the handler that is called when the application is asked to quitSecurityException
- if a security manager exists and it will not allow the caller to invoke System.exit
or it denies the RuntimePermission("canProcessApplicationEvents")
permissionUnsupportedOperationException
- if the current platform does not support the Desktop.Action.APP_QUIT_HANDLER
actionpublic void setQuitStrategy(QuitStrategy strategy)
strategy
- the way this application should be shutdownSecurityException
- if a security manager exists and it will not allow the caller to invoke System.exit
or it denies the RuntimePermission("canProcessApplicationEvents")
permissionUnsupportedOperationException
- if the current platform does not support the Desktop.Action.APP_QUIT_STRATEGY
actionpublic void enableSuddenTermination()
SecurityException
- if a security manager exists and it will not allow the caller to invoke System.exit
or it denies the RuntimePermission("canProcessApplicationEvents")
permissionUnsupportedOperationException
- if the current platform does not support the Desktop.Action.APP_SUDDEN_TERMINATION
actionpublic void disableSuddenTermination()
SecurityException
- if a security manager exists and it will not allow the caller to invoke System.exit
or it denies the RuntimePermission("canProcessApplicationEvents")
permissionUnsupportedOperationException
- if the current platform does not support the Desktop.Action.APP_SUDDEN_TERMINATION
actionpublic void requestForeground(boolean allWindows)
allWindows
- if all windows of this application should be moved to the foreground, or only the foremost oneSecurityException
- if a security manager exists and it denies the RuntimePermission("canProcessApplicationEvents")
permission.UnsupportedOperationException
- if the current platform does not support the Desktop.Action.APP_REQUEST_FOREGROUND
actionpublic void openHelpViewer()
SecurityException
- if a security manager exists and it denies the RuntimePermission("canProcessApplicationEvents")
permission, or it denies the AWTPermission("showWindowWithoutWarningBanner")
permission, or the calling thread is not allowed to create a subprocessUnsupportedOperationException
- if the current platform does not support the Desktop.Action.APP_HELP_VIEWER
actionpublic void setDefaultMenuBar(JMenuBar menuBar)
menuBar
- to use when no other frames are activeSecurityException
- if a security manager exists and it denies the RuntimePermission("canProcessApplicationEvents")
permission.UnsupportedOperationException
- if the current platform does not support the Desktop.Action.APP_MENU_BAR
actionpublic void browseFileDirectory(File file)
file
and selects it in a default system file manager.file
- the fileSecurityException
- If a security manager exists and its SecurityManager.checkRead(java.lang.String)
method denies read access to the file or to its parent, or it denies the AWTPermission("showWindowWithoutWarningBanner")
permission, or the calling thread is not allowed to create a subprocessUnsupportedOperationException
- if the current platform does not support the Desktop.Action.BROWSE_FILE_DIR
actionNullPointerException
- if file
is null
IllegalArgumentException
- if the specified file or its parent doesn't existpublic boolean moveToTrash(File file)
file
- the fileSecurityException
- If a security manager exists and its SecurityManager.checkDelete(java.lang.String)
method denies deletion of the fileUnsupportedOperationException
- if the current platform does not support the Desktop.Action.MOVE_TO_TRASH
actionNullPointerException
- if file
is null
IllegalArgumentException
- if the specified file doesn't exist
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/java/awt/Desktop.html