Class Desktop

Methods

getDesktop

public static 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:

the Desktop instance

Throws:

HeadlessException - if GraphicsEnvironment.isHeadless() returns true

UnsupportedOperationException - if this class is not supported on the current platform

See Also:

isDesktopSupported(), GraphicsEnvironment.isHeadless()

isDesktopSupported

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:

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

See Also:

getDesktop()

isSupported

public boolean isSupported(Desktop.Action action)

Parameters:

action - the specified Desktop.Action

Returns:

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

See Also:

Desktop.Action

open

public void open(File file)
          throws IOException

Parameters:

file - the file to be opened with the associated application

Throws:

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

IOException - if the specified file has no associated application or the associated application fails to be launched

SecurityException - 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 subprocess

See Also:

AWTPermission

edit

public void edit(File file)
          throws IOException

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 is null

IllegalArgumentException - if the specified file doesn't exist

UnsupportedOperationException - if the current platform does not support the Desktop.Action.EDIT action

IOException - if the specified file has no associated editor, or the associated application fails to be launched

SecurityException - 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 subprocess

See Also:

AWTPermission

print

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 - the file to be printed

Throws:

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

IOException - if the specified file has no associated application that can be used to print it

SecurityException - 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 subprocess

browse

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 - the URI to be displayed in the user default browser

Throws:

NullPointerException - if uri is null

UnsupportedOperationException - if the current platform does not support the Desktop.Action.BROWSE action

IOException - if the user default browser is not found, or it fails to be launched, or the default handler application failed to be launched

SecurityException - if a security manager exists and it denies the AWTPermission("showWindowWithoutWarningBanner") permission, or the calling thread is not allowed to create a subprocess

See Also:

URI, AWTPermission

mail

public void mail()
          throws IOException

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

Throws:

UnsupportedOperationException - if the current platform does not support the Desktop.Action.MAIL action

IOException - if the user default mail client is not found, or it fails to be launched

SecurityException - if a security manager exists and it denies the AWTPermission("showWindowWithoutWarningBanner") permission, or the calling thread is not allowed to create a subprocess

See Also:

AWTPermission

mail

public void mail(URI mailtoURI)
          throws IOException

Parameters:

mailtoURI - the specified mailto: URI

Throws:

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

IOException - if the user default mail client is not found or fails to be launched

SecurityException - if a security manager exists and it denies the AWTPermission("showWindowWithoutWarningBanner") permission, or the calling thread is not allowed to create a subprocess

See Also:

URI, AWTPermission

addAppEventListener

public void addAppEventListener(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 - listener

Throws:

SecurityException - if a security manager exists and it denies the RuntimePermission("canProcessApplicationEvents") permission

Since:

9

See Also:

AppForegroundListener, AppHiddenListener, AppReopenedListener, ScreenSleepListener, SystemSleepListener, UserSessionListener

removeAppEventListener

public void removeAppEventListener(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 - listener

Throws:

SecurityException - if a security manager exists and it denies the RuntimePermission("canProcessApplicationEvents") permission

Since:

9

See Also:

AppForegroundListener, AppHiddenListener, AppReopenedListener, ScreenSleepListener, SystemSleepListener, UserSessionListener

setAboutHandler

public void setAboutHandler(AboutHandler aboutHandler)

Parameters:

aboutHandler - the handler to respond to the AboutHandler.handleAbout(AboutEvent) message

Throws:

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_ABOUT action

Since:

9

setPreferencesHandler

public void setPreferencesHandler(PreferencesHandler preferencesHandler)

Parameters:

preferencesHandler - the handler to respond to the PreferencesHandler.handlePreferences(PreferencesEvent)

Throws:

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_PREFERENCES action

Since:

9

setOpenFileHandler

public void setOpenFileHandler(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 - handler

Throws:

SecurityException - 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 subprocess

UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_OPEN_FILE action

Since:

9

setPrintFileHandler

public void setPrintFileHandler(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 - handler

Throws:

SecurityException - if a security manager exists and its SecurityManager.checkPrintJobAccess() method denies the permission to print or it denies the RuntimePermission("canProcessApplicationEvents") permission

UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_PRINT_FILE action

Since:

9

setOpenURIHandler

public void setOpenURIHandler(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 CFBundleDocumentTypes array present in its Info.plist. Check the Apple Developer Documentation for more information about Info.plist.

Parameters:

openURIHandler - handler RuntimePermission("canProcessApplicationEvents") permission, or the calling thread is not allowed to create a subprocess

Throws:

UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_OPEN_URI action

Since:

9

setQuitHandler

public void setQuitHandler(QuitHandler quitHandler)

Installs the handler which determines if the application should quit. The handler is passed a one-shot 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 - the handler that is called when the application is asked to quit

Throws:

SecurityException - if a security manager exists and it will not allow the caller to invoke System.exit or it denies the RuntimePermission("canProcessApplicationEvents") permission

UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_QUIT_HANDLER action

Since:

9

setQuitStrategy

public void setQuitStrategy(QuitStrategy strategy)

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

Throws:

SecurityException - if a security manager exists and it will not allow the caller to invoke System.exit or it denies the RuntimePermission("canProcessApplicationEvents") permission

UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_QUIT_STRATEGY action

Since:

9

See Also:

QuitStrategy

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:

SecurityException - if a security manager exists and it will not allow the caller to invoke System.exit or it denies the RuntimePermission("canProcessApplicationEvents") permission

UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_SUDDEN_TERMINATION action

Since:

9

See Also:

disableSuddenTermination()

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:

SecurityException - if a security manager exists and it will not allow the caller to invoke System.exit or it denies the RuntimePermission("canProcessApplicationEvents") permission

UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_SUDDEN_TERMINATION action

Since:

9

See Also:

enableSuddenTermination()

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:

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_REQUEST_FOREGROUND action

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:

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 subprocess

UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_HELP_VIEWER action

Since:

9

setDefaultMenuBar

public void setDefaultMenuBar(JMenuBar menuBar)

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

Parameters:

menuBar - to use when no other frames are active

Throws:

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_MENU_BAR action

Since:

9

browseFileDirectory

public void browseFileDirectory(File file)

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

Parameters:

file - the file

Throws:

SecurityException - 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 subprocess

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

moveToTrash

public boolean moveToTrash(File file)

Moves the specified file to the trash.

Parameters:

file - the file

Returns:

returns true if successfully moved the file to the trash.

Throws:

SecurityException - If a security manager exists and its SecurityManager.checkDelete(java.lang.String) method denies deletion of the file

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