JavaFX 27 · jfx.incubator.scene.control.richtext.RichTextArea

The RichTextArea control is designed for visualizing and editing rich text that can be styled in a variety of ways.

The RichTextArea control has a number of features, including:

paragraph-oriented model, up to ~2 billion rows
virtualized text cell flow
support for text styling with an application stylesheet or inline attributes
support for multiple views connected to the same model
single selection
input map which allows for easy behavior customization and extension

Creating a RichTextArea

The following example creates an editable control with the default RichTextModel:

RichTextArea textArea = new RichTextArea();

The methods appendText(), insertText(), replaceText(), applyStyle(), setStyle(), or clear() can be used to modify text programmatically:

// create styles
  StyleAttributeMap heading = StyleAttributeMap.builder().setBold(true).setUnderline(true).setFontSize(18).build();
  StyleAttributeMap mono = StyleAttributeMap.builder().setFontFamily("Monospaced").build();

  RichTextArea textArea = new RichTextArea();
  // build the content
  textArea.setUndoRedoEnabled(false);
  textArea.appendText("RichTextArea\n", heading);
  textArea.appendText("Example:\nText is ", StyleAttributeMap.EMPTY);
  textArea.appendText("monospaced.\n", mono);
  textArea.setUndoRedoEnabled(true);

Which results in the following visual representation:

Image of the RichTextArea control

A view-only information control requires a different model. The following example illustrates how to create a model that uses a stylesheet for styling:

SimpleViewOnlyStyledModel m = new SimpleViewOnlyStyledModel();
    // add text segment using CSS style name (requires a stylesheet)
    m.addWithStyleNames("RichTextArea ", "HEADER");
    // add text segment using inline styles
    m.addWithInlineStyle("Demo", "-fx-font-size:200%; -fx-font-weight:bold;");
    // add newline
    m.nl();

    RichTextArea textArea = new RichTextArea(m);

Text Models

A number of standard models can be used with RichTextArea, each addressing a specific use case:

Standard Models
Model Class	Description
`StyledTextModel`	Base class (abstract)
├─ `RichTextModel`	Default model for RichTextArea
├─ `BasicTextModel`	Unstyled text model
│ └─ `CodeTextModel`	Default model for CodeArea
└─ `StyledTextModelViewOnlyBase`	Base class for a view-only model (abstract)
└─ `SimpleViewOnlyStyledModel`	In-memory view-only styled model

Selection

The RichTextArea control maintains a single contiguous selection segment as a part of the SelectionModel. Additionally, anchorPositionProperty() and caretPositionProperty() read-only properties are derived from the selectionProperty() for convenience.

Customizing

The RichTextArea control offers some degree of customization that does not require subclassing:

customizing key bindings with the InputMap
setting leftDecorator and rightDecorator properties

Modifier and Type	Class and Description
private static class	RichTextArea.StyleableProperties Defines styleable properties at the class level
public static class	RichTextArea.Tag Function tags serve as identifiers of methods that can be customized via the `InputMap`.

Modifier and Type	Field and Description
private RTAccessibilityHelper	accessibilityHelper
private SimpleStyleableObjectProperty<Duration>	caretBlinkPeriod
private SimpleStyleableObjectProperty<Insets>	contentPadding
private StyleableBooleanProperty	displayCaret
private ReadOnlyObjectWrapper<Bounds>	documentArea
private ReadOnlyObjectWrapper<TextPos>	dropTarget
private SimpleBooleanProperty	editableProperty
private StyleableBooleanProperty	highlightCurrentParagraph
private final InputMap	inputMap
private SimpleObjectProperty<StyleAttributeMap>	insertStyles
private SimpleObjectProperty<SideDecorator>	leftDecorator
private SimpleObjectProperty<StyledTextModel>	model
private ReadOnlyBooleanWrapper	redoable
private SimpleObjectProperty<SideDecorator>	rightDecorator
private final SelectionModel	selectionModel
protected static final StyleHandlerRegistry	styleHandlerRegistry The style handler registry instance, made available for use by subclasses to add support for new style attributes.
private ReadOnlyBooleanWrapper	undoable
private StyleableBooleanProperty	useContentHeight
private StyleableBooleanProperty	useContentWidth
private StyleableBooleanProperty	wrapText

