254 * Represents a move to trash
255 * @see #moveToTrash(java.io.File)
256 * @since 9
257 */
258 MOVE_TO_TRASH
259 };
260
261 private DesktopPeer peer;
262
263 /**
264 * Suppresses default constructor for noninstantiability.
265 */
266 private Desktop() {
267 Toolkit defaultToolkit = Toolkit.getDefaultToolkit();
268 // same cast as in isDesktopSupported()
269 if (defaultToolkit instanceof SunToolkit) {
270 peer = ((SunToolkit) defaultToolkit).createDesktopPeer(this);
271 }
272 }
273
274 /**
275 * Returns the {@code Desktop} instance of the current
276 * desktop context. On some platforms the Desktop API may not be
277 * supported; use the {@link #isDesktopSupported} method to
278 * determine if the current desktop is supported.
279 * @return the Desktop instance
280 * @throws HeadlessException if {@link
281 * GraphicsEnvironment#isHeadless()} returns {@code true}
282 * @throws UnsupportedOperationException if this class is not
283 * supported on the current platform
284 * @see #isDesktopSupported()
285 * @see java.awt.GraphicsEnvironment#isHeadless
286 */
287 public static synchronized Desktop getDesktop(){
288 if (GraphicsEnvironment.isHeadless()) throw new HeadlessException();
289 if (!Desktop.isDesktopSupported()) {
290 throw new UnsupportedOperationException("Desktop API is not " +
291 "supported on the current platform");
292 }
293
645 }
646
647 private void checkQuitPermission() {
648 SecurityManager sm = System.getSecurityManager();
649 if (sm != null) {
650 sm.checkExit(0);
651 }
652 }
653
654 /**
655 * Adds sub-types of {@link SystemEventListener} to listen for notifications
656 * from the native system.
657 *
658 * Has no effect if SystemEventListener's sub-type is unsupported on the current
659 * platform.
660 *
661 * @param listener listener
662 *
663 * @throws SecurityException if a security manager exists and it
664 * denies the
665 * {@code AWTPermission("showWindowWithoutWarningBanner")}
666 * permission
667 *
668 * @see java.awt.desktop.AppForegroundListener
669 * @see java.awt.desktop.AppHiddenListener
670 * @see java.awt.desktop.AppReopenedListener
671 * @see java.awt.desktop.ScreenSleepListener
672 * @see java.awt.desktop.SystemSleepListener
673 * @see java.awt.desktop.UserSessionListener
674 * @since 9
675 */
676 public void addAppEventListener(final SystemEventListener listener) {
677 checkAWTPermission();
678 peer.addAppEventListener(listener);
679 }
680
681 /**
682 * Removes sub-types of {@link SystemEventListener} to listen for notifications
683 * from the native system.
684 *
685 * Has no effect if SystemEventListener's sub-type is unsupported on the current
686 * platform.
687 *
688 * @param listener listener
689 *
690 * @throws SecurityException if a security manager exists and it
691 * denies the
692 * {@code AWTPermission("showWindowWithoutWarningBanner")}
693 * permission
694 *
695 * @see java.awt.desktop.AppForegroundListener
696 * @see java.awt.desktop.AppHiddenListener
697 * @see java.awt.desktop.AppReopenedListener
698 * @see java.awt.desktop.ScreenSleepListener
699 * @see java.awt.desktop.SystemSleepListener
700 * @see java.awt.desktop.UserSessionListener
701 * @since 9
702 */
703 public void removeAppEventListener(final SystemEventListener listener) {
704 checkAWTPermission();
705 peer.removeAppEventListener(listener);
706 }
707
708 /**
709 * Installs a handler to show a custom About window for your application.
710 * <p>
711 * Setting the {@link java.awt.desktop.AboutHandler} to {@code null} reverts it to the
712 * default behavior.
713 *
714 * @param aboutHandler the handler to respond to the
715 * {@link java.awt.desktop.AboutHandler#handleAbout} )} message
716 *
717 * @throws SecurityException if a security manager exists and it
718 * denies the
719 * {@code AWTPermission("showWindowWithoutWarningBanner")}
720 * permission
721 * @throws UnsupportedOperationException if the current platform
722 * does not support the {@link Desktop.Action#APP_ABOUT} action
723 *
724 * @since 9
725 */
726 public void setAboutHandler(final AboutHandler aboutHandler) {
727 checkAWTPermission();
728 checkActionSupport(Action.APP_ABOUT);
729 peer.setAboutHandler(aboutHandler);
730 }
731
732 /**
733 * Installs a handler to show a custom Preferences window for your
734 * application.
735 * <p>
736 * Setting the {@link PreferencesHandler} to {@code null} reverts it to
737 * the default behavior
738 *
739 * @param preferencesHandler the handler to respond to the
740 * {@link PreferencesHandler#handlePreferences(PreferencesEvent)}
741 *
742 * @throws SecurityException if a security manager exists and it
743 * denies the
744 * {@code AWTPermission("showWindowWithoutWarningBanner")}
745 * permission
746 * @throws UnsupportedOperationException if the current platform
747 * does not support the {@link Desktop.Action#APP_PREFERENCES} action
748 * @since 9
749 */
750 public void setPreferencesHandler(final PreferencesHandler preferencesHandler) {
751 checkAWTPermission();
752 checkActionSupport(Action.APP_PREFERENCES);
753 peer.setPreferencesHandler(preferencesHandler);
754 }
755
756 /**
757 * Installs the handler which is notified when the application is asked to
758 * open a list of files.
759 *
760 * @implNote Please note that for Mac OS, notifications
761 * are only sent if the Java app is a bundled application,
762 * with a {@code CFBundleDocumentTypes} array present in its
763 * Info.plist. See the
764 * <a href="http://developer.apple.com/mac/library/documentation/General/Reference/InfoPlistKeyReference">
765 * Info.plist Key Reference</a> for more information about adding a
766 * {@code CFBundleDocumentTypes} key to your app's Info.plist.
767 *
768 * @param openFileHandler handler
769 *
770 * @throws SecurityException if a security manager exists and its
771 * {@link java.lang.SecurityManager#checkRead(java.lang.String)}
772 * method denies read access to the files, or it denies the
773 * {@code AWTPermission("showWindowWithoutWarningBanner")}
774 * permission, or the calling thread is not allowed to create a
775 * subprocess
776 * @throws UnsupportedOperationException if the current platform
777 * does not support the {@link Desktop.Action#APP_OPEN_FILE} action
778 * @since 9
779 */
780 public void setOpenFileHandler(final OpenFilesHandler openFileHandler) {
781 checkAWTPermission();
782 checkExec();
783 checkRead();
784 checkActionSupport(Action.APP_OPEN_FILE);
785 peer.setOpenFileHandler(openFileHandler);
786 }
787
788 /**
789 * Installs the handler which is notified when the application is asked to
790 * print a list of files.
791 *
792 * @implNote Please note that for Mac OS, notifications
793 * are only sent if the Java app is a bundled application,
794 * with a {@code CFBundleDocumentTypes} array present in its
795 * Info.plist. See the
796 * <a href="http://developer.apple.com/mac/library/documentation/General/Reference/InfoPlistKeyReference">
797 * Info.plist Key Reference</a> for more information about adding a
798 * {@code CFBundleDocumentTypes} key to your app's Info.plist.
799 *
800 * @param printFileHandler handler
801 * @throws SecurityException if a security manager exists and its
802 * {@link java.lang.SecurityManager#checkPrintJobAccess()} method denies
803 * the permission to print.
804 * @throws UnsupportedOperationException if the current platform
805 * does not support the {@link Desktop.Action#APP_PRINT_FILE} action
806 * @since 9
807 */
808 public void setPrintFileHandler(final PrintFilesHandler printFileHandler) {
809 SecurityManager sm = System.getSecurityManager();
810 if (sm != null) {
811 sm.checkPrintJobAccess();
812 }
813 checkActionSupport(Action.APP_PRINT_FILE);
814 peer.setPrintFileHandler(printFileHandler);
815 }
816
817 /**
818 * Installs the handler which is notified when the application is asked to
819 * open a URL.
820 *
821 * Setting the handler to {@code null} causes all
822 * {@link OpenURIHandler#openURI(AppEvent.OpenURIEvent)} requests to be
823 * enqueued until another handler is set.
824 *
825 * @implNote Please note that for Mac OS, notifications
826 * are only sent if the Java app is a bundled application,
827 * with a {@code CFBundleDocumentTypes} array present in its
828 * Info.plist. See the
829 * <a href="http://developer.apple.com/mac/library/documentation/General/Reference/InfoPlistKeyReference">
830 * Info.plist Key Reference</a> for more information about adding a
831 * {@code CFBundleDocumentTypes} key to your app's Info.plist.
832 *
833 * @param openURIHandler handler
834 *
835 * {@code AWTPermission("showWindowWithoutWarningBanner")}
836 * permission, or the calling thread is not allowed to create a
837 * subprocess
838 * @throws UnsupportedOperationException if the current platform
839 * does not support the {@link Desktop.Action#APP_OPEN_URI} action
840 * @since 9
841 */
842 public void setOpenURIHandler(final OpenURIHandler openURIHandler) {
843 checkAWTPermission();
844 checkExec();
845 checkActionSupport(Action.APP_OPEN_URI);
846 peer.setOpenURIHandler(openURIHandler);
847 }
848
849 /**
850 * Installs the handler which determines if the application should quit. The
851 * handler is passed a one-shot {@link java.awt.desktop.QuitResponse} which can cancel or
852 * proceed with the quit. Setting the handler to {@code null} causes
853 * all quit requests to directly perform the default {@link QuitStrategy}.
854 *
855 * @param quitHandler the handler that is called when the application is
856 * asked to quit
857 *
858 * @throws SecurityException if a security manager exists and it
859 * will not allow the caller to invoke {@code System.exit}
860 * @throws UnsupportedOperationException if the current platform
861 * does not support the {@link Desktop.Action#APP_QUIT_HANDLER} action
862 * @since 9
863 */
864 public void setQuitHandler(final QuitHandler quitHandler) {
865 checkQuitPermission();
866 checkActionSupport(Action.APP_QUIT_HANDLER);
867 peer.setQuitHandler(quitHandler);
868 }
869
870 /**
871 * Sets the default strategy used to quit this application. The default is
872 * calling SYSTEM_EXIT_0.
873 *
874 * @param strategy the way this application should be shutdown
875 *
876 * @throws SecurityException if a security manager exists and it
877 * will not allow the caller to invoke {@code System.exit}
878 * @throws UnsupportedOperationException if the current platform
879 * does not support the {@link Desktop.Action#APP_QUIT_STRATEGY} action
880 * @see QuitStrategy
881 * @since 9
882 */
883 public void setQuitStrategy(final QuitStrategy strategy) {
884 checkQuitPermission();
885 checkActionSupport(Action.APP_QUIT_STRATEGY);
886 peer.setQuitStrategy(strategy);
887 }
888
889 /**
890 * Enables this application to be suddenly terminated.
891 *
892 * Call this method to indicate your application's state is saved, and
893 * requires no notification to be terminated. Letting your application
894 * remain terminatable improves the user experience by avoiding re-paging in
895 * your application when it's asked to quit.
896 *
897 * <b>Note: enabling sudden termination will allow your application to be
898 * quit without notifying your QuitHandler, or running any shutdown
899 * hooks.</b>
900 * E.g. user-initiated Cmd-Q, logout, restart, or shutdown requests will
901 * effectively "kill -KILL" your application.
902 *
903 * @throws SecurityException if a security manager exists and it
904 * will not allow the caller to invoke {@code System.exit}
905 * @throws UnsupportedOperationException if the current platform
906 * does not support the {@link Desktop.Action#APP_SUDDEN_TERMINATION} action
907 * @see #disableSuddenTermination()
908 * @since 9
909 */
910 public void enableSuddenTermination() {
911 checkQuitPermission();
912 checkActionSupport(Action.APP_SUDDEN_TERMINATION);
913 peer.enableSuddenTermination();
914 }
915
916 /**
917 * Prevents this application from being suddenly terminated.
918 *
919 * Call this method to indicate that your application has unsaved state, and
920 * may not be terminated without notification.
921 *
922 * @throws SecurityException if a security manager exists and it
923 * will not allow the caller to invoke {@code System.exit}
924 * @throws UnsupportedOperationException if the current platform
925 * does not support the {@link Desktop.Action#APP_SUDDEN_TERMINATION} action
926 * @see #enableSuddenTermination()
927 * @since 9
928 */
929 public void disableSuddenTermination() {
930 checkQuitPermission();
931 checkActionSupport(Action.APP_SUDDEN_TERMINATION);
932 peer.disableSuddenTermination();
933 }
934
935 /**
936 * Requests this application to move to the foreground.
937 *
938 * @param allWindows if all windows of this application should be moved to
939 * the foreground, or only the foremost one
940 * @throws SecurityException if a security manager exists and it denies the
941 * {@code AWTPermission("showWindowWithoutWarningBanner")} permission.
942 * @throws UnsupportedOperationException if the current platform
943 * does not support the {@link Desktop.Action#APP_REQUEST_FOREGROUND} action
944 * @since 9
945 */
946 public void requestForeground(final boolean allWindows) {
947 checkAWTPermission();
948 checkActionSupport(Action.APP_REQUEST_FOREGROUND);
949 peer.requestForeground(allWindows);
950 }
951
952 /**
953 * Opens the native help viewer application.
954 *
955 * @implNote Please note that for Mac OS, it opens the native help viewer
956 * application if a Help Book has been added to the application bundler
957 * and registered in the Info.plist with CFBundleHelpBookFolder
958 *
959 * @throws SecurityException if a security manager exists and it denies the
960 * {@code AWTPermission("showWindowWithoutWarningBanner")} permission.
961 * @throws UnsupportedOperationException if the current platform
962 * does not support the {@link Desktop.Action#APP_HELP_VIEWER} action
963 * @since 9
964 */
965 public void openHelpViewer() {
966 checkAWTPermission();
967 checkActionSupport(Action.APP_HELP_VIEWER);
968 peer.openHelpViewer();
969 }
970
971 /**
972 * Sets the default menu bar to use when there are no active frames.
973 *
974 * @implNote Aqua Look and Feel should be active to support this on Mac OS.
975 *
976 * @param menuBar to use when no other frames are active
977 * @throws SecurityException if a security manager exists and it denies the
978 * {@code AWTPermission("showWindowWithoutWarningBanner")} permission.
979 * @throws UnsupportedOperationException if the current platform
980 * does not support the {@link Desktop.Action#APP_MENU_BAR} action
981 * @since 9
982 */
983 public void setDefaultMenuBar(final JMenuBar menuBar) {
984 checkAWTPermission();
985 checkActionSupport(Action.APP_MENU_BAR);
986 peer.setDefaultMenuBar(menuBar);
987 }
988
989 /**
990 * Opens a folder containing the {@code file} and selects it
991 * in a default system file manager.
992 * @param file the file
993 * @throws SecurityException If a security manager exists and its
994 * {@link SecurityManager#checkRead(java.lang.String)} method
995 * denies read access to the file
996 * @throws UnsupportedOperationException if the current platform
997 * does not support the {@link Desktop.Action#BROWSE_FILE_DIR} action
998 * @throws NullPointerException if {@code file} is {@code null}
999 * @throws IllegalArgumentException if the specified file doesn't
1000 * exist
1001 * @since 9
1002 */
1003 public void browseFileDirectory(File file) {
|
254 * Represents a move to trash
255 * @see #moveToTrash(java.io.File)
256 * @since 9
257 */
258 MOVE_TO_TRASH
259 };
260
261 private DesktopPeer peer;
262
263 /**
264 * Suppresses default constructor for noninstantiability.
265 */
266 private Desktop() {
267 Toolkit defaultToolkit = Toolkit.getDefaultToolkit();
268 // same cast as in isDesktopSupported()
269 if (defaultToolkit instanceof SunToolkit) {
270 peer = ((SunToolkit) defaultToolkit).createDesktopPeer(this);
271 }
272 }
273
274 private static void checkEventsProcessingPermission() {
275 SecurityManager sm = System.getSecurityManager();
276 if (sm != null) {
277 sm.checkPermission(new RuntimePermission(
278 "canProcessApplicationEvents"));
279 }
280 }
281
282 /**
283 * Returns the {@code Desktop} instance of the current
284 * desktop context. On some platforms the Desktop API may not be
285 * supported; use the {@link #isDesktopSupported} method to
286 * determine if the current desktop is supported.
287 * @return the Desktop instance
288 * @throws HeadlessException if {@link
289 * GraphicsEnvironment#isHeadless()} returns {@code true}
290 * @throws UnsupportedOperationException if this class is not
291 * supported on the current platform
292 * @see #isDesktopSupported()
293 * @see java.awt.GraphicsEnvironment#isHeadless
294 */
295 public static synchronized Desktop getDesktop(){
296 if (GraphicsEnvironment.isHeadless()) throw new HeadlessException();
297 if (!Desktop.isDesktopSupported()) {
298 throw new UnsupportedOperationException("Desktop API is not " +
299 "supported on the current platform");
300 }
301
653 }
654
655 private void checkQuitPermission() {
656 SecurityManager sm = System.getSecurityManager();
657 if (sm != null) {
658 sm.checkExit(0);
659 }
660 }
661
662 /**
663 * Adds sub-types of {@link SystemEventListener} to listen for notifications
664 * from the native system.
665 *
666 * Has no effect if SystemEventListener's sub-type is unsupported on the current
667 * platform.
668 *
669 * @param listener listener
670 *
671 * @throws SecurityException if a security manager exists and it
672 * denies the
673 * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
674 * {@code RuntimePermission("canProcessApplicationEvents")}
675 * permission
676 *
677 * @see java.awt.desktop.AppForegroundListener
678 * @see java.awt.desktop.AppHiddenListener
679 * @see java.awt.desktop.AppReopenedListener
680 * @see java.awt.desktop.ScreenSleepListener
681 * @see java.awt.desktop.SystemSleepListener
682 * @see java.awt.desktop.UserSessionListener
683 * @since 9
684 */
685 public void addAppEventListener(final SystemEventListener listener) {
686 checkEventsProcessingPermission();
687 checkAWTPermission();
688 peer.addAppEventListener(listener);
689 }
690
691 /**
692 * Removes sub-types of {@link SystemEventListener} to listen for notifications
693 * from the native system.
694 *
695 * Has no effect if SystemEventListener's sub-type is unsupported on the current
696 * platform.
697 *
698 * @param listener listener
699 *
700 * @throws SecurityException if a security manager exists and it
701 * denies the
702 * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
703 * {@code RuntimePermission("canProcessApplicationEvents")}
704 * permission
705 *
706 * @see java.awt.desktop.AppForegroundListener
707 * @see java.awt.desktop.AppHiddenListener
708 * @see java.awt.desktop.AppReopenedListener
709 * @see java.awt.desktop.ScreenSleepListener
710 * @see java.awt.desktop.SystemSleepListener
711 * @see java.awt.desktop.UserSessionListener
712 * @since 9
713 */
714 public void removeAppEventListener(final SystemEventListener listener) {
715 checkEventsProcessingPermission();
716 checkAWTPermission();
717 peer.removeAppEventListener(listener);
718 }
719
720 /**
721 * Installs a handler to show a custom About window for your application.
722 * <p>
723 * Setting the {@link java.awt.desktop.AboutHandler} to {@code null} reverts it to the
724 * default behavior.
725 *
726 * @param aboutHandler the handler to respond to the
727 * {@link java.awt.desktop.AboutHandler#handleAbout} )} message
728 *
729 * @throws SecurityException if a security manager exists and it
730 * denies the
731 * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
732 * {@code RuntimePermission("canProcessApplicationEvents")}
733 * permission
734 * @throws UnsupportedOperationException if the current platform
735 * does not support the {@link Desktop.Action#APP_ABOUT} action
736 *
737 * @since 9
738 */
739 public void setAboutHandler(final AboutHandler aboutHandler) {
740 checkEventsProcessingPermission();
741 checkAWTPermission();
742 checkActionSupport(Action.APP_ABOUT);
743 peer.setAboutHandler(aboutHandler);
744 }
745
746 /**
747 * Installs a handler to show a custom Preferences window for your
748 * application.
749 * <p>
750 * Setting the {@link PreferencesHandler} to {@code null} reverts it to
751 * the default behavior
752 *
753 * @param preferencesHandler the handler to respond to the
754 * {@link PreferencesHandler#handlePreferences(PreferencesEvent)}
755 *
756 * @throws SecurityException if a security manager exists and it
757 * denies the
758 * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
759 * {@code RuntimePermission("canProcessApplicationEvents")}
760 * permission
761 * @throws UnsupportedOperationException if the current platform
762 * does not support the {@link Desktop.Action#APP_PREFERENCES} action
763 * @since 9
764 */
765 public void setPreferencesHandler(final PreferencesHandler preferencesHandler) {
766 checkEventsProcessingPermission();
767 checkAWTPermission();
768 checkActionSupport(Action.APP_PREFERENCES);
769 peer.setPreferencesHandler(preferencesHandler);
770 }
771
772 /**
773 * Installs the handler which is notified when the application is asked to
774 * open a list of files.
775 *
776 * @implNote Please note that for Mac OS, notifications
777 * are only sent if the Java app is a bundled application,
778 * with a {@code CFBundleDocumentTypes} array present in its
779 * Info.plist. See the
780 * <a href="http://developer.apple.com/mac/library/documentation/General/Reference/InfoPlistKeyReference">
781 * Info.plist Key Reference</a> for more information about adding a
782 * {@code CFBundleDocumentTypes} key to your app's Info.plist.
783 *
784 * @param openFileHandler handler
785 *
786 * @throws SecurityException if a security manager exists and its
787 * {@link java.lang.SecurityManager#checkRead(java.lang.String)}
788 * method denies read access to the files, or it denies the
789 * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
790 * {@code RuntimePermission("canProcessApplicationEvents")}
791 * permission, or the calling thread is not allowed to create a
792 * subprocess
793 * @throws UnsupportedOperationException if the current platform
794 * does not support the {@link Desktop.Action#APP_OPEN_FILE} action
795 * @since 9
796 */
797 public void setOpenFileHandler(final OpenFilesHandler openFileHandler) {
798 checkEventsProcessingPermission();
799 checkAWTPermission();
800 checkExec();
801 checkRead();
802 checkActionSupport(Action.APP_OPEN_FILE);
803 peer.setOpenFileHandler(openFileHandler);
804 }
805
806 /**
807 * Installs the handler which is notified when the application is asked to
808 * print a list of files.
809 *
810 * @implNote Please note that for Mac OS, notifications
811 * are only sent if the Java app is a bundled application,
812 * with a {@code CFBundleDocumentTypes} array present in its
813 * Info.plist. See the
814 * <a href="http://developer.apple.com/mac/library/documentation/General/Reference/InfoPlistKeyReference">
815 * Info.plist Key Reference</a> for more information about adding a
816 * {@code CFBundleDocumentTypes} key to your app's Info.plist.
817 *
818 * @param printFileHandler handler
819 * @throws SecurityException if a security manager exists and its
820 * {@link java.lang.SecurityManager#checkPrintJobAccess()} method denies
821 * the permission to print or it denies the
822 * {@code RuntimePermission("canProcessApplicationEvents")} permission
823 * @throws UnsupportedOperationException if the current platform
824 * does not support the {@link Desktop.Action#APP_PRINT_FILE} action
825 * @since 9
826 */
827 public void setPrintFileHandler(final PrintFilesHandler printFileHandler) {
828 checkEventsProcessingPermission();
829 SecurityManager sm = System.getSecurityManager();
830 if (sm != null) {
831 sm.checkPrintJobAccess();
832 }
833 checkActionSupport(Action.APP_PRINT_FILE);
834 peer.setPrintFileHandler(printFileHandler);
835 }
836
837 /**
838 * Installs the handler which is notified when the application is asked to
839 * open a URL.
840 *
841 * Setting the handler to {@code null} causes all
842 * {@link OpenURIHandler#openURI(AppEvent.OpenURIEvent)} requests to be
843 * enqueued until another handler is set.
844 *
845 * @implNote Please note that for Mac OS, notifications
846 * are only sent if the Java app is a bundled application,
847 * with a {@code CFBundleDocumentTypes} array present in its
848 * Info.plist. See the
849 * <a href="http://developer.apple.com/mac/library/documentation/General/Reference/InfoPlistKeyReference">
850 * Info.plist Key Reference</a> for more information about adding a
851 * {@code CFBundleDocumentTypes} key to your app's Info.plist.
852 *
853 * @param openURIHandler handler
854 *
855 * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
856 * {@code RuntimePermission("canProcessApplicationEvents")}
857 * permission, or the calling thread is not allowed to create a
858 * subprocess
859 * @throws UnsupportedOperationException if the current platform
860 * does not support the {@link Desktop.Action#APP_OPEN_URI} action
861 * @since 9
862 */
863 public void setOpenURIHandler(final OpenURIHandler openURIHandler) {
864 checkEventsProcessingPermission();
865 checkAWTPermission();
866 checkExec();
867 checkActionSupport(Action.APP_OPEN_URI);
868 peer.setOpenURIHandler(openURIHandler);
869 }
870
871 /**
872 * Installs the handler which determines if the application should quit. The
873 * handler is passed a one-shot {@link java.awt.desktop.QuitResponse} which can cancel or
874 * proceed with the quit. Setting the handler to {@code null} causes
875 * all quit requests to directly perform the default {@link QuitStrategy}.
876 *
877 * @param quitHandler the handler that is called when the application is
878 * asked to quit
879 *
880 * @throws SecurityException if a security manager exists and it
881 * will not allow the caller to invoke {@code System.exit} or it denies the
882 * {@code RuntimePermission("canProcessApplicationEvents")} permission
883 * @throws UnsupportedOperationException if the current platform
884 * does not support the {@link Desktop.Action#APP_QUIT_HANDLER} action
885 * @since 9
886 */
887 public void setQuitHandler(final QuitHandler quitHandler) {
888 checkEventsProcessingPermission();
889 checkQuitPermission();
890 checkActionSupport(Action.APP_QUIT_HANDLER);
891 peer.setQuitHandler(quitHandler);
892 }
893
894 /**
895 * Sets the default strategy used to quit this application. The default is
896 * calling SYSTEM_EXIT_0.
897 *
898 * @param strategy the way this application should be shutdown
899 *
900 * @throws SecurityException if a security manager exists and it
901 * will not allow the caller to invoke {@code System.exit} or it denies the
902 * {@code RuntimePermission("canProcessApplicationEvents")} permission
903 * @throws UnsupportedOperationException if the current platform
904 * does not support the {@link Desktop.Action#APP_QUIT_STRATEGY} action
905 * @see QuitStrategy
906 * @since 9
907 */
908 public void setQuitStrategy(final QuitStrategy strategy) {
909 checkEventsProcessingPermission();
910 checkQuitPermission();
911 checkActionSupport(Action.APP_QUIT_STRATEGY);
912 peer.setQuitStrategy(strategy);
913 }
914
915 /**
916 * Enables this application to be suddenly terminated.
917 *
918 * Call this method to indicate your application's state is saved, and
919 * requires no notification to be terminated. Letting your application
920 * remain terminatable improves the user experience by avoiding re-paging in
921 * your application when it's asked to quit.
922 *
923 * <b>Note: enabling sudden termination will allow your application to be
924 * quit without notifying your QuitHandler, or running any shutdown
925 * hooks.</b>
926 * E.g. user-initiated Cmd-Q, logout, restart, or shutdown requests will
927 * effectively "kill -KILL" your application.
928 *
929 * @throws SecurityException if a security manager exists and it
930 * will not allow the caller to invoke {@code System.exit} or it denies the
931 * {@code RuntimePermission("canProcessApplicationEvents")} permission
932 * @throws UnsupportedOperationException if the current platform
933 * does not support the {@link Desktop.Action#APP_SUDDEN_TERMINATION} action
934 * @see #disableSuddenTermination()
935 * @since 9
936 */
937 public void enableSuddenTermination() {
938 checkEventsProcessingPermission();
939 checkQuitPermission();
940 checkActionSupport(Action.APP_SUDDEN_TERMINATION);
941 peer.enableSuddenTermination();
942 }
943
944 /**
945 * Prevents this application from being suddenly terminated.
946 *
947 * Call this method to indicate that your application has unsaved state, and
948 * may not be terminated without notification.
949 *
950 * @throws SecurityException if a security manager exists and it
951 * will not allow the caller to invoke {@code System.exit} or it denies the
952 * {@code RuntimePermission("canProcessApplicationEvents")} permission
953 * @throws UnsupportedOperationException if the current platform
954 * does not support the {@link Desktop.Action#APP_SUDDEN_TERMINATION} action
955 * @see #enableSuddenTermination()
956 * @since 9
957 */
958 public void disableSuddenTermination() {
959 checkEventsProcessingPermission();
960 checkQuitPermission();
961 checkActionSupport(Action.APP_SUDDEN_TERMINATION);
962 peer.disableSuddenTermination();
963 }
964
965 /**
966 * Requests this application to move to the foreground.
967 *
968 * @param allWindows if all windows of this application should be moved to
969 * the foreground, or only the foremost one
970 * @throws SecurityException if a security manager exists and it denies the
971 * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
972 * {@code RuntimePermission("canProcessApplicationEvents")} permission.
973 * @throws UnsupportedOperationException if the current platform
974 * does not support the {@link Desktop.Action#APP_REQUEST_FOREGROUND} action
975 * @since 9
976 */
977 public void requestForeground(final boolean allWindows) {
978 checkEventsProcessingPermission();
979 checkAWTPermission();
980 checkActionSupport(Action.APP_REQUEST_FOREGROUND);
981 peer.requestForeground(allWindows);
982 }
983
984 /**
985 * Opens the native help viewer application.
986 *
987 * @implNote Please note that for Mac OS, it opens the native help viewer
988 * application if a Help Book has been added to the application bundler
989 * and registered in the Info.plist with CFBundleHelpBookFolder
990 *
991 * @throws SecurityException if a security manager exists and it denies the
992 * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
993 * {@code RuntimePermission("canProcessApplicationEvents")} permission.
994 * @throws UnsupportedOperationException if the current platform
995 * does not support the {@link Desktop.Action#APP_HELP_VIEWER} action
996 * @since 9
997 */
998 public void openHelpViewer() {
999 checkEventsProcessingPermission();
1000 checkAWTPermission();
1001 checkActionSupport(Action.APP_HELP_VIEWER);
1002 peer.openHelpViewer();
1003 }
1004
1005 /**
1006 * Sets the default menu bar to use when there are no active frames.
1007 *
1008 * @implNote Aqua Look and Feel should be active to support this on Mac OS.
1009 *
1010 * @param menuBar to use when no other frames are active
1011 * @throws SecurityException if a security manager exists and it denies the
1012 * {@code AWTPermission("showWindowWithoutWarningBanner")} or the
1013 * {@code RuntimePermission("canProcessApplicationEvents")} permission.
1014 * @throws UnsupportedOperationException if the current platform
1015 * does not support the {@link Desktop.Action#APP_MENU_BAR} action
1016 * @since 9
1017 */
1018 public void setDefaultMenuBar(final JMenuBar menuBar) {
1019 checkEventsProcessingPermission();
1020 checkAWTPermission();
1021 checkActionSupport(Action.APP_MENU_BAR);
1022 peer.setDefaultMenuBar(menuBar);
1023 }
1024
1025 /**
1026 * Opens a folder containing the {@code file} and selects it
1027 * in a default system file manager.
1028 * @param file the file
1029 * @throws SecurityException If a security manager exists and its
1030 * {@link SecurityManager#checkRead(java.lang.String)} method
1031 * denies read access to the file
1032 * @throws UnsupportedOperationException if the current platform
1033 * does not support the {@link Desktop.Action#BROWSE_FILE_DIR} action
1034 * @throws NullPointerException if {@code file} is {@code null}
1035 * @throws IllegalArgumentException if the specified file doesn't
1036 * exist
1037 * @since 9
1038 */
1039 public void browseFileDirectory(File file) {
|