Generated by
JDiff

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.

Class BlockView

A view implementation to display a block (as a box) with CSS specifications. @author Timothy Prinzing @version 1.25 0232 12/0203/0001
Class BlockView, float getMaximumSpan(int)

Determines the maximum span for this view along an axis. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into >= 0.; Typicallytypically the view is told to render into the span that is returned although there is no guarantee.; Thethe parent may choose to resize or break the view. @exception IllegalArgumentException for an invalid axis type
Class BlockView, float getMinimumSpan(int)

Determines the minimum span for this view along an axis. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into >= 0.; Typicallytypically the view is told to render into the span that is returned although there is no guarantee.; Thethe parent may choose to resize or break the view. @exception IllegalArgumentException for an invalid axis type
Class BlockView, float getPreferredSpan(int)

Determines the preferred span for this view along an axis. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into >= 0.; Typicallytypically the view is told to render into the span that is returned although there is no guarantee.; Thethe parent may choose to resize or break the view. @exception IllegalArgumentException for an invalid axis type
Class BlockView, void layoutMinorAxis(int, int, int[], int[])

Perform layout for the minor axis of the box (i.e. the axis orthoginal to the axis that it represents). The results of the layout should be placed in the given arrays which represent the allocations to the children along the minor axis. @param targetSpan the total span given to the view which whould be used to layout the childrenchildre. @param axis the axis being layed out. @param offsets the offsets from the origin of the view for each of the child views. This; this is a return value and is filled in by the implementation of this method. @param spans the span of each child view. This; this is a return value and is filled in by the implementation of this method. @returnsreturn the offset and span for each child view in the offsets and spans parameters.
Class BlockView, void setParent(View)

Establishes the parent view for this view. This is guaranteed to be called before any other methods if the parent view is functioning properly.

This is implemented to forward to the superclass as well as call the #setPropertiesFromAttributes() method to set the paragraph properties from the css attributes. The call is made at this time to ensure the ability to resolve upward through the parents view attributes. @param parent the new parent or null if the view is being removed from a parent it was previously added to


Class CSS

Defines a set of CSS attributes as a typesafe enumeration. The HTML View implementations use CSS attributes to determine how they will render. This also defines methods to map between CSS/HTML/StyleConstants. Any shorthand properties such as font are mapped to the intrinsic properties.

The following describes the CSS properties that are suppored by the rendering engine:

The following are modeled but currently not rendered.

Note: for the time being we do not fully support relative units unless noted so that p { margin-top: 10% } will be treated as if no margin-top was specified. @author Timothy Prinzing @author Scott Violet @version 1.30 0239 12/0203/0001 @see StyleSheet

Class CSS, Attribute getAttribute(String)

TranslateTranslates a string to a CSS.Attribute object. This will return null if there is no attribute by the given name. @param name the name of the CSS attribute to fetch the typesafe enumeration for. @returnsreturn the CSS.Attribute object or null if the string doesn't represent a valid attribute key.

Class FormView

Component decorator that implements the view interface for form elements <input> <textarea> and <select>. The model for the component is stored as an attribute of the the element (using StyleConstants.ModelAttribute) and is used to build the component of the view. The type of the model is assumed to of the type that would be set by HTMLDocument.HTMLReader.FormAction. If there are multiple views mapped over the document they will share the embedded component models.

The following table shows what components get built by this view.
Element Type Component built
input type button JButton
input type checkbox JCheckBox
input type image JButton
input type password JPasswordField
input type radio JRadioButton
input type reset JButton
input type submit JButton
input type text JTextField
select size > 1 or multiple attribute defined JList in a JScrollPane
select size unspecified or 1 JComboBox
textarea JTextArea in a JScrollPane
input type file JTextField
@author Timothy Prinzing @author Sunita Mani @version 1.14 0218 12/0203/0001

Class FormView, float getMaximumSpan(int)

Determines the maximum span for this view along an axis. This is implementedFor certain components tothe maximum and preferred span are the same. For others this will return the value returned by Component.getMaximumSize along the axis of interest. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned although there is no guarantee. The parent may choose to resize or break the view. @exception IllegalArgumentException for an invalid axis

Class HTML

Constants used in the HTMLDocument. These are basically tag and attribute definitions. @author Timothy Prinzing @author Sunita Mani @version 1.31 0238 12/0203/0001

