< prev index next >

src/java.desktop/share/classes/java/awt/Desktop.java

Print this page

        

*** 23,48 **** * questions. */ package java.awt; import java.awt.peer.DesktopPeer; import java.io.File; import java.io.FilePermission; import java.io.IOException; import java.net.MalformedURLException; import java.net.URI; import java.net.URISyntaxException; import java.net.URL; import sun.awt.SunToolkit; import sun.security.util.SecurityConstants; /** ! * The {@code Desktop} class allows a Java application to launch ! * associated applications registered on the native desktop to handle ! * a {@link java.net.URI} or a file. * * <p> Supported operations include: * <ul> * <li>launching the user-default browser to show a specified * URI;</li> --- 23,48 ---- * questions. */ package java.awt; + import java.awt.desktop.*; import java.awt.peer.DesktopPeer; import java.io.File; import java.io.FilePermission; import java.io.IOException; import java.net.MalformedURLException; import java.net.URI; import java.net.URISyntaxException; import java.net.URL; import sun.awt.SunToolkit; + import javax.swing.JMenuBar; import sun.security.util.SecurityConstants; /** ! * The {@code Desktop} class allows interact with various desktop capabilities. * * <p> Supported operations include: * <ul> * <li>launching the user-default browser to show a specified * URI;</li>
*** 56,65 **** --- 56,68 ---- * 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 {@link Desktop.Action} for the full list of supported operations + * and capabilities. + * * <p> 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 * launching the associated application is platform-dependent. *
*** 68,77 **** --- 71,82 ---- * * <p> 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. * + * @see Action + * * @since 1.6 * @author Armin Chen * @author George Zhang */ public class Desktop {
*** 104,118 **** * Represents a "mail" action. * @see Desktop#mail() * @see Desktop#mail(java.net.URI) */ MAIL, /** * Represents a "browse" action. * @see Desktop#browse(java.net.URI) */ ! BROWSE }; private DesktopPeer peer; /** --- 109,267 ---- * Represents a "mail" action. * @see Desktop#mail() * @see Desktop#mail(java.net.URI) */ MAIL, + /** * Represents a "browse" action. * @see Desktop#browse(java.net.URI) */ ! 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; /**
*** 126,139 **** } } /** * Returns the <code>Desktop</code> instance of the current ! * browser 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 * @throws HeadlessException if {@link * GraphicsEnvironment#isHeadless()} returns {@code true} * @throws UnsupportedOperationException if this class is not * supported on the current platform * @see #isDesktopSupported() --- 275,288 ---- } } /** * Returns the <code>Desktop</code> instance of the current ! * 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 * @throws HeadlessException if {@link * GraphicsEnvironment#isHeadless()} returns {@code true} * @throws UnsupportedOperationException if this class is not * supported on the current platform * @see #isDesktopSupported()
*** 241,250 **** --- 390,412 ---- "showWindowWithoutWarningBanner")); } } /** + * Calls to the security manager's <code>checkPermission</code> method with + * an <code>AWTPermission("fullScreenExclusive")</code> + * permission. + */ + private void checkFullscreenPermission(){ + SecurityManager sm = System.getSecurityManager(); + if (sm != null) { + sm.checkPermission(new AWTPermission( + "fullScreenExclusive")); + } + } + + /** * Launches the associated application to open the file. * * <p> If the specified file is a directory, the file manager of * the current platform is launched to open it. *
*** 480,485 **** --- 642,1074 ---- if (sm != null) { sm.checkPermission(new FilePermission("<<ALL FILES>>", SecurityConstants.FILE_EXECUTE_ACTION)); } } + + private void checkRead() throws SecurityException { + SecurityManager sm = System.getSecurityManager(); + if (sm != null) { + sm.checkPermission(new FilePermission("<<ALL FILES>>", + SecurityConstants.FILE_READ_ACTION)); + } + } + + private void checkWrite() throws SecurityException { + SecurityManager sm = System.getSecurityManager(); + if (sm != null) { + sm.checkPermission(new FilePermission("<<ALL FILES>>", + SecurityConstants.FILE_WRITE_ACTION)); + } + } + + /** + * Adds sub-types of {@link SystemEventListener} to listen for notifications + * from the native system. + * + * Has no effect if SystemEventListener's sub-type is unsupported on the current + * platform. + * + * @param listener listener + * @see AppForegroundListener + * @see AppHiddenListener + * @see AppReopenedListener + * @see ScreenSleepListener + * @see SystemSleepListener + * @see UserSessionListener + * @since 1.9 + */ + public void addAppEventListener(final SystemEventListener listener) { + peer.addAppEventListener(listener); + } + + /** + * Removes sub-types of {@link SystemEventListener} to listen for notifications + * from the native system. + * + * Has no effect if SystemEventListener's sub-type is unsupported on the current + * platform. + * + * @param listener listener + * @see AppForegroundListener + * @see AppHiddenListener + * @see AppReopenedListener + * @see ScreenSleepListener + * @see SystemSleepListener + * @see UserSessionListener + * @since 1.9 + */ + public void removeAppEventListener(final SystemEventListener listener) { + peer.removeAppEventListener(listener); + } + + /** + * Installs a handler to show a custom About window for your application. + * <p> + * Setting the {@link AboutHandler} to <code>null</code> 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. + * <p> + * Setting the {@link PreferencesHandler} to <code>null</code> 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 + * <a href="http://developer.apple.com/mac/library/documentation/General/Reference/InfoPlistKeyReference"> + * Info.plist Key Reference</a> 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 + * <a href="http://developer.apple.com/mac/library/documentation/General/Reference/InfoPlistKeyReference"> + * Info.plist Key Reference</a> 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 <code>null</code> 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 + * <a href="http://developer.apple.com/mac/library/documentation/General/Reference/InfoPlistKeyReference"> + * Info.plist Key Reference</a> 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 <code>null</code> 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. + * + * <b>Note: enabling sudden termination will allow your application to be + * quit without notifying your QuitHandler, or running any shutdown + * hooks.</b> + * 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 + * <code>AWTPermission("showWindowWithoutWarningBanner")</code> 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 + * <code>AWTPermission("showWindowWithoutWarningBanner")</code> 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 + * <code>AWTPermission("showWindowWithoutWarningBanner")</code> 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 + * <code>AWTPermission("showWindowWithoutWarningBanner")</code> + * and <code>AWTPermission("fullScreenExclusive")</code> + * 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 + * <code>AWTPermission("showWindowWithoutWarningBanner")</code> + * and <code>AWTPermission("fullScreenExclusive")</code> + * 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 + * <code>AWTPermission("showWindowWithoutWarningBanner")</code> + * and <code>AWTPermission("fullScreenExclusive")</code> + * 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 + * <code>AWTPermission("showWindowWithoutWarningBanner")</code> + * and <code>AWTPermission("fullScreenExclusive")</code> + * 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); + } }
< prev index next >