Text Command

The Text command provides powerful capabilities that are easy to use with minimal experience. Lightwing will render professional, presentation quality text directly from scripts, RSS channels or a CSV file, in any available font, size, color, with or without animations, font effects and/or drop-shadows with no additional software required. This makes changing text content as simple as editing the script or CSV file. The Text command supports limited 3D features as well, including perspective projections and effects.

The mandatory parameters for Text commands are a font name and either a constant line of text or a text variable name, which are defined with the type option. There must be a matching font file in the fonts folder with a PVR extension. Font names should also have a size suffix preceded by an underscore. The size suffix specifies the height that the font will be rendered at in pixels.

Many fonts are provided in the Lightwing SDK in sizes 10 through 200 pixels on 10 pixel height increments. The best way to preview and select fonts is to run the TestFonts.lws test script provided in the Lightwing SDK. Refer to the section on Converting Fonts for information on adding new fonts.

    Example of a Page with some Text Commands
    
    page: PageName    time: 1, 10
    text: OpenSansBold_40    type: "Hello World!"
    text: OpenSansRegular_80    type: DateLong
    text: GalatiaRegular_100    time 1, 5    fade: 1,1    position: 50, 50    align: CenterCenter    type: "Hello World!"

Special effects can also be applied to fonts. These effects can enhance the appearance of fonts and make them visually more effective. The best way to preview and select font effects is to run the TestFontEffects.lws test script provided in the Lightwing SDK.

Time Option

Defines the start and duration times for the text in seconds. If not specified, the default start and duration times will be the same as for the page that this text is on. These can be specified as either floating-point values in seconds or integer (sexagesimal) clock time durations. Refer to the Page command for examples.

Start times can be prefixed with a plus symbol (+) which means the new start time is the sum of the specified time and the start time from the previous Text command on the same page. This allows Text commands to be duplicated in the script without the need to manually add time values.

Box Option

Defines the name of an associated box from which many parameters will be inherited as defaults for the text. The specified box must precede the text command on the same page. Inherited parameters include time, position, size, scale, scroll, rotate, alignment, touch events and fade animation options. Any of these can still be overridden with specific command options.

Fade Option

Defines the time in seconds for text to fade-in and fade-out, when it appears and disappears, respectively. These time values are also used for most animation options that can be applied to Text commands, including zoom, slide, spin and bounce. Sexagesimal format can not be used here because these animations should never be more than a few seconds at most.

Zoom Option

Defines horizontal and vertical scaling factors used for the text command during fade-in and fade-out times. These time durations are defined by the fade option. This can be used to stretch or reduce the font in either direction as text appears and/or disappears on the display. Up to four floating-point scaling factors can be specified, for fade-in x, y and fade-out x, y. The default scaling factors are 1.0, 1.0, 1.0, 1.0, which disables zooming.

Slide Option

Defines horizontal and vertical sliding distances and directions used for the Text command during fade-in and fade-out times. These time durations are defined by the fade option. This is used to slide text in any direction as it appears and/or disappears on the display. Up to four floating-point values can be specified, the first two define the distance and directions for the fade-in slide movement and the last two define the distance and directions for the fade-out slide movement. The range for these values is -1.0 to 1.0. Their defaults are 0.0, 0.0, 0.0, 0.0 which disables sliding. Negative values mean the slide directions will be toward the origin (left and/or up), whereas positive values mean the slide directions will be away from the origin (right and/or down).

Scroll Option

Defines scroll directions used for the Text command during fade-in and fade-out times. These time durations are defined by the fade option. This can be used to scroll text in any of four directions as it appears and/or disappears on the display. One or two direction names can be specified, the first defines the direction for the fade-in scroll movement and the second defines the direction for the fade-out scroll movement. The default directions are None and None, which disable scrolling.

Text Scroll Directions

        Names              Short

        None                     n
        Top                        t
        Bottom                 b
        Left                        l
        Right                      r

Spin Option

Defines spin angles used for the text command during fade-in and fade-out times. These time durations are defined by the fade option. This can be used to spin text in either direction as it appears and/or disappears on the display. Two floating-point values can be specified in degrees, the first defines the angle for the fade-in spin and the second defines the angle for the fade-out spin. Positive values indicate clockwise rotation, whereas negative values indicate counter-clockwise rotation. The default angles are 0.0, 0.0, which disables spinning.

Bounce Option