Class HTML.Attribute

Typesafe enumeration representing an htmlHTML attribute.

Class HTML.Tag

Typesafe enumeration for an htmlHTML tag. Although the set of htmlHTML tags is a closed set we have letleft the set open so that people can add their own tag types to their custom parser and still communicate to the reader.
Class HTML.Tag, boolean breaksFlow()

IfReturns thetrue if this tag causes a line break to the flow of data thenotherwise this methodreturns willfalse. @return true. if this tag causes a line break to the flow of data otherwise returns false
Class HTML.Tag, boolean isBlock()

BlockReturns tagstrue are tags thatif this tag is a block tag which is a tag used to add structure to a document. @return true if this tag is a block tag otherwise returns false
Class HTML.Tag, String toString()

ReturnReturns the string representation of the tag. @return the String representation of the tag
Class HTML.Tag, Tag COMMENT

All comments are labeled with this tag.

This is a tag synthesized by the htmlHTML reader. Since elements are identified by their tag type we create a some fake tag types to mark the elements that were manufactured.

Class HTML.Tag, Tag CONTENT

All text content is labeled with this tag.

This is a tag synthesized by the htmlHTML reader. Since elements are identified by their tag type we create a some fake tag types to mark the elements that were manufactured.

Class HTML.Tag, Tag IMPLIED

All text content must be in a paragraph element. If a paragraph didn't exist when content was encountered a paragraph is manufactured.

This is a tag synthesized by the htmlHTML reader. Since elements are identified by their tag type we create a some fake tag types to mark the elements that were manufactured.


Class HTML.UnknownTag, boolean equals(Object)

Compares this object to the specifed object. The result is true if and only if the argument is not null and is aan UnknownTag object with the same name. @param obj the object to compare this tag with. @return true if the objects are equal; false otherwise.

Class HTML, Attribute[] getAllAttributeKeys()

ThisReturns is the set of htmlHTML attributes recognized. @return the set of HTML attributes recognized
Class HTML, Tag[] getAllTags()

This isReturns the set of actual htmlHTML tags that are known aboutrecognized theby the default htmlHTML reader. This set does not include tags that are manufactured by the reader.
Class HTML, Attribute getAttributeKey(String)

FetchFetches an attribute constant for a well-known attribute name (i.e. one of the attributes in the set allAttributes{FACE COMMENT SIZE COLOR CLEAR BACKGROUND BGCOLOR TEXT LINK VLINK ALINK WIDTH HEIGHT ALIGN NAME HREF REL REV TITLE TARGET SHAPE COORDS ISMAP NOHREF ALT ID SRC HSPACE VSPACE USEMAP LOWSRC CODEBASE CODE ARCHIVE VALUE VALUETYPE TYPE CLASS STYLE LANG DIR DECLARE CLASSID DATA CODETYPE STANDBY BORDER SHAPES NOSHADE COMPACT START ACTION METHOD ENCTYPE CHECKED MAXLENGTH MULTIPLE SELECTED ROWS COLS DUMMY CELLSPACING CELLPADDING VALIGN HALIGN NOWRAP ROWSPAN COLSPAN PROMPT HTTPEQUIV CONTENT LANGUAGE VERSION N FRAMEBORDER MARGINWIDTH MARGINHEIGHT SCROLLING NORESIZE MEDIA ENDTAG}). If the given name does not represent one of the well-known attributes then null will be returned. @param attName the String requested @return the Attribute corresponding to attName
Class HTML, int getIntegerAttributeValue(AttributeSet, Attribute, int)

FetchFetches an integer attribute value. Attribute values are stored as a string and this is a convenience method to convert to an actual integer. @param attr the set of attributes to use to try to fetch a value @param key the key to use to fetch the value. @param def the default value to use if the attribute isn't defined or there is an error converting to an integer.
Class HTML, Tag getTag(String)

FetchFetches a tag constant for a well-known tag name (i.e. one of the tags in the set allTags){A ADDRESS APPLET AREA B BASE BASEFONT BIG BLOCKQUOTE BODY BR CAPTION CENTER CITE CODE DD DFN DIR DIV DL DT EM FONT FORM FRAME FRAMESET H1 H2 H3 H4 H5 H6 HEAD HR HTML I IMG INPUT ISINDEX KBD LI LINK MAP MENU META NOBR NOFRAMES OBJECT OL OPTION P PARAM PRE SAMP SCRIPT SELECT SMALL SPAN STRIKE S STRONG STYLE SUB SUP TABLE TD TEXTAREA TH TITLE TR TT U UL VAR}. If the given name does not represent one of the well-known tags then null will be returned. @param tagName the String name requested @return a tag constant corresponding to the tagName or null if not found

