javax.swing.text.html

Class HTMLDocument

Implemented Interfaces:
Document, Serializable, StyledDocument

public class HTMLDocument
extends DefaultStyledDocument

TODO: Add more comments here
See Also:
Serialized Form

Nested Class Summary

class
HTMLDocument.BlockElement
class
HTMLDocument.HTMLReader
A reader to load an HTMLDocument with HTML structure.
static class
HTMLDocument.Iterator
An iterator over a particular type of tag.
class
HTMLDocument.RunElement
RunElement represents a section of text that has a set of HTML character level attributes assigned to it.

Nested classes/interfaces inherited from class javax.swing.text.DefaultStyledDocument

DefaultStyledDocument.AttributeUndoableEdit, DefaultStyledDocument.ElementBuffer, DefaultStyledDocument.ElementSpec, DefaultStyledDocument.SectionElement

Nested classes/interfaces inherited from class javax.swing.text.AbstractDocument

AbstractDocument.AbstractElement, AbstractDocument.AttributeContext, AbstractDocument.BranchElement, AbstractDocument.Content, AbstractDocument.DefaultDocumentEvent, AbstractDocument.ElementEdit, AbstractDocument.LeafElement

Field Summary

static String
AdditionalComments
A key for document properies.

Fields inherited from class javax.swing.text.DefaultStyledDocument

BUFFER_SIZE_DEFAULT, buffer

Fields inherited from class javax.swing.text.AbstractDocument

BAD_LOCATION, BidiElementName, ContentElementName, ElementNameAttribute, ParagraphElementName, SectionElementName, listenerList

Fields inherited from interface javax.swing.text.Document

StreamDescriptionProperty, TitleProperty

Constructor Summary

HTMLDocument()
Constructs an HTML document using the default buffer size and a default StyleSheet.
HTMLDocument(AbstractDocument.Content c, StyleSheet styles)
Constructs an HTML document with the given content storage implementation and the given style/attribute storage mechanism.
HTMLDocument(StyleSheet styles)
Constructs an HTML document with the default content storage implementation and the specified style/attribute storage mechanism.

Method Summary

protected void
create(DefaultStyledDocument.ElementSpec[] data)
Replaces the contents of the document with the given element specifications.
protected Element
createBranchElement(Element parent, AttributeSet a)
This method returns an HTMLDocument.BlockElement object representing the attribute set a and attached to parent.
protected AbstractDocument.AbstractElement
createDefaultRoot()
This method creates a root element for the new document.
protected Element
createLeafElement(Element parent, AttributeSet a, int p0, int p1)
This method returns an HTMLDocument.RunElement object attached to parent representing a run of text from p0 to p1.
protected void
fireChangedUpdate(DocumentEvent e)
This method flags a change in the document.
protected void
fireUndoableEditUpdate(UndoableEditEvent e)
This method fires an event intended to be caught by Undo listeners.
URL
getBase()
Returns the location against which to resolve relative URLs.
Element
getElement(String attrId)
Returns the element that has the given id Attribute.
Element
getElement(Element e, Object attribute, Object value)
Gets the child element that contains the attribute with the value or null.
HTMLDocument.Iterator
getIterator(HTML.Tag t)
Gets an iterator for the given HTML.Tag.
HTMLEditorKit.Parser
getParser()
Returns the parser used by this HTMLDocument to insert HTML.
boolean
getPreservesUnknownTags()
Returns whether or not the parser preserves unknown HTML tags.
HTMLEditorKit.ParserCallback
getReader(int pos)
Gets the reader for the parser to use when loading the document with HTML.
HTMLEditorKit.ParserCallback
getReader(int pos, int popDepth, int pushDepth, HTML.Tag insertTag)
Gets the reader for the parser to use when loading the document with HTML.
StyleSheet
getStyleSheet()
Gets the style sheet with the document display rules (CSS) that were specified in the HTML document.
int
getTokenThreshold()
Returns the number of tokens that are buffered before the document is rendered.
protected void
insert(int offset, DefaultStyledDocument.ElementSpec[] data)
Inserts new elements in bulk.
void
insertAfterEnd(Element elem, String htmlText)
Inserts the string after the end of the given element.
void
insertAfterStart(Element elem, String htmlText)
Inserts the string at the start of the element.
void
insertBeforeEnd(Element elem, String htmlText)
Inserts the string at the end of the element.
void
insertBeforeStart(Element elem, String htmlText)
Inserts the string before the start of the given element.
protected void
insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr)
Updates document structure as a result of text insertion.
void
processHTMLFrameHyperlinkEvent(HTMLFrameHyperlinkEvent event)
void
setBase(URL u)
Sets the location against which to resolve relative URLs.
void
setInnerHTML(Element elem, String htmlText)
Replaces the children of the given element with the contents of the string.
void
setOuterHTML(Element elem, String htmlText)
Replaces the given element in the parent with the string.
void
setParagraphAttributes(int offset, int length, AttributeSet s, boolean replace)
This method sets the attributes associated with the paragraph containing offset.
void
setParser(HTMLEditorKit.Parser p)
Sets the parser used by this HTMLDocument to insert HTML.
void
setPreservesUnknownTags(boolean preservesTags)
Sets the behaviour of the parser when it encounters unknown HTML tags.
void
setTokenThreshold(int n)
Sets the number of tokens to buffer before trying to display the Document.

Methods inherited from class javax.swing.text.DefaultStyledDocument

addStyle, create, createDefaultRoot, getBackground, getCharacterElement, getDefaultRootElement, getFont, getForeground, getLogicalStyle, getParagraphElement, getStyle, getStyleNames, insert, insertUpdate, removeStyle, removeUpdate, setCharacterAttributes, setLogicalStyle, setParagraphAttributes, styleChanged

Methods inherited from class javax.swing.text.AbstractDocument

addDocumentListener, addUndoableEditListener, createBranchElement, createLeafElement, createPosition, dump, fireChangedUpdate, fireInsertUpdate, fireRemoveUpdate, fireUndoableEditUpdate, getAsynchronousLoadPriority, getAttributeContext, getBidiRootElement, getContent, getCurrentWriter, getDefaultRootElement, getDocumentFilter, getDocumentListeners, getDocumentProperties, getEndPosition, getLength, getListeners, getParagraphElement, getProperty, getRootElements, getStartPosition, getText, getText, getUndoableEditListeners, insertString, insertUpdate, postRemoveUpdate, putProperty, readLock, readUnlock, remove, removeDocumentListener, removeUndoableEditListener, removeUpdate, render, replace, setAsynchronousLoadPriority, setDocumentFilter, setDocumentProperties, writeLock, writeUnlock

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

AdditionalComments

public static final String AdditionalComments
A key for document properies. The value for the key is a Vector of Strings of comments not found in the body.
Field Value:
"AdditionalComments"

Constructor Details

HTMLDocument

public HTMLDocument()
Constructs an HTML document using the default buffer size and a default StyleSheet.

HTMLDocument

public HTMLDocument(AbstractDocument.Content c,
                    StyleSheet styles)
Constructs an HTML document with the given content storage implementation and the given style/attribute storage mechanism.
Parameters:
c - - the document's content
styles - - the style sheet

HTMLDocument

public HTMLDocument(StyleSheet styles)
Constructs an HTML document with the default content storage implementation and the specified style/attribute storage mechanism.
Parameters:
styles - - the style sheet

Method Details

create

protected void create(DefaultStyledDocument.ElementSpec[] data)
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.
Overrides:
create in interface DefaultStyledDocument
Parameters:
data - - the date that replaces the content of the document

createBranchElement

protected Element createBranchElement(Element parent,
                                      AttributeSet a)
This method returns an HTMLDocument.BlockElement object representing the attribute set a and attached to parent.
Overrides:
createBranchElement in interface AbstractDocument
Parameters:
parent - - the parent element
a - - the attributes for the element
Returns:
the new element

createDefaultRoot

protected AbstractDocument.AbstractElement createDefaultRoot()
This method creates a root element for the new document.
Overrides:
createDefaultRoot in interface DefaultStyledDocument
Returns:
the new default root

createLeafElement

protected Element createLeafElement(Element parent,
                                    AttributeSet a,
                                    int p0,
                                    int p1)
