Skip to end of metadata
Go to start of metadata

Table of Contents


Extends:

ArrayGrid

Also See Related Page:

List and Grids Markup - LabelList Markup

Description

The LabelList node class is a simple list class that can be used to display a list of items. Each item can include a text string and an optional icon positioned to the left of the text string.

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

In most cases, you will want to populate the content of a LabelList (or other similar components like PosterGrids, etc.) from a content feed, web service API, or some other dynamic data source.  However, to illustrate the basics of how a LabelList is constructed and used, here is a simple example of creating a LabelList and populating it with static data.  Static data in a LabelList may be useful for channel screens such as settings or menus with fixed items.

Static LabelList Configuration

Example

This code renders the LabelList shown below.  

In this screen shot, the user has scrolled down one item to highlight "Drama" showing the separator after the last list item.


Fields

FieldTypeDefaultUse
contentContentNodenoneSpecifies the content for the list. See Data Bindings below for more details.
If the data contains section markers, section dividers will be drawn between each section. These section dividers may contain an icon and/or a string. 
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. The actual number of rows may be more or less than the number of visible rows specified depending on the number of items in the list content.
textHorizAlignoption stringleft

Specifies the horizontal alignment of the text in the list item area specified by the itemSize field value (the text is always centered vertically in the list item area). The possible options are:

OptionEffect
leftText is left-aligned
rightText is right-aligned
centerText is center-aligned
colorcolor

0xddddddff

Specifies the text color for unfocused list items
focusedColorcolor

0x262626ff

Specifies the text color for focused list items

fontfont

system default

Specifies the font for unfocused list items
focusedFontfont

system default

Specifies the font for focused list items
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
vertFocusAnimationStyle

string

fixedFocusWrap

Specifies the how the focus indicator moves in a list of items in response to the remote direction pad Up and Down key presses. The possible values are:

OptionEffect
fixedFocusWrapCauses the focus indicator to float up or down until it reaches the end of the list, at which point the focus indicator will stay fixed on the first or last item in the list, and the items will scroll up or down if there are items that were not visible.
floatingFocusCauses the list to wrap around when the focus indicator reaches the first or last item in the list, as long as the list contains enough items to fill the list. If the list does not contain enough items to fill the list, the focus indicator will float up and down.
focusRowinteger0Specifies the row that will have fixed focus if the vertFocusAnimationStyle field value is set to fixedFocusWrap.
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.
focusFootprintBlendColorcolor0xFFFFFFFFBlend 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 wrap divider, the visual separator between the last and first list items when the list wraps. In most cases, 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

0.0

Specifies the height of the wrap divider, the visual separator between the last and first list items when the list wraps. The bitmap for the wrap divider is scaled to this height. The width of the wrap divider is set to the width of the list items as specified by the itemSize field width value.

sectionDividerBitmapUriuri

""

Specifies the bitmap file to use as visual separator between sections of the list. The section dividers can include an icon and a label in addition to the section divider bitmap. Only set this field to specify a custom bitmap that differs in appearance from the default bitmap. For sections that do not contain an icon or a title, the bitmap for the wrap divider 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

If the ContentNode node specifies sections for a list or grid, and the section dividers are specified to include an icon and/or a label, specifies the spacing between the icon, label, and section divider bitmap.
sectionDividerHeightfloat

40

Specifies the height of the section dividers. The width of the section dividers is determined by the width of the list items as specified by the itemSize field width value.

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, set to the index of the selected item.
itemFocusedinteger0Read-Only
When a list item gains the key focus, set to the index of the focused item.
itemUnfocusedinteger0Read-Only
When a list item loses the key focus, 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.

Data Bindings

The data model for the LabelList 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 Being 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 have their ContentNode attributes set as shown in the table below.

AttributeTypeDescription
TITLEstringThe label for the list item
HDLISTITEMICONURLuriThe image file for the icon to be displayed to the left of the list item label when the list item is not focused
HDLISTITEMICONSELECTEDURLuriThe image file for the icon to be displayed to the left of the list item label when the list item is focused

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). Each item ContentNode node uses the same attributes as the item nodes when there are no sections, as shown in the table above.

The section root ContentNode nodes use the following attributes:

AttributeTypeDescription
CONTENTTYPE

string

Must 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