Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## sim.portrayal
Class Inspector

    java.lang.Object
      java.awt.Component
          java.awt.Container
              javax.swing.JComponent
                  javax.swing.JPanel
                      sim.portrayal.Inspector

All Implemented Interfaces:
  java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible

Direct Known Subclasses:
  FieldPortrayal.CustomInspector, SimpleInspector

    public abstract class Inspector

extends javax.swing.JPanel

An Inspector is a JPanel containing information about some object, and updates its displayed information when updateInspector() is called. In-between calls to updateInspector(), the Inspector should show the same information despite repeated repaints() etc. Inspectors commonly also allow the user to change the information, but this is not required: they can be "read-only" if desired.

Volatility. Inspectors are either volatile (they change each frame) or non-volatile (they're generally static). If your inspector is not volatile, you should call setInspectorVolatile(false). It's more efficient.

Some non-volatile inspectors never have their underlying data change except when the user tweaks the inspector itself. Other non-volatile inspectors have the underlying data change but don't reflect it automatically each frame because it's expensive to update the inspector. In this second case (and for good measure the first case), you should provide a button which manually updates the inspector via updateInspector(). The easiest way to do get such a button is to call makeUpdateButton(), which will do it for you. You can then stick the button in your inspector. When pressed this button will call updateButtonPressed(), which you can override as you like (by default, updateButtonPressed() simply calls updateInspector() to update the inspector).

The Stopper. Most inspectors, particularly volatile ones, are scheduled repeating and so need to have a way to be stopped if the user closes the inspector's window or otherwise clears it out. Normally the system gets this Stoppable after scheduling the inspector repeating. Before it uses it, it first calls reviseStopper(Stoppable). This gives you a chance to "wrap" the original Stoppable in a new one which calls the original. Beware that the original Stoppable could in theory be null.

Why would you want to do this? So you can be informed of when the Stoppable has been called -- to flush a stream perhaps -- or to call the underlying Stoppable yourself for some reason. If you override this method, be sure to call super.reviseStopper(Stoppable) first, and wrap what it returns. For example:

    public Stoppable reviseStopper(Stoppable stopper)
        {
        final Stoppable newStopper = super.reviseStopper(stopper);
        return new Stoppable()
        {
        if (newStopper!=null) newStopper.stop();  // wraps the stopper
        System.out.println("Hey, I stopped!");  // do my thing
        };
        }

Beware that your stopper may and probably will have its stop() method called multiple times.

The Frame. Some inspectors are placed in separate JFrames either immediately or later on when the user requests that the inspector be "detatched". When this happens, the system will call createFrame(Stoppable) to get a JFrame with the inspector in it. The Stoppable passed in is the same one that the system received from reviseStopper(Stoppable). In most cases you probably don't need to change anything about the JFrame. But occasionally you might want to override the createFrame(Stoppable) method to revise the JFrame in some way: perhaps to change its title, say. If you do, you probably should call super.createFrame(Stoppable), and use that existing JFrame, as the super method does a few other nice things as well (such as attaching the Stoppable to the close box on the JFrame).

For example, the default version of the createFrame(Stoppable) places the Inspector in a JFrame with a scroll panel. You may not want this behavior. If this is the case, you might do something like this:

    public JFrame createFrame(Stoppable stopper)
        {
        JFrame frame = super.createFrame(stopper);
        frame.removeAll();  // get rid of scroll pane
        frame.setLayout(new BorderLayout());
        frame.add(this, BorderLayout.CENTER);  // I fill the whole frame
        frame.setTitle("I prefer this title");  // here's my new title
        frame.pack();
        }

See Also:
  Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JPanel
`javax.swing.JPanel.AccessibleJPanel`

Nested classes/interfaces inherited from class javax.swing.JComponent
`javax.swing.JComponent.AccessibleJComponent`

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.BltBufferStrategy, java.awt.Component.FlipBufferStrategy`

Field Summary
`static javax.swing.ImageIcon` | `INSPECT_ICON`
`static javax.swing.ImageIcon` | `INSPECT_ICON_P`
`static javax.swing.ImageIcon` | `UPDATE_ICON`
`static javax.swing.ImageIcon` | `UPDATE_ICON_P`

Fields inherited from class javax.swing.JComponent
`accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW`

Fields inherited from class java.awt.Component
`BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT`

Fields inherited from interface java.awt.image.ImageObserver
`ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH`

Constructor Summary
`Inspector()`

Method Summary
`javax.swing.JFrame` | `createFrame(Stoppable stopper)` Creates a scrollable frame surrounding the inspector which calls stop() on the underlying stopper when closed.
`java.lang.String` | `getTitle()` Called by the system to come up with an appropriate title for a free-floating inspector window.
`Steppable` | `getUpdateSteppable()` Called whenever the system needs to get a Steppable which, when stepped, will update the inspector and repaint it.
`boolean` | `isVolatile()` Returns true (default) if the inspector should be updated every time step.
`java.awt.Component` | `makeUpdateButton()` A convenient function to create UpdateButton which you might add to the bottom of the JPanel (assuming it still is using BorderLayout).
`Stoppable` | `reviseStopper(Stoppable stopper)` Gives the user a chance to wrap the Inspector's stopper in a larger stopper, which will then get registered with the Inspector; this larger stopper is also what is passed into Inspector.createFrame(...).
`void` | `setVolatile(boolean val)` Set to true (default) if the inspector should be updated every time step.
`protected void` | `updateButtonPressed()` If you've added an UpdateButton with makeUpdateButton(), it will call updateButtonPressed when it is pressed, which by default will call updateInspector().
`abstract void` | `updateInspector()` Called by the system to inform the Inspector that it needs to update itself to reflect any changed in the underlying data.

Methods inherited from class javax.swing.JPanel
`getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI`

Methods inherited from class javax.swing.JComponent
`addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update`

Methods inherited from class java.awt.Container
`add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, 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, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### INSPECT_ICON

    public static final javax.swing.ImageIcon INSPECT_ICON

### INSPECT_ICON_P

    public static final javax.swing.ImageIcon INSPECT_ICON_P

### UPDATE_ICON

    public static final javax.swing.ImageIcon UPDATE_ICON

### UPDATE_ICON_P

    public static final javax.swing.ImageIcon UPDATE_ICON_P

Constructor Detail

### Inspector

    public Inspector()

Method Detail

### setVolatile

    public void setVolatile(boolean val)

  Set to true (default) if the inspector should be updated every time step. Else set to false.

### isVolatile

    public boolean isVolatile()

  Returns true (default) if the inspector should be updated every time step. Else returns false.

### updateInspector

    public abstract void updateInspector()

  Called by the system to inform the Inspector that it needs to update itself to reflect any changed in the underlying data.

### getTitle

    public java.lang.String getTitle()

  Called by the system to come up with an appropriate title for a free-floating inspector window. Often this is toString() on the underlying object. Some inspectors never become free-floating and so don't need to override this method. By default this method returns an empty String.

### getUpdateSteppable

    public Steppable getUpdateSteppable()

  Called whenever the system needs to get a Steppable which, when stepped, will update the inspector and repaint it.

### updateButtonPressed

    protected void updateButtonPressed()

  If you've added an UpdateButton with makeUpdateButton(), it will call updateButtonPressed when it is pressed, which by default will call updateInspector(). Override this method if that's not the behavior you want.

### makeUpdateButton

    public java.awt.Component makeUpdateButton()

  A convenient function to create UpdateButton which you might add to the bottom of the JPanel (assuming it still is using BorderLayout). This is helpful for the user if your inspector isn't volatile.

### reviseStopper

    public Stoppable reviseStopper(Stoppable stopper)

  Gives the user a chance to wrap the Inspector's stopper in a larger stopper, which will then get registered with the Inspector; this larger stopper is also what is passed into Inspector.createFrame(...). If you override this method, be sure to call super.getRevisedStopper(stopper) and wrap *that*.

### createFrame

    public javax.swing.JFrame createFrame(Stoppable stopper)

  Creates a scrollable frame surrounding the inspector which calls stop() on the underlying stopper when closed. stopper may be null, in which case stop() is not called.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD