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.
Desktop.Action
Modifier and Type | Class | Description |
---|---|---|
static class |
Desktop.Action |
Represents an action type.
|
Modifier and Type | Method | Description |
---|---|---|
void |
addAppEventListener(SystemEventListener listener) |
Adds sub-types of
SystemEventListener to listen for notifications
from the native system. |
void |
browse(URI uri) |
Launches the default browser to display a
URI . |
void |
browseFileDirectory(File file) |
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(File file) |
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(Desktop.Action action) |
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(URI mailtoURI) |
Launches the mail composing window of the user default mail
client, filling the message fields specified by a
mailto: URI. |
boolean |
moveToTrash(File file) |
Moves the specified file to the trash.
|
void |
open(File file) |
Launches the associated application to open the file.
|
void |
openHelpViewer() |
Opens the native help viewer application.
|
void |
print(File file) |
Prints a file with the native desktop printing facility, using
the associated application's print command.
|
void |
removeAppEventListener(SystemEventListener listener) |
Removes sub-types of
SystemEventListener to listen for notifications
from the native system. |
void |
requestForeground(boolean allWindows) |
Requests this application to move to the foreground.
|
void |
setAboutHandler(AboutHandler aboutHandler) |
Installs a handler to show a custom About window for your application.
|
void |
setDefaultMenuBar(JMenuBar menuBar) |
Sets the default menu bar to use when there are no active frames.
|
void |
setOpenFileHandler(OpenFilesHandler openFileHandler) |
Installs the handler which is notified when the application is asked to
open a list of files.
|
void |
setOpenURIHandler(OpenURIHandler openURIHandler) |
Installs the handler which is notified when the application is asked to
open a URL.
|
void |
setPreferencesHandler(PreferencesHandler preferencesHandler) |
Installs a handler to show a custom Preferences window for your
application.
|
void |
setPrintFileHandler(PrintFilesHandler printFileHandler) |
Installs the handler which is notified when the application is asked to
print a list of files.
|
void |
setQuitHandler(QuitHandler quitHandler) |
Installs the handler which determines if the application should quit.
|
void |
setQuitStrategy(QuitStrategy strategy) |
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 platformisDesktopSupported()
,
GraphicsEnvironment.isHeadless()
public static boolean isDesktopSupported()
getDesktop()
to retrieve an
instance.true
if this class is supported on the
current platform; false
otherwisegetDesktop()
public 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
otherwiseDesktop.Action
public 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
subprocessAWTPermission
public 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
subprocessAWTPermission
public 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.
If the calling thread does not have the necessary permissions,
and this is invoked from within an applet,
AppletContext.showDocument()
is used. Similarly, if the calling
does not have the necessary permissions, and this is invoked from within
a Java Web Started application, BasicService.showDocument()
is used.
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
subprocess; and not invoked from within an applet or Java Web Started
applicationIllegalArgumentException
- if the necessary permissions
are not available and the URI can not be converted to a URL
URI
,
AWTPermission
,
AppletContext
public 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
subprocessAWTPermission
public 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
subprocessURI
,
AWTPermission
public 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")
permissionAppForegroundListener
,
AppHiddenListener
,
AppReopenedListener
,
ScreenSleepListener
,
SystemSleepListener
,
UserSessionListener
public 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")
permissionAppForegroundListener
,
AppHiddenListener
,
AppReopenedListener
,
ScreenSleepListener
,
SystemSleepListener
,
UserSessionListener
public 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. See the
Info.plist Key Reference for more information about adding a
CFBundleDocumentTypes
key to your app's 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. See the
Info.plist Key Reference for more information about adding a
CFBundleDocumentTypes
key to your app's 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. See the
Info.plist Key Reference for more information about adding a
CFBundleDocumentTypes
key to your app's 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
actionQuitStrategy
public 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
actiondisableSuddenTermination()
public 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
actionenableSuddenTermination()
public 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.UnsupportedOperationException
- 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 fileUnsupportedOperationException
- if the current platform
does not support the Desktop.Action.BROWSE_FILE_DIR
actionNullPointerException
- if file
is null
IllegalArgumentException
- if the specified file 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 Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2017, Oracle and/or its affiliates. 500 Oracle Parkway
Redwood Shores, CA 94065 USA. All rights reserved.
DRAFT 9-internal+0-adhoc.mlchung.jdk9-jdeps