Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Swing 1.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.swing.text.html
Class HTMLEditorKit

    java.lang.Object
      |
      +--javax.swing.text.EditorKit
            |
            +--javax.swing.text.DefaultEditorKit
                  |
                  +--javax.swing.text.StyledEditorKit
                        |
                        +--javax.swing.text.html.HTMLEditorKit

public class HTMLEditorKit
extends StyledEditorKit

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`. It's 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 seperate 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.

See Also:
  Serialized Form

Inner Class Summary
`static class` | `HTMLEditorKit.HTMLFactory` A factory to build views for html.
`static class` | `HTMLEditorKit.HTMLTextAction` An abstract Action providing some convenience methods that may be useful in inserting HTML into an existing document.
`static class` | `HTMLEditorKit.InsertHTMLTextAction` InsertHTMLTextAction can be used to insert an arbitrary string of HTML into an existing HTML document.
`static class` | `HTMLEditorKit.LinkController` Class to watch the associated component and fire hyperlink events on it when appropriate.
`static class` | `HTMLEditorKit.Parser` Interface to be supported by the parser.
`static class` | `HTMLEditorKit.ParserCallback` The result of parsing drives these callback methods.

Inner classes inherited from class javax.swing.text.StyledEditorKit
`StyledEditorKit.AlignmentAction, StyledEditorKit.BoldAction, StyledEditorKit.FontFamilyAction, StyledEditorKit.FontSizeAction, StyledEditorKit.ForegroundAction, StyledEditorKit.ItalicAction, StyledEditorKit.StyledTextAction, StyledEditorKit.UnderlineAction`

Inner classes inherited from class javax.swing.text.DefaultEditorKit
`DefaultEditorKit.BeepAction, DefaultEditorKit.CopyAction, DefaultEditorKit.CutAction, DefaultEditorKit.DefaultKeyTypedAction, DefaultEditorKit.InsertBreakAction, DefaultEditorKit.InsertContentAction, DefaultEditorKit.InsertTabAction, DefaultEditorKit.PasteAction`

Field Summary
`static java.lang.String` | `BOLD_ACTION` The bold action identifier
`static java.lang.String` | `COLOR_ACTION` The Color choice action identifier The color is passed as an argument
`static java.lang.String` | `DEFAULT_CSS` Default Cascading Style Sheet file that sets up the tag views.
`static java.lang.String` | `FONT_CHANGE_BIGGER` The font size increase to next value action identifier
`static java.lang.String` | `FONT_CHANGE_SMALLER` The font size decrease to next value action identifier
`static java.lang.String` | `IMG_ALIGN_BOTTOM` Align images at the bottom.
`static java.lang.String` | `IMG_ALIGN_MIDDLE` Align images in the middle.
`static java.lang.String` | `IMG_ALIGN_TOP` Align images at the top.
`static java.lang.String` | `IMG_BORDER` Align images at the border.
`static java.lang.String` | `ITALIC_ACTION` The italic action identifier
`static java.lang.String` | `LOGICAL_STYLE_ACTION` The logical style choice action identifier The logical style is passed in as an argument
`static java.lang.String` | `PARA_INDENT_LEFT` The paragraph left indent action identifier
`static java.lang.String` | `PARA_INDENT_RIGHT` The paragraph right indent action identifier

Fields inherited from class javax.swing.text.DefaultEditorKit
`backwardAction, beepAction, beginAction, beginLineAction, beginParagraphAction, beginWordAction, copyAction, cutAction, defaultKeyTypedAction, deleteNextCharAction, deletePrevCharAction, downAction, endAction, endLineAction, EndOfLineStringProperty, endParagraphAction, endWordAction, forwardAction, insertBreakAction, insertContentAction, insertTabAction, nextWordAction, pageDownAction, pageUpAction, pasteAction, previousWordAction, readOnlyAction, selectAllAction, selectionBackwardAction, selectionBeginAction, selectionBeginLineAction, selectionBeginParagraphAction, selectionBeginWordAction, selectionDownAction, selectionEndAction, selectionEndLineAction, selectionEndParagraphAction, selectionEndWordAction, selectionForwardAction, selectionNextWordAction, selectionPreviousWordAction, selectionUpAction, selectLineAction, selectParagraphAction, selectWordAction, upAction, writableAction`

Constructor Summary
`HTMLEditorKit()` Constructs an HTMLEditorKit, creates a StyleContext, and loads the style sheet.

Method Summary
`java.lang.Object` | `clone()` Create a copy of the editor kit.
`Document` | `createDefaultDocument()` Create an uninitialized text storage model that is appropriate for this type of editor.
`protected void` | `createInputAttributes(Element element, MutableAttributeSet set)` Copies the key/values in `element`s 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.
`java.lang.String` | `getContentType()` Get the MIME type of the data that this kit represents support for.
`protected HTMLEditorKit.Parser` | `getParser()` Fetch the parser to use for reading html streams.
`StyleSheet` | `getStyleSheet()` Get the set of styles currently being used to render the html elements.
`ViewFactory` | `getViewFactory()` Fetch a factory that is suitable for producing views of any models that are produced by this kit.
`void` | `insertHTML(HTMLDocument doc, int offset, java.lang.String html, int popDepth, int pushDepth, HTML.Tag insertTag)` Inserts HTML into an existing document.
`void` | `install(JEditorPane c)` Called when the kit is being installed into the a JEditorPane.
`void` | `read(java.io.Reader in, Document doc, int pos)` Create and initialize a model from the given stream which is expected to be in a format appropriate for this kind of editor.
`void` | `setStyleSheet(StyleSheet s)` Set the set of styles to be used to render the various html elements.
`void` | `write(java.io.Writer out, Document doc, int pos, int len)` Write content from a document to the given stream in a format appropriate for this kind of content handler.

Methods inherited from class javax.swing.text.StyledEditorKit
`getCharacterAttributeRun, getInputAttributes`

Methods inherited from class javax.swing.text.DefaultEditorKit
`createCaret, read, write`

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### DEFAULT_CSS

    public static final java.lang.String DEFAULT_CSS

  Default Cascading Style Sheet file that sets up the tag views.

### BOLD_ACTION

    public static final java.lang.String BOLD_ACTION

  The bold action identifier

### ITALIC_ACTION

    public static final java.lang.String ITALIC_ACTION

  The italic action identifier

### PARA_INDENT_LEFT

    public static final java.lang.String PARA_INDENT_LEFT

  The paragraph left indent action identifier

### PARA_INDENT_RIGHT

    public static final java.lang.String PARA_INDENT_RIGHT

  The paragraph right indent action identifier

### FONT_CHANGE_BIGGER

    public static final java.lang.String FONT_CHANGE_BIGGER

  The font size increase to next value action identifier

### FONT_CHANGE_SMALLER

    public static final java.lang.String FONT_CHANGE_SMALLER

  The font size decrease to next value action identifier

### COLOR_ACTION

    public static final java.lang.String COLOR_ACTION

  The Color choice action identifier The color is passed as an argument

### LOGICAL_STYLE_ACTION

    public static final java.lang.String LOGICAL_STYLE_ACTION

  The logical style choice action identifier The logical style is passed in as an argument

### IMG_ALIGN_TOP

    public static final java.lang.String IMG_ALIGN_TOP

  Align images at the top.

### IMG_ALIGN_MIDDLE

    public static final java.lang.String IMG_ALIGN_MIDDLE

  Align images in the middle.

### IMG_ALIGN_BOTTOM

    public static final java.lang.String IMG_ALIGN_BOTTOM

  Align images at the bottom.

### IMG_BORDER

    public static final java.lang.String IMG_BORDER

  Align images at the border.

Constructor Detail

### HTMLEditorKit

    public HTMLEditorKit()

  Constructs an HTMLEditorKit, creates a StyleContext, and loads the style sheet.

Method Detail

### clone

    public java.lang.Object clone()

  Create a copy of the editor kit. This allows an implementation to serve as a prototype for others, so that they can be quickly created.
  Returns:
    the copy
  Overrides:
    clone in class StyledEditorKit

### getContentType

    public java.lang.String getContentType()

  Get the MIME type of the data that this kit represents support for. This kit supports the type `text/html`.
  Returns:
    the type
  Overrides:
    getContentType in class DefaultEditorKit

### getViewFactory

    public ViewFactory getViewFactory()

  Fetch a factory that is suitable for producing views of any models that are produced by this kit.
  Returns:
    the factory
  Overrides:
    getViewFactory in class StyledEditorKit

### createDefaultDocument

    public Document createDefaultDocument()

  Create an uninitialized text storage model that is appropriate for this type of editor.
  Returns:
    the model
  Overrides:
    createDefaultDocument in class StyledEditorKit

### read

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

  Create and initialize a model from the given stream which is expected to be in a format appropriate for this kind of editor. This is implemented to read html 3.2 text.
  Parameters:
    `in` - The stream to read from
    `doc` - The destination for the insertion.
    `pos` - The location in the document to place the content.
  Throws:
    java.io.IOException - on any I/O error
    BadLocationException - if pos represents an invalid location within the document.
  Overrides:
    read in class DefaultEditorKit

### insertHTML

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

  Inserts HTML into an existing document.
  Parameters:
    `doc` - Document to insert into.
    `offset` - offset to insert HTML at
    `popDepth` - number of ElementSpec.EndTagTag to generate before inserting.
    `pushDepth` - number of ElementSpec.StartTagType with a direction of ElementSpec.JoinNextDirection that should be generated before inserting, but after the end tags have been generated.
    `insertTag` - first tag to start inserting into document.

### write

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

  Write content from a document to the given stream in a format appropriate for this kind of content handler.
  Parameters:
    `out` - The stream to write to
    `doc` - The source for the write.
    `pos` - The location in the document to fetch the content.
    `len` - The amount to write out.
  Throws:
    java.io.IOException - on any I/O error
    BadLocationException - if pos represents an invalid location within the document.
  Overrides:
    write in class DefaultEditorKit

### install

    public void install(JEditorPane c)

  Called when the kit is being installed into the a JEditorPane.
  Parameters:
    `c` - the JEditorPane
  Overrides:
    install in class StyledEditorKit

### deinstall

    public void deinstall(JEditorPane c)

  Called when the kit is being removed from the JEditorPane. This is used to unregister any listeners that were attached.
  Parameters:
    `c` - the JEditorPane
  Overrides:
    deinstall in class StyledEditorKit

### setStyleSheet

    public void setStyleSheet(StyleSheet s)

  Set the set of styles to be used to render the various html elements. These styles are specified in terms of css specifications. Each document produced by the kit will have a copy of the sheet which it can add the document specific styles to. By default, the StyleSheet specified is shared by all HTMLEditorKit instances. This should be reimplemented to provide a finer granularity if desired.

### getStyleSheet

    public StyleSheet getStyleSheet()

  Get the set of styles currently being used to render the html elements. By default the resource specified by DEFAULT_CSS gets loaded, and is shared by all HTMLEditorKit instances.

### getActions

    public Action[] getActions()

  Fetches the command list for the editor. This is the list of commands supported by the superclass augmented by the collection of commands defined locally for style operations.
  Returns:
    the command list
  Overrides:
    getActions in class StyledEditorKit

### createInputAttributes

    protected void createInputAttributes(Element element,
                                         MutableAttributeSet set)

  Copies the key/values in `element`s AttributeSet into `set`. This does not copy component, icon, or element names attributes. Subclasses may wish to refine what is and what isn't copied here. But be sure to first remove all the attributes that are in `set`.

  This is called anytime the caret moves over a different location.

  Overrides:
    createInputAttributes in class StyledEditorKit

### getParser

    protected HTMLEditorKit.Parser getParser()

  Fetch the parser to use for reading html streams. This can be reimplemented to provide a different parser. The default implementation is loaded dynamically to avoid the overhead of loading the default parser if it's not used. The default parser is the HotJava parser using an html 3.2 dtd.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Swing 1.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road,
Palo Alto, California, 94303, U.S.A. All Rights Reserved.