Class HTMLDocument

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.133 02147 12/0203/0001


Class HTMLDocument.HTMLReader

An HTML reader to load an HTML document with an HTML element structure. This is a set of callbacks from the parser implemented to create a set of elements tagged with attributes. The parse builds up tokens (ElementSpec) that describe the element subtree desired and burst it into the document under the protection of a write lock using the insert method on the document outer class.

The reader can be configured by registering actions (of type HTMLDocument.HTMLReader.TagAction) that describe how to handle the action. The idea behind the actions provided is that the most natural text editing operations can be provided if the element structure boils down to paragraphs with runs of some kind of style in them. Some things are more naturally specified structurally so arbitrary structure should be allowed above the paragraphs but will need to be edited with structural actions. The implication of this is that some of the HTML elements specified in the stream being parsed will be collapsed into attributes and in some cases paragraphs will be synthesized. When HTML elements have been converted to attributes the attribute key will be of type HTML.Tag and the value will be of type AttributeSet so that no information is lost. This enables many of the existing actions to work so that the user can type input hit the return key backspace delete etc and have a reasonable result. Selections can be created and attributes applied or removed etc. With this in mind the work done by the reader can be categorized into the following kinds of tasks:

Block
Build the structure like it's specified in the stream. This produces elements that contain other elements.
Paragraph
Like block except that it's expected that the element will be used with a paragraph view so a paragraph element won't need to be synthesized.
Character
Contribute the element as an attribute that will start and stop at arbitrary text locations. This will ultimately be mixed into a run of text with all of the currently flattened HTML character elements.
Special
Produce an embedded graphical element.
Form
Produce an element that is like the embedded graphical element except that it also has a component model associated with it.
Hidden
Create an element that is hidden from view when the document is being viewed read-only and visible when the document is being edited. This is useful to keep the model from losing information and used to store things like comments and unrecognized tags.

Currently <APPLET> <PARAM> <MAP> <AREA> <LINK> <SCRIPT> and <STYLE> are unsupported.

The assignment of the actions described is shown in the following table for the tags defined in HTML.Tag.
HTML.Tag.A CharacterAction
HTML.Tag.ADDRESS CharacterAction
HTML.Tag.APPLET HiddenAction
HTML.Tag.AREA AreaAction
HTML.Tag.B CharacterAction
HTML.Tag.BASE BaseAction
HTML.Tag.BASEFONT CharacterAction
HTML.Tag.BIG CharacterAction
HTML.Tag.BLOCKQUOTEBlockAction
HTML.Tag.BODY BlockAction
HTML.Tag.BR SpecialAction
HTML.Tag.CAPTION BlockAction
HTML.Tag.CENTER BlockAction
HTML.Tag.CITE CharacterAction
HTML.Tag.CODE CharacterAction
HTML.Tag.DD BlockAction
HTML.Tag.DFN CharacterAction
HTML.Tag.DIR BlockAction
HTML.Tag.DIV BlockAction
HTML.Tag.DL BlockAction
HTML.Tag.DT ParagraphAction
HTML.Tag.EM CharacterAction
HTML.Tag.FONT CharacterAction
HTML.Tag.FORM CharacterActionAs of 1.4 a BlockAction
HTML.Tag.FRAME SpecialAction
HTML.Tag.FRAMESET BlockAction
HTML.Tag.H1 ParagraphAction
HTML.Tag.H2 ParagraphAction
HTML.Tag.H3 ParagraphAction
HTML.Tag.H4 ParagraphAction
HTML.Tag.H5 ParagraphAction
HTML.Tag.H6 ParagraphAction
HTML.Tag.HEAD HeadAction
HTML.Tag.HR SpecialAction
HTML.Tag.HTML BlockAction
HTML.Tag.I CharacterAction
HTML.Tag.IMG SpecialAction
HTML.Tag.INPUT FormAction
HTML.Tag.ISINDEX IsndexAction
HTML.Tag.KBD CharacterAction
HTML.Tag.LI BlockAction
HTML.Tag.LINK LinkAction
HTML.Tag.MAP MapAction
HTML.Tag.MENU BlockAction
HTML.Tag.META MetaAction
HTML.Tag.NOFRAMES BlockAction
HTML.Tag.OBJECT SpecialAction
HTML.Tag.OL BlockAction
HTML.Tag.OPTION FormAction
HTML.Tag.P ParagraphAction
HTML.Tag.PARAM HiddenAction
HTML.Tag.PRE PreAction
HTML.Tag.SAMP CharacterAction
HTML.Tag.SCRIPT HiddenAction
HTML.Tag.SELECT FormAction
HTML.Tag.SMALL CharacterAction
HTML.Tag.STRIKE CharacterAction
HTML.Tag.S CharacterAction
HTML.Tag.STRONG CharacterAction
HTML.Tag.STYLE StyleAction
HTML.Tag.SUB CharacterAction
HTML.Tag.SUP CharacterAction
HTML.Tag.TABLE BlockAction
HTML.Tag.TD BlockAction
HTML.Tag.TEXTAREA FormAction
HTML.Tag.TH BlockAction
HTML.Tag.TITLE TitleAction
HTML.Tag.TR BlockAction
HTML.Tag.TT CharacterAction
HTML.Tag.U CharacterAction
HTML.Tag.UL BlockAction
HTML.Tag.VAR CharacterAction

