Aqualeadウィジェットチュートリアル


目次

1. 概要
2. ボタンウィジェットの表示
3. カーソルの表示
4. ウィジェットの操作
5. ポインティングデバイスによる操作
6. カーソルの変更
7. モーション
8. 終わりに

第1章 概要

Aqualeadのウィジェットとはメニューを作るためのクラスの総称です。

ウィジェットはゲーム中のメニューを作るためにに作られており、 そのため標準の見た目などが存在しません。 その代わり、Aqualeadの全ての描画機能を使ってメニューを構築する事が出来るため、 大半のメニューを実現する事が出来ます。

ウィジェットはプログラムで作る事も可能ですが、データ定義とスクリプトで作る事も出来ます。 その場合はプログラマはメニューを作る作業はほとんど必要なくなります。 その為のGUIツールは現在構築中です。

このチュートリアルでは基本となるボタンウィジェットとカーソルを扱います。 このほかリストを扱うためのウィジェットや、このチュートリアルでは扱わないいろいろな機能がありますが、それはまた別のチュートリアルで扱います。

今回のチュートリアル作るメニューは以下のようになります。

シンプルなメニューですが、これの応用で大半のメニューを作る事が可能です。

第2章 ボタンウィジェットの表示

まずはボタンウィジェットを生成し、表示させてみます。

前述の通り、ボタンウィジェットの表示と言ってもボタンウィジェット自体は表示部分は持っていないので、 今回はスプライトとテキストを組み合わせて表示部分を作ります。

各ウィジェットは全てグループノードなので、 表示用のノードはこのウィジェットにAddNodeまたはAddReleaseNodeで登録します。

また、今回の例ではテキスト文字列以外は同一のボタンを三つ作るので、 Clone関数を使用しています。 ウィジェット関連は設定箇所が多く、また似たような設定の物を複数作る事が多いためClone関数を使うと便利です。

ソースは以下のようになります。 この時点ではまだ操作できません。

<xi:include></xi:include>

???

ボタンウィジェットを生成します。引数にはスキンやオーナーを指定する事が出来ますが、これは後述します。

???

スプライトをボタンウィジェットを追加します。AddReleaseNodeを使用すると解放をウィジェットに任せる事が出来ます。

なお、ウィジェットにノードを追加すると、自動的に親がそのウィジェットになります。

???

追加したスプライトを表示します。このようにウィジェットに追加するノードも明示的に表示する必要があります。

???

テキストのプライオリティを少し上げて、スプライトより手前に表示します。

ウィジェットでは複数の描画ノードの組み合わせを使う事が多いですが、このように明示的にプライオリティの設定をしないと予期せぬ表示になる事があるので注意して下さい。

???

ウィジェット自体を表示します。

???

ウィジェットの表示値を設定します。基準位置は表示用ノードの設定次第になります。今回はスプライト・テキスト共に左上を原点としているので、左上が基準座標です。

???

先ほど設定したウィジェットのクローンを生成します。グループ内のスプライト、テキストも同時にクローンされます。

???

クローンしたウィジェットからテキストノードを検索して取得します。

今回はテキストノードはウィジェット内に一つなので種別で検索しましたが、複数存在する場合はノードにIDをつけFindNode関数で検索する必要があります。

第3章 カーソルの表示

次はカーソルを表示します。 Aqualeadでは選択中のボタンを示すために、矢印のようなアイコンなどをカーソルとして使う事が出来ます。 もちろん、カーソルを使わずに選択中のボタンの表示を変えて選択中にしたり、 ボタンの表示変更とカーソルの両方を使う事も可能です。

カーソルを使うためには、ウィジェットのオーナーという概念を使う必要があります。 ウィジェットにはグループや親子関係とは別の階層構造があります。 単純なメニュー以外では、ウィジェットにはオーナーを指定し、各ウィジェットはオーナーが所有するという形を取ります。

所有されたウィジェットはオーナー削除時に自動削除されます。オーナーを削除後に、手動で所有されたウィジェットを削除すると多重削除エラーが発生するので注意して下さい。

オーナーにはALContainerWidgetかそのサブクラスを指定します。 これらのウィジェットは別のウィジェットを所有し、階層構造を持つために使用します。 各ウィジェットはオーナーの中で一つだけフォーカスを持つ事が出来、 フォーカスを持つウィジェットが選択中となり、カーソルを表示が可能になります。

カーソルはこのオーナーとなるウィジェットに設定をし、 そこに含まれるウィジェットがそのカーソルを使用します。

また、カーソルを使う場合は、通常ウィジェットのサイズが必要になります。 カーソルの位置やサイズは、カーソルのあるウィジェットのサイズに合わせて変わります。 そのため、適切なサイズ指定をしないとカーソルが正しく表示されません。

とりあえずは今回はデバッグ用に用意されているデフォルトのカーソルを使用します。