Defines bounce time scale factors for text. Up to three floating-point values can be specified, which correspond to the x, y and z axis, respectively. These bounce factors are multiplied by the fade-in time duration, which is defined by the fade option, to determine the time duration for the text bounce animation for all three axis. The bounce animation is unique in that it begins when the fade-in time ends, whereas the other text animations occur during the fade-in time. The default bounce values are 0.0, 0.0, 0.0, which disables bouncing.

Align Option

Defines the vertical and horizontal alignment for text lines.  This is used to determine the position the text will be drawn on the display and the pivot point for the rotate and spin options.

Text and Ticker Alignments

        Names              Short             Uses
        
        TopLeft                 tl                Left Justified Text    
        TopCenter            tc               Centered Text
        TopRight               tr                Right Justified Text    
        CenterLeft            cl                Left Justified Text    
        CenterCenter       cc               Centered Text
        CenterRight          cr                Right Justified Text
        BottomLeft           bl                Left Justified Text    
        BottomCenter      bc               Centered Text
        BottomRight        br                Right Justified Text

Position Option

Defines the position the text will be drawn on the display. The align option also affects this position. The default position for text is 0.0, 0.0, 0.0, which is the top left corner of the display and at the front of the coordinate space depth. If text wrapping is enabled with the lines option, the horizontal (y coordinate) will be used to position wrapped lines.

Any position coordinate can be prefixed with a plus symbol (+) to define the new position as the sum of the specified coordinate and the same position coordinate from the previous Text command on the same page. This allows Text commands to be duplicated in the script file without the need to manually add position values.

Scale Option

Defines horizontal and vertical scaling factors for the text. This can be used to stretch or reduce the font for text in either direction. This can also be used to enlarge fonts beyond the sizes at which they are provided in the Lightwing SDK. However, scaling fonts excessively will reduce their quality. The default scaling factors for text are 1.0, 1.0, which disables scaling. Lightwing automatically scales all fonts down by half (in both directions) when run windowed on Windows to approximate their size relative to the window. On multi-panel displays, Lightwing automatically scales all fonts up by the vertical number of panels in the display. For example, on an 8 x 2 panel display, font sizes are doubled because the vertical height of the display is 2 panels.

Delay Option

Defines a floating-point time duration in seconds to delay between drawing each character glyph of the constant or variable Text command. This has a dramatic effect which can make text much more visually interesting, especially when combined with other Text command options, such as fade, zoom, slide, spin and bounce. Valid delay values have a narrow range between zero and one. The default value is zero, which disables this feature. Practical values are about 0.1 for short strings and decrease with longer strings. This option must be combined with at least one other text animation option, in addition to the fade option, to have any visible effect.

Rotate Option

Defines rotation angles for the text in degrees. Up to three floating-point values can be specified, which correspond to rotations on the x, y and z axis, respectively. Positive degree values indicate clockwise rotation, whereas negative values indicate counter-clockwise rotation. The default rotations are 0.0, 0.0, 0.0 degrees. This option should not be used in combination with the jump, call, return or touch options for the Text command as rotations will cause misalignment between apparent text positions and touch boundaries.

Ortho Option

Defines if the text is drawn using an orthographic or perspective projection. This parameter can be specified as off or on. For text, this is on by default, so text will appear the same size regardless of its depth position. This is best for most text, unless an X or Y axis rotation is also applied, in which case a perspective projection can give text a 3D appearance. Lightwing does not support perspective text or tickers on multi-panel displays.

Color Option

