Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

FieldTypeDefaultUse
contentContentNodeinvalidSpecifies the content for the list. The content should be a single ContentNode that has one child ContentNode for each row. These child ContentNodes for each row should themselves contains child ContentNodes for each item in the row. See ZoomRowList Data below for more details. 
itemComponentNamestring""Specifies the name of an 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 Item Component Fields below
rowWidth

float

0.0

This specifies a "safe" width for the row. Currently, it's only used if the displayed width of the zoomed Item's exceeds this width. If that occurs, the items in the row will wrap horizontally.

Once full floating focus functionality is added in a subsequent release, this will be used to specify the rightmost limit that the focus can reach as focus floats from left to right.

rowHeightarray of float[ ]Specifies the height of the ZoomRowItem when the row is not zoomed. Note that this includes the height of the Row and its Decorations. At least one value must be specified.
rowZoomHeight

array of float[ ]

Specifies the height of the ZoomRowItem when the row is zoomed. As the row gains focus, the height of its ZoomRowItem will smoothly change from the row's itemHeight to the row's rowZoomHeight.

If no values are specified, none of the rows zoom.

spacingAfterRow

float0.0

Specifies the spacing between rows of the ZoomRowList. Note that this spacing value is not scaled by the zoomPercent.

itemClippingRectRect2D

AA with x, y, width, height set to zero

Specifies a clipping region for the ZoomRowItem's rendered. This provides control over which items are visible. For example, if the left value is set to a negative number, items to the left of the grid's item origin will be visible.

For best performance, this should be set so that the itemClippingRect exactly matches what's visible onscreen.

If this field is not set, heuristics are used to determine an acceptable clipping rectangle for the items in the ZoomRowList.This field will have the same value as rowFocusPercent unless the remainZoomedAboveFocus field is set to "never" or if the zoomed and un-zoomed height of a row are equal.

rowItemYOffset

array of float[ ]

This specifies the vertical position of the Row relative to the top of its ZoomRowItem when the row is unfocused.

Combined with rowZoomYOffset, this allows the vertical position of the ZoomRowItem's Row to smoothly change relative to the top of the ZoomRowItem as the ZoomRowItem gains or loses focus.

rowItemZoomYOffset

array of float[ ]

This specifies the vertical position of the Row relative to the top of its ZoomRowItem when the row is focused (i.e. zoomed).

Combined with rowYOffset, this allows the vertical position of the ZoomRowItem's Row to smoothly change relative to the top of the ZoomRowItem as the ZoomRowItem gains or loses focus.

rowItemHeight

array of float[ ]

This specifies the height of each Item in a Row when the row is unfocused.

Combined with rowZoomItemHeight, this allows the height of each Item in a Row to be scaled differently than the height of the Row's ZoomRowItem. As the ZoomRowItem gains or loses focus, the height of each Item in the Row smoothly interpolated between the rowItemHeight and rowZoomItemHeight for that row.

rowItemZoomHeight

array of float[ ]

This specifies the height of each Item in a Row when the row is focused (i.e. zoomed).

Combined with rowZoomItemHeight, this allows the height of each Item in a Row to be scaled differently than the height of the Row's ZoomRowItem. As the ZoomRowItem gains or loses focus, the height of each Item in the Row smoothly interpolated between the rowItemHeight and rowZoomItemHeight for that row.

rowItemAspectRatio

array of float[ ]

This specifies the aspect ratio of the Items in a Row. This is used to compute the width of the Item's based on the interpolated row item height (see the rowItemHeight and rowZoomItemHeight fields above).

If useDefaultAspectRatio is true for that row, then the rowItemAspectRatio value is used to compute the width of each Item in the Row. If false, then if the ContentNode for the Item includes an aspectRatio field, that value is used. This allows different items in a Row to have different aspect ratios.

The rowItemAspectRatio values should be a floating point values that represent the ratio of the Item's width to height. For example, if the Item should have a 16 x 9 aspect ratio, this value specified would by 1.7777778 ( = 16 / 9).

spacingAfterRowItemarray of float[ ]This specifies the horizontal spacing between Items in a Row. When the row is unfocused, this spacing is set to this value. As the row gains focus, this value scales by the same percentage as the row item height increases as it's interpolated between the rowItemHeight and the rowItemZoomHeight for the row.
useDefaultAspectRatio

array of Boolean[ ]If set to false, rowItemAspectRatio is used to specify the aspect ratio for items in a Row. If set to true and if the ContentNode for an Item in the row includes an aspectRatio field, that value is used instead of the rowItemAspectRatio value. This allows different items in a Row to have different aspect ratios.

