AnimButtonPluginリファレンス

概要：
	AnimButtonPlugin.ksは、アニメーションボタンを提供するプラグインで
	ある。
	アニメーションボタンはグラフィカルボタンの一種で、、用意された
	アニメーション画像ファイルとアニメーション定義ファイル(.bsdファイル)に
	従い、ボタン上の画像をアニメーションさせることができる。
	アニメーション定義ファイル(.bsd)の書式は、通常のKAGのアニメーション
	定義ファイル(.asd)とは異なるので注意。

	アニメーションボタンは自らレイヤを作成するので、kagの管理下にある
	レイヤは使用しない。また、通常のグラフィカルボタンと違い、
	messageレイヤにも属さない。表示プライオリティは、デフォルトでは
	「テキストの上かつメッセージ履歴の下」となっている。

****************************************************************************
アニメーション画像:
	アニメーション画像は、[button]タグで使用するボタン画像を縦に拡張した
	ものである。即ち、横方向には「通常」「クリック時」「フォーカス時」の
	画像が並び、縦方向にはそれぞれの場合のアニメーションパターンが列挙
	されている。アニメーションパターンは必ずしも縦いっぱいに並べなければ
	ならないわけではなく、例えば「通常時は4パターン、クリック時は
	アニメーションさせない」のであれば、クリック時の画像は一つだけを
	一番上に描画しておき、パターンを用意する必要はない。どのパターンを
	どのように表示するかは、後述するアニメーション定義ファイルに記述する。