This method returns an HTMLDocument.RunElement object attached to parent representing a run of text from p0 to p1. The run has attributes described by a.
Overrides:
createLeafElement in interface AbstractDocument
Parameters:
parent - - the parent element
a - - the attributes for the element
p0 - - the beginning of the range >= 0
p1 - - the end of the range >= p0
Returns:
the new element

fireChangedUpdate

protected void fireChangedUpdate(DocumentEvent e)
This method flags a change in the document.
Overrides:
fireChangedUpdate in interface AbstractDocument
Parameters:
e - - the Document event

fireUndoableEditUpdate

protected void fireUndoableEditUpdate(UndoableEditEvent e)
This method fires an event intended to be caught by Undo listeners. It simply calls the super version inherited from DefaultStyledDocument. With this method, an HTML editor could easily provide undo support.
Overrides:
fireUndoableEditUpdate in interface AbstractDocument
Parameters:
e - - the UndoableEditEvent

getBase

public URL getBase()
Returns the location against which to resolve relative URLs. This is the document's URL if the document was loaded from a URL. If a base tag is found, it will be used.
Returns:
the base URL

getElement

public Element getElement(String attrId)
Returns the element that has the given id Attribute. If it is not found, null is returned. This method works on an Attribute, not a character tag. This is not thread-safe.
Parameters:
attrId - - the Attribute id to look for
Returns:
the element that has the given id.

getElement

public Element getElement(Element e,
                          Object attribute,
                          Object value)
Gets the child element that contains the attribute with the value or null. Not thread-safe.
Parameters:
e - - the element to begin search at
attribute - - the desired attribute
value - - the desired value
Returns:
the element found with the attribute and value specified or null if it is not found.

getIterator

public HTMLDocument.Iterator getIterator(HTML.Tag t)
Gets an iterator for the given HTML.Tag.
Parameters:
t - the requested HTML.Tag
Returns:
the Iterator

getParser

public HTMLEditorKit.Parser getParser()
Returns the parser used by this HTMLDocument to insert HTML.
Returns:
the parser used by this HTMLDocument to insert HTML.

getPreservesUnknownTags

public boolean getPreservesUnknownTags()
Returns whether or not the parser preserves unknown HTML tags.
Returns:
true if the parser preserves unknown tags

getReader

public HTMLEditorKit.ParserCallback getReader(int pos)
Gets the reader for the parser to use when loading the document with HTML.
Parameters:
pos - - the starting position
Returns:
- the reader

getReader

public HTMLEditorKit.ParserCallback getReader(int pos,
                                              int popDepth,
                                              int pushDepth,
                                              HTML.Tag insertTag)
Gets the reader for the parser to use when loading the document with HTML.
Parameters:
pos - - the starting position
popDepth - - the number of EndTagTypes to generate before inserting
pushDepth - - the number of StartTagTypes with a direction of JoinNextDirection that should be generated before inserting, but after the end tags have been generated.
insertTag - - the first tag to start inserting into document
Returns:
- the reader

getStyleSheet

public StyleSheet getStyleSheet()
Gets the style sheet with the document display rules (CSS) that were specified in the HTML document.
Returns:
- the style sheet

getTokenThreshold

public int getTokenThreshold()
Returns the number of tokens that are buffered before the document is rendered.
Returns:
the number of tokens buffered

insert

protected void insert(int offset,
                      DefaultStyledDocument.ElementSpec[] data)
            throws BadLocationException
Inserts new elements in bulk. This is how elements get created in the document. The parsing determines what structure is needed and creates the specification as a set of tokens that describe the edit while leaving the document free of a write-lock. This method can then be called in bursts by the reader to acquire a write-lock for a shorter duration (i.e. while the document is actually being altered).
Overrides:
insert in interface DefaultStyledDocument
Parameters:
offset - - the starting offset
data - - the element data
Throws:
BadLocationException - - if the given position does not represent a valid location in the associated document.

insertAfterEnd

public void insertAfterEnd(Element elem,
                           String htmlText)
            throws BadLocationException,
                   IOException
Inserts the string after the end of the given element. The parser must be set.
Parameters:
elem - - the element to be the root for the new text
htmlText - - the text to insert
Throws:
BadLocationException -
IOException -
IllegalStateException - - if parser is not set

