Package org.fxmisc.richtext

Class GenericStyledArea<PS,​SEG,​S>

  • Type Parameters:
    PS - type of style that can be applied to paragraphs (e.g. TextFlow.
    SEG - type of segment used in Paragraph. Can be only text (plain or styled) or a type that combines text and other Nodes.
    S - type of style that can be applied to a segment.
    All Implemented Interfaces:
    Styleable, EventTarget, Virtualized, ClipboardActions<PS,​SEG,​S>, EditActions<PS,​SEG,​S>, TwoDimensional, NavigationActions<PS,​SEG,​S>, StyleActions<PS,​S>, TextEditingArea<PS,​SEG,​S>, UndoActions, ViewActions<PS,​SEG,​S>
    Direct Known Subclasses:
    StyledTextArea
    public class GenericStyledArea<PS,​SEG,​S>
extends Region
implements TextEditingArea<PS,​SEG,​S>, EditActions<PS,​SEG,​S>, ClipboardActions<PS,​SEG,​S>, NavigationActions<PS,​SEG,​S>, StyleActions<PS,​S>, UndoActions, ViewActions<PS,​SEG,​S>, TwoDimensional, Virtualized
    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 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.

    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 TwoDimensional and TwoDimensional.Bias. Also, read the difference between "position" and "index" in StyledDocument.getAbsolutePosition(int, int).

    See Also:
    EditableStyledDocument, TwoDimensional, TwoDimensional.Bias, VirtualFlow, VirtualizedScrollPane, Caret, Selection, CaretSelectionBind