javax.swing.text.html Documentation Differences

This file contains all the changes in documentation in the package javax.swing.text.html as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

A document that models HTML. The purpose of this model is to support both browsing and editing. As a result the structure described by an HTML document is not exactly replicated by default. The element structure that is modeled by default is built by the class HTMLDocument.HTMLReader which implements the HTMLEditorKit.ParserCallback protocol that the parser expects. To change the structure one can subclass HTMLReader and reimplement the method #getReader(int) to return the new reader implementation. The documentation for HTMLReader should be consulted for the details of the default structure created. The intent is that the document be non-lossy (although reproducing the HTML format may result in a different format).

The document models only HTML and makes no attempt to store view attributes in it. The elements are identified by the StyleContext.NameAttribute attribute which should always have a value of type HTML.Tag that identifies the kind of element. Some of the elements (such as comments) are synthesized. The HTMLFactory uses this attribute to determine what kind of view to build.

This document supports incremental loading. The TokenThreshold property controls how much of the parse is buffered before trying to update the element structure of the document. This property is set by the EditorKit so that subclasses can disable it.

The Base property determines the URL against which relative URLs are resolved. By default this will be the Document.StreamDescriptionProperty if the value of the property is a URL. If a <BASE> tag is encountered the base will become the URL specified by that tag. Because the base URL is a property it can of course be set directly.

The default content storage mechanism for this document is a gap buffer (GapContent). Alternatives can be supplied by using the constructor that takes a Content implementation. @author Timothy Prinzing @author Scott Violet @author Sunita Mani @version 1.147 12148 04/0309/0102

The Swing JEditorPane text component supports different kinds of content via a plug-in mechanism called an EditorKit. Because HTML is a very popular format of content some support is provided by default. The default support is provided by this class which supports HTML version 3.2 (with some extensions) and is migrating toward version 4.0. The <applet> tag is not supported but some support is provided for the <object> tag.

There are several goals of the HTML EditorKit provided that have an effect upon the way that HTML is modeled. These have influenced its design in a substantial way.

Support editing

It might seem fairly obvious that a plug-in for JEditorPane should provide editing support but that fact has several design considerations. There are a substantial number of HTML documents that don't properly conform to an HTML specification. These must be normalized somewhat into a correct form if one is to edit them. Additionally users don't like to be presented with an excessive amount of structure editing so using traditional text editing gestures is preferred over using the HTML structure exactly as defined in the HTML document.

The modeling of HTML is provided by the class HTMLDocument. Its documention describes the details of how the HTML is modeled. The editing support leverages heavily off of the text package.

Extendable/Scalable

To maximize the usefulness of this kit a great deal of effort has gone into making it extendable. These are some of the features.

1. The parser is replacable. The default parser is the Hot Java parser which is DTD based. A different DTD can be used or an entirely different parser can be used. To change the parser reimplement the getParser method. The default parser is dynamically loaded when first asked for so the class files will never be loaded if an alternative parser is used. The default parser is in a separate package called parser below this package.
2. The parser drives the ParserCallback which is provided by HTMLDocument. To change the callback subclass HTMLDocument and reimplement the createDefaultDocument method to return document that produces a different reader. The reader controls how the document is structured. Although the Document provides HTML support by default there is nothing preventing support of non-HTML tags that result in alternative element structures.
3. The default view of the models are provided as a hierarchy of View implementations so one can easily customize how a particular element is displayed or add capabilities for new kinds of elements by providing new View implementations. The default set of views are provided by the HTMLFactory class. This can be easily changed by subclassing or replacing the HTMLFactory and reimplementing the getViewFactory method to return the alternative factory.
4. The View implementations work primarily off of CSS attributes which are kept in the views. This makes it possible to have multiple views mapped over the same model that appear substantially different. This can be especially useful for printing. For most HTML attributes the HTML attributes are converted to CSS attributes for display. This helps make the View implementations more general purpose

Asynchronous Loading

