Java: Swing: Text 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:

There is no way to get all properties. They may be potentially interesting (at the very least for debugging). As it is, you can only lookup properties whose keys you know (#4148068).
AbstractDocument already offers accessthe properties as publicly accessible and replacable property 'DocumentProperties' of type Dictionary. It is currently not used internally.
Unlike the rest of Document, changes of the properties cannot be observed. As seen in the table below, this has already caused some heuristics to notice when a property (like "i18n") may have changed.
To explicitly reach the heuristics of for example BasicTextUI, a fake DocumentEvent (insert with length 0) could be sent from these methods.
In fact, if you change the RUN_DIRECTION property, AbstractDocument seems to send an (incorrect!) insertion type event for the whole document (although nothing has been inserted).

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.