AndroidTV:ListRow, ListRowPresenter

Table of contents

• ListRow, ListRowPresenter
  • Table of contents
  • Introduction
  • Overview
    • Horizontal list
    • Vertical list
  • APIs
    • ListRow
      • Class Overview
      • Summary
    • ListRowPresenter
      • Class Overview
        • Hover card
        • Selection animation
        • Shadow
      • Summary

Introduction

Android leanback support libraryにはコンテンツ表示用のAPIがいくつか備わっている.
ここではコンテンツを水平方向に並べるAPIについて記載する.

Overview

AndroidTVのデザインガイドラインには, 画面上下はカテゴリ等のセクション領域として確保する方針が書かれている.
そのためコンテンツのリストは垂直展開するListViewより水平展開するGridViewが好まれる.

[カテゴリ毎のメディアコンテンツリスト]

Horizontal list

Android leanback support libraryではコンテンツをリスト管理するためのクラスを提供する.

• ListRow
• ListRowPresenter

下記はこれらを使用したサンプルコード.

private ArrayObjectAdapter mRowsAdapter;
private static final int NUM_ROWS = 4;

private void buildRowsAdapter() {
    mRowsAdapter = new ArrayObjectAdapter(new ListRowPresenter());

    for (int i = 0; i < NUM_ROWS; ++i) {
        ArrayObjectAdapter listRowAdapter = new ArrayObjectAdapter(
                new StringPresenter());
        listRowAdapter.add("Media Item 1");
        listRowAdapter.add("Media Item 2");
        listRowAdapter.add("Media Item 3");
        HeaderItem header = new HeaderItem(i, "Category " + i, null);
        mRowsAdapter.add(new ListRow(header, listRowAdapter));
    }

    mBrowseFragment.setAdapter(mRowsAdapter);
}

ListRowはRowのサブクラスであるため, HeaderItemを持つ.
更にHeaderItemに紐づくコンテンツを子要素として管理するよう拡張されている.

下図はListRowの構造.

[ListRow]

ListRowは子要素をObjectArrayで保持する.
上記サンプルコードではStringとStringPresenterのセット(listRowAdapter)になる.
※StringPresenterは別途用意したString専用のPresenter

下図は子要素の構造.

[Child Elements]

これら行リストは水平方向へ展開するためにしばしばHorizontalGridViewにバインドされる.

Vertical list

ListRowは行のリスト表現である.
ここにヘッダ(カテゴリ等)を追加し, 列リストを形成するためにListRowをArrayObjectAdapterで管理する.
これにより複数行リスト(列×行)を作成し, ListRowを列リストとして表現する.

ListRowがModelで, ListRowPresenterがPresenterとして作用する.
最終的なデータ構造は次の通り.

[ListRows]

これら列リストは垂直方向へ展開するためにしばしばVertialGridViewにバインドされる.

APIs

ListRow

android.support.v17.leanback.widget.Row
　┗android.support.v17.leanback.widget.ListRow

Class Overview

A row composed of a optional HeaderItem, and an ObjectAdapter describing children.

HeaderItem(任意)と, 子要素が定義されたObjectAdapterから構成される.

Summary

ListRow(HeaderItem header, ObjectAdapter adapter)

(no description)

ListRowを初期化する. 行のメタ情報となるHeaderItemと, コンテンツをリスト表示するObjectAdapterを引数に取る

getAdapter()

Get the ObjectAdapter that represents a list of objects.

コンテンツをリスト表示するObjectAdapterを返却する

ListRowPresenter

android.support.v17.leanback.widget.Presenter
　┗android.support.v17.leanback.widget.RowPresenter
　　 ┗android.support.v17.leanback.widget.ListRowPresenter

Class Overview

ListRowPresenter renders ListRow using a HorizontalGridView hosted in a ListRowView.

ListRowPresenterはListRowをレンダリングする. ListRowはHorizontalGridViewを持つListRowViewにバインドされる.

Hover card

Optionally, setHoverCardPresenterSelector(PresenterSelector) can be used to display a view for the currently focused list item below the rendered list. This view is known as a hover card.

任意で, フォーカスされたアイテムのPresenterSelectorを指定するsetHoverCardPresenterSelector(PresenterSelector)が利用できる.
例えばフォーカスしたアイテムをHover cardのように見せることができる.

Selection animation

ListRowPresenter disables RowPresenter’s default dimming effect and draw a dim overlay on top of each individual child items. Subclass may override and disable isUsingDefaultListSelectEffect() and write its own dim effect in onSelectLevelChanged(RowPresenter.ViewHolder).