Once </html> is encountered the Actions are no longer notified.


Class HTMLDocument.Iterator, AttributeSet getAttributes()

FetchReturn the attributes for this tag. @return the AttributeSet for this tag or null if none can be found
Class HTMLDocument.Iterator, int getEndOffset()

EndReturns the end of the range for which the current occurenceoccurrence of the tag is defined and has the same attributes. @return the end of the range
Class HTMLDocument.Iterator, int getStartOffset()

StartReturns the start of the range for which the current occurenceoccurrence of the tag is defined and has the same attributes. @return the start of the range or -1 if it can't be found
Class HTMLDocument.Iterator, boolean isValid()

Indicates if the iterator is currently representing an occurenceoccurrence of a tag. If false there are no more tags for this iterator. @return true if the iterator is currently representing an occurrence of a tag otherwise returns false
Class HTMLDocument.Iterator, void next()

Move the iterator forward to the next occurenceoccurrence of the tag it represents.

Class HTMLDocument, constructor HTMLDocument()

Constructs an HTML document using the default buffer size and a default StyleSheet. This is a convenience method for the constructor HTMLDocument(Content StyleSheet).
Class HTMLDocument, constructor HTMLDocument(StyleSheet)

Constructs an HTML document with the default content storage implementation and the givenspecified style/attribute storage mechanism. This is a convenience method for the constructor HTMLDocument(Content StyleSheet). @param styles the styles
Class HTMLDocument, void create(ElementSpec[])

Replaces the contents of the document with the given element specifications. This is called before insert if the loading is done in bursts. This is the only method called if loading the document entirely in one burst. @param data the new contents of the document
Class HTMLDocument, URL getBase()

GetsReturns the location to resolve relative URLs against. By default this will be the document's URL if the document was loaded from a URL. If a base tag is found and can be parsed it will be used as the base location. @return the base location
Class HTMLDocument, Element getElement(Element, Object, Object)

Returns the child element of e that contains the attribute attribute with value value or null if one isn't found. This is not thread-safe. @param e the root element where the search begins @param attribute the desired Attribute @param value the values for the specified Attribute @return the element with the specified Attribute and the specified value or null if it can't be found @see javax.swing.text.html.HTML.Attribute @since 1.3
Class HTMLDocument, Element getElement(String)

FetchesReturns the element that has the given id attributeAttribute. If the element can't be found null is returned. Note that this method works on an Attribute not a character tag. In the following HTML snippet: <a id="HelloThere"> the attribute is 'id' and the character tag is 'a'. This is a convenience method for getElement(RootElement HTML.Attribute.id id). This is not thread-safe. @param id the string representing the desired Attribute @return the element with the specified Attribute or null if it can't be found or null if id is null @see javax.swing.text.html.HTML.Attribute @since 1.3
Class HTMLDocument, Iterator getIterator(Tag)

