Roku SDK Documentation : MarkupList

Table of Contents

Extends: 

ArrayGrid 

Also See Related Page:

List and Grids Markup - MarkupList Markup

Description

The MarkupList node class is a generic list class that can be used to display a list of items.

The contents of each list item is an instance of an XML component specified by the itemComponentName field value. An instance of the XML component is used to display the data for each item in the list data model. The appearance of the list item as it enters/exits the list focus position can be customized using BrightScript.  

SimpleMarkupList.zip is a sample channel containing a MarkupList where each item is an instance of an XML component. See the section MarkupList XML Component for details.

Example

The following example displays the use of the MarkupList node.

Fields

MarkupList XML Component

The MarkupList node itemComponentName field value should be set to the name of an XML component used to display each item in the list. An instance of this component is created for each visible item in the list.

If the XML component contains interface fields that match the names shown in the table below, those fields will be updated by the MarkupList node. This allows the XML component to alter the item appearance based on changes to these interface fields.

Note that the fields are updated in the order presented in the table below. Any layout scripting you write based on these fields should be done in that order to avoid updating your layout based on a field that has not been updated yet.

Example MarkupList XML Component

The following shows an example MarkupList node XML component. The XML markup defines a component named SimpleListItem that displays a poster as an icon, and two labels on the right for each list item. The labels are arranged vertically, with the top label having a larger font than the bottom one.

To use this component, set the value of the itemComponentName field of a MarkupList node to SimpleListItem.

Note that the index interface field is not used by the component, so it is not included in the component interface.

Also note how the focusPercent interface field has an onChange function defined that changes the color of the label text as the item enters/leaves the focus region of the list.

<?xml version="1.0" encoding="utf-8" ?>

<component name="SimpleListItem" extends="Group">

<interface> 
  <field id="width" type="float" onChange="widthChanged"/> 
  <field id="height" type="float" onChange="heightChanged"/> 
  <field id="itemContent" type="node" onChange="itemContentChanged"/> 
  <field id="focusPercent" type="float" onChange="focusPercentChanged"/> 
  <field id="listHasFocus" type="bool" onChange="focusPercentChanged"/> 
</interface>

<script type="text/brightscript" >
<![CDATA[ 
  function itemContentChanged() 
    m.itemImage.uri = m.top.itemContent.HDPOSTERURL
    m.itemText.text = m.top.itemContent.TITLE
    m.itemArtist.text = m.top.itemContent.ARTISTS[0] 
    updateLayout()
  end function

  function widthChanged() 
    updateLayout()
  end function

  function heightChanged() 
    updateLayout()
  end function

  function focusPercentChanged() 
    if m.top.listHasFocus and m.top.focusPercent > 0.5 
      m.itemText.color = "0x000000FF" 
    else 
      m.itemText.color = "0xFFFFFFFF" 
    end if 
    m.itemArtist.color = m.itemText.color
  end function

  function updateLayout() 
    if m.top.height > 0 and m.top.width > 0 
      posterSize = m.top.height
      m.itemImage.width = m.top.height - 20 ' make the posters square 
      m.itemImage.height = m.top.height - 20
      m.itemText.width = m.top.width - m.itemImage.width - 20 
      m.itemArtist.width = m.top.width - m.itemImage.width - 20 
    end if
  end function

  function init() 
    m.itemText = m.top.findNode("itemText") 
    m.itemArtist = m.top.findNode("itemArtist") 
    m.itemImage = m.top.findNode("itemImage")
    m.playIcon = m.top.findNode("playIcon")
  end function
]]>
</script>

<children>

<LayoutGroup layoutDirection="horizontal" vertAlignment="center" itemSpacings="20" translation="[0,34]" > 
  <Poster id="itemImage" /> 
  <LayoutGroup layoutDirection="vertical" horizAlignment="left" itemSpacings="0" > 
     <Label id="itemText" font="theme:MediumSystemFont" /> 
     <Label id="itemArtist" font="theme:SmallestSystemFont" /> 
   </LayoutGroup>
</LayoutGroup>

</children>
</component>

Data Bindings

A MarkupList node should have a single ContentNode node as the root node in its content field. The structure of the rest of the data model depends on whether or not the list items are to be grouped into sections.

List Items Not Grouped Into Sections

If the list items are not to be grouped into sections, one child ContentNode node should be added to the root node for each item in the list (these child nodes can be thought of as item nodes). Item nodes should contain the data required by the MarkupList node XML component.

List Items Grouped Into Sections

If the list items are to be grouped into sections, one child ContentNode node should be added to the root node for each section in the list (these child nodes can be thought of as section roots). Each section root should contain one child ContentNode node for each item in the section (that is, item nodes). The item nodes should contain the data required by the MarkupList node XML component.

The section root ContentNode nodes use the following attributes: