Package ptolemy.gui

Class Top

  • All Implemented Interfaces:
    java.awt.event.WindowFocusListener, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, java.util.EventListener, javax.accessibility.Accessible, javax.swing.RootPaneContainer, javax.swing.WindowConstants, StatusHandler
    Direct Known Subclasses:
    TableauFrame, TopTest
    public abstract class Top
extends javax.swing.JFrame
implements java.awt.event.WindowFocusListener, StatusHandler
    This is a top-level window with a menubar and an optional status bar. Derived classes should add components to the content pane using a line like: 
     getContentPane().add(component, BorderLayout.CENTER);
    Derived classes may wish to modify the menus. The File and Help menus are exposed as protected members. The File menu items in the _fileMenuItems protected array are, in order, Open File, Open URL, New, Save, Save As, Print, Close, and Exit. The Help menu items in the _helpMenuItems protected array are, in order, About and Help.

    A derived class can use the insert() methods of JMenu to insert a menu item defined by an Action or a JMenuItem into a specified position in the menu. Derived classes can also insert separators using the insertSeparator() method of JMenu. In principle, derived classes can also remove menu items using the remove() methods of JMenu; however, we discourage this. A basic principle of user interface design is habituation, where there is considerable value in having menus that have consistent contents and layout throughout the application (Microsoft, for example, violates this principle with adaptive menus).

    Instead of removing items from the menu, they can be disabled. For example, to disable the "Save" item in the File menu, do 

     _fileMenuItems[3].setEnabled(false);

    Some menu items are provided, but are disabled by default. The "New" item, for example, can be enabled with 

     _fileMenuItems[2].setEnabled(true);
    A derived class that enables this menu item can populate the menu with submenu items. This particular entry in the _fileMenuItems[2] is a JMenu, not just a JMenuItem, so it can have menu items added to it.

    A derived class can add an entirely new menu (many do that). However, at this time, the JMenuBar interface does not support putting a new menu into an arbitrary position. For this reason, derived classes should insert new menus into the menu bar only in the _addMenus() protected method. This ensures that the File menu is always the rightmost menu, and the Help menu is always the leftmost menu. The _addMenus() method is called when the window is first packed.

    Since:
    Ptolemy II 1.0
    Version:
    $Id$
    Author:
    Edward A. Lee and Steve Neuendorffer
    See Also:
    Serialized Form
    Pt.AcceptedRating:
    Yellow (janneck)
    Pt.ProposedRating:
    Yellow (eal)

    • Nested Class Summary

      • Nested classes/interfaces inherited from class javax.swing.JFrame

        javax.swing.JFrame.AccessibleJFrame

      • Nested classes/interfaces inherited from class java.awt.Frame

        java.awt.Frame.AccessibleAWTFrame

      • Nested classes/interfaces inherited from class java.awt.Window

        java.awt.Window.AccessibleAWTWindow, java.awt.Window.Type

      • Nested classes/interfaces inherited from class java.awt.Container

        java.awt.Container.AccessibleAWTContainer

      • Nested classes/interfaces inherited from class java.awt.Component

        java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static int _CANCELED
      Indicator that a close operation is canceled.
      protected boolean _debugClosing
      Set to true to print closing sequence information to standard out.
      protected static java.io.File _directory
      The most recent directory used in a file dialog.
      protected static int _DISCARDED
      Indicator that a file is discarded.
      protected int _exitResult
      The return value of the _exit() menu.
      protected static int _EXPORT_MENU_INDEX
      Index in the _fileMenuItems array of the Export item.
      protected static int _FAILED
      Indicator that a file save failed.
      protected javax.swing.filechooser.FileFilter _fileFilter
      The FileFilter that determines what files are displayed by the Open dialog and the Save As dialog The initial default is null, which causes no FileFilter to be applied, which results in all files being displayed.
      protected javax.swing.JMenu _fileMenu
      File menu for this frame.
      protected javax.swing.JMenuItem[] _fileMenuItems
      Items in the file menu.
      protected java.io.FilenameFilter _filenameFilter
      The FileFilter used by the java.awt.FileDialog that determines what files are displayed by the Open dialog and the Save As dialog The initial default is null, which causes no FileFilter to be applied, which results in all files being displayed.
      protected javax.swing.JMenu _helpMenu
      Help menu for this frame.
      protected javax.swing.JMenuItem[] _helpMenuItems
      Help menu items.
      protected static int _IMPORT_MENU_INDEX
      Index in the _fileMenuItems array of the Import item.
      protected javax.swing.JMenuBar _menubar
      Menubar for this frame.
      protected static int _NEW_MENU_INDEX
      Index in the _fileMenuItems array of the New item.
      protected static int _SAVED
      Indicator that a file is saved.
      protected StatusBar _statusBar
      The status bar.
      static long MAXIMUM_STATUS_MESSAGE_TIME
      Maximum amount of time that a status message is displayed in milliseconds.

      • Fields inherited from class javax.swing.JFrame

        accessibleContext, rootPane, rootPaneCheckingEnabled

      • Fields inherited from class java.awt.Frame

        CROSSHAIR_CURSOR, DEFAULT_CURSOR, E_RESIZE_CURSOR, HAND_CURSOR, ICONIFIED, MAXIMIZED_BOTH, MAXIMIZED_HORIZ, MAXIMIZED_VERT, MOVE_CURSOR, N_RESIZE_CURSOR, NE_RESIZE_CURSOR, NORMAL, NW_RESIZE_CURSOR, S_RESIZE_CURSOR, SE_RESIZE_CURSOR, SW_RESIZE_CURSOR, TEXT_CURSOR, W_RESIZE_CURSOR, WAIT_CURSOR

      • Fields inherited from class java.awt.Component

        BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

      • Fields inherited from interface java.awt.image.ImageObserver

        ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

      • Fields inherited from interface javax.swing.WindowConstants

        DISPOSE_ON_CLOSE, DO_NOTHING_ON_CLOSE, EXIT_ON_CLOSE, HIDE_ON_CLOSE

    • Constructor Summary

      Constructors 
      Constructor Description
      Top()
      Construct an empty top-level frame with the default status bar.
      Top​(StatusBar statusBar)
      Construct an empty top-level frame with the specified status bar.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      protected void _about()
      Open a dialog with basic information about this window.
      protected void _addMenus()
      Add menus to the menu bar.
      protected boolean _clear()
      Clear the current contents.
      protected boolean _close()
      Close the window.
      protected javax.swing.JMenuItem[] _createFileMenuItems()
      Create the items in the File menu.
      protected void _exit()
      Exit the application after querying the user to save data.
      protected java.io.File _getCurrentDirectory()
      Return the current directory.
      protected java.lang.String _getName()
      Get the name of this object, which in this base class is either the name of the file that has been associated with this object, or the string "Unnamed" if none.
      protected void _help()
      Display the same information given by _about().
      protected void _open()
      Open a file dialog to identify a file to be opened, and then call _read() to open the file.
      protected void _openURL()
      Open a dialog to enter a URL, and then invoke _read() to open the URL.
      protected void _populateHistory​(java.util.List historyList)
      Update the submenu with a history list and add a listener to each line.
      protected void _print()
      Print the contents.
      protected void _printCrossPlatform()
      Print using the cross platform dialog.
      protected void _printNative()
      Print using the native dialog.
      protected void _printPDF()
      If a PDF printer is available print to it.
      protected int _queryForSave()
      Open a dialog to prompt the user to save the data.
      protected abstract void _read​(java.net.URL url)
      Read the specified URL.
      protected boolean _save()
      Save the model to the current file, if there is one, and otherwise invoke _saveAs().
      protected boolean _saveAs()
      Query the user for a filename and save the model to that file.
      protected javax.swing.JFileChooser _saveAsFileDialog()
      Deprecated.
      Use _saveAsJFileChooserComponent()
      protected java.awt.FileDialog _saveAsFileDialogComponent()
      Create and return a FileDialog for the "Save As" command.
      protected javax.swing.JFileChooser _saveAsJFileChooserComponent()
      Create and return a JFileChooser for the "Save As" command.
      protected void _updateHistory​(java.lang.String file, boolean delete)
      Add the name of the last file open or set the name to the first position if already in the list.
      protected abstract void _writeFile​(java.io.File file)
      Write the model to the specified file.
      void about()
      Open a dialog with basic information about this window.
      void centerOnScreen()
      Center the window on the screen.
      void close()
      Close the window, prompting the user to save changes if there have been any.
      static void deferIfNecessary​(java.lang.Runnable action)
      If this method is called in the AWT event dispatch thread, then simply execute the specified action.
      void dispose()
      Dispose of this frame.
      boolean exit()
      Exit the application after querying the user to save data.
      boolean getCentering()
      Return true if the window is set to be centered when pack() is called.
      java.awt.Dimension getContentSize()
      Return the size of the contents of this window.
      void hideMenuBar()
      If called before the first time pack() is called, this method will prevent the appearance of a menu bar.
      boolean isDisposed()
      Return true if this frame has been disposed.
      boolean isMenuPopulated()
      Return true if the menu of this window has been populated.
      boolean isModified()
      Return true if the data associated with this window has been modified since it was first read or last saved.
      void pack()
      Size this window to its preferred size and make it displayable, and override the base class to populate the menu bar if the menus have not already been populated.
      void report​(java.lang.String message)
      Report a message to the user by displaying it in a status bar, if there is one.
      void report​(java.lang.String message, java.lang.Throwable throwable)
      Report a Throwable, which is usually an Exception but can also be an Error.
      void report​(java.lang.Throwable throwable)
      Report a Throwable, which is usually an Exception but can also be an Error.
      void setBackground​(java.awt.Color background)
      Set background color.
      void setCentering​(boolean centering)
      Specify whether or not to center the window on the screen when packing it.
      static void setDirectory​(java.io.File dir)
      Set the initial default directory.
      void setModified​(boolean modified)
      Record whether the data associated with this window has been modified since it was first read or last saved.
      void show()
      Override the base class to deiconify the window, if necessary.
      void status​(java.lang.String message)
      Display the specified message in the status bar.
      void windowGainedFocus​(java.awt.event.WindowEvent event)
      Register with the global message handler to receive status messages.
      void windowLostFocus​(java.awt.event.WindowEvent event)
      Unregister with the global message handler to receive status messages.

      • Methods inherited from class javax.swing.JFrame

        addImpl, createRootPane, frameInit, getAccessibleContext, getContentPane, getDefaultCloseOperation, getGlassPane, getGraphics, getJMenuBar, getLayeredPane, getRootPane, getTransferHandler, isDefaultLookAndFeelDecorated, isRootPaneCheckingEnabled, paramString, processWindowEvent, remove, repaint, setContentPane, setDefaultCloseOperation, setDefaultLookAndFeelDecorated, setGlassPane, setIconImage, setJMenuBar, setLayeredPane, setLayout, setRootPane, setRootPaneCheckingEnabled, setTransferHandler, update

      • Methods inherited from class java.awt.Frame

        addNotify, getCursorType, getExtendedState, getFrames, getIconImage, getMaximizedBounds, getMenuBar, getState, getTitle, isResizable, isUndecorated, remove, removeNotify, setCursor, setExtendedState, setMaximizedBounds, setMenuBar, setOpacity, setResizable, setShape, setState, setTitle, setUndecorated

      • Methods inherited from class java.awt.Window

        addPropertyChangeListener, addPropertyChangeListener, addWindowFocusListener, addWindowListener, addWindowStateListener, applyResourceBundle, applyResourceBundle, createBufferStrategy, createBufferStrategy, getBackground, getBufferStrategy, getFocusableWindowState, getFocusCycleRootAncestor, getFocusOwner, getFocusTraversalKeys, getIconImages, getInputContext, getListeners, getLocale, getModalExclusionType, getMostRecentFocusOwner, getOpacity, getOwnedWindows, getOwner, getOwnerlessWindows, getShape, getToolkit, getType, getWarningString, getWindowFocusListeners, getWindowListeners, getWindows, getWindowStateListeners, hide, isActive, isAlwaysOnTop, isAlwaysOnTopSupported, isAutoRequestFocus, isFocusableWindow, isFocusCycleRoot, isFocused, isLocationByPlatform, isOpaque, isShowing, isValidateRoot, paint, postEvent, processEvent, processWindowFocusEvent, processWindowStateEvent, removeWindowFocusListener, removeWindowListener, removeWindowStateListener, reshape, setAlwaysOnTop, setAutoRequestFocus, setBounds, setBounds, setCursor, setFocusableWindowState, setFocusCycleRoot, setIconImages, setLocation, setLocation, setLocationByPlatform, setLocationRelativeTo, setMinimumSize, setModalExclusionType, setSize, setSize, setType, setVisible, toBack, toFront

      • Methods inherited from class java.awt.Container

        add, add, add, add, add, addContainerListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalPolicy, getInsets, getLayout, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, print, printComponents, processContainerEvent, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, transferFocusDownCycle, validate, validateTree

      • Methods inherited from class java.awt.Component

        action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, requestFocusInWindow, resize, resize, revalidate, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setMaximumSize, setMixingCutoutShape, setName, setPreferredSize, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface java.awt.MenuContainer

        getFont, postEvent

    • Field Detail

      • MAXIMUM_STATUS_MESSAGE_TIME

        public static final long MAXIMUM_STATUS_MESSAGE_TIME
        Maximum amount of time that a status message is displayed in milliseconds.
        See Also:
        Constant Field Values

      • _CANCELED

        protected static final int _CANCELED
        Indicator that a close operation is canceled.
        See Also:
        Constant Field Values

      • _DISCARDED

        protected static final int _DISCARDED
        Indicator that a file is discarded.
        See Also:
        Constant Field Values

      • _FAILED

        protected static final int _FAILED
        Indicator that a file save failed.
        See Also:
        Constant Field Values

      • _SAVED

        protected static final int _SAVED
        Indicator that a file is saved.
        See Also:
        Constant Field Values

      • _directory

        protected static java.io.File _directory
        The most recent directory used in a file dialog.

      • _exitResult

        protected int _exitResult
        The return value of the _exit() menu. We use a separate variable here for backward compatibility. The values of this variable are the values returned by _queryForSave.

      • _fileFilter

        protected javax.swing.filechooser.FileFilter _fileFilter
        The FileFilter that determines what files are displayed by the Open dialog and the Save As dialog The initial default is null, which causes no FileFilter to be applied, which results in all files being displayed.

      • _filenameFilter

        protected java.io.FilenameFilter _filenameFilter
        The FileFilter used by the java.awt.FileDialog that determines what files are displayed by the Open dialog and the Save As dialog The initial default is null, which causes no FileFilter to be applied, which results in all files being displayed.

        Note that this class can use either java.awt.FileDialog or javax.swing.JFileChooser, so classes should set both _fileFilter and _filenameFilter. Note that it possible to define an inner class that extends javax.swing.filechooser.FileFilter and implements java.io.FilenameFilter and that has two separate accept() methods. This inner class can then be set as the value for both _fileFilter and _filenameFilter: 

          ...
      MyFileFilter myFileFilter = new MyFileFilter();
      _fileFilter = myFileFilter;
      _filenameFilter = myFileFilter;
  ...
  static MyFileFilter extends FileFilter implements FilenameFilter {
      public boolean accept(File file) {
         // For FileFilter
         return true;
      }

      public boolean accept(File director, String name) {
         // For FilenameFilter
         return true;
      }

      public String getDescription() {
         // For FileFilter
         return "My filter description.";
      }
  }

      • _fileMenu

        protected javax.swing.JMenu _fileMenu
        File menu for this frame.

      • _fileMenuItems

        protected javax.swing.JMenuItem[] _fileMenuItems
        Items in the file menu. A null element represents a separator.

      • _NEW_MENU_INDEX

        protected static int _NEW_MENU_INDEX
        Index in the _fileMenuItems array of the New item.

      • _IMPORT_MENU_INDEX

        protected static int _IMPORT_MENU_INDEX
        Index in the _fileMenuItems array of the Import item.

      • _EXPORT_MENU_INDEX

        protected static int _EXPORT_MENU_INDEX
        Index in the _fileMenuItems array of the Export item.

      • _helpMenu

        protected javax.swing.JMenu _helpMenu
        Help menu for this frame.

      • _helpMenuItems

        protected javax.swing.JMenuItem[] _helpMenuItems
        Help menu items.

      • _menubar

        protected javax.swing.JMenuBar _menubar
        Menubar for this frame.

      • _statusBar

        protected StatusBar _statusBar
        The status bar.

      • _debugClosing

        protected boolean _debugClosing
        Set to true to print closing sequence information to standard out.

    • Constructor Detail

      • Top

        public Top()
        Construct an empty top-level frame with the default status bar. After constructing this, it is necessary to call pack() to have the menus added, and then setVisible(true) to make the frame appear. It may also be desirable to call centerOnScreen(). This can be done after pack() and before setVisible().

      • Top

        public Top​(StatusBar statusBar)
        Construct an empty top-level frame with the specified status bar. After constructing this, it is necessary to call pack() to have the menus added, and then setVisible(true) to make the frame appear. It may also be desirable to call centerOnScreen(). This can be done after pack() and before setVisible().
        Parameters:
        statusBar - A status bar, or null to not insert one.

    • Method Detail

      • about

        public final void about()
        Open a dialog with basic information about this window. Derived classes may override _about().

      • centerOnScreen

        public void centerOnScreen()
        Center the window on the screen. This must be called after the window is populated with its contents, since it depends on the size being known. If this method is called from a thread that is not the AWT event dispatch thread, then its execution is deferred and performed in that thread.

      • close

        public final void close()
        Close the window, prompting the user to save changes if there have been any. Derived classes should override the protected method _close(), not this one. This method returns immediately if it is called outside the swing UI thread, deferring the action so that it is executed in the swing thread.

      • deferIfNecessary

        public static void deferIfNecessary​(java.lang.Runnable action)
        If this method is called in the AWT event dispatch thread, then simply execute the specified action. Otherwise, if there are already deferred actions, then add the specified one to the list. Otherwise, create a list of deferred actions, if necessary, and request that the list be processed in the event dispatch thread.

        Note that it does not work nearly as well to simply schedule the action yourself on the event thread because if there are a large number of actions, then the event thread will not be able to keep up. By grouping these actions, we avoid this problem.

        Parameters:
        action - The Runnable object to execute.

      • dispose

        public void dispose()
        Dispose of this frame. Override this dispose() method to unattach any listeners that may keep this model from getting garbage collected. This method invokes the dispose() method of the superclass, JFrame.
        Overrides:
        dispose in class java.awt.Window

      • exit

        public final boolean exit()
        Exit the application after querying the user to save data. Derived classes should override _exit().
        Returns:
        False if the use cancelled a saving a modified buffer, true otherwise.

      • getCentering

        public boolean getCentering()
        Return true if the window is set to be centered when pack() is called.
        Returns:
        True if the window will be centered when pack is called.
        See Also:
        setCentering(boolean)

      • getContentSize

        public java.awt.Dimension getContentSize()
        Return the size of the contents of this window.
        Returns:
        The size of the contents.

      • hideMenuBar

        public void hideMenuBar()
        If called before the first time pack() is called, this method will prevent the appearance of a menu bar. This is rarely desirable, but some subclasses of Top have to contain panels that are not swing components. Such components do not work with menus (the menu seems to appear behind the component instead of in front of it). Call this to prevent a menu bar.

      • isDisposed

        public boolean isDisposed()
        Return true if this frame has been disposed. It is possible for the dispose() method to be called directly. This may conflict with another dispose call in a window listener or somewhere else. Before Top calls super.dispose() (and thus triggering listeners) this boolean is set to true so listeners can check and make sure they aren't calling dispose for a second (or third) time.
        Returns:
        true if this frame has been disposed.

      • isMenuPopulated

        public boolean isMenuPopulated()
        Return true if the menu of this window has been populated. The menu is populated as a side effect of the first invocation to the pack() method.
        Returns:
        True if the menu bar has been populated.

      • isModified

        public boolean isModified()
        Return true if the data associated with this window has been modified since it was first read or last saved. This returns the value set by calls to setModified(), or false if that method has not been called.
        Returns:
        True if the data has been modified.

      • pack

        public void pack()
        Size this window to its preferred size and make it displayable, and override the base class to populate the menu bar if the menus have not already been populated. If the window size has not been set (by some derived class), then this will center the window on the screen. This is done here rather than in the constructor so that derived classes are assured that their constructors have been fully executed when _addMenus() is called. If this method is called outside the AWT event thread, then its execution is deferred and performed in that thread.
        Overrides:
        pack in class java.awt.Window

      • report

        public void report​(java.lang.String message)
        Report a message to the user by displaying it in a status bar, if there is one. If this method is called outside the AWT event thread, then its execution is deferred and performed in that thread.
        Parameters:
        message - The message to report.

      • report

        public void report​(java.lang.String message,
                   java.lang.Throwable throwable)
        Report a Throwable, which is usually an Exception but can also be an Error. If this method is called outside the AWT event thread, then its execution is deferred and performed in that thread. This pops up a window with the option of examining the stack trace, and reports the specified message in the status bar, if there is one.
        Parameters:
        message - The message.
        throwable - The Throwable to report.

      • report

        public void report​(java.lang.Throwable throwable)
        Report a Throwable, which is usually an Exception but can also be an Error. This displays a message in a dialog by calling the two-argument version with an empty string as the first argument. If this method is called outside the AWT event thread, then its execution is deferred and performed in that thread.
        Parameters:
        throwable - The Throwable to report
        See Also:
        report(String, Throwable)

      • setBackground

        public void setBackground​(java.awt.Color background)
        Set background color. This overrides the base class to set the background of the status bar. If this method is called outside the AWT event thread, then its execution is deferred and performed in that thread.
        Overrides:
        setBackground in class java.awt.Frame
        Parameters:
        background - The background color.

      • setCentering

        public void setCentering​(boolean centering)
        Specify whether or not to center the window on the screen when packing it. The default is true.
        Parameters:
        centering - Set to false to disable centering.
        See Also:
        getCentering()

      • setDirectory

        public static void setDirectory​(java.io.File dir)
        Set the initial default directory. If this method is not called, then the initial default directory will be the value of the user.dir Java property, which is typically the current working directory. This method allows external configuration to determine the initial/default opening/saving directory to use for file dialogs. (Used in Kepler)
        Parameters:
        dir - the initial directory to use for file dialogs

      • setModified

        public void setModified​(boolean modified)
        Record whether the data associated with this window has been modified since it was first read or last saved. If you call this with a true argument, then subsequent attempts to close the window will trigger a dialog box to confirm the closing.
        Parameters:
        modified - Indicator of whether the data has been modified.

      • show

        public void show()
        Override the base class to deiconify the window, if necessary. If this method is called outside the AWT event thread, then its execution is deferred and performed in that thread.
        Overrides:
        show in class java.awt.Window

      • status

        public void status​(java.lang.String message)
        Display the specified message in the status bar. This message will be displayed for a maximum of MAXIMUM_STATUS_MESSAGE_TIME (default 30 seconds). If there is no status bar, print to standard out.
        Specified by:
        status in interface StatusHandler
        Parameters:
        message - The message.

      • windowGainedFocus

        public void windowGainedFocus​(java.awt.event.WindowEvent event)
        Register with the global message handler to receive status messages.
        Specified by:
        windowGainedFocus in interface java.awt.event.WindowFocusListener
        Parameters:
        event - The window event.
        See Also:
        MessageHandler.status(String)

      • windowLostFocus

        public void windowLostFocus​(java.awt.event.WindowEvent event)
        Unregister with the global message handler to receive status messages.
        Specified by:
        windowLostFocus in interface java.awt.event.WindowFocusListener
        Parameters:
        event - The window event.
        See Also:
        MessageHandler.status(String)

      • _about

        protected void _about()
        Open a dialog with basic information about this window.

      • _addMenus

        protected void _addMenus()
        Add menus to the menu bar. In this base class, this does nothing. In derived classes, however, it will add items with commands like 
              JMenu newMenu = new JMenu("My Menu");
      _menubar.add(newMenu);
        The reason for doing this in a protected method rather than doing it directly in the constructor of the base class is subtle. Unfortunately, at this time, Java provides no mechanism for derived classes to insert menus at arbitrary points in the menu bar. Also, the menubar ignores the alignment property of the JMenu. By convention, however, we want the help menu to be the rightmost menu. Thus, we use a strategy pattern here, and call a protected method that derived classes can use to add menus. Thus, this method is called before the Help menu is added, and hence menus added in this method will appear to the left of the Help menu.

      • _clear

        protected boolean _clear()
        Clear the current contents. This base class checks to see whether the contents have been modified, and if so, then prompts the user to save them. Derived classes should override this method to first call this parent class method, then clear the data, unless the return value is false. A return value of false indicates that the user has canceled the action.
        Returns:
        True if the current contents are either saved or discarded with permission from the user.

      • _close

        protected boolean _close()
        Close the window. Derived classes should override this to release any resources or remove any listeners. In this class, if the data associated with this window has been modified, as indicated by isModified(), then ask the user whether to save the data before closing.
        Returns:
        False if the user cancels on a save query.

      • _createFileMenuItems

        protected javax.swing.JMenuItem[] _createFileMenuItems()
        Create the items in the File menu. A null element in the array represents a separator in the menu.
        Returns:
        The items in the File menu.

      • _exit

        protected void _exit()
        Exit the application after querying the user to save data. Derived classes should override this to do something more reasonable, so that user data is not discarded.

      • _getCurrentDirectory

        protected java.io.File _getCurrentDirectory()
        Return the current directory. If setDirectory(File) or _open(), then the value of the "user.dir" property is returned.
        Returns:
        The current directory.

      • _getName

        protected java.lang.String _getName()
        Get the name of this object, which in this base class is either the name of the file that has been associated with this object, or the string "Unnamed" if none.
        Returns:
        The name.

      • _help

        protected void _help()
        Display the same information given by _about(). Derived classes should override this to give information about the particular window and its role.

      • _open

        protected void _open()
        Open a file dialog to identify a file to be opened, and then call _read() to open the file. If PtGUIUtilities.useFileDialog() return true, then java.awt.FileDialog is used. Otherwise, javax.swing.JFileChooser is used.

      • _openURL

        protected void _openURL()
        Open a dialog to enter a URL, and then invoke _read() to open the URL.

      • _print

        protected void _print()
        Print the contents. If this frame implements either the Printable or Pageable then those interfaces are used to print it.

      • _printCrossPlatform

        protected void _printCrossPlatform()
        Print using the cross platform dialog. Note that in java 1.6.0_05, the properties button is disabled, so using _printNative() is preferred.

      • _printPDF

        protected void _printPDF()
                  throws java.awt.print.PrinterException
        If a PDF printer is available print to it.
        Throws:
        java.awt.print.PrinterException - If a printer with the string "PDF" cannot be found or if the job cannot be set to the PDF print service or if there is another problem printing.

      • _printNative

        protected void _printNative()
        Print using the native dialog.

      • _queryForSave

        protected int _queryForSave()
        Open a dialog to prompt the user to save the data. Return false if the user clicks "cancel", and otherwise return true. If the user clicks "Save", this also saves the data.
        Returns:
        _SAVED if the file is saved, _DISCARDED if the modifications are discarded, _CANCELED if the operation is canceled by the user, and _FAILED if the user selects save and the save fails.

      • _read

        protected abstract void _read​(java.net.URL url)
                       throws java.lang.Exception
        Read the specified URL.
        Parameters:
        url - The URL to read.
        Throws:
        java.lang.Exception - If the URL cannot be read.

      • _save

        protected boolean _save()
        Save the model to the current file, if there is one, and otherwise invoke _saveAs(). This calls _writeFile().
        Returns:
        True if the save succeeds.

      • _saveAs

        protected boolean _saveAs()
        Query the user for a filename and save the model to that file. If PtGUIUtilities.useFileDialog() return true, then java.awt.FileDialog is used. Otherwise, javax.swing.JFileChooser is used.
        Returns:
        True if the save succeeds.

      • _saveAsFileDialog

        @Deprecated
protected javax.swing.JFileChooser _saveAsFileDialog()
        Deprecated.
        Use _saveAsJFileChooserComponent()
        Create and return a file dialog for the "Save As" command.
        Returns:
        A file dialog for save as.

      • _populateHistory

        protected void _populateHistory​(java.util.List historyList)
        Update the submenu with a history list and add a listener to each line.
        Parameters:
        historyList - The list of history items, where each element is a String is the name of the menu item.

      • _updateHistory

        protected void _updateHistory​(java.lang.String file,
                              boolean delete)
                       throws java.io.IOException
        Add the name of the last file open or set the name to the first position if already in the list.
        Parameters:
        file - name of the file to add
        delete - If true, remove from the history list, otherwise the file is added to the beginning.
        Throws:
        java.io.IOException - If the history file cannot be created, written to, or saved.

      • _writeFile

        protected abstract void _writeFile​(java.io.File file)
                            throws java.io.IOException
        Write the model to the specified file.
        Parameters:
        file - The file to write to.
        Throws:
        java.io.IOException - If the write fails.