## calpa.html
Class CalHTMLPane

    java.lang.Object
      |
      +--java.awt.Component
            |
            +--java.awt.Container
                  |
                  +--javax.swing.JComponent
                        |
                        +--javax.swing.JLayeredPane
                              |
                              +--calpa.html.CalHTMLPane

public class CalHTMLPane
extends javax.swing.JLayeredPane
implements calpa.html.CalCons, java.awt.event.KeyListener

A component class which has the capacity to display HTML-formatted content. The default rendering style of the Pane and other aspects of its operation are controlled by a `CalHTMLPreferences` object. The Pane communicates internal events (e.g. a selected hyperlink) to a `CalHTMLObserver` object so that futher processing of such events can be handled by the programmer.

Documents are displayed in the `JLayeredPane.DEFAULT_LAYER`.
The Pane's dialog (if used) is displayed in the `JLayeredPane.MODAL_LAYER`.
The Pane's test navigation bar (if used) is displayed in the `JLayeredPane.PALETTE_LAYER`.

See the README.TXT file accompanying this document for further details on how to use this class.

See Also:
  `CalHTMLPreferences`, `CalHTMLObserver`, Serialized Form

Inner classes inherited from class javax.swing.JLayeredPane
`javax.swing.JLayeredPane.AccessibleJLayeredPane`

Inner classes inherited from class javax.swing.JComponent
`javax.swing.JComponent.AccessibleJComponent`

Fields inherited from class javax.swing.JLayeredPane
`DEFAULT_LAYER, DRAG_LAYER, FRAME_CONTENT_LAYER, LAYER_PROPERTY, MODAL_LAYER, PALETTE_LAYER, POPUP_LAYER`

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`

Constructor Summary
`CalHTMLPane()` Constructs a `CalHTMLPane` with default `CalHTMLPreferences`, a default `CalHTMLObserver` and default top-level frame name.
`CalHTMLPane(CalHTMLPreferences prefs, CalHTMLObserver obs, java.lang.String name)` Constucts a `CalHTMLPane` with the specified `CalHTMLObserver`, `CalHTMLPreferences` and top-level frame name.

Method Summary
`void` | `closeDialog()` Closes the Pane's dialog if it is currently visible.
`java.util.Hashtable` | `getIDComponents(java.lang.String targetFrame)` Returns a Hashtable containing all components in the target frame which have the HTML 'id' attribute.
`void` | `goBack()` Show the previous document in the Pane's history list.
`void` | `goForward()` Show the next document in the Pane's history list.
`void` | `goHome()` Show the contents of the `URL` specified as `homeURL` by `CalHTMLPreferences` in the top level frame of the Pane.
`boolean` | `isFocusTraversable()` Overrides `JComponent isFocusTraversable()`.
`boolean` | `isLoadSynchronouslyEnabled()` Returns whether documents will be loaded by the `CalPane` synchronously or asynchronously.
`boolean` | `isManagingFocus()` Overrides `JComponent isManagingFocus()`.
`void` | `keyPressed(java.awt.event.KeyEvent e)` Public due to implementation requirements.
`void` | `keyReleased(java.awt.event.KeyEvent e)` Public due to implementation requirements.
`void` | `keyTyped(java.awt.event.KeyEvent e)` Public due to implementation requirements.
`void` | `reloadDocument()` Reloads the current document.
`void` | `scrollToReference(java.lang.String ref, java.lang.String targetFrame)` Scrolls the document view to the specified anchor reference in the named target frame.
`void` | `setBounds(int x, int y, int w, int h)` Public due to inheritance.
`void` | `setLoadSynchronously(boolean b)` Enables/disables the synchronous loading of documents.
`boolean` | `setScrollBarPolicy(int n)` Sets the scrollbar policy of the Pane.
`void` | `showDialog(java.lang.String message)` Parses the sent message as HTML and displays the result in the Pane's dialog.
`void` | `showDialog(java.lang.String message, java.lang.String messageName, int x, int y, int w, int h)` Parses the sent message as HTML and displays the result in the Pane's dialog.
`void` | `showHTMLDocument(java.lang.String s)` Formats and displays the specified String as an HTML document in the top level frame of the Pane.
`void` | `showHTMLDocument(java.lang.String s, java.lang.String targetFrame)` Formats and displays the specified String as an HTML document in the named target frame.
`void` | `showHTMLDocument(java.net.URL url)` Shows the contents of the specified `URL` in the top level frame of the Pane.
`void` | `showHTMLDocument(java.net.URL url, java.lang.String targetFrame, boolean reload)` Shows the contents of the specified `URL` in the named target frame.
`void` | `stopAll()` Stops all processes within the Pane.

Methods inherited from class javax.swing.JLayeredPane
`addImpl, getAccessibleContext, getComponentCountInLayer, getComponentsInLayer, getComponentToLayer, getIndexOf, getLayer, getLayer, getLayeredPaneAbove, getObjectForLayer, getPosition, highestLayer, insertIndexForLayer, isOptimizedDrawingEnabled, lowestLayer, moveToBack, moveToFront, paint, paramString, putLayer, remove, setLayer, setLayer, setPosition`

Methods inherited from class javax.swing.JComponent

`addAncestorListener, addNotify, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getAlignmentX, getAlignmentY, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getGraphics, getHeight, getInsets, getInsets, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getUIClassID, getVisibleRect, getWidth, getX, getY, grabFocus, hasFocus, isDoubleBuffered, isFocusCycleRoot, isLightweightComponent, isOpaque, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, processComponentKeyEvent, processFocusEvent, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDebugGraphicsOptions, setDoubleBuffered, setEnabled, setFont, setForeground, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setUI, setVisible, unregisterKeyboardAction, update, updateUI`

Methods inherited from class java.awt.Container

`add, add, add, add, add, addContainerListener, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getLayout, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paintComponents, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, removeAll, removeContainerListener, setLayout, validate, validateTree`

Methods inherited from class java.awt.Component

`action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addPropertyChangeListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hide, imageUpdate, inside, isDisplayable, isEnabled, isLightweight, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processInputMethodEvent, processMouseEvent, remove, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setComponentOrientation, setCursor, setDropTarget, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus`

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

Constructor Detail

### CalHTMLPane

    public CalHTMLPane()

  Constructs a `CalHTMLPane` with default `CalHTMLPreferences`, a default `CalHTMLObserver` and default top-level frame name.

### CalHTMLPane

    public CalHTMLPane(CalHTMLPreferences prefs,
                       CalHTMLObserver obs,
                       java.lang.String name)

  Constucts a `CalHTMLPane` with the specified `CalHTMLObserver`, `CalHTMLPreferences` and top-level frame name. If any of the arguments are `null` then a default will be used.
  Parameters:
    `prefs` - the `CalHTMLPreferences` which determines the Pane's behaviour.
    `obs` - the `CalHTMLObserver` that will receive updates from the Pane.
    `name` - the name of the Pane's top-level frame.

Method Detail

### setBounds

    public void setBounds(int x,
                          int y,
                          int w,
                          int h)

  Public due to inheritance. Call `super.setBounds(x, y, w, h)` if you override this method or the Pane may not function correctly.
  Overrides:
    setBounds in class java.awt.Component

### showHTMLDocument

    public void showHTMLDocument(java.net.URL url)

  Shows the contents of the specified `URL` in the top level frame of the Pane. A cached document will be used if one is available and caching is enabled.
  Parameters:
    `url` - the URL of the document to be displayed.

### showHTMLDocument

    public void showHTMLDocument(java.net.URL url,
                                 java.lang.String targetFrame,
                                 boolean reload)

  Shows the contents of the specified `URL` in the named target frame. If the target frame is null the document will be displayed in the top level frame of the Pane. If the target frame is not a currently recognised frame:
  - if `handleNewFrames` is enabled in the `CalHTMLPreferences` controlling the Pane then a new `CalHTMLPane` will be created to show the document.
  - if `handleNewFrames` is not enabled then a `showNewFrameRequest` will be sent to the Pane's resident `CalHTMLObserver`.

  If `reload` is `false` a cached document will be used if one is available and caching is enabled. Otherwise the document will be reloaded from the specified URL.

  Parameters:
    `url` - the URL of the document to be displayed.
    `targetFrame` - the HTML frame that the document should be displayed in.
    `reload` - if `true` forces the document to be reloaded even if a cached version is available.

### showHTMLDocument

    public void showHTMLDocument(java.lang.String s)

  Formats and displays the specified String as an HTML document in the top level frame of the Pane.
  Parameters:
    `s` - a String to be formatted as an HTML document.

### showHTMLDocument

    public void showHTMLDocument(java.lang.String s,
                                 java.lang.String targetFrame)

  Formats and displays the specified String as an HTML document in the named target frame. If the target frame is null the document will be displayed in the top level frame of the Pane. If the target frame is not a currently recognised frame:
  - if `handleNewFrames` is enabled in the `CalHTMLPreferences` controlling the Pane then a new `CalHTMLPane` will be created to show the document.
  - if `handleNewFrames` is not enabled then a `showNewFrameRequest` will be sent to the Pane's resident `CalHTMLObserver`.
  Parameters:
    `s` - a String to be formatted as an HTML document.
    `targetFrame` - the HTML frame that the document should be displayed in.

### scrollToReference

    public void scrollToReference(java.lang.String ref,
                                  java.lang.String targetFrame)

  Scrolls the document view to the specified anchor reference in the named target frame. If the `targetFrame` argument is `null` then the reference will be looked for in the document in the CalPane's top level frame.

  This method has been incorporated to assist programmers who are displaying HTML Strings and who wish to navigate to internal links in their String HTML documents. For example, if there is an anchor in your String such as: <A name="contactinfo"> then you can call this method with `scrollToReference("contactinfo", null)`.

  Note that you will need to ensure that the String document has been parsed/loaded before attempting to navigate to anchors within it. Calling `showHTMLDocument(String s)` and then immediately calling this method may fail because the String is still being asynchronously parsed and the reference has not been encountered. You can use the `CalHTMLObserver` class to determine when the String has been fully parsed, or you could set the CalPane's loading policy to synchronous loading.

  Programmers using URL documents need not use this method. They can create a new URL which incorporates the anchor reference and call `showHTMLDocument(URL)` instead, which has the advantage that no check need be made to see if the document has loaded - the CalPane will automatically navigate to the anchor as soon as it is available.

  Parameters:
    `ref` - a named anchor reference within a document.
    `targetFrame` - the HTML frame that contains the document with the anchor reference.

### goBack

    public void goBack()

  Show the previous document in the Pane's history list. If the Pane is already at the bottom of its history then the call will be ignored.

### goForward

    public void goForward()

  Show the next document in the Pane's history list. If the Pane is already at the top of its history then the call will be ignored.

### goHome

    public void goHome()

  Show the contents of the `URL` specified as `homeURL` by `CalHTMLPreferences` in the top level frame of the Pane.

### reloadDocument

    public void reloadDocument()

  Reloads the current document.

### stopAll

    public void stopAll()

  Stops all processes within the Pane. In most cases cancellation of any current document loading will be immediate. However, this call has a slightly different effect on a thread that is currently waiting for image data, for this reason:

  > Some document authors do not specify widths and heights for images in their documents. This presents a problem when parsing/loading. A temporary default image size could be used so that the document could be displayed 'on the fly', but this means reformatting the whole document once the true image size becomes available. This can considerably lengthen parsing time and is disconcerting for the document reader. The alternative is to delay the display of the document until all image sizes are known.

  > The latter policy is followed by the CalHTMLPane. On occasions however the image data fails to arrive, and the parsing thread then becomes 'locked' as it waits for this data, even though the rest of the document has been parsed and is ready to be formatted. When this method is called (usually by the user pressing a 'STOP' button) a thread which is looping in this way will be freed and document parsing will continue, with default sizes being used for images with incomplete data.

### setScrollBarPolicy

    public boolean setScrollBarPolicy(int n)

  Sets the scrollbar policy of the Pane. The arguments which can be sent to this method are:

  - `CalCons.VIEWER` (The default setting)
    Equivalent to `ScrollPaneConstants.VERTICAL_SCROLLBAR_ALWAYS, ScrollPaneConstants.HORIZONTAL_SCROLLBAR_AS_NEEDED`
  - `CalCons.V_YES`
    Equivalent to `ScrollPaneConstants.VERTICAL_SCROLLBAR_ALWAYS, ScrollPaneConstants.HORIZONTAL_SCROLLBAR_ALWAYS`
  - `CalCons.V_NO`
    Equivalent to `ScrollPaneConstants.VERTICAL_SCROLLBAR_NEVER, ScrollPaneConstants.HORIZONTAL_SCROLLBAR_NEVER`
  - `CalCons.V_AUTO`
    Equivalent to `ScrollPaneConstants.VERTICAL_SCROLLBAR_AS_NEEDED, ScrollPaneConstants.HORIZONTAL_SCROLLBAR_AS_NEEDED`

  Note that unless scrolling policy is set to `V_NO`, documents will always be formatted on the assumption that a vertical scrollbar is present, even if one is not currently visible. This is due to the asynchronous loading of documents. When a Pane loads a document it cannot 'know' whether or not a vertical scrollbar is going to be required, and adjusting for the sudden appearance of one would necessitate a reformat of the whole document.

  Parameters:
    `n` - a value which dictates the scrollbar policy for the Pane.
  Returns:
    `true` if a supported scrollbar policy was sent to this method

### isManagingFocus

    public boolean isManagingFocus()

  Overrides `JComponent isManagingFocus()`. Programmers are advised not to override this method.
  Overrides:
    isManagingFocus in class javax.swing.JComponent

### isFocusTraversable

    public boolean isFocusTraversable()

  Overrides `JComponent isFocusTraversable()`. Programmers are advised not to override this method.
  Overrides:
    isFocusTraversable in class javax.swing.JComponent

### keyPressed

    public void keyPressed(java.awt.event.KeyEvent e)

  Public due to implementation requirements. Programmers are advised not to override this method.
  Specified by:
    keyPressed in interface java.awt.event.KeyListener

### keyReleased

    public void keyReleased(java.awt.event.KeyEvent e)

  Public due to implementation requirements. Programmers are advised not to override this method.
  Specified by:
    keyReleased in interface java.awt.event.KeyListener

### keyTyped

    public void keyTyped(java.awt.event.KeyEvent e)

  Public due to implementation requirements. Programmers are advised not to override this method.
  Specified by:
    keyTyped in interface java.awt.event.KeyListener

### showDialog

    public void showDialog(java.lang.String message)

  Parses the sent message as HTML and displays the result in the Pane's dialog. See the README.TXT file accompanying this documentation for more details regarding the Pane's dialog.
  Parameters:
    `message` - a String to be formatted as HTML in the Pane's dialog.

### showDialog

    public void showDialog(java.lang.String message,
                           java.lang.String messageName,
                           int x,
                           int y,
                           int w,
                           int h)

  Parses the sent message as HTML and displays the result in the Pane's dialog.
  If a messageName is given the Pane will attempt to use a cached version of the message which has already been parsed under the same name. The message sent to this method may be `null` if the messageName is not `null`;

  If x >= 0 the Pane will use this value as a guide to the left-horizontal coordinate for setting the dialog's bounds.
  If y >= 0 the Pane will use this value as a guide to the top-vertical coordinate for setting the dialog's bounds.
  If w > 0 the Pane will use this value as a guide to the width of the dialog.
  If h > 0 the Pane will use this value as a guide to the height of the dialog.

  The Pane will honour any sent bounds values where it can, but it will always try and ensure that the dialog is fully visible and that the dialog's contents fit properly within its bounds.

  See the README.TXT file accompanying this documentation for more details on programming the Pane's dialog.

  Parameters:
    `message` - a String to be formatted as HTML in the Pane's dialog.
    `messageName` - a name given to the message for caching purposes.
    `x` - the left-horizontal coordinate of the dialog's bounds.
    `y` - the top-vertical coordinate of the dialog's bounds.
    `w` - the width of the dialog.
    `h` - the height of the dialog.

### closeDialog

    public void closeDialog()

  Closes the Pane's dialog if it is currently visible. Any current parsing of a dialog message will be halted. If the dialog is not visible this method call is ignored.

### getIDComponents

    public java.util.Hashtable getIDComponents(java.lang.String targetFrame)

  Returns a Hashtable containing all components in the target frame which have the HTML 'id' attribute. If the target frame is null then all id components within the CalPane are returned.

  An example component would be one created with the following HTML:

  <INPUT type=text name=username id=username>

  The keys in the Hashtable are the id values of the components. This method allows programmers to get handles to HTML components after they have been created, either to monitor/manipulate their state or, for example, to programmatically fire a form submission.

  Note that programmers should ensure that a document has finished loading before trying to access any components within it, otherwise this method may return before the components have been created.

  Parameters:
    `targetFrame` - the name of the frame containing the components, or all frames if `null`
  Returns:
    a `Hashtable` of components, with their HTML 'id' values as keys

### setLoadSynchronously

    public void setLoadSynchronously(boolean b)

  Enables/disables the synchronous loading of documents. If `loadSynchronously` is enabled then `showHTMLDocument()` methods will not return until a document has loaded. In addition documents loading from activated hyperlinks will also load synchronously.

  Loading synchronously effectively blocks the current AWT thread which will reduce the responsiveness of the `CalHTMLPane` (and will freeze the rest of your application), but it can be useful for programmers who want to be sure that a document has loaded before proceeding with another operation. Generally it is better to use the callback methods in `CalHTMLObserver` to determine when a document has finished loading.

  The default policy is to load documents asynchronously.

### isLoadSynchronouslyEnabled

    public boolean isLoadSynchronouslyEnabled()

  Returns whether documents will be loaded by the `CalPane` synchronously or asynchronously.
  Returns:
    `true` if documents will load synchronously.
  See Also:
    `setLoadSynchronously(boolean)`