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:
| Attribute | Required | Description | ||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | required | A string containing the name of the field | ||||||||||||||||||||||||||||||||||||||||||||
| type | required | 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:
| ||||||||||||||||||||||||||||||||||||||||||||
| alias | optional | Allows 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. | ||||||||||||||||||||||||||||||||||||||||||||
| value | optional | A 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). | ||||||||||||||||||||||||||||||||||||||||||||
| onChange | optional | 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
| ||||||||||||||||||||||||||||||||||||||||||||
| alwaysNotify | optional | A 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:
| Attribute | Required | Description |
|---|---|---|
| name | required | A 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> <field id = "contenturi" type = "uri" /> <field id = "content" type = "node" /> </interface>
The following defines a function named doSomething on the corresponding component interface.
<interface>
<function name="doSomething" />
</interface>