Module java.desktop

Package java.awt

Class Desktop

java.lang.Object

java.awt.Desktop

       public class Desktop extends Object
      

Desktop类允许与各种桌面功能进行交互。

支持的操作包括：

• 启动用户默认浏览器以显示指定的URI；
• 启动用户默认邮件客户端，并带有可选的mailto URI；
• 启动已注册的应用程序以打开、编辑或打印指定的文件。

该类提供了对应于这些操作的方法。这些方法会查找当前平台上注册的关联应用程序，并启动它来处理URI或文件。如果没有关联的应用程序或关联的应用程序无法启动，则会抛出异常。请参阅Desktop.Action以获取支持的操作和功能的完整列表。

应用程序会注册到URI或文件类型。注册、访问和启动关联应用程序的机制取决于平台。

每个操作都是由Desktop.Action类表示的操作类型。

注意：当调用某个操作并执行关联的应用程序时，它将在启动Java应用程序的系统上执行。

自版本:

1.6

参见:

• Desktop.Action

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	Desktop.Action	表示一个操作类型。

Method Summary

Modifier and Type	Method	Description
void	addAppEventListener(SystemEventListener listener)	向SystemEventListener添加子类型，以便监听来自本机系统的通知。
void	browse(URI uri)	启动默认浏览器以显示一个URI。
void	browseFileDirectory(File file)	打开包含file的文件夹，并在默认系统文件管理器中选择它。
void	disableSuddenTermination()	防止此应用程序突然终止。
void	edit(File file)	启动关联的编辑器应用程序并打开文件进行编辑。
void	enableSuddenTermination()	允许此应用程序突然终止。
static Desktop	getDesktop()	返回当前桌面上下文的Desktop实例。
static boolean	isDesktopSupported()	测试当前平台是否支持此类。
boolean	isSupported(Desktop.Action action)	测试当前平台是否支持某个操作。
void	mail()	启动用户默认邮件客户端的邮件撰写窗口。
void	mail(URI mailtoURI)	启动用户默认邮件客户端的邮件撰写窗口，并填写由mailto: URI指定的消息字段。
boolean	moveToTrash(File file)	将指定的文件移动到回收站。
void	open(File file)	启动关联应用程序以打开文件。
void	openHelpViewer()	打开本机帮助查看器应用程序。
void	print(File file)	使用关联应用程序的打印命令，通过本机桌面打印设施打印文件。
void	removeAppEventListener(SystemEventListener listener)	从SystemEventListener中移除子类型，以便监听来自本机系统的通知。
void	requestForeground(boolean allWindows)	请求此应用程序移至前台。
void	setAboutHandler(AboutHandler aboutHandler)	安装处理程序，以显示应用程序的自定义关于窗口。
void	setDefaultMenuBar(JMenuBar menuBar)	设置在没有活动框架时使用的默认菜单栏。
void	setOpenFileHandler(OpenFilesHandler openFileHandler)	安装处理程序，当应用程序被要求打开文件列表时通知。
void	setOpenURIHandler(OpenURIHandler openURIHandler)	安装处理程序，当应用程序被要求打开URL时通知。
void	setPreferencesHandler(PreferencesHandler preferencesHandler)	安装处理程序，以显示应用程序的自定义首选项窗口。
void	setPrintFileHandler(PrintFilesHandler printFileHandler)	安装处理程序，当应用程序被要求打印文件列表时通知。
void	setQuitHandler(QuitHandler quitHandler)	安装处理程序，确定应用程序是否应退出。
void	setQuitStrategy(QuitStrategy strategy)	设置用于退出此应用程序的默认策略。

Methods declared in class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

getDesktop

             public static Desktop getDesktop()
            

返回当前桌面上下文的Desktop实例。在某些平台上，可能不支持Desktop API；使用isDesktopSupported()方法来确定当前桌面是否受支持。

返回:

Desktop实例

抛出:

HeadlessException - 如果GraphicsEnvironment.isHeadless()返回true

