An implementation of the document interface to serve as a
basis for implementing various kinds of documents.  At this
level there is very little policy, so there is a corresponding
increase in difficulty of use.

This class implements a locking mechanism for the document.  It
allows multiple readers or one writer, and writers must wait until
all observers of the document have been notified of a previous
change before beginning another mutation to the document.  The
read lock is acquired and released using the render
method.  A write lock is acquired by the methods that mutate the
document, and are held for the duration of the method call.
Notification is done on the thread that produced the mutation,
and the thread has full read access to the document for the
duration of the notification, but other readers are kept out
until the notification has finished.  The notification is a
beans event notification which does not allow any further
mutations until all listeners have been notified.

Any models subclassed from this class and used in conjunction
with a text component that has a look and feel implementation
that is derived from BasicTextUI may be safely updated
asynchronously, because all access to the View hierarchy
is serialized by BasicTextUI if the document is of type
AbstractDocument.  The locking assumes that an
independent thread will access the View hierarchy only from
the DocumentListener methods, and that there will be only
one event thread active at a time.

If concurrency support is desired, there are the following
additional implications.  The code path for any DocumentListener
implementation and any UndoListener implementation must be threadsafe,
and not access the component lock if trying to be safe from deadlocks.
The repaint and revalidate methods
on JComponent are safe.

AbstractDocument models an implied break at the end of the document.
Among other things this allows you to position the caret after the last
character. As a result of this, getLength returns one less
than the length of the Content. If you create your own Content, be
sure and initialize it to have an additional character. Refer to
StringContent and GapContent for examples of this. Another implication
of this is that Elements that model the implied end character will have
an endOffset == (getLength()  1). For example, in DefaultStyledDocument
getParagraphElement(getLength()).getEndOffset() == getLength()  1
.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

An interface that can be used to allow MutableAttributeSet
implementations to use pluggable attribute compression
techniques.  Each mutation of the attribute set can be
used to exchange a previous AttributeSet instance with
another, preserving the possibility of the AttributeSet
remaining immutable.  An implementation is provided by
the StyleContext class.

The Element implementations provided by this class use
this interface to provide their MutableAttributeSet
implementations, so that different AttributeSet compression
techniques can be employed.  The method
getAttributeContext should be implemented to
return the object responsible for implementing the desired
compression technique.

Interface to describe a sequence of character content that
can be edited.  Implementations may or may not support a
history mechanism which will be reflected by whether or not
mutations return an UndoableEdit implementation.

An implementation of ElementChange that can be added to the document
event.

AbstractWriter is an abstract class that actually
does the work of writing out the element tree
including the attributes.  In terms of how much is
written out per line, the writer defaults to 100.
But this value can be set by subclasses.

A box that does layout asynchronously.  This
is useful to keep the GUI event thread moving by
not doing any layout on it.  The layout is done
on a granularity of operations on the child views.
After each child view is accessed for some part
of layout (a potentially time consuming operation)
the remaining tasks can be abandoned or a new higher
priority task (i.e. to service a synchronous request
or a visible area) can be taken on.

While the child view is being accessed
a read lock is acquired on the associated document
so that the model is stable while being accessed.

A collection of unique attributes.  This is a read-only,
immutable interface.  An attribute is basically a key and
a value assigned to the key.  The collection may represent
something like a style run, a logical style, etc.  These
are generally used to describe features that will contribute
to some graphical representation such as a font.  The
set of possible keys is unbounded and can be anything.
Typically View implementations will respond to attribute
definitions and render something to represent the attributes.

Attributes can potentially resolve in a hierarchy.  If a
key doesn't resolve locally, and a resolving parent
exists, the key will be resolved through the parent.

This interface is the type signature that is expected
to be present on any attribute key that contributes to
character level presentation.  This would be any attribute
that applies to a so-called run of
style.

This interface is the type signature that is expected
to be present on any attribute key that contributes to
presentation of color.

This interface is the type signature that is expected
to be present on any attribute key that contributes to
the determination of what font to use to render some
text.  This is not considered to be a closed set, the
definition can change across version of the platform and can
be amended by additional user added entries that
correspond to logical settings that are specific to
some type of content.

This interface is the type signature that is expected
to be present on any attribute key that contributes to
the paragraph level presentation.