ListRowPresenterはRowPresenterの標準エフェクトを無効化し, フォーカスされていない各行のコンテンツリストにオーバレイの効果を描画する.
サブクラスはisUsingDefaultListSelectEffect()をoverrideしてこれを無効化し, onSelectLevelChanged(RowPresenter.ViewHolder)でエフェクトを再定義できる.

Shadow

ListRowPresenter applies a default shadow to child of each view. Call setShadowEnabled(boolean) to disable shadow. Subclass may override and return false in isUsingDefaultShadow() and replace with its own shadow implementation.

ListRowPresenterは標準でViewに影の効果を与える. setShadowEnabled(boolean)でこれを無効化できる.
サブクラスはisUsingDefaultShadow()でfalseを返し,独自の影の効果を実装できる.

Summary

下記は主なAPI.

ListRowPresenter (int zoomFactor)

Constructs a ListRowPresenter with the given parameters.
zoomFactor: Controls the zoom factor used when an item view is focused. One of ZOOM_FACTOR_NONE, ZOOM_FACTOR_SMALL, ZOOM_FACTOR_MEDIUM, ZOOM_FACTOR_LARGE

ListRowPresenterを初期化する.
引数zoomFactorにはViewがフォーカスされた際のズーム係数を指定する. 係数は次の中から選択する(ZOOM_FACTOR_NONE, ZOOM_FACTOR_SMALL, ZOOM_FACTOR_MEDIUM, ZOOM_FACTOR_LARGE)

setHoverCardPresenterSelector(PresenterSelector selector)

Set PresenterSelector used for showing a select object in a hover card.

選択されたアイテムをHover cardとして表示するためのPresenterSelectorを設定する

getHoverCardPresenterSelector()

Get PresenterSelector used for showing a select object in a hover card.

選択されたアイテムをHolver cardとして表示するためのPresenterSelectorを取得する

getShadowEnabled()

Returns true if child shadow is enabled.

子要素の影効果が有効になっている場合はtrueを返却する

setShadowEnabled(boolean enabled)

Enable or disable child shadow.

子要素の影効果を有効/無効で設定する

isUsingDefaultShadow()

Returns true if SDK >= 18, where default shadow is applied to each individual child of HorizontalGridView.

SDKバージョンが18以上の場合にtrueを返却する. 標準の影効果はHorizontalGridViewの子要素として個別に充てられる.

License:
Portions of this page are modifications based on work created and shared by the Android Open Source Project
and used according to terms described in the Creative Commons 2.5 Attribution License.

AndroidTV:Row, RowPresenter

Table of contents

• Row, RowPresenter
  • Table of contents
  • Introduction
  • Overview
    • Row header
  • APIs
    • Row
      • Class Overview
      • Summary
    • HeaderItem
      • Class Overview
      • Summary
    • RowPresenter
      • Class Overview
        • Customize UI widgets
        • UI events from fragments
        • User events
        • Selection animation
      • Summary

Introduction

Android leanback support libraryにはコンテンツ表示用のAPIがいくつか提供されている.
ここではコンテンツのヘッダを表現するクラス群について記載する.

Overview

メディアコンテンツを一覧表示する際には”カテゴリ”といったメタ情報を表示し, グルーピングするのが一般的である.
Android leanback support libraryはメタ情報をヘッダとして扱い, 抽象化する.

[カテゴリ毎にグルーピングされたメディアコンテンツ]

Row header

コンテンツリストの”行”はRowクラスで表現され, メタ情報はHeaderItemとしてRowに保持される.
RowがModelに対応し, RowPresenterがModelをViewへバインドするPresenterとして作用する.
Rowは”行”(および行見出し)として振る舞うだけで, “行”に紐づく子要素を持たない.

Rowに(先述のような)Menu Item 1, 2, 3 … を追加したければ, サブクラスのListRowクラスを使用する.

APIs

Row

android.support.v17.leanback.widget.Row

Class Overview

A row in a RowsFragment. This is the base class for all rows. You will typically use a ListRow, but you may override this class for non-list Rows.

“行”を表現するクラス. これはすべての”行”の基底クラスとなる.
ただし, 非リスト表現のためにこのクラスを拡張することもできる.

Summary

下記は主なAPI.

Row(HeaderItem headerItem)

Constructor for a Row.

行を初期化し, HeaderItemをセットする.

getHeaderItem()

