Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 9 Next »

 

Extends: MaskGroup 

Description

The RowList node is a list of independently scrollable rows of posters. Each item in the list contains a row of posters that can be scrolled left/right independently of the other rows. The posters in any single row must be the same size, but the posters in different rows of the list can have different sizes. In addition to the posters, each row may contain a right-justified title label and a left-justified label that displays a "1 of N" message, indicating which poster in the row currently has the focus.

There are two horizontal scrolling options for the RowList node controlled by the rowFocusAnimationStyle field. Setting the rowFocusAnimationStyle field to "floatingFocus" causes the focus indicator to float left or right until it reaches the end of the row, at which point the focus will stay fixed on the first or last item in the row and the items will scroll left or right. Setting the rowFocusAnimationStyle field to "fixedFocusWrap" cause each row to wrap around when navigation reaches the first or last item in the row, as long as the row contains enough items to fill the row. If the row does not contain enough items to fill the row, the focus will float left and right.

The RowList node supports two variations. The first variation provides a simple option for the common case where each item in each row is displayed as a single bitmap. The second variation allows the contents of each item in each row to be an instance of an SDK2 component that defines a set of interface fields that provide for communication between the RowList node and the items is displays, similar to that used by the MarkupList and MarkupGrid node. In the documentation below, the first variation is referred to as the "simple item case" and the second variation is referred to as the "component item case"

Fields

FieldTypeDefaultUsed for Simple Items and/or Component ItemsUse
contentContentNodenoneBoth

Specifies the content for the list. The content should be a single ContentNode that has one child ContentNode for each row in the RowList. These child ContentNode's for each row should themselves contains child ContentNode's for each item in the row.

See the Data Bindings section below for more details. 

rowItemSelectedarray of integer[ ]BothRead-Only
When an item is selected, rowItemSelected is set to a 2-element array where element 0 contains the index of the row containing the selected item and element 1 contains the index of the selected item in that row.
rowItemFocusedarray of integer[ ]Both Read-Only
When an item gains the key focus, rowItemFocused is set to a 2-element array where element 0 contains the index of the focused row and element 1 contains the index of the focused item in that row.
itemSelectedinteger0BothRead-Only
When an item is selected, itemSelected is set to the index of the selected row.
itemFocusedinteger0BothRead-Only
When a row gains the key focus, itemFocused is set to the index of the focused row.
itemUnfocusedinteger0BothRead-Only
When a row loses the key focus, itemFocused is set to the index of the unfocused row.
jumpToIteminteger0BothWrite-Only
When set to a valid item index, this causes the list to immediately update so that the specified row moves into the focus position
animateToIteminteger0BothWrite-Only
When set to a valid item index, this causes the list to quickly scroll so that the specified row moves into the focus position
itemSizeVector2D[0, 0]BothSpecifies the width and height of rows in the list. Note that this the width of the entire row, not the width of the posters in the row.
itemSpacingVector2D[0, 0]BothA vector specifying the spacing between rows in the list. The y-component of the vector (i.e. array index 1) specifies the vertical spacing between rows. the x-component of the vector is ignored.
numRowsinteger0BothSpecifies the number of visible rows in the list. 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.
rowHeightsarray of floats[ ]Both

When specified, the rowHeights field specifies the heights of each row of the list. This allows the height of each row of the grid to vary from row to row.

The rowHeights values override the height specified in element 1 of the itemSize field. If the rowHeights array contains fewer elements than the number of rows in the data model, element 1 of the itemSize field is used as the height of the excess rows.

rowSpacingsarray of floats[ ]Both

When specified, the rowSpacings field specifies the spacing after each row of the list. This allows the spacing between rows to vary from row to row.

The rowSpacings values override the vertical spacing specified in element 1 of the itemSpacing field. If the rowSpacings array contains fewer elements than the number of rows in the data model, element 1 of the itemSpacing field is used as the spacing after the excess rows.

rowItemSizearray of Vector2D's[ ]Both

Specifies the width and height of the items in each row. The array of values must include at least one element.

If the array contains fewer elements than the number of rows in the data model, the last value in the array is used as the size for the excess rows.

rowItemSpacingarray of Vector2D's[ ]Both

Specifies the spacing between items in each row. The x-component (i.e. array index 0) of each Vector2D in the array specifies the horizontal spacing between posters in the corresponding row.

If the array contains fewer elements than the number of rows in the data model, the last value in the array is used as the spacing for the excess rows. If the array contains no values, no space will be included between posters in all rows.

focusXOffsetarray of floats[ ]Both

Specifies the X offset of the first fully visible item in each row relative to the left edge of the list.

In most cases, the first fully visible item in each row will be positioned at the left edge of the list, so this field does not need to be specified.

If the array contains fewer elements than the number of rows in the data model, the last value in the array is used as the X offset for the excess rows. If the array contains no values, the default X offset of 0.0, is used.

rowLabelOffsetarray of Vector2D's[ ]Both

Specifies the offset of the row label for each row. The X component specifies the horizontal offset of the label from the left edge of the row. The Y component specifies the vertical spacing between the label and the posters in the row.

If the array contains fewer elements than the number of rows in the data model, the last value in the array is used as the offset for the labesl of the excess rows. If the array contains no values, an offset of [ 0, 0 ] is used.