UnsupportedOperationException - 如果当前平台不支持此类

参见:

• isDesktopSupported()
• GraphicsEnvironment.isHeadless()

isDesktopSupported

             public static boolean isDesktopSupported()
            

测试当前平台是否支持此类。如果支持，请使用getDesktop()来检索一个实例。

返回:

如果当前平台支持此类，则返回true；否则返回false

参见:

• getDesktop()

isSupported

             public boolean isSupported(Desktop.Action action)
            

测试当前平台是否支持某个操作。

即使平台支持某个操作，文件或URI可能没有注册应用程序来执行该操作。例如，大多数平台支持Desktop.Action.OPEN操作。但是对于特定文件，可能没有注册应用程序来打开它。在这种情况下，isSupported(Action)可能返回true，但相应的操作方法将抛出一个IOException。

参数:

action - 指定的Desktop.Action

返回:

如果当前平台支持指定的操作，则返回true；否则返回false

参见:

• Desktop.Action

open

             public void open(File file) throws IOException
            

启动关联应用程序以打开文件。

如果指定的文件是一个目录，则启动当前平台的文件管理器以打开它。

参数:

file - 要使用关联应用程序打开的文件

抛出:

NullPointerException - 如果file为null

IllegalArgumentException - 如果指定的文件不存在

UnsupportedOperationException - 如果当前平台不支持Desktop.Action.OPEN操作

IOException - 如果指定的文件没有关联应用程序，或关联的应用程序无法启动

SecurityException - 如果存在安全管理器且其SecurityManager.checkRead(java.lang.String)方法拒绝对文件的读取访问，或拒绝AWTPermission("showWindowWithoutWarningBanner")权限，或调用线程不允许创建子进程

参见:

• AWTPermission

edit

             public void edit(File file) throws IOException
            

启动关联的编辑器应用程序并打开文件进行编辑。

参数:

file - 要打开进行编辑的文件

抛出:

NullPointerException - 如果指定的文件为null

IllegalArgumentException - 如果指定的文件不存在

UnsupportedOperationException - 如果当前平台不支持Desktop.Action.EDIT操作

IOException - 如果指定的文件没有关联编辑器，或关联的应用程序无法启动

SecurityException - 如果存在安全管理器且其SecurityManager.checkRead(java.lang.String)方法拒绝对文件的读取访问，或SecurityManager.checkWrite(java.lang.String)方法拒绝对文件的写访问，或拒绝AWTPermission("showWindowWithoutWarningBanner")权限，或调用线程不允许创建子进程

参见:

• AWTPermission

print

             public void print(File file) throws IOException
            

使用关联应用程序的打印命令，通过本机桌面打印设施打印文件。

参数:

file - 要打印的文件

抛出:

NullPointerException - 如果指定的文件为null

IllegalArgumentException - 如果指定的文件不存在

UnsupportedOperationException - 如果当前平台不支持Desktop.Action.PRINT操作

IOException - 如果指定的文件没有关联的应用程序可用于打印

SecurityException - 如果存在安全管理器且其SecurityManager.checkRead(java.lang.String)方法拒绝对文件的读取访问，或其SecurityManager.checkPrintJobAccess()方法拒绝打印文件的权限，或调用线程不允许创建子进程

browse

             public void browse(URI uri) throws IOException
            

启动默认浏览器以显示URI。如果默认浏览器无法处理指定的URI，则调用注册用于处理指定类型URI的应用程序。应用程序由URI类定义的协议和路径确定。

参数:

uri - 要在用户默认浏览器中显示的URI

抛出:

NullPointerException - 如果uri为null

UnsupportedOperationException - 如果当前平台不支持Desktop.Action.BROWSE操作

IOException - 如果未找到用户默认浏览器，或者启动失败，或者默认处理程序应用程序启动失败

SecurityException - 如果存在安全管理器且拒绝AWTPermission("showWindowWithoutWarningBanner")权限，或调用线程不允许创建子进程

参见:

• URI
• AWTPermission

mail

             public void mail() throws IOException
            

启动用户默认邮件客户端的邮件撰写窗口。

抛出:

UnsupportedOperationException - 如果当前平台不支持Desktop.Action.MAIL操作

IOException - 如果未找到用户默认邮件客户端，或者启动失败

SecurityException - 如果存在安全管理器且拒绝AWTPermission("showWindowWithoutWarningBanner")权限，或调用线程不允许创建子进程

参见:

• AWTPermission

mail

             public void mail(URI mailtoURI) throws IOException
            

启动用户默认邮件客户端的邮件撰写窗口，并填写由mailto: URI指定的消息字段。

mailto: URI可以指定消息字段，包括"to"、"cc"、"subject"、"body"等。请参阅mailto URL scheme (RFC 2368)以获取mailto: URI规范详细信息。

参数:

mailtoURI - 指定的mailto: URI

抛出:

NullPointerException - 如果指定的URI为null

IllegalArgumentException - 如果URI方案不是"mailto"

UnsupportedOperationException - 如果当前平台不支持Desktop.Action.MAIL操作

IOException - 如果未找到用户默认邮件客户端或启动失败

SecurityException - 如果存在安全管理器且拒绝AWTPermission("showWindowWithoutWarningBanner")权限，或调用线程不允许创建子进程

参见:

• URI
• AWTPermission

addAppEventListener

             public void addAppEventListener(SystemEventListener listener)
            

添加SystemEventListener的子类型以侦听来自本地系统的通知。如果当前平台不支持SystemEventListener的子类型，则不会产生任何效果。

参数:

listener - 监听器

抛出:

SecurityException - 如果存在安全管理器且拒绝RuntimePermission("canProcessApplicationEvents")权限

自:

9

参见:

• AppForegroundListener
• AppHiddenListener
• AppReopenedListener
• ScreenSleepListener
• SystemSleepListener
• UserSessionListener

removeAppEventListener

             public void removeAppEventListener(SystemEventListener listener)
            

移除SystemEventListener的子类型以侦听来自本地系统的通知。如果当前平台不支持SystemEventListener的子类型，则不会产生任何效果。

参数:

listener - 监听器

抛出:

SecurityException - 如果存在安全管理器且拒绝RuntimePermission("canProcessApplicationEvents")权限

自:

9

参见:

• AppForegroundListener
• AppHiddenListener
• AppReopenedListener
• ScreenSleepListener
• SystemSleepListener
• UserSessionListener

setAboutHandler

             public void setAboutHandler(AboutHandler aboutHandler)
            

安装处理程序以显示应用程序的自定义关于窗口。

将AboutHandler设置为null会将其恢复为默认行为。

参数:

aboutHandler - 用于响应AboutHandler.handleAbout(AboutEvent)消息的处理程序

抛出:

SecurityException - 如果存在安全管理器且拒绝RuntimePermission("canProcessApplicationEvents")权限

UnsupportedOperationException - 如果当前平台不支持Desktop.Action.APP_ABOUT操作

自:

9

setPreferencesHandler

             public void setPreferencesHandler(PreferencesHandler preferencesHandler)
            

安装处理程序以显示应用程序的自定义首选项窗口。

将PreferencesHandler设置为null会将其恢复为默认行为

参数:

preferencesHandler - 响应 PreferencesHandler.handlePreferences(PreferencesEvent) 的处理程序

抛出:

SecurityException - 如果存在安全管理器并且拒绝 RuntimePermission("canProcessApplicationEvents") 权限

UnsupportedOperationException - 如果当前平台不支持 Desktop.Action.APP_PREFERENCES 操作

自 JDK 版本:

9

setOpenFileHandler

             public void setOpenFileHandler(OpenFilesHandler openFileHandler)
            

安装处理程序，当应用程序被要求打开文件列表时会收到通知。

实现注意事项:

请注意，对于 macOS，仅当 Java 应用程序是捆绑应用程序且其 Info.plist 中存在 CFBundleDocumentTypes 数组时，才会发送通知。有关 Info.plist 的更多信息，请查看 Apple Developer Documentation。

