1 /* 2 * Copyright (c) 2005, 2013, 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</code> 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</code> 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.AppEvent.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</code> 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 }