HiRISE

HiRISE.HiPlan.Help
Class Help_Viewer

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 HiRISE.HiPlan.Help.Help_Viewer
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, EventListener, Accessible, HyperlinkListener, RootPaneContainer, WindowConstants

public class Help_Viewer
extends JFrame
implements HyperlinkListener

A simple help viewer. The viewer has two panes: an index pane and a content pane. Each pane can display HTML, RTF, or plain text; "file:" protocol hyperlinks clicked in either pane open their targets in the content pane (see Protocols, below). A status bar at the bottom of the frame indicates the target of any hyperlink hovered over in either of the panes.

The viewer operates as a standalone application, a JFrame dialog, or a modal JDialog. In each case, the viewer is supplied at initial construction with a URL for the index pane and for the content pane. If the index pane URL is null, the index pane is removed from the viewer. If the content pane URL is null, the content pane is retained but is blank. The URLs can also be derived from a reference class and a set of constants: Constants.RESOURCES_DIRECTORY, DEFAULT_INDEX_URL, and DEFAULT_CONTENT_URL.

As a Standalone Application

To use the help viewer as a standalone application, invoke it on the command line as with any Java application:

java [-cp classpath] HiRISE.HiPlan.Help.Help_Viewer [--class className] [--index indexUrl] [--content contentUrl] [--title title]

Without any of the command-line options, the help viewer is invoked with no index pane and a blank content pane; it has the title "HiPlan Help."

The --class option loads the viewer's index and content panes from URLs generated by the class loader. The default path to the index file is resources/help/index.html, rooted at className's location. The default path to the content file is resources/help/main.html, also rooted at className's location. The --class option also sets the viewer's title based on the simple name of the indicated class.

Example: With the option --class HiRISE.HiPlan.HOGG.HOGG, the index file is loaded from HiRISE/HiPlan/HOGG/resources/help/index.html, wherever the HiRISE.HiPlan.HOGG package is found in the classpath. The viewer's title is "HOGG Help."

The --index option loads the index pane from indexUrl. If combined with the --class option, the URL is assumed to be relative to the className's class path as determined by the class loader.

The --content option loads the content pane from contentUrl. If combined with the --class option, the URL is assumed to be relative to the className's class path as determined by the class loader.

Examples: The options --class HiRISE.HiPlan.HOGG.HOGG --index foo.html will cause the help viewer to load the index pane from HiRISE/HiPlan/HOGG/foo.html. The options --class HiRISE.HiPlan.HOGG.HOGG --content bar.html will cause the help viewer to load the content pane from HiRISE/HiPlan/HOGG/bar.html.

The --title option overrides the application's default window title. The default title is either "HiPlan Help" or the simple name of the className if supplied.

As a JFrame Dialog

To use the help viewer as a modeless JFrame dialog, intantiate it with a reference class from which the help viewer's title and index and content URLs will be derived. The title is derived from the reference class's simple name. The URLs are generated by the class loader from the reference class's path, to which is appended resources and either help/index.html or help/main.html. Set the viewer to visible to display.

Example:

    final Help_Viewer viewer = new Help_Viewer(HiRISE.HiPlan.HOGG.HOGG.class);
    Action showHelp = new AbstractAction("Help") {
        public void actionPerformed(ActionEvent e) {
            viewer.setVisible(true);
        }
    };
    JMenuItem item = new JMenuItem(showHelp);

Alternatively, instantiate it with a custom title, index URL, and content URL.

Example:

    Class hogg = HiRISE.HiPlan.HOGG.HOGG.class;
    URL indexUrl = hogg.getResource(
        Constants.RESOURCES_DIRECTORY + "/" + Help_Viewer.DEFAULT_INDEX_URL
    );
    URL contentUrl = hogg.getResource(
        Constants.RESOURCES_DIRECTORY + "/" + Help_Viewer.DEFAULT_CONTENT_URL
    );
    final Help_Viewer viewer = new Help_Viewer(
        hogg.getSimpleName(), indexUrl, contentUrl
    );
    Action showHelp = new AbstractAction("Help") {
        public void actionPerformed(ActionEvent e) {
            viewer.setVisible(true);
        }
    };
    JMenuItem item = new JMenuItem(showHelp);

As a Modal JDialog

To use the help viewer as a modal JDialog instead of as a modeless JFrame, a showDialog(Dialog) method is provided. This method embeds the help viewer in a JDialog. To use, instantiate the help viewer with a reference class as above and invoke the showDialog method.

Example:

    final HOGG_Dialog hogg = new HOGG_Dialog();
    final Help_Viewer viewer = new Help_Viewer(HiRISE.HiPlan.HOGG.HOGG.class);
    Action showHelp = new AbstractAction("Help") {
        public void actionPerformed(ActionEvent e) {
            viewer.showDialog(hogg);
        }
    };
    JMenuItem item = new JMenuItem(showHelp);

Protocols

The help viewer handles file protocol URLs itself; their contents are displayed in its content pane.

http protocol URLs are passed off to an external web browser if possible; if not, the operator is presented with a dialog indicating this fact that includes the target URL. The operator can copy this URL and paste it into a browser manually.

