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 data 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 data 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 Data variables requires the Data option to be defined for the 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/...
DataItem Item1
DataRow Item1 Item2 Item3 Item4
DataColumn
DataBlock
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 DataColumn and DataBlock 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 data 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.
Data Option
Defines the name of a Data channel that will provide the dynamic data to resolve the Data variables used by this Text command. This data channel must have already been established with a Data command at the top of the script file with a matching data channel name. Note that the DataColumn and DataBlock 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 TestData.lws script in the Lightwing SDK for examples of its proper use.
Index Option
Defines which items from a data channel are used to resolve the Data 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 zero to the number of items and rows in the file for this data channel, minus one (as of the last time it was read from the file system). Lightwing will report an error if an index exceeds the boundaries of a data channel array the first time the channel is created. However, it is possible for the array boundaries to change if the data file for the channel is updated, in which case the variables may resolve to blank space. Refer to the TestData.lws script in the Lightwing SDK for examples of its proper use.
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.
Input Option
Defines the input device(s) from which to accept user input for the text. The valid parameters are Touch, Camera or Both. The default value can be defined by an Input command before the first page in the script. Otherwise, the default value is Touch, which requires a display with touch screen capabilities to be connected via USB. Camera means that touch events will be detected based on a motion map generated from the video from a camera. Both will accept touch events from either of these devices. Lightwing always displays status messages upon start up that indicate which of these input devices are actually detected and enabled. Touch screen capabilities are always enabled on Windows because Lightwing emulates this using the mouse input. Camera features are not available on Windows.
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!"