This exception is to report bad locations within a document model
(that is, attempts to reference a location that doesn't exist).

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

A view that arranges its children into a box shape by tiling
its children along an axis.  The box is somewhat like that
found in TeX where there is alignment of the
children, flexibility of the children is considered, etc.
This is a building block that might be useful to represent
things like a collection of lines, paragraphs,
lists, columns, pages, etc.  The axis along which the children are tiled is
considered the major axis.  The orthogonal axis is the minor axis.

Layout for each axis is handled separately by the methods
layoutMajorAxis and layoutMinorAxis.
Subclasses can change the layout algorithm by
reimplementing these methods.    These methods will be called
as necessary depending upon whether or not there is cached
layout information and the cache is considered
valid.  These methods are typically called if the given size
along the axis changes, or if layoutChanged is
called to force an updated layout.  The layoutChanged
method invalidates cached layout information, if there is any.
The requirements published to the parent view are calculated by
the methods calculateMajorAxisRequirements
and  calculateMinorAxisRequirements.
If the layout algorithm is changed, these methods will
likely need to be reimplemented.

A place within a document view that represents where
things can be inserted into the document model.  A caret
has a position in the document referred to as a dot.
The dot is where the caret is currently located in the
model.  There is
a second position maintained by the caret that represents
the other end of a selection called mark.  If there is
no selection the dot and mark will be equal.  If a selection
exists, the two values will be different.

The dot can be placed by either calling
setDot or moveDot.  Setting
the dot has the effect of removing any selection that may
have previously existed.  The dot and mark will be equal.
Moving the dot has the effect of creating a selection as
the mark is left at whatever position it previously had.

ChangedCharSetException as the name indicates is an exception
thrown when the charset is changed.

Component decorator that implements the view interface.  The
entire element is used to represent the component.  This acts
as a gateway from the display-only View implementations to
interactive lightweight components (ie it allows components
to be embedded into the View hierarchy).

The component is placed relative to the text baseline
according to the value returned by
Component.getAlignmentY.  For Swing components
this value can be conveniently set using the method
JComponent.setAlignmentY.  For example, setting
a value of 0.75 will cause 75 percent of the
component to be above the baseline, and 25 percent of the
component to be below the baseline.

This class is implemented to do the extra work necessary to
work properly in the presence of multiple threads (i.e. from
asynchronous notification of model changes for example) by
ensuring that all component access is done on the event thread.

The component used is determined by the return value of the
createComponent method.  The default implementation of this
method is to return the component held as an attribute of
the element (by calling StyleConstants.getComponent).  A
limitation of this behavior is that the component cannot
be used by more than one text component (i.e. with a shared
model).  Subclasses can remove this constraint by implementing
the createComponent to actually create a component based upon
some kind of specification contained in the attributes.  The
ObjectView class in the html package is an example of a
ComponentView implementation that supports multiple component
views of a shared model.

CompositeView is an abstract View
implementation which manages one or more child views.
(Note that CompositeView is intended
for managing relatively small numbers of child views.)
CompositeView is intended to be used as
a starting point for View implementations,
such as BoxView, that will contain child
Views. Subclasses that wish to manage the
collection of child Views should use the
replace(int, int, javax.swing.text.View[]) method.  As View invokes
replace during DocumentListener
notification, you normally won't need to directly
invoke replace.

While CompositeView
does not impose a layout policy on its child Views,
it does allow for inseting the child Views
it will contain.  The insets can be set by either
setInsets(short, short, short, short) or setParagraphInsets(javax.swing.text.AttributeSet).

In addition to the abstract methods of
View,
subclasses of CompositeView will need to
override:

isBefore(int, int, java.awt.Rectangle) - Used to test if a given
    View location is before the visual space
    of the CompositeView.
isAfter(int, int, java.awt.Rectangle) - Used to test if a given
    View location is after the visual space
    of the CompositeView.
getViewAtPoint(int, int, java.awt.Rectangle) - Returns the view at
    a given visual location.
childAllocation(int, java.awt.Rectangle) - Returns the bounds of
    a particular child View.
    getChildAllocation will invoke
    childAllocation after offseting
    the bounds by the Insets of the
    CompositeView.

DateFormatter is an InternationalFormatter that does its
formatting by way of an instance of java.text.DateFormat.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

A default implementation of Caret.  The caret is rendered as
a vertical line in the color specified by the CaretColor property
of the associated JTextComponent.  It can blink at the rate specified
by the BlinkRate property.

This implementation expects two sources of asynchronous notification.
The timer thread fires asynchronously, and causes the caret to simply
repaint the most recent bounding box.  The caret also tracks change
as the document is modified.  Typically this will happen on the
event dispatch thread as a result of some mouse or keyboard event.
The caret behavior on both synchronous and asynchronous documents updates
is controlled by UpdatePolicy property. The repaint of the
new caret location will occur on the event thread in any case, as calls to
modelToView are only safe on the event thread.

The caret acts as a mouse and focus listener on the text component
it has been installed in, and defines the caret semantics based upon
those events.  The listener methods can be reimplemented to change the
semantics.
By default, the first mouse button will be used to set focus and caret
position.  Dragging the mouse pointer with the first mouse button will
sweep out a selection that is contiguous in the model.  If the associated
text component is editable, the caret will become visible when focus
is gained, and invisible when focus is lost.

The Highlighter bound to the associated text component is used to
render the selection by default.
Selection appearance can be customized by supplying a
painter to use for the highlights.  By default a painter is used that
will render a solid color as specified in the associated text component
in the SelectionColor property.  This can easily be changed
by reimplementing the
getSelectionPainter
method.

A customized caret appearance can be achieved by reimplementing
the paint method.  If the paint method is changed, the damage method
should also be reimplemented to cause a repaint for the area needed
to render the caret.  The caret extends the Rectangle class which
is used to hold the bounding box for where the caret was last rendered.
This enables the caret to repaint in a thread-safe manner when the
caret moves without making a call to modelToView which is unstable
between model updates and view repair (i.e. the order of delivery
to DocumentListeners is not guaranteed).

The magic caret position is set to null when the caret position changes.
A timer is used to determine the new location (after the caret change).
When the timer fires, if the magic caret position is still null it is
reset to the current caret position. Any actions that change
the caret position and want the magic caret position to remain the
same, must remember the magic caret position, change the cursor, and
then set the magic caret position to its original value. This has the
benefit that only actions that want the magic caret position to persist
(such as open/down) need to know about it.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

This is the set of things needed by a text component
to be a reasonably functioning editor for some type
of text document.  This implementation provides a default
implementation which treats text as plain text and
provides a minimal set of actions for a simple editor.


Newlines

There are two properties which deal with newlines.  The
system property, line.separator, is defined to be
platform-dependent, either "\n", "\r", or "\r\n".  There is also
a property defined in DefaultEditorKit, called
EndOfLineStringProperty,
which is defined automatically when a document is loaded, to be
the first occurrence of any of the newline characters.
When a document is loaded, EndOfLineStringProperty
is set appropriately, and when the document is written back out, the
EndOfLineStringProperty is used.  But while the document
is in memory, the "\n" character is used to define a
newline, regardless of how the newline is defined when
the document is on disk.  Therefore, for searching purposes,
"\n" should always be used.  When a new document is created,
and the EndOfLineStringProperty has not been defined,
it will use the System property when writing out the
document.
Note that EndOfLineStringProperty is set
on the Document using the get/putProperty
methods.  Subclasses may override this behavior.

Creates a beep.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

Copies the selected region and place its contents
into the system clipboard.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

Cuts the selected region and place its contents
into the system clipboard.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

The action that is executed by default if
a key typed event is received and there
is no keymap entry.  There is a variation across
different VM's in what gets sent as a key typed
event, and this action tries to filter out the undesired
events.  This filters the control characters and those
with the ALT modifier.  It allows Control-Alt sequences
through as these form legitimate unicode characters on
some PC keyboards.

If the event doesn't get filtered, it will try to insert
content into the text editor.  The content is fetched
from the command string of the ActionEvent.  The text
entry is done through the replaceSelection
method on the target text component.  This is the
action that will be fired for most text entry tasks.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

Places a line/paragraph break into the document.
If there is a selection, it is removed before
the break is added.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

Places content into the associated document.
If there is a selection, it is removed before
the new content is added.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

Places a tab character into the document. If there
is a selection, it is removed before the tab is added.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

Pastes the contents of the system clipboard into the
selected region, or before the caret if nothing is
selected.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

DefaultFormatter formats arbitrary objects. Formatting is done
by invoking the toString method. In order to convert the
value back to a String, your class must provide a constructor that
takes a String argument. If no single argument constructor that takes a
String is found, the returned value will be the String passed into
stringToValue.

Instances of DefaultFormatter can not be used in multiple
instances of JFormattedTextField. To obtain a copy of
an already configured DefaultFormatter, use the
clone method.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

An implementation of
JFormattedTextField.AbstractFormatterFactory.
DefaultFormatterFactory allows specifying a number of
different JFormattedTextField.AbstractFormatters that are to
be used.
The most important one is the default one
(setDefaultFormatter). The default formatter will be used
if a more specific formatter could not be found. The following process
is used to determine the appropriate formatter to use.

  Is the passed in value null? Use the null formatter.
  Does the JFormattedTextField have focus? Use the edit
      formatter.
  Otherwise, use the display formatter.
  If a non-null AbstractFormatter has not been found, use
      the default formatter.


The following code shows how to configure a
JFormattedTextField with two
JFormattedTextField.AbstractFormatters, one for display and
one for editing.


JFormattedTextField.AbstractFormatter editFormatter = ...;
JFormattedTextField.AbstractFormatter displayFormatter = ...;
DefaultFormatterFactory factory = new DefaultFormatterFactory(
                displayFormatter, displayFormatter, editFormatter);
JFormattedTextField tf = new JFormattedTextField(factory);

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

Implements the Highlighter interfaces.  Implements a simple highlight
painter that renders in a solid color.

Simple highlight painter that fills a highlighted area with
a solid color.

A document that can be marked up with character and paragraph
styles in a manner similar to the Rich Text Format.  The element
structure for this document represents style crossings for
style runs.  These style runs are mapped into a paragraph element
structure (which may reside in some other structure).  The
style runs break at paragraph boundaries since logical styles are
assigned to paragraph boundaries.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

An UndoableEdit used to remember AttributeSet changes to an
Element.

Specification for building elements.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

Deprecated.

 The Document is a container for text that serves
as the model for swing text components.  The goal for this
interface is to scale from very simple needs (a plain text textfield)
to complex needs (an HTML or XML document, for example).

Content

At the simplest level, text can be
modeled as a linear sequence of characters. To support
internationalization, the Swing text model uses
unicode characters.
The sequence of characters displayed in a text component is
generally referred to as the component's content.

To refer to locations within the sequence, the coordinates
used are the location between two characters.  As the diagram
below shows, a location in a text document can be referred to
as a position, or an offset. This position is zero-based.


In the example, if the content of a document is the
sequence "The quick brown fox," as shown in the preceding diagram,
the location just before the word "The" is 0, and the location after
the word "The" and before the whitespace that follows it is 3.
The entire sequence of characters in the sequence "The" is called a
range.
The following methods give access to the character data
that makes up the content.

getLength()
getText(int, int)
getText(int, int, javax.swing.text.Segment)

Structure

Text is rarely represented simply as featureless content. Rather,
text typically has some sort of structure associated with it.
Exactly what structure is modeled is up to a particular Document
implementation.  It might be as simple as no structure (i.e. a
simple text field), or it might be something like diagram below.


The unit of structure (i.e. a node of the tree) is referred to
by the Element interface.  Each Element
can be tagged with a set of attributes.  These attributes
(name/value pairs) are defined by the
AttributeSet interface.
The following methods give access to the document structure.

getDefaultRootElement()
getRootElements()


Mutations

All documents need to be able to add and remove simple text.
Typically, text is inserted and removed via gestures from
a keyboard or a mouse.  What effect the insertion or removal
has upon the document structure is entirely up to the
implementation of the document.
The following methods are related to mutation of the
document content:

insertString(int, java.lang.String, javax.swing.text.AttributeSet)
remove(int, int)
createPosition(int)


Notification

Mutations to the Document must be communicated to
interested observers.  The notification of change follows the event model
guidelines that are specified for JavaBeans.  In the JavaBeans
event model, once an event notification is dispatched, all listeners
must be notified before any further mutations occur to the source
of the event.  Further, order of delivery is not guaranteed.

Notification is provided as two separate events,
DocumentEvent, and
UndoableEditEvent.
If a mutation is made to a Document through its api,
a DocumentEvent will be sent to all of the registered
DocumentListeners.  If the Document
implementation supports undo/redo capabilities, an
UndoableEditEvent will be sent
to all of the registered UndoableEditListeners.
If an undoable edit is undone, a DocumentEvent should be
fired from the Document to indicate it has changed again.
In this case however, there should be no UndoableEditEvent
generated since that edit is actually the source of the change
rather than a mutation to the Document made through its
api.


Referring to the above diagram, suppose that the component shown
on the left mutates the document object represented by the blue
rectangle. The document responds by dispatching a DocumentEvent to
both component views and sends an UndoableEditEvent to the listening
logic, which maintains a history buffer.

Now suppose that the component shown on the right mutates the same
document.  Again, the document dispatches a DocumentEvent to both
component views and sends an UndoableEditEvent to the listening logic
that is maintaining the history buffer.

If the history buffer is then rolled back (i.e. the last UndoableEdit
undone), a DocumentEvent is sent to both views, causing both of them to
reflect the undone mutation to the document (that is, the
removal of the right component's mutation). If the history buffer again
rolls back another change, another DocumentEvent is sent to both views,
causing them to reflect the undone mutation to the document -- that is,
the removal of the left component's mutation.

The methods related to observing mutations to the document are:

addDocumentListener(DocumentListener)
removeDocumentListener(DocumentListener)
addUndoableEditListener(UndoableEditListener)
removeUndoableEditListener(UndoableEditListener)


Properties

Document implementations will generally have some set of properties
associated with them at runtime.  Two well known properties are the
StreamDescriptionProperty,
which can be used to describe where the Document came from,
and the TitleProperty, which can be used to
name the Document.  The methods related to the properties are:

getProperty(java.lang.Object)
putProperty(java.lang.Object, java.lang.Object)


For more information on the Document class, see
The Swing Connection
and most particularly the article,

The Element Interface.

DocumentFilter, as the name implies, is a filter for the
Document mutation methods. When a Document
containing a DocumentFilter is modified (either through
insert or remove), it forwards the appropriate
method invocation to the DocumentFilter. The
default implementation allows the modification to
occur. Subclasses can filter the modifications by conditionally invoking
methods on the superclass, or invoking the necessary methods on
the passed in FilterBypass. Subclasses should NOT call back
into the Document for the modification
instead call into the superclass or the FilterBypass.

When remove or insertString is invoked
on the DocumentFilter, the DocumentFilter
may callback into the
FilterBypass multiple times, or for different regions, but
it should not callback into the FilterBypass after returning
from the remove or insertString method.

By default, text related document mutation methods such as
insertString, replace and remove
in AbstractDocument use DocumentFilter when
available, and Element related mutation methods such as
create, insert and removeElement in
DefaultStyledDocument do not use DocumentFilter.
If a method doesn't follow these defaults, this must be explicitly stated
in the method documentation.

Used as a way to circumvent calling back into the Document to
change it. Document implementations that wish to support
a DocumentFilter must provide an implementation that will
not callback into the DocumentFilter when the following methods
are invoked from the DocumentFilter.

Establishes the set of things needed by a text component
to be a reasonably functioning editor for some type
of text content.  The EditorKit acts as a factory for some
kind of policy.  For example, an implementation
of html and rtf can be provided that is replaceable
with other implementations.

A kit can safely store editing state as an instance
of the kit will be dedicated to a text component.
New kits will normally be created by cloning a
prototype kit.  The kit will have it's
setComponent method called to establish
it's relationship with a JTextComponent.

Interface to describe a structural piece of a document.  It
is intended to capture the spirit of an SGML element.

 ElementIterator, as the name suggests, iterates over the Element
tree.  The constructor can be invoked with either Document or an Element
as an argument.  If the constructor is invoked with a Document as an
argument then the root of the iteration is the return value of
document.getDefaultRootElement().

The iteration happens in a depth-first manner.  In terms of how
boundary conditions are handled:
a) if next() is called before first() or current(), the
   root will be returned.
b) next() returns null to indicate the end of the list.
c) previous() returns null when the current element is the root
   or next() has returned null.

