キーボード、ゲームパッドコントローラーで操作可能なScrollView (KeyControllableScroll)

キーボードや、ゲームパッドコントローラーで操作可能な ScrollView をMITのオープンソースライブラリとして作ったのでご紹介。

" Key Controllable Scroll " なので以下 KCS と呼びます。

使い方の面で少し面倒な部分もありますが、スクロールの挙動を色々カスタムできる上、パフォーマンスもかなり良いと思います。

OSSのリンクはこちら
Read Me in English is Here // Sorry, not finished yet

*なぜかSafariでこのページ開くとGif挙動がおかしくなるらしいので、Chrome等で開くことをお勧めします。

概要

操作

KCSでは「スクロールの操作」と「フォーカスの操作」がそれぞれ可能です。

スクロールのキー操作

縦スクロールの時は上下、横スクロールの時は左右に動かせます。
フォーカス (黄色ハイライト) は画面内に収まるように自動で移動します。

フォーカスのキー操作

上下左右のセルにフォーカスを動かせます。
フォーカスが画面内に収まるようにスクロールは自動で移動します。

負荷

軽量化

• スクロールの移動によって画面外に出たセルは、再利用しているため軽量化されています。
• 初期化時にセルの任意のコンポーネントをキャッシュできるため、動作中にGetComponent()の必要がありません。
• セルの再利用とキャッシュには配列 Array を使っているためメモリ負荷も軽いです。
• より詳しい負荷については、後述の 負荷について (詳細) にて説明しています。

↓ セルの再利用 ↓

使い方 (KCSの作成と追加)

使用上の注意

• １つの KCS 内では同一サイズのセルしか使えません。
• セル Prefab の種類ごとに KCS を作成する必要があります。*1
• セル Prefab内の、オブジェクトの親子関係が変化したとき (追加/削除/移動) には KCS を作成し直す必要があります。*2

*これらは「使い方」の使用例でも説明します。

1. セル Prefab の作成

手順

• セルのPrefabを作ります。
• この時、Rootオブジェクトには必ず Anchors Max (x, y) = (0, 1)、 Anchors Min (x, y) = (0, 1)、 Pivot (x, y) = (0, 1)、の RectTransform をアタッチしてください。
• セルの内容が定まっていない時は、適当に Rootオブジェクトと RectTransform だけでもいいですが、セルPrefab の内容が変化 (子オブジェクトの追加/削除/移動)すると、この「使い方」の手順をやり直す必要がある ので、先にある程度決めておくと楽です。
• フォーカスは セルPrefab の Rootオブジェクト が対象になるので、Rootオブジェクト に Button などをアタッチするとフォーカスを視認できます。 Sample では Button をアタッチして Selected Color を黄色にしています。
• 実際にはセルの内容を持ったオブジェクトであれば良いので、必ずしも Prefab化したオブジェクトである必要はありません。

SampleのセルPrefabの内容はこんな感じ

SampleCell が Rootオブジェクト、ImageObject と TextObject が同じ階層の子オブジェクトです。
-以下はそのオブジェクトにアタッチされているコンポーネントです。

2. KCS Script.cs の作成

OSSをGitHubからダウンロード していると、ツールバーから、Window > UI Toolkit > KCS Script Generator を開けます。

開いた KCS Script Generator ウィンドウで、先ほど生成したセルPrefabを Cell Prefab: にアサインすると、こんな感じに折り畳みやトグルをチェック出来るようになります。

それぞれのパラメーターを設定します。

• KCS Type:
  KCS のスクロール方向を、横 (Horizontal) か縦 (Vertical) か選べます。Sampleでは縦方向です。

• Cell Prefab:
  この KCS に使うセルを選択します。これが None だと以下の項目は表示されません。

• DataSource Target Components:
  初期化時にキャッシュしたい任意のコンポーネントを指定できます。 セルを描写する時に使いたい セルPrefab のコンポーネントにチェックを入れておきましょう (例えば、表示するセルごとに画像を変えたいなら Image 、ボタンクリック操作を変えたいなら Button などなど)。ここに表示されるオブジェクトやコンポーネントの順番は セルPrefab の Hierachyで表示される通りなので、見比べながら確認すると便利です。

