Roku SDK Documentation : MarkupGrid

Table of Contents

Extends:

ArrayGrid 

Also See Related Page:

List and Grids Markup - MarkupGrid Markup

Description

The MarkupGrid node class is a  is a generic grid class that can be used to display a set of items arranged into a 2D grid. The contents of each grid item is an instance of an XML component specified by the itemComponentName field. An instance of the XML component is used to display the data for each item in the grid data model. The appearance of the grid item as it enters/exits the grid focus position can be customized using scripting. SimpleMarkupList.zip is a sample channel containing a MarkupGrid where each item is an instance of an XML component. See the section MarkupGrid XML Component for details.

The number of columns in the MarkupGrid node is fixed and the number of rows varies as needed to display all of the items in the grid data model. The items in the grid fill each row from left to right, then top to bottom. For example, if the grid data contains 8 items and the number of columns is set to 3, then items 1, 2 and 3 will be in the first row. Items 4, 5 and 6 will be in the second row. The third row will contain items 7 and 8 in the leftmost two columns and blank space in the right column.

The layout of rows and columns in the grid is very flexible. Possible layouts include:

• a simple layout with all items in the grid having the same size
• a layout with the items in some rows having varying heights and/or the items in some columns having varying widths
• a layout with varying width rows and columns and items that occupy one or more rows and columns

The grid items can be organized into sections that are demarcated by labelled horizontal divider lines between the sections.

Example

The following is an example using MarkupGrid.

Grid Layouts

The MarkupGrid class supports very flexible layouts. The philosophy is that simple layouts are easy to produce and complicated layouts are possible.

There are three general categories of layouts:

1. Simple layouts with all grid items and spacings between items equal.
   
   To specify a simple layout, set the itemSize field value to the width and height of each of the items in the grid, and set the itemSpacing field value to the desired spacing between items. For example, if the itemSize field value is [300,100],and itemSpacing field value is [4,8], then the grid items will be 300 pixels wide and 100 pixels high. There will be four pixels between the columns of the grid, and eight pixels between rows of the grid.
   
   

2. All the items are aligned in rows and columns, but the rows and columns (or the spacing between them) varies.
   
   To specify this type of layout, set the columnWidths, columnSpacings, rowHeights and rowSpacings field values. Each of these fields takes an array of values, specifying the values for each row width, column height or spacing between rows and columns. If there are more rows or columns in the grid than specified in the arrays for these fields, the corresponding simple layout field values are used for the missing values (such as the x-dimension value of the itemSize field for a missing columnWidth field value). 
   
   For example, suppose a grid is designed with four columns, where each item was 80 pixels wide, and had four pixels of space between them. The grid data includes ten rows, where the first four rows have items that are 120 pixels tall, and the remaining six rows have items that are 80 pixels high. All the rows should have six pixels of space between them. To specify this layout, you would set the field values like this:
   
   

   Field	Value
   itemSize	[80,80]
   itemSpacing	[4,6]
   rowHeights	[120,120,120,120,80,80,80,80,80,80]

   Since the final six values in the rowHeights field value array equal the y-dimension itemSize field value, you could omit them, so in this case setting the rowHeights field value to [120,120,120,120] would have the same result.
3. There are clear alignments in the row/column layout, but some items can span more than one row or column (plus the space in between).
   
   To specify this type of layout, set the field values as in the first two types of grid layouts to define the sizes of the rows/columns. If any of the grid items occupy more than one row or column, then the metadata for each grid item must contain extra metadata specifying the starting row, starting column, numbers of rows and number of columns that the item occupies. In addition, the fixedLayout field value must be set to true.
   
   For example, if a grid item is supposed to span columns 2 and 3, and rows 3 through 6, then in addition to the metadata for the item contents, the metadata for that item would include (X = 2, Y = 3, W = 2, H = 4). W is set to 2 because the item is 2 columns wide. Similarly H is set to 4 because the item is 4 rows tall.
   
   The total pixel width of the item would be the (width of column 2) + (spacing between columns 2 and 3) + (width of column 3). Similarly, the height of the item would be the sum of the heights of columns 3, 4, 5 and 6, plus the spacings between columns 3 and 4, 4 and 5, and 5 and 6.
   
   The X and Y indices start from 0 (that is, the first column is X = 0).

