## mars.tools
Class AbstractMarsToolAndApplication

    java.lang.Object
      java.awt.Component
          java.awt.Container
              java.awt.Window
                  java.awt.Frame
                      javax.swing.JFrame
                          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.