****************************************************************************
アニメーション定義ファイル(.bsd)
	アニメーション定義ファイルは、アニメーションをどのように実行するかを
	記述したシナリオテキストファイルである。アニメーション画像ファイルの
	拡張子を.bsdに変更したものを用いる。
	シナリオファイルは*normal、*onenter、*onclickの三つのラベルから
	構成されている。それぞれ、通常時、フォーカス時、クリック時の
	アニメーションを定義する。

	特殊タグとして、[pattern]が使用できる。これは、以下の二つのパラメータを
	持ち、アニメーションパターンを指定するタグである。
	[pattern num=# index="xxx"]

	num=	全体のパターン数を指定する。indexは自動的に補正され、大きな
		値・小さな値を指定しても、この数を超えることはない
	index=	次に表示するパターンインデックスを、計算式で指定する。
		現在のパターンインデックスはindexで参照できる。例えば
		「index="0"」や「index="index+1"」のように指定する。TJS式と
		して評価するので、計算は何でもできる。

	このほかに、[wait time=xxx]、[jump target="xxx"]、[s]が指定できる。
	これだけあれば殆どのアニメーションは作成できる…と思う。

	記述例：
		*normal
		[pattern num=10 index=0]
		*normal_loop
		[wait time=100]
		[pattern index="index + 1"]
		[jump target="*normal_loop"]

		*onclick
		[pattern num=1 index=0]
		[s]

		*onenter
		[pattern num=10]
		; indexをあえて↑指定しないと、現在のindexを引き継ぐ
		*onenter_loop
		[wait time=100]
		[pattern index="index - 1"]  ←normalの逆回しっぽくになる？
		[jump target="*onenter_loop"]


****************************************************************************
内部情報
	アニメーションボタンは、kag.base.foreおよびkag.base.backの子レイヤと
	して作成される。表示優先順位は2000000-3で、これは履歴レイヤの直後と
	なっている。今は、右クリックでテキスト画面消去の場合、同時に
	消えるようになっている。

****************************************************************************
タグリファレンス for KAG：
	これはKAGスクリプト中で使用できるタグのリファレンス。.bsdファイル
	のリファレンスは後述。
	パラメータを指定しなかった場合、(def)またはdefaultと書いてあるものが
	デフォルト値として採用される。

[animbutton key= page=]
説明:
	アニメーションボタンを作成する。
引数:
	key=		ボタンのキー。指定しないと自動的に"all"が設定される。
			その場合、「そのボタンだけ操作する」ことはできず、
			全ボタン操作のみが可能になる。[animbutton_setopt]や
			[animbutton_erase]のkeyパラメータも参照のこと。
	page=		作成するページ。foreとbackがある。
		fore	foreに作成する(default)。すぐに表示される
		back	backに作成する
	※この他に、[animbutton_setopt]で指定できる全てのオプションが指定可能。
使用例:
	; ボタンを(100,25)に作成し、0.3秒でフェードインする
	[backlay]
	[animbutton page=back graphic="abc" height=50 left=100 top=25]
	[trans method=crossfade time=300]


[animbutton_erase]
説明:
	アニメーションボタンを消去する。
引数:
	key=		ボタンのキー。指定すると、該当ボタンだけを削除できる。
			指定しないと、全てのボタンが対象になる
	page=		消去するボタンが属するページ。
		fore	foreのボタンを消去する。画面上からすぐ消える
		back	backのボタンを消去する
		both	fore,back両方のボタンを消去する(default)
使用例:
	; 作成済みの全てのボタンを削除する
	[animbutton_erase]

	; 作成済みの全てのボタンを0.5秒でフェードアウト後削除する
	[backlay]
	[animbutton_erase page=back]
	[trans method=crossfade time=500]

	; ボタン"abc"だけを、0.5秒でフェードアウト後削除する
	[backlay]
	[animbutton_erase key="abc" page=back]
	[trans method=crossfade time=500]
	

[animbutton_setopt]
説明:
	アニメーションボタンのオプションを指定する
引数:
	オプションは、ButtonLayerの全てのプロパティに加え、[button]タグに
	近いいくつかが指定できる。プロパティを全て列挙するのは困難なので、
	以下には代表的なものを記す。
	graphic=	アニメーション画像ファイルを指定する。拡張子を指定する
			必要はない。透明色を含んだ.png画像であることが
			望ましい。
			これを指定すると、合わせてアニメーション定義ファイル
			(.bsd)も自動的に検索されて読み込まれる。定義ファイルが
			存在しない場合は[button]と同じ動作になる。
	height=		アニメーション画像の縦幅を指定する。ここで言う
			画像縦幅とは、表示されるボタンの縦幅であって、
			画像ファイルの縦幅とは異なる。画像ファイルの縦幅は
			画像ファイルを見れば判るが、ボタン縦幅は画像ファイル
			からは判断が難しいので、ここで指定する。アニメーション
			定義ファイルに書けばいいじゃん、という話もあるが、
			今は実現可能性が見えないのでそうしていない。将来
			実装できればこのパラメータは無くなる可能性がある。
			このパラメータは必ずgraphicと同時に指定すること。
	※以下は[button]タグのパラメータとほぼ同じ
	storage=	クリック時にjumpする時のjump先ファイル名を指定する。
			指定しなければ同じシナリオファイル内を示す。
	target=		クリック時にjumpする時のjump先ファイル名を指定する。
			指定しなければファイル先頭を示す。なお、storageも
			targetも指定されない場合は何もしない。
	hint=		ボタンがフォーカスされた時に表示されるヒントを指定する
	countpage=
		true	読んだと見なす(default)
		false	読んでないことにする
	top=		ボタンを表示する左上Y座標を指定する。(default=0)
	left=		ボタンを表示する左上X座標を指定する。(default=0)
	onenter=	ボタンにマウスカーソルが入った時に実行するTJS式を
			指定する。
	enterse=	ボタンにマウスカーソルが入った時に鳴らす音を指定する。
	entersebuf=	ボタンにマウスカーソルが入った時に鳴らす音のバッファ
			番号を指定する。(default=0)
	onclick=	ボタンをクリックした時に実行するTJS式を指定する。
	exp=		onclickと全く同じ
	clickse=	ボタンをクリックした時に鳴らす音を指定する。
	clicksebuf=	ボタンをクリックした時に鳴らす音のバッファを指定する。
			(default=0)
	onleave=	ボタンからマウスカーソルが出た時に実行するTJS式を指定
			する
	leavese=	ボタンからマウスカーソルが出た時に鳴らす音を指定する。
	leavesebuf=	ボタンからマウスカーソルが出た時に鳴らす音のバッファを
			指定する。(default=0)

****************************************************************************
タグリファレンス for .bsdファイル(アニメーション定義ファイル)：
	これは.bsdファイル中で使用できるタグのリファレンス。
	前述のように、.bsdファイルは以下の三つのラベルを頂く三つのスクリプトの
	集合である。それぞれのセクションは、[s]で終るか、[jump]でセクション中に
	戻ることが望ましい。
		*normal: マウスカーソルが乗っていない時の動作を規定する
		*onenter:マウスカーソルが乗った時の動作を規定する
		*onclick:マウスがクリックされた時の動作を規定する
	最初は*normalから実行される。

[pattern num= index=]
説明:	 アニメーションの個数と開始インデックスを指定する。num=は、セクション
	先頭では必ず設定すること。index=も、特別の事情がない限りは指定する
	こと。
引数:	num=	アニメーションの画像数。縦に何個列挙されているかを指定する。
		アニメーションは、常に「0〜ここで指定した値-1」の範囲で
		実行される。
	index=	アニメーション画像インデックスを指定する。0が一番上、1が
		その下、というように連続に指定されている。式を書くことが
		できる。現在のインデックス値はindexで参照できるので、
		「index="index+1"」と指定すると、インデックスを+1する
		ことができる。なお、indexが「0〜num-1」の範囲外の時は、
		自動的にindex = index%numとして範囲内にキャストされる。

[wait time=]
説明:	KAGのwaitタグと同じ。.bsdファイル中のwait。
引数:	time=	待ち時間。ms単位。		

[jump target=]
説明:	KAGのjumpタグと同じ。.bsdファイル中のjump。ただし、storage=は指定
	できないので、他の.bsdファイルにジャンプすることはできない。
引数:	target=	jump先ラベル名。

[s]
説明:	.bsdファイルのスクリプト実行を停止する。ただし、そこで完全に停止
	するわけではなく、マウスがクリックされたり移動したりすると、また
	*onclickなどの各ラベルから実行が再開される。
引数:	なし