Fetches an iterator for the followingspecified kind of HTML tag. This can be used for things like iterating over the set of anchors contained or iterating over the input elements. @param t the requested HTML.Tag @return the etcIterator for the given HTML tag @see javax.swing.text.html.HTML.Tag
Class HTMLDocument, Parser getParser()

Returns the parser that is used when inserting HTML into the existing document. @return the parser used for text insertion @since 1.3
Class HTMLDocument, boolean getPreservesUnknownTags()

Returns the behavior the parser observes when encountering unknown tags. @see javax.swing.text.html.HTML.Tag @return true if unknown tags are to be preserved when parsing.
Class HTMLDocument, ParserCallback getReader(int)

Fetches the reader for the parser to use to loadwhen loading the document with HTML. This is implemented to return an instance of HTMLDocument.HTMLReader. Subclasses can reimplement this method to change how the document getgets structured if desired. (e.g.For example to handle custom tags or structurally represent character style elements etc.). @param pos the starting position @return the reader used by the parser to load the document
Class HTMLDocument, ParserCallback getReader(int, int, int, Tag)

FetchesReturns the reader for the parser to use to load the document with HTML. This is implemented to return an instance of HTMLDocument.HTMLReader. Subclasses can reimplement this method to change how the document getgets structured if desired. (e.g.For example to handle custom tags or structurally represent character style elements.)

This is a convenience method for etcgetReader(int int int HTML.Tag TRUE). @param popDepth the number of ElementSpec.EndTagTypes to generate before inserting @param pushDepth the number of ElementSpec.StartTagTypes with a direction of ElementSpec.JoinNextDirection that should be generated before inserting but after the end tags have been generated @param insertTag the first tag to start inserting into document @return the reader used by the parser to load the document

Class HTMLDocument, StyleSheet getStyleSheet()

Fetches the StyleSheet with the document-specific display rules (CSS) that were specified in the HTML document itself. @return the StyleSheet
Class HTMLDocument, int getTokenThreshold()

Gets the number of tokens to buffer before trying to update the documents element structure. ByThe default thisvalue willis be Integer.MAX_VALUE. @return the number of tokens to buffer
Class HTMLDocument, void insertAfterEnd(Element, String)

Inserts the HTML specified as a string after the the end of the given element.

For this to work correcty the receiverdocument must have an HTMLEditorKit.Parser set. This will be the case if the receiverdocument was created from an HTMLEditorKit via the createDefaultDocument method. @param elem the element to be the root for the new text @param htmlText the string to be parsed and assigned to elem @throws IllegalStateException if an HTMLEditorKit.Parser has not been set on the receiver.document @since 1.3

Class HTMLDocument, void insertAfterStart(Element, String)

Inserts the HTML specified as a string at the start of the element.

For this to work correcty the receiverdocument must have an HTMLEditorKit.Parser set. This will be the case if the receiverdocument was created from an HTMLEditorKit via the createDefaultDocument method. @param elem the branch element to be the root for the new text @param htmlText the string to be parsed and assigned to elem @throws IllegalStateException if an HTMLEditorKit.Parser has not been set on the receiver.document @since 1.3

Class HTMLDocument, void insertBeforeEnd(Element, String)

Inserts the HTML specified as a string at the end of the element.

If elem's children are leafs atleaves and the character at a elem.getEndOffset() - 1 is a newline this will insert before the newline so that there isn't text after the newline.

For this to work correcty the receiverdocument must have an HTMLEditorKit.Parser set. This will be the case if the receiverdocument was created from an HTMLEditorKit via the createDefaultDocument method. @param elem the element to be the root for the new text @param htmlText the string to be parsed and assigned to elem @throws IllegalStateException if an HTMLEditorKit.Parser has not been set on the receiver.document @since 1.3

Class HTMLDocument, void insertBeforeStart(Element, String)

Inserts the HTML specified as a string before the start of the given element.

For this to work correcty the receiverdocument must have an HTMLEditorKit.Parser set. This will be the case if the receiverdocument was created from an HTMLEditorKit via the createDefaultDocument method. @param elem the element to be the root for the new text @param htmlText the string to be parsed and assigned to elem @throws IllegalStateException if an HTMLEditorKit.Parser has not been set on the receiver.document @since 1.3

Class HTMLDocument, void processHTMLFrameHyperlinkEvent(HTMLFrameHyperlinkEvent)