• KCS Name:
  KCS Script の名前を決めれます。

• Generate KCS Script
  KCS Script を保存します。Dafault Path では KeyControllableScroll > NewKCSs のディレクトリに、Select Path では任意の場所に保存できます。

3. KCS オブジェクトの作成

Assets > Create > UI > KCS から、横方向スクロールの時は Horizontal KCS Framework を、縦方向スクロールの時は Vertical KCS Framework を作成します。

KCS Framework を作成した後は、KCS の Rootオブジェクト に先ほど作成した KCS Script をアタッチします。 Add Component ボタンから UI > KCS でも追加できます。

使い方 (KCSのカスタム)

1. インスペクターでカスタム

次にインスペクターを見ていきます。

Cell Recycle Param

KCS の基本的なパラメーターです。

• Smooth Mode:
  オフにすると、画面外で待機させるセルの数を減らします。負荷を軽くできますが、フォーカスのキーを高速に連続入力した時の遅れが大きくなります (下図➀)。負荷を減らしたい時や、フォーカスのキーを連続入力した際に見栄えがゆっくりになっても構わない時はオフを推奨します。

• Cell Prefab:
  この KCS Script を作ったときに使った セルPrefab を設定します。設定は必須です。

• Viewport Width / Height:
  横方向スクロールのときはVeiwport の幅を、縦方向スクロールのときはVeiwport の高さを設定します。デフォルトだと Viewport は KCS の Rootオブジェクトにフィットしているので、Rootオブジェクトの値をそのまま設定します。設定は必須です。

• All Contents Num:
  セルの総数を設定します。設定は必須です。

図➀ - SmoothMode オン (左) と オフ (右)

下図では同じ入力頻度でフォーカスキーを高速連続入力。
オン (左) の方が画面外で待機するセルの数が多く、フォーカスのキーを連続入力した時の遅れが小さい。

Grid Layout Group Param

Grid Layout Group コンポーネントと同じノリでレイアウト設定ができるパラメーターです。これでセルの大きさや、セル同士のスペースを設定して下さい。ただし、KCS の仕様で値が制限されていたり (Limited)、固定されていたり (Fixed) します。

• Padding:
  CellList の上下左右端から、セルの集団までの余白を設定できます。

• Cell Size:
  セルのサイズを設定できます。

• Spacing:
  セル同士間の余白を設定できます。

• Start Coner: / Start Axis:（Fixed）
  横方向スクロールでは、セルは左上からスタートして上詰めに配置されていきます。縦方向スクロールでは、セルは左上からスタートして左詰めに配置されていきます (下図➁)。

• Child Alignment:（Fixed）
  セルの集団は CellList の左上に配置されます。

• Constraint:
  横方向スクロールでは行の数、縦方向スクロールでは列の数を設定できます。

図➁ - セルの配置順

横スクロールは左上からスタートして上詰めに配置

縦スクロールは左上からスタートして左詰めに配置

Scroll Key Control

スクロールのキー操作用パラメーターです。

• Scroll Key Control:
  スクロールのキー操作が有効になります。スクリプト上でスクロールキーを割り当てるインターフェースの実装が必要です (後述)。

• Scroll Speed:
  スクロールの速度を設定できます。

Focus Key Control

フォーカスのキー操作用パラメーターです。

• Focus Key Control:
  フォーカスのキー操作が有効になります。スクリプト上でフォーカスキーを割り当てるインターフェースの実装が必要です (後述)。

• Focus Fixed Row:
  スクロール方向に垂直な、 Viewport 中央の軸を 0 として、Viewport 内でフォーカスが移動できる範囲を行数で設定できます (下図➂)。スクロール方向のセルの大きさ ( 横方向では Width、縦方向では Height ) が Viewport に対して小さくなるほど設定できる範囲が増え、逆に十分大きいと 0 固定になります。