Access	Constructor and Description
public	RichTextArea() Creates the instance with the in-memory model `RichTextModel`.
public	RichTextArea(StyledTextModel the model model) Creates the instance using the specified model.

Method Summary

Modifier and Type	Method and Description
private RTAccessibilityHelper	accessibilityHelper()
public final ReadOnlyProperty<TextPos>	Returns: the anchor position property anchorPositionProperty() Tracks the selection anchor position within the document.
public final TextPos	Returns: the text position at the end of the appended text, or null if editing is disabled appendText(String the text to append text, StyleAttributeMap the style attributes attrs) Appends the styled text to the end of the document.
public final TextPos	Returns: the text position at the end of the appended text, or null if editing is disabled appendText(String the text to append text) Appends the styled text to the end of the document.
public final TextPos	Returns: the text position at the end of the appended text, or null if editing is disabled appendText(StyledInput the input stream in) Appends the styled content to the end of the document.
public void	applyStyle(TextPos the start of text range start, TextPos the end of text range end, StyleAttributeMap the style attributes to apply attrs) Applies the specified style to the selected range.
public void	backspace() When selection exists, deletes selected text.
private DataFormat	bestDataFormat(boolean forExport)
public final ObjectProperty<Duration>	Returns: the caret blink period property caretBlinkPeriodProperty() Determines the caret blink period.
public final ReadOnlyProperty<TextPos>	Returns: the caret position property caretPositionProperty() Tracks the caret position within the document.
public final void	clear() Clears the document.
public final void	clearDropTarget() Sets the value of the `dropTarget` property to `null`.
public final void	clearSelection() Clears existing selection, if any.
public final void	clearUndoRedo() Clears the undo-redo stack of the underlying model.
public final ObjectProperty<Insets>	Returns: the content padding property contentPaddingProperty() Specifies the padding for the RichTextArea content.
public void	copy() When selection exists, copies the selected rich text to the clipboard in all the formats supported by the model.
public final void	copy(DataFormat the data format to use format) Copies the selected text in the specified format to the clipboard.
protected RichTextAreaSkin	createDefaultSkin() Overrides javafx.scene.control.Control.createDefaultSkin. Create a new instance of the default skin for this control.
public void	cut() Transfers the currently selected text to the clipboard, removing the current selection.
public void	delete() When selection exists, deletes selected text.
public void	deleteParagraph() When selection exists, deletes selected paragraphs.
public void	deleteParagraphStart() Deletes text from the caret position to the start of the paragraph, ignoring existing selection.
public void	deleteWordNextEnd() Deletes from the caret positon to the end of next word, ignoring existing selection.
public void	deleteWordNextStart() Deletes from the caret positon to the start of next word, ignoring existing selection.
public void	deleteWordPrevious() Deletes (multiple) empty paragraphs or text from the caret position to the start of the previous word, ignoring existing selection.
public void	deselect() Clears the selected text range by moving anchor to the caret position.
public final BooleanProperty	Returns: the display caret property displayCaretProperty() This property controls whether caret will be displayed or not.
public final ReadOnlyObjectProperty<Bounds>	Returns: the document area documentAreaProperty() Provides the bounds to the document area in local coordinates.
private final ReadOnlyObjectWrapper<Bounds>	documentAreaPropertyImpl()
private ReadOnlyObjectWrapper<TextPos>	dropTarget()
public final ReadOnlyProperty<TextPos>	Returns: the drop target property dropTargetProperty() This property indicates the target text position during drag-and-drop operations.
public final BooleanProperty	Returns: the editable property editableProperty() Indicates whether this RichTextArea can be edited by the user, provided the model is also writable.
public void	errorFeedback() Provides audio and/or visual error feedback.
public final void	execute(FunctionTag the function tag tag) Executes a function mapped to the specified function tag.
public void	executeAccessibleAction(AccessibleAction action, Object... parameters) Overrides javafx.scene.control.Control.executeAccessibleAction. This method is called by the assistive technology to request the action indicated by the argument should be executed.
public final void	executeDefault(FunctionTag the function tag tag) Executes the default function mapped to the specified tag.
public final void	extendSelection(TextPos the text position pos) Extends selection to the specified position.
public final StyleAttributeMap	Returns: the non-null `StyleAttributeMap` instance getActiveStyleAttributeMap() Returns `StyleAttributeMap` which contains character and paragraph attributes.
public final TextPos	getAnchorPosition()
public final Duration	getCaretBlinkPeriod()
public final TextPos	getCaretPosition()
public static List<CssMetaData<? extends Styleable, ?>>	Returns: the `CssMetaData` getClassCssMetaData() Hides javafx.scene.control.Control.getClassCssMetaData. Gets the `CssMetaData` associated with this class, which may include the `CssMetaData` of its superclasses.
public final Insets	getContentPadding()
public List<CssMetaData<? extends Styleable, ?>>	getControlCssMetaData() Overrides javafx.scene.control.Control.getControlCssMetaData. Gets the unmodifiable list of the control's CSS-styleable properties.
public final Bounds	getDocumentArea()
public final TextPos	Returns: the text position getDocumentEnd() Returns a TextPos corresponding to the end of the document.
public final TextPos	getDropTarget()
public final InputMap	Returns: the input map instance getInputMap() Returns the input map instance.
public final StyleAttributeMap	getInsertStyles()
public final SideDecorator	getLeftDecorator()
public final LineEnding	Returns: the model's line ending value getLineEnding() Convenience method which delegates to `StyledTextModel#getLineEnding()`.
public final StyledTextModel	getModel()
private StyleAttributeMap	getModelStyleAttrs(StyleResolver r, TextPos pos, boolean forInsert)
public final int	Returns: the paragraph count getParagraphCount() Returns the number of paragraphs in the model.
public final TextPos	Returns: text position getParagraphEnd(int paragraph index index) Returns a TextPos corresponding to the end of paragraph.
public final String	Returns: the non-null plain text string getPlainText(int the paragraph index index) Returns the plain text at the specified paragraph index.
public final SideDecorator	getRightDecorator()
public final SelectionSegment	getSelection()
public final StyleAttributeMap	Returns: the style attributes, never null getStyleAttributeMap(TextPos the text position pos, boolean whether to pick preceding style at the segment boundary forInsert) Returns the `StyleAttributeMap` of the character at the specified position's `charIndex`.
public StyleHandlerRegistry	Returns: the style handler registry getStyleHandlerRegistry() Returns the style handler registry for this control.
private final boolean	Returns: `true` if all the text fit in the buffer getText(TextPos the start position start, TextPos the end position end, StringBuilder the buffer to copy to sb, int the maximum number of characters to copy, must be >= 0 limit) Copies the plain text between `start` and `end` positions to the provided buffer.
public final TextPos	Returns: the text position, or null getTextPosition(double the screen x coordinate screenX, double the screen y coordinate screenY) Finds a text position corresponding to the specified screen coordinates.
public final boolean	Returns: true when an non-empty selection exists hasNonEmptySelection() This convenience method returns true when a non-empty selection exists.
public final BooleanProperty	Returns: the highlight current paragraph property highlightCurrentParagraphProperty() Indicates whether the current paragraph will be visually highlighted.
private static StyleHandlerRegistry	initStyleHandlerRegistry()
public void	insertLineBreak() Inserts a line break at the caret.
public final ObjectProperty<StyleAttributeMap>	Returns: the insert styles property insertStylesProperty() Specifies the styles to be in effect for the characters to be inserted via user input.
public void	insertTab() Inserts a tab symbol at the caret.
public final TextPos	Returns: the text position at the end of the appended text, or null if editing is disabled insertText(TextPos the insert position pos, String the text to inser text, StyleAttributeMap the style attributes attrs) Inserts the styled text at the specified position.
public final TextPos	Returns: the text position at the end of the appended text, or null if editing is disabled insertText(TextPos the insert position pos, StyledInput the input stream in) Inserts the styled content at the specified position.
public final boolean	isDisplayCaret()
public final boolean	isEditable()
public final boolean	isHighlightCurrentParagraph()
public final boolean	isRedoable()
public final boolean	isUndoable()
public final boolean	Returns: true if undo/redo functionality is enabled in the model isUndoRedoEnabled() Indicates whether undo/redo functionality is enabled in the model.
public final boolean	isUseContentHeight()
public final boolean	isUseContentWidth()
public final boolean	isWrapText()
public final ObjectProperty<SideDecorator>	Returns: the left decorator property leftDecoratorProperty() Specifies the left-side paragraph decorator.
public final ObjectProperty<StyledTextModel>	Returns: the model property modelProperty() Determines the `StyledTextModel` to use with this RichTextArea.
public void	moveDocumentEnd() Moves the caret to after the last character of the text, clearing an existing selection.
public void	moveDocumentStart() Moves the caret to before the first character of the text, clearing an existing selection.
public void	moveDown() Moves the caret one visual line down, clearing an existing selection.
public void	moveLeft() Moves the caret left, clearing an existing selection range.
public void	moveLineEnd() Moves the caret to the end of the visual text line at caret, clearing an existing selection.
public void	moveLineStart() Moves the caret to the start of the visual text line at caret, clearing an existing selection.
public void	moveParagraphDown() Moves the caret to the end of the current paragraph, or, if already there, to the end of the next paragraph.
public void	moveParagraphEnd() Moves the caret to the end of the paragraph at caret, clearing an existing selection.
public void	moveParagraphStart() Moves the caret to the start of the current paragraph, clearing an existing selection.
public void	moveParagraphUp() Moves the caret to the start of the current paragraph, or, if already there, to the start of the previous paragraph.
public void	moveRight() Moves the caret to the next symbol, clearing an existing selection.
public void	moveUp() Moves the caret one visual line up, clearing an existing selection.
public void	moveWordLeft() Moves the caret to the beginning of previous word in a left-to-right setting (or the beginning of the next word in a right-to-left setting), clearing an existing selection.
public void	moveWordNextEnd() Moves the caret to the end of the next word, clearing an existing selection.
public void	moveWordNextStart() Moves the caret to the start of next word, clearing an existing selection.
public void	moveWordPrevious() Moves the caret to the beginning of previous word, clearing an existing selection.
public void	moveWordRight() Moves the caret to the beginning of next word in a left-to-right setting (or the beginning of the previous word in a right-to-left setting), clearing an existing selection.
public void	pageDown() Move caret one visual page down, clearing an existing selection.
public void	pageUp() Move caret one visual page up, clearing an existing selection.
public void	paste() Pastes the clipboard content at the caret, or, if selection exists, replacing the selected text.
public void	paste(DataFormat the data format to use format) Pastes the clipboard content at the caret, or, if selection exists, replacing the selected text.
public final void	pastePlainText() Pastes the plain text clipboard content at the caret, or, if selection exists, replacing the selected text.
public Object	queryAccessibleAttribute(AccessibleAttribute attribute, Object... parameters) Overrides javafx.scene.control.Control.queryAccessibleAttribute. This method is called by the assistive technology to request the value for an attribute.
public final void	read(DataFormat the data format f, InputStream the input stream in) Calls the model to replace the current document with the content read from the stream using the specified `DataFormat`.
public final void	read(InputStream the input stream in) Calls the model to replace the current document with the content read from the input stream.
public void	redo() If possible, redoes the last undone modification.
public final ReadOnlyBooleanProperty	Returns: the read-only property redoableProperty() The property describes if it's currently possible to redo the latest change of the content that was undone.
public final TextPos	Returns: the new caret position at the end of inserted text, or null if the change cannot be made replaceText(TextPos the start text position start, TextPos the end text position end, String the input text text) Replaces the specified range with the new text.
public final TextPos	Returns: the new caret position at the end of inserted text, or null if the change cannot be made replaceText(TextPos the start text position start, TextPos the end text position end, StyledInput the input stream in) Replaces the specified range with the new input.
private StyleResolver	resolver()
private RichTextAreaSkin	richTextAreaSkin()
public final ObjectProperty<SideDecorator>	Returns: the right decorator property rightDecoratorProperty() Specifies the right-side paragraph decorator.
public final void	select(TextPos the text position pos) Moves both the caret and the anchor to the specified position, clearing any existing selection.
public final void	select(TextPos the new selection anchor position anchor, TextPos the new caret position caret) Selects the specified range and places the caret at the new position.
public void	selectAll() Selects all the text in the document: the anchor is set at the document start, while the caret is positioned at the end of the document.
public void	selectDown() Extends selection one visual text line down.
public final ReadOnlyProperty<SelectionSegment>	Returns: the selection property selectionProperty() Tracks the current selection.
public void	selectLeft() Extends selection one symbol to the left.
public void	selectPageDown() Extends selection one visible page down.
public void	selectPageUp() Extends selection one visible page up.
public void	selectParagraph() Selects the current paragraph.
public void	selectParagraphDown() Extends selection to the end of the current paragraph, or, if already at the end, to the end of the next paragraph.
public void	selectParagraphEnd() Selects from the current position to the paragraph end.
public void	selectParagraphStart() Selects from the current position to the paragraph start.
public void	selectParagraphUp() Extends selection to the start of the current paragraph, or, if already at the start, to the start of the previous paragraph.
public void	selectRight() Extends selection one symbol (or grapheme cluster) to the right.
public void	selectToDocumentEnd() Extends selection to the end of the document.
public void	selectToDocumentStart() Extends selection to the start of the document.
public void	selectToLineEnd() Extends selection to the end of the visual text line at caret.
public void	selectToLineStart() Extends selection to the start of the visual text line at caret.
public void	selectUp() Extends selection one visual text line up.
public void	selectWord() Selects a word at the caret position.
public void	selectWordLeft() Moves the caret to the beginning of previous word in a left-to-right setting, or to the beginning of the next word in a right-to-left setting.
public void	selectWordNextEnd() Extends selection to the end of the next word.
public void	selectWordNextStart() Moves the caret to the start of the next word.
public void	selectWordPrevious() Moves the caret to the beginning of previous word.
public void	selectWordRight() Moves the caret to the beginning of next word in a left-to-right setting, or to the beginning of the previous word in a right-to-left setting.
public final void	setCaretBlinkPeriod(Duration period)
public final void	setContentPadding(Insets value)
public final void	setDisplayCaret(boolean on)
private final void	setDocumentArea(double minX, double minY, double width, double height)
public final void	setDropTarget(double the screen x coordinate screenX, double the screen y coordinate screenY) Attempts to set the drop target position at the specified screen coordinates.
public final void	setEditable(boolean on)
public final void	setHighlightCurrentParagraph(boolean on)
public final void	setInsertStyles(StyleAttributeMap v)
public final void	setLeftDecorator(SideDecorator d)
public final void	setLineEnding(LineEnding the line ending value, cannot be null value) Sets the model's line ending characters.
public final void	setModel(StyledTextModel m)
public final void	setRightDecorator(SideDecorator d)
public final void	setStyle(TextPos the start of text range start, TextPos the end of text range end, StyleAttributeMap the style attributes to set attrs) Sets the specified style to the selected range.
public final void	setUndoRedoEnabled(boolean true to enable undo/redo on) Controls whether undo/redo functionality is enabled in the model.
public final void	setUseContentHeight(boolean on)
public final void	setUseContentWidth(boolean on)
public final void	setWrapText(boolean value)
public void	undo() If possible, undoes the last modification.
public final ReadOnlyBooleanProperty	Returns: the read-only property undoableProperty() The property describes if it's currently possible to undo the latest change of the content that was done.
public final BooleanProperty	Returns: the use content height property useContentHeightProperty() Determines whether the preferred height is the same as the content height.
public final BooleanProperty	Returns: the use content width property useContentWidthProperty() Determines whether the preferred width is the same as the content width.
protected void	validateModel(StyledTextModel the model (can be null) m) Validates the model property value.
pack-priv VFlow	vflow()
public final BooleanProperty	Returns: the wrap text property wrapTextProperty() Indicates whether text should be wrapped in this RichTextArea.
public final void	write(DataFormat the data format f, OutputStream the output stream out) Calls the model to writes the current document to the output stream using the specified `DataFormat`.
public final void	write(OutputStream the output stream out) Calls the model to write the current document to the output stream, using the highest priority `DataFormat` as determined by the model.

public Class RichTextArea

Creating a RichTextArea

Text Models

Selection

Customizing

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary