1/*
2 * Copyright (c) 2005, 2017, 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 */
25package java.awt.peer;
26
27import java.awt.Desktop.Action;
28import java.awt.desktop.AboutHandler;
29import java.awt.desktop.OpenFilesHandler;
30import java.awt.desktop.OpenURIEvent;
31import java.awt.desktop.OpenURIHandler;
32import java.awt.desktop.PreferencesEvent;
33import java.awt.desktop.PreferencesHandler;
34import java.awt.desktop.PrintFilesHandler;
35import java.awt.desktop.QuitHandler;
36import java.awt.desktop.QuitStrategy;
37import java.awt.desktop.SystemEventListener;
38import java.io.File;
39import java.io.IOException;
40import java.net.URI;
41
42import javax.swing.JMenuBar;
43
44/**
45 * The {@code DesktopPeer} interface provides methods for the operation
46 * of open, edit, print, browse and mail with the given URL or file, by
47 * launching the associated application.
48 * <p>
49 * Each platform has an implementation class for this interface.
50 *
51 */
52public interface DesktopPeer {
53
54    /**
55     * Returns whether the given action is supported on the current platform.
56     * @param action the action type to be tested if it's supported on the
57     *        current platform.
58     * @return {@code true} if the given action is supported on
59     *         the current platform; {@code false} otherwise.
60     */
61    boolean isSupported(Action action);
62
63    /**
64     * Launches the associated application to open the given file. The
65     * associated application is registered to be the default file viewer for
66     * the file type of the given file.
67     *
68     * @param file the given file.
69     * @throws IOException If the given file has no associated application,
70     *         or the associated application fails to be launched.
71     */
72    void open(File file) throws IOException;
73
74    /**
75     * Launches the associated editor and opens the given file for editing. The
76     * associated editor is registered to be the default editor for the file
77     * type of the given file.
78     *
79     * @param file the given file.
80     * @throws IOException If the given file has no associated editor, or
81     *         the associated application fails to be launched.
82     */
83    void edit(File file) throws IOException;
84
85    /**
86     * Prints the given file with the native desktop printing facility, using
87     * the associated application's print command.
88     *
89     * @param file the given file.
90     * @throws IOException If the given file has no associated application
91     *         that can be used to print it.
92     */
93    void print(File file) throws IOException;
94
95    /**
96     * Launches the mail composing window of the user default mail client,
97     * filling the message fields including to, cc, etc, with the values
98     * specified by the given mailto URL.
99     *
100     * @param mailtoURL represents a mailto URL with specified values of the message.
101     *        The syntax of mailto URL is defined by
102     *        <a href="http://www.ietf.org/rfc/rfc2368.txt">RFC2368: The mailto
103     *        URL scheme</a>
104     * @throws IOException If the user default mail client is not found,
105     *         or it fails to be launched.
106     */
107    void mail(URI mailtoURL) throws IOException;
108
109    /**
110     * Launches the user default browser to display the given URI.
111     *
112     * @param uri the given URI.
113     * @throws IOException If the user default browser is not found,
114     *         or it fails to be launched.
115     */
116    void browse(URI uri) throws IOException;
117
118    /**
119     * Adds sub-types of {@link SystemEventListener} to listen for notifications
120     * from the native system.
121     *
122     * @param listener listener
123     * @see java.awt.desktop.AppForegroundListener
124     * @see java.awt.desktop.AppHiddenListener
125     * @see java.awt.desktop.AppReopenedListener
126     * @see java.awt.desktop.ScreenSleepListener
127     * @see java.awt.desktop.SystemSleepListener
128     * @see java.awt.desktop.UserSessionListener
129     */
130    default void addAppEventListener(final SystemEventListener listener) {
131    }
132
133    /**
134     * Removes sub-types of {@link SystemEventListener} to listen for notifications
135     * from the native system.
136     *
137     * @param listener listener
138     * @see java.awt.desktop.AppForegroundListener
139     * @see java.awt.desktop.AppHiddenListener
140     * @see java.awt.desktop.AppReopenedListener
141     * @see java.awt.desktop.ScreenSleepListener
142     * @see java.awt.desktop.SystemSleepListener
143     * @see java.awt.desktop.UserSessionListener
144     */
145    default void removeAppEventListener(final SystemEventListener listener) {
146    }
147
148    /**
149     * Installs a handler to show a custom About window for your application.
150     * <p>
151     * Setting the {@link AboutHandler} to {@code null} reverts it to the
152     * default behavior.
153     *
154     * @param aboutHandler the handler to respond to the
155     * {@link AboutHandler#handleAbout} )} message
156     */
157    default void setAboutHandler(final AboutHandler aboutHandler) {
158    }
159
160    /**
161     * Installs a handler to show a custom Preferences window for your
162     * application.
163     * <p>
164     * Setting the {@link PreferencesHandler} to {@code null} reverts it to
165     * the default behavior
166     *
167     * @param preferencesHandler the handler to respond to the
168     * {@link java.awt.desktop.PreferencesHandler#handlePreferences(PreferencesEvent) }
169     */
170    default void setPreferencesHandler(final PreferencesHandler preferencesHandler) {
171    }
172
173    /**
174     * Installs the handler which is notified when the application is asked to
175     * open a list of files.
176     *
177     * @param openFileHandler handler
178     *
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} causes all
197     * {@link OpenURIHandler#openURI(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.
207     *
208     * @param quitHandler the handler that is called when the application is
209     * asked to quit
210     * @see java.awt.Desktop#setQuitHandler(java.awt.desktop.QuitHandler)
211     */
212    default void setQuitHandler(final QuitHandler quitHandler) {
213    }
214
215    /**
216     * Sets the default strategy used to quit this application. The default is
217     * calling SYSTEM_EXIT_0.
218     *
219     * @param strategy the way this application should be shutdown
220     */
221    default void setQuitStrategy(final QuitStrategy strategy) {
222    }
223
224    /**
225     * Enables this application to be suddenly terminated.
226     *
227     * @see java.awt.Desktop#disableSuddenTermination()
228     */
229    default void enableSuddenTermination() {
230    }
231
232   /**
233     * Prevents this application from being suddenly terminated.
234     *
235     * @see java.awt.Desktop#enableSuddenTermination()
236     */
237    default void disableSuddenTermination() {
238    }
239
240    /**
241     * Requests this application to move to the foreground.
242     *
243     * @param allWindows if all windows of this application should be moved to
244     * the foreground, or only the foremost one
245     */
246    default void requestForeground(final boolean allWindows) {
247    }
248
249    /**
250     * Opens the native help viewer application.
251     */
252    default void openHelpViewer() {
253    }
254
255    /**
256     * Sets the default menu bar to use when there are no active frames.
257     *
258     * @param menuBar to use when no other frames are active
259     */
260    default void setDefaultMenuBar(final JMenuBar menuBar) {
261    }
262
263    /**
264     * Opens a folder containing the {@code file} in a default system file manager.
265     * @param file the file
266     * @return returns true if successfully opened
267     */
268    default boolean browseFileDirectory(File file) {
269        return false;
270    }
271    /**
272     * Moves the specified file to the trash.
273     *
274     * @param file the file
275     * @return returns true if successfully moved the file to the trash.
276     */
277    default boolean moveToTrash(File file) {
278        return false;
279    }
280
281}
282