Text (Character Displays)

Displays text in either a single line or multiple lines.

Text component example

{
  "type": "Text",
  "textAlign": "center",
  "text": "Hello! I am here to serve."
}

Text properties

The Text component has the following properties in addition to the standard component properties:

Property Type Default Dynamic Description
msPerCharacter Integer 500 No Time per character scrolled for marquee text.
overflow wrap, marquee wrap No Specify behavior when text is longer than the width.
text String "" Yes Data to display in the text block.
textAlign auto, left, center, right auto No Horizontal alignment.
textAlignVertical top, center, bottom top No Vertical alignment.

When the component is the target of an event (see Event definition), the following values are reported in event.target:

"event": {
  "target": {
    "disabled": Boolean, // True if the component is disabled
    "id": ID,            // ID of the component
    "uid": UID,          // Runtime-generated unique ID of the component
    "height": Number,    // Height of the component, in ch (includes the padding)
    "text": String,      // Displayed text
    "width": Number      // Width of the component, in ch (includes the padding)
  }
}

msPerCharacter

Time to scroll a character when overflow is marquee. For example, if using value of 500 and showing "Winter storm watch from Thursday afternoon through late Tuesday night…" on a display that has 30 characters, it will render as "Winter storm watch from Thursd" and after 500 milliseconds it will change to "inter storm watch from Thursda" and then after another 500ms to "nter storm watch from Thursday".

overflow

Defines the behavior when the text is longer than the width of the text field. The following options are supported:

Property Value Description
wrap Wrap text to the next line if the height of the text field is greater than one character, otherwise truncate the text.
marquee Scroll the text at the rate defined by the msPerCharacter property (the property should be set in this case).

In case of marquee, the author can fine tune the appearance by inserting spaces to the text property. This controls the initial appearance as well as wrap-around. For example, if showing on a 8-character display it would show as:

"text" value Initially shown After four shifts
"123456789" "12345678" "56789123"
" 123456789" " 123456" "3456789 "
"123456789 " "12345678" "56789 1"

text

String data to display in the text block. If not set, an empty string is displayed. Text blocks support simple markup:

Tag Description Example
<br> Insert a line break. Line breaks may be repeated. Line 1<br>Line 2

Markup elements may be nested. Improperly nested markup gives undefined behavior.

If line breaks are present in the text, setting overflow to marquee is not supported.

Markup characters in text must be replaced with character entity references:

Entity Character Description
&amp; & Ampersand
&lt; < Less-than
&gt; > Greater-than
&#nn; Any Decimal Unicode code-point. "nn" is a valid integer.
&#xnn; Any Hexadecimal Unicode code-point. "nn" is a valid hexadecimal number

Numeric entity references can be in decimal or hexadecimal. For example, © can be written &#169; or &#xa9;.

The string "Copyright &\#169; 2018, Simon \&amp; Schuster. \<br\>All Rights Reserved" is rendered:

Copyright © 2018, Simon & Schuster.
All Rights Reserved

textAlign

Controls the positioning of lines of text: left, center, right, or auto. The default is "auto", which uses the default font direction (e.g., left for English).

If textAlign is "center" and there are an even number of characters in a line, it will default to lower. For example, a text "C" on a display with 6 characters will be displayed as the 3rd character (using indexing from 1 through 6).

textAlignVertical

Positions the text within the text box. Only used if the text box is taller than the text content. Defaults to "top".

If the value is "center" and there are an even number of lines, it will default to lower. For example, a text "Center line" on a display with 6 lines will be displayed on the 3rd line (using indexing from 1 through 6).

Was this page helpful?

Last updated: May 10, 2024