The ElementIterator does no locking of the Element tree. This means
that it does not track any changes.  It is the responsibility of the
user of this class, to ensure that no changes happen during element
iteration.

Simple usage example:

   public void iterate() {
       ElementIterator it = new ElementIterator(root);
       Element elem;
       while (true) {
          if ((elem = next()) != null) {
              // process element
              System.out.println("elem: "  elem.getName());
          } else {
              break;
          }
       }
   }

Extends the multi-line plain text view to be suitable
for a single-line editor view.  If the view is
allocated extra space, the field must adjust for it.
If the hosting component is a JTextField, this view
will manage the ranges of the associated BoundedRangeModel
and will adjust the horizontal allocation to match the
current visibility settings of the JTextField.

A View that tries to flow it's children into some
partially constrained space.  This can be used to
build things like paragraphs, pages, etc.  The
flow is made up of the following pieces of functionality.

A logical set of child views, which as used as a
layout pool from which a physical view is formed.
A strategy for translating the logical view to
a physical (flowed) view.
Constraints for the strategy to work against.
A physical structure, that represents the flow.
The children of this view are where the pieces of
of the logical views are placed to create the flow.

Strategy for maintaining the physical form
of the flow.  The default implementation is
completely stateless, and recalculates the
entire flow if the layout is invalid on the
given FlowView.  Alternative strategies can
be implemented by subclassing, and might
perform incremental repair to the layout
or alternative breaking behavior.

An implementation of the AbstractDocument.Content interface
implemented using a gapped buffer similar to that used by emacs.
The underlying storage is a array of unicode characters with
a gap somewhere.  The gap is moved to the location of changes
to take advantage of common behavior where most changes are
in the same location.  Changes that occur at a gap boundary are
generally cheap and moving the gap is generally cheaper than
moving the array contents directly to accommodate the change.

The positions tracking change are also generally cheap to
maintain.  The Position implementations (marks) store the array
index and can easily calculate the sequential position from
the current gap location.  Changes only require update to the
the marks between the old and new gap boundaries when the gap
is moved, so generally updating the marks is pretty cheap.
The marks are stored sorted so they can be located quickly
with a binary search.  This increases the cost of adding a
mark, and decreases the cost of keeping the mark updated.

A GlyphView is a styled chunk of text that represents a view
mapped over an element in the text model. This view is generally
responsible for displaying text glyphs using character level
attributes in some way.
An implementation of the GlyphPainter class is used to do the
actual rendering and model/view translations.  This separates
rendering from layout and management of the association with
the model.

The view supports breaking for the purpose of formatting.
The fragments produced by breaking share the view that has
primary responsibility for the element (i.e. they are nested
classes and carry only a small amount of state of their own)
so they can share its resources.

Since this view
represents text that may have tabs embedded in it, it implements the
TabableView interface.  Tabs will only be
expanded if this view is embedded in a container that does
tab expansion.  ParagraphView is an example of a container
that does tab expansion.

A class to perform rendering of the glyphs.
This can be implemented to be stateless, or
to hold some information as a cache to
facilitate faster rendering and model/view
translation.  At a minimum, the GlyphPainter
allows a View implementation to perform its
duties independant of a particular version
of JVM and selection of capabilities (i.e.
shaping for i18n, etc).

An interface for an object that allows one to mark up the background
with colored areas.

Highlight renderer.

A view implementation to display a block (as a box)
with CSS specifications.

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 supported by the
rendering engine:
font-family
  font-style
  font-size (supports relative units)
  font-weight
  font
  color
  background-color (with the exception of transparent)
  background-image
  background-repeat
  background-position
  background
  text-decoration (with the exception of blink and overline)
  vertical-align (only sup and super)
  text-align (justify is treated as center)
  margin-top
  margin-right
  margin-bottom
  margin-left
  margin
  padding-top
  padding-right
  padding-bottom
  padding-left
  padding
  border-top-style
  border-right-style
  border-bottom-style
  border-left-style
  border-style (only supports inset, outset and none)
  border-top-color
  border-right-color
  border-bottom-color
  border-left-color
  border-color
  list-style-image
  list-style-type
  list-style-position

The following are modeled, but currently not rendered.
font-variant
  background-attachment (background always treated as scroll)
  word-spacing
  letter-spacing
  text-indent
  text-transform
  line-height
  border-top-width (this is used to indicate if a border should be used)
  border-right-width
  border-bottom-width
  border-left-width
  border-width
  border-top
  border-right
  border-bottom
  border-left
  border
  width
  height
  float
  clear
  display
  white-space
  list-style

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.

Definitions to be used as a key on AttributeSet's
that might hold CSS attributes.  Since this is a
closed set (i.e. defined exactly by the specification),
it is final and cannot be extended.

FormSubmitEvent is used to notify interested
parties that a form was submitted.

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

Constants used in the HTMLDocument.  These
are basically tag and attribute definitions.

Typesafe enumeration representing an HTML
attribute.

Typesafe enumeration for an HTML tag.  Although the
set of HTML tags is a closed set, we have left the
set open so that people can add their own tag types
to their custom parser and still communicate to the
reader.

Example
insertAfterStart
insertBeforeEnd
insertBeforeStart
insertAfterEnd
setInnerHTML
setOuterHTML




    Paragraph 1
    Paragraph 2

      List Item

    Paragraph 1
    Paragraph 2

    Paragraph 1
    Paragraph 2

      List Item

    List Item


    Paragraph 1
    Paragraph 2

    Paragraph 1
    Paragraph 2


    List Item

      List Item

    List Item

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.

Modifying HTMLDocument

In addition to the methods provided by Document and
StyledDocument for mutating an HTMLDocument, HTMLDocument provides
a number of convenience methods.  The following methods can be used
to insert HTML content into an existing document.


  setInnerHTML(Element, String)
  setOuterHTML(Element, String)
  insertBeforeStart(Element, String)
  insertAfterStart(Element, String)
  insertBeforeEnd(Element, String)
  insertAfterEnd(Element, String)


The following examples illustrate using these methods.  Each
example assumes the HTML document is initialized in the following
way:



