23.4 Hyperlink Events

JEditorPane s fire a type of event called a HyperlinkEvent. Typically, this event is fired when the user clicks on a hyperlink in the currently displayed document; the program normally responds by loading a new page. To support this event type, a related event class and listener interface are available in the javax.swing.event package.

23.4.1 The HyperlinkListener Interface

The HyperlinkListener interface (found in javax.swing.event) defines a single method, used to respond to hyperlink activations:

public abstract void hyperlinkUpdate(HyperlinkEvent e)

Called to indicate that a hyperlink request has been made. Typical implementations of this method obtain the new URL from the event and call setPage( ) on the associated JEditorPane. See the JEditorPane example earlier in the chapter to learn how this method can be used.

23.4.2 The HyperlinkEvent Class

The HyperlinkEvent class (found in javax.swing.event) describes a hyperlink request.

23.4.2.1 Properties

HyperlinkEvent defines the properties shown in Table 23-9. The URL property contains a java.net.URL object that can be used to retrieve URL content represented by the event. The description property allows a description of the link (typically, the text of the hyperlink) to be supplied. This can be useful when the URL property is null, such as when the hyperlink can't be parsed well enough to create a URL object. The eventType property defines the type of event that has occurred.

Table 23-9. HyperlinkEvent properties

Property	Data type	get	is	set	Default value
description	String	·			null
eventType	HyperlinkEvent.EventType	·			From constructor
sourceElement1.4	Element	·			null
URL	java.net.URL	·			From constructor
1.4since 1.4 See also the java.util.EventObject class (not covered in this book).

23.4.2.2 Constructors

public HyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL u)

public HyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL u, String desc)

public HyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL u, String desc, Element sourceElement)

Create a new event with the specified properties. The u argument represents the destination of the link. The value of the type parameter is taken from the constant values defined in the HyperlinkEvent.EventType class: ENTERED, EXITED, and ACTIVATED. The desc parameter is optional. The sourceElement argument is also optional (and can be null). It represents the originating anchor Element from the HTML Document.

23.4.2.3 Inner classes

public static final class EventType

This simple inner class is a type-safe enumeration that defines three constants of type HyperlinkEvent.EventType. These constants are ENTERED, EXITED, and, ACTIVATED. As the cursor enters and exits a hyperlinked area of the document, ENTERED and EXITED events are fired. The ACTIVATED constant indicates that a hyperlink has been activated (clicked) by the user.

Prior to the 1.3 release of the SDK, ENTERED and EXITED events were not fired. The aforementioned January 1999 JavaWorld article discusses a workaround for the 1.2 and 1.1 releases.

23.4.3 The HTMLFrameHyperlinkEvent Class

Another event that can arrive at your doorstep in the hyperlinkUpdate( ) method is the HTMLFrameHyperlinkEvent class from the javax.swing.text.html package. (We know, we know. Why isn't it part of the event package? Well, it is quite specific to HTML content whereas the concept of a hyperlink is supposed to be more generic.) This event is similar in content and purpose to the regular HyperlinkEvent and indeed extends that class. It carries information relating to HTML frames—specifically, the target frame for the hyperlink. target is the one new property this class adds, as shown in Table 23-10

Table 23-10. HTMLFrameHyperlinkEvent property

Property	Data type	get	is	set	Default value
target	String	·			null
See also the javax.swing.HyperlinkEvent class (Table 23-9).

If you look back at the code for the SimpleLinkListener class, you can see where we look for this type of event. ENTERED and EXITED hyperlink events are treated the same—we just update our status bar. However, if the user activates a link, we need to see where its destination lies. If the link is an instance of HTMLFrameHyperlinkEvent, we have to treat it differently. Fortunately, we don't have to do much work. The HTMLDocument class knows how to handle these events, so we just pass it to our document.

We should note a few things about frame-related hyperlink events. They are not well-supported in SDK 1.2. They do exist there, but are probably best left out of the picture. Even in the 1.4 release, these events are not handled as gracefully as you might hope. For example, the _blank target does not open a new window in the current implementation of JEditorPane. To support such a target, you would need to monitor the target property of any incoming ACTIVATED HTMLFrameHyperlinkEvent object and launch your own new window if necessary.