Other protocol URLs are not handled at all. An error dialog indicates this fact and presents the operator with the target URL. The operator can copy and paste this URL into an appropriate browser if desired.

Version:
1.27
Author:
Christian Schaller - UA/PIRL
See Also:
JEditorPane, Serialized Form

Nested Class Summary
 
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
static String DEFAULT_CONTENT_URL
          The default content URL.
static String DEFAULT_INDEX_URL
          The default index URL.
static String DEFAULT_TITLE
          The default title for the dialog window.
static int FAILURE
          Exit status when the application fails.
static String FILE_PROTOCOL_PREFIX
          The starting text for a URL file protocol.
static String HTTP_PROTOCOL_PREFIX
          The starting text for a URL HTTP protocol.
static String ID
          Class identification name with source code version and date.
static String STANDALONE_PROPERTY
          The system property whose value is "true" if the help viewer should be started up in standalone mode.
static int SUCCESS
          Exit status when the application succeeds.
 
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
Help_Viewer()
          Creates a new help viewer frame with a default title.
Help_Viewer(Class referenceClass)
          Creates a new help viewer based on the input reference class.
Help_Viewer(String title)
          Creates a new help viewer frame with the indicated title.
Help_Viewer(String title, URL indexUrl, URL contentUrl)
          Creates a new help viewer frame with the indicated title.
Help_Viewer(URL indexUrl, URL contentUrl)
          Creates a new help viewer frame with a default title.
 
Method Summary
 URL getContentUrl()
          Gets the URL for the contents of the content pane.
 URL getIndexUrl()
          Gets the URL for the contents of the index pane.
 void handleAbout()
          Handles a request to display the application About dialog.
 boolean handleMacQuit()
          Handles a request to quit as generated by the Mac-supplied Quit menu item.
 void hyperlinkUpdate(HyperlinkEvent e)
          Receives hyperlink events and handles them appropriately.
static void main(String[] args)
          Invokes a standalone application version of the help viewer in its own thread.
 void setContentUrl(URL contentUrl)
          Sets the URL for the contents of the content pane and loads the content pane with that content.
 void setIndexUrl(URL indexUrl)
          Sets the URL for the contents of the index pane and loads the index pane with that content.
 void showDialog(Dialog owner)
          Displays the help viewer in a modeless dialog instead of in its default window.
 
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, 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, 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

ID

public static final String ID
Class identification name with source code version and date.

See Also:
Constant Field Values

DEFAULT_INDEX_URL

public static final String DEFAULT_INDEX_URL
The default index URL.

See Also:
Constant Field Values

DEFAULT_CONTENT_URL

public static final String DEFAULT_CONTENT_URL
The default content URL.

See Also:
Constant Field Values

HTTP_PROTOCOL_PREFIX

public static final String HTTP_PROTOCOL_PREFIX
The starting text for a URL HTTP protocol.

See Also:
Constant Field Values

FILE_PROTOCOL_PREFIX

public static final String FILE_PROTOCOL_PREFIX
The starting text for a URL file protocol.

See Also:
Constant Field Values

DEFAULT_TITLE

public static final String DEFAULT_TITLE
The default title for the dialog window.

See Also:
Constant Field Values

STANDALONE_PROPERTY

public static final String STANDALONE_PROPERTY
The system property whose value is "true" if the help viewer should be started up in standalone mode. If the viewer is in standalone mode, the application gets an actual Quit menu item (in addition to a Close menu item). On a Mac, the standalone viewer gets a custom icon for the Dock and the Mac application switcher, and it behaves more like a Mac application in general.

See Also:
Constant Field Values

SUCCESS

public static final int SUCCESS
Exit status when the application succeeds.

See Also:
Constant Field Values

FAILURE

public static final int FAILURE
Exit status when the application fails.

See Also:
Constant Field Values
Constructor Detail

Help_Viewer

public Help_Viewer(Class referenceClass)
Creates a new help viewer based on the input reference class.

The viewer's title is set to the class's simple name plus Help. For example, with a referenceClass of HiRISE.HiPlan.HOGG.HOGG, the title is "HOGG Help."

The viewer's index URL and initial content URL are generated by the class loader. The path to the index file is resources/help/index.html. The path to the content file is resources/help/main.html. Both are rooted at referenceClass's location.

Parameters:
referenceClass - The reference class from which the help viewer's title and URLs are derived. May not be null.
See Also:
Constants.RESOURCES_DIRECTORY, DEFAULT_INDEX_URL, DEFAULT_CONTENT_URL

Help_Viewer

public Help_Viewer(String title,
                   URL indexUrl,
                   URL contentUrl)
Creates a new help viewer frame with the indicated title. The index pane's contents are loaded from the indexUrl. The content pane's contents are loaded from the contentUrl.

If the title is null, the DEFAULT_TITLE will be used instead. If the index URL is null, the index pane will not be displayed. If the content URL is null, the content pane will be displayed with a blank document.

Parameters:
title - the frame title.
indexUrl - the URL from which the index pane's contents are loaded.
contentUrl - the URL from which the content pane's contents are loaded.

