The MarkupList node class provides a customizable list that can include multiple graphic images and labels, in virtually any type of design and configuration for the list items.
MarkupListExample.zip is a list where each item has two graphic images (an icon and a small poster image), a label, and a custom underline focus indicator:
The method to configure a custom list like this is to have a separate component definition of the appearance and behavior of the list items. The name of this component is set as the
itemComponentName field value of the MarkupList node. Then as the user moves focus to an individual item in the list, the appearance and behavior of the item is configured according to the item component scripting. In the example, as each item is focused, the red underline focus indicator appears, along with the small poster image. The icon, label, and small poster image for each item are contained in the ContentNode node set as the
content field value of the MarkupList node, the same way the graphic images and other content meta-data are set in PosterGrid Markup.
markuplistscene.xml, we define the basic dimensions and configuration of the MarkupList node in the <children> element in a way that is similar to how lists and grids were defined in LabelList Markup and PosterGrid Markup. In addition to the
itemComponentName field where we set name of the component with the list item configuration, we set the
itemSize field (similar to the
basePosterSize field of a PosterGrid node) and the
itemSpacing field (identical to the PosterGrid node
Then we set the
drawFocusFeedback field to false, since we will be using a custom underline focus indicator, and set
floatingFocus (again, these fields are the same as in the LabelList node and several other list and grid nodes).
Now let's look at
markuplistitem.xml, which is the list item configuration component file:
The <children> element of
markuplistitem.xml contains the renderable nodes that will be in each list item. It's a typical markup for renderable nodes as described in Renderable Node Markup, except for a couple of things. Note that we don't supply a
uri field value for the Poster nodes, or a text field value for the Label node. We do provide an ID for each renderable node, because we intend to supply the missing field values in the <script> element using BrightScript.
As the ContentNode node for the list is set, and a user moves focus to an item in the list, the <interface> element fields are updated by the MarkupList node to the value for that item. So to script the custom appearance and behavior of the list items, we set observers on the relevant <interface> fields using the
onChange attribute to identify the callback functions triggered by the field value change:
When the ContentNode node for the list is set, the
itemContent field value change triggers the
showcontent() callback function, and
focusPercent field value change triggers the
showfocus() callback function. The
showcontent() callback function sets the URL of the each item icon and the small poster image, and the text of the item label, according the attributes in the child ContentNode node for the item:
showfocus() callback function makes visible the custom red underline focus indicator and the small poster image when the item is focused:
showfocus() callback function makes use of the
focusPercent field value, which varies from 0 to 1.0 as focus moves to the item, and from 1.0 to 0 as focus leaves the item. Since this varying value has the identical range as the
key field range of an Animation node (see Animation Markup), this field value can be used as an animation "key" to smoothly "fade" in and out an item element as focus moves to and from the item. In this example, we key the cursor and small poster image opacity to the value of the
This method of creating a custom list or grid item appearance is used in the MarkupGrid and RowList nodes too, so spend a little time now to understand how it works...