Text editing control that renders and edits a EditableStyledDocument. Accepts user input (keyboard, mouse) and provides API to assign style to text ranges. It is suitable for syntax highlighting and rich-text editors.

Adding Scrollbars to the Area

By default, scroll bars do not appear when the content spans outside of the viewport. To add scroll bars, the area needs to be wrapped in a VirtualizedScrollPane. For example,

// shows area without scroll bars
InlineCssTextArea area = new InlineCssTextArea();

// add scroll bars that will display as needed
VirtualizedScrollPane<InlineCssTextArea> vsPane = new VirtualizedScrollPane<>(area);

Parent parent = // creation code
parent.getChildren().add(vsPane)

Auto-Scrolling to the Caret

Every time the underlying EditableStyledDocument changes via user interaction (e.g. typing) through the GenericStyledArea, the area will scroll to insure the caret is kept in view. However, this does not occur if changes are done programmatically. For example, let's say the area is displaying the bottom part of the area's EditableStyledDocument and some code changes something in the top part of the document that is not currently visible. If there is no call to requestFollowCaret() at the end of that code, the area will not auto-scroll to that section of the document. The change will occur, and the user will continue to see the bottom part of the document as before. If such a call is there, then the area will scroll to the top of the document and no longer display the bottom part of it.

For example...

// assuming the user is currently seeing the top of the area

// then changing the bottom, currently not visible part of the area...
int startParIdx = 40;
int startColPosition = 2;
int endParIdx = 42;
int endColPosition = 10;

// ...by itself will not scroll the viewport to where the change occurs
area.replaceText(startParIdx, startColPosition, endParIdx, endColPosition, "replacement text");

// adding this line after the last modification to the area will cause the viewport to scroll to that change
// leaving the following line out will leave the viewport unaffected and the user will not notice any difference
area.requestFollowCaret();

Additionally, when overriding the default user-interaction behavior, remember to include a call to requestFollowCaret().

Setting the area's UndoManager

The default UndoManager can undo/redo either PlainTextChanges or RichTextChanges. To create your own specialized version that may use changes different than these (or a combination of these changes with others), create them using the convenient factory methods in UndoUtils.

Overriding default keyboard behavior

GenericStyledArea uses KEY_TYPED to handle ordinary character input and KEY_PRESSED to handle control key combinations (including Enter and Tab). To add or override some keyboard shortcuts, while keeping the rest in place, you would combine the default event handler with a new one that adds or overrides some of the default key combinations.

For example, this is how to bind Ctrl+S to the save() operation:

import static javafx.scene.input.KeyCode.*;
import static javafx.scene.input.KeyCombination.*;
import static org.fxmisc.wellbehaved.event.EventPattern.*;
import static org.fxmisc.wellbehaved.event.InputMap.*;

import org.fxmisc.wellbehaved.event.Nodes;

// installs the following consume InputMap,
// so that a CTRL+S event saves the document and consumes the event
Nodes.addInputMap(area, consume(keyPressed(S, CONTROL_DOWN), event -> save()));

Overriding default mouse behavior

The area's default mouse behavior properly handles auto-scrolling and dragging the selected text to a new location. As such, some parts cannot be partially overridden without it affecting other behavior.

The following lists either org.fxmisc.wellbehaved.event.EventPatterns that cannot be overridden without negatively affecting the default mouse behavior or describe how to safely override things in a special way without disrupting the auto scroll behavior.

