Box Command

The Box command draws 2D rectangular shapes with either solid colors, linear color gradients, video or images from files or an RSS channel. Boxes have many uses, including page decoration, highlighting text, tickers or objects or for defining rectangular touch zones, whether visible or invisible. The Box command has the same default depth position (0.0) and shares most of the same command options as the Text command. This makes it easy to highlight text or tickers with boxes drawn under text or transparent color drawn over text. Boxes drawn at the same depth will draw under text and tickers. To draw boxes over text, tickers or objects, move their depth (Z coordinate) to a greater value than for the box.

The first parameter for box commands is a name, which is mandatory. Box names are only required to be unique for the current page. Box names can then be referenced by text, ticker, toggle and track commands that are defined later on the same page to inherit various parameters such as size, timing, alignment, position and fade animation options.

The Box command can draw rectangles with a solid color, linear color gradient, or with images from an image file, video or an RSS channel. Invisible boxes can be drawn by defining a color with a zero alpha value. This is useful for defining invisible touch regions on a touch-capable display. The Box command is limited to the built-in animations controlled by the fade option. For more elaborate animations, shapes or materials, use the Object command instead.

    Example Box Commands
    
    box: FullScreen    size: 100, 100
    box: QuarterScreen1    size: 50, 50    position: 50, 50    align: CenterCenter    color: 1, 0, 0
    box: QuarterScreen2    size: 50, 50    time: 1, 0    fade: 1, 1    position: 50, 50    align: CenterCenter    color: 0.5, 0.5, 0.5, 0.5

    Box Option

Defines the name of an associated (parent) box from which most parameters will be inherited as defaults for this box. This allows a preceding box on the same page to define the appearance of the new box, including time, position, size, image and/or color. Any of these can still be overridden with specific command options.

Time Option

Defines the start and duration times for the box in seconds. If not specified, the default start and duration times will be the same as for the page that this box 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 box command on the same page. This allows box commands to be duplicated in the script without the need to manually add time values. Refer to the Page command for examples.

Size Option

Defines the width and height of the box, 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 box were positioned at the origin. Small values (0.1) can be used to draw horizontal or vertical lines. The size option can be omitted in some cases, such as when the image, video or rss options are used to define images for the box, or when the box is associated with a text or ticker command.

If the size option is omitted but the box has an image or video, the dimensions of the image or video will be used for the box. Image dimensions are in pixel units. The scale option can be used to adjust the box size in this case. If no scaling is used, the image will be displayed in its native (pixel) size.

The size option can also be omitted if the box is associated with a subsequent text or ticker command on the same page. In this case, the size of the box will match the size of the associated text or ticker based on the font and content that is defined for the text. This makes it easy to place boxes under text to opaque or highlight the text. The size will also adapt automatically to changes in content from text variables.

If only one value is specified (the width), the height is computed automatically to make the box square, regardless of the aspect ratio of the display.

Fade Option

Defines the time in seconds for the box 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 box 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 box 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 box in either direction as it 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 Box command during fade-in and fade-out times. These time durations are defined by the fade option. This is used to slide boxes in any direction as they appear and/or disappear 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).

Spin Option

Defines spin angles used for the box command during fade-in and fade-out times. These time durations are defined by the fade option. This can be used to spin the box 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.

Scroll Option

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

Box Scroll Directions

        Names              Short

        None                     n
        Top                        t
        Bottom                 b
        Left                        l
        Right                      r

Bounce Option

Defines bounce time scale factors for the box. 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 box bounce animation for all three axis. The bounce animation is unique in that it begins when the fade-in time ends, whereas the other box 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 the box.  This is used to determine the position the box will be drawn on the display and the pivot point for the rotate and spin options.

Box Alignments

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

Position Option

Defines the position the box will be drawn on the display. The align option also affects this position. The default position for boxes 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.

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 box command on the same page. This allows box 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 box. This can be used to stretch or reduce the box in either direction. The default scaling factors for boxes are 1.0, 1.0, which disables scaling.

Rotate Option

Defines rotation angles for the box 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 box command as rotations will cause misalignment between apparent box positions and touch boundaries.

Ortho Option

Defines if the box is drawn using an orthographic or perspective projection. This parameter can be specified as off or on. For boxes, this is on by default, so boxes will appear the same size regardless of their depth positions. This will produce simple rectangles, but if an X or Y axis rotation is also defined, a perspective projection will produce trapezoidal shapes.

Color Option

Defines colors for the box. Each color may include an optional alpha value to blend 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 box color is opaque white (1.0, 1.0, 1.0, 1.0 or 255, 255, 255, 255 or #FFFFFFFF).

Up to four colors can be defined per box command by repeating this option. These colors are assigned to the corners of the box in a clockwise direction starting with the top left corner. The box command interpolates the colors assigned to the corners to fill the box. If only a single color is defined, it is used for all four corners. If a second color is defined, it is used for the right two corners to create a horizontal color gradient from the left two coroners. Vertical or diagonal color gradients can be created by defining all four colors.

Video Option

Defines the name of a video that will be drawn on the box instead of just colors. The video must have already been established with a video command either on the same page or on a preceding global page.

Image Option

Defines one or more images that will be drawn on the box instead of just colors. The image is drawn using the default effect named Image unless an effect option is defined, in which case the defined images will override images named in that effect. Each image name may have a file name extension which defines the file type of the image. The supported types are BMP, PNG, JPG and PVR.  The default type is PVR because this format loads more quickly. If a BMP, PNG, or JPG image can not be found, Lightwing will substitute it with another file of the same name but with the PVR extension.

There are some reserved image names which can be used with this option which have special uses. Refer to the Object command for more information.

RSS Option

Defines the name of an RSS channel that will provide thumbnail images for the box. 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 and it must enable thumbnail images with the thumbnail option. Not all RSS websites provide thumbnail images and even those that do typically do not provide thumbnail images for every item in the channel feed. Therefore, when no image is available for the current item, Lightwing attempts to display the channel image instead and when neither image is available, the box will not be drawn until the RSS channel steps to an item which does have a valid image.

This option can not be combined with the color, image or video options. Refer to the TestRSS.lws script in the Lightwing SDK for an example.

Touch Option

Defines the polarity for which touch screen events will be recognized for the box. Touch events for boxes have precedence over events for backgrounds, but can be superseded by events for text, tickers or 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 box. 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 box 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 box 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 box 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 box and its touch events. If a toggle control name is specified with this option, the box will only be drawn when the toggle control is active, otherwise the box 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 Box command provided they are defined on the same page.

Effect Option

Defines an effect to be used to draw the box instead of the default box effect (Box.pfx). A PFX extension is appended to the end of this name to construct the file name of the effect.

Arg0 Option

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

    Example of a Box with a Box Effect and Arguments
  
        box: BoxName    size: 20, 20    effect: BoxEffect    arg0: 1.0, 1.0, 1.0, 1.0

 

 

<   Audio Command                                                                                  Call Command   >