JavaSwingText components and Document: Document properties


Document properties

Properties

Every Document has the methods getProperty() to access 'properties' and putProperty() to store properties in the Document. The names and values can be arbitrary Objects (!= null). What these properties mean (and what type the values must have) must be documented somewhere, or the property is useless. There are some predefined properties in standard classes, and some more are in internal use.

Two problem exist with this property interface:

As a workaround, it is better only to change properties that affect appearance before the Document is displayed in a text component, or while it isn't.

A suggestion for custom Documents might be to store the properties in the AttributeSet of a separate root element (or even in the default root element, since they do no clash with standard attribute set properties, except RUN_DIRECTION, and there it does the right thing). Both problems mentioned above don't exist then. The whole Document would be reconsidered when a property is changed (then again, for longer Documents this may be too expensive). The heuristic for BasicTextUI and "i18n" still must be applied.

Most of the standard properties below are Strings, so they are sensitive to name clash. When using own keys, I suggest using "more unique" Objects to avoid this (but beware of Serialization duplicates, which must compare equal or be resolved to the original).

Table of standard properties

The following properties are / seem to be used internally in the Swing text packages on Documents.

Warning: Do not rely on any information that follows. It may be only temporarily true, or not at all. Believe only what you read in the Javadoc API specification.

(put) in the 'Use' column means that the class sets the property (putProperty).

String value

(if String)

Definition class

Field name

Type

Description / Comments

Use

stream

Document

StreamDescriptionProperty

URL?

(description) where the document came from

JTextComponent (put):

set to 'description' argument in read(), no matter what type

JEditorPane (put):

stores the URL (get/setPage()).

looked up again when ChangedCharSetException was caught.

HTMLEditorKit.ActivateLinkAction:

URL, used as base for URLs.

HTMLDocument:

if URL, used as "base" (getReader).

html/FormView (put):

set in new document for get/post URL.

title

Document

TitleProperty

String?

title (name) of the document

HTMLDocument.HTMLReader (put):

set to String from TITLE element.

HTMLWriter:

String, written if met HTML.Tag.TITLE

1.4: AccessibleHTML: ACCESSIBLE_NAME

i18n

AbstractDocument

I18NProperty

(package access)

Boolean

Should bidirectional text be supported?

AbstractDocument (put):

default looked up by System.getProperty("i18n"). automatically set by insertString if RUN_DIRECTION is set or the inserted string requires bidirectional handling.

DefaultStyledDocument:

once looked up, together RUN_DIRECTION as element attribute.

ParagraphView:

if true, create a "i18nStrategy" (only in constructor)

if true, TextLayoutStrategy is used, if not, normal FlowStrategy (from superclass)

TextLayoutStrategy:

use bidi algorithm if set.

BasicTextUI:

recreate views if set (tested in insertUpdate).

BasicTextFieldUI / BasicTextAreaUI:

recreate views if set (tested in "font" property change listener).

if true, create different views

JEditorPane.PlainEditorKit: creates different views

load priority

AbstractDocument

AsyncLoadPriority

(package access)

Integer

Should asynchronous loading (with given Thread priority) be supported?

AbstractDocument:

get/setAsynchronousLoadPriority(): set allows only non-negative values; get() returns any value, -1 if not found.

getAsynchronousLoadPriority() is looked up in JEditorPane.setPage(), and a Thread is started if >= 0.

set from HTMLEditorKit, BasicHTML

tabSize

PlainDocument

tabSizeAttribute

Integer

width of tabulator stops in "ems"

PlainDocument (put):

set to 8 from constructor(s).

JTextArea (put): wrapped in get/setTabSize(), defaults to 8.

(Wrapped)PlainView:

looked up in getTabSize(), defaults to 8.

lineLimit

PlainDocument

lineLimitAttribute

Integer

maximum length of a line

not supported (yet?)

TextAttribute

RUN_DIRECTION

Boolean

default run direction?

BasicTextUI (put): set on document if property change event for component orientation arrives.

AbstractDocument:

used for some bidi stuff; interaction with "i18n", presence automatically enables "i18n" in insertString().

TextLayoutStrategy: used as global attribute.

__EndOfLine__

DefaultEditorKit

EndOfLineStringProperty

String

the line separator that the "stream" the document was read from had

AbstractWriter:

used for line breaks instead of the system property if set.

DefaultEditorKit (put):

set on reading to the encountered separator.

used for line breaks instead of the system property

HTMLEditorKit (put):

set from handleEndOfLineString

IgnoreCharsetDirective

Boolean

Parser should ignore charset change (embedded charset in source stream).

JEditorPane (put):

set when ChangedCharSetException was caught (setPage)

HTMLEditorKit:

given the parser

content-type

String

JEditorPane (put):

getStream(URL) from the URL info

never looked up again

content-encoding

String

JEditorPane (put):

getStream(URL) from the URL info

never looked up again

1.4: filterNewlines

Boolean

insertString should replace newlines by spaces

PlainDocument: support

JTextField (put): set to true in setDocument (bad style?)

1.4: DocumentFilter.class

DocumentFilter

should delegate insertString/remove to the provided DocumentFilter (see official text).

JFormattedTextField.AbstractFormatter (put): sets it, in addition to AbstractDocument.setDocumentFilter (the latter only if possible)

AbstractDocument.insertString/remove use the filterdirectly (and not the property) - sounsetting/changing the property doesn't affect the filtering (this should really be done differently)

1.4.2. changed to String "multibyte"

1.4beta2: AbstractDocument.MultiByteProperty

(which is a package-private Object, thus it breaks serialization, (#4513615))

Boolean

Are chars >255 in Document?

AbstractDocument.insertUpdate (put)

GlyphView: uses BreakIterator instead of white space heuristic if present (efficiency hack?)

Table of HTMLDocument properties

These properties are only used on HTMLDocument and are mostly specific to that.

String value

(if String)

Definition class

Field name

Type

Description / Comments

Use

AdditionalComments

HTMLDocument

AdditionalComments

Vector[of String?]

additional comments (found during reading)

HTMLDocument.HTMLReader (put):

set/appended to in handleComment().

1.4: not cleared anymore (?)

HTMLWriter:

written (at the end?)

__PARSER__

HTMEditorKit.Parser?

parser used to produce the document?

HTMLDocument (put):

set to null in setParser().

value is returned if proper type and != null fromgetParser() otherwise explicit member variable is used.

token threshold

HTMLDocument

TokenThreshold

(package access)

Integer

loading behaviour: how much buffering before updating element structure

HTMLDocument (put):

get/set with default Integer.MAX_VALUE.

StyleType

HTMLDocument

StyleType

(package access)

String

content type for style sheets

HTMLDocument (put):

package access methods get/setDefaultStyleSheetType() with default "text/css".

__MAP__

HTMLDocument

MAP_PROPERTY

(package access)

Hashtable[String->Map]

(Map has package access)

for HTML.Tag.MAP

HTMLDocument (put):

package access methods add/removeMap,

getMap, getMaps which are used in HTMLEditorKit, HTMLWriter

imageCache

ImageView

(package access)

IMAGE_CACHE_PROPERTY

Dictionary[URL->Image]

Image caching

ImageView:

not set, only used if found (i.e. the cache is never used)

RTF properties

There are a lot of RTF properties (with String keys), but they are used only internally (like some of the HTML properties), and I am not interested enough to look them all up.


(C) 2001-2009 Christian Kaufhold (swing@chka.de)