1 /*
   2  * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package java.awt.peer;
  26 
  27 import java.io.File;
  28 import java.io.IOException;
  29 import java.net.URI;
  30 import java.awt.Desktop.Action;
  31 import java.awt.desktop.AboutHandler;
  32 import java.awt.desktop.SystemEventListener;
  33 import java.awt.desktop.OpenFilesHandler;
  34 import java.awt.desktop.OpenURIHandler;
  35 import java.awt.desktop.PreferencesHandler;
  36 import java.awt.desktop.PrintFilesHandler;
  37 import java.awt.desktop.QuitHandler;
  38 import java.awt.desktop.QuitStrategy;
  39 import javax.swing.JMenuBar;
  40 
  41 /**
  42  * The {@code DesktopPeer} interface provides methods for the operation
  43  * of open, edit, print, browse and mail with the given URL or file, by
  44  * launching the associated application.
  45  * <p>
  46  * Each platform has an implementation class for this interface.
  47  *
  48  */
  49 public interface DesktopPeer {
  50 
  51     /**
  52      * Returns whether the given action is supported on the current platform.
  53      * @param action the action type to be tested if it's supported on the
  54      *        current platform.
  55      * @return {@code true} if the given action is supported on
  56      *         the current platform; {@code false} otherwise.
  57      */
  58     boolean isSupported(Action action);
  59 
  60     /**
  61      * Launches the associated application to open the given file. The
  62      * associated application is registered to be the default file viewer for
  63      * the file type of the given file.
  64      *
  65      * @param file the given file.
  66      * @throws IOException If the given file has no associated application,
  67      *         or the associated application fails to be launched.
  68      */
  69     void open(File file) throws IOException;
  70 
  71     /**
  72      * Launches the associated editor and opens the given file for editing. The
  73      * associated editor is registered to be the default editor for the file
  74      * type of the given file.
  75      *
  76      * @param file the given file.
  77      * @throws IOException If the given file has no associated editor, or
  78      *         the associated application fails to be launched.
  79      */
  80     void edit(File file) throws IOException;
  81 
  82     /**
  83      * Prints the given file with the native desktop printing facility, using
  84      * the associated application's print command.
  85      *
  86      * @param file the given file.
  87      * @throws IOException If the given file has no associated application
  88      *         that can be used to print it.
  89      */
  90     void print(File file) throws IOException;
  91 
  92     /**
  93      * Launches the mail composing window of the user default mail client,
  94      * filling the message fields including to, cc, etc, with the values
  95      * specified by the given mailto URL.
  96      *
  97      * @param mailtoURL represents a mailto URL with specified values of the message.
  98      *        The syntax of mailto URL is defined by
  99      *        <a href="http://www.ietf.org/rfc/rfc2368.txt">RFC2368: The mailto
 100      *        URL scheme</a>
 101      * @throws IOException If the user default mail client is not found,
 102      *         or it fails to be launched.
 103      */
 104     void mail(URI mailtoURL) throws IOException;
 105 
 106     /**
 107      * Launches the user default browser to display the given URI.
 108      *
 109      * @param uri the given URI.
 110      * @throws IOException If the user default browser is not found,
 111      *         or it fails to be launched.
 112      */
 113     void browse(URI uri) throws IOException;
 114 
 115     /**
 116      * Adds sub-types of {@link SystemEventListener} to listen for notifications
 117      * from the native system.
 118      *
 119      * @param listener listener
 120      * @see java.awt.desktop.AppForegroundListener
 121      * @see java.awt.desktop.AppHiddenListener
 122      * @see java.awt.desktop.AppReopenedListener
 123      * @see java.awt.desktop.ScreenSleepListener
 124      * @see java.awt.desktop.SystemSleepListener
 125      * @see java.awt.desktop.UserSessionListener
 126      */
 127     default void addAppEventListener(final SystemEventListener listener) {
 128     }
 129 
 130     /**
 131      * Removes sub-types of {@link SystemEventListener} to listen for notifications
 132      * from the native system.
 133      *
 134      * @param listener listener
 135      * @see java.awt.desktop.AppForegroundListener
 136      * @see java.awt.desktop.AppHiddenListener
 137      * @see java.awt.desktop.AppReopenedListener
 138      * @see java.awt.desktop.ScreenSleepListener
 139      * @see java.awt.desktop.SystemSleepListener
 140      * @see java.awt.desktop.UserSessionListener
 141      */
 142     default void removeAppEventListener(final SystemEventListener listener) {
 143     }
 144 
 145     /**
 146      * Installs a handler to show a custom About window for your application.
 147      * <p>
 148      * Setting the {@link AboutHandler} to {@code null} reverts it to the
 149      * default behavior.
 150      *
 151      * @param aboutHandler the handler to respond to the
 152      * {@link AboutHandler#handleAbout} )} message
 153      */
 154     default void setAboutHandler(final AboutHandler aboutHandler) {
 155     }
 156 
 157     /**
 158      * Installs a handler to show a custom Preferences window for your
 159      * application.
 160      * <p>
 161      * Setting the {@link PreferencesHandler} to {@code null} reverts it to
 162      * the default behavior
 163      *
 164      * @param preferencesHandler the handler to respond to the
 165      * {@link java.awt.desktop.PreferencesHandler#handlePreferences(java.awt.PreferencesEvent) }
 166      */
 167     default void setPreferencesHandler(final PreferencesHandler preferencesHandler) {
 168     }
 169 
 170     /**
 171      * Installs the handler which is notified when the application is asked to
 172      * open a list of files.
 173      *
 174      * @param openFileHandler handler
 175      *
 176      */
 177     default void setOpenFileHandler(final OpenFilesHandler openFileHandler) {
 178     }
 179 
 180     /**
 181      * Installs the handler which is notified when the application is asked to
 182      * print a list of files.
 183      *
 184      * @param printFileHandler handler
 185      */
 186     default void setPrintFileHandler(final PrintFilesHandler printFileHandler) {
 187     }
 188 
 189     /**
 190      * Installs the handler which is notified when the application is asked to
 191      * open a URL.
 192      *
 193      * Setting the handler to {@code null} causes all
 194      * {@link OpenURIHandler#openURI(AppEvent.OpenURIEvent)} requests to be
 195      * enqueued until another handler is set.
 196      *
 197      * @param openURIHandler handler
 198      */
 199     default void setOpenURIHandler(final OpenURIHandler openURIHandler) {
 200     }
 201 
 202     /**
 203      * Installs the handler which determines if the application should quit.
 204      *
 205      * @param quitHandler the handler that is called when the application is
 206      * asked to quit
 207      * @see java.awt.Desktop#setQuitHandler(java.awt.desktop.QuitHandler)
 208      */
 209     default void setQuitHandler(final QuitHandler quitHandler) {
 210     }
 211 
 212     /**
 213      * Sets the default strategy used to quit this application. The default is
 214      * calling SYSTEM_EXIT_0.
 215      *
 216      * @param strategy the way this application should be shutdown
 217      */
 218     default void setQuitStrategy(final QuitStrategy strategy) {
 219     }
 220 
 221     /**
 222      * Enables this application to be suddenly terminated.
 223      *
 224      * @see java.awt.Desktop#disableSuddenTermination()
 225      */
 226     default void enableSuddenTermination() {
 227     }
 228 
 229    /**
 230      * Prevents this application from being suddenly terminated.
 231      *
 232      * @see java.awt.Desktop#enableSuddenTermination()
 233      */
 234     default void disableSuddenTermination() {
 235     }
 236 
 237     /**
 238      * Requests this application to move to the foreground.
 239      *
 240      * @param allWindows if all windows of this application should be moved to
 241      * the foreground, or only the foremost one
 242      */
 243     default void requestForeground(final boolean allWindows) {
 244     }
 245 
 246     /**
 247      * Opens the native help viewer application.
 248      */
 249     default void openHelpViewer() {
 250     }
 251 
 252     /**
 253      * Sets the default menu bar to use when there are no active frames.
 254      *
 255      * @param menuBar to use when no other frames are active
 256      */
 257     default void setDefaultMenuBar(final JMenuBar menuBar) {
 258     }
 259 
 260     /**
 261      * Opens a folder containing the {@code file} in a default system file manager.
 262      * @param file the file
 263      * @return returns true if successfully opened
 264      */
 265     default boolean browseFileDirectory(File file) {
 266         return false;
 267     }
 268     /**
 269      * Moves the specified file to the trash.
 270      *
 271      * @param file the file
 272      * @return returns true if successfully moved the file to the trash.
 273      */
 274     default boolean moveToTrash(File file) {
 275         return false;
 276     }
 277 
 278 }