Larger documents involve a lot of parsing and take some time to load. By default this kit produces documents that will be loaded asynchronously if loaded using JEditorPane.setPage. This is controlled by a property on the document. The method createDefaultDocument can be overriden to change this. The batching of work is done by the HTMLDocument.HTMLReader class. The actual work is done by the DefaultStyledDocument and AbstractDocument classes in the text package.

Customization from current LAF

HTML provides a well known set of features without exactly specifying the display characteristics. Swing has a theme mechanism for its look-and-feel implementations. It is desirable for the look-and-feel to feed display characteristics into the HTML views. An user with poor vision for example would want high contrast and larger than typical fonts.

The support for this is provided by the StyleSheet class. The presentation of the HTML can be heavily influenced by the setting of the StyleSheet property on the EditorKit.

Not lossy

An EditorKit has the ability to be read and save documents. It is generally the most pleasing to users if there is no loss of data between the two operation. The policy of the HTMLEditorKit will be to store things not recognized or not necessarily visible so they can be subsequently written out. The model of the HTML document should therefore contain all information discovered while reading the document. This is constrained in some ways by the need to support editing (i.e. incorrect documents sometimes must be normalized). The guiding principle is that information shouldn't be lost but some might be synthesized to produce a more correct model or it might be rearranged.

@author Timothy Prinzing @version 1.115 12117 06/0325/0102

Support for defining the visual characteristics of HTML views being rendered. The StyleSheet is used to translate the HTML model into visual characteristics. This enables views to be customized by a look-and-feel multiple views over the same model can be rendered differently etc. This can be thought of as a CSS rule repository. The key for CSS attributes is an object of type CSS.Attribute. The type of the value is up to the StyleSheet implementation but the toString method is required to return a string representation of CSS value.

The primary entry point for HTML View implementations to get their attributes is the getViewAttributes method. This should be implemented to establish the desired policy used to associate attributes with the view. Each HTMLEditorKit (i.e. and therefore each associated JEditorPane) can have its own StyleSheet but by default one sheet will be shared by all of the HTMLEditorKit instances. HTMLDocument instance can also have a StyleSheet which holds the document-specific CSS specifications.

In order for Views to store less state and therefore be more lightweight the StyleSheet can act as a factory for painters that handle some of the rendering tasks. This allows implementations to determine what they want to cache and have the sharing potentially at the level that a selector is common to multiple views. Since the StyleSheet may be used by views over multiple documents and typically the HTML attributes don't effect the selector being used the potential for sharing is significant.

The rules are stored as named styles and other information is stored to translate the context of an element to a rule quickly. The following code fragment will display the named styles and therefore the CSS rules contained.

     import java.util.*;   import javax.swing.text.*;   import javax.swing.text.html.*;     public class ShowStyles {     public static void main(String[] args) {   HTMLEditorKit kit = new HTMLEditorKit();   HTMLDocument doc = (HTMLDocument) kit.createDefaultDocument();   StyleSheet styles = doc.getStyleSheet();     Enumeration rules = styles.getStyleNames();   while (rules.hasMoreElements()) {   String name = (String) rules.nextElement();   Style rule = styles.getStyle(name);   System.out.println(rule.toString());   }   System.exit(0);   }   }   

The semantics for when a CSS style should overide visual attributes defined by an element are not well defined. For example the html <body bgcolor=red> makes the body have a red background. But if the html file also contains the CSS rule body { background: blue } it becomes less clear as to what color the background of the body should be. The current implemention gives visual attributes defined in the element the highest precedence that is they are always checked before any styles. Therefore in the previous example the background would have a red color as the body element defines the background color to be red.

As already mentioned this supports CSS. We don't support the full CSS spec. Refer to the javadoc of the CSS class to see what properties we support. The two major CSS parsing related concepts we do not currently support are pseudo selectors such as A:link { color: red } and the important modifier.

Note: This implementation is currently incomplete. It can be replaced with alternative implementations that are complete. Future versions of this class will provide better CSS support. @author Timothy Prinzing @author Sunita Mani @author Sara Swanson @author Jill Nakata @version 1.7475 12/0307/01