• First (1 click count) Primary Button Mouse Pressed Events: (EventPattern.mousePressed(MouseButton.PRIMARY).onlyIf(e -> e.getClickCount() == 1)). Do not override. Instead, use onOutsideSelectionMousePressed, onInsideSelectionMousePressReleased, or see next item.
• ( All Other Mouse Pressed Events (e.g., Primary with 2+ click count): Aside from hiding the context menu if it is showing (use hideContextMenu() some((where in your overriding InputMap to maintain this behavior), these can be safely overridden via any of the InputMapTemplate's factory methods or InputMap's factory methods.
• Primary-Button-only Mouse Drag Detection Events: (EventPattern.eventType(MouseEvent.DRAG_DETECTED).onlyIf(e -> e.getButton() == MouseButton.PRIMARY && !e.isMiddleButtonDown() && !e.isSecondaryButtonDown())). Do not override. Instead, use onNewSelectionDrag or onSelectionDrag.
• Primary-Button-only Mouse Drag Events: (EventPattern.mouseDragged().onlyIf(e -> e.getButton() == MouseButton.PRIMARY && !e.isMiddleButtonDown() && !e.isSecondaryButtonDown())) Do not override, but see next item.
• All Other Mouse Drag Events: You may safely override other Mouse Drag Events using different org.fxmisc.wellbehaved.event.EventPatterns without affecting default behavior only if process InputMaps ( org.fxmisc.wellbehaved.event.template.InputMapTemplate#process(javafx.event.EventType, BiFunction), org.fxmisc.wellbehaved.event.template.InputMapTemplate#process(org.fxmisc.wellbehaved.event.EventPattern, BiFunction), org.fxmisc.wellbehaved.event.InputMap#process(javafx.event.EventType, Function), or org.fxmisc.wellbehaved.event.InputMap#process(org.fxmisc.wellbehaved.event.EventPattern, Function) ) are used and org.fxmisc.wellbehaved.event.InputHandler.Result#PROCEED is returned. The area has a "catch all" Mouse Drag InputMap that will auto scroll towards the mouse drag event when it occurs outside the bounds of the area and will stop auto scrolling when the mouse event occurs within the area. However, this only works if the event is not consumed before the event reaches that InputMap. To insure the auto scroll feature is enabled, set isAutoScrollOnDragDesired() to true in your process InputMap. If the feature is not desired for that specific drag event, set it to false in the process InputMap. Note: Due to this "catch-all" nature, all Mouse Drag Events are consumed.
• Primary-Button-only Mouse Released Events: (EventPattern.mouseReleased().onlyIf(e -> e.getButton() == MouseButton.PRIMARY && !e.isMiddleButtonDown() && !e.isSecondaryButtonDown())). Do not override. Instead, use onNewSelectionDragFinished, onSelectionDropped, or see next item.
• All other Mouse Released Events: You may override other Mouse Released Events using different org.fxmisc.wellbehaved.event.EventPatterns without affecting default behavior only if process InputMaps ( org.fxmisc.wellbehaved.event.template.InputMapTemplate#process(javafx.event.EventType, BiFunction), org.fxmisc.wellbehaved.event.template.InputMapTemplate#process(org.fxmisc.wellbehaved.event.EventPattern, BiFunction), org.fxmisc.wellbehaved.event.InputMap#process(javafx.event.EventType, Function), or org.fxmisc.wellbehaved.event.InputMap#process(org.fxmisc.wellbehaved.event.EventPattern, Function) ) are used and org.fxmisc.wellbehaved.event.InputHandler.Result#PROCEED is returned. The area has a "catch-all" InputMap that will consume all mouse released events and stop auto scroll if it was scrolling. However, this only works if the event is not consumed before the event reaches that InputMap. Note: Due to this "catch-all" nature, all Mouse Released Events are consumed.

CSS, Style Classes, and Pseudo Classes

Refer to the RichTextFX CSS Reference Guide .

Area Actions and Other Operations

To distinguish the actual operations one can do on this area from the boilerplate methods within this area (e.g. properties and their getters/setters, etc.), look at the interfaces this area implements. Each lists and documents methods that fall under that category.

To update multiple portions of the area's underlying document in one call, see createMultiChange().

Calculating a Position Within the Area

To calculate a position or index within the area, read through the javadoc of org.fxmisc.richtext.model.TwoDimensional and org.fxmisc.richtext.model.TwoDimensional.Bias. Also, read the difference between "position" and "index" in org.fxmisc.richtext.model.StyledDocument#getAbsolutePosition(int, int).

    StyledTextArea area = // creation code
    area.addEventHandler(MouseEvent.MOUSE_PRESSED, (MouseEvent e) -> {
        CharacterHit hit = area.hit(e.getX(), e.getY());
        int characterPosition = hit.getInsertionIndex();

        // move the caret to that character's position
        area.moveTo(characterPosition, SelectionPolicy.CLEAR);
    }