HTMLEditorKit

Class Overview

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.

Summary

[Expand] Inherited Constants

From class javax.swing.text.DefaultEditorKit String EndOfLineStringProperty When reading a document if a CRLF is encountered a property with this name is added and the value will be "\r\n". String backwardAction Name of the Action for moving the caret logically backward one position. String beepAction Name of the action to create a beep. String beginAction Name of the Action for moving the caret to the beginning of the document. String beginLineAction Name of the Action for moving the caret to the beginning of a line. String beginParagraphAction Name of the Action for moving the caret to the beginning of a paragraph. String beginWordAction Name of the Action for moving the caret to the beginning of a word. String copyAction Name of the action to copy the selected region and place the contents into the system clipboard. String cutAction Name of the action to cut the selected region and place the contents into the system clipboard. String defaultKeyTypedAction Name of the action that is executed by default if a key typed event is received and there is no keymap entry. String deleteNextCharAction Name of the action to delete the character of content that follows the current caret position. String deleteNextWordAction Name of the action to delete the word that follows the beginning of the selection. String deletePrevCharAction Name of the action to delete the character of content that precedes the current caret position. String deletePrevWordAction Name of the action to delete the word that precedes the beginning of the selection. String downAction Name of the Action for moving the caret logically downward one position. String endAction Name of the Action for moving the caret to the end of the document. String endLineAction Name of the Action for moving the caret to the end of a line. String endParagraphAction Name of the Action for moving the caret to the end of a paragraph. String endWordAction Name of the Action for moving the caret to the end of a word. String forwardAction Name of the Action for moving the caret logically forward one position. String insertBreakAction Name of the action to place a line/paragraph break into the document. String insertContentAction Name of the action to place content into the associated document. String insertTabAction Name of the action to place a tab character into the document. String nextWordAction Name of the Action for moving the caret to the beginning of the next word. String pageDownAction Name of the action to page down vertically. String pageUpAction Name of the action to page up vertically. String pasteAction Name of the action to paste the contents of the system clipboard into the selected region, or before the caret if nothing is selected. String previousWordAction Name of the Action for moving the caret to the beginning of the previous word. String readOnlyAction Name of the action to set the editor into read-only mode. String selectAllAction Name of the Action for selecting the entire document String selectLineAction Name of the Action for selecting a line around the caret. String selectParagraphAction Name of the Action for selecting a paragraph around the caret. String selectWordAction Name of the Action for selecting a word around the caret. String selectionBackwardAction Name of the Action for extending the selection by moving the caret logically backward one position. String selectionBeginAction Name of the Action for moving the caret to the beginning of the document. String selectionBeginLineAction Name of the Action for moving the caret to the beginning of a line, extending the selection. String selectionBeginParagraphAction Name of the Action for moving the caret to the beginning of a paragraph, extending the selection. String selectionBeginWordAction Name of the Action for moving the caret to the beginning of a word, extending the selection. String selectionDownAction Name of the Action for moving the caret logically downward one position, extending the selection. String selectionEndAction Name of the Action for moving the caret to the end of the document. String selectionEndLineAction Name of the Action for moving the caret to the end of a line, extending the selection. String selectionEndParagraphAction Name of the Action for moving the caret to the end of a paragraph, extending the selection. String selectionEndWordAction Name of the Action for moving the caret to the end of a word, extending the selection. String selectionForwardAction Name of the Action for extending the selection by moving the caret logically forward one position. String selectionNextWordAction Name of the Action for moving the selection to the beginning of the next word, extending the selection. String selectionPreviousWordAction Name of the Action for moving the selection to the beginning of the previous word, extending the selection. String selectionUpAction Name of the Action for moving the caret logically upward one position, extending the selection. String upAction Name of the Action for moving the caret logically upward one position. String writableAction Name of the action to set the editor into writeable mode.

[Expand] Inherited Methods
From class javax.swing.text.StyledEditorKit Object clone() Creates a copy of the editor kit. Document createDefaultDocument() Creates an uninitialized text storage model that is appropriate for this type of editor. void createInputAttributes(Element element, MutableAttributeSet set) Copies the key/values in elements AttributeSet into set. void deinstall(JEditorPane c) Called when the kit is being removed from the JEditorPane. Action[] getActions() Fetches the command list for the editor. Element getCharacterAttributeRun() Fetches the element representing the current run of character attributes for the caret. MutableAttributeSet getInputAttributes() Gets the input attributes for the pane. ViewFactory getViewFactory() Fetches a factory that is suitable for producing views of any models that are produced by this kit. void install(JEditorPane c) Called when the kit is being installed into a JEditorPane.
From class javax.swing.text.DefaultEditorKit Caret createCaret() Fetches a caret that can navigate through views produced by the associated ViewFactory. Document createDefaultDocument() Creates an uninitialized text storage model (PlainDocument) that is appropriate for this type of editor. Action[] getActions() Fetches the set of commands that can be used on a text component that is using a model and view produced by this kit. String getContentType() Gets the MIME type of the data that this kit represents support for. ViewFactory getViewFactory() Fetches a factory that is suitable for producing views of any models that are produced by this kit. void read(InputStream in, Document doc, int pos) Inserts content from the given stream which is expected to be in a format appropriate for this kind of content handler. void read(Reader in, Document doc, int pos) Inserts content from the given stream, which will be treated as plain text. void write(Writer out, Document doc, int pos, int len) Writes content from a document to the given stream as plain text. void write(OutputStream out, Document doc, int pos, int len) Writes content from a document to the given stream in a format appropriate for this kind of content handler.
From class javax.swing.text.EditorKit Object clone() Creates a copy of the editor kit. abstract Caret createCaret() Fetches a caret that can navigate through views produced by the associated ViewFactory. abstract Document createDefaultDocument() Creates an uninitialized text storage model that is appropriate for this type of editor. void deinstall(JEditorPane c) Called when the kit is being removed from the JEditorPane. abstract Action[] getActions() Fetches the set of commands that can be used on a text component that is using a model and view produced by this kit. abstract String getContentType() Gets the MIME type of the data that this kit represents support for. abstract ViewFactory getViewFactory() Fetches a factory that is suitable for producing views of any models that are produced by this kit. void install(JEditorPane c) Called when the kit is being installed into the a JEditorPane. abstract void read(InputStream in, Document doc, int pos) Inserts content from the given stream which is expected to be in a format appropriate for this kind of content handler. abstract void read(Reader in, Document doc, int pos) Inserts content from the given stream which is expected to be in a format appropriate for this kind of content handler. abstract void write(Writer out, Document doc, int pos, int len) Writes content from a document to the given stream in a format appropriate for this kind of content handler. abstract void write(OutputStream out, Document doc, int pos, int len) Writes content from a document to the given stream in a format appropriate for this kind of content handler.
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait() Causes the current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object. final void wait(long timeout, int nanos) Causes the current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed. final void wait(long timeout) Causes the current thread to wait until either another thread invokes the notify() method or the notifyAll() method for this object, or a specified amount of time has elapsed.
From interface javax.accessibility.Accessible abstract AccessibleContext getAccessibleContext() Returns the AccessibleContext associated with this object.