showRowLabelarray of boolean's[ ]Both

Specifies whether the row label on the left edge of each row is displayed.

If the array contains fewer elements than the number of rows in the data model, the last value in array is used to control the display of the row label for the excess rows. If the array contains no values, no row labels are displayed.

showRowCounterarray of boolean's[ ]Both

Specifies whether the "1 of N" label on the right edge of each row is displayed. Note that the "1 of N" label is only displayed for the focused row even if the showRowCounter value for that row is true.

If the array contains fewer elements than the number of rows in the data model, the last value in array is used to control the display of the "1 of N" label for the excess rows. If the array contains no values, no "1 of N" labels are displayed.

rowFocusAnimationStylestring"floatingFocus"Both

Specifies the scrolling behavior for each row of the grid.

Setting the rowFocusAnimationStyle field to "floatingFocus" causes the focus indicator to float left or right until it reaches the end of the row, at which point the focus will stay fixed on the first or last item in the row and the items will scroll left or right.

Setting the rowFocusAnimationStyle field to "fixedFocusWrap" cause each row to wrap around when navigation reaches the first or last item in the row, as long as the row contains enough items to fill the row. If the row does not contain enough items to fill the row, the focus will float left and right.

rowLabelColorColor0xFFFFFFFFBothSpecifies the color of the row and "1 on N" labels
rowLabelFontFontThe theme's DefaultText fontBothSpecifies the font for the row and "1 of N" labels
drawFocusFeedbackOnTopbooleanfalseBothSpecifies whether the focus indicator bitmap is drawn below or on top of the list items
drawFocusFeedbackbooleantrueBothSpecifies whether or not the focus indicator bitmap is displayed
focusBitmapUriBitmaptheme:LabelListFocusBitmapBothSpecifies 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.
focusFootprintBitmapUristringtheme:LabelListFocusFootprintBitmapBothSpecifies 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.
wrapDividerBitmapUristringtheme:ListDividerBitmapBothSpecifies 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.
wrapDividerHeightfloattheme:LabelListDividerHeightBoth

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]) 

loadingBitmapUristring""Simple Items OnlySpecifies a bitmap file to display while a grid item's poster is loading.
loadingBitmapOpacityfloat1.0Simple Items OnlySpecifies an opacity value used to render the loading bitmap
failedBitmapUristring""Simple Items OnlySpecifies a bitmap file to display when a grid item's poster fails to load
failedBitmapOpacityfloat1.0Simple Items OnlySpecifies an opacity value used to render the failed bitmap
imageWellBitmapUristring""Simple Items OnlySpecifies the bitmap file to use to suggest where images would appear for empty lists.
itemComponentNamestring""Component Items OnlySpecifies the name of a XML component for the items in each row. An instance of this component is created on demand for each visible item of each row. The XML component must define a specific interface as detailed below.

RowList XML Component (RowList Nodes That Use Component Items Only)

The RowList itemComponentName field should contain the name of an XML component to be used to display each item in the grid's data model. An instance of this component is created for each visible item in each row of 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 RowList. This allows the XML Component to alter the item's appearance based on changes to these interface fields.

Field NameField TypeDescription
itemContentContentNodeContains the data to be displayed by the item. The relationship between data in the ContentNode and the visual elements of the item is determined by the scripts in the item's XML component. Typically, an observer of the itemContent field is used to update the list item when then content changes.
widthfloatRead-Only
Set to the width of the item.
heightfloatRead-Only
Set to the height of the item
indexintRead-Only
Set to the data model index within the data for the row of the RowList that contains this item. For example, if this appeared in row 2 of the RowList, then the index field would be set to 0 for the first item in row 2, 1 for the second item in row 2, etc.
rowIndexintRead-Only
Set to the data model index of the row thata contains this item
focusPercentfloatRead-Only
Set to the percent (0.0 to 1.0) that this list item overlaps the focus region of the grid. This value can be used with scripts or interpolators to smoothly animate the appearance of the grid item as it enters/leaves the focus region.
rowFocusPercentfloatRead-Only
Set to the percent (0.0 to 1.0) that the row that contains this item overlaps the focus region of the list
rowHasFocusboolRead-Only
Set to true if the row that contains this item has focus, false otherwise.
rowListHasFocusboolRead-Only
Set to true if the item's RowList has focus, false otherwise.

Theme Attributes

TBD Need to fill out this table TBD

Data Bindings

The data model for the RowList node should have a single ContentNode as the root node. One child ContentNode should be added to the root node for each row in the list (these nodes will be referred to as "row nodes"). Each row node should contain one child ContentNode for each item in the row (these nodes will be referred to as "item nodes").

Row Node Data Bindings

AttributeTypeDescription
TITLEstringThe label for the row.

Item Node Data Bindings (For RowList Nodes That Use Simple Items Only)
 

AttributeTypeDescription
HDGRIDPOSTERURL / HDPOSTERURLstringThe image file for the item's poster when the screen resolution is set to HD. HDGRIDPOSTERURL is used if non-empty. HDPOSTERURL is used otherwise.
SDGRIDPOSTERURL / SDPOSTERURLstringThe image file for the item's poster when the screen resolution is set to SD. SDGRIDPOSTERURL is used if non-empty. SDPOSTERURL is used otherwise.
  • No labels