Skip to content

RichTextFX CSS Reference Guide

Jump to bottom Edit New page
Jurgen edited this page Nov 29, 2024 · 23 revisions

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.

  • A VirtualizedScrollPane is a Region that displays a StyledTextArea and sometimes displays a horizontal and/or vertical scroll bar. In short, it adds scrollbars to the area.
  • 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.
  • A CaretNode is a Path used to render a caret in the area
  • A SelectionPath is a Path used to render a portion of a selection on a given paragraph.

So, the seven items to keep in mind are:

  • VirtualizedScrollPane (Region)
  • StyledTextArea (Region)
  • VirtualFlow (Region)
  • ParagraphBox (Region)
  • ParagraphText (TextFlow)
  • TextExt (Text)
  • CaretNode (Path)
  • SelectionPath (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
VirtualizedScrollPane "virtualized-scroll-pane" VirtualizedScrollPane, Region, Node
StyledTextArea "styled-text-area" Region, Node
StyledTextField "styled-text-field" Region, Node
VirtualFlow "virtual-flow" VirtualFlow, 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
SelectionPath "main-selection", "line-highlighter", and for any additional selections you added use the selections name 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>;
}

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 {}

RTFX-Specific CSS for CaretNode

.caret {
    /* set the blink rate of the area as [number][ms|s|m|h] */
    -rtfx-blink-rate: <duration>ms;
}

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

    /* the amount of pixels to separate lines in a multi-line paragraph
       (e.g. when `area.isWrapText() == true`) */
    -fx-line-spacing: <number>;

    /* the size of a tab stop in spaces, defaults to 8
       (values less than 1 are treated as 1) */
    -fx-tab-size: <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>;

    /* the radius used to create waved underline */
    -rtfx-underline-wave-radius: <size>;

    /* the offset between text and underline */
    -rtfx-underline-offset: <size>;

    /* the gap for double underlining, i.e: two parallel straight or wavy lines */
    -rtfx-underline-double-gap: <size>;}

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 THE DEFAULT's SELECTOR(S) PREFIX */
.green {
    -fx-fill: green;
}
/* THIS WILL WORK */
.styled-text-area .red {
    -fx-fill: red;
}

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;
}
  • Note: in some cases, the default JavaFX font does not support certain CSS properties such as -fx-font-weight or -fx-font-style. This is a JavaFX issue and not a richtextfx issue. If you experience issues with certain properties, try using different fonts.

dsadrgt

Clone this wiki locally