• Scroll Chase Speed:
  フォーカスが画面内に収まるようにスクロールが自動移動する際の速度を設定できます (下図➃)。

• Key Hold Repeat:
  キーの長押しで、フォーカスが連続移動するように設定できます。

• Repeat Interval:
  フォーカスの連続移動のインターバルを設定できます。

• Repeat Start Delay:
  キーの長押し時に、フォーカスが連続移動を始めるまでのディレイを設定できます。

• Delay Decreasing:
  フォーカスが連続移動を始めるまでのディレイを徐々に減らして、移動を徐々に加速させます (下図➄)。

• Decreasing Time:
  ディレイを完全に無くすまでの時間を設定できます。

図➂ - Focus Fixed Row の設定

スクロール方向に垂直な、Viewport中央の軸が 0 となる。Sample では -1 ～ 1 の範囲で設定できる。

Up Focus Fixed Row と Down Focus Fixed Row を 0 に設定すると、画面内におけるフォーカスの移動範囲は０行目だけになる。

一方でそれぞれを -1 と 1 に設定すると、画面内におけるフォーカスの移動範囲は -1 ～ 1 行目までになる。

Viewportに対するセルの大きさが小さいほど設定できる範囲が増え (左)、逆にセルの大きさが十分大きいと 0 固定になります (右)。

図➃ - Scroll Chase Speed の設定

フォーカスをキー操作した時に、スクロールがフォーカスを追従する速度。左が 0.1 右が 1 。

図➄ - Delay Decreasing の設定

キーの長押し時、オフだとディレイは初めだけ生じる。オンだとディレイが徐々に減少し、移動が加速する。

Public Methods & Fields

上記以外の、スクリプト上で使える KCS の Publicメソッド や Publicフィールド をお試しで使えます。ランタイム中しか有効になりません。

• Scroll Key Suspended:
  スクロールのキー操作を一時停止します。

• Focus Key Suspended:
  フォーカスのキー操作を一時停止します。

• Focused Cell No:
  現在フォーカスされているセルの番号が確認できます。Get のみで Set できません。

• Jump To:
  後ろで指定した番号のセルまで移動してフォーカスします。

• Scroll Init:
  KCS を初期化します。

2. インターフェースでカスタム

KCS の初期化は Start() で行われているため、インターフェースのセットは Start() より前で行う必要があります。
Sampleでは Awake() で行っています。

DataSource (必須)

セルを描写する時の処理を実装します。これを実装しないと KCS は動きません。
引数には KCS Script を作成時に選択したコンポーネントがキャッシュされています。

DataSource

I"KCS名"DataSource
public void SetCellData(int index, Image image, Button button, Image image_0, Text text_1) {}

Input (準必須)

スクロールまたはフォーカスをキー操作する時の、キーの割り当てを実装します。
Scroll KeyControll または Focus KeyControll を有効にすると、それぞれの実装が必要になります。
長押しで連続入力が可能な入力 ( Input.GetKey() など ) を、それぞれのキーにタプルとして retrun してください。

Input

I"KCS名"ScrollKeyInput
public (bool ScrollUpOrLeftKey, bool ScrollDownOrRightKey) GetScrollKeys() {}

I"KCS名"FocusKeyInput
public (bool UpKey, bool DownKey, bool LeftKey, bool RightKey) GetFocusKeys() {}

KeyMoved (任意)

スクロールまたはフォーカスのキー操作が行われるたびに呼ばれるインターフェースです。
移動時の効果音などを実装したい時に利用できます。

KeyMoved

I"KCS名"ScrollKeyMoved
public void WhenScrollMoved() {}

I"KCS名"FocusKeyMoved
public void WhenFocusMoved() {}

3. スクリプトでカスタム

Public フィールド

インスペクターのパラメーターとして表示されているフィールドは、全て Publicフィールドとして Get や Set できます。

Public フィールド

// 現在フォーカスされているセル番号の取得
int cellNo = "KCSのインスタンス".FocusedCellNo

// スクリプトから AllContentsNum (セルの総数) の設定
"KCSのインスタンス".AllContentsNum = 100 ;

