23.5 The HTMLEditorKit Class

The API for the HTMLEditorKit is more or less what you might expect from an editor kit if you made it through Chapter 19-Chapter 22 on Swing text components. We'll take a brief look at the API and then go through examples of how to work with this editor kit.

23.5.1 Inner Classes

As you can see in Figure 23-7, HTMLEditorKit defines several inner classes. These inner classes are integral to the display and editing of HTML content. While we don't want to spend too much time on the details of these classes, you should know about them. We list them here as a quick reference.

public static class HTMLEditorKit.HTMLFactory

The view factory implementation for HTML.

public static class HTMLEditorKit.HTMLTextAction

An Action for inserting HTML into an existing document.

public static class HTMLEditorKit.InsertHTMLTextAction

An extension of HTMLTextAction that allows you to insert arbitrary HTML content. This one is quite handy. For example, we can create an action for a toolbar or menu that inserts a copyright:

private final static String COPY_HTML =   "<p>&copy; 2002, O'Reilly &amp; Associates</p>"; Action a = new HTMLEditorKit.InsertHTMLTextAction("InsertCopyright",      COPY_HTML, HTML.Tag.BODY, HTML.Tag.P); a.putValue(Action.SMALL_ICON, new ImageIcon("icons/cpyrght.gif")); a.putValue(Action.NAME, "Copyright Text");

The action can be added to a toolbar or menu, just like the others in the StyledEditor example. We end up with a one-touch button that adds our copyright information to the page.

public static class HTMLEditorKit.LinkController

The event listener that translates mouse events into the (often) more desirable HyperlinkEvents.

public static class HTMLEditorKit.Parser

A parser to read an input stream of HTML.

public static class HTMLEditorKit.ParserCallback

An implementation of a callback for use while loading an HTML document.

Figure 23-7. HTMLEditorKit class diagram

23.5.2 Properties

Apart from some of the obvious properties you might expect from an editor kit the content type and parser, for example several other display properties for HTML documents are present in the HTMLEditorKit class. These properties are shown in Table 23-11.

Table 23-11. HTMLEditorKit properties

Property	Data type	get	is	set	Default value
actionso	Action[]	·			Standard text actions plus HTML-specific actions*
contentTypeo	String	·			"text/html"
defaultCursor1.3	Cursor	·		·	System default cursor
inputAttributes	MutableAttributeSet	·			Defined by default.css
linkCursor1.3	Cursor	·		·	System "hand" cursor
parser	HTMLEditorKit.Parser	·			ParserDelegate( )
styleSheet	StyleSheet	·		·	Defined by default.css
viewFactoryo	ViewFactory	·			HTMLFactory( )
1.3since 1.3, ooverridden See Appendix B for a list of these actions. This file is in the javax/swing/text/html directory and is most often pulled from the rt.jar file. See also properties from the EditorKit class (Table 23-3) and the StyledEditorKit class (Table 23-6).

The actions property lists available text actions. In addition to standard actions like making text bold or italic, the HTML additions let you insert images, horizontal rules, and anchors (among other things). The editor kit stores the MIME type for the document in the contentType property. The defaultCursor and linkCursor properties dictate the cursor to be displayed over normal text (defaultCursor) and over hyperlinks (linkCursor). As of SDK 1.3, the visual update of the cursor happens automatically. The inputAttributes property returns the attribute set associated with the current stylesheet. The parser property provides easy access to the installed parser that reads content. The styleSheet and viewFactory properties dictate the presentation of the document. Both of these can be overridden in subclasses.

23.5.3 Constructor

public HTMLEditorKit( )

Construct a simple instance of the HTMLEditorKit class.

23.5.4 Editor Kit Methods

If you intend to create your own subclass of the HTMLEditorKit, these methods will come in handy. Overriding them allows you to control exactly which steps from the parent class are performed.

public void install(JEditorPane c)

Called when the editor kit is associated with an editor pane. This is where the default link controller is attached to the editor pane so that hyperlink activity is reported to any HyperlinkListener objects correctly.

public void deinstall(JEditorPane c)

Called to remove an editor kit from an editor pane if, for example, a new, non-HTML document is loaded into the pane.

23.5.5 HTML Document Methods

These methods allow you to create, modify, and save HTML documents programmatically. Again, if you want to simply display HTML text in a JEditorPane, none of these are necessary.

public Document createDefaultDocument( )

Create a blank document that you can use to build an HTML page from scratch. HTML can be inserted using the insertHTML( ) method.

public void insertHTML(HTMLDocument doc, int offset, String html, int popDepth, int pushDepth, HTML.Tag insertTag) throws BadLocationException, IOException

Insert HTML into an existing document. You can insert images, formatted text, or even hyperlinks. The doc is the document where the html will be inserted. popDepth and pushDepth indicate how many closing and opening tags, respectively, are required to insert the html. For just a simple insert, both can be 0. The insertTag parameter dictates the tag associated with the HTML in the document hierarchy obviously closely associated with the html you supply. Inserting content beyond the end or before the beginning of the document throws a BadLocationException.

public void read(Reader in, Document doc, int pos) throws IOException, BadLocationException

Manually read HTML text into an existing document starting at pos. The Reader supplied (in) should not have a parser attached to it, as the parser from the editor kit is used.

public void write(Writer out, Document doc, int pos, int len) throws IOException, BadLocationException

Save some or all of a document as HTML. To save the entire document, pos should start at 0 and len should be doc.length( ). Examples of the read( ) and write( ) methods appear in Section 23.7 later in this chapter.