Fields

MarkupGrid XML Component

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

If the XML component contains interface fields that match the names shown in the table below, those fields will be updated by the MarkupGrid 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 MarkupGrid XML Component

The following shows an example MarkupGrid node XML component. The XML markup defines a component named SimpleGridItem that creates a poster for each grid item. The poster has either a price or an icon overlaid on top of it, depending on the value of the GOTITEMCONTENT attribute of the item ContentNode node. If GOTITEMCONTENT is true, that indicates that the item has already been purchased, and an icon is drawn on top of the lower/right corner of the poster. If GOTITEMCONTENT is false, that indicates that the item has not already been purchased. In that case, a semitransparent rectangle is drawn over the bottom part of the poster, and inside that rectangle, a label is drawn containing the price of the item.

To use this component, set the value of the itemComponentName field of a MarkupGrid node to SimpleGridItem.

Note that the index and focusPercent interface fields are not used by the component, so they are not included in the component interface.

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

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

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

<script type="text/brightscript" > 
<![CDATA[ 
  function itemContentChanged() 
    m.gridPoster.uri = m.top.itemContent.HDPOSTERURL
    if m.top.itemContent.GOTITEMCONTENT
      m.priceBox.visible = false 
      m.priceLabel.visible = false 
      m.ownedIcon.visible = true 
    else 
      m.priceLabel.text = m.top.itemContent.PRICE
      m.priceBox.visible = true 
      m.priceLabel.visible = true 
      m.ownedIcon.visible = false 
    end if 
    updateLayout() 
  end function 

  function widthChanged() 
    updateLayout() 
  end function 

  function heightChanged() 
    updateLayout() 
  end function 

  function updateLayout() 
    if m.top.height > 0 and m.top.width > 0 
      posterSize = m.top.height 
      m.gridPoster.width = m.top.width 
      m.gridPoster.height = m.top.height 
      ' position the ownedIcon in the bottom/right corner 
      m.ownedIcon.translation = [ m.top.width - m.ownedIcon.bitmapWidth, m.top.height - m.ownedIcon.bitmapHeight ] 
      m.priceBox.width = m.top.width 
      m.priceBox.height = m.ownedIcon.bitmapHeight 
      m.priceBox.translation = [ 0, m.top.height - m.priceBox.height ] 
      m.priceLabel.width = m.top.width 
      m.priceLabel.height = m.priceBox.height 
      m.priceLabel.vertAlign = "center" 
      m.priceLabel.horizAlign = "center" 
      m.priceLabel.translation = m.priceBox.translation 
    end if 
  end function 

  function init() 
    m.gridPoster = m.top.findNode("gridPoster") 
    m.priceBox = m.top.findNode("priceBox") 
    m.priceLabel = m.top.findNode("priceLabel") 
    m.ownedIcon = m.top.findNode("ownedIcon") 
    m.ownedIcon.loadSync = true 
    m.ownedIcon.uri = "pkg:/images/greenCheck.png" 
  end function 
]]> 
</script> 

<children>

<Poster id="gridPoster" renderPass="1" /> 
<Rectangle id="priceBox" color="0x00000080" renderPass="2" /> 
<Label id="priceLabel" renderPass="3" /> 
<Poster id="ownedIcon" renderPass="4" />

</children>

</component>

Data Bindings

A MarkupGrid 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 grid items are to be grouped into sections.

List Items Not Grouped Into Sections

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

List Items Grouped Into Sections

If the grid items are to be grouped into sections, one child ContentNode node should be added to the root node for each section in the grid (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 MarkupGrid node XML component.

The section root ContentNode nodes use the following attributes: