JSignage:TextArea

From SpinetiX Support Wiki

Jump to: navigation, search

This page is related to jSignage layers.

jSignage.textArea()

jSignage.textArea( attributesObject )

Returns: jSignage Object

Description

This jSignage basic layer type allows wrapping of simple or formatted text content within a given rectangular region. As this function returns a jSignage Object, any of the layer functions can be applied - to add or change the text content inside a text area, use the .text() method.

For reference, see the documentation of the <textArea> element (SVG Tiny 1.2).

$.textArea( ).text('Welcome to jSignage').addTo( 'svg' );

Parameters

  • attributesObject
    Type: Plain Object.
    An object containing any of the following attributes:

Text area 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 (3.1)
    Color to use for the text border. Default: black.
  • textBorderSize (3.1)
    Width of text border. The text border is drawn along the outline of each character. Default: 0.
  • textFillGradient (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 (3.1)
    Description of a text shadow effect using the CSS3 syntax.
    Example: 2px 2px black
  • unicodeBidi
    Control the unicode bidir text layout algorithm.

Specific functions

As the jSignage.textArea() function returns a jSignage Object, any of the layer functions can be applied - to add or change the text content inside a text area, use the .text() method.

The textArea layer extends the functionality of the .text() function to support formatted text.

.text()

.text( text )
.text( formattedTextObject  )

Returns: jSignage Object

  • .text(text)
    Replace the text content with unformatted text.
  • .text(obj)
    Replace all text content with a formatted text object. Formatted text allows fine control over the fonts, styles, and wrapping of the text.

Formatted text object

Formatted can be created using the following functions:

  • $.tspan(text)
    Create an unformatted text.
  • $.tspan(text, { ... })
    Create a text with font styling attributes. See Fonts and styling attributes for the list of attributes available.
  • $.tbreak()
    Append a line break.

Note that $.tspan( ) will automatically convert any new line character ("\n") into a line break.

Formatted text object can be created using multiple $.tspan( ) and $.tbreak():

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

which is equivalent to:

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

Examples

Simple text

Adding a simple textArea at the bottom of the document.

$(function(){ 
  $('svg').add( 
    $.textArea({ id: 'txt1', width: '90%', height: '15%', top: '80%', left: '5%', fontSize: 60})
     .text("Welcome to jSignage demo")
  );
});

Text with background and frame

Adding a text with a white background and a black frame using frame decoration.

$(function(){ 
  $('svg').add( 
    $.textArea({
      id: 'txt1',
      width: '90%', height: '15%', top: '75%', left: '5%', fontSize: '60px',
      frame: {
        backColor: 'white',
        frameColor: 'black'
      }
    }).text("Welcome to jSignage demo")
  );
});

Formatted text

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

$(function(){  
  $('svg').add( 
    $.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") )
  );
});

New lines

Adding a text area with a list of items with bullets:

$(function(){
  $('svg').add( 
    $.textArea({ width:640, height:360, fontSize: '40px' }).text(
      $.tspan("* Item 1").tbreak()
       .tspan("* Item 2").tbreak()
    )
  );
});

Note that .text() and $.tspan() will automatically convert any new line character in the text to a call to $.tbreak(). The above example can be simplified by taking advantage of this:

$(function(){
  $('svg').add( 
    $.textArea({ width:640, height:360, fontSize: '40px' }).text( "* Item 1\n* Item 2\n" )
  );
});

Automatic font size

Using the fontSize: 'max' option will ensure that the size of the text fits the height of the text area.

$(function(){ 
  $('svg').add( 
    $.textArea({ width: '90%', height: '15%', top: '15%', left: '5%', fontSize: 'max' })
     .text("Welcome to jSignage demo")
  );
});

Note: If the text is too long to fit into the text box it will be truncated; to make sure that the entire text is visible, fitTextArea() should be used instead.

Using effects

Adding a text appearing using a random fly-in effect, and disappearing after 5 seconds using a page-out effect.

$(function(){ 
  $('svg').add( 
    $.textArea({ width: '90%', height: '15%', top: '75%', left: '5%', fontSize: '60px', dur: 5 })
     .text("Welcome to jSignage demo")
     .flyIn()
     .pageOut()
  );
});

Underline

Draws some text and a red line underneath.

$(function(){
  $('svg').add( [
    $.textArea({ top: 30, left: 40, width: 1200, fontSize: '50px',  displayAlign: 'before', lineIncrement: 60 })
     .text("Welcome to jSignage demo"),
    $.line({ x1: 80, y1: 90, x2: 1200, y2: 90, stroke: 'red', strokeWidth: 2 })
  ] );
});

Note:

  • The line vertical position is set to 90 (y1: 90, y2: 90) as this is equal to the sum of the top position of the text (top: 30) and the line increment ( which correspond to the position of the baseline of the first line of text ).
  • The size of the line is constant regardless of the text size.

Advanced examples

Showing the time

Shows the current time. The SVGTimer is used to update the display every second.

function showTime() {
  var now = new Date();
  var hour = now.toTimeString().substr(0,8);
  $('#time').text( hour );
}
 
$(function(){ 
  $('svg').add( 
    $.textArea( { top: '30%', height: '40%', fontSize: 'max', id: 'time' } )
  );
  $.setInterval( showTime, 1000 );
});

Timer

Create a timer counting down from 10 to 0.

var cnt = 10;

function timerText() {
  if ( cnt>0 ) {
    $('#timer').text( cnt-- );
    $.setTimeout( timerText, 1000 );
  } else {
    $('#timer').text( "Time out" ).attr( 'fill', 'red' );
  }
}

$(function(){ 
  $('svg').add( 
    $.textArea( { 
            fontSize: '85px' 
        } )
     .text( 
            $.tspan( "Timer: " )
             .tspan( "", { id: 'timer' } ) 
        )
  );
  timerText();
});

Note:

  • The timer is a simple text element. The content of the tspan is modified using text().
  • The content of the first tspan is not modified.
  • The timer is created using the setTimeout function. The timeout is set to one second in the future.
  • When the timer expires (reach zero), the text is set to "Time out" and the color of the text is modified using the fill attribute.

Automatic underlying of text

The addTextWithUnderline() function creates a text area layer and then adds a red line underneath the text content.

/**
 * Gets the bounding box of the text regardless of the layer's width and height.
 * @param {Object} elem The SVG Element to measure.
 */
function getRealBBox( elem ) {
    var boundingBox,
        w = elem.getAttribute( 'width' ), 
        h = elem.getAttribute( 'height' );
    
    // change the element dimensions to auto
    elem.setAttribute( 'width', 'auto' );
    elem.setAttribute( 'height', 'auto' );
    
    // get the bounding box of the text
    boundingBox = elem.getBBox();
    
    // reset the element dimensions
    elem.setAttribute( 'width', w);
    elem.setAttribute( 'height', h);
    
    return boundingBox;
}
 
/**
 * Creates a text area layer and then adds a red line underneath the text content.
 * @param {string} text
 * @param {number} left
 * @param {number} top
 * @param {number} width
 * @param {number} height
 * @param {string} fontSize
 * @param {number} margin The margin between the text and the line
 * @param {string} color The line color
 */
function addTextWithUnderline( text, left, top, width, height, fontSize, margin, color ) {
    // create a text area layer with the text centered
    var txt = $.textArea( { 
        top: top, left: left, width: width, height: height, fontSize: fontSize 
    } ).text( text ).addTo('svg');  
 
    var boundingBox = getRealBBox( txt[0] );    // get the "real" dimensions of the text
    var padding = ( width - boundingBox.width ) / 2;    // set the horizontal padding
    var baseline = top + ( height + boundingBox.height ) / 2 + margin;
    
    // draw a line underneath the text
    $.line( { 
        x1: left + padding, 
        y1: baseline, 
        x2: left + width - padding, 
        y2: baseline, 
        stroke: color, 
        strokeWidth: 2 
    } ).addTo('svg'); 
}

// create two undelined text areas
addTextWithUnderline( 'Welcome', 40, 40, 250, 60, '50px', 5, 'blue' );
addTextWithUnderline( 'to jSignage demo', 80, 80, 500, 200, '50px', 15, 'red' );
This page was last modified on 28 November 2018, at 17:36.