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 26 package java.awt.peer; 27 28 29 import java.io.File; 30 import java.io.IOException; 31 import java.net.URI; 32 import java.awt.Desktop.Action; 33 34 /** 35 * The {@code DesktopPeer} interface provides methods for the operation 36 * of open, edit, print, browse and mail with the given URL or file, by 37 * launching the associated application. 38 * <p> 39 * Each platform has an implementation class for this interface. 40 * 41 */ 42 public interface DesktopPeer { 43 44 /** 45 * Returns whether the given action is supported on the current platform. 46 * @param action the action type to be tested if it's supported on the 47 * current platform. 48 * @return {@code true} if the given action is supported on 49 * the current platform; {@code false} otherwise. 50 */ 51 boolean isSupported(Action action); 52 87 * filling the message fields including to, cc, etc, with the values 88 * specified by the given mailto URL. 89 * 90 * @param mailtoURL represents a mailto URL with specified values of the message. 91 * The syntax of mailto URL is defined by 92 * <a href="http://www.ietf.org/rfc/rfc2368.txt">RFC2368: The mailto 93 * URL scheme</a> 94 * @throws IOException If the user default mail client is not found, 95 * or it fails to be launched. 96 */ 97 void mail(URI mailtoURL) throws IOException; 98 99 /** 100 * Launches the user default browser to display the given URI. 101 * 102 * @param uri the given URI. 103 * @throws IOException If the user default browser is not found, 104 * or it fails to be launched. 105 */ 106 void browse(URI uri) throws IOException; 107 } | 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.Window; 32 import java.awt.desktop.AboutHandler; 33 import java.awt.desktop.FileManager; 34 import java.awt.desktop.FullScreenListener; 35 import java.awt.desktop.SystemEventListener; 36 import java.awt.desktop.OpenFilesHandler; 37 import java.awt.desktop.OpenURIHandler; 38 import java.awt.desktop.PreferencesHandler; 39 import java.awt.desktop.PrintFilesHandler; 40 import java.awt.desktop.QuitHandler; 41 import java.awt.desktop.QuitStrategy; 42 import javax.swing.JMenuBar; 43 import javax.swing.RootPaneContainer; 44 45 /** 46 * The {@code DesktopPeer} interface provides methods for the operation 47 * of open, edit, print, browse and mail with the given URL or file, by 48 * launching the associated application. 49 * <p> 50 * Each platform has an implementation class for this interface. 51 * 52 */ 53 public interface DesktopPeer { 54 55 /** 56 * Returns whether the given action is supported on the current platform. 57 * @param action the action type to be tested if it's supported on the 58 * current platform. 59 * @return {@code true} if the given action is supported on 60 * the current platform; {@code false} otherwise. 61 */ 62 boolean isSupported(Action action); 63 98 * filling the message fields including to, cc, etc, with the values 99 * specified by the given mailto URL. 100 * 101 * @param mailtoURL represents a mailto URL with specified values of the message. 102 * The syntax of mailto URL is defined by 103 * <a href="http://www.ietf.org/rfc/rfc2368.txt">RFC2368: The mailto 104 * URL scheme</a> 105 * @throws IOException If the user default mail client is not found, 106 * or it fails to be launched. 107 */ 108 void mail(URI mailtoURL) throws IOException; 109 110 /** 111 * Launches the user default browser to display the given URI. 112 * 113 * @param uri the given URI. 114 * @throws IOException If the user default browser is not found, 115 * or it fails to be launched. 116 */ 117 void browse(URI uri) throws IOException; 118 119 /** 120 * Adds sub-types of {@link SystemEventListener} to listen for notifications 121 * from the native system. 122 * 123 * @param listener listener 124 * @see java.awt.desktop.AppForegroundListener 125 * @see java.awt.desktop.AppHiddenListener 126 * @see java.awt.desktop.AppReopenedListener 127 * @see java.awt.desktop.ScreenSleepListener 128 * @see java.awt.desktop.SystemSleepListener 129 * @see java.awt.desktop.UserSessionListener 130 */ 131 default void addAppEventListener(final SystemEventListener listener) { 132 } 133 134 /** 135 * Removes sub-types of {@link SystemEventListener} to listen for notifications 136 * from the native system. 137 * 138 * @param listener listener 139 * @see java.awt.desktop.AppForegroundListener 140 * @see java.awt.desktop.AppHiddenListener 141 * @see java.awt.desktop.AppReopenedListener 142 * @see java.awt.desktop.ScreenSleepListener 143 * @see java.awt.desktop.SystemSleepListener 144 * @see java.awt.desktop.UserSessionListener 145 */ 146 default void removeAppEventListener(final SystemEventListener listener) { 147 } 148 149 /** 150 * Installs a handler to show a custom About window for your application. 151 * <p> 152 * Setting the {@link AboutHandler} to <code>null</code> reverts it to the 153 * default behavior. 154 * 155 * @param aboutHandler the handler to respond to the 156 * {@link AboutHandler#handleAbout} )} message 157 */ 158 default void setAboutHandler(final AboutHandler aboutHandler) { 159 } 160 161 /** 162 * Installs a handler to show a custom Preferences window for your 163 * application. 164 * <p> 165 * Setting the {@link PreferencesHandler} to <code>null</code> reverts it to 166 * the default behavior 167 * 168 * @param preferencesHandler the handler to respond to the 169 * {@link PreferencesHandler#handlePreferences(PreferencesEvent)} 170 */ 171 default void setPreferencesHandler(final PreferencesHandler preferencesHandler) { 172 } 173 174 /** 175 * Installs the handler which is notified when the application is asked to 176 * open a list of files. 177 * 178 * @param openFileHandler handler 179 */ 180 default void setOpenFileHandler(final OpenFilesHandler openFileHandler) { 181 } 182 183 /** 184 * Installs the handler which is notified when the application is asked to 185 * print a list of files. 186 * 187 * @param printFileHandler handler 188 */ 189 default void setPrintFileHandler(final PrintFilesHandler printFileHandler) { 190 } 191 192 /** 193 * Installs the handler which is notified when the application is asked to 194 * open a URL. 195 * 196 * Setting the handler to <code>null</code> causes all 197 * {@link OpenURIHandler#openURI(AppEvent.OpenURIEvent)} requests to be 198 * enqueued until another handler is set. 199 * 200 * @param openURIHandler handler 201 */ 202 default void setOpenURIHandler(final OpenURIHandler openURIHandler) { 203 } 204 205 /** 206 * Installs the handler which determines if the application should quit. The 207 * handler is passed a one-shot {@link QuitResponse} which can cancel or 208 * proceed with the quit. Setting the handler to <code>null</code> causes 209 * all quit requests to directly perform the default {@link QuitStrategy}. 210 * 211 * @param quitHandler the handler that is called when the application is 212 * asked to quit 213 */ 214 default void setQuitHandler(final QuitHandler quitHandler) { 215 } 216 217 /** 218 * Sets the default strategy used to quit this application. The default is 219 * calling SYSTEM_EXIT_0. 220 * 221 * @param strategy the way this application should be shutdown 222 */ 223 default void setQuitStrategy(final QuitStrategy strategy) { 224 } 225 226 /** 227 * Enables this application to be suddenly terminated. 228 * 229 * Call this method to indicate your application's state is saved, and 230 * requires no notification to be terminated. Letting your application 231 * remain terminatable improves the user experience by avoiding re-paging in 232 * your application when it's asked to quit. 233 * 234 * <b>Note: enabling sudden termination will allow your application to be 235 * quit without notifying your QuitHandler, or running any shutdown 236 * hooks.</b> 237 * E.g. user initiated Cmd-Q, logout, restart, or shutdown requests will 238 * effectively "kill -KILL" your application. 239 * 240 * @see #disableSuddenTermination() 241 */ 242 default void enableSuddenTermination() { 243 } 244 245 /** 246 * Prevents this application from being suddenly terminated. 247 * 248 * Call this method to indicate that your application has unsaved state, and 249 * may not be terminated without notification. 250 * 251 * @see #enableSuddenTermination() 252 */ 253 default void disableSuddenTermination() { 254 } 255 256 /** 257 * Requests this application to move to the foreground. 258 * 259 * @param allWindows if all windows of this application should be moved to 260 * the foreground, or only the foremost one 261 */ 262 default void requestForeground(final boolean allWindows) { 263 } 264 265 /** 266 * Opens the native help viewer application. 267 */ 268 default void openHelpViewer() { 269 } 270 271 /** 272 * Sets the default menu bar to use when there are no active frames. 273 * 274 * @param menuBar to use when no other frames are active 275 */ 276 default void setDefaultMenuBar(final JMenuBar menuBar) { 277 } 278 279 /** 280 * Attaches a {@link FullScreenListener} to the specified top-level 281 * {@link Window}. 282 * 283 * @param window to attach the {@link FullScreenListener} to 284 * @param listener to be notified when a full screen event occurs 285 * @throws IllegalArgumentException if window is not a 286 * {@link RootPaneContainer} 287 */ 288 default void addWindowFullScreenListener(final Window window, 289 final FullScreenListener listener) { 290 } 291 292 /** 293 * Removes a {@link FullScreenListener} from the specified top-level 294 * {@link Window}. 295 * 296 * @param window to remove the {@link FullScreenListener} from 297 * @param listener to be removed 298 * @throws IllegalArgumentException if window is not a 299 * {@link RootPaneContainer} 300 */ 301 default void removeWindowFullScreenListener(final Window window, 302 final FullScreenListener listener) { 303 } 304 305 /** 306 * Marks a {@link Window} as able to animate into or out of full screen 307 * mode. 308 * 309 * Only top-level {@link Window}s which are {@link RootPaneContainer}s are 310 * able to be animated into and out of full screen mode. The {@link Window} 311 * must be marked as full screen-able before the native peer is created with 312 * {@link Component#addNotify()}. 313 * 314 * @param window window 315 * @param canFullScreen flag 316 * @throws IllegalArgumentException if window is not a 317 * {@link RootPaneContainer} 318 */ 319 default void setWindowCanFullScreen(final Window window, 320 final boolean canFullScreen) { 321 } 322 323 /** 324 * Requests that a {@link Window} should get into or out of full screen 325 * mode. Only {@link Window}s marked as full screenable by 326 * {@link #setWindowCanFullScreen(Window, boolean)} can be toggled. 327 * 328 * @param window to animate into or out of full screen mode 329 */ 330 default void requestToggleFullScreen(final Window window) { 331 } 332 333 /** 334 * Returns the Mac specific FileManager. 335 * @return FileManager 336 * @see FileManager 337 */ 338 default FileManager getFileManager() { 339 return null; 340 } 341 342 } |