- Description
- Nested Class Summary
- Property Summary
- Constructor Summary
- Method Summary
- Property Details
- Constructor Details
- Method Details
- isWritable()
- size()
- getPlainText(int)
- getParagraph(int)
- removeRange(TextPos, TextPos)
- insertTextSegment(int, int, String, StyleAttributeMap)
- insertLineBreak(int, int)
- insertParagraph(int, Supplier)
- setParagraphStyle(int, StyleAttributeMap)
- applyStyle(int, int, int, StyleAttributeMap, boolean)
- getStyleAttributeMap(StyleResolver, TextPos)
- getSupportedAttributes()
- addListener(StyledTextModel.Listener)
- removeListener(StyledTextModel.Listener)
- registerDataFormatHandler(DataFormatHandler, boolean, boolean, int)
- removeDataFormatHandler(DataFormat, boolean, boolean)
- getSupportedDataFormats(boolean)
- getDataFormatHandler(DataFormat, boolean)
- fireChangeEvent(TextPos, TextPos, int, int, int)
- fireStyleChangeEvent(TextPos, TextPos)
- getParagraphLength(int)
- export(TextPos, TextPos, StyledOutput)
- exportParagraph(int, int, int, boolean, StyledOutput)
- getMarker(TextPos)
- clamp(TextPos)
- getDocumentEnd()
- getEndOfParagraphTextPos(int)
- replace(StyleResolver, TextPos, TextPos, String, boolean)
- replace(StyleResolver, TextPos, TextPos, StyledInput, boolean)
- applyStyle(TextPos, TextPos, StyleAttributeMap, boolean)
- clearUndoRedo()
- undo(StyleResolver)
- redo(StyleResolver)
- undoableProperty()
- isUndoable()
- redoableProperty()
- isRedoable()
- read(StyleResolver, DataFormat, InputStream)
- write(StyleResolver, DataFormat, OutputStream)
Class StyledTextModel
- Direct Known Subclasses:
BasicTextModel
,RichTextModel
,StyledTextModelViewOnlyBase
RichTextArea
.
This class handles the following functionality with the intent to simplify custom models:
- managing listeners
- firing events
- decomposing the edits into multiple operations performed on individual paragraphs
- managing
Marker
s
Editing 
The model supports editing when isWritable()
returns true
.
Three methods participate in modification of the content:
replace(StyleResolver, TextPos, TextPos, String, boolean)
,
replace(StyleResolver, TextPos, TextPos, StyledInput, boolean)
,
applyStyle(TextPos, TextPos, StyleAttributeMap, boolean)
.
These methods decompose the main modification into operations with individual paragraphs
and delegate these to subclasses.
At the end of this process, an event is sent to all the StyledTextModel.Listener
s, followed by the
skin requesting the updated paragraphs when required.
Creating a Paragraph 
The model presents its content to the view(s) via immutable RichParagraph
.
There are two ways of adding styles to the model:
- Using the style names in the stylesheet or inline styles (example:
"-fx-font-size:200%;"
), or - Using attributes defined in
StyleAttributeMap
, such as bold typeface, italic, and so on. In this case, the resulting paragraph appearance is decoupled from the stylesheet and will look the same regardless of the active stylesheet.
Extending the Model 
The subclasses are free to choose how the data is stored, the only limitation is that the model neither
stores nor caches any Node
s, since multiple skins might be attached to the same
model. When required, the model may contain properties which can be bound to the Nodes created in
getParagraph(int)
. It is the responsibility of the model to store and restore the values
of such properties.- Since:
- 24
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
Receives information about modifications of the model. -
Property Summary
PropertiesTypePropertyDescriptionfinal ReadOnlyBooleanProperty
The property describes if it's currently possible to redo the latest change of the content that was undone.final ReadOnlyBooleanProperty
The property describes if it's currently possible to undo the latest change of the content that was done. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionfinal void
addListener
(StyledTextModel.Listener listener) Adds aStyledTextModel.Listener
to this model.protected abstract void
applyStyle
(int index, int start, int end, StyleAttributeMap a, boolean merge) Applies style to the specified text range within a single paragraph.final void
applyStyle
(TextPos start, TextPos end, StyleAttributeMap attrs, boolean mergeAttributes) Applies the style attributes to the specified range in the document.final TextPos
Returns the text position guaranteed to be within the document and paragraph limits.final void
Clears the undo-redo stack.final void
export
(TextPos start, TextPos end, StyledOutput out) Exports the stream ofStyledSegment
s in the given range to the specifiedStyledOutput
.protected final void
exportParagraph
(int index, int start, int end, boolean withParAttrs, StyledOutput out) Exports part of the paragraph as a sequence of styled segments.void
fireChangeEvent
(TextPos start, TextPos end, int charsTop, int linesAdded, int charsBottom) Fires a text modification event for the given range.void
fireStyleChangeEvent
(TextPos start, TextPos end) Fires a style change event for the given range.final DataFormatHandler
getDataFormatHandler
(DataFormat format, boolean forExport) Returns aDataFormatHandler
instance corresponding to the givenDataFormat
.final TextPos
Returns the text position corresponding to the end of the document.final TextPos
getEndOfParagraphTextPos
(int index) Returns a TextPos corresponding to the end of paragraph at the given index.final Marker
Returns theMarker
at the specified position.abstract RichParagraph
getParagraph
(int index) Returns aRichParagraph
at the given model index.int
getParagraphLength
(int index) Returns the length of text in a paragraph at the specified index.abstract String
getPlainText
(int index) Returns the plain text string for the specified paragraph.abstract StyleAttributeMap
getStyleAttributeMap
(StyleResolver resolver, TextPos pos) Returns theStyleAttributeMap
of the character at the specified position'scharIndex
.protected Set
<StyleAttribute<?>> Returns the set of attributes supported attributes.final List
<DataFormat> getSupportedDataFormats
(boolean forExport) Returns an immutable list of supported data formats for either export or import operations, in the order of priority - from high to low.protected abstract void
insertLineBreak
(int index, int offset) Inserts a line break at the specified position.protected abstract void
insertParagraph
(int index, Supplier<Region> generator) Inserts a paragraph that contains a singleRegion
.protected abstract int
insertTextSegment
(int index, int offset, String text, StyleAttributeMap attrs) This method is called to insert a single styled text segment at the given position.final boolean
Gets the value of theredoable
property.final boolean
Gets the value of theundoable
property.abstract boolean
Indicates whether the model supports content modifications made viaapplyStyle()
,replace()
,undo()
,redo()
methods.final void
read
(StyleResolver r, DataFormat f, InputStream input) Replaces the content of the model with the data read from the input stream, using the specifiedDataFormat
.final TextPos[]
redo
(StyleResolver resolver) Redoes the recent change, if possible, returning an array comprising [start, end] text positions prior to the change.final ReadOnlyBooleanProperty
The property describes if it's currently possible to redo the latest change of the content that was undone.protected final void
registerDataFormatHandler
(DataFormatHandler h, boolean forExport, boolean forImport, int priority) Registers a format handler for export and/or import operations.protected final void
removeDataFormatHandler
(DataFormat f, boolean forExport, boolean forImport) Removes the data format handler registered previously withregisterDataFormatHandler(DataFormatHandler, boolean, boolean, int)
.final void
removeListener
(StyledTextModel.Listener listener) Removes aStyledTextModel.Listener
from this model.protected abstract void
removeRange
(TextPos start, TextPos end) Removes the specified text range.final TextPos
replace
(StyleResolver resolver, TextPos start, TextPos end, String text, boolean allowUndo) Replaces the given range with the provided plain text.final TextPos
replace
(StyleResolver resolver, TextPos start, TextPos end, StyledInput input, boolean allowUndo) Replaces the given range with the provided styled text input.protected abstract void
setParagraphStyle
(int index, StyleAttributeMap paragraphAttrs) Replaces the paragraph styles in the specified paragraph.abstract int
size()
Returns the number of paragraphs in the model.final TextPos[]
undo
(StyleResolver resolver) Undoes the recent change, if possible, returning an array comprising [start, end] text positions prior to the change.final ReadOnlyBooleanProperty
The property describes if it's currently possible to undo the latest change of the content that was done.final void
write
(StyleResolver r, DataFormat f, OutputStream out) Writes the model content to the output stream using the specifiedDataFormat
.
-
Property Details
-
Constructor Details
-
Method Details
-
isWritable
public abstract boolean isWritable()Indicates whether the model supports content modifications made viaapplyStyle()
,replace()
,undo()
,redo()
methods.Note that even when this method returns
false
, the model itself may still update its content and fire the change events as a response, for example, to changes in its backing data storage.- Returns:
- true if the model supports content modifications
-
size
public abstract int size()Returns the number of paragraphs in the model.- Returns:
- number of paragraphs
-
getPlainText
Returns the plain text string for the specified paragraph. The returned text string cannot be null and must not contain any control characters other than TAB. The callers must ensure that the value ofindex
is within the valid document range, since doing otherwise might result in an exception or undetermined behavior.- Parameters:
index
- the paragraph index in the range (0...size()
)- Returns:
- the non-null paragraph text string
-
getParagraph
Returns aRichParagraph
at the given model index. The callers must ensure that the value ofindex
is within the valid document range, since doing otherwise might result in an exception or undetermined behavior.This method makes no guarantees that the same paragraph instance will be returned for the same model index.
- Parameters:
index
- the paragraph index in the range (0...size()
)- Returns:
- the instance of
RichParagraph
-
removeRange
Removes the specified text range. This method gets called only if the model is editable. The caller guarantees thatstart
precedesend
.- Parameters:
start
- the start of the range to be removedend
- the end of the range to be removed, expected to be greater than the start position- Throws:
UnsupportedOperationException
- if the model is notwritable
-
insertTextSegment
protected abstract int insertTextSegment(int index, int offset, String text, StyleAttributeMap attrs) This method is called to insert a single styled text segment at the given position.- Parameters:
index
- the paragraph indexoffset
- the insertion offset within the paragraphtext
- the text to insertattrs
- the style attributes- Returns:
- the number of characters inserted
- Throws:
UnsupportedOperationException
- if the model is notwritable
-
insertLineBreak
protected abstract void insertLineBreak(int index, int offset) Inserts a line break at the specified position.- Parameters:
index
- the model indexoffset
- the text offset- Throws:
UnsupportedOperationException
- if the model is notwritable
-
insertParagraph
Inserts a paragraph that contains a singleRegion
.The model should not cache or otherwise retain references to the created
Region
s, as they might be requested multiple times during the lifetime of the model, or by different views.This method allows for embedding
Control
s that handle user input. In this case, the model should declare necessary properties and provide bidirectional bindings between the properties in the model and the corresponding properties in the control, as well as handle copy, paste, writing to and reading from I/O streams.- Parameters:
index
- model indexgenerator
- code that will be used to create a Node instance- Throws:
UnsupportedOperationException
- if the model is notwritable
-
setParagraphStyle
Replaces the paragraph styles in the specified paragraph.- Parameters:
index
- the paragraph indexparagraphAttrs
- the paragraph attributes- Throws:
UnsupportedOperationException
- if the model is notwritable
-
applyStyle
protected abstract void applyStyle(int index, int start, int end, StyleAttributeMap a, boolean merge) Applies style to the specified text range within a single paragraph. The new attributes override any existing attributes. Theend
argument may exceed the paragraph length, in which case the outcome should be the same as supplying the paragraph length value.- Parameters:
index
- the paragraph indexstart
- the start offsetend
- the end offseta
- the character attributesmerge
- determines whether to merge with or overwrite the existing attributes- Throws:
UnsupportedOperationException
- if the model is notwritable
-
getStyleAttributeMap
Returns theStyleAttributeMap
of the character at the specified position'scharIndex
. When at the end of the document, returns the attributes of the last character.- Parameters:
resolver
- the style resolverpos
- the text position- Returns:
- the style attributes, non-null
-
getSupportedAttributes
Returns the set of attributes supported attributes. When this method returns a non-null set, it will be used by the methods which handle the external input for the purpose of filtering out the attributes the model cannot understand, preventing the attributes from being added to the model (for example, as a result of pasting from the system clipboard).The methods that utilize the filtering are:
applyStyle(TextPos, TextPos, StyleAttributeMap, boolean)
,replace(StyleResolver, TextPos, TextPos, StyledInput, boolean)
, andreplace(StyleResolver, TextPos, TextPos, String, boolean)
.When this method returns
null
, no filtering is performed.This method might be overridden by certain models. The base class implementation returns
null
.- Returns:
- the set of supported attributes, or null if the model requires no filtering
-
addListener
Adds aStyledTextModel.Listener
to this model.- Parameters:
listener
- a non-null listener
-
removeListener
Removes aStyledTextModel.Listener
from this model.This method does nothing if this listener has never been added.
- Parameters:
listener
- a non-null listener
-
registerDataFormatHandler
protected final void registerDataFormatHandler(DataFormatHandler h, boolean forExport, boolean forImport, int priority) Registers a format handler for export and/or import operations. The priority determines the format chosen for operations with theClipboard
when input data is available in more than one supported format. The handler with the highest priority will be used byRichTextArea.read(InputStream)
andRichTextArea.write(OutputStream)
methods.The same handler can be registered for input and export. When registering multiple handlers for the same data handler and import/export, the last registered one wins.
This method is expected to be called from a
StyledTextModel
child class constructor.- Parameters:
h
- data format handlerforExport
- true if the handler supports export operationsforImport
- true if the handler supports import operationspriority
- from 0 (lowest, usually plain text) toInteger.MAX_VALUE
-
removeDataFormatHandler
Removes the data format handler registered previously withregisterDataFormatHandler(DataFormatHandler, boolean, boolean, int)
.- Parameters:
f
- the data formatforExport
- whether to remove the export handlerforImport
- whether to remove the import handler
-
getSupportedDataFormats
Returns an immutable list of supported data formats for either export or import operations, in the order of priority - from high to low.The top priority format will be used by
RichTextArea.read(InputStream)
andRichTextArea.write(OutputStream)
methods.- Parameters:
forExport
- determines whether the operation is export (true) or import (false)- Returns:
- the immutable list of supported formats
-
getDataFormatHandler
Returns aDataFormatHandler
instance corresponding to the givenDataFormat
. This method will returnnull
if the data format is not supported.- Parameters:
format
- data formatforExport
- for export (true) or for input (false)- Returns:
- DataFormatHandler or null
-
fireChangeEvent
public void fireChangeEvent(TextPos start, TextPos end, int charsTop, int linesAdded, int charsBottom) Fires a text modification event for the given range.- Parameters:
start
- start of the affected rangeend
- end of the affected rangecharsTop
- number of characters added before any added paragraphslinesAdded
- number of paragraphs insertedcharsBottom
- number of characters added after any inserted paragraphs
-
fireStyleChangeEvent
Fires a style change event for the given range. This event indicates that only the styling has changed, with no changes to any text positions.- Parameters:
start
- the start positionend
- the end position, must be greater than the start position
-
getParagraphLength
public int getParagraphLength(int index) Returns the length of text in a paragraph at the specified index.- Parameters:
index
- the paragraph index- Returns:
- the length
-
export
Exports the stream ofStyledSegment
s in the given range to the specifiedStyledOutput
. This method does not close theStyledOutput
.- Parameters:
start
- start of the rangeend
- end of the rangeout
-StyledOutput
to receive the stream- Throws:
IOException
- when an I/O error occurs- See Also:
-
exportParagraph
protected final void exportParagraph(int index, int start, int end, boolean withParAttrs, StyledOutput out) throws IOException Exports part of the paragraph as a sequence of styled segments. The caller guarantees that the start position precedes the end. The subclass may override this method to provide a more performant implementation. The paragraph end argument may exceed the actual length of the paragraph, in which case it should be treated as equal to the paragraph text length.- Parameters:
index
- the paragraph index in the modelstart
- the start offsetend
- the end offset (may exceed the paragraph length)withParAttrs
- determines whether to emit paragraph attributesout
- the target StyledOutput- Throws:
IOException
- when an I/O error occurs
-
getMarker
-
clamp
-
getDocumentEnd
Returns the text position corresponding to the end of the document. The start of the document can be referenced by theTextPos.ZERO
constant.- Returns:
- the text position
- See Also:
-
getEndOfParagraphTextPos
Returns a TextPos corresponding to the end of paragraph at the given index.- Parameters:
index
- the paragraph index- Returns:
- the text position
-
replace
public final TextPos replace(StyleResolver resolver, TextPos start, TextPos end, String text, boolean allowUndo) Replaces the given range with the provided plain text.This is a convenience method which eventually calls
replace(StyleResolver, TextPos, TextPos, StyledInput, boolean)
with the attributes provided bygetStyleAttributeMap(StyleResolver, TextPos)
at thestart
position.- Parameters:
resolver
- the StyleResolver to usestart
- start text positionend
- end text positiontext
- text string to insertallowUndo
- when true, creates an undo-redo entry- Returns:
- the text position at the end of the inserted text, or null if the model is read only
- Throws:
UnsupportedOperationException
- if the model is notwritable
-
replace
public final TextPos replace(StyleResolver resolver, TextPos start, TextPos end, StyledInput input, boolean allowUndo) Replaces the given range with the provided styled text input. When inserting plain text, the style is taken from the preceding text segment, or, if the text is being inserted in the beginning of the document, the style is taken from the following text segment.After the model applies the requested changes, an event is sent to all the registered listeners.
- Parameters:
resolver
- the StyleResolver to use, can be nullstart
- the start text positionend
- the end text positioninput
- the input content streamallowUndo
- when true, creates an undo-redo entry- Returns:
- the text position at the end of the inserted text, or null if the model is read only
- Throws:
UnsupportedOperationException
- if the model is notwritable
-
applyStyle
public final void applyStyle(TextPos start, TextPos end, StyleAttributeMap attrs, boolean mergeAttributes) Applies the style attributes to the specified range in the document.Depending on
mergeAttributes
parameter, the attributes will either be merged with (true) or completely replace the existing attributes within the range. The affected range might be wider than the range specified when applying the paragraph attributes.This operation is undoable.
- Parameters:
start
- the start of text rangeend
- the end of text rangeattrs
- the style attributes to setmergeAttributes
- whether to merge or replace the attributes- Throws:
UnsupportedOperationException
- if the model is notwritable
-
clearUndoRedo
public final void clearUndoRedo()Clears the undo-redo stack. -
undo
Undoes the recent change, if possible, returning an array comprising [start, end] text positions prior to the change. Returns null when the undo operation is not possible.- Parameters:
resolver
- the StyleResolver to use- Returns:
- the [start, end] text positions prior to the change
- Throws:
UnsupportedOperationException
- if the model is notwritable
-
redo
Redoes the recent change, if possible, returning an array comprising [start, end] text positions prior to the change. Returns null when the redo operation is not possible.- Parameters:
resolver
- the StyleResolver to use- Returns:
- the [start, end] text positions prior to the change
- Throws:
UnsupportedOperationException
- if the model is notwritable
-
undoableProperty
The property describes if it's currently possible to undo the latest change of the content that was done.- Default value:
- false
- Returns:
- the read-only property
- See Also:
-
isUndoable
public final boolean isUndoable()Gets the value of theundoable
property.- Property description:
- The property describes if it's currently possible to undo the latest change of the content that was done.
- Default value:
- false
- Returns:
- the value of the
undoable
property - See Also:
-
redoableProperty
The property describes if it's currently possible to redo the latest change of the content that was undone.- Default value:
- false
- Returns:
- the read-only property
- See Also:
-
isRedoable
public final boolean isRedoable()Gets the value of theredoable
property.- Property description:
- The property describes if it's currently possible to redo the latest change of the content that was undone.
- Default value:
- false
- Returns:
- the value of the
redoable
property - See Also:
-
read
Replaces the content of the model with the data read from the input stream, using the specifiedDataFormat
. This operation clears the undo/redo stack.- Parameters:
r
- the style resolverf
- the data formatinput
- the input stream- Throws:
IOException
- in case of an I/O errorUnsupportedOperationException
- when the data format is not supported by the model, or the model is notwritable
-
write
Writes the model content to the output stream using the specifiedDataFormat
.- Parameters:
r
- the style resolverf
- the data formatout
- the output stream- Throws:
IOException
- in case of an I/O errorUnsupportedOperationException
- when the data format is not supported by the model
-