参数:

openFileHandler - 处理程序

抛出:

SecurityException - 如果存在安全管理器并且其 SecurityManager.checkRead(java.lang.String) 方法拒绝对文件的读取访问，或者拒绝 RuntimePermission("canProcessApplicationEvents") 权限，或者调用线程不允许创建子进程

UnsupportedOperationException - 如果当前平台不支持 Desktop.Action.APP_OPEN_FILE 操作

自 JDK 版本:

9

setPrintFileHandler

             public void setPrintFileHandler(PrintFilesHandler printFileHandler)
            

安装处理程序，当应用程序被要求打印文件列表时会收到通知。

实现注意事项:

请注意，对于 macOS，仅当 Java 应用程序是捆绑应用程序且其 Info.plist 中存在 CFBundleDocumentTypes 数组时，才会发送通知。有关 Info.plist 的更多信息，请查看 Apple Developer Documentation。

参数:

printFileHandler - 处理程序

抛出:

SecurityException - 如果存在安全管理器并且其 SecurityManager.checkPrintJobAccess() 方法拒绝打印权限，或者拒绝 RuntimePermission("canProcessApplicationEvents") 权限

UnsupportedOperationException - 如果当前平台不支持 Desktop.Action.APP_PRINT_FILE 操作

自 JDK 版本:

9

setOpenURIHandler

             public void setOpenURIHandler(OpenURIHandler openURIHandler)
            

安装处理程序，当应用程序被要求打开 URL 时会收到通知。将处理程序设置为 null 会导致所有 OpenURIHandler.openURI(OpenURIEvent) 请求被排队，直到设置另一个处理程序。

实现注意事项:

请注意，对于 macOS，仅当 Java 应用程序是捆绑应用程序且其 Info.plist 中存在 CFBundleDocumentTypes 数组时，才会发送通知。有关 Info.plist 的更多信息，请查看 Apple Developer Documentation。

参数:

openURIHandler - 处理程序 RuntimePermission("canProcessApplicationEvents") 权限，或者调用线程不允许创建子进程

抛出:

UnsupportedOperationException - 如果当前平台不支持 Desktop.Action.APP_OPEN_URI 操作

自 JDK 版本:

9

setQuitHandler

             public void setQuitHandler(QuitHandler quitHandler)
            

安装处理程序，确定应用程序是否应该退出。处理程序会传递一个一次性的 QuitResponse，可以取消退出或继续退出。将处理程序设置为 null 会导致所有退出请求直接执行默认的 QuitStrategy。

参数:

quitHandler - 当应用程序被要求退出时调用的处理程序

抛出:

SecurityException - 如果存在安全管理器并且不允许调用者调用 System.exit，或者拒绝 RuntimePermission("canProcessApplicationEvents") 权限

UnsupportedOperationException - 如果当前平台不支持 Desktop.Action.APP_QUIT_HANDLER 操作

自 JDK 版本:

9

setQuitStrategy

             public void setQuitStrategy(QuitStrategy strategy)
            

设置用于退出此应用程序的默认策略。默认情况下调用 SYSTEM_EXIT_0。

参数:

strategy - 应用程序应该关闭的方式

抛出:

SecurityException - 如果存在安全管理器并且不允许调用者调用 System.exit，或者拒绝 RuntimePermission("canProcessApplicationEvents") 权限

UnsupportedOperationException - 如果当前平台不支持 Desktop.Action.APP_QUIT_STRATEGY 操作

自 JDK 版本:

9

参见:

• QuitStrategy

enableSuddenTermination

             public void enableSuddenTermination()
            

启用此应用程序突然终止。调用此方法表示您的应用程序状态已保存，并且不需要通知即可终止。让您的应用程序保持可终止状态可通过避免在要求退出时重新分页应用程序来提高用户体验。 注意: 启用突然终止将允许您的应用程序在不通知 QuitHandler 或运行任何关闭挂钩的情况下退出。 例如，用户发起的 Cmd-Q、注销、重新启动或关机请求将有效地 "kill -KILL" 您的应用程序。

