commands/UI - lightvn

#freeze
TITLE:UI関連コマンド（Ver16.5.1）
#contents
~

*ボタン（button）[#button]
 ボタン btn1 a.png b.png c.png 200 300 40 透明無視 カメラ付着 ゲーム終了
 ボタン0 btn2 200 300 40 透明無視 カメラ付着
-Imagesフォルダ内にある画像を素材として、特定のコマンドを持つボタンを作成します。
コマンドを持たせないこともできます。
-Ver14.6.0より、適用コマンドの基準は「スクリプトスタックの最上位」ではなく「ボタン個体の存在するスクリプト」となりました。
-設定項目「ボタンクリック時イメージ」は、Ver8.0.0以降においてはコマンド「ハイライト条件」で設定した条件を満たす場合に表示を継続させることができます（項目参照：[[ハイライト条件>commands/UI#highlight_if]]）。
-ボタン0……透明度0の状態で設定します。インや透明度コマンドで表示することができますが、''透明度0でもボタンはコマンドを適用してしまう''ので注意が必要です。
-設定項目「透明無視」は、素材の透明度0の領域をボタン反応範囲から除外します。
これにおける「透明度0」は「見た目上の透明度0の領域」ではなく「''素材上の透明度0の領域（アルファ値が0）''」を指します。
したがって、コマンド「ボタン0」「透明度」等で個体全体の透明度が0になっても個体全体がボタン反応範囲から除外されるわけではなく、''素材上の透明度が0より大きい領域はボタン反応範囲として機能します''。

||設定項目|記述の種類|説明|h
|&color(Red){【必須】};|名前|命名|ボタンに設定する個体名|
|CENTER:（※1）|ボタン通常イメージ|ファイル名&br;または&br;個体名|通常時に使用するボタン画像ファイル名&br;または&br;登録済みアニメ名（※2）|
|CENTER:（※1）|ボタンタッチ時イメージ|ファイル名&br;または&br;個体名|カーソルを当てた時に使用するボタン画像ファイル名&br;または&br;登録済みアニメ名（※2）|
|CENTER:（※1）|ボタンクリック時イメージ|ファイル名&br;または&br;個体名|クリック時に使用するボタン画像ファイル名&br;または&br;登録済みアニメ名（※2）|
|&color(Red){【必須】};|x座標|数値|素材左上の頂点のx座標（左右方向の座標）|
|&color(Red){【必須】};|y座標|数値|素材左上の頂点のy座標（上下方向の座標）|
|&color(Red){【必須】};|r座標|数値|素材左上の頂点のr座標（手前方向の座標）|
||透明無視|設定項目の語句&br;（透明無視）|素材の透明度0の領域をボタン反応領域から除外|
||カメラオプション|※3|カメラに対する反映方法|
||Light.vnコマンド|コマンド|クリック時に適用するコマンド|
※1……当該3項目はコマンド「[[タッチ素材設定>commands/UI#touchableRes]]」の宣言以降において省略することができます。
※2……「登録済みアニメ名」に関しては項目参照：[[アニメ登録>commands/transition#animation]]
※3……「カメラオプション」に関しては項目参照：[[カメラオプションについて>command#command1a5]]



/////////////////////////////////////////////////////////////////



*ボタン文字（btnText）[#btnText]
 ボタン文字 ita Harenosora.otf 24 "設定画面へ"
 ボタン文字 ita2 Harenosora.otf 24 -10 -2 "設定画面へ"

-指定したボタンにテキストを表示します。横書きの一行表示に限定されています。
-ボタンへの文字使用を簡略化するためのコマンドです。
-''ボタン文字には文字関連のコマンドを適用することができます''。
Ver6.2.0からVer7.1.0までは対象名にボタンの個体名を、Ver7.6.0以降はボタン名の末尾に「_text」を付与したものを設定します。
-初期設定ではフォントに文字陰を適用し、ボールド体を使用しません。
-Ver10.0.0から、ボタン中央に対する文字位置の設定項目が追加されました。
設定しなければ文字はボタン中央に整列します。変更する場合は、左右方向（x方向）は右、上下方向（y方向）は下を正として移動量を指定します。

||設定項目|記述の種類|説明|h
|&color(Red){【必須】};|ボタン名前|個体名|テキストを表示するボタンの個体名|
|&color(Red){【必須】};|フォント名|ファイル名|テキストに使用するフォント|
|&color(Red){【必須】};|フォント大きさ|数値|文字の大きさ（単位：px）|
||相対x座標|数値|ボタン中心を基準とする文字列中心点のx座標（左右方向の座標）|
||相対y座標|数値|ボタン中心を基準とする文字列中心点のy座標（上下方向の座標）|
|&color(Red){【必須】};|テキスト|テキスト|表示させるテキスト|



/////////////////////////////////////////////////////////////////



*ボタングループ化（setButtonGroup）[#setButtonGroup]
 ボタングループ化 ui_menu_

-指定した文字列を個体名の先頭に持つボタン個体をグループ化します。
グループ化されたボタン個体は、グループ内の個体のひとつが選択された時点で他の個体の選択を禁止します。
分岐の選択肢において、他の選択肢を選んで意図しないジャンプ先となってしまうことを避ける等の使い方があります。

||設定項目|記述の種類|説明|h
|&color(Red){【必須】};|グループ接頭辞|個体名（一部）|グループ化するボタン個体が先頭に持つ文字列|



///////////////////////////////////////////////////////////////



*反応範囲（touchArea）[#touchArea]
 反応範囲 btn1 50 50 400 400
-ボタン自身の反応範囲領域を設定するコマンドです（Ver7.1.0以前においては動作しません）。
12.0.0以前におけるコマンド名は「ボタン反応範囲」です。
-''反応範囲の設定は、対象となるボタンの左上座標からの相対座標です''。
たとえば、大きさが500×100のボタンが座標（100,100）に設定されている場合において、コマンド「ボタン反応範囲 (ボタン名) 50 10 400 80」を設定します。
このとき、反応範囲として指定される領域は、左右方向が150から550まで、上下方向が110から190までとなります。
-対象となるボタンの本来の領域よりも大きな領域を反応範囲とすることも可能です。

||設定項目|記述の種類|説明|h
|&color(Red){【必須】};|ボタン名前|個体名|反応範囲を設定するボタンの個体名|
|&color(Red){【必須】};|相対x座標|数値|反応範囲の左上の頂点の相対x座標（左右方向の座標）|
|&color(Red){【必須】};|相対y座標|数値|反応範囲の左上の頂点の相対y座標（上下方向の座標）|
|&color(Red){【必須】};|幅|数値|反応範囲の左右方向の大きさ|
|&color(Red){【必須】};|高さ|数値|反応範囲の上下方向の大きさ|



///////////////////////////////////////////////////////////////



*画面内反応範囲（touchAreaScreen）[#touchAreaScreen]
 画面内反応範囲 btn1 500 200 400 400
-ボタンの反応する範囲領域を設定するコマンドです。
''設定した範囲以外の領域にある、指定したボタンの反応範囲は無効となります''。
マスクと併用することで、スクロールメニュー等の実装が可能です。
-反応範囲は絶対座標で指定します。
たとえば、大きさが500×100のボタンが座標（100,100）に設定されている場合において、コマンド「ボタン反応範囲 (ボタン名) 50 10 400 80」を設定します。
このとき、反応範囲として指定される領域は、左右方向が50から450まで、上下方向が10から90までとなります。
-対象となるボタンの本来の領域よりも大きな領域を反応範囲とすることも可能です。

||設定項目|記述の種類|説明|h
|&color(Red){【必須】};|ボタン名前|個体名|反応範囲を設定するボタンの個体名|
|&color(Red){【必須】};|x座標|数値|反応範囲の左上の頂点のx座標（左右方向の座標）|
|&color(Red){【必須】};|y座標|数値|反応範囲の左上の頂点のy座標（上下方向の座標）|
|&color(Red){【必須】};|幅|数値|反応範囲の左右方向の大きさ|
|&color(Red){【必須】};|高さ|数値|反応範囲の上下方向の大きさ|



///////////////////////////////////////////////////////////////



*反応透明度（touchAlpha）[#touchAlpha]
 反応透明度 btn1 50
-ボタンの全体透明度が指定した値未満である時に反応しないように設定します。
-素材画像上の透明度ではなく、''Light.vn上の個体としての透明度''が検出されます。
したがって、画像素材に透明領域（透明度0）があったとしても、個体の透明度を変更していなければ反応してしまいます。
上記の例では、ボタン個体「btn1」の透明度をコマンド「透明度」等で50未満に変更した場合には反応しなくなります。
-透明度の変化は連続的なものでも検出されます。
したがって、コマンド「イン」「アウト」によるフェードの途中でも検知下限を下回れば反応しなくなります。

||設定項目|記述の種類|説明|h
|&color(Red){【必須】};|ボタン名前|個体名|検知透明度を設定するボタンの個体名|
|&color(Red){【必須】};|検知透明度|数値|反応処理を検知する下限の透明度|



//////////////////////////////////////////////////////////////////////



*ハイライト条件（highlight_if）[#highlight_if]
 ハイライト条件 btn1 "vn_sysTextReadMethod == 1"
-ボタンの表示画像を「UI活性時画像（UIタッチ時画像）」で固定する条件を設定します。
条件式が満たされている場合には表示画像が固定され、満たされていない場合には表示画像が元の設定に従うようになります。
--たとえば、上記の例において（vn_sysTextReadMethod = 1）であれば、「btn1」はカーソルの接触に関係なく「UI活性時画像（UIタッチ時画像）」が表示されます。
また、（vn_sysTextReadMethod = 0）であれば、「btn1」は通常どおりにカーソルの接触に応じて表示画像が変更されます。
-Ver8.0.0未満においては、ボタンに特定のコマンド（「文字進行」等）を設定している場合にコマンドの適用状態に応じて自動的に表示画像を固定していましたが、Ver8.0.0において特別に設定することが必要となりました。
-''条件式はテキストとして記述するため、先頭と末尾に「"」を必要とします''。式であっても「()」で囲むわけではありません。

||設定項目|記述の種類|説明|h
|&color(Red){【必須】};|ボタン名前|個体名|カーソルに反応するボタンの名前|
|&color(Red){【必須】};|活性条件|テキスト|ボタンの表示画像を固定する条件式|



//////////////////////////////////////////////////////////////////////



*タッチ開始時（onTouchStart）[#onTouchStart]
 タッチ開始時 btn1 スクリプト system.txt showbtn
-ボタンやトラックボールにカーソルを合わせた時に適用するコマンドを設定します。

||設定項目|記述の種類|説明|h
|&color(Red){【必須】};|判定対象|個体名|カーソルに反応するボタンおよびトラックバーの名前|
|&color(Red){【必須】};|タッチ時発動コマンド|コマンド|カーソルを合わせた時に適用するコマンド|



//////////////////////////////////////////////////////////////////////



*タッチ終了時（onTouchExit）[#onTouchExit]
 タッチ終了時 btn1 スクリプト system.txt hidebtn
-ボタンやトラックボールからカーソルを離す時に適用するコマンドを設定します。
-''カーソルを合わせていない時に常時適用されるコマンドではありません''。
必ず「カーソルを合わせた後で、カーソルを離す時」のみにコマンドが適用されます。
「[[タッチ開始時>commands/UI#onBtnTouch]]」によって適用されたコマンドを初期化する等の使い方ができます。

||設定項目|記述の種類|説明|h
|&color(Red){【必須】};|判定対象|個体名|カーソル外に反応するボタンおよびトラックバーの名前|
|&color(Red){【必須】};|未タッチ時発動コマンド|コマンド|カーソル外の状態において適用するコマンド|



//////////////////////////////////////////////////////////////////////



*タッチ状態強制（touchStateForce）[#touchStateForce]
 タッチ状態強制 btn1 2
 タッチ状態強制 btn1 false
-指定したボタンやトラックバー（トラックボール）を指定した状態で固定します。
状態を固定されると、カーソルを合わせたりクリックしたりしても状態は変化せず、反応もしなくなります。
-状態は番号で指定します。
--''「0」''
カーソルを合わせていないのと同じ状態にします。
--''「1」''
カーソルを合わせているのと同じ状態になります。
--''「2」''
クリックと同じになり、コマンドも適用されます。
-状態強制を解除するには、真偽値「false」を指定します。

||設定項目|記述の種類|説明|h
|&color(Red){【必須】};|ボタン名前|個体名|状態を固定するボタンおよびトラックバーの名前|
|&color(Red){【必須】};|状態番号|数値（0,1,2）|固定する状態を表す番号|

||設定項目|記述の種類|説明|h
|&color(Red){【必須】};|ボタン名前|個体名|状態を固定するボタンおよびトラックバーの名前|
|&color(Red){【必須】};|強制設定解除|真偽値（false）|状態強制の解除を指定|



///////////////////////////////////////////////////////////////////////////



*タッチ素材設定（touchableRes）[#touchableRes]
 タッチ素材設定 a.png b.png c.png touchbtn.ogg clickbtn.ogg d.png e.png
-UI（ボタンおよびトラックバー）に使用する画像と効果音のファイルを事前に一括で設定します。
再度の設定があるまで、このコマンド以降に設定されるUIには、このコマンドで指定した素材が用いられます。
-画像素材はいずれも同じサイズのものを設定する必要があります。
-''UIに対する効果音の設定はこのコマンド限定の機能です''（Ver12.0.0現在）。
ただしコマンド「ボタンタッチ時」でタッチ時の効果音を設定することは可能です。
--他コマンドにおいて、各ボタンに設定された効果音を対象に指定することができます。
UIタッチ時音を対象に指定する場合には、対象名に「vn_」+「ボタン個体名」+「_touchedSound」を記述します。
UIクリック時音を対象に指定する場合には、対象名に「vn_」+「ボタン個体名」+「_clickedSound」を記述します。
たとえば、前者は「vn_btn1_touchedSound」、後者は「vn_btn1_clickedSound」と記述します。
-''「UI活性時画像」「UI非活性時画像」の設定はこのコマンド限定の機能です''（Ver12.0.0現在）。
「UI活性時画像」は、コマンド「ハイライト条件」で指定した条件に合致する場合における画像素材を指定します。未指定の場合には「UIクリック時画像」が用いられます。
「UI非活性時画像」は、Ver12.0.0現在では未実装項目となっているため、指定は不要です。
-''設定項目「UIタッチ時音」「UIクリック時音」に「""」を記述することによって、タッチ時やクリック時の効果音の設定を省略できます（Ver5.7.0以前は非対応）''。

||設定項目|記述の種類|説明|h
|&color(Red){【必須】};|UI通常画像|ファイル名&br;または&br;個体名|通常時に使用するUI画像ファイル名&br;または&br;登録済みアニメ名（※1）|
|&color(Red){【必須】};|UIタッチ時画像|ファイル名&br;または&br;個体名|カーソルを当てた時に使用するUI画像ファイル名&br;または&br;登録済みアニメ名（※1）|
|&color(Red){【必須】};|UIクリック時画像|ファイル名&br;または&br;個体名|クリック時やコマンド適用時に使用するUI画像ファイル名&br;または&br;登録済みアニメ名（※1）|
||UIタッチ時音|ファイル名|カーソルを当てた時の効果音のファイル名|
||UIクリック時音|ファイル名|UIをクリックした時の効果音のファイル名|
||UI活性時画像|ファイル名&br;または&br;個体名|ハイライト条件合致時に使用するUI画像ファイル名&br;または&br;登録済みアニメ名（※1）|
|（※2）|UI非活性時画像|ファイル名&br;または&br;個体名|（※2）|
※1……「登録済みアニメ名」に関しては項目参照：[[アニメ登録>commands/transition#animation]]
※2……Ver12.0.0現在では機能しないため、指定は不要です。



////////////////////////////////////////////////////////////////////////////



*タッチ処理順位（touchFilterRange）[#touchFilterRange]
 タッチ処理順位 0
-領域の重なるボタンおよびトラックボールの存在時において、重複領域がクリックされた際の処理を設定します。
デフォルトは「0」です。
--「タッチ処理順位 0」……クリック座標に領域を持つすべてのボタンが選択されます。
--「タッチ処理順位 1」……レイヤーの値が最も大きいボタンのみ選択されます。
-設定の有効範囲は現画面領域です。画面領域が変更されると「0」に初期化されます。

||設定項目|記述の種類|説明|h
|&color(Red){【必須】};|0&br;または&br;1|数値|ボタンおよびトラックボールの重複領域のクリックに対する処理|



////////////////////////////////////////////////////////////////////////////



*トラックバー（trackbar）[#trackbar]
 トラックバー c_textspeed 300 100 170 横 500 vn_sysTextSpeed 10 800 trackball.png trackball_on.png trackball_click.png カメラ付着
-変数操作を行うことができるトラックバーを設定します。
-このコマンドでは、''トラックバーは透明の領域として設定され、トラックボールのみが表示されます''。
したがって、コマンド「絵」などを用いてトラックバー自体の素材を設定しておく必要があります。
-変数には、コマンド「変数」で設定したものの他に、特定のシステム変数を用いることができます（項目参照：[[変数>commands/var#var]]）。
-設定項目「調整完了後実行コマンド」は、トラックバーによる変数操作の完了後にコマンドを適用するよう指定します。
調整完了の効果音や設定調整の実演等に用いることが想定されています。

||設定項目|記述の種類|説明|h
|&color(Red){【必須】};|トラックバー個体名|命名|トラックバーに設定する個体名|
|CENTER:（※1）|トラックボール通常イメージ|ファイル名&br;または&br;個体名|通常時に使用するトラックボール画像ファイル名&br;または&br;登録済みアニメ名（※2）|
|CENTER:（※1）|トラックボールタッチ時イメージ|ファイル名&br;または&br;個体名|カーソルを当てた時に使用するトラックボール画像ファイル名&br;または&br;登録済みアニメ名（※2）|
|CENTER:（※1）|トラックボールクリック時イメージ|ファイル名&br;または&br;個体名|クリック時に使用するトラックボール画像ファイル名&br;または&br;登録済みアニメ名（※2）|
|&color(Red){【必須】};|x座標|数値|トラックバー領域の左上頂点のx座標（左右方向の座標）|
|&color(Red){【必須】};|y座標|数値|トラックバー領域の左上頂点のy座標（上下方向の座標）|
|&color(Red){【必須】};|r座標|数値|トラックバー領域の左上頂点のr座標（手前方向の座標）|
|&color(Red){【必須】};|縦&br;または&br;横|設定項目の語句&br;（縦・横）|トラックバーの方向|
|&color(Red){【必須】};|長さ|数値|トラックバーの長さ|
|&color(Red){【必須】};|変数名|個体名|操作対象となる変数の個体名|
|&color(Red){【必須】};|左側・上方変数値|数値|左端または上端に設定する変数値|
|&color(Red){【必須】};|右側・下方変数値|数値|右端または下端に設定する変数値|
||透明無視|設定項目の語句&br;（透明無視）|素材の透明度0の領域をトラックボール反応領域から除外|
||カメラオプション|※3|カメラに対する反映方法|
||調整完了後実行コマンド|コマンド|トラックバーによる変数操作の完了後に適用するコマンド|
※1……当該3項目はコマンド「[[タッチ素材設定>commands/UI#touchableRes]]」の宣言以降において省略することができます。
※2……「登録済みアニメ名」に関しては項目参照：[[アニメ登録>commands/transition#animation]]
※3……「カメラオプション」に関しては項目参照：[[カメラオプションについて>command#command1a5]]