ptolemy.vergil.actor
Class DocViewer

java.lang.Object
  java.awt.Component
      java.awt.Container
          java.awt.Window
              java.awt.Frame
                  javax.swing.JFrame
                      ptolemy.gui.Top
                          ptolemy.actor.gui.TableauFrame
                              ptolemy.actor.gui.HTMLViewer
                                  ptolemy.vergil.actor.DocViewer

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.awt.print.Printable, java.io.Serializable, java.util.EventListener, javax.accessibility.Accessible, javax.swing.event.HyperlinkListener, javax.swing.RootPaneContainer, javax.swing.WindowConstants

public class DocViewer
extends HTMLViewer

This class defines a specialized window for displaying Ptolemy II actor documentation. The three versions of the constructor offer mechanisms to display documentation for a particular actor instance or a specified actor class name, or to display a specified documentation file. The documentation file is expected to be an XML file using the DocML schema, as defined in the DocManager class.

Since:

Ptolemy II 5.2

Version:

$Id: DocViewer.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Edward A. Lee

See Also:

DocManager, Serialized Form

Accepted Rating:

Red (cxh)

Proposed Rating:

Yellow (eal)

Nested Class Summary

private class

DocViewer.BuildMenuListener Listener for build menu commands.

Nested classes/interfaces inherited from class ptolemy.actor.gui.TableauFrame

TableauFrame.ExtensionFileFilter

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

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

private java.lang.String	_applicationName The name of the application, usually from the _applicationName StringAttribute in configuration.xml.
private static int	_AUTHOR_WINDOW_WIDTH Author window width.
private static int	_BOTTOM_HEIGHT Bottom window height.
private Configuration	_configuration The configuration specified in the constructor.
private static int	_DESCRIPTION_WIDTH Width of the description pane.
private java.awt.Font	_font The font to use for No icon available message.
private GraphPane	_graphPane The graph pane.
private static java.lang.String	_HTML_HEADER HTML Header information.
private static java.lang.String	_HTML_TAIL
private static int	_ICON_WINDOW_HEIGHT Icon window width.
private static int	_ICON_WINDOW_WIDTH Icon window width.
private CompositeEntity	_iconContainer The composite entity containing the icon.
private JGraph	_jgraph The jgraph.
private static int	_MAIN_WINDOW_HEIGHT Main window height.
private static int	_MAIN_WINDOW_WIDTH Main window width.
private static int	_PADDING Padding in icon window.
private static int	_SEE_ALSO_WIDTH Width of the see also pane.
private static int	_SPACING Spacing between subwindows.
private static java.lang.String	_tableClosing
private static java.lang.String	_tableOpening
private NamedObj	_target The target given in the constructor, if any.
private static java.lang.String	_td
private static java.lang.String	_td20
private static java.lang.String	_tdColSpan
private static java.lang.String	_tde
private static java.lang.String	_tr
private static java.lang.String	_tre

Fields inherited from class ptolemy.actor.gui.HTMLViewer

_scroller, pane

Fields inherited from class ptolemy.actor.gui.TableauFrame

_initialSaveAsFileName, _viewMenu, aboutFile, helpFile

Fields inherited from class ptolemy.gui.Top

_CANCELED, _directory, _DISCARDED, _FAILED, _fileFilter, _fileMenu, _fileMenuItems, _helpMenu, _helpMenuItems, _menubar, _SAVED, _statusBar

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 java.awt.print.Printable

NO_SUCH_PAGE, PAGE_EXISTS

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

DocViewer(NamedObj target, Configuration configuration)
Construct a documentation viewer for the specified target.

DocViewer(java.lang.String className, Configuration configuration)
Construct a documentation viewer for the specified class name.

DocViewer(java.net.URL url, Configuration configuration)
Construct a documentation viewer for the specified documentation file.

Method Summary

protected void	_addMainPane() Override the base class to do nothing.
protected void	_addMenus() Add a Build menu item.
private void	_adjustIconDisplay(NamedObj sample, CompositeEntity container, GraphPane graphPane, JGraph jgraph) Adjust the icon display for the specified target.
private java.lang.String	_colorizeRating(java.lang.String rating) Return HTML that colorizes the rating text.
private java.lang.String	_getParameterEntries(NamedObj target, DocManager manager) Return a string with parameter table entries.
private java.lang.String	_getPortEntries(NamedObj target, DocManager manager) Return a string with port table entries.
private java.lang.String	_getPortParameterEntries(NamedObj target, DocManager manager) Return a string with port-parameter table entries.
protected void	_help() Display the help file given by the configuration, or if there is none, then the file specified by the public variable helpFile.
private void	_includeClassDefinitions(NamedObj target, java.lang.StringBuffer buffer) Append to the specified buffer any locally defined base classes that are needed to define the specified target.
private void	_init(NamedObj target, Configuration configuration, java.lang.String className, java.net.URL url) Construct a documentation viewer for the specified target, class name, or URL.
private void	_populatePortsAndParametersTable(NamedObj target, DocManager manager) Populate the window displaying ports and parameters.
protected void	_setScrollerSize(int width, int height) Override the base class to do nothing.
Configuration	getConfiguration() Get the configuration specified in the constructor.
void	hyperlinkUpdate(javax.swing.event.HyperlinkEvent event) Override the base class to react to links of the form #parentClass.