Processes HyperlinkEvents that are generated by documents in an HTML frame. The HyperlinkEvent type as the parameter suggests is HTMLFrameHyperlinkEvent. In addition to the typical information contained in a HyperlinkEvent this event contains the element that corresponds to the frame in which the click happened (the source element) and the target name. The target name has 4 possible values: If target is _self the action is to change the value of the HTML.Attribute.SRC attribute and fires a ChangedUpdate event.

If the target is _parent then it deletes the parent element which is a <FRAMESET> element and inserts a new <FRAME> element and sets its HTML.Attribute.SRC attribute to have a value equal to the destination URL and fire a RemovedUpdate and InsertUpdate.

If the target is _top this method does nothing. In the implementation of the view for a frame namely the FrameView the processing of _top is handled. Given that _top implies replacing the entire document it made sense to handle this outside of the document that it will replace.

If the target is a named frame then the element hierarchy is searched for an element with a name equal to the target its HTML.Attribute.SRC attribute is updated and a ChangedUpdate event is fired. @param e the event

Class HTMLDocument, void setBase(URL)

Sets the location to resolve relative URLs against. By default this will be the document's URL if the document was loaded from a URL. If a base tag is found and can be parsed it will be used as the base location.

This also sets the base of the StyleSheet to be u as well as the receiverbase of the document. @param u the desired base URL

Class HTMLDocument, void setInnerHTML(Element, String)

Replaces the children of the given element with the contents specified as an HTML string.

This will be seen as at least two events n inserts followed by a remove.

For this to work correcty the receiverdocument must have an HTMLEditorKit.Parser set. This will be the case if the receiverdocument was created from an HTMLEditorKit via the createDefaultDocument method. @param elem the branch element whose children will be replaced @param htmlText the string to be parsed and assigned to elem @throws IllegalArgumentException isif elem is a leaf @throws IllegalStateException if an HTMLEditorKit.Parser has not been set on the receiver.defined @since 1.3

Class HTMLDocument, void setOuterHTML(Element, String)

Replaces the given element in the parent with the contents specified as an HTML string.

This will be seen as at least two events n inserts followed by a remove.

When replacing a leaf this will attempt to make sure there is a newline present if one is needed. This may result in an additional element being inserted. Consider if you were to replace a character element that contained a newline with <img> this would create two elements one for the image ane one for the newline.

If you try to replace the element at length you will most likely end up with two elements eg setOuterHTML(getCharacterElement (getLength()) "blah") will result in two leaf elements at the end one representing 'blah' and the other representing the end element.

For this to work correcty the receiverdocument must have an HTMLEditorKit.Parser set. This will be the case if the receiverdocument was created from an HTMLEditorKit via the createDefaultDocument method. @param elem the branch element whose children will be replaced @param htmlText the string to be parsed and assigned to elem @throws IllegalStateException if an HTMLEditorKit.Parser has not been set on the receiver. @since 1.3

Class HTMLDocument, void setParser(Parser)

Sets the parser that is used by the methods that insert html into the existing document egsuch as setInnerHTML and setOuterHTML...

HTMLEditorKit.createDefaultDocument will set the parser for you. If you create an HTMLDocument by hand be sure and set the parser accordingly. @param parser the parser to be used for text insertion @since 1.3

Class HTMLDocument, void setPreservesUnknownTags(boolean)

SetsDetermines how unknown tags are handled by the parser. If set to true unknown tags are put in the model otherwise they are dropped. @param preservesTags true if unknown tags should be saved in the model otherwise tags are dropped @see javax.swing.text.html.HTML.Tag
Class HTMLDocument, void setTokenThreshold(int)

Sets the number of tokens to buffer before trying to update the documents element structure. @param n the number of tokens to buffer

Class HTMLEditorKit

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 seperateseparate 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.98115 0712/2003/0001

Class HTMLEditorKit.HTMLTextAction

An abstract Action providing some convenience methods that may be useful in inserting HTML into an existing document.

NOTE: None of the convenience methods obtain a lock on the document. If you have another thread modifying the text these methods may have inconsistantinconsistent behavior or return the wrong thing.


Class HTMLEditorKit, Object clone()

CreateCreates a copy of the editor kit. This allows an implementation to serve as a prototype for others so that they can be quickly created. @return the copy

Class HTMLFrameHyperlinkEvent