Get the HeaderItem that represents metadata for the row.

行のメタ情報表現であるHeaderItemを返却する

setHeaderItem(HeaderItem headerItem)

Set the HeaderItem that represents metadata for the row.

行のメタ情報表現であるHeaderItemを設定する

getId()

Returns a unique identifier for this row. This id can come from one of three places:

• If setId(long) is ever called on this row, it will return this id.
• If setId(long) has not been called but the header item is not null, the result of HeaderItem.getId() is returned.
• Otherwise ObjectAdapter#NO_ID is returned.

行を特定するユニークなIDを返却する.IDは次の3つの内から返される.

• setId(long)が呼ばれている場合は, この行のIDを返却する
• setId(long)が呼ばれておらず, HeaderItemが存在する場合はHeaderItem.getId()の値を返却する
• 上記以外の場合はObjectAdapter#NO_IDを返却する

setId(long id)

Set the id for this row.

行を特定するユニークIDを設定する

HeaderItem

android.support.v17.leanback.widget.HeaderItem

Class Overview

A header item is an item that describes metadata of Row, such as a category of media items. Developer may override this class to add more information.

ヘッダは, メディアコンテンツの”カテゴリ”にあたるメタ情報の表現.
メタ情報を追加したい場合はこのクラスを拡張する.

Summary

下記は主なAPI.

HeaderItem(long id, String name, String imageUri)

Create a header item.

ヘッダの初期化

getId()

Returns a unique identifier for this item.

このヘッダのユニークIDを返却する

getImageUri()

Returns the icon for this header item.

このヘッダのアイコンを返却する

getName()

Returns the name of this header item.

このヘッダの名前を返却する

RowPresenter

android.support.v17.leanback.widget.Presenter
　┗android.support.v17.leanback.widget.RowPresenter

Class Overview

An abstract Presenter that renders a Row.

Rowをレンダリング対象とする抽象的なPresenter

Customize UI widgets

When a subclass of RowPresenter adds UI widgets, it should subclass RowPresenter.ViewHolder and override createRowViewHolder(ViewGroup) and initializeRowViewHolder(ViewHolder).

RowPresenterを継承しUIウィジェットを追加する場合, そのサブクラスはRowPresenter.ViewHolderを継承し, createRowViewHolder(ViewGroup)メソッドとinitializeRowViewHolder(ViewHolder)メソッドをオーバライドすべき.

The subclass must use layout id “row_content” for the widget that will be aligned to the title of any HeadersFragment that may exist in the parent fragment.

サブクラスはUIウィジェットのレイアウトIDにrow_contentを使用すること.
これにより親Fragmentとして存在し得るHeadersFragmentにより, タイトルに沿って行が配置される.

RowPresenter contains an optional and replaceable RowHeaderPresenter that renders the header. You can disable the default rendering or replace the Presenter with a new header presenter by calling setHeaderPresenter(RowHeaderPresenter).

RowPresenterはヘッダをレンダリングする置換可能なRowHeaderPresenterを持つことがある.
setHeaderPresenter(RowHeaderPresenter)を使用することで, 標準レンダラを無効化するか, あるいは別のレンダラに置き換えることもできる.

UI events from fragments

RowPresenter receives calls from its parent (typically a Fragment) when:

RowPresenterは次のケースで(通常Fragmentから)呼び出される

• A Row is selected via setRowViewSelected(Presenter.ViewHolder, boolean). The event is triggered immediately when there is a row selection change before the selection animation is started. Subclasses of RowPresenter may override onRowViewSelected(ViewHolder, boolean).

setRowViewSelected(Presenter.ViewHolder, boolean)で行が選択された場合.
行を選択する際, 選択アニメーションが始まるよりも前にイベントは発行される.
RowPresenterのサブクラスはonRowViewSelected(ViewHolder, boolean)メソッドをoverrideできる.

• A Row is expanded to full width via setRowViewExpanded(Presenter.ViewHolder, boolean). The event is triggered immediately before the expand animation is started. Subclasses of RowPresenter may override onRowViewExpanded(ViewHolder, boolean).

setRowViewExpanded(Presenter.ViewHolder, boolean)で行が展開された場合.
展開アニメーションよりも前にイベントは発行される.
RowPresenterのサブクラスはonRowViewExpanded(ViewHolder, boolean)メソッドをoverrideできる.

User events

