Skip to end of metadata
Go to start of metadata

Table of Contents


Description

The <interface> element defines a set of fields to be exposed by a component, to allow instances of the component to be manipulated externally to the component, while hiding details of the component implementation, in much the same way that C++ classes provide a public interface to objects. For example, a XML component might define a sprite object, and have an integer interface field that specifies which sprite bitmap to be displayed.

The <interface> element may include one or more <field> XML elements. Each <field> XML element defines a top-level field for the XML component. These top-level fields define an interface that allow users of the component to read, write, and observe the fields.

As of the 7.5 Roku OS release, the <interface> element may also include one or more <function> elements.  This provides a mechanism for Roku channels to call functions synchronously, directly from a component. See Functional Fields for more details.

Attributes

The following attributes define each <field> XML element:

AttributeRequiredDescription
idrequiredA string containing the name of the field
typerequired

A string containing the type of the field. The allowable types are BrightScript fundamental types, a SceneGraph node object reference, and a URL identifier type, as follows:

TypeDescription
integer, intBrightScript integer type
floatBrightScript float type
string, strBrightScript string type
Boolean, boolBrightScript Boolean type
vector2dX/Y coordinate array
colorColor type
timeTime type
uriA URL identifier
nodeSceneGraph node object reference
floatarrayArray of float
intarrayArray of integer
boolarrayArray of Boolean
stringarrayArray of string
vector2darrayArray of vector2d
colorarrayArray of color
timearrayArray of time
nodearrayArray of SceneGraph node object reference
assocarrayAssociative array
array

Array of objects - type specifier can be either array or roArray

Available since firmware version 7.5

rect2D

An associative array with 4 float values: (x, y, width, height)

x and y represent the coordinates of the top left corner of the rectangle

Available since firmware version 7.5

rect2DArray

Array of rect2D associative arrays

Available since firmware version 7.5d

aliasoptionalAllows a top-level component field to be declared as an alias of a field in one of the component child nodes. This allows a field of an internal component node to be exposed to users of the component. The attribute is set to a string with format node.field, where node is the ID of a SceneGraph node element, and field is the name of one of the node fields. The type of the component child node field must match the type attribute.
valueoptionalA string representing the initial value of the top-level field. If not specified, the default value for the field type is used (such as, zero for numeric fields, an empty string to string fields, and so forth).
onChangeoptional

Sets an observer call-back function to be added for the top-level field. The value of the attribute is a call-back function name in BrightScript code associated with the component. This attribute is provided as a quick way to set up an observer call-back function for top-level fields. It is equivalent to calling the ifSGNodeField observeField() method in BrightScript code associated with the component as follows:

m.top.ObserveField(fieldName, functionName)

alwaysNotifyoptionalA string with the value true or false that indicates whether the field observer functions should be notified every time the field value is set, or only when the field value changes. By default, the attribute is false, so the observer functions are only notified when the field value changes. Set this attribute to true if the observer function should be notified every time the field value is set even though it doesn't necessarily change.

 

The following attributes define each <function> XML element:

AttributeRequiredDescription
namerequiredA string containing the name of the function which can be called using the callFunc function.

Examples

The following adds two fields as the interface to a component: a uri field, and a SceneGraph node object reference. 

<interface> Element Example

 

The following defines a function named doSomething on the corresponding component interface.

  • No labels