AndroidTV:ListRow, ListRowPresenter

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

Blog: [Yukiの枝折](http://yuki312.blogspot.jp/2014/08/androidtvlistrow-listrowpresenter.html)

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

![enter image description here][1]
[カテゴリ毎のメディアコンテンツリスト]

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

 - `ListRow`
 - `ListRowPresenter`

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

```java
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 Structure](https://lh4.googleusercontent.com/kr0MpuY6H7Ms0E9dkSZ9vSiG1Qrus7Qu3KhBDpAyvVk=s600 "listrow_structure.png")
[ListRow]

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

下図は子要素の構造.  

![Child Elements](https://lh6.googleusercontent.com/RMVDkpD8pWm-LHdBVcQZduoElynvkYvthrhNdqcsXnA=s600 "child_elements.png")
[Child Elements]

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

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

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

![List Structure](https://lh5.googleusercontent.com/Syvh5xUJQfihuvWUTlj8YoHxGYjZ42NBSHh3Mm33b-Q=s600 "all_structure.png")
[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 discription)
: 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](http://code.google.com/policies.html)
 and used according to terms described in the [Creative Commons 2.5 Attribution License](http://creativecommons.org/licenses/by/2.5/).  


  [1]: https://lh3.googleusercontent.com/-x0j4iWHz4dI/U-wrLjnoCvI/AAAAAAAAEkU/bygM6FiWRuk/s600/ListRow.png "ListRow.png"
  [2]: https://lh6.googleusercontent.com/-R5gX0eqMN1A/U-t81e-dtqI/AAAAAAAAEhY/sBd21vHd6NM/s600/listrow_structure.png "listrow_structure.png"
  [3]: https://lh4.googleusercontent.com/--yZj95kKOug/U-uBgSwjHSI/AAAAAAAAEh4/EA7EjSKeIlI/s600/child_elements.png "child_elements.png"
  [4]: https://lh5.googleusercontent.com/-yCLp7XV2NhM/U-uA7cUgiqI/AAAAAAAAEhw/zIvdZFFlH5w/s600/all_structure.png "all_structure.png"