模块 java.desktop

包 java.awt

类 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

内部类总结

内部类

修饰符和类型	类	描述
static enum	Desktop.Action	代表一个动作类型。

方法总结

修饰符和类型	方法	描述
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)	设置用于退出此应用程序的默认策略。

在类 java.lang.Object 中声明的方法

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

方法详情

getDesktop

public static Desktop  getDesktop()
            

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

返回：

桌面实例

抛出：

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 ，则调用为处理指定类型的 URIs 而注册的应用程序。应用程序由 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 可以指定消息字段，包括“到”, “抄送”, “主题”, “身体”等。有关 mailto: URI 规范的详细信息，请参阅 mailto URL 方案 (RFC 2368)。

参数：

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 操作

自从：

9

setOpenFileHandler

public void setOpenFileHandler(OpenFilesHandler  openFileHandler)
            

安装当要求应用程序打开文件列表时通知的处理程序。

实现注意事项：

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

参数：

openFileHandler - 处理程序

抛出：

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

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

自从：

9

setPrintFileHandler

public void setPrintFileHandler(PrintFilesHandler  printFileHandler)
            

安装当要求应用程序打印文件列表时通知的处理程序。

实现注意事项：

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

参数：

printFileHandler - 处理程序

抛出：

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

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

自从：

9

setOpenURIHandler

public void setOpenURIHandler(OpenURIHandler  openURIHandler)
            

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

实现注意事项：

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

参数：

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

抛出：

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

自从：

9

setQuitHandler

public void setQuitHandler(QuitHandler  quitHandler)
            

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

参数：

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

抛出：

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

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

自从：

9

setQuitStrategy

public void setQuitStrategy(QuitStrategy  strategy)
            

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

参数：

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

抛出：

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

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

自从：

9

参见：

• QuitStrategy

enableSuddenTermination

public void enableSuddenTermination()
            

使此应用程序能够突然终止。调用此方法以指示您的应用程序的状态已保存，并且无需通知即可终止。让您的应用程序保持可终止状态可以避免在应用程序被要求退出时重新分页，从而改善用户体验。注意：启用突然终止将允许您的应用程序在不通知您的 QuitHandler 或运行任何关闭挂钩的情况下退出。例如，用户启动的 Cmd-Q、注销、重新启动或关闭请求将有效地“杀死-杀死”您的应用程序。

抛出：

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

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

自从：

9

参见：

• disableSuddenTermination()

disableSuddenTermination

public void disableSuddenTermination()
            

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

抛出：

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

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

自从：

9

参见：

• enableSuddenTermination()

requestForeground

public void requestForeground(boolean allWindows)
            

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

参数：

allWindows - 如果此应用程序的所有窗口都应移至前台，或仅移至最前面的窗口

抛出：

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

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

自从：

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