JEditorPane p = new JEditorPane();
p.setContentType("text/html");
p.setText("..."); // Document text is provided below.
HTMLDocument d = (HTMLDocument) p.getDocument();

With the following HTML content:



<html>
  <head>
    <title>An example HTMLDocument</title>
    <style type="text/css">
      div { background-color: silver; }
      ul { color: red; }
    </style>
  </head>
  <body>
    <div id="BOX">
      <p>Paragraph 1</p>
      <p>Paragraph 2</p>
    </div>
  </body>
</html>

All the methods for modifying an HTML document require an Element.  Elements can be obtained from an HTML document by using
the method getElement(Element e, Object attribute, Object
value).  It returns the first descendant element that contains the
specified attribute with the given value, in depth-first order.
For example, d.getElement(d.getDefaultRootElement(),
StyleConstants.NameAttribute, HTML.Tag.P) returns the first
paragraph element.

A convenient shortcut for locating elements is the method getElement(String); returns an element whose ID
attribute matches the specified value.  For example,
d.getElement("BOX") returns the DIV
element.

The getIterator(HTML.Tag t) method can also be used for
finding all occurrences of the specified HTML tag in the
document.

Inserting elements

Elements can be inserted before or after the existing children
of any non-leaf element by using the methods
insertAfterStart and insertBeforeEnd.
For example, if e is the DIV element,
d.insertAfterStart(e, "<ul><li>List
Item</li></ul>") inserts the list before the first
paragraph, and d.insertBeforeEnd(e, "<ul><li>List
Item</li></ul>") inserts the list after the last
paragraph.  The DIV block becomes the parent of the
newly inserted elements.

Sibling elements can be inserted before or after any element by
using the methods insertBeforeStart and
insertAfterEnd.  For example, if e is the
DIV element, d.insertBeforeStart(e,
"<ul><li>List Item</li></ul>") inserts the list
before the DIV element, and d.insertAfterEnd(e,
"<ul><li>List Item</li></ul>") inserts the list
after the DIV element.  The newly inserted elements
become siblings of the DIV element.

Replacing elements

Elements and all their descendants can be replaced by using the
methods setInnerHTML and setOuterHTML.
For example, if e is the DIV element,
d.setInnerHTML(e, "<ul><li>List
Item</li></ul>") replaces all children paragraphs with
the list, and d.setOuterHTML(e, "<ul><li>List
Item</li></ul>") replaces the DIV element
itself.  In latter case the parent of the list is the
BODY element.

Summary

The following table shows the example document and the results
of various methods described above.



    Example
    insertAfterStart
    insertBeforeEnd
    insertBeforeStart
    insertAfterEnd
    setInnerHTML
    setOuterHTML




        Paragraph 1
        Paragraph 2


insertAfterStart



          List Item

        Paragraph 1
        Paragraph 2


insertBeforeEnd


        Paragraph 1
        Paragraph 2

          List Item



insertBeforeStart


        List Item


        Paragraph 1
        Paragraph 2


insertAfterEnd


        Paragraph 1
        Paragraph 2


        List Item


setInnerHTML



          List Item



setOuterHTML


        List Item





Warning: Serialized objects of this class will
not be compatible with future Swing releases. The current
serialization support is appropriate for short term storage or RMI
between applications running the same version of Swing.  As of 1.4,
support for long term storage of all JavaBeans™
has been added to the
java.beans package.  Please see XMLEncoder.

An iterator to iterate over a particular type of
tag.  The iterator is not thread safe.  If reliable
access to the document is not already ensured by
the context under which the iterator is being used,
its use should be performed under the protection of
Document.render.

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 documentation 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.


  The parser is replaceable.  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.

  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.

  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.

  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.

A factory to build views for HTML.  The following
table describes what this factory will build by
default.



TagView created

HTML.Tag.CONTENTInlineView

HTML.Tag.IMPLIEDjavax.swing.text.html.ParagraphView

HTML.Tag.Pjavax.swing.text.html.ParagraphView

HTML.Tag.H1javax.swing.text.html.ParagraphView

HTML.Tag.H2javax.swing.text.html.ParagraphView

HTML.Tag.H3javax.swing.text.html.ParagraphView

HTML.Tag.H4javax.swing.text.html.ParagraphView

HTML.Tag.H5javax.swing.text.html.ParagraphView

HTML.Tag.H6javax.swing.text.html.ParagraphView

HTML.Tag.DTjavax.swing.text.html.ParagraphView

HTML.Tag.MENUListView

HTML.Tag.DIRListView

HTML.Tag.ULListView

HTML.Tag.OLListView

HTML.Tag.LIBlockView

HTML.Tag.DLBlockView

HTML.Tag.DDBlockView

HTML.Tag.BODYBlockView

HTML.Tag.HTMLBlockView

HTML.Tag.CENTERBlockView

HTML.Tag.DIVBlockView

HTML.Tag.BLOCKQUOTEBlockView

HTML.Tag.PREBlockView

HTML.Tag.BLOCKQUOTEBlockView

HTML.Tag.PREBlockView

HTML.Tag.IMGImageView

HTML.Tag.HRHRuleView

HTML.Tag.BRBRView

HTML.Tag.TABLEjavax.swing.text.html.TableView

HTML.Tag.INPUTFormView

HTML.Tag.SELECTFormView

HTML.Tag.TEXTAREAFormView

HTML.Tag.OBJECTObjectView

HTML.Tag.FRAMESETFrameSetView

HTML.Tag.FRAMEFrameView

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 inconsistent behavior, or return the wrong thing.

InsertHTMLTextAction can be used to insert an arbitrary string of HTML
into an existing HTML document. At least two HTML.Tags need to be
supplied. The first Tag, parentTag, identifies the parent in
the document to add the elements to. The second tag, addTag,
identifies the first tag that should be added to the document as
seen in the HTML string. One important thing to remember, is that
the parser is going to generate all the appropriate tags, even if
they aren't in the HTML string passed in.
For example, lets say you wanted to create an action to insert
a table into the body. The parentTag would be HTML.Tag.BODY,
addTag would be HTML.Tag.TABLE, and the string could be something
like <table><tr><td></td></tr></table>.
There is also an option to supply an alternate parentTag and
addTag. These will be checked for if there is no parentTag at
offset.

Class to watch the associated component and fire
hyperlink events on it when appropriate.

Interface to be supported by the parser.  This enables
providing a different parser while reusing some of the
implementation provided by this editor kit.

The result of parsing drives these callback methods.
The open and close actions should be balanced.  The
flush method will be the last method
called, to give the receiver a chance to flush any
pending data into the document.
Refer to DocumentParser, the default parser used, for further
information on the contents of the AttributeSets, the positions, and
other info.

HTMLFrameHyperlinkEvent is used to notify interested
parties that link was activated in a frame.

This is a writer for HTMLDocuments.

View of an Image, intended to support the HTML <IMG> tag.
Supports scaling via the HEIGHT and WIDTH attributes of the tag.
If the image is unable to be loaded any text specified via the
ALT attribute will be rendered.

While this class has been part of swing for a while now, it is public
as of 1.4.

Displays the inline element styles
based upon css attributes.

A view implementation to display an html list

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>

 <object classid="javax.swing.JLabel">
 <param name="text" value="sample text">
 </object>

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 document's
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:


     <object classid="javax.swing.JLabel">
     <param name="text" value="sample text">
     </object>

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.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

Displays the a paragraph, and uses css attributes for its
configuration.

This class defines the attributes of an SGML element
as described in a DTD using the ATTLIST construct.
An AttributeList can be obtained from the Element
class using the getAttributes() method.

It is actually an element in a linked list. Use the
getNext() method repeatedly to enumerate all the attributes
of an element.

A representation of a content model. A content model is
basically a restricted BNF expression. It is restricted in
the sense that it must be deterministic. This means that you
don't have to represent it as a finite state automaton.
See Annex H on page 556 of the SGML handbook for more information.

A Parser for HTML Documents (actually, you can specify a DTD, but
you should really only use this class with the html dtd in swing).
Reads an InputStream of HTML and
invokes the appropriate methods in the ParserCallback class. This
is the default parser used by HTMLEditorKit to parse HTML url's.
This will message the callback for all valid tags, as well as
tags that are implied but not explicitly specified. For example, the
html string (<p>blah) only has a p tag defined. The callback
will see the following methods:
handleStartTag(html, ...)
    handleStartTag(head, ...)
    handleEndTag(head)
    handleStartTag(body, ...)
    handleStartTag(p, ...)
    handleText(...)
    handleEndTag(p)
    handleEndTag(body)
    handleEndTag(html)

The items in italic are implied, that is, although they were not
explicitly specified, to be correct html they should have been present
(head isn't necessary, but it is still generated). For tags that
are implied, the AttributeSet argument will have a value of
Boolean.TRUE for the key
HTMLEditorKit.ParserCallback.IMPLIED.
HTML.Attributes defines a type safe enumeration of html attributes.
If an attribute key of a tag is defined in HTML.Attribute, the
HTML.Attribute will be used as the key, otherwise a String will be used.
For example <p foo=bar class=neat> has two attributes. foo is
not defined in HTML.Attribute, where as class is, therefore the
AttributeSet will have two values in it, HTML.Attribute.CLASS with
a String value of 'neat' and the String key 'foo' with a String value of
'bar'.
The position argument will indicate the start of the tag, comment
or text. Similar to arrays, the first character in the stream has a
position of 0. For tags that are
implied the position will indicate
the location of the next encountered tag. In the first example,
the implied start body and html tags will have the same position as the
p tag, and the implied end p, html and body tags will all have the same
position.
As html skips whitespace the position for text will be the position
of the first valid character, eg in the string '\n\n\nblah'
the text 'blah' will have a position of 3, the newlines are skipped.

For attributes that do not have a value, eg in the html
string <foo blah> the attribute blah
does not have a value, there are two possible values that will be
placed in the AttributeSet's value:

If the DTD does not contain an definition for the element, or the
    definition does not have an explicit value then the value in the
    AttributeSet will be HTML.NULL_ATTRIBUTE_VALUE.
If the DTD contains an explicit value, as in:
    <!ATTLIST OPTION selected (selected) #IMPLIED>
    this value from the dtd (in this case selected) will be used.


Once the stream has been parsed, the callback is notified of the most
likely end of line string. The end of line string will be one of
\n, \r or \r\n, which ever is encountered the most in parsing the
stream.

The representation of an SGML DTD.  DTD describes a document
syntax and is used in parsing of HTML documents.  It contains
a list of elements and their attributes as well as a list of
entities defined in the DTD.

SGML constants used in a DTD. The names of the
constants correspond the the equivalent SGML constructs
as described in "The SGML Handbook" by  Charles F. Goldfarb.

An element as described in a DTD using the ELEMENT construct.
This is essential the description of a tag. It describes the
type, content model, attributes, attribute types etc. It is used
to correctly parse a document by the Parser.

An entity is described in a DTD using the ENTITY construct.
It defines the type and value of the the entity.

A simple DTD-driven HTML parser. The parser reads an
HTML file from an InputStream and calls various methods
(which should be overridden in a subclass) when tags and
data are encountered.

Unfortunately there are many badly implemented HTML parsers
out there, and as a result there are many badly formatted
HTML files. This parser attempts to parse most HTML files.
This means that the implementation sometimes deviates from
the SGML specification in favor of HTML.

The parser treats \r and \r\n as \n. Newlines after starttags
and before end tags are ignored just as specified in the SGML/HTML
specification.

The html spec does not specify how spaces are to be coalesced very well.
Specifically, the following scenarios are not discussed (note that a
space should be used here, but I am using &nbsp to force the space to
be displayed):

'<b>blah <i> <strike> foo' which can be treated as:
'<b>blah <i><strike>foo'
as well as:
'<p><a href="xx"> <em>Using</em></a></p>'
which appears to be treated as:
'<p><a href="xx"><em>Using</em></a></p>'

If strict is false, when a tag that breaks flow,
(TagElement.breaksFlows) or trailing whitespace is
encountered, all whitespace will be ignored until a non whitespace
character is encountered. This appears to give behavior closer to
the popular browsers.

Responsible for starting up a new DocumentParser
each time its parse method is invoked. Stores a
reference to the dtd.

A generic HTML TagElement class. The methods define how white
space is interpreted around the tag.

  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);
  }

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
implementation 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.

Class to carry out some of the duties of
CSS formatting.  Implementations of this
class enable views to present the CSS formatting
while not knowing anything about how the CSS values
are being cached.

As a delegate of Views, this object is responsible for
the insets of a View and making sure the background
is maintained according to the CSS attributes.

Class to carry out some of the duties of CSS list
formatting.  Implementations of this
class enable views to present the CSS formatting
while not knowing anything about how the CSS values
are being cached.

Icon decorator that implements the view interface.  The
entire element is used to represent the icon.  This acts
as a gateway from the display-only View implementations to
interactive lightweight icons (that is, it allows icons
to be embedded into the View hierarchy.  The parent of the icon
is the container that is handed out by the associated view
factory.

InternationalFormatter extends DefaultFormatter,
using an instance of java.text.Format to handle the
conversion to a String, and the conversion from a String.

If getAllowsInvalid() is false, this will ask the
Format to format the current text on every edit.

You can specify a minimum and maximum value by way of the
setMinimum and setMaximum methods. In order
for this to work the values returned from stringToValue must be
comparable to the min/max values by way of the Comparable
interface.

Be careful how you configure the Format and the
InternationalFormatter, as it is possible to create a
situation where certain values can not be input. Consider the date
format 'M/d/yy', an InternationalFormatter that is always
valid (setAllowsInvalid(false)), is in overwrite mode
(setOverwriteMode(true)) and the date 7/1/99. In this
case the user will not be able to enter a two digit month or day of
month. To avoid this, the format should be 'MM/dd/yy'.

If InternationalFormatter is configured to only allow valid
values (setAllowsInvalid(false)), every valid edit will result
in the text of the JFormattedTextField being completely reset
from the Format.
The cursor position will also be adjusted as literal characters are
added/removed from the resulting String.

InternationalFormatter's behavior of
stringToValue is  slightly different than that of
DefaultTextFormatter, it does the following:

  parseObject is invoked on the Format
      specified by setFormat
  If a Class has been set for the values (setValueClass),
      supers implementation is invoked to convert the value returned
      from parseObject to the appropriate class.
  If a ParseException has not been thrown, and the value
      is outside the min/max a ParseException is thrown.
  The value is returned.

InternationalFormatter implements stringToValue
in this manner so that you can specify an alternate Class than
Format may return.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

3.
registered key listeners
registered input method listeners

4.

input method handling in JTextComponent

5.   keymap handling using the current keymap

JTextComponent is the base class for swing text
components.  It tries to be compatible with the
java.awt.TextComponent class
where it can reasonably do so.  Also provided are other services
for additional flexibility (beyond the pluggable UI and bean
support).
You can find information on how to use the functionality
this class provides in
General Rules for Using Text Components,
a section in The Java Tutorial.


Caret Changes

The caret is a pluggable object in swing text components.
Notification of changes to the caret position and the selection
are sent to implementations of the CaretListener
interface that have been registered with the text component.
The UI will install a default caret unless a customized caret
has been set.
By default the caret tracks all the document changes
performed on the Event Dispatching Thread and updates it's position
accordingly if an insertion occurs before or at the caret position
or a removal occurs before the caret position. DefaultCaret
tries to make itself visible which may lead to scrolling
of a text component within JScrollPane. The default caret
behavior can be changed by the DefaultCaret.setUpdatePolicy(int) method.

Note: Non-editable text components also have a caret though
it may not be painted.

Commands

Text components provide a number of commands that can be used
to manipulate the component.  This is essentially the way that
the component expresses its capabilities.  These are expressed
in terms of the swing Action interface,
using the TextAction implementation.
The set of commands supported by the text component can be
found with the getActions() method.  These actions
can be bound to key events, fired from buttons, etc.

Text Input

The text components support flexible and internationalized text input, using
keymaps and the input method framework, while maintaining compatibility with
the AWT listener model.

A Keymap lets an application bind key
strokes to actions.
In order to allow keymaps to be shared across multiple text components, they
can use actions that extend TextAction.
TextAction can determine which JTextComponent
most recently has or had focus and therefore is the subject of
the action (In the case that the ActionEvent
sent to the action doesn't contain the target text component as its source).

The input method framework
lets text components interact with input methods, separate software
components that preprocess events to let users enter thousands of
different characters using keyboards with far fewer keys.
JTextComponent is an active client of
the framework, so it implements the preferred user interface for interacting
with input methods. As a consequence, some key events do not reach the text
component because they are handled by an input method, and some text input
reaches the text component as committed text within an InputMethodEvent instead of as a key event.
The complete text input is the combination of the characters in
keyTyped key events and committed text in input method events.

The AWT listener model lets applications attach event listeners to
components in order to bind events to actions. Swing encourages the
use of keymaps instead of listeners, but maintains compatibility
with listeners by giving the listeners a chance to steal an event
by consuming it.

Keyboard event and input method events are handled in the following stages,
with each stage capable of consuming the event:



Stage
KeyEvent
InputMethodEvent
1.
    input methods
    (generated here)
2.
    focus manager



    3.
    registered key listeners
    registered input method listeners

    4.

    input method handling in JTextComponent

    5.   keymap handling using the current keymap
6.   keyboard handling in JComponent (e.g. accelerators, component navigation, etc.)




To maintain compatibility with applications that listen to key
events but are not aware of input method events, the input
method handling in stage 4 provides a compatibility mode for
components that do not process input method events. For these
components, the committed text is converted to keyTyped key events
and processed in the key event pipeline starting at stage 3
instead of in the input method event pipeline.

By default the component will create a keymap (named DEFAULT_KEYMAP)
that is shared by all JTextComponent instances as the default keymap.
Typically a look-and-feel implementation will install a different keymap
that resolves to the default keymap for those bindings not found in the
different keymap. The minimal bindings include:

inserting content into the editor for the
 printable keys.
removing content with the backspace and del
 keys.
caret movement forward and backward


Model/View Split

The text components have a model-view split.  A text component pulls
together the objects used to represent the model, view, and controller.
The text document model may be shared by other views which act as observers
of the model (e.g. a document may be shared by multiple components).




The model is defined by the Document interface.
This is intended to provide a flexible text storage mechanism
that tracks change during edits and can be extended to more sophisticated
models.  The model interfaces are meant to capture the capabilities of
expression given by SGML, a system used to express a wide variety of
content.
Each modification to the document causes notification of the
details of the change to be sent to all observers in the form of a
DocumentEvent which allows the views to stay up to date with the model.
This event is sent to observers that have implemented the
DocumentListener
interface and registered interest with the model being observed.

Location Information

The capability of determining the location of text in
the view is provided.  There are two methods, modelToView(int)
and viewToModel(java.awt.Point) for determining this information.

Undo/Redo support

Support for an edit history mechanism is provided to allow
undo/redo operations.  The text component does not itself
provide the history buffer by default, but does provide
the UndoableEdit records that can be used in conjunction
with a history buffer to provide the undo/redo support.
The support is provided by the Document model, which allows
one to attach UndoableEditListener implementations.

Thread Safety

The swing text components provide some support of thread
safe operations.  Because of the high level of configurability
of the text components, it is possible to circumvent the
protection provided.  The protection primarily comes from
the model, so the documentation of AbstractDocument
describes the assumptions of the protection provided.
The methods that are safe to call asynchronously are marked
with comments.

Newlines

For a discussion on how newlines are handled, see
DefaultEditorKit.


Printing support

Several print methods are provided for basic
document printing.  If more advanced printing is needed, use the
getPrintable(java.text.MessageFormat, java.text.MessageFormat) method.



Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

Represents a drop location for JTextComponents.

Binding record for creating key bindings.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

A collection of bindings of KeyStrokes to actions.  The
bindings are basically name-value pairs that potentially
resolve in a hierarchy.

A LabelView is a styled chunk of text
that represents a view mapped over an element in the
text model.  It caches the character level attributes
used for rendering.

Layered highlight renderer.

A queue of text layout tasks.

MaskFormatter is used to format and edit strings. The behavior
of a MaskFormatter is controlled by way of a String mask
that specifies the valid characters that can be contained at a particular
location in the Document model. The following characters can
be specified:



   Character
   Description


   #
   Any valid number, uses Character.isDigit.


   '
   Escape character, used to escape any of the
      special formatting characters.


   UAny character (Character.isLetter). All
       lowercase letters are mapped to upper case.

LAny character (Character.isLetter). All
       upper case letters are mapped to lower case.

AAny character or number (Character.isLetter
      or Character.isDigit)

?Any character
       (Character.isLetter).

*Anything.
HAny hex character (0-9, a-f or A-F).



Typically characters correspond to one char, but in certain languages this
is not the case. The mask is on a per character basis, and will thus
adjust to fit as many chars as are needed.

You can further restrict the characters that can be input by the
setInvalidCharacters and setValidCharacters
methods. setInvalidCharacters allows you to specify
which characters are not legal. setValidCharacters allows
you to specify which characters are valid. For example, the following
code block is equivalent to a mask of '0xHHH' with no invalid/valid
characters:


MaskFormatter formatter = new MaskFormatter("0x***");
formatter.setValidCharacters("0123456789abcdefABCDEF");

When initially formatting a value if the length of the string is
less than the length of the mask, two things can happen. Either
the placeholder string will be used, or the placeholder character will
be used. Precedence is given to the placeholder string. For example:


  MaskFormatter formatter = new MaskFormatter("###-####");
  formatter.setPlaceholderCharacter('_');
  formatter.getDisplayValue(tf, "123");

Would result in the string '123-____'. If
setPlaceholder("555-1212") was invoked '123-1212' would
result. The placeholder String is only used on the initial format,
on subsequent formats only the placeholder character will be used.

If a MaskFormatter is configured to only allow valid characters
(setAllowsInvalid(false)) literal characters will be skipped as
necessary when editing. Consider a MaskFormatter with
the mask "###-####" and current value "555-1212". Using the right
arrow key to navigate through the field will result in (| indicates the
position of the caret):


  |555-1212
  5|55-1212
  55|5-1212
  555-|1212
  555-1|212
The '-' is a literal (non-editable) character, and is skipped.

Similar behavior will result when editing. Consider inserting the string
'123-45' and '12345' into the MaskFormatter in the
previous example. Both inserts will result in the same String,
'123-45__'. When MaskFormatter
is processing the insert at character position 3 (the '-'), two things can
happen:

  If the inserted character is '-', it is accepted.
  If the inserted character matches the mask for the next non-literal
      character, it is accepted at the new location.
  Anything else results in an invalid edit


By default MaskFormatter will not allow invalid edits, you can
change this with the setAllowsInvalid method, and will
commit edits on valid edits (use the setCommitsOnValidEdit to
change this).

By default, MaskFormatter is in overwrite mode. That is as
characters are typed a new character is not inserted, rather the character
at the current location is replaced with the newly typed character. You
can change this behavior by way of the method setOverwriteMode.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

A generic interface for a mutable collection of unique attributes.

Implementations will probably want to provide a constructor of the
form:
public XXXAttributeSet(ConstAttributeSet source);

NavigationFilter can be used to restrict where the cursor can
be positioned. When the default cursor positioning actions attempt to
reposition the cursor they will call into the
NavigationFilter, assuming
the JTextComponent has a non-null
NavigationFilter set. In this manner
the NavigationFilter can effectively restrict where the
cursor can be positioned. Similarly DefaultCaret will call
into the NavigationFilter when the user is changing the
selection to further restrict where the cursor can be positioned.

Subclasses can conditionally call into supers implementation to restrict
where the cursor can be placed, or call directly into the
FilterBypass.

Used as a way to circumvent calling back into the caret to
position the cursor. Caret implementations that wish to support
a NavigationFilter must provide an implementation that will
not callback into the NavigationFilter.

NumberFormatter subclasses InternationalFormatter
adding special behavior for numbers. Among the specializations are
(these are only used if the NumberFormatter does not display
invalid numbers, for example, setAllowsInvalid(false)):

  Pressing /- (- is determined from the
      DecimalFormatSymbols associated with the
      DecimalFormat) in any field but the exponent
      field will attempt to change the sign of the number to
      positive/negative.
  Pressing /- (- is determined from the
      DecimalFormatSymbols associated with the
      DecimalFormat) in the exponent field will
      attempt to change the sign of the exponent to positive/negative.


If you are displaying scientific numbers, you may wish to turn on
overwrite mode, setOverwriteMode(true). For example:


DecimalFormat decimalFormat = new DecimalFormat("0.000E0");
NumberFormatter textFormatter = new NumberFormatter(decimalFormat);
textFormatter.setOverwriteMode(true);
textFormatter.setAllowsInvalid(false);

If you are going to allow the user to enter decimal
values, you should either force the DecimalFormat to contain at least
one decimal (#.0###), or allow the value to be invalid
setAllowsInvalid(true). Otherwise users may not be able to
input decimal values.

NumberFormatter provides slightly different behavior to
stringToValue than that of its superclass. If you have
specified a Class for values, DefaultFormatter.setValueClass(java.lang.Class<?>), that is one of
of Integer, Long, Float,
Double, Byte or Short and
the Format's parseObject returns an instance of
Number, the corresponding instance of the value class
will be created using the constructor appropriate for the primitive
type the value class represents. For example:
setValueClass(Integer.class) will cause the resulting
value to be created via
new Integer(((Number)formatter.parseObject(string)).intValue()).
This is typically useful if you
wish to set a min/max value as the various Number
implementations are generally not comparable to each other. This is also
useful if for some reason you need a specific Number
implementation for your values.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

View of a simple line-wrapping paragraph that supports
multiple fonts, colors, components, icons, etc.  It is
basically a vertical box with a margin around it.  The
contents of the box are a bunch of rows which are special
horizontal boxes.  This view creates a collection of
views that represent the child elements of the paragraph
element.  Each of these views are placed into a row
directly if they will fit, otherwise the breakView
method is called to try and carve the view into pieces
that fit.

Implements a View suitable for use in JPasswordField
UI implementations.  This is basically a field ui that
renders its contents as the echo character specified
in the associated component (if it can narrow the
component to a JPasswordField).

A plain document that maintains no character attributes.  The
default element structure for this document is a map of the lines in
the text.  The Element returned by getDefaultRootElement is
a map of the lines, and each child element represents a line.
This model does not maintain any character level attributes,
but each line can be tagged with an arbitrary set of attributes.
Line to offset, and offset to line translations can be quickly
performed using the default root element.  The structure information
of the DocumentEvent's fired by edits will indicate the line
structure changes.

The default content storage management is performed by a
gapped buffer implementation (GapContent).  It supports
editing reasonably large documents with good efficiency when
the edits are contiguous or clustered, as is typical.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

Implements View interface for a simple multi-line text view
that has text in one font and color.  The view represents each
child element as a line of text.

Represents a location within a document.  It is intended to abstract away
implementation details of the document and enable specification of
positions within the document that are capable of tracking of change as
the document is edited.

A Position object points at a location between two characters.
As the surrounding content is altered, the Position object
adjusts its offset automatically to reflect the changes. If content is
inserted or removed before the Position object's location, then the
Position increments or decrements its offset, respectively,
so as to point to the same location. If a portion of the document is removed
that contains a Position's offset, then the Position's
offset becomes that of the beginning of the removed region. For example, if
a Position has an offset of 5 and the region 2-10 is removed, then
the Position's offset becomes 2.

Position with an offset of 0 is a special case. It never changes its
offset while document content is altered.

A typesafe enumeration to indicate bias to a position
in the model.  A position indicates a location between
two characters.  The bias can be used to indicate an
interest toward one of the two sides of the position
in boundary conditions where a simple offset is
ambiguous.

This is the default implementation of RTF editing
functionality.  The RTF support was not written by the
Swing team.  In the future we hope to improve the support
provided.

A segment of a character array representing a fragment
of text.  It should be treated as immutable even though
the array is directly accessible.  This gives fast access
to fragments of text without the overhead of copying
around characters.  This is effectively an unprotected
String.

The Segment implements the java.text.CharacterIterator
interface to support use with the i18n support without
copying text into a string.

A straightforward implementation of MutableAttributeSet using a
hash table.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

An implementation of the AbstractDocument.Content interface that is
a brute force implementation that is useful for relatively small
documents and/or debugging.  It manages the character content
as a simple character array.  It is also quite inefficient.

It is generally recommended that the gap buffer or piece table
implementations be used instead.  This buffer does not scale up
to large sizes.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

A collection of attributes to associate with an element in a document.
Since these are typically used to associate character and paragraph
styles with the element, operations for this are provided.  Other
customized attributes that get associated with the element will
effectively be name-value pairs that live in a hierarchy and if a name
(key) is not found locally, the request is forwarded to the parent.
Commonly used attributes are separated out to facilitate alternative
implementations that are more efficient.

 A collection of well known or common attribute keys
and methods to apply to an AttributeSet or MutableAttributeSet
to get/set the properties in a typesafe manner.

The paragraph attributes form the definition of a paragraph to be rendered.
All sizes are specified in points (such as found in postscript), a
device independent measure.

This is a typesafe enumeration of the well-known
attributes that contribute to a character style.  These are
aliased by the outer class for general presentation.

This is a typesafe enumeration of the well-known
attributes that contribute to a color.  These are aliased
by the outer class for general presentation.

This is a typesafe enumeration of the well-known
attributes that contribute to a font.  These are aliased
by the outer class for general presentation.

This is a typesafe enumeration of the well-known
attributes that contribute to a paragraph style.  These are
aliased by the outer class for general presentation.

A pool of styles and their associated resources.  This class determines
the lifetime of a group of resources by being a container that holds
caches for various resources such as font and color that get reused
by the various style definitions.  This can be shared by multiple
documents if desired to maximize the sharing of related resources.

This class also provides efficient support for small sets of attributes
and compresses them by sharing across uses and taking advantage of
their immutable nature.  Since many styles are replicated, the potential
for sharing is significant, and copies can be extremely cheap.
Larger sets reduce the possibility of sharing, and therefore revert
automatically to a less space-efficient implementation.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

Interface for a generic styled document.

This is the set of things needed by a text component
to be a reasonably functioning editor for some type
of text document.  This implementation provides a default
implementation which treats text as styled text and
provides a minimal set of actions for editing styled text.

An action to set paragraph alignment.  This sets the
StyleConstants.Alignment attribute for the
currently selected range of the target JEditorPane.
This is done by calling
StyledDocument.setParagraphAttributes
on the styled document associated with the target
JEditorPane.

If the target text component is specified as the
source of the ActionEvent and there is a command string,
the command string will be interpreted as an integer
that should be one of the legal values for the
StyleConstants.Alignment attribute.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

An action to toggle the bold attribute.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

An action to set the font family in the associated
JEditorPane.  This will use the family specified as
the command string on the ActionEvent if there is one,
otherwise the family that was initialized with will be used.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

An action to set the font size in the associated
JEditorPane.  This will use the size specified as
the command string on the ActionEvent if there is one,
otherwise the size that was initialized with will be used.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

An action to set foreground color.  This sets the
StyleConstants.Foreground attribute for the
currently selected range of the target JEditorPane.
This is done by calling
StyledDocument.setCharacterAttributes
on the styled document associated with the target
JEditorPane.

If the target text component is specified as the
source of the ActionEvent and there is a command string,
the command string will be interpreted as the foreground
color.  It will be interpreted by called
Color.decode, and should therefore be
legal input for that method.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

An action to toggle the italic attribute.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

An action that assumes it's being fired on a JEditorPane
with a StyledEditorKit (or subclass) installed.  This has
some convenience methods for causing character or paragraph
level attribute changes.  The convenience methods will
throw an IllegalArgumentException if the assumption of
a StyledDocument, a JEditorPane, or a StyledEditorKit
fail to be true.

The component that gets acted upon by the action
will be the source of the ActionEvent if the source
can be narrowed to a JEditorPane type.  If the source
can't be narrowed, the most recently focused text
component is changed.  If neither of these are the
case, the action cannot be performed.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

An action to toggle the underline attribute.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

Interface for Views that have size dependent upon tabs.

Simple interface to allow for different types of
implementations of tab expansion.

 Implements View interface for a table, that is composed of an
element structure where the child elements of the element
this view is responsible for represent rows and the child
elements of the row elements are cells.  The cell elements can
have an arbitrary element structure under them, which will
be built with the ViewFactory returned by the getViewFactory
method.


   TABLE
     ROW
       CELL
       CELL
     ROW
       CELL
       CELL

This is implemented as a hierarchy of boxes, the table itself
is a vertical box, the rows are horizontal boxes, and the cells
are vertical boxes.  The cells are allowed to span multiple
columns and rows.  By default, the table can be thought of as
being formed over a grid (i.e. somewhat like one would find in
gridbag layout), where table cells can request to span more
than one grid cell.  The default horizontal span of table cells
will be based upon this grid, but can be changed by reimplementing
the requested span of the cell (i.e. table cells can have independant
spans if desired).

A TabSet is comprised of many TabStops. It offers methods for locating the
closest TabStop to a given position and finding all the potential TabStops.
It is also immutable.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

This class encapsulates a single tab stop (basically as tab stops
are thought of by RTF). A tab stop is at a specified distance from the
left margin, aligns text in a specified way, and has a specified leader.
TabStops are immutable, and usually contained in TabSets.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

An Action implementation useful for key bindings that are
shared across a number of different text components.  Because
the action is shared, it must have a way of getting it's
target to act upon.  This class provides support to try and
find a text component to operate on.  The preferred way of
getting the component to act upon is through the ActionEvent
that is received.  If the Object returned by getSource can
be narrowed to a text component, it will be used.  If the
action event is null or can't be narrowed, the last focused
text component is tried.  This is determined by being
used in conjunction with a JTextController which
arranges to share that information with a TextAction.

Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing.  As of 1.4, support for long term storage
of all JavaBeans™
has been added to the java.beans package.
Please see XMLEncoder.

A collection of methods to deal with various text
related activities.

Participate in layout.

The view has a setSize method which is like
doLayout and setSize in Component combined.
The view has a preferenceChanged method which is
like invalidate in Component except that one can
invalidate just one axis
and the child requesting the change is identified.
A View expresses the size that it would like to be in terms of three
values, a minimum, a preferred, and a maximum span.  Layout in a view is
can be done independently upon each axis.  For a properly functioning View
implementation, the minimum span will be <= the preferred span which in turn
will be <= the maximum span.


The minimum set of methods for layout are:

getMinimumSpan
getPreferredSpan
getMaximumSpan
getAlignment
preferenceChanged
setSize

The exact calling sequence is up to the layout functionality of
the parent view (if the view has any children).  The view may collect
the preferences of the children prior to determining what it will give
each child, or it might iteratively update the children one at a time.


Render a portion of the model.

This is done in the paint method, which is pretty much like a component
paint method.  Views are expected to potentially populate a fairly large
tree.  A View has the following semantics for rendering:


The view gets its allocation from the parent at paint time, so it
must be prepared to redo layout if the allocated area is different from
what it is prepared to deal with.
The coordinate system is the same as the hosting Component
(i.e. the Component returned by the
getContainer method).
This means a child view lives in the same coordinate system as the parent
view unless the parent has explicitly changed the coordinate system.
To schedule itself to be repainted a view can call repaint on the hosting
Component.
The default is to not clip the children.  It is more efficient
to allow a view to clip only if it really feels it needs clipping.
The Graphics object given is not initialized in any way.
A view should set any settings needed.
A View is inherently transparent.  While a view may render into its
entire allocation, typically a view does not.  Rendering is performed by
traversing down the tree of View implementations.
Each View is responsible
for rendering its children.  This behavior is depended upon for thread
safety.  While view implementations do not necessarily have to be implemented
with thread safety in mind, other view implementations that do make use of
concurrency can depend upon a tree traversal to guarantee thread safety.
The order of views relative to the model is up to the implementation.
Although child views will typically be arranged in the same order that they
occur in the model, they may be visually arranged in an entirely different
order.  View implementations may have Z-Order associated with them if the
children are overlapping.

The methods for rendering are:

paint


Translate between the model and view coordinate systems.

Because the view objects are produced from a factory and therefore cannot
necessarily be counted upon to be in a particular pattern, one must be able
to perform translation to properly locate spatial representation of the model.
The methods for doing this are:

modelToView
viewToModel
getDocument
getElement
getStartOffset
getEndOffset

The layout must be valid prior to attempting to make the translation.
The translation is not valid, and must not be attempted while changes
are being broadcasted from the model via a DocumentEvent.


Respond to changes from the model.

If the overall view is represented by many pieces (which is the best situation
if one want to be able to change the view and write the least amount of new code),
it would be impractical to have a huge number of DocumentListeners.
If each
view listened to the model, only a few would actually be interested in the
changes broadcasted at any given time.   Since the model has no knowledge of
views, it has no way to filter the broadcast of change information.  The view
hierarchy itself is instead responsible for propagating the change information.
At any level in the view hierarchy, that view knows enough about its children to
best distribute the change information further.   Changes are therefore broadcasted
starting from the root of the view hierarchy.
The methods for doing this are:

insertUpdate
removeUpdate
changedUpdate

 A very important part of the text package is the View class.
 As the name suggests it represents a view of the text model,
 or a piece of the text model.
 It is this class that is responsible for the look of the text component.
 The view is not intended to be some completely new thing that one must
 learn, but rather is much like a lightweight component.

By default, a view is very light.  It contains a reference to the parent
view from which it can fetch many things without holding state, and it
contains a reference to a portion of the model (Element).
A view does not
have to exactly represent an element in the model, that is simply a typical
and therefore convenient mapping.  A view can alternatively maintain a couple
of Position objects to maintain its location in the model (i.e. represent
a fragment of an element).  This is typically the result of formatting where
views have been broken down into pieces.  The convenience of a substantial
relationship to the element makes it easier to build factories to produce the
views, and makes it easier  to keep track of the view pieces as the model is
changed and the view must be changed to reflect the model.  Simple views
therefore represent an Element directly and complex views do not.

A view has the following responsibilities:


    Participate in layout.

    The view has a setSize method which is like
    doLayout and setSize in Component combined.
    The view has a preferenceChanged method which is
    like invalidate in Component except that one can
    invalidate just one axis
    and the child requesting the change is identified.
    A View expresses the size that it would like to be in terms of three
    values, a minimum, a preferred, and a maximum span.  Layout in a view is
    can be done independently upon each axis.  For a properly functioning View
    implementation, the minimum span will be <= the preferred span which in turn
    will be <= the maximum span.


    The minimum set of methods for layout are:

    getMinimumSpan
    getPreferredSpan
    getMaximumSpan
    getAlignment
    preferenceChanged
    setSize


  The setSize method should be prepared to be called a number of times
    (i.e. It may be called even if the size didn't change).
    The setSize method
    is generally called to make sure the View layout is complete prior to trying
    to perform an operation on it that requires an up-to-date layout.  A view's
    size should always be set to a value within the minimum and maximum
    span specified by that view.  Additionally, the view must always call the
    preferenceChanged method on the parent if it has changed the
    values for the
    layout it would like, and expects the parent to honor.  The parent View is
    not required to recognize a change until the preferenceChanged
    has been sent.
    This allows parent View implementations to cache the child requirements if
    desired.  The calling sequence looks something like the following:



    The exact calling sequence is up to the layout functionality of
    the parent view (if the view has any children).  The view may collect
    the preferences of the children prior to determining what it will give
    each child, or it might iteratively update the children one at a time.


    Render a portion of the model.

    This is done in the paint method, which is pretty much like a component
    paint method.  Views are expected to potentially populate a fairly large
    tree.  A View has the following semantics for rendering:


    The view gets its allocation from the parent at paint time, so it
    must be prepared to redo layout if the allocated area is different from
    what it is prepared to deal with.
    The coordinate system is the same as the hosting Component
    (i.e. the Component returned by the
    getContainer method).
    This means a child view lives in the same coordinate system as the parent
    view unless the parent has explicitly changed the coordinate system.
    To schedule itself to be repainted a view can call repaint on the hosting
    Component.
    The default is to not clip the children.  It is more efficient
    to allow a view to clip only if it really feels it needs clipping.
    The Graphics object given is not initialized in any way.
    A view should set any settings needed.
    A View is inherently transparent.  While a view may render into its
    entire allocation, typically a view does not.  Rendering is performed by
    traversing down the tree of View implementations.
    Each View is responsible
    for rendering its children.  This behavior is depended upon for thread
    safety.  While view implementations do not necessarily have to be implemented
    with thread safety in mind, other view implementations that do make use of
    concurrency can depend upon a tree traversal to guarantee thread safety.
    The order of views relative to the model is up to the implementation.
    Although child views will typically be arranged in the same order that they
    occur in the model, they may be visually arranged in an entirely different
    order.  View implementations may have Z-Order associated with them if the
    children are overlapping.

    The methods for rendering are:

    paint


    Translate between the model and view coordinate systems.

    Because the view objects are produced from a factory and therefore cannot
    necessarily be counted upon to be in a particular pattern, one must be able
    to perform translation to properly locate spatial representation of the model.
    The methods for doing this are:

    modelToView
    viewToModel
    getDocument
    getElement
    getStartOffset
    getEndOffset

    The layout must be valid prior to attempting to make the translation.
    The translation is not valid, and must not be attempted while changes
    are being broadcasted from the model via a DocumentEvent.


    Respond to changes from the model.

    If the overall view is represented by many pieces (which is the best situation
    if one want to be able to change the view and write the least amount of new code),
    it would be impractical to have a huge number of DocumentListeners.
    If each
    view listened to the model, only a few would actually be interested in the
    changes broadcasted at any given time.   Since the model has no knowledge of
    views, it has no way to filter the broadcast of change information.  The view
    hierarchy itself is instead responsible for propagating the change information.
    At any level in the view hierarchy, that view knows enough about its children to
    best distribute the change information further.   Changes are therefore broadcasted
    starting from the root of the view hierarchy.
    The methods for doing this are:

    insertUpdate
    removeUpdate
    changedUpdate

A factory to create a view of some portion of document subject.
This is intended to enable customization of how views get
mapped over a document model.

View of plain text (text with only one font and color)
that does line-wrapping.  This view expects that its
associated element has child elements that represent
the lines it should be wrapping.  It is implemented
as a vertical box that contains logical line views.
The logical line views are nested classes that render
the logical line as multiple physical line if the logical
line is too wide to fit within the allocation.  The
line views draw upon the outer class for its state
to reduce their memory requirements.

The line views do all of their rendering through the
drawLine method which in turn does all of
its rendering through the drawSelectedText
and drawUnselectedText methods.  This
enables subclasses to easily specialize the rendering
without concern for the layout aspects.

ZoneView is a View implementation that creates zones for which
the child views are not created or stored until they are needed
for display or model/view translations.  This enables a substantial
reduction in memory consumption for situations where the model
being represented is very large, by building view objects only for
the region being actively viewed/edited.  The size of the children
can be estimated in some way, or calculated asynchronously with
only the result being saved.

ZoneView extends BoxView to provide a box that implements
zones for its children.  The zones are special View implementations
(the children of an instance of this class) that represent only a
portion of the model that an instance of ZoneView is responsible
for.  The zones don't create child views until an attempt is made
to display them. A box shaped view is well suited to this because:


  Boxes are a heavily used view, and having a box that
  provides this behavior gives substantial opportunity
  to plug the behavior into a view hierarchy from the
  view factory.

  Boxes are tiled in one direction, so it is easy to
  divide them into zones in a reliable way.

  Boxes typically have a simple relationship to the model (i.e. they
  create child views that directly represent the child elements).

  Boxes are easier to estimate the size of than some other shapes.


The default behavior is controlled by two properties, maxZoneSize
and maxZonesLoaded.  Setting maxZoneSize to Integer.MAX_VALUE would
have the effect of causing only one zone to be created.  This would
effectively turn the view into an implementation of the decorator
pattern.  Setting maxZonesLoaded to a value of Integer.MAX_VALUE would
cause zones to never be unloaded.  For simplicity, zones are created on
boundaries represented by the child elements of the element the view is
responsible for.  The zones can be any View implementation, but the
default implementation is based upon AsyncBoxView which supports fairly
large zones efficiently.