Help_Viewer

public Help_Viewer(URL indexUrl,
                   URL contentUrl)
Creates a new help viewer frame with a default title. The index pane's contents are loaded from the indexUrl. The content pane's contents are loaded from the contentUrl.

Parameters:
indexUrl - the URL from which the index pane's contents are loaded.
contentUrl - the URL from which the content pane's contents are loaded.
See Also:
Help_Viewer(String,URL,URL)

Help_Viewer

public Help_Viewer(String title)
Creates a new help viewer frame with the indicated title. The frame will have no index pane and an initial blank content pane.

Parameters:
title - the frame title.
See Also:
Help_Viewer(String,URL,URL)

Help_Viewer

public Help_Viewer()
Creates a new help viewer frame with a default title. The frame will have no index pane and an initial blank content pane.

See Also:
Help_Viewer(String,URL,URL)
Method Detail

getIndexUrl

public URL getIndexUrl()
Gets the URL for the contents of the index pane.

Returns:
the index URL; may be null.

setIndexUrl

public void setIndexUrl(URL indexUrl)
Sets the URL for the contents of the index pane and loads the index pane with that content. If the index pane does not exist, because the viewer was created with an index pane, this method does nothing. If the URL is null, this method does nothing.

Parameters:
indexUrl - the new index URL to set.

getContentUrl

public URL getContentUrl()
Gets the URL for the contents of the content pane.

Returns:
the content URL; may be null.

setContentUrl

public void setContentUrl(URL contentUrl)
Sets the URL for the contents of the content pane and loads the content pane with that content. If the URL is null, this method does nothing; it does not even clear the frame.

Parameters:
contentUrl - the new content URL to set.

hyperlinkUpdate

public void hyperlinkUpdate(HyperlinkEvent e)
Receives hyperlink events and handles them appropriately.

Events of type ENTERED trigger a status bar update that reports the URL's target in the help viewer's status bar.

Events of type EXITED clear the status bar.

Events of type ACTIVATED are handled in one of three ways. If the URL is a file URL, the indicated resource is loaded into the content panel, regardless of the event's source. If the URL is an HTTP protocol URL (or HTTPS), an attempt is made to load it into an external browser; if the attempt fails, a message with the URL is presented to the operator. If the URL is of some other protocol, a message with the URL is presented to the operator.

The third-party BrowserLauncher utility is used for handing URLs off to external browsers. It is invoked via reflection as either edu.asu.jmars.util.BrowserLauncher or edu.stanford.ejalbert.BrowserLauncher. If the launcher is not found in the classpath, a message with the URL is presented to the operator. (The launcher is included in the JMARS distribution, so it is likely able to be found.)

Specified by:
hyperlinkUpdate in interface HyperlinkListener
Parameters:
e - the hyperlink event.

handleAbout

public void handleAbout()
Handles a request to display the application About dialog. This method is called when the operator selects the About menu item in HiTemp's Help menu.

On a Mac, an About menu item is also supplied in the application menu. A Mac_Adapter registers this method as the handler for the Apple event generated by this menu item.

This method is exposed for access by the Mac Adapter.


handleMacQuit

public boolean handleMacQuit()
Handles a request to quit as generated by the Mac-supplied Quit menu item.

This method is exposed for access by the Mac Adapter.

Returns:
true.

showDialog

public void showDialog(Dialog owner)
Displays the help viewer in a modeless dialog instead of in its default window. The dialog is owned by the indicated owner. The dialog's state is persistent, so subsequent viewings keep the help information at the last viewed position.

Parameters:
owner - the non-null dialog owner for the help viewer dialog.

main

public static void main(String[] args)
Invokes a standalone application version of the help viewer in its own thread.

Usage

java [-cp classpath] HiRISE.HiPlan.Help.Help_Viewer [--class className] [--index indexUrl] [--content contentUrl] [--title title]

Options are not case-sensitive and may be reduced to their shortest unique form. One or two dashes may be used.

Options

--class className
Sets a reference (fully qualified) class name; the viewer application uses this to find bundled help files.
--index indexUrl
Sets the index pane URL; the default value is null.
--content contentUrl
Sets the content pane URL; the default value is null.
--title title
Sets the viewer's title. The default title is DEFAULT_TITLE.

The indexUrl and contentUrl are straightforward on their own: they set the contents of the index and content panes, respectively.

If className is used on its own, the viewer's index and content panes are loaded from URLs generated by the class loader. The path to the index file is the class name plus Constants.RESOURCES_DIRECTORY plus DEFAULT_INDEX_URL. The content file is likewise constructed from DEFAULT_CONTENT_URL.

If className is used in conjunction with indexUrl or contentUrl, the index or content URL will be appended to the class name's URL from the class loader. If only one such URL is provided, the other pane will be loaded as above.

If title is not specified, DEFAULT_TITLE will be used unless className is used. If the class name is provided, it will be incorporated into the title in this case.

Parameters:
args - the command-line arguments.

HiRISE

Copyright (C) Arizona Board of Regents on behalf of the Planetary Image Research Laboratory, Lunar and Planetary Laboratory at the University of Arizona