Class Desktop
Desktop class allows interact with various desktop capabilities.
Supported operations include:
- launching the user-default browser to show a specified URI;
- launching the user-default mail client with an optional
mailtoURI; - launching a registered application to open, edit or print a specified file.
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.
- Since:
- 1.6
- See Also:
-
Nested Class Summary
Nested Classes -
Method Summary
Modifier and TypeMethodDescriptionvoidaddAppEventListener(SystemEventListener listener) Adds sub-types ofSystemEventListenerto listen for notifications from the native system.voidLaunches the default browser to display aURI.voidbrowseFileDirectory(File file) Opens a folder containing thefileand selects it in a default system file manager.voidPrevents this application from being suddenly terminated.voidLaunches the associated editor application and opens a file for editing.voidEnables this application to be suddenly terminated.static DesktopReturns theDesktopinstance of the current desktop context.static booleanTests whether this class is supported on the current platform.booleanisSupported(Desktop.Action action) Tests whether an action is supported on the current platform.voidmail()Launches the mail composing window of the user default mail client.voidLaunches the mail composing window of the user default mail client, filling the message fields specified by amailto:URI.booleanmoveToTrash(File file) Moves the specified file to the trash.voidLaunches the associated application to open the file.voidOpens the native help viewer application.voidPrints a file with the native desktop printing facility, using the associated application's print command.voidremoveAppEventListener(SystemEventListener listener) Removes sub-types ofSystemEventListenerto listen for notifications from the native system.voidrequestForeground(boolean allWindows) Requests this application to move to the foreground.voidsetAboutHandler(AboutHandler aboutHandler) Installs a handler to show a custom About window for your application.voidsetDefaultMenuBar(JMenuBar menuBar) Sets the default menu bar to use when there are no active frames.voidsetOpenFileHandler(OpenFilesHandler openFileHandler) Installs the handler which is notified when the application is asked to open a list of files.voidsetOpenURIHandler(OpenURIHandler openURIHandler) Installs the handler which is notified when the application is asked to open a URL.voidsetPreferencesHandler(PreferencesHandler preferencesHandler) Installs a handler to show a custom Preferences window for your application.voidsetPrintFileHandler(PrintFilesHandler printFileHandler) Installs the handler which is notified when the application is asked to print a list of files.voidsetQuitHandler(QuitHandler quitHandler) Installs the handler which determines if the application should quit.voidsetQuitStrategy(QuitStrategy strategy) Sets the default strategy used to quit this application.
-
Method Details
-
getDesktop
Returns theDesktopinstance of the current desktop context. On some platforms the Desktop API may not be supported; use theisDesktopSupported()method to determine if the current desktop is supported.- Returns:
- the Desktop instance
- Throws:
HeadlessException- ifGraphicsEnvironment.isHeadless()returnstrueUnsupportedOperationException- if this class is not supported on the current platform- See Also:
-
isDesktopSupported
public static boolean isDesktopSupported()Tests whether this class is supported on the current platform. If it's supported, usegetDesktop()to retrieve an instance.- Returns:
trueif this class is supported on the current platform;falseotherwise- See Also:
-
isSupported
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.OPENaction. But for a specific file, there may not be an application registered to open it. In this case,isSupported(Action)may returntrue, but the corresponding action method will throw anIOException.- Parameters:
action- the specifiedDesktop.Action- Returns:
trueif the specified action is supported on the current platform;falseotherwise- See Also:
-
open
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- the file to be opened with the associated application- Throws:
NullPointerException- iffileisnullIllegalArgumentException- if the specified file doesn't existUnsupportedOperationException- if the current platform does not support theDesktop.Action.OPENactionIOException- if the specified file has no associated application or the associated application fails to be launched
-
edit
Launches the associated editor application and opens a file for editing.- Parameters:
file- the file to be opened for editing- Throws:
NullPointerException- if the specified file isnullIllegalArgumentException- if the specified file doesn't existUnsupportedOperationException- if the current platform does not support theDesktop.Action.EDITactionIOException- if the specified file has no associated editor, or the associated application fails to be launched
-
print
Prints a file with the native desktop printing facility, using the associated application's print command.- Parameters:
file- the file to be printed- Throws:
NullPointerException- if the specified file isnullIllegalArgumentException- if the specified file doesn't existUnsupportedOperationException- if the current platform does not support theDesktop.Action.PRINTactionIOException- if the specified file has no associated application that can be used to print it
-
browse
Launches the default browser to display aURI. If the default browser is not able to handle the specifiedURI, the application registered for handlingURIsof the specified type is invoked. The application is determined from the protocol and path of theURI, as defined by theURIclass.- Parameters:
uri- the URI to be displayed in the user default browser- Throws:
NullPointerException- ifuriisnullUnsupportedOperationException- if the current platform does not support theDesktop.Action.BROWSEactionIOException- if the user default browser is not found, or it fails to be launched, or the default handler application failed to be launched- See Also:
-
mail
Launches the mail composing window of the user default mail client.- Throws:
UnsupportedOperationException- if the current platform does not support theDesktop.Action.MAILactionIOException- if the user default mail client is not found, or it fails to be launched
-
mail
Launches the mail composing window of the user default mail client, filling the message fields specified by amailto:URI.A
mailto:URI can specify message fields including "to", "cc", "subject", "body", etc. See The mailto URL scheme (RFC 2368) for themailto:URI specification details.- Parameters:
mailtoURI- the specifiedmailto:URI- Throws:
NullPointerException- if the specified URI isnullIllegalArgumentException- if the URI scheme is not"mailto"UnsupportedOperationException- if the current platform does not support theDesktop.Action.MAILactionIOException- if the user default mail client is not found or fails to be launched- External Specifications
- See Also:
-
addAppEventListener
Adds sub-types ofSystemEventListenerto listen for notifications from the native system. Has no effect if SystemEventListener's sub-type is unsupported on the current platform.- Parameters:
listener- listener- Since:
- 9
- See Also:
-
removeAppEventListener
Removes sub-types ofSystemEventListenerto listen for notifications from the native system. Has no effect if SystemEventListener's sub-type is unsupported on the current platform.- Parameters:
listener- listener- Since:
- 9
- See Also:
-
setAboutHandler
Installs a handler to show a custom About window for your application.Setting the
AboutHandlertonullreverts it to the default behavior.- Parameters:
aboutHandler- the handler to respond to theAboutHandler.handleAbout(AboutEvent)message- Throws:
UnsupportedOperationException- if the current platform does not support theDesktop.Action.APP_ABOUTaction- Since:
- 9
-
setPreferencesHandler
Installs a handler to show a custom Preferences window for your application.Setting the
PreferencesHandlertonullreverts it to the default behavior- Parameters:
preferencesHandler- the handler to respond to thePreferencesHandler.handlePreferences(PreferencesEvent)- Throws:
UnsupportedOperationException- if the current platform does not support theDesktop.Action.APP_PREFERENCESaction- Since:
- 9
-
setOpenFileHandler
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
CFBundleDocumentTypesarray present in itsInfo.plist. Check the Apple Developer Documentation for more information aboutInfo.plist. - Parameters:
openFileHandler- handler- Throws:
UnsupportedOperationException- if the current platform does not support theDesktop.Action.APP_OPEN_FILEaction- Since:
- 9
-
setPrintFileHandler
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
CFBundleDocumentTypesarray present in itsInfo.plist. Check the Apple Developer Documentation for more information aboutInfo.plist. - Parameters:
printFileHandler- handler- Throws:
UnsupportedOperationException- if the current platform does not support theDesktop.Action.APP_PRINT_FILEaction- Since:
- 9
-
setOpenURIHandler
Installs the handler which is notified when the application is asked to open a URL. Setting the handler tonullcauses allOpenURIHandler.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
CFBundleDocumentTypesarray present in itsInfo.plist. Check the Apple Developer Documentation for more information aboutInfo.plist. - Parameters:
openURIHandler- handler- Throws:
UnsupportedOperationException- if the current platform does not support theDesktop.Action.APP_OPEN_URIaction- Since:
- 9
-
setQuitHandler
Installs the handler which determines if the application should quit. The handler is passed a one-shotQuitResponsewhich can cancel or proceed with the quit. Setting the handler tonullcauses all quit requests to directly perform the defaultQuitStrategy.- Parameters:
quitHandler- the handler that is called when the application is asked to quit- Throws:
UnsupportedOperationException- if the current platform does not support theDesktop.Action.APP_QUIT_HANDLERaction- Since:
- 9
-
setQuitStrategy
Sets the default strategy used to quit this application. The default is calling SYSTEM_EXIT_0.- Parameters:
strategy- the way this application should be shutdown- Since:
- 9
- See Also:
-
enableSuddenTermination
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.- Throws:
UnsupportedOperationException- if the current platform does not support theDesktop.Action.APP_SUDDEN_TERMINATIONaction- Since:
- 9
- See Also:
-
disableSuddenTermination
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.- Throws:
UnsupportedOperationException- if the current platform does not support theDesktop.Action.APP_SUDDEN_TERMINATIONaction- Since:
- 9
- See Also:
-
requestForeground
public void requestForeground(boolean allWindows) Requests this application to move to the foreground.- Parameters:
allWindows- if all windows of this application should be moved to the foreground, or only the foremost one- Throws:
UnsupportedOperationException- if the current platform does not support theDesktop.Action.APP_REQUEST_FOREGROUNDaction- Since:
- 9
-
openHelpViewer
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
- Throws:
UnsupportedOperationException- if the current platform does not support theDesktop.Action.APP_HELP_VIEWERaction- Since:
- 9
-
setDefaultMenuBar
Sets the default menu bar to use when there are no active frames.- Parameters:
menuBar- to use when no other frames are active- Throws:
UnsupportedOperationException- if the current platform does not support theDesktop.Action.APP_MENU_BARaction- Since:
- 9
-
browseFileDirectory
Opens a folder containing thefileand selects it in a default system file manager.- Parameters:
file- the file- Throws:
UnsupportedOperationException- if the current platform does not support theDesktop.Action.BROWSE_FILE_DIRactionNullPointerException- iffileisnullIllegalArgumentException- if the specified file or its parent doesn't exist- Since:
- 9
-
moveToTrash
Moves the specified file to the trash.- Parameters:
file- the file- Returns:
- returns true if successfully moved the file to the trash.
- Throws:
UnsupportedOperationException- if the current platform does not support theDesktop.Action.MOVE_TO_TRASHactionNullPointerException- iffileisnullIllegalArgumentException- if the specified file doesn't exist- Since:
- 9
-