Defines a color for the text. This may include an optional alpha value to blend the text with the background. The colors can be specified in one of three different formats, float values with a range of 0.0 to 1.0, integer values with a range of 0 to 255 or as a six or eight digit hexadecimal value preceded with a hash symbol (HTML style). For all of these formats, the ordering of the values is red, green, blue and alpha. The alpha parameter is optional. The default color for text is opaque white (1.0, 1.0, 1.0, 1.0 or 255, 255, 255, 255 or #FFFFFFFF).

Type Option

Defines either a constant text string or a variable name to be drawn in the font specified for this text. Constant strings must be enclosed within a pair of double quote symbols, “like this”. Double quote symbols can also be used within a constant text string simply by repeating the double quote symbols. If the string does not begin with a double quote, it is assumed to be the name of a text variable and must match one of the variable names supported by Lightwing, which are listed in the table below.

Text variable names are resolved and replaced with information that is current at the time the text is drawn. Many of the supported variables have additional requirements. For example, time and date variables depend on the NTP (Network Time Protocol) configuration (in /etc/ntp.conf) which requires an active internet connection and the correct time zone configuration (in /etc/init.d/timezone). Use of any of the RSS variables requires the rss option to be defined and use of any of the CSV variables requires the csv option to be defined for this text command.

Text and Ticker Variable Names

        Names                                                Examples of Resolved Text
        
        Year                                                     2015
        Month                                                 1
        MonthName                                       January
        Week                                                    1
        Day                                                       1
        DayName                                            Thursday
        Hours12                                              12
        Hours24                                              24
        AmPm                                                  AM
        Minutes                                               10
        Seconds                                               20
        Clock12                                                12:10 AM
        ClockSeconds12                                 12:10:20 AM
        Clock24                                                24:10
        ClockSeconds24                                 24:10:20
        DateFull                                               Thu, Jan 1, 2015
        DateShort                                            Jan 1, 2015
        DateLong                                             Thursday, January 1, 2015
        DateNumeric                                      1/1/2015
        TimeZone                                            CST6CDT
        FramesPerSecond                              60
        Version                                                 1.2
        TouchX1                                               50
        TouchY1                                               50
        TouchX2                                              100
        TouchY2                                              100
        TrackControlFloat1                           50.0
        TrackControlFloat2                           50.00
        TrackControlFloat3                           50.000
        TrackControlFloat4                           50.0000
        TrackControlInteger                          50
        TrackControlHex                                ABCDEF00
        RssChannelTitle                                 NPR News
        RssChannelDescription                    Latest Headlines
        RssChannelLink                                 http://www.npr.org/rss/rss.php?id=1001
        RssChannelCopyright                       Copyright 2015 NPR
        RssChannelItems                               100
        RssItemTitle                                        Star Trek Returns
        RssItemDescription                           Space, the final frontier. These are ...
        RssItemLink                                        http://www.npr.org/star_trek_story/...
        CsvItem                                                 Item1
        CsvRow                                                 Item1    Item2    Item3    Item4
        CsvColumn
        CsvBlock

Constant and variable text strings can be up to 1000 characters in length per text command. The length, lines and position options can be used to format long strings across multiple lines on the display. Backslash symbols can be used to break long text commands into multiple lines within script files, but this does not affect how text is drawn on the display.

    Example of a Text Command with Indented and Wrapped Text
    
        text: GalatiaRegular_90    position: 15, 15    align: TopLeft    length: 40    lines: 3 \
            type: "   Space, the final frontier. These are the voyages of the starship Enterprise. Its five year mission: to explore strange new worlds"

Length Option

Defines the maximum number of characters that will be drawn on the display on any single line for constant or variable text. If a text line exceeds this length, it will be wrapped to the next line on the display up to the available number of wrap lines, as specified by the lines option. If the number of wrap lines is exhausted, the text will be truncated instead. Text lines are always wrapped at a space, tab or hyphen symbol in the text which precedes the specified length as closely as possible. The wrapped line will be positioned on the display at the same horizontal and depth position as the current line, but down vertically by the height of the specified font.

Lines Option

Defines the maximum number of lines that can be drawn on the display for any constant or variable text. The actual number of lines drawn depends on the length of the text and may be less. Text can only be wrapped if the length option has been defined and the lines option is greater than 1. The default number of wrap lines is 1. Text lines are wrapped at space, tab or hyphen symbols in the text which precedes the specified length as closely as possible. The length option defines the maximum length for the lines.

Note that the CsvColumn and CsvBlock variables are exceptions because they normally produce text wrapped onto multiple lines on the display. These variables require that the lines option be specified with enough lines to display the desired number of rows from the CSV channel and the length option is not required.

RSS Option

Defines the name of an RSS channel that will provide the dynamic data to resolve the RSS variables used by this Text command. This RSS channel must have already been established with an RSS command at the top of the script file with a matching RSS channel name. Note that the RssChannelDescription and RssItemDescription variables typically produce text which are so long that they need to be wrapped onto multiple lines on the display when used with Text commands. Therefore, the lines and length options must also be used to define how many lines are available and where to break the lines. Refer to the TestRSS.lws script in the Lightwing SDK for an example.

CSV Option

Defines the name of a CSV channel that will provide the dynamic data to resolve the CSV variables used by this Text command. This CSV channel must have already been established with a CSV command at the top of the script file with a matching CSV channel name. Note that the CsvColumn and CsvBlock variables typically produce text wrapped onto multiple lines on the display. Therefore, the lines option must also be used to define how many lines are available. Refer to the TestCSV.lws script in the Lightwing SDK for an example.

Index Option

Defines which data items from a CSV channel are used to resolve the CSV variables for the Text command. One or two positive integers may be specified. The first value indexes a data item from a horizontal row and the second value indexes which row from the two dimensional array will be displayed. The valid range of these indices is 0 to the number of items and rows in the file for this CSV channel minus one, the last time it was read. Lightwing will report an error if an index exceeds the boundaries of a CSV channel array the first time the channel is created. However, it is possible for the array boundaries to change if the CSV file for the channel is updated, in which case the variables may resolve to blank space. Refer to the TestCSV.lws script in the Lightwing SDK for an example.

Touch Option

Defines the polarity for which touch screen events will be recognized for the text. Touch events for text have precedence over events for backgrounds and boxes, but can be superseded by events for objects.

This parameter can be specified as on, off, both or dir. The default is on. A touch on event means a finger has made contact with the touch screen. A touch off event means a finger has broken contact with the touch screen. Touch both means that both on and off touch events are recognized. This option requires that a jump, call or return option must also be specified for the page command to define the branch page that will be executed when the touch event is detected.

The dir touch option allows one of several branch pages to be selected based on swipe direction. A touch swipe event is when a finger is dragged on the display at least 10% of the width or height of the display and released. The dominate direction of movement at the point of release selects the branch page. One of four swipe directions can be detected, left, right, top and bottom. This requires that either two or four branch pages be defined for the touch branch option for the page. The best practice is to define all four page names, even if only two are actually needed. The dir option can not be used with the return option.

Touch events are not recognized during page transitions.

Jump Option

Defines a branch page to execute when a touch event occurs on the text with the correct polarity. The polarity is defined by the touch option. This feature is only available if a supported touch screen is connected to the Lightwing player and configured properly. This option is similar to the Jump command, except that no branch condition options can be used here.

Call Option

Defines a branch page to execute when a touch event occurs on the text with the correct polarity. The polarity is defined by the touch option. This feature is only available if a supported touch screen is connected to the Lightwing player and configured properly. This option is similar to the Call command, except that no branch condition options can be used here.

Return Option

Defines that a branch page from the call stack will be executed when a touch event occurs on the text with the correct polarity. The polarity is defined by the touch option. This feature is only available if a supported touch screen is connected to the Lightwing player and configured properly. This option is similar to the Return command, except that no branch condition options can be used here.

Toggle Option

Defines a toggle control which enables and disables the text and its touch events. If a toggle control name is specified with this option, the text will only be drawn when the toggle control is active, otherwise the text is invisible and its touch events are not processed either. This toggle control name must be defined either on the same page or the current global page. However, toggle controls can be defined before or after the Text command, provided they are defined on the same page.

Track Option

Defines a track control whose numeric value will be displayed to resolve a track control variable. One of the text variable names which are prefixed with TrackControl must be specified for the Type option, as well. This track control name must have been defined previously on the same page.

Effect Option

Defines an effect to be used to draw the font for a Text command instead of the default font effect (Font.pfx). A PFX extension is appended to the end of this name to construct the file name of the effect. Font effects are located in the same folder as image effects, but have file names that begin with Font. Image and font effects are not interchangeable because fonts are stored in a compact 8 bits per pixel format, so only effects that have names beginning with Font can be used with the Text commands. A font effect can specify a custom font image, but the font effects supplied in the Lightwing SDK specify Default images, which means the font name given as the first parameter to the Text command will be used.

Arg0 Option

Defines effect-specific parameters for a selected font effect for a Text command. Up to four floating-point values are passed to the effect to draw the font. The meaning of these values depends on the selected font effect. These parameters are required by some font effects, but ignored by the default font effect. To determine the appropriate values for a particular effect, refer to the notes in the individual effect files.

    Example of a Text Command with a Font Effect and Arguments
  
        text: GalatiaBold_200    effect: FontColorBlocks    arg0: 1.0, 0.0, 0.0, 1.0    type: "Hello World!"

 

 

<   System Command                                             Introduction                                            Ticker Command   >