抛出:

SecurityException - 如果存在安全管理器并且不允许调用者调用 System.exit，或者拒绝 RuntimePermission("canProcessApplicationEvents") 权限

UnsupportedOperationException - 如果当前平台不支持 Desktop.Action.APP_SUDDEN_TERMINATION 操作

自 JDK 版本:

9

参见:

• disableSuddenTermination()

disableSuddenTermination

             public void disableSuddenTermination()
            

防止此应用程序突然终止。调用此方法表示您的应用程序具有未保存的状态，并且可能不会在没有通知的情况下终止。

抛出:

SecurityException - 如果存在安全管理器并且不允许调用者调用 System.exit，或者拒绝 RuntimePermission("canProcessApplicationEvents") 权限

UnsupportedOperationException - 如果当前平台不支持 Desktop.Action.APP_SUDDEN_TERMINATION 操作

自 JDK 版本:

9

参见:

• enableSuddenTermination()

requestForeground

             public void requestForeground(boolean allWindows)
            

请求此应用程序移至前台。

参数:

allWindows - 是否应将此应用程序的所有窗口移至前台，或仅将最前面的窗口移至前台

抛出:

SecurityException - 如果存在安全管理器并且拒绝 RuntimePermission("canProcessApplicationEvents") 权限。

UnsupportedOperationException - 如果当前平台不支持 Desktop.Action.APP_REQUEST_FOREGROUND 操作

自 JDK 版本:

9

openHelpViewer

             public void openHelpViewer()
            

打开本机帮助查看器应用程序。

实现注意事项:

请注意，对于Mac OS，如果应用程序包装器中添加了帮助书并在Info.plist中注册了CFBundleHelpBookFolder，则会打开本机帮助查看器应用程序

抛出:

SecurityException - 如果存在安全管理器并且拒绝RuntimePermission("canProcessApplicationEvents")权限，或者拒绝AWTPermission("showWindowWithoutWarningBanner")权限，或者调用线程不允许创建子进程

UnsupportedOperationException - 如果当前平台不支持Desktop.Action.APP_HELP_VIEWER操作

自版本:

9

setDefaultMenuBar

             public void setDefaultMenuBar(JMenuBar menuBar)
            

设置当没有活动框架时要使用的默认菜单栏。

参数:

menuBar - 当没有其他框架处于活动状态时要使用的菜单栏

抛出:

SecurityException - 如果存在安全管理器并且拒绝RuntimePermission("canProcessApplicationEvents")权限。

UnsupportedOperationException - 如果当前平台不支持Desktop.Action.APP_MENU_BAR操作

自版本:

9

browseFileDirectory

             public void browseFileDirectory(File file)
            

打开包含file的文件夹并在默认系统文件管理器中选择它。

参数:

file - 文件

抛出:

SecurityException - 如果存在安全管理器并且其SecurityManager.checkRead(java.lang.String)方法拒绝对文件或其父级的读取访问，或者拒绝AWTPermission("showWindowWithoutWarningBanner")权限，或者调用线程不允许创建子进程

UnsupportedOperationException - 如果当前平台不支持Desktop.Action.BROWSE_FILE_DIR操作

NullPointerException - 如果file为null

IllegalArgumentException - 如果指定的文件或其父级不存在

自版本:

9

moveToTrash

             public boolean moveToTrash(File file)
            

将指定的文件移动到回收站。

参数:

file - 文件

返回:

如果成功将文件移动到回收站，则返回true。

抛出:

SecurityException - 如果存在安全管理器并且其SecurityManager.checkDelete(java.lang.String)方法拒绝删除文件

UnsupportedOperationException - 如果当前平台不支持Desktop.Action.MOVE_TO_TRASH操作

NullPointerException - 如果file为null

IllegalArgumentException - 如果指定的文件不存在

自版本:

9