mars.tools
Class AbstractMarsToolAndApplication

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by java.awt.Window
              extended by java.awt.Frame
                  extended by javax.swing.JFrame
                      extended by mars.tools.AbstractMarsToolAndApplication
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Observer, Accessible, RootPaneContainer, WindowConstants, MarsTool
Direct Known Subclasses:
BHTSimulator, BitmapDisplay, CacheSimulator, DigitalLabSim, FloatRepresentation, InstructionCounter, InstructionStatistics, IntroToTools, KeyboardAndDisplaySimulator, MemoryReferenceVisualization

public abstract class AbstractMarsToolAndApplication
extends JFrame
implements MarsTool, Observer

An abstract class that provides generic components to facilitate implementation of a MarsTool and/or stand-alone Mars-based application. Provides default definitions of both the action() method required to implement MarsTool and the go() method conventionally used to launch a Mars-based stand-alone application. It also provides generic definitions for interactively controlling the application. The generic controls for MarsTools are 3 buttons: connect/disconnect to MIPS resource (memory and/or registers), reset, and close (exit). The generic controls for stand-alone Mars apps include: button that triggers a file open dialog, a text field to display status messages, the run-speed slider to control execution rate when running a MIPS program, a button that assembles and runs the current MIPS program, a button to interrupt the running MIPS program, a reset button, and an exit button. Pete Sanderson, 14 November 2006.

See Also:
Serialized Form

Nested Class Summary
protected  class AbstractMarsToolAndApplication.ConnectButton
           
protected  class AbstractMarsToolAndApplication.EnterKeyListener
           
 
Nested classes/interfaces inherited from class javax.swing.JFrame
JFrame.AccessibleJFrame
 
Nested classes/interfaces inherited from class java.awt.Frame
Frame.AccessibleAWTFrame
 
Nested classes/interfaces inherited from class java.awt.Window
Window.AccessibleAWTWindow
 
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
 
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
 
Field Summary
protected  AbstractMarsToolAndApplication.ConnectButton connectButton
           
protected  boolean isBeingUsedAsAMarsTool
           
protected  Window theWindow
           
protected  AbstractMarsToolAndApplication thisMarsApp
           
 
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
protected AbstractMarsToolAndApplication(String title, String heading)
          Simple constructor
 
Method Summary
 void action()
          Required MarsTool method to carry out Tool functions.
protected  void addAsObserver()
          Add this app/tool as an Observer of desired MIPS Observables (memory and registers).
protected  void addAsObserver(int lowEnd, int highEnd)
          Add this app/tool as an Observer of the specified subrange of MIPS memory.
protected  void addAsObserver(Register reg)
          Add this app/tool as an Observer of the specified MIPS register.
protected  JComponent buildButtonAreaMarsTool()
          The MarsTool default set of controls has one row of 3 buttons.
protected  JComponent buildButtonAreaStandAlone()
          The Mars stand-alone app default set of controls has two rows of controls.
protected  JComponent buildHeadingArea()
          Constructs GUI header as label with default positioning and font.
protected abstract  JComponent buildMainDisplayArea()
          Abstract method that must be instantiated by subclass to build the main display area of the GUI.
protected  void deleteAsObserver()
          Delete this app/tool as an Observer of MIPS Observables (memory and registers).
protected  void deleteAsObserver(Register reg)
          Delete this app/tool as an Observer of the specified MIPS register
protected  JComponent getHelpComponent()
          Override this method to provide a JComponent (probably a JButton) of your choice to be placed just left of the Close/Exit button.
abstract  String getName()
          Required MarsTool method to return Tool name.
 void go()
          Run the simulator as stand-alone application.
protected  void initializePostGUI()
          Method that will be called once just after the GUI is constructed in the go() and action() methods.
protected  void initializePreGUI()
          Method that will be called once just before the GUI is constructed in the go() and action() methods.
protected  boolean isObserving()
          Query method to let you know if the tool/app is (or could be) currently "observing" any MIPS resources.
protected  void performSpecialClosingDuties()
          This method is called when tool/app is exited either through the close/exit button or the window's X box.
protected  void processMIPSUpdate(Observable resource, AccessNotice notice)
          Override this method to process a received notice from MIPS Observable (memory or register) It will only be called if the notice was generated as the result of MIPS instruction execution.
protected  void reset()
          Method that will be called each time the default Reset button is clicked.
 void update(Observable resource, Object accessNotice)
          Called when receiving notice of access to MIPS memory or registers.
protected  void updateDisplay()
          Override this method to implement updating of GUI after each MIPS instruction is executed, while running in "timed" mode (user specifies execution speed on the slider control).
 
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, setResizable, setState, setTitle, setUndecorated
 
