The Toggle command defines binary state touch controls with 2D rectangular shapes at a depth position of zero (0.0). The current state of the toggle control is available to other commands on the same page to create buttons for interactive control. The first parameter is a name, which is mandatory. Toggle names are only required to be unique for the current page. Defined toggle names can then be referenced by other commands on the same page to enable/disable boxes, text, tickers, objects and other toggle controls. Track controls can not be used to define parameters for Toggle commands.
Touch controls can only be used on the same page they are defined on unless they are defined on a global page, in which case they can be used on subsequent pages until the next global page. Toggle controls have the special capability to be defined in any order on the same page. This allows mutually exclusive button groups to be defined using the disable option, provided that the entire group is defined on the same page.
Example of a Page with Two Toggle Control Buttons
page: PageName time: 1, 10
box: Highlight1 position: 15, 20 size: 15, 10 toggle: Button1 color: 0.5, 0.5, 0
box: Highlight2 position: 15, 40 size: 15, 10 toggle: Button2 color: 0.5, 0.5, 0
toggle: Button1 box: Highlight1 disable: Button2 initial: on stick: on
toggle: Button2 box: Highlight2 disable: Button1 initial: off stick: on
Box Option
Defines the name of an associated box from which many parameters will be inherited as defaults for the toggle control. This allows a preceding box on the same page to define the appearance of the toggle control, including time, position, size, image and/or color. Any of these can still be overridden with specific command options, but usually a button image should be aligned with the touch control for a proper user interface. Toggle controls will function without an associated box, but will be invisible.
Time Option
Defines the start and duration times for the toggle control in seconds. If not specified, the default start and duration times will be the same as for the page that this control is on. These can be specified as either floating-point values in seconds or integer (sexagesimal) clock time durations. 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 toggle command on the same page. This allows toggle commands to be duplicated in the script without the need to manually add time values. Refer to the Page command for examples. This parameter is typically inherited from a box which defines the appearance of the toggle control, but this option allows that to be overridden.
Size Option
Defines the width and height of the toggle control, respectively. These dimensions are specified in the same coordinate system used to position text, tickers and objects. Dimensions of 100, 100 would cover the entire page, for example, if the top left corner of the toggle control were positioned at the origin. This parameter is typically inherited from a box which defines the appearance of the toggle control, but this option allows that to be overridden. If a size is defined which differs from an associated box, the box image will be scaled to this size. If only one value is specified (the width), the height is computed automatically to make the toggle control square, regardless of the aspect ratio of the display.
Align Option
Defines the vertical and horizontal alignment for the toggle control. This determines the position of the toggle control region on the display. This parameter is typically inherited from a box which defines the appearance of the toggle control, but this option allows that to be overridden.
Toggle Control Alignments
Names Short Uses TopLeft tl Left Justified Control TopCenter tc Centered Control TopRight tr Right Justified Control CenterLeft cl Left Justified Control CenterCenter cc Centered Control CenterRight cr Right Justified Control BottomLeft bl Left Justified Control BottomCenter bc Centered Control BottomRight br Right Justified Control
Position Option
Defines the position for the toggle control on the display. The align option also affects this position. The default position for touch controls 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. The depth coordinate is fixed for touch controls at zero (0.0) and can not be altered.
Position coordinates 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 toggle command on the same page. This allows toggle commands to be duplicated in the script file without the need to manually add position values. This parameter is typically inherited from a box command which defines the appearance of the toggle control, but this option allows that to be overridden.
Scale Option
Defines horizontal and vertical scaling factors for the toggle control. This can be used to stretch or reduce the toggle control’s region in either direction. The default scaling factors for toggle controls are 1.0, 1.0, which disables scaling. This parameter is typically inherited from a box command which defines the appearance of the toggle control, but this option allows that to be overridden.
Initial Option
Defines the initial state of the toggle control. Toggle controls reset to their initial state whenever the page begins or whenever their reset time expires. This parameter must be either on or off. The default state is off. This option is ignored if combined with the Data option on the same touch control.
Stick Option
Defines if the toggle control will stick in the active state when it is touched and released. By default, toggle controls automatically reset to their initial state when the touch ends, which is intended for creating buttons with momentary behavior that define a binary state. This option allows this automatic reset to be disabled which causes the toggle control to stick until it is reset by either the reset or disable options or by restarting the page. This parameter must be either on or off. The default state is off.
Touch Option
Defines the polarity for which touch screen events will be recognized for the toggle control. This parameter can be specified as on, off or both. The default is both. 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. Touch events are not recognized during page transitions.
Disable Option
Defines other toggle controls which will be reset when this toggle control is touched and becomes active. Any number of toggle controls can be associated into mutually exclusive groups using this option, such that activating any button can reset any or all of the other buttons in the group. The names of up to 24 toggle controls can be specified. All of these toggle controls must be defined on the same page.
Instead of listing toggle names individually, the reserved name All can be used instead. This will cause all of the other toggle controls on the page to be reset.
Reset Option
Defines a time interval in seconds when the toggle control will be automatically reset to its initial state, as defined by the initial option. Toggle controls always reset to their initial state when the page begins. This option provides an additional means to reset the state of the toggle control without the need to restart the page. By default, this parameter is zero, which disables this reset. This parameter can be specified as either a floating-point value in seconds or an integer (sexagesimal) clock time duration.
Data Option
Defines the name of a data channel to associate with this toggle control. If this is defined, the initial state of the touch control will be set from the named data channel each time the page for this touch control is displayed. This option overrides the Initial option, if both are used. The named data channel must have been created by a corresponding Data command at the top of the script to use this option. This allows the state of touch controls to be preserved beyond the duration of the page. Data channels which are modified by associated touch controls are written back to their corresponding data files when the page ends.
Index Option
Defines which item is read to set the initial state of the toggle control from an associated data channel, at the start of the page. This option requires the Data option also, to define the associated data channel name. 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 read. 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 TestControlsData.lws script in the Lightwing SDK for examples of its proper use.
Input Option
Defines the input device(s) from which to accept user input for the toggle control. 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.
End Option
Defines the ending duration time for when the toggle control is activated in seconds. This is the time duration until the page is aborted to execute the branch in response to the input event. If not specified, the default value is zero. This can be specified as either a floating-point value in seconds or an integer (sexagesimal) clock time duration. End times can be prefixed with a plus symbol “+” which means the new end time is the sum of the specified time and the end time from the previous toggle command on the same page. This allows toggle commands to be duplicated in the script without the need to manually add end time values.