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:

javax.accessibility.Accessible, java.awt.image.ImageObserver, java.awt.MenuContainer, javax.swing.RootPaneContainer, java.io.Serializable, javax.swing.WindowConstants

public abstract class Top

extends javax.swing.JFrame

This is a top-level window with a menubar and 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, SaveAs, 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: Top.java,v 1.48 2002/07/22 22:01:38 eal Exp $

Author:

Edward A. Lee and Steve Neuendorffer

See Also:

Serialized Form

Inner classes inherited from class javax.swing.JFrame

javax.swing.JFrame.AccessibleJFrame

Inner classes inherited from class java.awt.Frame

java.awt.Frame.AccessibleAWTFrame

Inner classes inherited from class java.awt.Window

java.awt.Window.AccessibleAWTWindow

Inner classes inherited from class java.awt.Container

java.awt.Container.AccessibleAWTContainer

Inner classes inherited from class java.awt.Component

java.awt.Component.AccessibleAWTComponent

Field Summary

protected static java.io.File	_directory The most recent directory used in a file dialog.
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 javax.swing.JMenu	_helpMenu Help menu for this frame.
protected javax.swing.JMenuItem[]	_helpMenuItems Help menu items.
protected javax.swing.JMenuBar	_menubar Menubar for this frame.
protected StatusBar	_statusBar The status bar.

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, 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

Top()
Construct an empty top-level frame.

Method Summary

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 void	_exit() Exit the application after querying the user to save data.
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" is 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	_print() Print the contents.
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 abstract void	_writeFile(java.io.File file) Write the model to the specified file.
void	centerOnScreen() Center the window on the screen.
static java.lang.String	getLastOverallURL() Return the most recently entered URL in the most recently invoked Open URL dialog box.
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.Exception ex) Report an exception.
void	report(java.lang.String message) Report a message to the user by displaying it in a status bar.
void	report(java.lang.String message, java.lang.Exception ex) Report an exception.
void	setBackground(java.awt.Color background) Set background color.
static void	setLastOverallURL(java.lang.String lastOverallURL) Set the value of the last overall URL.
void	setModified(boolean modified) Record whether the data associated with this window has been modified since it was first read or last saved.

Methods inherited from class javax.swing.JFrame

addImpl, createRootPane, frameInit, getAccessibleContext, getContentPane, getDefaultCloseOperation, getGlassPane, getJMenuBar, getLayeredPane, getRootPane, isRootPaneCheckingEnabled, paramString, processKeyEvent, processWindowEvent, remove, setContentPane, setDefaultCloseOperation, setGlassPane, setJMenuBar, setLayeredPane, setLayout, setRootPane, setRootPaneCheckingEnabled, update

Methods inherited from class java.awt.Frame

addNotify, finalize, getCursorType, getFrames, getIconImage, getMenuBar, getState, getTitle, isResizable, remove, removeNotify, setCursor, setIconImage, setMenuBar, setResizable, setState, setTitle

Methods inherited from class java.awt.Window

addWindowListener, applyResourceBundle, applyResourceBundle, dispose, getFocusOwner, getGraphicsConfiguration, getInputContext, getListeners, getLocale, getOwnedWindows, getOwner, getToolkit, getWarningString, hide, isShowing, postEvent, processEvent, removeWindowListener, setCursor, show, toBack, toFront

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getInsets, getLayout, getMaximumSize, getMinimumSize, getPreferredSize, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paint, paintComponents, preferredSize, print, printComponents, processContainerEvent, remove, removeAll, removeContainerListener, setFont, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addPropertyChangeListener, addPropertyChangeListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, getBackground, getBounds, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getGraphics, getHeight, getInputMethodRequests, getLocation, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getSize, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isDisplayable, isDoubleBuffered, isEnabled, isFocusTraversable, isLightweight, isOpaque, 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, processMouseEvent, processMouseMotionEvent, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, reshape, resize, resize, setBounds, setBounds, setComponentOrientation, setDropTarget, setEnabled, setForeground, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, size, toString, transferFocus

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.awt.MenuContainer

getFont, postEvent

Field Detail

_directory

protected static java.io.File _directory

The most recent directory used in a file dialog.

_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.

_fileMenu

protected javax.swing.JMenu _fileMenu

File menu for this frame.

_fileMenuItems

protected javax.swing.JMenuItem[] _fileMenuItems

Items in the file menu.

_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.

Constructor Detail

Top

public Top()

Construct an empty top-level frame. 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().

Method Detail

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.

getLastOverallURL

public static java.lang.String getLastOverallURL()

Return the most recently entered URL in the most recently invoked Open URL dialog box. Note that each Top has its own last url, this method returns the value of the last Open URL dialog. If the Open URL menu choice has not yet been invoked, then return null.

The value returned by getLastOverallURL() is used by MoMLParser to determine whether we should display a Security concern dialog and ask the user if they want to download a model from outside the value of getLastOverallURL().

Returns:

the most recently entered URL in the most recently invoked Open URL dialog box.

See Also:

setLastOverallURL(java.lang.String)

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.

report

public void report(java.lang.Exception ex)

Report an exception. This displays a message in a dialog by calling the two-argument version with an empty string as the first argument.

Parameters:

ex - The exception to report.

See Also:

report(String, Exception)

report

public void report(java.lang.String message)

Report a message to the user by displaying it in a status bar.

Parameters:

message - The message to report.

report

public void report(java.lang.String message,
                   java.lang.Exception ex)

Report an exception. This pops up a window with the option of examining the stack trace.

Parameters:

message - The message.

ex - The exception to report.

setBackground

public void setBackground(java.awt.Color background)

Set background color. This overrides the base class to set the background of contained ModelPane.

Overrides:

setBackground in class java.awt.Component

Parameters:

background - The background color.

setLastOverallURL

public static void setLastOverallURL(java.lang.String lastOverallURL)

Set the value of the last overall URL.

Parameters:

lastOverallURL - The last overall URL

See Also:

getLastOverallURL()

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.

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

Overrides:

pack in class java.awt.Window

_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:

False if the user cancels the clear.

_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.

_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.

_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" is 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.

_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.

_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.

Returns:

True if the save succeeds.

_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.