Methods inherited from class java.awt.Window
addPropertyChangeListener, addPropertyChangeListener, addWindowFocusListener, addWindowListener, addWindowStateListener, applyResourceBundle, applyResourceBundle, createBufferStrategy, createBufferStrategy, dispose, getBufferStrategy, getFocusableWindowState, getFocusCycleRootAncestor, getFocusOwner, getFocusTraversalKeys, getGraphicsConfiguration, getIconImages, getInputContext, getListeners, getLocale, getModalExclusionType, getMostRecentFocusOwner, getOwnedWindows, getOwner, getOwnerlessWindows, getToolkit, getWarningString, getWindowFocusListeners, getWindowListeners, getWindows, getWindowStateListeners, hide, isActive, isAlwaysOnTop, isAlwaysOnTopSupported, isFocusableWindow, isFocusCycleRoot, isFocused, isLocationByPlatform, isShowing, pack, paint, postEvent, processEvent, processWindowFocusEvent, processWindowStateEvent, removeWindowFocusListener, removeWindowListener, removeWindowStateListener, reshape, setAlwaysOnTop, setBounds, setBounds, setCursor, setFocusableWindowState, setFocusCycleRoot, setIconImages, setLocationByPlatform, setLocationRelativeTo, setMinimumSize, setModalExclusionType, setSize, setSize, setVisible, show, 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, transferFocusBackward, 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, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, 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, isOpaque, 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, setBackground, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setName, setPreferredSize, show, size, toString, transferFocus, 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

isBeingUsedAsAMarsTool

protected boolean isBeingUsedAsAMarsTool

thisMarsApp

protected AbstractMarsToolAndApplication thisMarsApp

theWindow

protected Window theWindow

connectButton

protected AbstractMarsToolAndApplication.ConnectButton connectButton
Constructor Detail

AbstractMarsToolAndApplication

protected AbstractMarsToolAndApplication(String title,
                                         String heading)
Simple constructor

Parameters:
title - String containing title bar text
Method Detail

getName

public abstract String getName()
Required MarsTool method to return Tool name. Must be defined by subclass.

Specified by:
getName in interface MarsTool
Overrides:
getName in class Component
Returns:
Tool name. MARS will display this in menu item.

buildMainDisplayArea

protected abstract JComponent buildMainDisplayArea()
Abstract method that must be instantiated by subclass to build the main display area of the GUI. It will be placed in the CENTER area of a BorderLayout. The title is in the NORTH area, and the controls are in the SOUTH area.


go

public void go()
Run the simulator as stand-alone application. For this default implementation, the user-defined main display of the user interface is identical for both stand-alone and MARS Tools menu use, but the control buttons are different because the stand-alone must include a mechansim for controlling the opening, assembling, and executing of an underlying MIPS program. The generic controls include: a button that triggers a file open dialog, a text field to display status messages, the run-speed slider to control execution rate when running a MIPS program, a button that assembles and runs the current MIPS program, a reset button, and an exit button. This method calls 3 methods that can be defined/overriden in the subclass: initializePreGUI() for any special initialization that must be completed before building the user interface (e.g. data structures whose properties determine default GUI settings), initializePostGUI() for any special initialization that cannot be completed until after the building the user interface (e.g. data structure whose properties are determined by default GUI settings), and buildMainDisplayArea() to contain application-specific displays of parameters and results.


action

public void action()
Required MarsTool method to carry out Tool functions. It is invoked when MARS user selects this tool from the Tools menu. This default implementation provides generic definitions for interactively controlling the tool. The generic controls for MarsTools are 3 buttons: connect/disconnect to MIPS resource (memory and/or registers), reset, and close (exit). Like "go()" above, this default version calls 3 methods that can be defined/overriden in the subclass: initializePreGUI() for any special initialization that must be completed before building the user interface (e.g. data structures whose properties determine default GUI settings), initializePostGUI() for any special initialization that cannot be completed until after the building the user interface (e.g. data structure whose properties are determined by default GUI settings), and buildMainDisplayArea() to contain application-specific displays of parameters and results.

Specified by:
action in interface MarsTool

initializePreGUI

protected void initializePreGUI()
Method that will be called once just before the GUI is constructed in the go() and action() methods. Use it to initialize any data structures needed for the application whose values will be needed to determine the initial state of GUI components. By default it does nothing.


initializePostGUI

protected void initializePostGUI()
Method that will be called once just after the GUI is constructed in the go() and action() methods. Use it to initialize data structures needed for the application whose values may depend on the initial state of GUI components. By default it does nothing.


reset

protected void reset()
Method that will be called each time the default Reset button is clicked. Use it to reset any data structures and/or GUI components. By default it does nothing.