ただし、ランタイム中にインスペクターで無効になっているフィールドは、動作中に Set すると KCS の挙動がバグるので、Set する場合は初期化の前に行う必要があります。 デフォルトでは初期化Init( ) は Start() で行われます。

ランタイム中に無効になるパラメーター (右: 灰色部分)

Public メソッド

インスペクターでボタンとして表示されている関数も、全て Publicメソッドとして利用できます。

Public メソッド

// KCS の初期化
"KCSのインスタンス".Init();

// 指定セル番号まで移動
"KCSのインスタンス".JumpTo( 68 );

負荷について (詳細)

実測値（セル描写実装なし）

Sample の セルPrefab を使い、セルの描写時に何の処理もしない KCS のみを配置したプロジェクト の PlayerLoop 負荷は、以下の通りになりました。
*Unity Profiler の Deep Profile で計測

状態	GC Alloc.	Time ms
Init( ) 発火	2.6 KB	6 ms 前後
スクロール中	51 B	1.5 ms 前後
スクロール中以外	51 B	1 ms 前後

Init( ) 発火

スクロール中

スクロール中以外

利用時の最適化

上記のように、セルの描写時に何の処理もしない KCS の負荷は、初期化時ではそれなりに重く、初期化時以外はかなり軽くなっています (有名な LoopScrollRect と比べても軽い)。そのため、KCS の利用時の負荷は 初期化Init( ) と、セル描写時の処理SetCellData( ) の重さに依存します。

初期化処理 Init( )

• できるだけ Init( )を発火しない。初期位置に戻りたいときは JumpTo(int)を使う。
• セルPrefab 内の子オブジェクト数を減らす。( Instantiate() が内在するため )
• SmoothMode をオフにする。
• Viewport に対してセルやスペースを大きくして、画面に一度に表示されるセルの数を減らす。

セル描写処理 SetCellData( )

• String の多用など、重たい処理を避ける。
• SmoothMode をオフにする。
• Viewport に対してセルやスペースを大きくして、画面に一度に表示されるセルの数を減らす。

トラブルシューティング

インスペクターで Cell Recycle Param を埋めてください

KCS Script のインスペクターで、Cell Recycle Param が設定されていない時に発生します。

DataSourceにインターフェースをセットしてください

IDataSource インターフェースが実装されていない時に発生します。

～ にインターフェースをセットするか、～ を無効にしてください

スクロールやフォーカスのキー操作が有効になっているが、キーの割り当てが行われていない時に発生します。
インターフェースでキーの割り当てを実装するか、インスペクターでキー操作を無効にしてください。

セルとスペースのサイズが大きすぎます

セルの大きさが Viewport の大きさよりも大きい時に発生します。
少なくとも１つのセルが完全に表示できるように、セルの大きさとスペースの大きさを小さくするか、Viewportを大きくして下さい。

型や名前空間が見つからない: Type or NameSpace missing

セル描写時にキャッシュしたコンポーネントを使用するのに、必要な型の参照がインポートされていない時に発生します。
エラー箇所に必要な参照を using でインポートしてください。

それ以外

KCS 以外の部分にエラーの可能性があるので、一度 KCS を取り除き、作り直してみて再度エラーが生じるか確認してください。依然

後の機能追加予定

• 無限スクロールに対応したい。
• 一つの KCS 内で異なる大きさのセルを置けるようになりたい。
• 逆方向のスクロール (右から左 or 下から上)を作りたい。
• セルの配置を左上以外からスタートできるようにしたい。

Thank you for reading !

作るまでが面倒で申し訳ないです ; ; が、作り終えた後は結構カスタムも効く上パフォーマンスもかなり良いと思います。

(というよりカスタムできる要素を増やしすぎた感はある、、)

ちゃんとプログラミングを始めてまだ半年ちょいなので、あまり良くないコードとかが割とありそうです、、。

色々と参考にさせていただきたいので、意見やコメント等がありましたら是非よろしくお願いします _ ( . _ . ) _