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.FullScreenListener;
34 import java.awt.desktop.SystemEventListener;
35 import java.awt.desktop.OpenFilesHandler;
36 import java.awt.desktop.OpenURIHandler;
37 import java.awt.desktop.PreferencesHandler;
38 import java.awt.desktop.PrintFilesHandler;
39 import java.awt.desktop.QuitHandler;
40 import java.awt.desktop.QuitStrategy;
41 import javax.swing.JMenuBar;
42 import javax.swing.RootPaneContainer;
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 */
52 public 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</code> 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</code> reverts it to
165 * the default behavior
166 *
167 * @param preferencesHandler the handler to respond to the
168 * {@link 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</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.
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 * Attaches a {@link FullScreenListener} to the specified top-level
265 * {@link Window}.
266 *
267 * @param window to attach the {@link FullScreenListener} to
268 * @param listener to be notified when a full screen event occurs
269 * @throws IllegalArgumentException if window is not a
270 * {@link RootPaneContainer}
271 */
272 default void addWindowFullScreenListener(final Window window,
273 final FullScreenListener listener) {
274 }
275
276 /**
277 * Removes a {@link FullScreenListener} from the specified top-level
278 * {@link Window}.
279 *
280 * @param window to remove the {@link FullScreenListener} from
281 * @param listener to be removed
282 * @throws IllegalArgumentException if window is not a
283 * {@link RootPaneContainer}
284 */
285 default void removeWindowFullScreenListener(final Window window,
286 final FullScreenListener listener) {
287 }
288
289 /**
290 * Marks a {@link Window} as able to animate into or out of full screen
291 * mode.
292 *
293 * @param window window
294 * @param canFullScreen flag
295 * @throws IllegalArgumentException if window is not a
296 * {@link RootPaneContainer}
297 *
298 * @see java.awt.Desktop#setWindowCanFullScreen(java.awt.Window, boolean)
299 */
300 default void setWindowCanFullScreen(final Window window,
301 final boolean canFullScreen) {
302 }
303
304 /**
305 * Requests that a {@link Window} should get into or out of full screen
306 * mode. Only {@link Window}s marked as full screenable by
307 * {@link #setWindowCanFullScreen(Window, boolean)} can be toggled.
308 *
309 * @param window to animate into or out of full screen mode
310 */
311 default void requestToggleFullScreen(final Window window) {
312 }
313
314 /**
315 * Opens a folder containing the {@code file} in a default system file manager.
316 * @param file the file
317 * @return returns true if successfully opened
318 */
319 default boolean browseFileDirectory(File file) {
320 return false;
321 }
322 /**
323 * Moves the specified file to the trash.
324 *
325 * @param file the file
326 * @return returns true if successfully moved the file to the trash.
327 */
328 default boolean moveToTrash(File file) {
329 return false;
330 }
331
332 }