Package jahuwaldt.swing

Class MDIApplication

  • Direct Known Subclasses:
    GeomSSGUI
    public class MDIApplication
extends java.lang.Object
    This class defines a MacOS friendly application instance. It is a replacement for Steve Roy's excellent MRJAdapter package of old that adds Window Menu support and other features used by Multi-Document-Interface (MDI) applications. Under MacOS, an application instance will automatically call "handleNew()" method if the user brings the application forward and there are no open window's registered. On non-Mac platforms, the application will quit once the last document window has been closed.

    Modified by: Joseph A. Huwaldt

    Version:
    December 24, 2023
    Author:
    Joseph A. Huwaldt, Date: April 25, 2004

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static void addQuitListener​(QuitListener listener)
      Register an object to receive notification that the application is going to quit soon.
      static void addWindow​(java.awt.Window window)
      Register the supplied window with the list of windows managed by this MDIApplication.
      static java.util.List<java.awt.Window> allOpenWindows()
      Get an unmodifiable list of all the currently open windows in the application.
      static void browse​(java.net.URI uri)
      Launches the default browser to display a URI.
      AboutJMenuItem getAboutJMenuItem()
      Get the About item as a Swing menu item.
      static java.io.FilenameFilter getFilenameFilter()
      Return a reference to this application's default file name filter or null if a filename filter has not been stored.
      static javax.swing.JMenuBar getFramelessJMenuBar()
      Get the Swing frameless menu bar.
      static MDIApplication getInstance()
      Get the unique application instance.
      java.lang.String getName()
      Get the name of the application.
      Preferences getPreferences()  
      PreferencesJMenuItem getPreferencesJMenuItem()
      Get the About item as a Swing menu item.
      PreferencesJMenuItem getPreferencesJMenuItem​(java.lang.String prefsLabel)
      Get the About item as a Swing menu item.
      QuitJMenuItem getQuitJMenuItem()
      Get the Quit item as a Swing menu item.
      QuitJMenuItem getQuitJMenuItem​(java.lang.String exitLabel)
      Get the Quit item as a Swing menu item.
      static boolean getQuitOnClose()
      Returns a flag indicating if the application should quit when the last window is closed (true) or stay open (false; allowing the user to select "New" from the file menu for instance).
      java.util.ResourceBundle getResourceBundle()
      Returns the resource bundle stored with this application.
      static java.awt.Window getTopWindow()
      Returns a reference to the top-most window in the list of all open windows registered with this application.
      static void handleClose​(java.awt.event.ActionEvent event)
      Handle the user choosing "Close" from the File menu.
      java.awt.Frame handleNew​(java.awt.event.ActionEvent event)
      Handle the user requesting a new document window.
      static boolean handleQuit​(java.awt.desktop.QuitEvent event, java.awt.desktop.QuitResponse response)
      Handle the user choosing "Quit" from the File menu.
      static javax.swing.JMenu newWindowsMenu​(java.lang.String title)
      Get a new JMenu instance that can be used as a Windows menu using the specified title (typically "Windows").
      static void removeQuitListener​(QuitListener listener)
      Method to remove a quit listener from the list of quit listeners for this application.
      static void setAboutHandler​(java.awt.desktop.AboutHandler aboutHandler)
      Installs a handler to show a custom About window for your application.
      static void setFilenameFilter​(java.io.FilenameFilter filter)
      Used to set the filename filter for this application.
      static void setFramelessJMenuBar​(javax.swing.JMenuBar menuBar)
      Set the Swing frameless menu bar.
      void setName​(java.lang.String appName)
      Set the name of the application.
      static void setOpenFileHandler​(java.awt.desktop.OpenFilesHandler openFilesHandler)
      Installs the handler which is notified when the application is asked to open a list of files.
      static void setPreferences​(Preferences appPrefs)
      Used to set the user preferences for this application.
      static void setPreferencesHandler​(java.awt.desktop.PreferencesHandler preferencesHandler)
      Installs a handler to show a custom Preference window for your application.
      static void setQuitHandler​(java.awt.desktop.QuitHandler quitHandler)
      Installs the handler which determines if the application should quit.
      static void setQuitOnClose​(boolean flag)
      Sets a flag indicating if the application should quit when the last window is closed (true) or stay open (false; allowing the user to select "New" from the file menu for instance).
      static void setResourceBundle​(java.util.ResourceBundle bundle)
      Used to set the resource bundle for this application.
      static void windowTitleChanged​(java.awt.Window window)
      Call this method when a window being shown in a Windows menu has changed it's title.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • getInstance

        public static MDIApplication getInstance()
        Get the unique application instance. If it doesn't exist, this method creates it.
        Returns:
        the unique application instance

      • setName

        public final void setName​(java.lang.String appName)
        Set the name of the application.
        Parameters:
        appName - the name of the application

      • getName

        public java.lang.String getName()
        Get the name of the application.
        Returns:
        the name of the application

      • setFramelessJMenuBar

        public static void setFramelessJMenuBar​(javax.swing.JMenuBar menuBar)
        Set the Swing frameless menu bar. This menu bar is shown when no frame is visible. This state is normal for a Mac application Note that this method won't have any visual effect if the application is running on platforms other than MacOS. This method sets the menu bar internally so that it will be properly returned by a subsequent call to getFramelessMenuBar().
        Parameters:
        menuBar - the Swing menu bar to use as frameless menu bar

      • getFramelessJMenuBar

        public static javax.swing.JMenuBar getFramelessJMenuBar()
        Get the Swing frameless menu bar. This method is functional on all platforms.
        Returns:
        the Swing frameless menu bar or null if it hasn't been set.

      • setResourceBundle

        public static void setResourceBundle​(java.util.ResourceBundle bundle)
        Used to set the resource bundle for this application. This is provided as a convenience for storing the resource bundle so that it is accessible throughout an application.
        Parameters:
        bundle - The resource bundle to be stored with this application.

      • getResourceBundle

        public java.util.ResourceBundle getResourceBundle()
        Returns the resource bundle stored with this application. If no resource bundle has been stored, then null is returned.
        Returns:
        The resource bundle stored with this application.

      • setPreferences

        public static final void setPreferences​(Preferences appPrefs)
        Used to set the user preferences for this application. This is provided as a convenience for storing the preferences so that it is accessible throughout an application.
        Parameters:
        appPrefs - The user preferences for this application.

      • getPreferences

        public final Preferences getPreferences()
        Returns:
        a reference to the user preferences for this application.

      • setPreferencesHandler

        public static void setPreferencesHandler​(java.awt.desktop.PreferencesHandler preferencesHandler)
        Installs a handler to show a custom Preference window for your application.
        Parameters:
        prefsHandler - the handler to respond to the PreferencesHandler.handlePreferences(PreferencesEvent) message
        Throws:
        java.lang.SecurityException - if a security manager exists and it denies the RuntimePermission("canProcessApplicationEvents") permission
        java.lang.UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_ABOUT action.

      • getPreferencesJMenuItem

        public PreferencesJMenuItem getPreferencesJMenuItem()
        Get the About item as a Swing menu item. This item will automatically have the correct text and will have an ActionListener registered that will call the registered AboutHandler if the ActionEvent is triggered.
        Returns:
        the About Swing menu item

      • getPreferencesJMenuItem

        public PreferencesJMenuItem getPreferencesJMenuItem​(java.lang.String prefsLabel)
        Get the About item as a Swing menu item. This item will automatically have the correct text and will have an ActionListener registered that will call the registered AboutHandler if the ActionEvent is triggered.
        Parameters:
        prefsLabel - the label for the Preferences menu item.
        Returns:
        the About Swing menu item

      • setFilenameFilter

        public static void setFilenameFilter​(java.io.FilenameFilter filter)
        Used to set the filename filter for this application. This is provided as a convenience for storing the filename filter so that it is accessible throughout an application.
        Parameters:
        filter - The filename filter to be stored with this application.

      • getFilenameFilter

        public static java.io.FilenameFilter getFilenameFilter()
        Return a reference to this application's default file name filter or null if a filename filter has not been stored.
        Returns:
        The default filename filter for this application.

      • setQuitOnClose

        public static void setQuitOnClose​(boolean flag)
        Sets a flag indicating if the application should quit when the last window is closed (true) or stay open (false; allowing the user to select "New" from the file menu for instance). The default value is true except on MacOS X where the default value if false.
        Parameters:
        flag - Set to true to have the application automatically quit when all the windows close.

      • getQuitOnClose

        public static boolean getQuitOnClose()
        Returns a flag indicating if the application should quit when the last window is closed (true) or stay open (false; allowing the user to select "New" from the file menu for instance). The default value is true except on MacOS X where the default value if false.
        Returns:
        A flag indicating if the application should quit when the last window is closed.

      • getQuitJMenuItem

        public QuitJMenuItem getQuitJMenuItem()
        Get the Quit item as a Swing menu item. This item will automatically have the correct text and shortcut key for the platform and will have an ActionListener registered that will call System.exit(0) if the ActionEvent is triggered.
        Returns:
        the Quit Swing menu item

      • getQuitJMenuItem

        public QuitJMenuItem getQuitJMenuItem​(java.lang.String exitLabel)
        Get the Quit item as a Swing menu item. This item will automatically have the correct text and shortcut key for the platform and will have an ActionListener registered that will call System.exit(0) if the ActionEvent is triggered.
        Parameters:
        exitLabel - The label for the quit menu on non-MacOS platforms.
        Returns:
        the Quit Swing menu item

      • addWindow

        public static void addWindow​(java.awt.Window window)
        Register the supplied window with the list of windows managed by this MDIApplication. When the window is made visible, it will be added to the "Windows" menu. The window will be removed from the "Windows" menu when it is closed.
        Parameters:
        window - The window to be added to the list of open windows.

      • addQuitListener

        public static void addQuitListener​(QuitListener listener)
        Register an object to receive notification that the application is going to quit soon.
        Parameters:
        listener - The listener to register.

      • removeQuitListener

        public static void removeQuitListener​(QuitListener listener)
        Method to remove a quit listener from the list of quit listeners for this application.
        Parameters:
        listener - The listener to remove.

      • setQuitHandler

        public static void setQuitHandler​(java.awt.desktop.QuitHandler quitHandler)
        Installs the handler which determines if the application should quit. The handler is passed a one-shot QuitResponse which can cancel or proceed with the quit. Setting the handler to null causes all quit requests to directly perform the default QuitStrategy.
        Parameters:
        listener - The listener to register.

      • browse

        public static void browse​(java.net.URI uri)
                   throws java.io.IOException
        Launches the default browser to display a URI. If the default browser is not able to handle the specified URI, the application registered for handling URIs of the specified type is invoked. The application is determined from the protocol and path of the URI, as defined by the URI class.
        Parameters:
        uri - the URI to be displayed in the user default browser.
        Throws:
        java.io.IOException

      • setAboutHandler

        public static void setAboutHandler​(java.awt.desktop.AboutHandler aboutHandler)
        Installs a handler to show a custom About window for your application.
        Parameters:
        aboutHandler - the handler to respond to the AboutHandler.handleAbout(AboutEvent) message
        Throws:
        java.lang.SecurityException - if a security manager exists and it denies the RuntimePermission("canProcessApplicationEvents") permission
        java.lang.UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_ABOUT action.

      • getAboutJMenuItem

        public AboutJMenuItem getAboutJMenuItem()
        Get the About item as a Swing menu item. This item will automatically have the correct text and will have an ActionListener registered that will call the registered AboutHandler if the ActionEvent is triggered.
        Returns:
        the About Swing menu item

      • setOpenFileHandler

        public static void setOpenFileHandler​(java.awt.desktop.OpenFilesHandler openFilesHandler)
                               throws java.lang.SecurityException,
                                      java.lang.UnsupportedOperationException
        Installs the handler which is notified when the application is asked to open a list of files.
        Parameters:
        openFilesHandler - handler
        Throws:
        java.lang.SecurityException - if a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the files, or it denies the RuntimePermission("canProcessApplicationEvents") permission, or the calling thread is not allowed to create a subprocess.
        java.lang.UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_OPEN_FILE action

      • getTopWindow

        public static java.awt.Window getTopWindow()
        Returns a reference to the top-most window in the list of all open windows registered with this application. If there are no open windows, null is returned.
        Returns:
        The top-most window in the list of all open windows.

      • allOpenWindows

        public static java.util.List<java.awt.Window> allOpenWindows()
        Get an unmodifiable list of all the currently open windows in the application.
        Returns:
        An unmodifiable list of all the currently open windows.

      • newWindowsMenu

        public static javax.swing.JMenu newWindowsMenu​(java.lang.String title)
        Get a new JMenu instance that can be used as a Windows menu using the specified title (typically "Windows"). The menu that is returned is maintained by this class and should not be modified by the user.
        Parameters:
        title - The title for the Windows menu.
        Returns:
        A JMenu that represents the application's Windows menu.

      • windowTitleChanged

        public static void windowTitleChanged​(java.awt.Window window)
        Call this method when a window being shown in a Windows menu has changed it's title. This method will update the titles shown in the Windows menu.
        Parameters:
        window - The window that has changed titles.

      • handleNew

        public java.awt.Frame handleNew​(java.awt.event.ActionEvent event)
        Handle the user requesting a new document window. If it is inappropriate for the application to create a new document window, then this method should do nothing. The default implementation does nothing and returns null.
        Parameters:
        event - The event that caused this method to be called. May be "null" if this method is called by MDIApplication or one of it's subclasses.
        Returns:
        A reference to the newly created window frame or null if a window was not created.

      • handleClose

        public static void handleClose​(java.awt.event.ActionEvent event)
        Handle the user choosing "Close" from the File menu. This implementation dispatches a "Window Closing" event on the top most window.
        Parameters:
        event - The event that caused this method to be called.

      • handleQuit

        public static boolean handleQuit​(java.awt.desktop.QuitEvent event,
                                 java.awt.desktop.QuitResponse response)
        Handle the user choosing "Quit" from the File menu. This implementation dispatches a separate "window closing" event to each window. This gives each window an opportunity to cancel the quit process.
        Parameters:
        event - The event that caused this method to be called or null if none.
        response - the one-shot response object used to cancel or proceed with the quit action or null if none.
        Returns:
        True if the application can proceed with the quit or false if it shoudl be canceled.