This example shows how to combine the touch controls and data channel features of Lightwing to construct buttons and sliders whose positions are stored in a data file. These features have already been introduced separately in previous tutorial examples.
Note that the Windows version of Lightwing uses mouse clicks to emulate touch events so that touch enabled content can be developed on Windows using just a mouse. This example requires a touch capable display to function on the Linux player. Such content should have the touch: on command before the first page, as shown. This causes Lightwing to abort and report an error message if a touch capable display is not detected when this script is parsed, but only on Linux.
The data command opens the CSV file named TouchTutorial, creates a data channel of the same name and defines the maximum size of the array for this channel with the limit option. An extension of .csv is assumed for data files and they are located in the data folder. This command can be repeated for any number of data files and their corresponding channels remain in effect throughout the entire script. Since this command is global in nature, it should always appear before the first page, as shown. These data channels can then be used by commands on subsequent pages.
In this example, the data channel is used to initialize the values for toggle and track touch controls. This requires those commands to use the data option with the name of an open data channel and use index options to specify specific items in the data channel’s array, as shown. When touch controls are associated with a data channel this way, the control is always initialized from the channel when the page begins and the channel will retain the current value of the touch control, even after the page expires. This allows subsequent pages to define touch controls with values that were selected on previous pages. Note that the initial and update options should not be used with touch controls that are associated with a data channel.
The only way to write data channels back to the file system is with the write command, which must be done sometime before the script terminates if the data is to be preserved. This allows the positions of touch controls to be retained for when the script is run again. This command writes the current contents of the entire array for the channel, but only channels that have been modified by an associated touch control are actually written. Up to 8 channels can be written by a single command, but only one write command can be used per page.
This example defines a toggle control named ExitButton which branches to the Exit page when touched, so that the data channel is written back to the file system just before the script ends. Since the page Earth has an infinite time duration, this touch control is needed to end the page. The jump option enables the branch, but the touch: off option delays the jump until the touch is released. This allows the box highlight to be seen before the touch is released because the box is enabled by touch on events which occur before touch off events.
Also refer to the online Lightwing script documentation for more details about these commands.
// Scripting Tutorial - Touch Controls with an Associated Data Channel
version: 1.0
touch: on
// Open a data channel with array dimensions of 1 x 8 items and read it from a CSV file.
data: TouchTutorial limit: 1, 8
page: Earth time: 0, 0
// This button is required to exit the page.
box: ExitButton position: 15, 20 size: 15, 10 align: CenterCenter toggle: ExitButton color: 0.5, 0.5, 0 touch: off jump: Exit
toggle: ExitButton box: ExitButton
text: OpenSansBold_50 box: ExitButton type: "Exit"
// These boxes highlight the enabled button and define button positions, sizes and colors.
box: Button1 position: 85, 20 size: 15, 10 align: CenterCenter toggle: Button1 color: 0.5, 0.5, 0
box: Button2 position: 85, +20 size: 15, 10 align: CenterCenter toggle: Button2 color: 0.5, 0.5, 0
box: Button3 position: 85, +20 size: 15, 10 align: CenterCenter toggle: Button3 color: 0.5, 0.5, 0
box: Button4 position: 85, +20 size: 15, 10 align: CenterCenter toggle: Button4 color: 0.5, 0.5, 0
// Defines toggle names for buttons with initial states and makes them mutually exclusive.
toggle: Button1 box: Button1 disable: Button2, Button3, Button4 stick: on data: TouchTutorial index: 0, 0
toggle: Button2 box: Button2 disable: Button1, Button3, Button4 stick: on data: TouchTutorial index: 0, 1
toggle: Button3 box: Button3 disable: Button1, Button2, Button4 stick: on data: TouchTutorial index: 0, 2
toggle: Button4 box: Button4 disable: Button1, Button2, Button3 stick: on data: TouchTutorial index: 0, 3
// Text labels for the buttons which use the same positions and alignments as highlight boxes above.
text: OpenSansBold_50 box: Button1 type: "Globe 1"
text: OpenSansBold_50 box: Button2 type: "Globe 2"
text: OpenSansBold_50 box: Button3 type: "Globe 3"
text: OpenSansBold_50 box: Button4 type: "Globe 4"
// Defines a two-dimensional relative tracking control for rotating objects with a range of -180 to 180 degrees.
box: Globe position: 50, 50 size: 38 align: CenterCenter color: 1, 1, 1, 0.08
track: RotateX axis: X box: Globe range: 180, -180 relative: on data: TouchTutorial index: 0, 4
track: RotateY axis: Y box: Globe range: 180, -180 relative: on data: TouchTutorial index: 0, 5
// Defines a sliding track control for scaling the globe objects.
box: Slide position: 5, 90, 1 size: 90, 5 color: 1, 1, 1, 0.08
track: Scale axis: X box: Slide range: 0.1, 2 data: TouchTutorial index: 0, 6
track: PositionX axis: X box: Slide range: 5, 90 data: TouchTutorial index: 0, 7
box: Knob position: PositionX, 90, 0 size: 5, 5 color: 0.5, 0.5, 0
// Four instances of the same object using different globe images selected by toggle controls and rotated and scaled by tracking controls.
object: SphereSpin rate: 0 rotate: RotateY, RotateX scale: Scale, Scale, Scale toggle: Button1 image: GlobeNasa1
object: SphereSpin rate: 0 rotate: RotateY, RotateX scale: Scale, Scale, Scale toggle: Button2 image: GlobeNasa2
object: SphereSpin rate: 0 rotate: RotateY, RotateX scale: Scale, Scale, Scale toggle: Button3 image: GlobeNasa3
object: SphereSpin rate: 0 rotate: RotateY, RotateX scale: Scale, Scale, Scale toggle: Button4 image: GlobeNasa4
// Write data channel back to file system before exiting.
page: Exit
write: TouchTutorial