Supported operations include: *
An application is registered to a URI or file type; for
* example, the {@code "sxi"} file extension is typically registered
* to StarOffice. The mechanism of registering, accessing, and
@@ -70,6 +73,8 @@
* application is executed, it will be executed on the same system as
* the one on which the Java application was launched.
*
+ * @see Action
+ *
* @since 1.6
* @author Armin Chen
* @author George Zhang
@@ -106,11 +111,155 @@
* @see Desktop#mail(java.net.URI)
*/
MAIL,
+
/**
* Represents a "browse" action.
* @see Desktop#browse(java.net.URI)
*/
- BROWSE
+ BROWSE,
+
+ /**
+ * Represents an AppForegroundListener
+ * @see java.awt.desktop.AppForegroundListener
+ * @since 1.9
+ */
+ APP_EVENT_FOREGROUND,
+
+ /**
+ * Represents an AppHiddenListener
+ * @see java.awt.desktop.AppHiddenListener
+ * @since 1.9
+ */
+ APP_EVENT_HIDDEN,
+
+ /**
+ * Represents an AppReopenedListener
+ * @see java.awt.desktop.AppReopenedListener
+ * @since 1.9
+ */
+ APP_EVENT_REOPENED,
+
+ /**
+ * Represents a ScreenSleepListener
+ * @see java.awt.desktop.ScreenSleepListener
+ * @since 1.9
+ */
+ APP_EVENT_SCREEN_SLEEP,
+
+ /**
+ * Represents a SystemSleepListener
+ * @see java.awt.desktop.SystemSleepListener
+ * @since 1.9
+ */
+ APP_EVENT_SYSTEM_SLEEP,
+
+ /**
+ * Represents a UserSessionListener
+ * @see java.awt.desktop.UserSessionListener
+ * @since 1.9
+ */
+ APP_EVENT_USER_SESSION,
+
+ /**
+ * Represents an AboutHandler
+ * @see #setAboutHandler(java.awt.desktop.AboutHandler)
+ * @since 1.9
+ */
+ APP_ABOUT,
+
+ /**
+ * Represents a PreferencesHandler
+ * @see #setPreferencesHandler(java.awt.desktop.PreferencesHandler)
+ * @since 1.9
+ */
+ APP_PREFERENCES,
+
+ /**
+ * Represents an OpenFilesHandler
+ * @see #setOpenFileHandler(java.awt.desktop.OpenFilesHandler)
+ * @since 1.9
+ */
+ APP_OPEN_FILE,
+
+ /**
+ * Represents a PrintFilesHandler
+ * @see #setPrintFileHandler(java.awt.desktop.PrintFilesHandler)
+ * @since 1.9
+ */
+ APP_PRINT_FILE,
+
+ /**
+ * Represents an OpenURIHandler
+ * @see #setOpenURIHandler(java.awt.desktop.OpenURIHandler)
+ * @since 1.9
+ */
+ APP_OPEN_URI,
+
+ /**
+ * Represents a QuitHandler
+ * @see #setQuitHandler(java.awt.desktop.QuitHandler)
+ * @since 1.9
+ */
+ APP_QUIT_HANDLER,
+
+ /**
+ * Represents a QuitStrategy
+ * @see #setQuitStrategy(java.awt.desktop.QuitStrategy)
+ * @since 1.9
+ */
+ APP_QUIT_STRATEGY,
+
+ /**
+ * Represents a SuddenTermination
+ * @see #enableSuddenTermination()
+ * @since 1.9
+ */
+ APP_SUDDEN_TERMINATION,
+
+ /**
+ * Represents a requestForeground
+ * @see #requestForeground(boolean)
+ * @since 1.9
+ */
+ APP_REQUEST_FOREGROUND,
+
+ /**
+ * Represents a HelpViewer
+ * @see #openHelpViewer()
+ * @since 1.9
+ */
+ APP_HELP_VIEWER,
+
+ /**
+ * Represents a menu bar
+ * @see #setDefaultMenuBar(javax.swing.JMenuBar)
+ * @since 1.9
+ */
+ APP_MENU_BAR,
+
+ /**
+ * Represents a platform-specific full screen
+ * @see #addWindowFullScreenListener(java.awt.Window, java.awt.desktop.FullScreenListener)
+ * @see #removeWindowFullScreenListener(java.awt.Window, java.awt.desktop.FullScreenListener)
+ * @see #setWindowCanFullScreen(java.awt.Window, boolean)
+ * @see #requestToggleFullScreen(java.awt.Window)
+ * @since 1.9
+ */
+ FULLSCREEN,
+
+ /**
+ * Represents a browse file directory
+ * @see #browseFileDirectory(java.io.File)
+ * @since 1.9
+ */
+ BROWSE_FILE_DIR,
+
+ /**
+ * Represents a move to trash
+ * @see #moveToTrash(java.io.File)
+ * @since 1.9
+ */
+ MOVE_TO_TRASH
};
private DesktopPeer peer;
@@ -128,10 +277,10 @@
/**
* Returns the
+ * Setting the {@link AboutHandler} to
+ * Setting the {@link PreferencesHandler} to Desktop instance of the current
- * browser context. On some platforms the Desktop API may not be
+ * desktop context. On some platforms the Desktop API may not be
* supported; use the {@link #isDesktopSupported} method to
* determine if the current desktop is supported.
- * @return the Desktop instance of the current browser context
+ * @return the Desktop instance
* @throws HeadlessException if {@link
* GraphicsEnvironment#isHeadless()} returns {@code true}
* @throws UnsupportedOperationException if this class is not
@@ -208,7 +357,7 @@
if (!file.exists()) {
throw new IllegalArgumentException("The file: "
- + file.getPath() + " doesn't exist.");
+ + file.getPath() + " doesn't exist.");
}
file.canRead();
@@ -224,7 +373,7 @@
private void checkActionSupport(Action actionType){
if (!isSupported(actionType)) {
throw new UnsupportedOperationException("The " + actionType.name()
- + " action is not supported on the current platform!");
+ + " action is not supported on the current platform!");
}
}
@@ -238,7 +387,20 @@
SecurityManager sm = System.getSecurityManager();
if (sm != null) {
sm.checkPermission(new AWTPermission(
- "showWindowWithoutWarningBanner"));
+ "showWindowWithoutWarningBanner"));
+ }
+ }
+
+ /**
+ * Calls to the security manager's checkPermission method with
+ * an AWTPermission("fullScreenExclusive")
+ * permission.
+ */
+ private void checkFullscreenPermission(){
+ SecurityManager sm = System.getSecurityManager();
+ if (sm != null) {
+ sm.checkPermission(new AWTPermission(
+ "fullScreenExclusive"));
}
}
@@ -479,7 +641,434 @@
SecurityManager sm = System.getSecurityManager();
if (sm != null) {
sm.checkPermission(new FilePermission("<null reverts it to the
+ * default behavior.
+ *
+ * @param aboutHandler the handler to respond to the
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Desktop.Action#APP_ABOUT} action
+ * {@link AboutHandler#handleAbout} )} message
+ * @since 1.9
+ */
+ public void setAboutHandler(final AboutHandler aboutHandler) {
+ checkActionSupport(Action.APP_ABOUT);
+ peer.setAboutHandler(aboutHandler);
+ }
+
+ /**
+ * Installs a handler to show a custom Preferences window for your
+ * application.
+ * null reverts it to
+ * the default behavior
+ *
+ * @param preferencesHandler the handler to respond to the
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Desktop.Action#APP_PREFERENCES} action
+ * {@link PreferencesHandler#handlePreferences(PreferencesEvent)}
+ * @since 1.9
+ */
+ public void setPreferencesHandler(final PreferencesHandler preferencesHandler) {
+ checkActionSupport(Action.APP_PREFERENCES);
+ peer.setPreferencesHandler(preferencesHandler);
+ }
+
+ /**
+ * Installs the handler which is notified when the application is asked to
+ * open a list of files.
+ *
+ * @implNote Please note that for Mac OS, notifications
+ * are only sent if the Java app is a bundled application,
+ * with a {@code CFBundleDocumentTypes} array present in its
+ * Info.plist. See the
+ *
+ * Info.plist Key Reference for more information about adding a
+ * {@code CFBundleDocumentTypes} key to your app's Info.plist.
+ *
+ * @param openFileHandler handler
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Desktop.Action#APP_OPEN_FILE} action
+ * @since 1.9
+ */
+ public void setOpenFileHandler(final OpenFilesHandler openFileHandler) {
+ checkActionSupport(Action.APP_OPEN_FILE);
+ peer.setOpenFileHandler(openFileHandler);
+ }
+
+ /**
+ * Installs the handler which is notified when the application is asked to
+ * print a list of files.
+ *
+ * @implNote Please note that for Mac OS, notifications
+ * are only sent if the Java app is a bundled application,
+ * with a {@code CFBundleDocumentTypes} array present in its
+ * Info.plist. See the
+ *
+ * Info.plist Key Reference for more information about adding a
+ * {@code CFBundleDocumentTypes} key to your app's Info.plist.
+ *
+ * @param printFileHandler handler
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Desktop.Action#APP_PRINT_FILE} action
+ * @since 1.9
+ */
+ public void setPrintFileHandler(final PrintFilesHandler printFileHandler) {
+ checkActionSupport(Action.APP_PRINT_FILE);
+ peer.setPrintFileHandler(printFileHandler);
+ }
+
+ /**
+ * Installs the handler which is notified when the application is asked to
+ * open a URL.
+ *
+ * Setting the handler to null causes all
+ * {@link OpenURIHandler#openURI(AppEvent.OpenURIEvent)} requests to be
+ * enqueued until another handler is set.
+ *
+ * @implNote Please note that for Mac OS, notifications
+ * are only sent if the Java app is a bundled application,
+ * with a {@code CFBundleDocumentTypes} array present in its
+ * Info.plist. See the
+ *
+ * Info.plist Key Reference for more information about adding a
+ * {@code CFBundleDocumentTypes} key to your app's Info.plist.
+ *
+ * @param openURIHandler handler
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Desktop.Action#APP_OPEN_URI} action
+ * @since 1.9
+ */
+ public void setOpenURIHandler(final OpenURIHandler openURIHandler) {
+ checkActionSupport(Action.APP_OPEN_URI);
+ peer.setOpenURIHandler(openURIHandler);
+ }
+
+ /**
+ * Installs the handler which determines if the application should quit. The
+ * handler is passed a one-shot {@link QuitResponse} which can cancel or
+ * proceed with the quit. Setting the handler to null causes
+ * all quit requests to directly perform the default {@link QuitStrategy}.
+ *
+ * @param quitHandler the handler that is called when the application is
+ * asked to quit
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Desktop.Action#APP_QUIT_HANDLER} action
+ * @since 1.9
+ */
+ public void setQuitHandler(final QuitHandler quitHandler) {
+ checkActionSupport(Action.APP_QUIT_HANDLER);
+ peer.setQuitHandler(quitHandler);
+ }
+
+ /**
+ * Sets the default strategy used to quit this application. The default is
+ * calling SYSTEM_EXIT_0.
+ *
+ * @param strategy the way this application should be shutdown
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Desktop.Action#APP_QUIT_STRATEGY} action
+ * @see QuitStrategy
+ * @since 1.9
+ */
+ public void setQuitStrategy(final QuitStrategy strategy) {
+ checkActionSupport(Action.APP_QUIT_STRATEGY);
+ peer.setQuitStrategy(strategy);
+ }
+
+ /**
+ * 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 the {@link Desktop.Action#APP_SUDDEN_TERMINATION} action
+ * @see #disableSuddenTermination()
+ * @since 1.9
+ */
+ public void enableSuddenTermination() {
+ checkActionSupport(Action.APP_SUDDEN_TERMINATION);
+ peer.enableSuddenTermination();
+ }
+
+ /**
+ * 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 the {@link Desktop.Action#APP_SUDDEN_TERMINATION} action
+ * @see #enableSuddenTermination()
+ * @since 1.9
+ */
+ public void disableSuddenTermination() {
+ checkActionSupport(Action.APP_SUDDEN_TERMINATION);
+ peer.disableSuddenTermination();
+ }
+
+ /**
+ * Requests this application to move to the foreground.
+ *
+ * @param 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
+ * AWTPermission("showWindowWithoutWarningBanner") permission.
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Desktop.Action#APP_REQUEST_FOREGROUND} action
+ * @since 1.9
+ */
+ public void requestForeground(final boolean allWindows) {
+ checkAWTPermission();
+ checkActionSupport(Action.APP_REQUEST_FOREGROUND);
+ peer.requestForeground(allWindows);
+ }
+
+ /**
+ * Opens the native help viewer application.
+ *
+ * @throws SecurityException if a security manager exists and it denies the
+ * AWTPermission("showWindowWithoutWarningBanner") permission.
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Desktop.Action#APP_HELP_VIEWER} action
+ * @since 1.9
+ */
+ public void openHelpViewer() {
+ checkAWTPermission();
+ checkActionSupport(Action.APP_HELP_VIEWER);
+ peer.openHelpViewer();
+ }
+
+ /**
+ * Sets the default menu bar to use when there are no active frames.
+ *
+ * @implNote Aqua Look and Feel should be active to support this on Mac OS.
+ *
+ * @param menuBar to use when no other frames are active
+ * @throws SecurityException if a security manager exists and it denies the
+ * AWTPermission("showWindowWithoutWarningBanner") permission.
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Desktop.Action#APP_MENU_BAR} action
+ * @since 1.9
+ */
+ public void setDefaultMenuBar(final JMenuBar menuBar) {
+ checkAWTPermission();
+ checkActionSupport(Action.APP_MENU_BAR);
+ peer.setDefaultMenuBar(menuBar);
+ }
+
+ /**
+ * Attaches a {@link FullScreenListener} to the specified top-level
+ * {@link Window}.
+ *
+ * @param window to attach the {@link FullScreenListener} to
+ * @param listener to be notified when a full screen event occurs
+ * @throws SecurityException if a security manager exists and it denies the
+ * AWTPermission("showWindowWithoutWarningBanner")
+ * and AWTPermission("fullScreenExclusive")
+ * permission.
+ * @throws IllegalArgumentException if window is not a
+ * {@link javax.swing.JFrame} or a {@link javax.swing.JDialog}
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Desktop.Action#FULLSCREEN} action
+ * @since 1.9
+ */
+ public void addWindowFullScreenListener(final Window window,
+ final FullScreenListener listener) {
+ checkAWTPermission();
+ checkFullscreenPermission();
+ checkActionSupport(Action.FULLSCREEN);
+ peer.addWindowFullScreenListener(window, listener);
+ }
+
+ /**
+ * Removes a {@link FullScreenListener} from the specified top-level
+ * {@link Window}.
+ *
+ * @param window to remove the {@link FullScreenListener} from
+ * @param listener to be removed
+ * @throws SecurityException if a security manager exists and it denies the
+ * AWTPermission("showWindowWithoutWarningBanner")
+ * and AWTPermission("fullScreenExclusive")
+ * permission.
+ * @throws IllegalArgumentException if window is not a
+ * {@link javax.swing.JFrame} or a {@link javax.swing.JDialog}
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Desktop.Action#FULLSCREEN} action
+ * @since 1.9
+ */
+ public void removeWindowFullScreenListener(final Window window,
+ final FullScreenListener listener) {
+ checkAWTPermission();
+ checkFullscreenPermission();
+ checkActionSupport(Action.FULLSCREEN);
+ peer.removeWindowFullScreenListener(window, listener);
+ }
+
+ /**
+ * Marks a {@link Window} as able to animate into or out of full screen
+ * mode.
+ *
+ * Only top-level {@link Window}s which are a
+ * {@link javax.swing.JFrame} or a {@link javax.swing.JDialog}
+ * are able to be animated into and out of full screen mode. The {@link Window}
+ * must be marked as full screen-able before the native peer is created with
+ * {@link Component#addNotify()}.
+ *
+ * @param window window
+ * @param canFullScreen flag
+ * @throws SecurityException if a security manager exists and it denies the
+ * AWTPermission("showWindowWithoutWarningBanner")
+ * and AWTPermission("fullScreenExclusive")
+ * permission.
+ * @throws IllegalArgumentException if window is not a
+ * {@link javax.swing.JFrame} or a {@link javax.swing.JDialog}
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Desktop.Action#FULLSCREEN} action
+ * @since 1.9
+ */
+ public void setWindowCanFullScreen(final Window window,
+ final boolean canFullScreen) {
+ checkAWTPermission();
+ checkFullscreenPermission();
+ checkActionSupport(Action.FULLSCREEN);
+ peer.setWindowCanFullScreen(window, canFullScreen);
+ }
+
+ /**
+ * Requests that a {@link Window} should get into or out of full screen
+ * mode. Only {@link Window}s marked as full screenable by
+ * {@link #setWindowCanFullScreen(Window, boolean)} can be toggled.
+ *
+ * @param window to animate into or out of full screen mode
+ * @throws SecurityException if a security manager exists and it denies the
+ * AWTPermission("showWindowWithoutWarningBanner")
+ * and AWTPermission("fullScreenExclusive")
+ * permission.
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Desktop.Action#FULLSCREEN} action
+ * @since 1.9
+ */
+ public void requestToggleFullScreen(final Window window) {
+ checkAWTPermission();
+ checkFullscreenPermission();
+ checkActionSupport(Action.FULLSCREEN);
+ peer.requestToggleFullScreen(window);
+ }
+
+
+ /**
+ * Opens a folder containing the {@code file} and selects it
+ * in a default system file manager.
+ * @param file the file
+ * @throws SecurityException If a security manager exists and its
+ * {@link SecurityManager#checkRead(java.lang.String)} method
+ * denies read access to the file
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Desktop.Action#BROWSE_FILE_DIR} action
+ * @throws NullPointerException if {@code file} is {@code null}
+ * @throws IllegalArgumentException if the specified file doesn't
+ * exist
+ * @since 1.9
+ */
+ public void browseFileDirectory(File file) {
+ checkRead();
+ checkActionSupport(Action.BROWSE_FILE_DIR);
+ checkFileValidation(file);
+ peer.browseFileDirectory(file);
+ }
+
+ /**
+ * Moves the specified file to the trash.
+ *
+ * @param file the file
+ * @return returns true if successfully moved the file to the trash.
+ * @throws SecurityException If a security manager exists and its
+ * {@link SecurityManager#checkWrite(java.lang.String)} method
+ * denies write access to the file
+ * @throws UnsupportedOperationException if the current platform
+ * does not support the {@link Desktop.Action#MOVE_TO_TRASH} action
+ * @throws NullPointerException if {@code file} is {@code null}
+ * @throws IllegalArgumentException if the specified file doesn't
+ * exist
+ *
+ * @since 1.9
+ */
+ public boolean moveToTrash(final File file) {
+ checkWrite();
+ checkActionSupport(Action.MOVE_TO_TRASH);
+ checkFileValidation(file);
+ return peer.moveToTrash(file);
+ }
}