Skip to end of metadata
Go to start of metadata

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

FieldTypeDefaultUse
itemComponentNamestring""Specifies the name of a XML component for the list items. An instance of this component is created on demand for each visible item of the list. The XML component must define a specific interface as detailed in MarkupList XML Component below.
contentContentNodenoneSpecifies the content for the list. The binding between the data model defined by the ContentNode node and its child nodes and the visual elements of the MarkupList node XML component are determined by the scripting in the component. See Data Bindings below for more details.
itemSizevector2d[0,0]Specifies the width and height of each item in the list
itemSpacingvector2d[0,0]The second value of the vector specifies the vertical spacing between items in the list. The first value of the vector is ignored.
numRowsinteger12Specifies the number of visible rows displayed. Note that the actual number of rows may be more or less than the number of visible rows depending on the number of items in the list's content.
drawFocusFeedbackBooleantrueSpecifies whether or not the focus indicator bitmap is displayed
drawFocusFeedbackOnTopBooleanfalseSpecifies whether the focus indicator bitmap is drawn below or on top of the list items
focusBitmapUriuri

""

Specifies the bitmap file used for the focus indicator when the list has focus. In most cases, this should be a 9-patch image that specifies both expandable regions as well as margins. Only set this field to specify a custom bitmap that differs in appearance from the default bitmap.
focusFootprintBitmapUriuri

""

Specifies the bitmap file used for the focus indicator when the list does not have focus. In most cases, this should be a 9-patch image that specifies both expandable regions as well as margins. Only set this field to specify a custom bitmap that differs in appearance from the default bitmap.
focusBitmapBlendColorcolor0xFFFFFFFFBlend the graphic image specified by focusBitmapUri with the specified color. If set to the default, 0xFFFFFFFF, no color blending will occur. Set this field to show a focus indicator graphic image with a different color than the image specified by focusBitmapUri.
focusFootprintBlendColorcolor 0xFFFFFFFFBlend the graphic image specified by focusFootprintBitmapUri with the specified color. If set to the default, 0xFFFFFFFF, no color blending will occur. Set this field to show a focus footprint indicator graphic image with a different color than the image specified by focusFootprintBitmapUri.
wrapDividerBitmapUriuri

""

Specifies the bitmap file to use as a visual separator between the last and first list items when the list wraps. In most case, this should be a 9-patch image that specifies both expandable regions. Only set this field to specify a custom bitmap that differs in appearance from the default bitmap.
wrapDividerHeightfloat

24

Specifies the height of the divider. The wrapDividerBitmap will be scaled to this height.

The width of the wrap divider is set to the width of the list items (i.e. itemSize[0]) 

sectionDividerBitmapUristring

""

Specifies the bitmap file to use as visual separator between sections of the grid. The section dividers can include an icon and a label in addition to the section divider bitmap.

Note that for sections that do not contain an icon or a title, the wrapDividerBitmapUri is used for the section dividers instead.

sectionDividerFontfont

system default

Specifies the font for section divider labels

sectionDividerTextColorcolor

0xddddddff

Specifies the text color for section divider labels
sectionDividerSpacingfloat

10

Specifies the spacing between the items appearing in the section divider (e.g. the spacing between the section divider icon, the section divider label, and the section divider bitmap). Note the section divider does not always include an icon and/or a title.
sectionDividerHeightfloat

40

Specifies the height of the section dividers.

The width of the section dividers is determined by the width of the list items (e.g. itemSize[0]) and the sectionDividerLeftOffset field.

sectionDividerMinWidthfloat

117

Specifies the minimum width of the section divider bitmap. The section divider label will be ellipsized if necessary in order to ensure that the section divider bitmap meets the minimum width.
sectionDividerLeftOffsetfloat

0

Number of pixels to offset the left edge of the section divider relative to the left edge of the list items.
itemSelectedinteger0Read-Only
When a list item is selected, itemSelected is set to the index of the selected item.
itemFocusedinteger0Read-Only
When a list item gains the key focus, itemFocused is set to the index of the focused item.
itemUnfocusedinteger0Read-Only
When a list item loses the key focus, itemFocused is set to the index of the unfocused item.
jumpToIteminteger0Write-Only
When set to a valid item index, this causes the list to immediately update so that the specified index moves into the focus position.
animateToIteminteger0Write-Only
When set to a valid item index, this causes the list to quickly scroll so that the specified index moves into the focus position.

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.

Field NameField TypeDescription
widthfloatRead-Only
Set to the width of the list item.
heightfloatRead-Only
Set to the height of the list item
indexintegerRead-Only
Set to the index of this item in the data model.
listHasFocusBooleanRead-Only
Set to true if the MarkupList node has focus, false otherwise.
itemContentContentNodeContains the data to be displayed by the list item. The relationship between data in the ContentNode node and the visual elements of the list item is determined by the scripts in the item XML component. Typically, an observer of the itemContent field is used to update the list item when the content changes.
focusPercentfloatRead-Only
The fractional value, from 0.0 to 1.0, of a time delay after focus has moved from one item to the next. The fractional value increases incrementally from 0.0 to 1.0 for the newly-focused item, while simultaneously decreasing from 1.0 to 0.0 for the previously-focused item. This value can be used as a timing key to smoothly animate the appearance of the focused item as well as the previously-focused item, to indicate the movement of focus to the user.
itemHasFocusBoolean

Available since firmware version 8.

Read-Only
Indicates whether the item component currently is the MarkupList's focused item. When scrolling starts, the itemHasFocus field for the currently focused item is set to false. When scrolling ends, the itemHasFocus field for the newly focused item is set to true. During the scrolling animation, all itemHasFocus fields are set to false.

Only one item component of any MarkupList should have itemHasFocus set to true. If the MarkupList does not focus, all itemHasFocus fields of their item components should be set to false.

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.

Markup List XML Component Example

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:

AttributeTypeDescription
CONTENTTYPEstringMust be set to SECTION
TITLEstringLabel for the section divider
HDGRIDPOSTERURLuriThe image file for the icon to be displayed to the left of the section label when the screen resolution is set to HD.
SDGRIDPOSTERURLuriThe image file for the icon to be displayed to the left of the section label when the screen resolution is set to SD.

 

 

  • No labels