uic.widgets.html
Class HTMLPane

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.JLayeredPane
                  uic.widgets.html.HTMLPane

All Implemented Interfaces:

KeyListener, ImageObserver, MenuContainer, Serializable, EventListener, Accessible

public class HTMLPane
extends JLayeredPane
implements 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 Config object. The Pane communicates internal events (e.g. a selected hyperlink) to a HTMLObserver 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 messageViewer (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:

HTMLConfig, HTMLObserver, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JLayeredPane

JLayeredPane.AccessibleJLayeredPane

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

JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

static String	PROPERTY_URL Each time a link is followed or a form is submitted this property is fired with the old and new URL objects
static short	SCROLLBARS_AUTO
static short	SCROLLBARS_NO
static short	SCROLLBARS_VIEWER
static short	SCROLLBARS_YES

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

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

HTMLPane()
Constructs a HTMLPane with default Config, a default HTMLObserver and default top-level frame name.

HTMLPane(HTMLConfig prefs, HTMLObserver obs, String name)
Constucts a HTMLPane with the specified HTMLObserver, Config and top-level frame name.

Method Summary

void	closeMessageViewer() Closes the Pane's messageViewereViewer if it is currently visible.
URL	getCurrentPage() Return the URL of the currently viewing remote page.
URL	getCurrentPage(String frameName) Return the URL of the currently viewing remote page in the target (child) frame.
HTMLDocument	getDocument()
Hashtable	getIDComponents(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.
boolean	isFocusTraversable() Overrides JComponent isFocusTraversable().
boolean	isLoadSynchronouslyEnabled() Returns whether documents will be loaded by the HTMLPane synchronously or asynchronously.
boolean	isManagingFocus() Overrides JComponent isManagingFocus().
void	keyPressed(KeyEvent e) Public due to implementation requirements.
void	keyReleased(KeyEvent e) Public due to implementation requirements.
void	keyTyped(KeyEvent e) Public due to implementation requirements.
void	reloadDocument() Reloads the current document.
void	scrollToReference(String ref, 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 policy) Sets the scrollbar policy of the Pane.
void	setText(String s)
void	showHTMLDocument(String s) Formats and displays the specified String as an HTML document in the top level frame of the Pane.
void	showHTMLDocument(String s, String targetFrame) Formats and displays the specified String as an HTML document in the named target frame.
void	showHTMLDocument(URL url) Shows the contents of the specified URL in the top level frame of the Pane.
void	showHTMLDocument(URL url, String targetFrame, boolean reload) Shows the contents of the specified URL in the named target frame.
void	showMessageViewer(String message) Parses the sent message as HTML and displays the result in the Pane's messageViewer.
void	showMessageViewer(String message, String messageName, int x, int y, int w, int h) Parses the sent message as HTML and displays the result in the Pane's messageViewer.
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, removeAll, setLayer, setLayer, setPosition

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, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isOpaque, isPaintingTile, isRequestFocusEnabled, isValidateRoot, 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, updateUI

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, 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, 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, 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, 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

PROPERTY_URL

public static final String PROPERTY_URL

Each time a link is followed or a form is submitted this property is fired with the old and new URL objects

See Also:

Constant Field Values

SCROLLBARS_YES

public static final short SCROLLBARS_YES

See Also:

setScrollBarPolicy(int), Constant Field Values

SCROLLBARS_VIEWER

public static final short SCROLLBARS_VIEWER

See Also:

setScrollBarPolicy(int), Constant Field Values

SCROLLBARS_NO

public static final short SCROLLBARS_NO

See Also:

setScrollBarPolicy(int), Constant Field Values

SCROLLBARS_AUTO

public static final short SCROLLBARS_AUTO

See Also:

setScrollBarPolicy(int), Constant Field Values

Constructor Detail

HTMLPane

public HTMLPane()

Constructs a HTMLPane with default Config, a default HTMLObserver and default top-level frame name.

HTMLPane

public HTMLPane(HTMLConfig prefs,
                HTMLObserver obs,
                String name)

Constucts a HTMLPane with the specified HTMLObserver, Config and top-level frame name. If any of the arguments are null then a default will be used.

Parameters:

prefs - the Config which determines the Pane's behaviour.

obs - the HTMLObserver 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).

Overrides:

setBounds in class Component

showHTMLDocument

public void showHTMLDocument(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(URL url,
                             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 Config controlling the Pane then a new HTMLPane will be created to show the document.
• if handleNewFrames is not enabled then a showNewFrameRequest will be sent to the Pane's resident HTMLObserver.

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(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.

setText

public void setText(String s)

getCurrentPage

public URL getCurrentPage()

Return the URL of the currently viewing remote page.

Returns:

the URL or null if nothing is loaded.

getCurrentPage

public URL getCurrentPage(String frameName)

Return the URL of the currently viewing remote page in the target (child) frame.

Parameters:

frameName - the name of the frame

Returns:

the URL or null if nothing is loaded, or frame not found.

showHTMLDocument

public void showHTMLDocument(String s,
                             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 Config controlling the Pane then a new HTMLPane will be created to show the document.
• if handleNewFrames is not enabled then a showNewFrameRequest will be sent to the Pane's resident HTMLObserver.

Parameters:

s - a String to be formatted as an HTML document.

targetFrame - the HTML frame that the document should be displayed in.

getDocument

public HTMLDocument getDocument()

scrollToReference

public void scrollToReference(String ref,
                              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 HTMLPane'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 HTMLObserver class to determine when the String has been fully parsed, or you could set the HTMLPane'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 HTMLPane 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.

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 HTMLPane. 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 policy)

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

• SCROLLBARS_VIEWER (The default setting)
  Equivalent to ScrollPaneConstants.VERTICAL_SCROLLBAR_ALWAYS, ScrollPaneConstants.HORIZONTAL_SCROLLBAR_AS_NEEDED
  
• SCROLLBARS_YES
  Equivalent to ScrollPaneConstants.VERTICAL_SCROLLBAR_ALWAYS, ScrollPaneConstants.HORIZONTAL_SCROLLBAR_ALWAYS
  
• SCROLLBARS_NO
  Equivalent to ScrollPaneConstants.VERTICAL_SCROLLBAR_NEVER, ScrollPaneConstants.HORIZONTAL_SCROLLBAR_NEVER
  
• SCROLLBARS_AUTO
  Equivalent to ScrollPaneConstants.VERTICAL_SCROLLBAR_AS_NEEDED, ScrollPaneConstants.HORIZONTAL_SCROLLBAR_AS_NEEDED
  

Note that unless scrolling policy is set to SCROLLBARS_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:

policy - 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 JComponent

isFocusTraversable

public boolean isFocusTraversable()

Overrides JComponent isFocusTraversable(). Programmers are advised not to override this method.

Overrides:

isFocusTraversable in class Component

keyPressed

public void keyPressed(KeyEvent e)

Public due to implementation requirements. Programmers are advised not to override this method.

Specified by:

keyPressed in interface KeyListener

keyReleased

public void keyReleased(KeyEvent e)

Public due to implementation requirements. Programmers are advised not to override this method.

Specified by:

keyReleased in interface KeyListener

keyTyped

public void keyTyped(KeyEvent e)

Public due to implementation requirements. Programmers are advised not to override this method.

Specified by:

keyTyped in interface KeyListener

showMessageViewer

public void showMessageViewer(String message)

Parses the sent message as HTML and displays the result in the Pane's messageViewer. See the README.TXT file accompanying this documentation for more details regarding the Pane's messageViewer.

Parameters:

message - a String to be formatted as HTML in the Pane's messageViewer.

showMessageViewer

public void showMessageViewer(String message,
                              String messageName,
                              int x,
                              int y,
                              int w,
                              int h)

Parses the sent message as HTML and displays the result in the Pane's messageViewer.
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 messageViewer's bounds.
If y >= 0 the Pane will use this value as a guide to the top-vertical coordinate for setting the messageViewer's bounds.
If w > 0 the Pane will use this value as a guide to the width of the messageViewer.
If h > 0 the Pane will use this value as a guide to the height of the messageViewer.

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

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

Parameters:

message - a String to be formatted as HTML in the Pane's messageViewer.

messageName - a name given to the message for caching purposes.

x - the left-horizontal coordinate of the messageViewer's bounds.

y - the top-vertical coordinate of the messageViewer's bounds.

w - the width of the messageViewer.

h - the height of the messageViewer.

closeMessageViewer

public void closeMessageViewer()

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

getIDComponents

public Hashtable getIDComponents(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 HTMLPane 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 HTMLPane (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 HTMLObserver 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 HTMLPane synchronously or asynchronously.

Returns:

true if documents will load synchronously.

See Also:

setLoadSynchronously(boolean)