RichTextFX CSS Reference Guide

Because some issues are fixable by CSS...

There have been a number of questions asking, "How do I change the color of [some object]?" or "How do I change the size of [some object]?", etc.

Instead of a person needing to open up a new question relating to these things and contributors explaining "Just adjust the CSS like so," we've decided to include a CSS Guide for RichTextFX.

Relevant CSS info for RichTextFX

Understanding the design structure of a StyledTextArea

What are the components that make up a StyledTextArea? There are more than a few and thus why adjusting the CSS can get very complicated very quickly. So, let's overview the components.

• StyledTextArea is a Region whose single child is a (vertical) VirtualFlow (See Tomas' Flowless project).
• A VirtualFlow is a Region that displays ParagraphBoxes (the cells of the virtual flow, aka lines of the area).
• A ParagraphBox is a Region that can display some graphic factory (specifically, an IntFunction<Node> that is usually used for the indicating the linenumber) and the styled text via a ParagraphText.
• A ParagraphText is a modified version of TextFlow that layouts TextExt objects (rich text content) and displays the caret (a Path object).
• A TextExt is a modified version of Text with additional CSS properties.

So, the seven items to keep in mind are:

• StyledTextArea (Region)
• VirtualFlow (Region)
• ParagraphBox (Region)
• ParagraphText (TextFlow)
• TextExt (Text)
• Caret (Path)
• (Optional) LineNumberFactory (Label) - a provided IntFunction<Node> graphic factory that indicates the line's line number

The CSS' "layout style" isn't always applied

If we look at the core layout code in StyledTextArea's layoutChildren() method, we'll see that it doesn't respect padding:

@Override protected void layoutChildren() {
    // virtualFlow's size does not take into account
    //  any possible padding!!!
    virtualFlow.resize(getWidth(), getHeight());
    // other code which isn't relevant in our case...
}

So, even if one adjusts the styled-text-area style class to include padding, it won't actually apply the style. This issue also shows up in ParagraphBox:

    @Override protected void layoutChildren() {
        Bounds bounds = getLayoutBounds();
        double w = bounds.getWidth();
        double h = bounds.getHeight();
        double graphicWidth = getGraphicPrefWidth();

        text.resizeRelocate(graphicWidth, 0, w - graphicWidth, h);

        graphic.ifPresent(g -> g.resizeRelocate(graphicOffset.get(), 0, graphicWidth, h));
    }

A possible workaround

Fortunately, this issue does not arise with VirtualFlow or ParagraphText. So, if one wants to add some padding to StyledTextArea, they should apply the padding to the VirtualFlow. The same workaround with ParagraphBox and ParagraphText might work for some cases but not all of them. No cases have been tested.

The RichTextFX CSS Reference Guide

Summary of relevant information

Name	Style Class	Respects Layout styles	Includes CSS from
StyledTextArea	"styled-text-area"	No	Region, Node
VirtualFlow	"virtual-flow"	Yes	Region, Node
ParagraphBox	"paragraph-box"	No	Region, Node
ParagraphText	"paragraph-text"	Yes	TextFlow (see below), Region, Node
TextExt	Depends on how styles are applied	N\A	TextExt (see below), Text, Font Properties, Shape, Node
Caret	"caret"	N/A	Path, Shape, Node
----	----	---	---
LineNumberFactory	"lineno"	Yes	Label, Control, Region, Node

Cheat Sheet

This Cheat Sheet does not include CSS from Region or Node. Use the CSS Reference Guide.

StyledTextArea Guide

/* StyledTextArea - regular CSS */
.styled-text-area {
    /* set the entire area's font size to the given size */
    -fx-font-size: <size>;

    /* set the blink rate of the area */
    -fx-caret-blink-rate: <duration>;

    /* CURRENTLY DOES NOT WORK: See Issue #303 
       set the background color for selected text */
    -fx-highlight-fill: <paint>;

    /* CURRENTLY DOES NOT WORK: See Issue #303
       set the foreground color (color of letters) of selected text */
    -fx-highlight-text-fill: <paint>;    
}

/* StyledTextArea - pseudo states */

 /* special styling applied to the current line (ParagraphBox) */
.styled-text-area:has-caret {}

 /* special styling applied to the first paragraph (ParagraphBox) */
.styled-text-area:first-paragraph {}

 /* special styling applied to the last paragraph (ParagraphBox) */
.styled-text-area:last-paragraph {}

The missing TextFlow CSS guide

The CSS Reference guide does not yet include anything on TextFlow. By looking at its javadoc, however, it seems reasonable to suggest that it supports the following:

.text-flow {
    /* the alignment of the text, where <alignment> can be 
        [ left | center | right | justify ] and defaults to "left" */
    -fx-text-alignment: <alignment>;
    /* when lines are wrapped, the number (double) of pixels between lines */
    -fx-line-spacing: <number>;
}

The additional CSS properties for TextExt

TextExt adds the following CSS properties to a Text object. Note: the underline properties will take affect regardless of the boolean value of Text#isUnderline(). Additionally, the prefix -rtfx is used to distinguish RichTextFX-added CSS from the JavaFX Text CSS:

.text {
    /* the color of the text's background color*/
    -rtfx-background-color: <paint>;

    /* the color of the underline */
    -rtfx-underline-color: <paint>;

    /* the width of the underline */
    -rtfx-underline-width: <size>;

    /* the dash lengths: allows dot/dash style lines */
    -rtfx-underline-dash-array: <size>[ <size>]+;

    /* the StrokeLineCap to use: [ square | butt | round ] 
       defaults to "square" */
    -rtfx-underline-cap: <stroke-line-cap>;
}