HTMLFrameHyperlinkEvent is used to notify interested parties that link was activated in a frame. @author Sunita Mani @version 1.4 027 12/0203/0001
Class HTMLFrameHyperlinkEvent, Element getSourceElement()

returnsReturns the elementElement that corresponds to the source of the event. This would alwayswill typically be thean Element representing an anchor. leaf element whose tagIf a constructur that is HTML.Tagused that does not specify a source Element or null was specified as the source Element this will return null.FRAME @return Element indicating source of event or null @since 1.4

Class InlineView

Displays the inline element styles based upon css attributes. @author Timothy Prinzing @version 1.19 0221 12/0203/0001

Class ListView

A view implementation to display an html list @author Timothy Prinzing @version 1.25 0226 12/0203/0001

Class MinimalHTMLWriter

MinimalHTMLWriter is a fallback writer used by the HTMLEditorKit to write out HTML for a document that is a not produced by the EditorKit. The format for the document is:
 <html> <head> <style> < -- list of named styles p.normal { font-family: SansSerif; margin-height: 0; font-size: 14 } --> </style> </head> <body> <p style=normal> Bold italic and underline attributes of the run are emitted as HTML tags. The remaining attributes are emitted as part of the style attribute of a <span> tag. The syntax is similar to inline styles. </p> </body> </html> 
@author Sunita Mani @version 1.11 0212 12/0203/0001

Class ObjectView

Component decorator that implements the view interface for <object> elements.

This view will try to load the class specified by the classid attribute. If possible the Classloader used to load the associated Document is used. This would typically be the same as the ClassLoader used to load the EditorKit. If the documents ClassLoader is null Class.forName is used.

If the class can successfully be loaded an attempt will be made to create an instance of it by calling Class.newInstance. An attempt will be made to narrow the instance to type java.awt.Component to display the object.

This view can also manage a set of parameters with limitations. The parameters to the <object> element are expected to be present on the associated elements attribute set as simple strings. Each bean property will be queried as a key on the AttributeSet with the expectation that a non-null value (of type String) will be present if there was a parameter specification for the property. Reflection is used to set the parameter. Currently this is limited to a very simple single parameter of type String.

A simple example html invocation is:

    
@author Timothy Prinzing @version 1.7 0210 12/0203/0001

Class Option

Value for the ListModel used to represent <option> elements. This is the object installed as items of the DefaultComboBoxModel used to represent the <select> element. @author Timothy Prinzing @version 1.7 028 12/0203/0001

Class ParagraphView

Displays the a paragraph and uses css attributes for its configuration. @author Timothy Prinzing @version 1.21 0226 12/0203/0001
Class ParagraphView, float getMaximumSpan(int)

Determines the maximum span for this view along an axis. Returns 0 if the view is not visible otherwise it calls the superclass method ot get the maximum span. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the maximum span the view can be rendered into. @see javax.swing.text.ParagraphView#getMaximumSpan
Class ParagraphView, float getMinimumSpan(int)

Determines the minimum span for this view along an axis. Returns 0 if the view is not visible otherwise it calls the superclass method to get the minimum span. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the minimum span the view can be rendered into. @see javax.swing.text.ParagraphView#getMinimumSpan
Class ParagraphView, float getPreferredSpan(int)

Determines the preferred span for this view. Returns 0 if the view is not visible otherwise it calls the superclass method to get the preferred span. axis. @param axis may be either View.X_AXIS or View.Y_AXIS @returnsreturn the span the view would like to be rendered into.; Typicallytypically the view is told to render into the span that is returned although there is no guarantee.; Thethe parent may choose to resize or break the view. @see javax.swing.text.ParagraphView#getPreferredSpan
Class ParagraphView, boolean isVisible()

Indicates whether or not this view should be displayed. If none of the children wish to be displayed and the only visible child is the break that ends the paragraph the paragraph will not be considered visible. Otherwise it will be considered visible and return true. @returnsreturn true if the paragraph should be displayed.

Class StyleSheet

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.63 0274 12/0203/0001

Class StyleSheet, Style getRule(Tag, Element)

Fetches the style to use to render the given type of HTML tag. The element given is representing the tag and can be used to determine the nesting for situations where the attributes will differ if nesting inside of elements. @param t the type to translate to visual attributes. @param e the element representing the tag. The; the element can be used to determine the nesting for situations where the attributes will differ if nested inside of other elements. @returnsreturn the set of CSS attributes to use to render the tag.