<xi:include></xi:include>

???

コンテナウィジェットを生成します。これをボタンウィジェットのオーナーにします。

???

生成したコンテナウィジェットを、ウィジェットのデフォルトオーナーとして設定します。以降指定がなければこのウィジェットがオーナーとなります。

???

オーナーに設定した時点で参照カウントが増えるので、ここで減らしておくとオーナー解除時にDestoryが自動実行されます。

???

ウィジェットの縦幅を設定します。今回は横幅は使用しないので、縦のみ設定します。

???

カーソルを生成します。なお、引数でfalseを設定するとカーソルを削除できます。

???

デフォルトオーナーを解除します。すでにReleaseが実行されているので、オーナーのDestroyも実行されます。

それに伴い、オーナーに所有されている他のボタンウィジェットも同時にDestroyされます。

第4章 ウィジェットの操作

それでは、このボタンウィジェットを操作できるようにしましょう。 Aqualeadではパッド入力と、マウス等のポインティングデバイスのクリック両方に対応しています。 まずはパッド入力を行います。

パッド入力の場合、上下左右を押された場合にどのウィジェットにフォーカスを移すかを設定します。

決定はWidgetに設定されているDecisionKeyを使います。 デフォルトではALPAD_Aですが、これは変更も可能です。

決定ボタンが押されると、ウィジェットは決定状態になり、設定があればコールバックを呼び出します。 このコールバック内ではどのウィジェットが決定されたか、どのような理由で決定されたか、 どのボタンで決定されたか等の情報が取得できます。

このほか、ショートカットキーの設定が出来ます。 ショートカットキーは決定の他のキーを使い、 そのキーが押されると現在の選択に関わらずそのウィジェットが決定されます。

<xi:include></xi:include>

???

決定時に呼び出されるコールバック関数を登録します。

Cloneを実行するとコールバック呼び出しもコピーされるので、全てのボタンウィジェットで共有されます。

???

ウィジェットの区別用にタグを設定します。

これはアプリケーションで自由に使用できる32ビットの数値です。UserDataとは別物です。

???

上下左右を押したときに、どのウィジェットに移動するかをそれぞれ設定します。

なお、bw1のUpWidgetにbw3を、bw3のDownWidgetにbw1を指定する事で上下ループになります。

???

ショートカットボタンを設定します。このショートカットが押されると、そのウィジェットにフォーカスが移り決定状態になります。

ショートカットボタンは複数割り当てる事も出来ます。

また、決定まで行わず、フォーカスのみ移動に設定する事も可能です。

???

決定状態になったときに呼び出されるコールバックです。

一度決定状態になったときにはClearDecisionを呼び出したり、フォーカスを移さない限りは決定状態が維持され、続けてこのコールバックが呼ばれる事はありません。

???

ActionReasonにより、どのような理由でコールバックが発生したかを取得が出来ます。

この場合は、通常の決定ボタンで決定が行われた時の処理です。

???

この場合は、ショートカットボタンで決定が行われた時の処理です。

???

ActionReasonにはボタンの種別も格納されています。

必要があれば、このようにボタン種別での判定も可能です。

???

ALWIDGET_ACTION_REASON_BUTTON_MASKを使う事により、ボタン部分のみ取り出す事も出来ます。

???

Tagを使う事により、どのウィジェットが決定されたかを区別する事が出来ます。

第5章 ポインティングデバイスによる操作

ウィジェットはパッドだけではなく、マウス等のポインティングデバイスで操作する事も可能です。

ポインティングデバイスで操作する場合は、ウィジェットにクリック範囲となるコリジョンを設定します。 通常、コリジョンは矩形の2DRectCollisionを使用しますが、 それ以外の形状のコリジョンや複数コリジョンの使用も可能なので、複雑な形状をクリック範囲に設定することも可能です。

ボタンウィジェットのクリックは、選択中のウィジェットをクリックすると決定になりますが、 選択をされていないウィジェットをクリックするとフォーカスがそのウィジェットに移るだけになります。 ウィジェット毎の設定により、これを常にクリックで決定に変更する事も可能です。

もしウィジェットが重なり、クリック範囲が重なった場合は表示の優先順位に従い、手前のものが選択されます。

<xi:include></xi:include>

???

クリック用の矩形コリジョンを設定します。第1引数であるアトリビュートは内部で自動設定されるので、0を設定しておきます。

ViewRectはそのノードの描画範囲を矩形で取得します。

???

このボタンのみ、クリックでそのまま決定する設定に変更します。

パッド入力を受け付けず、カーソルを作らない場合は全てこの設定にした方がいいでしょう。

???

クリック時のActionReasonを判定します。

なお、クリック時はボタン種別には何も値が入りません。

第6章 カーソルの変更