insertAfterStart

public void insertAfterStart(Element elem,
                             String htmlText)
            throws BadLocationException,
                   IOException
Inserts the string at the start of the element. The parser must be set.
Parameters:
elem - - the element to be the root for the new text
htmlText - - the text to insert
Throws:
BadLocationException -
IOException -
IllegalStateException - - if parser is not set

insertBeforeEnd

public void insertBeforeEnd(Element elem,
                            String htmlText)
            throws BadLocationException,
                   IOException
Inserts the string at the end of the element. If elem's children are leaves, and the character at elem.getEndOffset() - 1 is a newline, then it will be inserted before the newline. The parser must be set.
Parameters:
elem - - the element to be the root for the new text
htmlText - - the text to insert
Throws:
BadLocationException -
IOException -
IllegalStateException - - if parser is not set

insertBeforeStart

public void insertBeforeStart(Element elem,
                              String htmlText)
            throws BadLocationException,
                   IOException
Inserts the string before the start of the given element. The parser must be set.
Parameters:
elem - - the element to be the root for the new text.
htmlText - - the string to be parsed and assigned to elem
Throws:
BadLocationException -
IOException -
IllegalStateException - - if parser has not been set

insertUpdate

protected void insertUpdate(AbstractDocument.DefaultDocumentEvent chng,
                            AttributeSet attr)
Updates document structure as a result of text insertion. This will happen within a write lock. This implementation simply parses the inserted content for line breaks and builds up a set of instructions for the element buffer.
Overrides:
insertUpdate in interface DefaultStyledDocument
Parameters:
chng - - a description of the document change
attr - - the attributes

processHTMLFrameHyperlinkEvent

public void processHTMLFrameHyperlinkEvent(HTMLFrameHyperlinkEvent event)

setBase

public void setBase(URL u)
Sets the location against which to resolve relative URLs.
Parameters:
u - the new base URL

setInnerHTML

public void setInnerHTML(Element elem,
                         String htmlText)
            throws BadLocationException,
                   IOException
Replaces the children of the given element with the contents of the string. The document must have an HTMLEditorKit.Parser set. This will be seen as at least two events, n inserts followed by a remove.
Parameters:
elem - - the brance element whose children will be replaced
htmlText - - the string to be parsed and assigned to element.
Throws:
BadLocationException -
IOException -
IllegalArgumentException - - if elem is a leaf
IllegalStateException - - if an HTMLEditorKit.Parser has not been set

setOuterHTML

public void setOuterHTML(Element elem,
                         String htmlText)
            throws BadLocationException,
                   IOException
Replaces the given element in the parent with the string. 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. This will be seen as at least two events, n inserts followed by a remove. The HTMLEditorKit.Parser must be set.
Parameters:
elem - - the branch element whose parent will be replaced
htmlText - - the string to be parsed and assigned to elem
Throws:
BadLocationException -
IOException -
IllegalStateException - - if parser is not set

setParagraphAttributes

public void setParagraphAttributes(int offset,
                                   int length,
                                   AttributeSet s,
                                   boolean replace)
This method sets the attributes associated with the paragraph containing offset. If replace is false, s is merged with existing attributes. The length argument determines how many characters are affected by the new attributes. This is often the entire paragraph.
Specified by:
setParagraphAttributes in interface StyledDocument
Overrides:
setParagraphAttributes in interface DefaultStyledDocument
Parameters:
offset - - the offset into the paragraph (must be at least 0)
length - - the number of characters affected (must be at least 0)
s - - the attributes
replace - - whether to replace existing attributes, or merge them

setParser

public void setParser(HTMLEditorKit.Parser p)
Sets the parser used by this HTMLDocument to insert HTML.
Parameters:
p - the parser to use

setPreservesUnknownTags

public void setPreservesUnknownTags(boolean preservesTags)
Sets the behaviour of the parser when it encounters unknown HTML tags.
Parameters:
preservesTags - true if the parser should preserve unknown tags.

setTokenThreshold

public void setTokenThreshold(int n)
Sets the number of tokens to buffer before trying to display the Document.
Parameters:
n - the number of tokens to buffer

HTMLDocument.java -- Copyright (C) 2005 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.