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.



Java Swing
Graphic Java 2: Mastering the Jfc, By Geary, 3Rd Edition, Volume 2: Swing
ISBN: 0130796670
EAN: 2147483647
Year: 2001
Pages: 289
Authors: David Geary

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net