wrap

BooleanfalsetrueIf true, the items wrap from bottom to top. If false, the items do not wrap.
drawFocusFeedbackOnTopBoolean true If true, the focus feedback indicator is drawn on top of (after) the items. If false, it is drawn below (before) the items.
drawFocusFeedbackBooleantrue

If true, the focus feedback indicator is drawn. If false, it is not drawn.

fadeFocusFeedbackWhenLongPressScrolling

Booleantrue

If true, when long press scrolling begins, the focus indicator will fade out and reappear when long press scrolling ends. If false, the focus indicator remains visible during long press scrolling.

focusBitmapUriuri""

Specifies the bitmap file used for the focus feedback indicator when the ZoomRowList 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.

focusBitmapBlendColorcolor0xFFFFFFFF

Blend 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.

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.

wrapDividerBitmapBlendColor

color0xFFFFFFFFBlend the graphic image specified by wrapDividerBitmapUri 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 wrapDividerBitmapUri.
wrapDividerHeightfloat0

Specifies the height of the divider. The wrap divider bitmap will be scaled to this height. This height is also added to the row spacing after the last row to allow more space between the first and last rows when the divider is drawn.

wrapDividerWidthfloat0Specifies the width of the divider. The wrap divider bitmap will be scaled to this width. If not specified, the width is set to the value of the rowWidth field.
wrapDividerOffset

Vector2D0By default, the wrap divider is drawn with its X-position set to 0 in the ZoomRowList's coordinate system and vertically centered in the space between the first and last rows (This space equals the spacing after the last row plus the row divider height). This field allows the position of the wrap divider to be adjusted relative to its default position.
showRowTitle

array of Boolean[ ]

Specifies whether the row title displayed.

NOTE: RowList has an identical field named "showRowLabel". The name was changed to "showRowTitle" for the ZoomRowList to indicate that the text for the label comes from the Row ContentNode's title field.

rowTitleOffset

array of Vector2D[ ]Specifies the offset of the Row Title for each row. The x-coordinate specifies the horizontal offset of the label from the left edge of the row. The y-coordinate specifies the vertical spacing of the top of the Row Title from the top of the row's coordinate system. If the array specified contains no values, a default offset value of [0,0] is used.
rowTitleFont

Fontinvalid

Specifies the font for the Row Title's text.

