6.1-Object Reference

ON THIS PAGE

Firmware Version 6.1

BrightSign players use a standardized library of BrightScript objects to expose functionality for software development. To publish a new API for interacting with BrightSign hardware, we create a new BrightScript object.

The pages in this section provide definitions for objects that can be used in BrightScript. A brief description, a list of interfaces, and the member functions of the interfaces are provided for each object class. While most BrightScript objects have self-contained pages, some objects are grouped on the same page if they are closely related or depend on one another for functionality.

Here is a sample of objects that are used frequently when creating applications in BrightScript:

roVideoMode	Configures video output and interacts with displays using CEC/EDID.
roRectangle	Used to define zones/widgets on the screen. This object is passed to many other objects to define their screen area, including roVideoPlayer, roImagePlayer, roImageWidget, roHtmlWidget, roClockWidget, and roCanvasWidget.
roVideoPlayer	Plays video files, streams, and HDMI input.
roImagePlayer	Displays images.
roHtmlWidget	Displays local or remote HTML content using the Chromium rendering engine.
roNetworkConfiguration	Used to configure Ethernet, WiFi, and local network parameters.
roDeviceInformation	Used to retrieve a wide array of system information, including model type, device serial number, and firmware version.

Interfaces and Methods

Every BrightScript object consists of one or more "interfaces." An interface consists of one or more "methods." For example, the roVideoPlayer object has several interfaces, including ifMessagePort. The interface ifMessagePort has one method: SetPort().

The abstract interface ifMessagePort is exposed and implemented by both the roControlPort and the roVideoPlayer objects. Once the SetPort() method is called, these objects will send their events to the supplied message port. This is discussed more in the Event Loops section below.

Example

p = CreateObject("roMessagePort")
video = CreateObject("roVideoPlayer") 
gpio = CreateObject("roControlPort", "BrightSign")
gpio.SetPort(p)
video.SetPort(p)

The above syntax makes use of a shortcut provided by the language: The interface name is optional, unless it is needed to resolve name conflicts. For example, the following two lines of code carry out the exact same function:

gpio.SetPort(p)
gpio.ifMessagePort.SetPort(p)

BrightScript Objects consist only of interfaces, and interfaces define only methods. There is no concept of a "property" or variable at the object or interface level. These must be implemented as "set" or "get" methods in an interface.

Classes

A class name is used to create a BrightScript object. For example, the class name for a video playback instance is roVideoPlayer, so, to initialize a video playback instance, you would use code similar to the following:

Example

video = CreateObject("roVideoPlayer")

Note that "video" can be any name that follows the syntax outlined in the next section.

Object and Class Name Syntax

Class names have the following characteristics:

Must start with an alphabetic character (a – z).
May consist of alphabetic characters, numbers, or the "_" (i.e. underscore) symbol.
Are not case sensitive.
May be of any reasonable length.

Zones

With the BrightSign Zones feature, you can divide the screen into rectangles and play different content in each rectangle.

Depending on the BrightSign model, zones can contain video, images, HTML content, audio, a clock, or text. 4Kx42, XDx32, and XDx30 models can display two video zones on screen, while the HDx22, HDx20, and LSx22 models can only display one. There can be multiple zones of other types on the screen. A text zone can contain simple text strings or can be configured to display an RSS feed in a ticker-type display.

As of firmware 6.0.x, zone support is enabled by default. When zones are enabled, the image layer is on top of the video layer by default. The default behavior can be modified using theroVideoMode.SetGraphicsZOrder() method.

Zone support can be disabled by calling EnableZoneSupport(false). When zones are not enabled, the image layer is hidden whenever video is played, and the video layer is hidden whenever images are played.

Event Loops

When writing anything more than a very simple script, an "event loop" will need to be created. Event loops typically have the following structure:

Wait for an event.
Process the event.
Return to step 1.

An event can be any number occurrences: a button has been pressed; a timer has been triggered; a UDP message has been received; a video has finished playing back; etc. By convention, event scripting for BrightScript objects follows this work flow:

An object of the type roMessagePort is created by the user's script.
Objects that can send events (i.e. those that support the ifMessagePort/ifSetMessagePort interface) are instructed to send their events to this message port using the SetPort() method. You can set up multiple message ports and have each event go to its own message port, but it is usually simpler to create one message port and have all the events sent to this one port.
The script waits for an event. The actual function to do this is ifMessagePort.WaitMessage(), but the built-in Wait() statement in BrightScript allows you to do this more easily.
If multiple event types are possible, your script should determine which event the wait function received, then process it. The script then jumps back to the wait.

An event can be generated by any BrightScript Object. For example, the class roControlPort sends events of type roControlDown and roControlUp. The roControlDown implements the ifInt interface, which allows access to an integer. An event loop needs to be aware of the possible events it can receive and be able to process them.