JSignage:Text layers

This page is related to jSignage layers.

Description

jSignage API includes the following methods for displaying plain or formatted text content inside a layer:

• Text area

  This is a basic layer type that allows wrapping of simple or formatted text content within a given rectangular region.

• Fit text area

  This is an extension of the text area layer that automatically chooses the optimal font size so that all the text is visible. It is especially useful for text from an external source, such as a news feed, which needs to be displayed in full, but whose size may be variable and cannot be known in advance.

• Ping-pong text area

  This is an extension of the text area layer that automatically applies scrolling back and forth if the text does not fit entirely within the area.

• Headline text area

  This is an extension of the text area layer optimized for single lines. It automatically adjusts the font size and transform so that the text occupies the full height of the area on a single line and it is entirely visible. It is especially useful for single line text from an external source, such as a news headline, which needs to be displayed in full, but whose size may be variable and cannot be known in advance.

• Scrolling text area

  This is an extension of the text area layer that scrolls vertically automatically if the number of lines of text exceeds the number of lines that fits in the area, either line by line or page by page.

Attributes

All jSignage layers share a common set of attributes to define their screen layout (left, top, width, etc.) and active time interval (begin, dur, repeatCount, etc.). Frame decoration (frame) can be used to improve the layout of text layers.

The text layer specific attributes are detailed below.

Alignment attributes

These attributes can only be applied at the text area level.

• displayAlign

  Type: String. Default: 'center'.

  Vertical alignment of the text inside the text area. Can be: 'center', 'before' (i.e. align at top) or 'after' (i.e. align at bottom).

• lineIncrement

  Type: Number or String. Default: 'auto'.

  Size of the interline (i.e. subsequent lines are offset from the previous line by this amount). Can be either 'auto' or number.

• textAlign

  Type: String. Default: 'center'.

  Horizontal alignment of the text inside the text area. Can be: 'center', 'start', 'end' or 'justify'.

  'start' means left for left-to-right documents and right for right-to-left documents, while 'end' is the opposite.

Styling attributes

These attributes can be applied at the text area level as well as to parts of the text when using formatted text.

• direction

  Control the unicode bidir text layout algorithm.

• fill

  Specify the text color.

• fontFamily

  Specify which font is used to render the text.

• fontSize

  Specify which the size of the font used to render the text.

  The special value 'max' is valid only at the text area level and will adjust the font size automatically to match the height of the text area.

• fontStyle

  Specify whether the text is to be rendered as italic or normal. The default value is normal, use italic for italic text.

• fontVariant

  Specify whether the text is to be rendered using small-caps glyphs for lowercase characters. The default value is normal, use small-caps for small-caps text.

• fontWeight

  Specify the boldness or lightness of the font used to render text relative to other fonts in the same font family. The default value is normal. Use bold or bolder for bold text; lighter is also available.

• textBorderColor (Added in firmware 3.1)

  Color to use for the text border. Default: black.

• textBorderSize (Added in firmware 3.1)

  Width of text border. The text border is drawn along the outline of each character. Default: 0.

• textFillGradient (Added in firmware 3.1)

  Description of a linear gradient paint for the text. It overrides the fill attribute, if any.

  The value must be a linear-gradient() CSS3 description.

  Example: linear-gradient(to bottom, yellow, blue)

• textShadow (Added in firmware 3.1)

  Description of a text shadow effect using the CSS3 syntax.

  Example: 2px 2px black

• unicodeBidi

  Control the unicode bidir text layout algorithm.

Functions

All jSignage layers share a common set of functions, such as .begin(), .end(), .show(), .hide(), .addTo(), etc.

The text layer specific functions are detailed below.

.text()

Use this method to add or replace the content inside a text area with a plain or formatted text object.

textLayer.text( formattedTextObject )
textLayer.text( text )

Returns: jSignage Object

Note:

Formatted text allows fine control over the fonts, styles, and wrapping of the text. It can be created using one or more $.tspan( ) and $.tbreak() functions.

jSignage.tbreak()

Use this method to create a "tbreak" element, which is an empty element that forcibly breaks the current line of text, even if the current line of text is empty (i.e., multiple consecutive 'tbreak' elements each cause a line break).

$.tbreak()

jSignage.tspan()

Use this method to create a formatted text object, with or without different styling attributes applied to it.

$.tspan( text, { stylingAttributes } )
$.tspan( text )

Note:

Any new line character ("\n") will automatically be converted into a line break, as if $.tbreak() was used.

var myText = $.tspan( "First line" ).tbreak().tspan( "Second " ).tspan( "line" );

is equivalent to:

var myText = $.tspan( "First line\nSecond line" );

Examples

Formatted text

Adding a text area, with the sentence "Welcome to the jSignage API demo". The word "jSignage" is written in blue.

$(function(){  
    $.textArea({ 
        id: 'txt1', width: '90%', height: '15%', top: '85%', left: '5%', fontSize: '60px'
    }).text( 
        $.tspan("Welcome to the ").tspan("jSignage", { fill: 'blue'} ).tspan(" API demo") 
    ).addTo('svg');
});

Variable text size

Relative text size between the tspan() are preserved.

$(function(){ 
    $.fitTextArea().text(
        $.tspan( 'Big text', { fontSize: 200 } )
        .tbreak().tbreak()
        .tspan( 'Small text', { fontSize: 100 } )
    ).addTo('svg');
});

Ping-pong

Display the text area, making it scroll from left to right and then right to left.

$(function(){ 
    $.pingPongTextArea( { fontSize: 'max', speed: 50, scrollBack: true } ).text('<--- OK --->').addTo('svg');
});

Scaled text area

Create a single line of text as large as possible reducing the font size to make it fit in the area.

$(function(){ 
    $.headlineTextArea( { scaleMethod: 'uniform' } ).text( 'Fit this text.' ).addTo('svg');
});

Message

Display a message at the bottom of the screen, two lines at the time.

$(function(){ 
    $.scrollingTextArea( { 
        lines: 2, repeatCount: 'indefinite', top: '80%', height: '20%', 
        frame: { shape: 'round', backColor: 'white', frameColor: 'grey', padding: '5%' }
    } ).text(
        $.tspan().tbreak()
        .tspan('Welcome to the jSignage demo.').tbreak()
        .tspan('This is an example of scrollingTextArea.').tbreak()
        .tspan('Lines are shown one by one.').tbreak()
        .tbreak()
    ).addTo('svg');
});

Notes:

• 2 lines of text are displayed, and the text will scroll for ever ({ lines: 2, repeatCount: 'indefinite' }
• The text is composed using tspan().
• Additional tbreak() are added at the top and at the bottom of the text to control how it appears and disappears from the screen.
• The frame attribute is used to add a white background with rounded corners to the text.