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.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 
  64     /**
  65      * Launches the associated application to open the given file. The
  66      * associated application is registered to be the default file viewer for
  67      * the file type of the given file.
  68      *
  69      * @param file the given file.
  70      * @throws IOException If the given file has no associated application,
  71      *         or the associated application fails to be launched.
  72      */
  73     void open(File file) throws IOException;
  74 
  75     /**
  76      * Launches the associated editor and opens the given file for editing. The
  77      * associated editor is registered to be the default editor for the file
  78      * type of the given file.
  79      *
  80      * @param file the given file.
  81      * @throws IOException If the given file has no associated editor, or
  82      *         the associated application fails to be launched.
  83      */
  84     void edit(File file) throws IOException;
  85 
  86     /**
  87      * Prints the given file with the native desktop printing facility, using
  88      * the associated application's print command.
  89      *
  90      * @param file the given file.
  91      * @throws IOException If the given file has no associated application
  92      *         that can be used to print it.
  93      */
  94     void print(File file) throws IOException;
  95 
  96     /**
  97      * Launches the mail composing window of the user default mail client,
  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 }