- java.lang.Object
-
- java.awt.Desktop
-
public class Desktop extends Object
TheDesktop
class allows a Java application to launch associated applications registered on the native desktop to handle aURI
or a file.Supported operations include:
- launching the user-default browser to show a specified URI;
- launching the user-default mail client with an optional
mailto
URI; - launching a registered application to open, edit or print a specified file.
This class provides methods corresponding to these 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.
An application is registered to a URI or file type; for example, the
"sxi"
file extension is typically registered to StarOffice. The mechanism of registering, accessing, and launching the associated application is platform-dependent.Each operation is an action type represented by the
Desktop.Action
class.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.
- Since:
- 1.6
-
-
Nested Class Summary
Nested Classes Modifier and Type Class and Description static class
Desktop.Action
Represents an action type.
-
Method Summary
Methods Modifier and Type Method and Description void
browse(URI uri)
Launches the default browser to display aURI
.void
edit(File file)
Launches the associated editor application and opens a file for editing.static Desktop
getDesktop()
Returns theDesktop
instance of the current browser context.static boolean
isDesktopSupported()
Tests whether this class is supported on the current platform.boolean
isSupported(Desktop.Action action)
Tests whether an action is supported on the current platform.void
mail()
Launches the mail composing window of the user default mail client.void
mail(URI mailtoURI)
Launches the mail composing window of the user default mail client, filling the message fields specified by amailto:
URI.void
open(File file)
Launches the associated application to open the file.void
print(File file)
Prints a file with the native desktop printing facility, using the associated application's print command.
-
-
-
Method Detail
-
getDesktop
public static Desktop getDesktop()
Returns theDesktop
instance of the current browser context. On some platforms the Desktop API may not be supported; use theisDesktopSupported()
method to determine if the current desktop is supported.- Returns:
- the Desktop instance of the current browser context
- Throws:
HeadlessException
- ifGraphicsEnvironment.isHeadless()
returnstrue
UnsupportedOperationException
- if this class is not supported on the current platform- See Also:
isDesktopSupported()
,GraphicsEnvironment.isHeadless()
-
isDesktopSupported
public static boolean isDesktopSupported()
Tests whether this class is supported on the current platform. If it's supported, usegetDesktop()
to retrieve an instance.- Returns:
true
if this class is supported on the current platform;false
otherwise- See Also:
getDesktop()
-
isSupported
public boolean isSupported(Desktop.Action action)
Tests whether an action is supported on the current platform.Even when the platform supports an action, a file or URI may not have a registered application for the action. For example, most of the platforms support the
Desktop.Action.OPEN
action. But for a specific file, there may not be an application registered to open it. In this case,isSupported(java.awt.Desktop.Action)
may returntrue
, but the corresponding action method will throw anIOException
.- Parameters:
action
- the specifiedDesktop.Action
- Returns:
true
if the specified action is supported on the current platform;false
otherwise- See Also:
Desktop.Action
-
open
public void open(File file) throws IOException
Launches the associated application to open the file.If the specified file is a directory, the file manager of the current platform is launched to open it.
- Parameters:
file
- the file to be opened with the associated application- Throws:
NullPointerException
- iffile
isnull
IllegalArgumentException
- if the specified file doesn't existUnsupportedOperationException
- if the current platform does not support theDesktop.Action.OPEN
actionIOException
- if the specified file has no associated application or the associated application fails to be launchedSecurityException
- if a security manager exists and itsSecurityManager.checkRead(java.lang.String)
method denies read access to the file, or it denies theAWTPermission("showWindowWithoutWarningBanner")
permission, or the calling thread is not allowed to create a subprocess- See Also:
AWTPermission
-
edit
public void edit(File file) throws IOException
Launches the associated editor application and opens a file for editing.- Parameters:
file
- the file to be opened for editing- Throws:
NullPointerException
- if the specified file isnull
IllegalArgumentException
- if the specified file doesn't existUnsupportedOperationException
- if the current platform does not support theDesktop.Action.EDIT
actionIOException
- if the specified file has no associated editor, or the associated application fails to be launchedSecurityException
- if a security manager exists and itsSecurityManager.checkRead(java.lang.String)
method denies read access to the file, orSecurityManager.checkWrite(java.lang.String)
method denies write access to the file, or it denies theAWTPermission("showWindowWithoutWarningBanner")
permission, or the calling thread is not allowed to create a subprocess- See Also:
AWTPermission
-
print
public void print(File file) throws IOException
Prints a file with the native desktop printing facility, using the associated application's print command.- Parameters:
file
- the file to be printed- Throws:
NullPointerException
- if the specified file isnull
IllegalArgumentException
- if the specified file doesn't existUnsupportedOperationException
- if the current platform does not support theDesktop.Action.PRINT
actionIOException
- if the specified file has no associated application that can be used to print itSecurityException
- if a security manager exists and itsSecurityManager.checkRead(java.lang.String)
method denies read access to the file, or itsSecurityManager.checkPrintJobAccess()
method denies the permission to print the file, or the calling thread is not allowed to create a subprocess
-
browse
public void browse(URI uri) throws IOException
Launches the default browser to display aURI
. If the default browser is not able to handle the specifiedURI
, the application registered for handlingURIs
of the specified type is invoked. The application is determined from the protocol and path of theURI
, as defined by theURI
class.If the calling thread does not have the necessary permissions, and this is invoked from within an applet,
AppletContext.showDocument()
is used. Similarly, if the calling does not have the necessary permissions, and this is invoked from within a Java Web Started application,BasicService.showDocument()
is used.- Parameters:
uri
- the URI to be displayed in the user default browser- Throws:
NullPointerException
- ifuri
isnull
UnsupportedOperationException
- if the current platform does not support theDesktop.Action.BROWSE
actionIOException
- if the user default browser is not found, or it fails to be launched, or the default handler application failed to be launchedSecurityException
- if a security manager exists and it denies theAWTPermission("showWindowWithoutWarningBanner")
permission, or the calling thread is not allowed to create a subprocess; and not invoked from within an applet or Java Web Started applicationIllegalArgumentException
- if the necessary permissions are not available and the URI can not be converted to aURL
- See Also:
URI
,AWTPermission
,AppletContext
-
mail
public void mail() throws IOException
Launches the mail composing window of the user default mail client.- Throws:
UnsupportedOperationException
- if the current platform does not support theDesktop.Action.MAIL
actionIOException
- if the user default mail client is not found, or it fails to be launchedSecurityException
- if a security manager exists and it denies theAWTPermission("showWindowWithoutWarningBanner")
permission, or the calling thread is not allowed to create a subprocess- See Also:
AWTPermission
-
mail
public void mail(URI mailtoURI) throws IOException
Launches the mail composing window of the user default mail client, filling the message fields specified by amailto:
URI.A
mailto:
URI can specify message fields including "to", "cc", "subject", "body", etc. See The mailto URL scheme (RFC 2368) for themailto:
URI specification details.- Parameters:
mailtoURI
- the specifiedmailto:
URI- Throws:
NullPointerException
- if the specified URI isnull
IllegalArgumentException
- if the URI scheme is not"mailto"
UnsupportedOperationException
- if the current platform does not support theDesktop.Action.MAIL
actionIOException
- if the user default mail client is not found or fails to be launchedSecurityException
- if a security manager exists and it denies theAWTPermission("showWindowWithoutWarningBanner")
permission, or the calling thread is not allowed to create a subprocess- See Also:
URI
,AWTPermission
-
-
Traduction non disponible
Les API Java ne sont pas encore traduites en français sur l'infobrol. Seule la version anglaise est disponible pour l'instant.
Version en cache
05/11/2024 17:41:08 Cette version de la page est en cache (à la date du 05/11/2024 17:41:08) afin d'accélérer le traitement. Vous pouvez activer le mode utilisateur dans le menu en haut pour afficher la dernère version de la page.Document créé le 11/06/2005, dernière modification le 04/03/2020
Source du document imprimé : https://www.gaudry.be/java-api-rf-java/awt/desktop.html
L'infobrol est un site personnel dont le contenu n'engage que moi. Le texte est mis à disposition sous licence CreativeCommons(BY-NC-SA). Plus d'info sur les conditions d'utilisation et sur l'auteur.
Références
Ces références et liens indiquent des documents consultés lors de la rédaction de cette page, ou qui peuvent apporter un complément d'information, mais les auteurs de ces sources ne peuvent être tenus responsables du contenu de cette page.
L'auteur de ce site est seul responsable de la manière dont sont présentés ici les différents concepts, et des libertés qui sont prises avec les ouvrages de référence. N'oubliez pas que vous devez croiser les informations de sources multiples afin de diminuer les risques d'erreurs.