1 /* 2 * Copyright (c) 2011, 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 26 package com.apple.eawt; 27 28 import java.awt.*; 29 import java.awt.peer.*; 30 import java.beans.Beans; 31 import java.security.PrivilegedAction; 32 33 import javax.swing.JMenuBar; 34 35 import sun.lwawt.*; 36 import sun.lwawt.macosx.*; 37 38 /** 39 * The <code>Application</code> class allows you to integrate your Java application with the native Mac OS X environment. 40 * You can provide your Mac OS X users a greatly enhanced experience by implementing a few basic handlers for standard system events. 41 * 42 * For example: 43 * <ul> 44 * <li>Open an about dialog when a user chooses About from the application menu.</li> 45 * <li>Open a preferences window when the users chooses Preferences from the application menu.</li> 46 * <li>Create a new document when the user clicks on your Dock icon, and no windows are open.</li> 47 * <li>Open a document that the user double-clicked on in the Finder.</li> 48 * <li>Open a custom URL scheme when a user clicks on link in a web browser.</li> 49 * <li>Reconnect to network services after the system has awoke from sleep.</li> 50 * <li>Cleanly shutdown your application when the user chooses Quit from the application menu, Dock icon, or types Command-Q.</li> 51 * <li>Cancel shutdown/logout if the user has unsaved changes in your application.</li> 52 * </ul> 53 * 54 * @since 1.4 55 */ 56 public class Application { 57 private static native void nativeInitializeApplicationDelegate(); 58 59 static Application sApplication = null; 60 61 static { 62 java.security.AccessController.doPrivileged((PrivilegedAction<?>)new sun.security.action.LoadLibraryAction("awt")); 63 64 checkSecurity(); 65 if (!Beans.isDesignTime()) { 66 nativeInitializeApplicationDelegate(); 67 } 68 69 sApplication = new Application(); 70 } 71 72 private static void checkSecurity() { 73 final SecurityManager security = System.getSecurityManager(); 74 if (security == null) return; 75 security.checkPermission(new RuntimePermission("canProcessApplicationEvents")); 76 } 77 78 /** 79 * @return the singleton representing this Mac OS X Application 80 * 81 * @since 1.4 82 */ 83 public static Application getApplication() { 84 checkSecurity(); 85 return sApplication; 86 } 87 88 // some singletons, since they get called back into from native 89 final _AppEventHandler eventHandler = _AppEventHandler.getInstance(); 90 final _AppMenuBarHandler menuBarHandler = _AppMenuBarHandler.getInstance(); 91 final _AppDockIconHandler iconHandler = new _AppDockIconHandler(); 92 93 /** 94 * Creates an Application instance. Should only be used in JavaBean environments. 95 * @deprecated use {@link #getApplication()} 96 * 97 * @since 1.4 98 */ 99 @Deprecated 100 public Application() { 101 checkSecurity(); 102 } 103 104 /** 105 * Adds sub-types of {@link AppEventListener} to listen for notifications from the native Mac OS X system. 106 * 107 * @see AppForegroundListener 108 * @see AppHiddenListener 109 * @see AppReOpenedListener 110 * @see ScreenSleepListener 111 * @see SystemSleepListener 112 * @see UserSessionListener 113 * 114 * @param listener 115 * @since Java for Mac OS X 10.6 Update 3 116 * @since Java for Mac OS X 10.5 Update 8 117 */ 118 public void addAppEventListener(final AppEventListener listener) { 119 eventHandler.addListener(listener); 120 } 121 122 /** 123 * Removes sub-types of {@link AppEventListener} from listening for notifications from the native Mac OS X system. 124 * 125 * @see AppForegroundListener 126 * @see AppHiddenListener 127 * @see AppReOpenedListener 128 * @see ScreenSleepListener 129 * @see SystemSleepListener 130 * @see UserSessionListener 131 * 132 * @param listener 133 * @since Java for Mac OS X 10.6 Update 3 134 * @since Java for Mac OS X 10.5 Update 8 135 */ 136 public void removeAppEventListener(final AppEventListener listener) { 137 eventHandler.removeListener(listener); 138 } 139 140 /** 141 * Installs a handler to show a custom About window for your application. 142 * 143 * Setting the {@link AboutHandler} to <code>null</code> reverts it to the default Cocoa About window. 144 * 145 * @param aboutHandler the handler to respond to the {@link AboutHandler#handleAbout()} message 146 * @since Java for Mac OS X 10.6 Update 3 147 * @since Java for Mac OS X 10.5 Update 8 148 */ 149 public void setAboutHandler(final AboutHandler aboutHandler) { 150 eventHandler.aboutDispatcher.setHandler(aboutHandler); 151 } 152 153 /** 154 * Installs a handler to create the Preferences menu item in your application's app menu. 155 * 156 * Setting the {@link PreferencesHandler} to <code>null</code> will remove the Preferences item from the app menu. 157 * 158 * @param preferencesHandler 159 * @since Java for Mac OS X 10.6 Update 3 160 * @since Java for Mac OS X 10.5 Update 8 161 */ 162 public void setPreferencesHandler(final PreferencesHandler preferencesHandler) { 163 eventHandler.preferencesDispatcher.setHandler(preferencesHandler); 164 } 165 166 /** 167 * Installs the handler which is notified when the application is asked to open a list of files. 168 * The {@link OpenFilesHandler#openFiles(AppEvent.OpenFilesEvent)} notifications are only sent if the Java app is a bundled application, with a <code>CFBundleDocumentTypes</code> array present in it's Info.plist. 169 * See the <a href="http://developer.apple.com/mac/library/documentation/General/Reference/InfoPlistKeyReference">Info.plist Key Reference</a> for more information about adding a <code>CFBundleDocumentTypes</code> key to your app's Info.plist. 170 * 171 * @param openFileHandler 172 * @since Java for Mac OS X 10.6 Update 3 173 * @since Java for Mac OS X 10.5 Update 8 174 */ 175 public void setOpenFileHandler(final OpenFilesHandler openFileHandler) { 176 eventHandler.openFilesDispatcher.setHandler(openFileHandler); 177 } 178 179 /** 180 * Installs the handler which is notified when the application is asked to print a list of files. 181 * The {@link PrintFilesHandler#printFiles(AppEvent.PrintFilesEvent)} notifications are only sent if the Java app is a bundled application, with a <code>CFBundleDocumentTypes</code> array present in it's Info.plist. 182 * See the <a href="http://developer.apple.com/mac/library/documentation/General/Reference/InfoPlistKeyReference">Info.plist Key Reference</a> for more information about adding a <code>CFBundleDocumentTypes</code> key to your app's Info.plist. 183 * 184 * @param printFileHandler 185 * @since Java for Mac OS X 10.6 Update 3 186 * @since Java for Mac OS X 10.5 Update 8 187 */ 188 public void setPrintFileHandler(final PrintFilesHandler printFileHandler) { 189 eventHandler.printFilesDispatcher.setHandler(printFileHandler); 190 } 191 192 /** 193 * Installs the handler which is notified when the application is asked to open a URL. 194 * The {@link OpenURIHandler#openURI(AppEvent.OpenURIEvent)} notifications are only sent if the Java app is a bundled application, with a <code>CFBundleURLTypes</code> array present in it's Info.plist. 195 * See the <a href="http://developer.apple.com/mac/library/documentation/General/Reference/InfoPlistKeyReference">Info.plist Key Reference</a> for more information about adding a <code>CFBundleURLTypes</code> key to your app's Info.plist. 196 * 197 * Setting the handler to <code>null</code> causes all {@link OpenURIHandler#openURI(AppEvent.OpenURIEvent)} requests to be enqueued until another handler is set. 198 * 199 * @param openURIHandler 200 * @since Java for Mac OS X 10.6 Update 3 201 * @since Java for Mac OS X 10.5 Update 8 202 */ 203 public void setOpenURIHandler(final OpenURIHandler openURIHandler) { 204 eventHandler.openURIDispatcher.setHandler(openURIHandler); 205 } 206 207 /** 208 * Installs the handler which determines if the application should quit. 209 * The handler is passed a one-shot {@link QuitResponse} which can cancel or proceed with the quit. 210 * Setting the handler to <code>null</code> causes all quit requests to directly perform the default {@link QuitStrategy}. 211 * 212 * @param quitHandler the handler that is called when the application is asked to quit 213 * @since Java for Mac OS X 10.6 Update 3 214 * @since Java for Mac OS X 10.5 Update 8 215 */ 216 public void setQuitHandler(final QuitHandler quitHandler) { 217 eventHandler.quitDispatcher.setHandler(quitHandler); 218 } 219 220 /** 221 * Sets the default strategy used to quit this application. The default is calling SYSTEM_EXIT_0. 222 * 223 * The quit strategy can also be set with the "apple.eawt.quitStrategy" system property. 224 * 225 * @param strategy the way this application should be shutdown 226 * @since Java for Mac OS X 10.6 Update 3 227 * @since Java for Mac OS X 10.5 Update 8 228 */ 229 public void setQuitStrategy(final QuitStrategy strategy) { 230 eventHandler.setDefaultQuitStrategy(strategy); 231 } 232 233 /** 234 * Enables this application to be suddenly terminated. 235 * 236 * Call this method to indicate your application's state is saved, and requires no notification to be terminated. 237 * Letting your application remain terminatable improves the user experience by avoiding re-paging in your application when it's asked to quit. 238 * 239 * <b>Note: enabling sudden termination will allow your application to be quit without notifying your QuitHandler, or running any shutdown hooks.</b> 240 * User initiated Cmd-Q, logout, restart, or shutdown requests will effectively "kill -KILL" your application. 241 * 242 * This call has no effect on Mac OS X versions prior to 10.6. 243 * 244 * @see <a href="http://developer.apple.com/mac/library/documentation/cocoa/reference/foundation/Classes/NSProcessInfo_Class">NSProcessInfo class references</a> for more information about Sudden Termination. 245 * @see Application#disableSuddenTermination() 246 * 247 * @since Java for Mac OS X 10.6 Update 3 248 * @since Java for Mac OS X 10.5 Update 8 249 */ 250 public void enableSuddenTermination() { 251 _AppMiscHandlers.enableSuddenTermination(); 252 } 253 254 /** 255 * Prevents this application from being suddenly terminated. 256 * 257 * Call this method to indicate that your application has unsaved state, and may not be terminated without notification. 258 * 259 * This call has no effect on Mac OS X versions prior to 10.6. 260 * 261 * @see <a href="http://developer.apple.com/mac/library/documentation/cocoa/reference/foundation/Classes/NSProcessInfo_Class">NSProcessInfo class references</a> for more information about Sudden Termination. 262 * @see Application#enableSuddenTermination() 263 * 264 * @since Java for Mac OS X 10.6 Update 3 265 * @since Java for Mac OS X 10.5 Update 8 266 */ 267 public void disableSuddenTermination() { 268 _AppMiscHandlers.disableSuddenTermination(); 269 } 270 271 /** 272 * Requests this application to move to the foreground. 273 * 274 * @param allWindows if all windows of this application should be moved to the foreground, or only the foremost one 275 * 276 * @since Java for Mac OS X 10.6 Update 1 277 * @since Java for Mac OS X 10.5 Update 6 - 1.6, 1.5 278 */ 279 public void requestForeground(final boolean allWindows) { 280 _AppMiscHandlers.requestActivation(allWindows); 281 } 282 283 /** 284 * Requests user attention to this application (usually through bouncing the Dock icon). Critical 285 * requests will continue to bounce the Dock icon until the app is activated. An already active 286 * application requesting attention does nothing. 287 * 288 * @param critical if this is an important request 289 * 290 * @since Java for Mac OS X 10.6 Update 1 291 * @since Java for Mac OS X 10.5 Update 6 - 1.6, 1.5 292 */ 293 public void requestUserAttention(final boolean critical) { 294 _AppMiscHandlers.requestUserAttention(critical); 295 } 296 297 /** 298 * Opens the native help viewer application if a Help Book has been added to the 299 * application bundler and registered in the Info.plist with CFBundleHelpBookFolder. 300 * 301 * See http://developer.apple.com/qa/qa2001/qa1022.html for more information. 302 * 303 * @since Java for Mac OS X 10.5 - 1.5 304 * @since Java for Mac OS X 10.5 Update 1 - 1.6 305 */ 306 public void openHelpViewer() { 307 _AppMiscHandlers.openHelpViewer(); 308 } 309 310 /** 311 * Attaches the contents of the provided PopupMenu to the application's Dock icon. 312 * 313 * @param menu the PopupMenu to attach to this application's Dock icon 314 * 315 * @since Java for Mac OS X 10.5 - 1.5 316 * @since Java for Mac OS X 10.5 Update 1 - 1.6 317 */ 318 public void setDockMenu(final PopupMenu menu) { 319 iconHandler.setDockMenu(menu); 320 } 321 322 /** 323 * @return the PopupMenu used to add items to this application's Dock icon 324 * 325 * @since Java for Mac OS X 10.5 - 1.5 326 * @since Java for Mac OS X 10.5 Update 1 - 1.6 327 */ 328 public PopupMenu getDockMenu() { 329 return iconHandler.getDockMenu(); 330 } 331 332 /** 333 * Changes this application's Dock icon to the provided image. 334 * 335 * @param image 336 * 337 * @since Java for Mac OS X 10.5 - 1.5 338 * @since Java for Mac OS X 10.5 Update 1 - 1.6 339 */ 340 public void setDockIconImage(final Image image) { 341 iconHandler.setDockIconImage(image); 342 } 343 344 /** 345 * Obtains an image of this application's Dock icon. 346 * 347 * @return an image of this application's Dock icon 348 * 349 * @since Java for Mac OS X 10.5 - 1.5 350 * @since Java for Mac OS X 10.5 Update 1 - 1.6 351 */ 352 public Image getDockIconImage() { 353 return iconHandler.getDockIconImage(); 354 } 355 356 /** 357 * Affixes a small system provided badge to this application's Dock icon. Usually a number. 358 * 359 * @param badge textual label to affix to the Dock icon 360 * 361 * @since Java for Mac OS X 10.5 - 1.5 362 * @since Java for Mac OS X 10.5 Update 1 - 1.6 363 */ 364 public void setDockIconBadge(final String badge) { 365 iconHandler.setDockIconBadge(badge); 366 } 367 368 /** 369 * Sets the default menu bar to use when there are no active frames. 370 * Only used when the system property "apple.laf.useScreenMenuBar" is "true", and 371 * the Aqua Look and Feel is active. 372 * 373 * @param menuBar to use when no other frames are active 374 * 375 * @since Java for Mac OS X 10.6 Update 1 376 * @since Java for Mac OS X 10.5 Update 6 - 1.6, 1.5 377 */ 378 public void setDefaultMenuBar(final JMenuBar menuBar) { 379 menuBarHandler.setDefaultMenuBar(menuBar); 380 } 381 382 /** 383 * Requests that a {@link Window} should animate into or out of full screen mode. 384 * Only {@link Window}s marked as full screenable by {@link FullScreenUtilities#setWindowCanFullScreen(Window, boolean)} can be toggled. 385 * 386 * @param window to animate into or out of full screen mode 387 * 388 * @since Java for Mac OS X 10.7 Update 1 389 */ 390 @SuppressWarnings("deprecation") 391 public void requestToggleFullScreen(final Window window) { 392 final ComponentPeer peer = window.getPeer(); 393 394 if (!(peer instanceof LWWindowPeer)) return; 395 Object platformWindow = ((LWWindowPeer) peer).getPlatformWindow(); 396 if (!(platformWindow instanceof CPlatformWindow)) return; 397 ((CPlatformWindow)platformWindow).toggleFullScreen(); 398 } 399 400 401 // -- DEPRECATED API -- 402 403 /** 404 * Adds the specified ApplicationListener as a receiver of callbacks from this class. 405 * This method throws a RuntimeException if the newer About, Preferences, Quit, etc handlers are installed. 406 * 407 * @param listener an implementation of ApplicationListener that handles ApplicationEvents 408 * 409 * @deprecated register individual handlers for each task (About, Preferences, Open, Print, Quit, etc) 410 * @since 1.4 411 */ 412 @SuppressWarnings("deprecation") 413 @Deprecated 414 public void addApplicationListener(final ApplicationListener listener) { 415 eventHandler.legacyHandler.addLegacyAppListener(listener); 416 } 417 418 /** 419 * Removes the specified ApplicationListener from being a receiver of callbacks from this class. 420 * This method throws a RuntimeException if the newer About, Preferences, Quit, etc handlers are installed. 421 * 422 * @param listener an implementation of ApplicationListener that had previously been registered to handle ApplicationEvents 423 * 424 * @deprecated unregister individual handlers for each task (About, Preferences, Open, Print, Quit, etc) 425 * @since 1.4 426 */ 427 @SuppressWarnings("deprecation") 428 @Deprecated 429 public void removeApplicationListener(final ApplicationListener listener) { 430 eventHandler.legacyHandler.removeLegacyAppListener(listener); 431 } 432 433 /** 434 * Enables the Preferences item in the application menu. The ApplicationListener receives a callback for 435 * selection of the Preferences item in the application menu only if this is set to <code>true</code>. 436 * 437 * If a Preferences item isn't present, this method adds and enables it. 438 * 439 * @param enable specifies whether the Preferences item in the application menu should be enabled (<code>true</code>) or not (<code>false</code>) 440 * 441 * @deprecated no replacement 442 * @since 1.4 443 */ 444 @Deprecated 445 public void setEnabledPreferencesMenu(final boolean enable) { 446 menuBarHandler.setPreferencesMenuItemVisible(true); 447 menuBarHandler.setPreferencesMenuItemEnabled(enable); 448 } 449 450 /** 451 * Enables the About item in the application menu. The ApplicationListener receives a callback for 452 * selection of the About item in the application menu only if this is set to <code>true</code>. Because AWT supplies 453 * a standard About window when an application may not, by default this is set to <code>true</code>. 454 * 455 * If the About item isn't present, this method adds and enables it. 456 * 457 * @param enable specifies whether the About item in the application menu should be enabled (<code>true</code>) or not (<code>false</code>) 458 * 459 * @deprecated no replacement 460 * @since 1.4 461 */ 462 @Deprecated 463 public void setEnabledAboutMenu(final boolean enable) { 464 menuBarHandler.setAboutMenuItemEnabled(enable); 465 } 466 467 /** 468 * Determines if the Preferences item of the application menu is enabled. 469 * 470 * @deprecated no replacement 471 * @since 1.4 472 */ 473 @Deprecated 474 public boolean getEnabledPreferencesMenu() { 475 return menuBarHandler.isPreferencesMenuItemEnabled(); 476 } 477 478 /** 479 * Determines if the About item of the application menu is enabled. 480 * 481 * @deprecated no replacement 482 * @since 1.4 483 */ 484 @Deprecated 485 public boolean getEnabledAboutMenu() { 486 return menuBarHandler.isAboutMenuItemEnabled(); 487 } 488 489 /** 490 * Determines if the About item of the application menu is present. 491 * 492 * @deprecated no replacement 493 * @since 1.4 494 */ 495 @Deprecated 496 public boolean isAboutMenuItemPresent() { 497 return menuBarHandler.isAboutMenuItemVisible(); 498 } 499 500 /** 501 * Adds the About item to the application menu if the item is not already present. 502 * 503 * @deprecated use {@link #setAboutHandler(AboutHandler)} with a non-null {@link AboutHandler} parameter 504 * @since 1.4 505 */ 506 @Deprecated 507 public void addAboutMenuItem() { 508 menuBarHandler.setAboutMenuItemVisible(true); 509 } 510 511 /** 512 * Removes the About item from the application menu if the item is present. 513 * 514 * @deprecated use {@link #setAboutHandler(AboutHandler)} with a null parameter 515 * @since 1.4 516 */ 517 @Deprecated 518 public void removeAboutMenuItem() { 519 menuBarHandler.setAboutMenuItemVisible(false); 520 } 521 522 /** 523 * Determines if the About Preferences of the application menu is present. By default there is no Preferences menu item. 524 * 525 * @deprecated no replacement 526 * @since 1.4 527 */ 528 @Deprecated 529 public boolean isPreferencesMenuItemPresent() { 530 return menuBarHandler.isPreferencesMenuItemVisible(); 531 } 532 533 /** 534 * Adds the Preferences item to the application menu if the item is not already present. 535 * 536 * @deprecated use {@link #setPreferencesHandler(PreferencesHandler)} with a non-null {@link PreferencesHandler} parameter 537 * @since 1.4 538 */ 539 @Deprecated 540 public void addPreferencesMenuItem() { 541 menuBarHandler.setPreferencesMenuItemVisible(true); 542 } 543 544 /** 545 * Removes the Preferences item from the application menu if that item is present. 546 * 547 * @deprecated use {@link #setPreferencesHandler(PreferencesHandler)} with a null parameter 548 * @since 1.4 549 */ 550 @Deprecated 551 public void removePreferencesMenuItem() { 552 menuBarHandler.setPreferencesMenuItemVisible(false); 553 } 554 555 /** 556 * @deprecated Use <code>java.awt.MouseInfo.getPointerInfo().getLocation()</code>. 557 * 558 * @since 1.4 559 */ 560 @Deprecated 561 public static Point getMouseLocationOnScreen() { 562 return java.awt.MouseInfo.getPointerInfo().getLocation(); 563 } 564 }