ptolemy.gui

Class Top

java.lang.Object

java.awt.Component

java.awt.Container

java.awt.Window

java.awt.Frame

javax.swing.JFrame

ptolemy.gui.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

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

Modifier and Type	Class and Description
(package private) class	Top.CenterOnScreenRunnable A runnable for centering the window on the screen.
(package private) class	Top.CloseWindowAdapter Listener for windowClosing action.
(package private) class	Top.CloseWindowRunnable A runnable for closing the window.
(package private) static class	Top.DeferredActionsRunnable A runnable for executing deferred actions.
(package private) class	Top.DoPackRunnable A runnable for packing the Window.
(package private) class	Top.FileMenuListener Listener for file menu commands.
(package private) class	Top.HelpMenuListener Listener for help menu commands.
(package private) class	Top.HistoryMenuListener Listener for history menu commands.
(package private) class	Top.SetBackgroundRunnable A runnable for setting the background color of the status bar.
(package private) class	Top.ShowWindowRunnable A runnable for showing the window.
(package private) class	Top.StatusBarMessageReportRunnable A runnable for setting the status bar message for a report.
(package private) class	Top.StatusBarMessageRunnable A runnable for setting the status bar message.

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 and 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, EXIT_ON_CLOSE, 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 javax.swing.WindowConstants

DISPOSE_ON_CLOSE, DO_NOTHING_ON_CLOSE, HIDE_ON_CLOSE

Fields inherited from interface java.awt.image.ImageObserver

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

Constructor Summary

Constructors

Constructor and 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

Modifier and Type	Method and 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, getPeer, 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, requestFocusInWindow, requestFocusInWindow, resize, resize, revalidate, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setMaximumSize, 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.

_saveAsFileDialogComponent

protected java.awt.FileDialog _saveAsFileDialogComponent()

Create and return a FileDialog for the "Save As" command. If PtGUIUtilities.useFileDialog() returns true, then _saveAs() uses this method. Otherwise, _saveAsJFileChooserComponent() is used.

Returns:

A file dialog for save as.

_saveAsJFileChooserComponent

protected javax.swing.JFileChooser _saveAsJFileChooserComponent()

Create and return a JFileChooser for the "Save As" command. If PtGUIUtilities.useFileDialog() returns false, then _saveAs() uses this method. Otherwise, _saveAsFileDialogComponent() is used.

Returns:

A JFileChooser 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.