RowPresenter provides OnItemSelectedListener and OnItemClickedListener. If a subclass wants to add its own View.OnFocusChangeListener or View.OnClickListener, it must do that in createRowViewHolder(ViewGroup) to be properly chained by the library. Adding View listeners after createRowViewHolder(ViewGroup) is undefined and may result in incorrect behavior by the library’s listeners.

RowPresenterはonItemSelectedListenerとOnItemClickedListenerを提供する.
もしサブクラスがView.OnFocusChangeListenerまたはView.OnClickListenerを追加したい場合はcreateRowViewHolder(ViewGroup)で行う.
createRowViewHolder(ViewGroup)は後続処理のため適切にoverrideすること. createRowViewHolder(ViewGroup)の後でViewのリスナーを追加しても正しく動作しない可能性がある.

Selection animation

When a user scrolls through rows, a fragment will initiate animation and call setSelectLevel(Presenter.ViewHolder, float) with float value between 0 and 1. By default, the RowPresenter draws a dim overlay on top of the row view for views that are not selected.

ユーザが行をスクロールした場合, Fragmentはアニメーションを生成しsetSlectLevel(Presenter.ViewHolder, float)メソッドを呼び出す. float値は0(unselected)~1(selected)の間.
RowPresenterは標準で選択されていない行に対してdimエフェクトをオーバレイ描画する.

[dimming effect off/on]

Subclasses may override this default effect by having isUsingDefaultSelectEffect() return false and overriding onSelectLevelChanged(ViewHolder) to apply a different selection effect.

サブクラスはisUsingDefaultSelectEffect()でfalseを返し, onSelectLevelChanged(ViewHolder)をoverrideして異なる選択エフェクトを適用することができる.

Call setSelectEffectEnabled(boolean) to enable/disable the select effect, This will not only enable/disable the default dim effect but also subclasses must respect this flag as well.

setSelectEffectEnabled(boolean)でdimエフェクトのon/offを選択できる.
これはデフォルトのdimエフェクトをon/offするにとどまらない. サブクラスはこのフラグに注意すること.

Summary

下記は主なAPI.

getSelectEffectEnabled()

Returns true if the row selection effect is enabled. This value not only determines whether the default dim implementation is used, but subclasses must also respect this flag.

行の選択エフェクトが有効である場合はtrueが返却される. このフラグはデフォルトdimエフェクトを使うかどうかだけでは決定されないため, サブクラスはこのフラグに注意すること.

setSelectEffectEnabled(boolean applyDimOnSelect)

Enables or disables the row selection effect. This will not only affect the default dim effect, but subclasses must respect this flag as well.

選択エフェクトを有効あるいは無効にする. このフラグの影響はデフォルトdimエフェクトに留まらない.
サブクラスはこのフラグに注意すること.

isUsingDefaultSelectEffect()

Return whether this RowPresenter is using the default dimming effect provided by the library. Subclasses may(most likely) return false and override onSelectLevelChanged(ViewHolder).

RowPresenterがライブラリ標準のdimエフェクトを提供しているかどうか.
サブクラスはonSelectLevelChanged(ViewHolder)をoverrideして選択エフェクトを再定義する場合はfalseを返すこと.

setOnItemClickedListener(OnItemClickedListener listener)

Set the listener for item click events. A RowPresenter does not use this listener, but a subclass may fire an item click event if it has the concept of an item. The OnItemClickedListener will override any View.OnClickListener that an item’s Presenter sets during onCreateViewHolder(ViewGroup). So in general, you should choose to use an OnItemClickedListener or a View.OnClickListener, but not both.

アイテムのクリックイベントリスナを設定する. RowPresenterはこのリスナを使用しないが, サブクラスはクリックイベントの処理をここに定義できる.
OnItemClickedListenerは, PresenterによりonCreateViewHolder(ViewGroup)の中でoverrideされたView.OnClickListenerでセットされます.
一般的にOnItemClickedListenerまたはView.OnClickListenerのいずれかが選択されます.

setOnItemSelectedListener(OnItemSelectedListener listener)

Set the listener for item or row selection. A RowPresenter fires a row selection event with a null item. Subclasses (e.g. ListRowPresenter) can fire a selection event with the selected item.

行,またはアイテム選択のリスナを設定する. RowPresenterは性質上, 空アイテムの選択でこのイベントを発行する.
サブクラス(例えばListRowPresenter)はアイテムが選択されたらイベントを発行できる.

License:
Portions of this page are modifications based on work created and shared by the Android Open Source Project
and used according to terms described in the Creative Commons 2.5 Attribution License.