buildHeadingArea

protected JComponent buildHeadingArea()
Constructs GUI header as label with default positioning and font. May be overridden.


buildButtonAreaMarsTool

protected JComponent buildButtonAreaMarsTool()
The MarsTool default set of controls has one row of 3 buttons. It includes a dual-purpose button to attach or detach simulator to MIPS memory, a button to reset the cache, and one to close the tool.


buildButtonAreaStandAlone

protected JComponent buildButtonAreaStandAlone()
The Mars stand-alone app default set of controls has two rows of controls. It includes a text field for displaying status messages, a button to trigger an open file dialog, the MARS run speed slider to control timed execution, a button to assemble and run the program, a reset button whose action is determined by the subclass reset() method, and an exit button.


update

public void update(Observable resource,
                   Object accessNotice)
Called when receiving notice of access to MIPS memory or registers. Default implementation of method required by Observer interface. This method will filter out notices originating from the MARS GUI or from direct user editing of memory or register displays. Only notices arising from MIPS program access are allowed in. It then calls two methods to be overridden by the subclass (since they do nothing by default): processMIPSUpdate() then updateDisplay().

Specified by:
update in interface Observer
Parameters:
resource - the attached MIPS resource
accessNotice - AccessNotice information provided by the resource

processMIPSUpdate

protected void processMIPSUpdate(Observable resource,
                                 AccessNotice notice)
Override this method to process a received notice from MIPS Observable (memory or register) It will only be called if the notice was generated as the result of MIPS instruction execution. By default it does nothing. After this method is complete, the updateDisplay() method will be invoked automatically.


performSpecialClosingDuties

protected void performSpecialClosingDuties()
This method is called when tool/app is exited either through the close/exit button or the window's X box. Override it to perform any special housecleaning needed. By default it does nothing.


addAsObserver

protected void addAsObserver()
Add this app/tool as an Observer of desired MIPS Observables (memory and registers). By default, will add as an Observer of the entire Data Segment in memory. Override if you want something different. Note that the Memory methods to add an Observer to memory are flexible (you can register for a range of addresses) but may throw an AddressErrorException that you need to catch. This method is called whenever the default "Connect" button on a MarsTool or the default "Assemble and run" on a stand-alone Mars app is selected. The corresponding NOTE: if you do not want to register as an Observer of the entire data segment (starts at address 0x10000000) then override this to either do some alternative or nothing at all. This method is also overloaded to allow arbitrary memory subrange.


addAsObserver

protected void addAsObserver(int lowEnd,
                             int highEnd)
Add this app/tool as an Observer of the specified subrange of MIPS memory. Note that this method is not invoked automatically like the no-argument version, but if you use this method, you can still take advantage of provided default deleteAsObserver() since it will remove the app as a memory observer regardless of the subrange or number of subranges it is registered for.

Parameters:
lowEnd - low end of memory address range.
highEnd - high end of memory address range; must be >= lowEnd

addAsObserver

protected void addAsObserver(Register reg)
Add this app/tool as an Observer of the specified MIPS register.


deleteAsObserver

protected void deleteAsObserver()
Delete this app/tool as an Observer of MIPS Observables (memory and registers). By default, will delete as an Observer of memory. Override if you want something different. This method is called when the default "Disconnect" button on a MarsTool is selected or when the MIPS program execution triggered by the default "Assemble and run" on a stand-alone Mars app terminates (e.g. when the button is re-enabled).


deleteAsObserver

protected void deleteAsObserver(Register reg)
Delete this app/tool as an Observer of the specified MIPS register


isObserving

protected boolean isObserving()
Query method to let you know if the tool/app is (or could be) currently "observing" any MIPS resources. When running as a MarsTool, this will be true by default after clicking the "Connect to MIPS" button until "Disconnect from MIPS" is clicked. When running as a stand-alone app, this will be true by default after clicking the "Assemble and Run" button until until program execution has terminated either normally or by clicking the "Stop" button. The phrase "or could be" was added above because depending on how the tool/app operates, it may be possible to run the MIPS program without first registering as an Observer -- i.e. addAsObserver() is overridden and takes no action.

Returns:
true if tool/app is (or could be) currently active as an Observer.

updateDisplay

protected void updateDisplay()
Override this method to implement updating of GUI after each MIPS instruction is executed, while running in "timed" mode (user specifies execution speed on the slider control). Does nothing by default.


getHelpComponent

protected JComponent getHelpComponent()
Override this method to provide a JComponent (probably a JButton) of your choice to be placed just left of the Close/Exit button. Its anticipated use is for a "help" button that launches a help message or dialog. But it can be any valid JComponent that doesn't mind co-existing among a bunch of JButtons.