The JFC Swing Tutorial: A Guide to Constructing GUIs (2nd Edition)

Two Swing classes support styled text: JEditorPane and its subclass JTextPane . JEditorPane is the foundation for Swing's styled text components and provides the mechanism through which you can add support for custom text formats. If you want unstyled text, consider using a text area instead. See also How to Use Text Areas (page 418).

Figure 14 shows TextSamplerDemo , which uses many text components, including an editor pane and text demo.

TextSamplerDemo hardly begins to exercise the capabilities of editor and text panes. However, the editor pane at its top right does illustrate a very handy, easy-to-use feature: displaying uneditable help information loaded from a URL. The text pane at the lower right demonstrates that you can easily embed images and even components directly into text panes.

Note: If you need a full-fledged help system, take a look at the JavaHelp ^TM system: http://java.sun.com/products/javahelp/.

The Swing text API is powerful and immense, and we could devote an entire book just to using editor panes and text panes. This section introduces their capabilities, offers hints on which one you might want to use, and points to other sources of information.

Using an Editor Pane to Display Text from a URL

One task that you can accomplish without knowing anything about the Swing text system is displaying text from a URL. Here's the code from TextSamplerDemo.java that creates an uneditable editor pane that displays text formatted with HTML tags:

JEditorPane editorPane = new JEditorPane(); editorPane.setEditable(false); java.net.URL helpURL = TextSamplerDemo.class.getResource( "TextSamplerDemoHelp.html"); if (helpURL != null) { try { editorPane.setPage(helpURL); } catch (IOException e) { System.err.println("Attempted to read a bad URL: " + helpURL); } } else { System.err.println("Couldn't find file: TextSampleDemoHelp.html"); } //Put the editor pane in a scroll pane. JScrollPane editorScrollPane = new JScrollPane(editorPane); editorScrollPane.setVerticalScrollBarPolicy( JScrollPane.VERTICAL_SCROLLBAR_ALWAYS); editorScrollPane.setPreferredSize(new Dimension(250, 145)); editorScrollPane.setMinimumSize(new Dimension(10, 10));

The code uses the default constructor to create the editor pane, then calls set- Editable(false) so that the user cannot edit the text. Next, the code creates the URL object and calls the setPage method with it.

The setPage method opens the resource pointed to by the URL and figures out the format of the text (which in the example is HTML). If the text format is known, the editor pane initializes itself with the text found at the URL. A standard editor pane can understand plain text, HTML, and RTF. Note that the page might be loaded asynchronously, which keeps the GUI responsive but means that you shouldn't count on the data being completely loaded after the call to setPage returns.

Editor Panes versus Text Panes

For most uses of editor panes and text panes, you need to understand the text system, which is described in Text Component Features (page 64) in Chapter 3. Several facts about editor panes and text panes are sprinkled throughout that section. Here we list the facts again, to collect them in one place and to provide a bit more detail. The information here should help you understand the differences between editor panes and text panes and when to use which.

• An editor pane or a text pane can easily be loaded with text from a URL using the setPage method. The JEditorPane class also provides constructors that let you initialize an editor pane from a URL. JTextPane has no such constructors. See Using an Editor Pane to Display Text from a URL (page 201) for an example of using this feature to load an uneditable editor pane with HTML-formatted text.

  Be aware that the document and editor kit might change when using the setPage method. For example, if an editor pane contains plain text (the default) and you load it with HTML, the document will change to an HTMLDocument instance and the editor kit will change to an HTMLEditorKit instance. If your program uses the setPage method, make sure that the code adjusts for possible changes to the pane's document and editor kit instances (reregister document listeners on the new document, and so on).

• Editor panes, by default, know how to read, write, and edit plain, HTML, and RTF text. Text panes inherit this capability but impose certain limitations. A text pane insists that its document implement the StyledDocument interface. HTMLDocument and RTFDocument are both StyledDocuments so HTML and RTF work as expected within a text pane. If you load a text pane with plain text though, the text pane's document is not a PlainDocument as you might expect, but a DefaultStyledDocument .

• To support a custom text format, implement an editor kit that can read, write, and edit text of that format. Then call the registerEditorKitForContentType method to register your kit with the JEditorPane class. By registering an editor kit in this way, all editor panes and text panes in your program will be able to read, write, and edit the new format. However, if the new editor kit is not a StyledEditorKit , text panes will not support the new format.

• As mentioned previously, a text pane requires its document to implement the StyledDocument interface. The Swing text package provides a default implementation of this interface, DefaultStyledDocument , which is the document text panes use by default. A text pane also requires that its editor kit be an instance of a StyledEditorKit (or a subclass). Be aware that the read and write methods for StyledEditorKit write plain text.

• Through its styled document and styled editor kit, text panes provide support for named styles and logical styles. The JTextPane class itself contains many methods for working with styles that simply call methods in its document or editor kit.

• Through the API provided in the JTextPane class, you can embed images and components in a text pane. You can embed images in an editor pane, too, but only by including the images in an HTML or RTF file.

An Example of Using a Text Pane

Here's the code from TextSamplerDemo that creates and initializes the text pane.

String[] initString = { /* ... fill array with initial text ... */ }; String[] initStyles = { /* ... fill array with names of styles ... */ }; JTextPane textPane = new JTextPane(); StyledDocument doc = textPane.getStyledDocument(); addStylesToDocument(doc); //Load the text pane with styled text. try { for (int i=0; i < initString.length; i++) { doc.insertString(doc.getLength(), initString[i], doc.getStyle(initStyles[i])); } } catch (BadLocationException ble) { System.err.println("Couldn't insert initial text into text pane."); }

Briefly, this code hard-codes the initial text into an array and creates and hard-codes several styles ”objects that represent different paragraph and character formats ”into another array. Next, the code loops over the arrays, inserts the text into the text pane, and specifies the style to use for the inserted text.

Although this makes for an interesting example and concisely shows off several features of JTextPane , "real-world" programs aren't likely to initialize a text pane this way. Instead, the program would use a text pane to save out a document, which would then be used to initialize the text pane.

The Editor Pane and Text Pane API

Tables 19 and 20 list a bit of the API related to text and editor panes. Many of the most useful methods for JEditorPane and its subclass JTextPane are inherited from JTextComponent . You can find the API tables for JTextComponent in The Text Component API (page 77) in Chapter 3. Also see The JComponent Class (page 53), which describes the API inherited from JComponent . You can also refer to the API documentation for JEditorPane and JTextPane :

http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JEditorPane.html

http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JTextPane.html

Table 19. JEditorPane API for Displaying Text from a URL

Table 20. JTextPane API

Examples That Use Editor Panes and Text Panes

To get started with text, you might want to run these programs and examine their code to find something similar to what you want to do.