Package org.fxmisc.richtext.model

Defines the support classes and operations related to EditableStyledDocument, the immutable model of rich-text content that can be rendered and edited.

An EditableStyledDocument acts as an immutable model for rich-text content that will be rendered by an object implementing the TextEditingArea interface. A StyledDocument is composed of a list of Paragraphs. Paragraphs are nothing more than an object containing a paragraph style (type PS), a list of a generic segments (type SEG), and a list of generic styles (type S) that can apply to a segment. Most of the time, either EditableStyledDocument or ReadOnlyStyledDocument are being used to implement that interface.

The document can include more than just text; thus, the segment generic can be specified as regular text (String) or as an Either (e.g. Either<String, Image> or as a nested Either (e.g. Either<String, Either<Image, Either<Circle, Square>) if one wanted to have four different kinds of segments (ways to specify a segment generic in a way that still makes the code easy to read are not described here).

To allow these generics, one must supply a SegmentOps object that can correctly operate on the generic segments and their generic styles. In addition, a TextOps adds one more method to its base interface by adding a method that maps a String to a given segment. For text-based custom segments, one should use SegmentOpsBase and for node-based custom segments, one should use NodeSegmentOpsBase.

The document also uses StyleSpans to store styles in a memory-efficient way. To construct one, use StyleSpans.singleton(org.fxmisc.richtext.model.StyleSpan) or StyleSpansBuilder.

To navigate throughout the document, read through the javadoc of TwoDimensional and TwoDimensional.Bias. Also, read the difference between "position" and "index" in StyledDocument.getAbsolutePosition(int, int).

To serialize things correctly, see Codec and its static factory methods.

Lastly, the EditableStyledDocument can emit PlainTextChanges or RichTextChanges that can be used to undo/redo various changes.

See Also:

EditableStyledDocument, Paragraph, SegmentOps, TwoDimensional, TwoDimensional.Bias

Interface Summary

Interface	Description
Codec<T>	Specifies a way to serialize an object to/from a data stream
EditableStyledDocument<PS,SEG,S>	Content model for GenericStyledArea.
SegmentOps<SEG,S>	Defines the operations which are supported on a specific segment type.
StyledDocument<PS,SEG,S>	An object (document) that is a list of styleable Paragraph that each contain a list of styleable segments.
StyleSpans<S>	Essentially, a list of StyleSpan objects.
TextOps<SEG,S>	Extends SegmentOps by adding TextOps.create(String), which can create a TextOps segment from a given String
TwoDimensional	TwoDimensional is an interface for any item which can be navigated in two dimensions, such as a List of Lists.
TwoDimensional.Position	A two dimensional position, with a major offset (such as a paragraph index within a document) and a minor dimension (such as a segment index or column position within a paragraph).

Class Summary

Class	Description
GenericEditableStyledDocument<PS,SEG,S>	Provides a basic implementation of EditableStyledDocument while still allowing a developer to specify its generics.
NodeSegmentOpsBase<SEG,S>	Properly implements SegmentOps when implementing a non-text custom object, such as a shape or image, and reduces boilerplate.
Paragraph<PS,SEG,S>	One paragraph in the document that can itself be styled and which contains a list of styled segments.
PlainTextChange	An object that specifies where a non-style change occurred in a GenericStyledArea.
ReadOnlyStyledDocument<PS,SEG,S>	An immutable implementation of StyledDocument that does not allow editing.
ReadOnlyStyledDocumentBuilder<PS,SEG,S>	Helper class via ReadOnlyStyledDocumentBuilder.constructDocument(SegmentOps, Object, Consumer) or one of its constructors and ReadOnlyStyledDocumentBuilder.build() for easily creating a ReadOnlyStyledDocument from a list of Paragraphs that is constructed via "addParagraph(s)" methods.
Replacement<PS,SEG,S>	Encapsulates the all the arguments for EditableStyledDocument.replace(int, int, StyledDocument).
RichTextChange<PS,SEG,S>	An object that specifies where a change occurred in a GenericStyledArea.
SegmentOpsBase<SEG,S>	Provides a base for properly implementing the SegmentOps interface and reduces boilerplate, so that a developer only needs to implement methods for real segments, not empty ones.
SimpleEditableStyledDocument<PS,S>	Provides an implementation of EditableStyledDocument that specifies its segment type as String.
StyledSegment<SEG,S>	Essentially, an immutable Tuple2 that combines a segment object and a style object together.
StyleSpan<S>	Essentially, a Tuple2 of a given style StyleSpan that spans a given length.
StyleSpansBuilder<S>	A one-time-use builder that Builds a memory efficient StyleSpans object.
TextChange<S,Self extends TextChange<S,Self>>	Base change class for style changes (RichTextChange) and non-style changes (PlainTextChange) in a TextEditingArea.
TextOpsBase<SEG,S>	Base class for a TextOps implementation that uses a text-based segment
TwoLevelNavigator	Default implementation of TwoDimensional that makes it trivial to calculate a position within a two dimensional object.

Enum Summary

Enum	Description
TwoDimensional.Bias	Determines whether to add 1 when the end of an inner list is reached