NOTE: RowList has an identical field named "rowLabelFont" (see showRowTitle's description above for more details).

rowTitleColor

array of color[ ]

Specifies the color of the Row Title's text.

NOTE: RowList has an identical field named "rowLabelColor" (see showRowTitle's description above for more details).

showRowCounterarray of Boolean[ ]

Specifies whether each row's Row Counter is displayed. Note that the Row Counter is displayed for the focused row even if the showRowTitle field value for that row is set to true.

rowCounterOffsetarray of Vector2D[ ]

Specifies the offset of the Row Counter for each row. The x-coordinate specifies the horizontal offset of the label from the left edge of the row. The y-coordinate specifies the vertical spacing of the top of the Row Counter from the top of the row's coordinate system. 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 labels of the extra rows. If the array specified contains no values, a default offset value of [0,0] is used.

Note that the Row Counter is right-aligned, so the x-coordinate of its rowCounterOffset is used to position the right edge of the Row Counter's Label node.

rowCounterFont

Fontinvalid

Specifies the font for the Row Counter's text.

NOTE: RowList did not allow a different font for the Row Counter to be used. It always used the same font as the Row Title.

rowCounterColor

array of color[ ]

Specifies the font for the Row Counter's text.

NOTE: RowList did not allow a different color for the Row Counter to be used. It always used the same color as the Row Title.

showRowCounterForShortRowsBooleantrue

When set to true, the Row Counter is shown for all rows. When set to false, the Row Counter is not shown if the total zoomed width of the items in the room is less than the value of the rowWidth field.

rowDecorationComponentName

string""Specifies the name of an XML component to decorate 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 Row Decoration Component Fields below
rowSelected

integer-1

Read-Only 

When an item is selected, set to the index of the selected row.

NOTE: RowList has an identical field named "itemSelected". This new name better reflects the field's purpose.

rowFocused

integer-1

Read-Only 

When a row gains the key focus, set to the index of the focused row.

NOTE: RowList has an identical field named "itemFocused". This new name better reflects the field's purpose.

rowUnfocused

integer-1

Read-Only 

When a row loses the key focus, set to the index of the unfocused row.

NOTE: RowList has an identical field named "itemUnfocused". This new name better reflects the field's purpose.

rowItemSelectedarray of integer[ ]

Read-Only 

When an item is selected, 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[ ]

Read-Only 

When an item gains the key focus, 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.

scrollingStatusBooleanfalse

Read-Only 

Set to true whenever the ZoomRowList is scrolling the focus horizontally or vertically.

rowsRendered

array of integer[ ]

Read-Only 

Contains a pair of indices that indicate the first and last Row ContentNode's that were rendered during the previous render. It is set at the end of each render.

For example, if rows 2, 3 and 4 were rendered, the field is set to [2, 4]

Note if the rows have wrapped vertically, the first value will be less than the second. So if there are 7 Row ContentNode's and itemsRendered is set to [ 6, 1] that indicates that Row ContentNode's 6, 0 and 1 were rendered.

rowItemsRendered

array of integer

[ ]

Read-Only 

Contains an array of values that indicate what Row ContentNode's and what Item ContentNode's were rendered during the previous render. It is set at the end of each render.

The values in the arrays are triples of integers with each triple containing the index of the Row ContentNode, followed by the first and last index of the Item ContentNode's in that row that was rendered.

For example if rowItemsRender is set to [ 0, 4, 7, 1, 0, 2, 2, 0, 3 ] that indicates that Item ContentNode children 4 to 7 of Row ContentNode 0 were rendered, Item ContentNode children 0 to 2 of Row ContentNode 1 were rendered and Item ContentNode children 0 to 3 of Row ContentNode 2 were rendered.

The triples will appear in the order in which the rows were rendered and will contain one triple of values for each rendered row.

If the Item's in a row have wrapped horizontally, the first item index for that row will be greater than the second. For example, if row 3 has 8 Item ContentNode's and rowItemsRendered is set to [ 3, 6, 2], that indicates that Item ContentNode's 6, 7, 0, 1 and 2 of row 3 were rendered.

currFocusRow

float-1.0

Read-Only 

Set to the index of the row that currently overlaps the ZoomRowList's fixed focus position (i.e. y=0 in the ZoomRowList's coordinate system). Let's refer to that position as yFocusTop. The value is a floating point value where the integer part represents the row that overlaps yFocusTOp and the fractional part represents the percentage of the item that overlaps the fixed focus position. For example, a value of 2.3 indicates that the focus is 30% of the way between row's 2 and 3.

If currFocusRow is greater than the number of rows' in the content minus 1, that indicates that the focus is between the last row and the first row. For example, if the ZoomRowList's content has 8 rows, currFocusRow = 7.65 would indicate that the focus is 65% of the way between row 7 and row 0.

jumpToRow

integer-1

Write-Only 

When set to a valid item index, causes the list to immediately update so that the specified row moves into the focus position.

NOTE: RowList has an identical field named "jumpToItem". This new name better reflects the field's purpose.

jumpToRowItemarray of integer[ ]

Write-Only 

When set to a valid [ row, col ] index pair, causes the list to immediately update so that the specified row, col item moves into the focus position.

animateToRow

integer-1

Write-Only 

When set to a valid item index, causes the list to quickly scroll so that the specified row moves into the focus position.

NOTE: RowList has an identical field named "animateToItem". This new name better reflects the field's purpose.

remainZoomedAboveFocus

 

stringfocusIsAtTop

This field controls whether the rows that appear above the focus row are shown in their zoomed size or un-zoomed size as they move in/out of the focus position.

If set to "focusIsAtTop" and the ZoomRowList's itemClippingRect's top is set 0.0, then rows will remain at their zoomed size as they enter/exit the focus region from above. The UX team has decided that this looks better as it minimizes the number of items simultaneously changing sizes as the user scrolls vertically.

If set to "never", then rows will zoom up/down as they enter/exit the focus region from above.

If set to "always", then rows will always remain at their zoomed size as they enter/exit the focus region from above regardless of the itemClippingRect's top value.

fadeOutAboveFocus

 

stringfocusIsAtTop

This field controls whether the rows that appear above the focus row fade in/out as they move in/out of the focus position.

If set to "focusIsAtTop" and the ZoomRowList's itemClippingRect's top is set 0.0, then rows will fade in/out as they enter/exit the focus region from above.

If set to "never", then rows will not fade in/out as they enter/exit the focus region from above.

If set to "always", then rows will always fade in/out as they enter/exit the focus region from above regardless of the itemClippingRect's top value.

...