今まではデフォルトのカーソルを使用していましたが、これは独自のカーソルに変更することも可能です。

カーソルは見た目だけではなく、動きなども設定が出来ます。 動きはフォーカス変更時に発生するコールバック関数で設定します。 移動時のコールバック関数の設定をしなければ、現在のようにフォーカスの対象に瞬時に移動します。

対象のウィジェットのサイズも取得できるので、ウィジェットを囲むようなカーソルも実装が可能です。

<xi:include></xi:include>

???

コールバック関数を使用したカーソルを生成します。

コールバック関数には初期化、位置更新、終了時の3種類のコールバックが設定できます。

今回は終了時のコールバックは使用していません。

???

UseCursorの代わりに、SetCursorで生成したカーソルを渡します。

???

初期化用コールバックです。カーソルが新規に生成されるときに呼び出されます。

このコールバックを使用せず、ALFuncWidgetCursor生成時に直接記述しても構いません。

???

カーソルの中心位置を指定します。

元ファイルはbmpなので中心位置は原点ですが、これを右端で上下中央を原点に変更します。

???

スプライトをカーソルに登録します。AddReleaseNodeを使用しているので、カーソル破棄時に一緒に破棄されます。

???

カーソル移動用のコントローラを使用します。座標を移動させるため、対象はPositionプロパティになります。

補間方法は2次関数の反転で、最初に急加速してゆっくり止まる動きになります。移動時間は8フレームです。

???

コントローラはまだ使用しないので、いったんスリープしておきます。

???

カーソル移動時のコールバックです。

カーソルを常に選択位置へ瞬時に移動する場合はこのコールバックは必要ありません。

引数はカーソル自身の他、瞬時に位置を変えるか、補間するかのフラグがあります。

???

ターゲットとなるウィジェットの範囲を取得します。カーソルはこの位置に合わせて移動させる必要があります。

???

instantlyフラグが立っているときは、初期化時やショートカットクリック等で瞬時に移動する必要があるので、座標を直接更新します。

???

instantlyフラグが立っていないときは、あらかじめ生成した補間コントローラを使って座標を移動させます。

第7章 モーション

次はウィジェットにモーションをつけてみます。

モーションはツールで作ったモーションデータを読む方法もありますが、 今回は動的モーションを使って、プログラムでモーションを作ります。

動的モーションはプログラムでモーションを生成する物です。 メモリや速度的には非効率ですが、ちょっとした動きを作るには便利です。

ウィジェットには各種ステート毎に呼び出すモーションIDを設定できます。 ステートとは、通常状態、選択状態、決定状態等です。 今回はその3種のみを使います。 その設定があると、ステート変更時に自動的にモーションが再生されます。

なお、今回はメイン関数以外の変更はないので、メイン関数以外のソースは省略します。

<xi:include></xi:include>

???

モーション対象のプロパティを取得します。今回は色のみを使用しますが、このほか座標、テクスチャ等複数の要素を組み合わせる事も可能です。

???

動的モーションを開始します。なお、終了は特にありません。

???

現在の色をフレーム0にキーとして設定します。

???

キーに設定するのは現在の値なので、明滅用に少し暗くした色を登録します。

???

モーションはデフォルト状態では設定した値の切り替えになるので、ここで補間方法を設定します。

今回はSin波を選びます

???

このモーションにIDをつけます。

一つのみのモーションを使う場合はIDの必要はありませんが、今回は複数モーションを切り替えるために設定をします。

ちなみに複数のモーション切り替えは、ChangeMotionやLoadMotionを使用します。

???

二つ目のモーションを作る場合、BeginDynamicMotionではなく、NewDynamicMotionを実行します。

これで新しいモーションを作る準備が出来ます。

???

このモーションは決定時に使うので、ループさせずに一回再生しただけで終了するようにします。

なお、決定時のモーションにこのようなループしないモーションが設定されていると、モーション終了時に決定状態が自動解除されます。

???

これは通常時のモーションです。

通常時のモーションを用意しないと、選択時から元に戻ったときに設定した値が元に戻りません。

その為、0フレームのみに通常時の色を設定しておきます。

???

それぞれのステートに対し、使用するモーションIDをセットします。

第8章 終わりに

以上がボタンウィジェットとカーソルを使用したウィジェットの基本的なチュートリアルです。

今回のチュートリアルではほとんどプログラムコードで記述しましたが、 これらはほとんどデータで記述する事が可能です。

また、各種イベントをスクリプト記述する事も出来るため、 アプリケーション側では最終的な結果のみを受け取るようにする事が出来ます。

現状でもデータを作れば動作可能ですが、 それらを簡単につくるGUIツールを制作中です。

ウィジェットには今回紹介しなかったいろいろな機能がまだ存在し、 複雑なメニューを作る時に役に立ちます。 それらは、別のチュートリアルとして取り上げる予定です。