< prev index next >

src/java.desktop/macosx/classes/com/apple/eawt/Application.java

Print this page




  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.Image;
  29 import java.awt.Point;
  30 import java.awt.PopupMenu;
  31 import java.awt.Toolkit;
  32 import java.awt.Window;
  33 import java.beans.Beans;
  34 
  35 import javax.swing.JMenuBar;
  36 
  37 import sun.awt.AWTAccessor;
  38 import sun.lwawt.LWWindowPeer;
  39 import sun.lwawt.macosx.CPlatformWindow;
  40 
  41 /**
  42  * The <code>Application</code> class allows you to integrate your Java application with the native Mac OS X environment.
  43  * You can provide your Mac OS X users a greatly enhanced experience by implementing a few basic handlers for standard system events.
  44  *
  45  * For example:
  46  * <ul>
  47  * <li>Open an about dialog when a user chooses About from the application menu.</li>
  48  * <li>Open a preferences window when the users chooses Preferences from the application menu.</li>
  49  * <li>Create a new document when the user clicks on your Dock icon, and no windows are open.</li>
  50  * <li>Open a document that the user double-clicked on in the Finder.</li>
  51  * <li>Open a custom URL scheme when a user clicks on link in a web browser.</li>
  52  * <li>Reconnect to network services after the system has awoke from sleep.</li>
  53  * <li>Cleanly shutdown your application when the user chooses Quit from the application menu, Dock icon, or types Command-Q.</li>
  54  * <li>Cancel shutdown/logout if the user has unsaved changes in your application.</li>
  55  * </ul>
  56  *
  57  * @since 1.4
  58  */
  59 public class Application {
  60     private static native void nativeInitializeApplicationDelegate();
  61 
  62     static Application sApplication = null;


 125      * Removes sub-types of {@link AppEventListener} from listening for notifications from the native Mac OS X system.
 126      *
 127      * @see AppForegroundListener
 128      * @see AppHiddenListener
 129      * @see AppReOpenedListener
 130      * @see ScreenSleepListener
 131      * @see SystemSleepListener
 132      * @see UserSessionListener
 133      *
 134      * @param listener
 135      * @since Java for Mac OS X 10.6 Update 3
 136      * @since Java for Mac OS X 10.5 Update 8
 137      */
 138     public void removeAppEventListener(final AppEventListener listener) {
 139         eventHandler.removeListener(listener);
 140     }
 141 
 142     /**
 143      * Installs a handler to show a custom About window for your application.
 144      *
 145      * Setting the {@link AboutHandler} to <code>null</code> reverts it to the default Cocoa About window.
 146      *
 147      * @param aboutHandler the handler to respond to the {@link AboutHandler#handleAbout()} message
 148      * @since Java for Mac OS X 10.6 Update 3
 149      * @since Java for Mac OS X 10.5 Update 8
 150      */
 151     public void setAboutHandler(final AboutHandler aboutHandler) {
 152         eventHandler.aboutDispatcher.setHandler(aboutHandler);
 153     }
 154 
 155     /**
 156      * Installs a handler to create the Preferences menu item in your application's app menu.
 157      *
 158      * Setting the {@link PreferencesHandler} to <code>null</code> will remove the Preferences item from the app menu.
 159      *
 160      * @param preferencesHandler
 161      * @since Java for Mac OS X 10.6 Update 3
 162      * @since Java for Mac OS X 10.5 Update 8
 163      */
 164     public void setPreferencesHandler(final PreferencesHandler preferencesHandler) {
 165         eventHandler.preferencesDispatcher.setHandler(preferencesHandler);
 166     }
 167 
 168     /**
 169      * Installs the handler which is notified when the application is asked to open a list of files.
 170      * 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.
 171      * 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.
 172      *
 173      * @param openFileHandler
 174      * @since Java for Mac OS X 10.6 Update 3
 175      * @since Java for Mac OS X 10.5 Update 8
 176      */
 177     public void setOpenFileHandler(final OpenFilesHandler openFileHandler) {
 178         eventHandler.openFilesDispatcher.setHandler(openFileHandler);
 179     }
 180 
 181     /**
 182      * Installs the handler which is notified when the application is asked to print a list of files.
 183      * 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.
 184      * 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.
 185      *
 186      * @param printFileHandler
 187      * @since Java for Mac OS X 10.6 Update 3
 188      * @since Java for Mac OS X 10.5 Update 8
 189      */
 190     public void setPrintFileHandler(final PrintFilesHandler printFileHandler) {
 191         eventHandler.printFilesDispatcher.setHandler(printFileHandler);
 192     }
 193 
 194     /**
 195      * Installs the handler which is notified when the application is asked to open a URL.
 196      * 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.
 197      * 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.
 198      *
 199      * Setting the handler to <code>null</code> causes all {@link OpenURIHandler#openURI(AppEvent.OpenURIEvent)} requests to be enqueued until another handler is set.
 200      *
 201      * @param openURIHandler
 202      * @since Java for Mac OS X 10.6 Update 3
 203      * @since Java for Mac OS X 10.5 Update 8
 204      */
 205     public void setOpenURIHandler(final OpenURIHandler openURIHandler) {
 206         eventHandler.openURIDispatcher.setHandler(openURIHandler);
 207     }
 208 
 209     /**
 210      * Installs the handler which determines if the application should quit.
 211      * The handler is passed a one-shot {@link QuitResponse} which can cancel or proceed with the quit.
 212      * Setting the handler to <code>null</code> causes all quit requests to directly perform the default {@link QuitStrategy}.
 213      *
 214      * @param quitHandler the handler that is called when the application is asked to quit
 215      * @since Java for Mac OS X 10.6 Update 3
 216      * @since Java for Mac OS X 10.5 Update 8
 217      */
 218     public void setQuitHandler(final QuitHandler quitHandler) {
 219         eventHandler.quitDispatcher.setHandler(quitHandler);
 220     }
 221 
 222     /**
 223      * Sets the default strategy used to quit this application. The default is calling SYSTEM_EXIT_0.
 224      *
 225      * The quit strategy can also be set with the "apple.eawt.quitStrategy" system property.
 226      *
 227      * @param strategy the way this application should be shutdown
 228      * @since Java for Mac OS X 10.6 Update 3
 229      * @since Java for Mac OS X 10.5 Update 8
 230      */
 231     public void setQuitStrategy(final QuitStrategy strategy) {
 232         eventHandler.setDefaultQuitStrategy(strategy);


 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 


 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 }


  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.Image;
  29 import java.awt.Point;
  30 import java.awt.PopupMenu;
  31 import java.awt.Toolkit;
  32 import java.awt.Window;
  33 import java.beans.Beans;
  34 
  35 import javax.swing.JMenuBar;
  36 
  37 import sun.awt.AWTAccessor;
  38 import sun.lwawt.LWWindowPeer;
  39 import sun.lwawt.macosx.CPlatformWindow;
  40 
  41 /**
  42  * The {@code Application} class allows you to integrate your Java application with the native Mac OS X environment.
  43  * You can provide your Mac OS X users a greatly enhanced experience by implementing a few basic handlers for standard system events.
  44  *
  45  * For example:
  46  * <ul>
  47  * <li>Open an about dialog when a user chooses About from the application menu.</li>
  48  * <li>Open a preferences window when the users chooses Preferences from the application menu.</li>
  49  * <li>Create a new document when the user clicks on your Dock icon, and no windows are open.</li>
  50  * <li>Open a document that the user double-clicked on in the Finder.</li>
  51  * <li>Open a custom URL scheme when a user clicks on link in a web browser.</li>
  52  * <li>Reconnect to network services after the system has awoke from sleep.</li>
  53  * <li>Cleanly shutdown your application when the user chooses Quit from the application menu, Dock icon, or types Command-Q.</li>
  54  * <li>Cancel shutdown/logout if the user has unsaved changes in your application.</li>
  55  * </ul>
  56  *
  57  * @since 1.4
  58  */
  59 public class Application {
  60     private static native void nativeInitializeApplicationDelegate();
  61 
  62     static Application sApplication = null;


 125      * Removes sub-types of {@link AppEventListener} from listening for notifications from the native Mac OS X system.
 126      *
 127      * @see AppForegroundListener
 128      * @see AppHiddenListener
 129      * @see AppReOpenedListener
 130      * @see ScreenSleepListener
 131      * @see SystemSleepListener
 132      * @see UserSessionListener
 133      *
 134      * @param listener
 135      * @since Java for Mac OS X 10.6 Update 3
 136      * @since Java for Mac OS X 10.5 Update 8
 137      */
 138     public void removeAppEventListener(final AppEventListener listener) {
 139         eventHandler.removeListener(listener);
 140     }
 141 
 142     /**
 143      * Installs a handler to show a custom About window for your application.
 144      *
 145      * Setting the {@link AboutHandler} to {@code null} reverts it to the default Cocoa About window.
 146      *
 147      * @param aboutHandler the handler to respond to the {@link AboutHandler#handleAbout()} message
 148      * @since Java for Mac OS X 10.6 Update 3
 149      * @since Java for Mac OS X 10.5 Update 8
 150      */
 151     public void setAboutHandler(final AboutHandler aboutHandler) {
 152         eventHandler.aboutDispatcher.setHandler(aboutHandler);
 153     }
 154 
 155     /**
 156      * Installs a handler to create the Preferences menu item in your application's app menu.
 157      *
 158      * Setting the {@link PreferencesHandler} to {@code null} will remove the Preferences item from the app menu.
 159      *
 160      * @param preferencesHandler
 161      * @since Java for Mac OS X 10.6 Update 3
 162      * @since Java for Mac OS X 10.5 Update 8
 163      */
 164     public void setPreferencesHandler(final PreferencesHandler preferencesHandler) {
 165         eventHandler.preferencesDispatcher.setHandler(preferencesHandler);
 166     }
 167 
 168     /**
 169      * Installs the handler which is notified when the application is asked to open a list of files.
 170      * The {@link OpenFilesHandler#openFiles(AppEvent.OpenFilesEvent)} notifications are only sent if the Java app is a bundled application, with a {@code CFBundleDocumentTypes} array present in it's Info.plist.
 171      * 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} key to your app's Info.plist.
 172      *
 173      * @param openFileHandler
 174      * @since Java for Mac OS X 10.6 Update 3
 175      * @since Java for Mac OS X 10.5 Update 8
 176      */
 177     public void setOpenFileHandler(final OpenFilesHandler openFileHandler) {
 178         eventHandler.openFilesDispatcher.setHandler(openFileHandler);
 179     }
 180 
 181     /**
 182      * Installs the handler which is notified when the application is asked to print a list of files.
 183      * The {@link PrintFilesHandler#printFiles(AppEvent.PrintFilesEvent)} notifications are only sent if the Java app is a bundled application, with a {@code CFBundleDocumentTypes} array present in it's Info.plist.
 184      * 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} key to your app's Info.plist.
 185      *
 186      * @param printFileHandler
 187      * @since Java for Mac OS X 10.6 Update 3
 188      * @since Java for Mac OS X 10.5 Update 8
 189      */
 190     public void setPrintFileHandler(final PrintFilesHandler printFileHandler) {
 191         eventHandler.printFilesDispatcher.setHandler(printFileHandler);
 192     }
 193 
 194     /**
 195      * Installs the handler which is notified when the application is asked to open a URL.
 196      * The {@link OpenURIHandler#openURI(AppEvent.OpenURIEvent)} notifications are only sent if the Java app is a bundled application, with a {@code CFBundleURLTypes} array present in it's Info.plist.
 197      * 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} key to your app's Info.plist.
 198      *
 199      * Setting the handler to {@code null} causes all {@link OpenURIHandler#openURI(AppEvent.OpenURIEvent)} requests to be enqueued until another handler is set.
 200      *
 201      * @param openURIHandler
 202      * @since Java for Mac OS X 10.6 Update 3
 203      * @since Java for Mac OS X 10.5 Update 8
 204      */
 205     public void setOpenURIHandler(final OpenURIHandler openURIHandler) {
 206         eventHandler.openURIDispatcher.setHandler(openURIHandler);
 207     }
 208 
 209     /**
 210      * Installs the handler which determines if the application should quit.
 211      * The handler is passed a one-shot {@link QuitResponse} which can cancel or proceed with the quit.
 212      * Setting the handler to {@code null} causes all quit requests to directly perform the default {@link QuitStrategy}.
 213      *
 214      * @param quitHandler the handler that is called when the application is asked to quit
 215      * @since Java for Mac OS X 10.6 Update 3
 216      * @since Java for Mac OS X 10.5 Update 8
 217      */
 218     public void setQuitHandler(final QuitHandler quitHandler) {
 219         eventHandler.quitDispatcher.setHandler(quitHandler);
 220     }
 221 
 222     /**
 223      * Sets the default strategy used to quit this application. The default is calling SYSTEM_EXIT_0.
 224      *
 225      * The quit strategy can also be set with the "apple.eawt.quitStrategy" system property.
 226      *
 227      * @param strategy the way this application should be shutdown
 228      * @since Java for Mac OS X 10.6 Update 3
 229      * @since Java for Mac OS X 10.5 Update 8
 230      */
 231     public void setQuitStrategy(final QuitStrategy strategy) {
 232         eventHandler.setDefaultQuitStrategy(strategy);


 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}.
 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}) or not ({@code false})
 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}. Because AWT supplies
 453      * a standard About window when an application may not, by default this is set to {@code true}.
 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}) or not ({@code false})
 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 


 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()}.
 557      *
 558      * @since 1.4
 559      */
 560     @Deprecated
 561     public static Point getMouseLocationOnScreen() {
 562         return java.awt.MouseInfo.getPointerInfo().getLocation();
 563     }
 564 }
< prev index next >