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 RichTextFX CSS Reference Guide

Summary of relevant information

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

Cheat Sheet

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

StyledTextArea Guide

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>;

    /* 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>;    
}

Pseudo States

 /* special styling applied when the area is not editable */
.styled-text-area:read-only {}

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

 /* WARNING: ':last-paragraph' must be applied BEFORE ':first-paragraph' if using both for both to work! 
        (Takes into account an area with only one line.) */

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

 /* special styling applied to the first paragraph (ParagraphBox) */
.styled-text-area:first-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>;

    /* WARNING: Never use the line spacing CSS as it will never change the visuals of the area. 

        It is only applied when a TextFlow has a Text object containing a newline character,
        which never occurs in a RTFX area. Instead, one should add padding to ParagraphBox's top/bottom
        to simulate line spacing. Note: TextFlow's line spacing CSS does not add spacing in-between
        lines on a wrapped multi-line "paragraph" */
    /* -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:

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

    /* the color of the border around a section of text */
    -rtfx-border-stroke-color: <paint>;

    /* the width of the border around a section of text */
    -rtfx-border-stroke-width: <size>;

    /* the type of the border around a section of text */
    -rtfx-border-stroke-type: [inside | outside | centered];

    /* the border's dash lengths: allows dot/dash style borders */
    -rtfx-border-stroke-dash-array: <size>[ <size>]+;

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

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

    /* the underline's 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>;
}

Issue with StyleClassed-based CSS Default Styling

When an area's text is styled by default using style classes, for example:

.styled-text-area .text {
    -fx-fill: white;
}

... then any additional styling must include the same selector prefix. In other words, if one wanted to apply the style class "red" to the area, one would need to precede it with ".styled-text-area " in order for that style class to be applied properly. Thus, given the following code...

StyleClassedTextArea area = // creation code;

// from 0 to 19, default style is used
area.setStyle(20, 40, Collections.singleton("green"); 
area.setStyle(41, 60, Collections.singleton("red");

/* THIS WILL NOT WORK AS IT DOES NOT INCLUDE DEFAULT's SELECTOR(S) PREFIX */
.green {
    -fx-fill: green;
}
/* THIS WILL WORK */
.styled-text-area .red {
    -fx-fill: white;
}

The same applies if one sets the area's id, as shown by CodeArea, a subclass of StyleClassedTextArea:

CodeArea area = new CodeArea("int x = 3 + 5;");
area.setId("codeArea");
area.computeHighlighting();

/* default text styling */
#codeArea .text {
    -fx-fill: white;
}
/* Overriding styling for key words */
#codeArea .keyword {
    -fx-fill: blue;
}
/* Overriding styling for operators */
#codeArea .operator {
    -fx-fill: purple;
}