Track Command

The Track command defines a touch control region with a 2D rectangular shape at a depth position of zero (0.0) which tracks touch movements within the region. Relative or absolute touch movements are translated linearly to values within defined ranges that are appropriate for parameters to other commands. The first parameter for track commands is a name, which is mandatory. Track names are only required to be unique for the current page. Defined track names can then be referenced by other commands to control properties like position, size, color, scale and rotate for boxes, text, tickers and objects on the same page. 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. Track controls must be defined on the page prior to being used, unlike toggle controls. Track controls can not be used to define parameters for other Track or Toggle commands or the same control.

    Example of an Object Rotated with Track Controls
    
    page: PageName    time: 1, 10
        box: Globe    position: 50, 50    size: 40, 40    align: CenterCenter
        track: RotateX    axis: X        box: Globe    range: 180, -180    relative: on
        track: RotateY    axis: Y        box: Globe    range: 180, -180    relative: on
        object: Sphere    rotate: RotateY, RotateX

Box Option

Defines the name of an associated box from which many parameters will be inherited as defaults for the track control. This allows a preceding box on the same page to define the appearance of the track control, including time, position, size, image and/or color. Any of these can still be overridden with specific command options, but usually box images should be aligned with the touch control for a proper user interface. Track controls will function without an associated box, but will be invisible.

Time Option

Defines the start and duration times for the track 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 track command on the same page. This allows track 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 track control, but this option allows that to be overridden.

Size Option

Defines the width and height of the track 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 track control were positioned at the origin. This parameter is typically inherited from a box which defines the appearance of the track 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 track control square, regardless of the aspect ratio of the display.

Align Option

Defines the vertical and horizontal alignment for the track control. This determines the position of the track control region on the display. This parameter is typically inherited from a box which defines the appearance of the track control, but this option allows that to be overridden.

Track 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 track 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 track command on the same page. This allows track 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 track control, but this option allows that to be overridden.

Scale Option

Defines horizontal and vertical scaling factors for the track control. This can be used to stretch or reduce the track control’s region in either direction. The default scaling factors for track controls are 1.0, 1.0, which disables scaling. This parameter is typically inherited from a box command which defines the appearance of the track control, but this option allows that to be overridden.

Axis Option

Defines the direction, distance or angle for which touch movements will be tracked. This parameter can be x, y, center, pinch or angle. The default is x, which means horizontal tracking. y means vertical tracking. These directions are independent of whether the display has a landscape or portrait orientation. The center axis is defined as the distance from the touch point to the mid-point (between the minimum and maximum of the range option) on both the x and y axis.

On multi-touch capable panels, pinch or angle can be specified for the axis option. These require two simultaneous touch contacts on the panel. Pinch is defined as the distance between the two touch points. Angle is defined as the angle from the first touch point to the second touch point, in degrees.

Range Option

Defines the minimum and maximum floating-point values of the track control. Both parameters are required. The last touch position within the tracking control region is linearly translated to a value which will always be within this range. These parameters must be chosen carefully to match the requirements of how the track control will be used. For example, scale values usually have a range of 0.0 to 10.0 or higher. However, a rotation value might require a range of -180.0 to 180.0 (in degrees), and color values must have a range that does not exceed 0.0 to 1.0.

Initial Option

Defines the initial floating-point value of the track control. Track controls reset to their initial value whenever the page begins or whenever their reset time expires. The default value is the average of the two range values, as defined by the range option. Lightwing does not clip this parameter to the range. This option is ignored if combined with the Data option on the same touch control.

Touch Option

Defines the polarity for which touch screen events will be recognized for the track 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 only recognized when the page is active and not during page transitions.

Relative Option

Defines if the control will track relative touch movements or absolute touch position. For example, relative tracking is the way a mouse works, but drawing tablets typically use absolute tracking. This parameter must be either on or off. The default is off, which means absolute tracking.

Data Option

Defines the name of a data channel to associate with this track 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 value for the track 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 track 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.

      Filter Option

Defines the depth of filtering for camera motion tracking as an integer count of frames. When the Input option is Camera, motion tracking is filtered to reduce noise. This is an averaging filter that is updated each time a new frame is drawn and the filter depth can be defined separately for each track control. The default value for this option is 50 frames. Specifying a larger value will improve noise rejection, but will reduce the responsiveness of motion tracking. Specifying a smaller value will decrease noise rejection, but improve responsiveness. This option only applies to camera motion tracking. To adjust the filtering of touch input, open a command shell and edit:

nano  /etc/ts.conf

 

 

<   Touch Command                                             Introduction                                            Version Command   >