Methods inherited from class ptolemy.actor.gui.HTMLViewer

_writeFile, getPage, print, setBase, setPage, setSize, setText

Methods inherited from class ptolemy.actor.gui.TableauFrame

_about, _close, _confirmFile, _exit, _getDefaultIconImage, _getName, _read, _save, _saveAs, _saveAs, _saveAsHelper, getAlternateTopPack, getDirectory, getEffigy, getEffigy, getTableau, isModified, pack, printPDF, setModified, setTableau

Methods inherited from class ptolemy.gui.Top

_clear, _createFileMenuItems, _getCurrentDirectory, _open, _openURL, _print, _printCrossPlatform, _printNative, _printPDF, _queryForSave, _saveAsFileDialog, centerOnScreen, close, deferIfNecessary, getCentering, hideMenuBar, isMenuPopulated, report, report, report, setBackground, setCentering, setDirectory, show

Methods inherited from class javax.swing.JFrame

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

Methods inherited from class java.awt.Frame

addNotify, finalize, 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, getInputContext, getListeners, getLocale, getMostRecentFocusOwner, getOwnedWindows, getOwner, getToolkit, getWarningString, getWindowFocusListeners, getWindowListeners, getWindowStateListeners, hide, isActive, isAlwaysOnTop, isFocusableWindow, isFocusCycleRoot, isFocused, isLocationByPlatform, isShowing, postEvent, processEvent, processWindowFocusEvent, processWindowStateEvent, removeWindowFocusListener, removeWindowListener, removeWindowStateListener, setAlwaysOnTop, setBounds, setCursor, setFocusableWindowState, setFocusCycleRoot, setLocationByPlatform, setLocationRelativeTo, 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, paint, 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, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, 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, 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, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBounds, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setVisible, show, size, toString, transferFocus, transferFocusUpCycle

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

_applicationName

private java.lang.String _applicationName

The name of the application, usually from the _applicationName StringAttribute in configuration.xml. If the value is the empty string, then use the default documentation in doc/codeDoc.

_AUTHOR_WINDOW_WIDTH

private static int _AUTHOR_WINDOW_WIDTH

Author window width.

_configuration

private Configuration _configuration

The configuration specified in the constructor.

_BOTTOM_HEIGHT

private static int _BOTTOM_HEIGHT

Bottom window height.

_DESCRIPTION_WIDTH

private static int _DESCRIPTION_WIDTH

Width of the description pane.

_font

private java.awt.Font _font

The font to use for No icon available message.

_graphPane

private GraphPane _graphPane

The graph pane.

_HTML_HEADER

private static java.lang.String _HTML_HEADER

HTML Header information.

_HTML_TAIL

private static java.lang.String _HTML_TAIL

_iconContainer

private CompositeEntity _iconContainer

The composite entity containing the icon.

_ICON_WINDOW_HEIGHT

private static int _ICON_WINDOW_HEIGHT

Icon window width.

_ICON_WINDOW_WIDTH

private static int _ICON_WINDOW_WIDTH

Icon window width.

_jgraph

private JGraph _jgraph

The jgraph.

_MAIN_WINDOW_HEIGHT

private static int _MAIN_WINDOW_HEIGHT

Main window height.

_MAIN_WINDOW_WIDTH

private static int _MAIN_WINDOW_WIDTH

Main window width.

_PADDING

private static int _PADDING

Padding in icon window.

_SEE_ALSO_WIDTH

private static int _SEE_ALSO_WIDTH

Width of the see also pane.

_SPACING

private static int _SPACING

Spacing between subwindows.

_target

private NamedObj _target

The target given in the constructor, if any.

_tr

private static java.lang.String _tr

_tre

private static java.lang.String _tre

_td

private static java.lang.String _td

_td20

private static java.lang.String _td20

_tdColSpan

private static java.lang.String _tdColSpan

_tde

private static java.lang.String _tde

_tableOpening

private static java.lang.String _tableOpening

_tableClosing

private static java.lang.String _tableClosing

Constructor Detail

DocViewer

public DocViewer(NamedObj target,
                 Configuration configuration)

Construct a documentation viewer for the specified target.

Parameters:

target - The object to get documentation for.

configuration - The configuration in charge of this viewer.

DocViewer

public DocViewer(java.lang.String className,
                 Configuration configuration)
          throws java.lang.ClassNotFoundException

Construct a documentation viewer for the specified class name.

Parameters:

className - The class name to get documentation for.

configuration - The configuration in charge of this viewer.

Throws:

java.lang.ClassNotFoundException - If the class cannot be found.

DocViewer

public DocViewer(java.net.URL url,
                 Configuration configuration)

Construct a documentation viewer for the specified documentation file.

Parameters:

url - The URL at which to find the documentation.

configuration - The configuration in charge of this viewer.

Method Detail

getConfiguration

public Configuration getConfiguration()

Get the configuration specified in the constructor.

Overrides:

getConfiguration in class TableauFrame

Returns:

The configuration controlling this frame, or null if there isn't one.

hyperlinkUpdate

public void hyperlinkUpdate(javax.swing.event.HyperlinkEvent event)

Override the base class to react to links of the form #parentClass.

Specified by:

hyperlinkUpdate in interface javax.swing.event.HyperlinkListener

Overrides:

hyperlinkUpdate in class HTMLViewer

Parameters:

event - The hyperlink event.

_addMainPane

protected void _addMainPane()

Override the base class to do nothing. The main content pane is added after the top content.

Overrides:

_addMainPane in class HTMLViewer

_help

protected void _help()

Display the help file given by the configuration, or if there is none, then the file specified by the public variable helpFile. To specify a default help file in the configuration, create a FileParameter named "_helpDocViewer" whose value is the name of the file. If the specified file fails to open, then invoke the _help() method of the superclass.

Overrides:

_help in class TableauFrame

See Also:

FileParameter

_setScrollerSize

protected void _setScrollerSize(int width,
                                int height)

Override the base class to do nothing.

Overrides:

_setScrollerSize in class HTMLViewer

Parameters:

width - The width.

height - The width.

_adjustIconDisplay

private void _adjustIconDisplay(NamedObj sample,
                                CompositeEntity container,
                                GraphPane graphPane,
                                JGraph jgraph)
                         throws IllegalActionException,
                                NameDuplicationException

Adjust the icon display for the specified target.

Parameters:

sample - The instance whose icon is displayed.

container - The container of the sample instance.

graphPane - The graph pane in which it is displayed.

jgraph - The jgraph.

Throws:

IllegalActionException

NameDuplicationException

_colorizeRating

private java.lang.String _colorizeRating(java.lang.String rating)

Return HTML that colorizes the rating text.

Parameters:

rating - The rating text, such as "Red (mrptolemy)"

Returns:

HTML, such as "Red (mrptolemy)"

_getParameterEntries

private java.lang.String _getParameterEntries(NamedObj target,
                                              DocManager manager)

Return a string with parameter table entries.

Parameters:

target - The target.

manager - The manager.

Returns:

Parameter table entries, or null if there are no parameters.

_getPortEntries

private java.lang.String _getPortEntries(NamedObj target,
                                         DocManager manager)

Return a string with port table entries.

Parameters:

target - The target.

manager - The manager.

Returns:

Port table entries, or null if there are no ports.

_getPortParameterEntries

private java.lang.String _getPortParameterEntries(NamedObj target,
                                                  DocManager manager)

Return a string with port-parameter table entries.

Parameters:

target - The target.

manager - The manager.

Returns:

Port-parameter table entries, or null if there are no port-parameters.

_includeClassDefinitions

private void _includeClassDefinitions(NamedObj target,
                                      java.lang.StringBuffer buffer)

Append to the specified buffer any locally defined base classes that are needed to define the specified target.

Parameters:

target - The target whose parent may need to be included.

buffer - The buffer to append the definition to.

_init

private void _init(NamedObj target,
                   Configuration configuration,
                   java.lang.String className,
                   java.net.URL url)
            throws java.lang.ClassNotFoundException

Construct a documentation viewer for the specified target, class name, or URL. Normally, one of these three arguments will be non-null.

Parameters:

target - The object to get documentation for, or null to base this on the specified class name.

configuration - The configuration in charge of this viewer.

className - The class name of the target, or null if a target is given.

url - The URL from which to read the doc file, or null to infer it from the target or className.

Throws:

java.lang.ClassNotFoundException

_addMenus

protected void _addMenus()

Add a Build menu item.

Overrides:

_addMenus in class TableauFrame

_populatePortsAndParametersTable

private void _populatePortsAndParametersTable(NamedObj target,
                                              DocManager manager)

Populate the window displaying ports and parameters.

Parameters:

target - The target object whose ports and parameters will be described.

manager - The doc manager.