MessageBox(table)
| grandMA3 ユーザマニュアル » プラグイン » Lua 関数 - Object-Free API » MessageBox(table) | Version 2.0 |
説明
Lua 関数の MessageBox は、メッセージボックスを作成するために用いられます。単純なものから、多くのオプションやユーザ入力を持つ複雑なものまで、さまざまな情報ポップアップを作成できます。
この関数は、入力引数として1つのテーブルを指定します。このテーブルによって、メッセージボックスに表示する複数の要素を定義できます。
メッセージボックス内の要素は、アルファベット順に表示されます。
この関数は、ユーザ・インターフェース機能の一部です。
引数
- table:
関数への入力は、キーと値のペアによるテーブル形式で指定する必要があります。必要な要素には、変更されない場合に用いられるデフォルト値があります。キーが指定されている場合、値は任意の順序で定義できます。
テーブルには以下の要素を含めることができます。- title:
メッセージボックス・ポップアップのタイトルです。 - titleTextColor:
タイトルの文字色です。値は、カラーテーマ の UI Colors を参照する数値または文字列です。 - backColor:
ポップアップの枠や境界線の色です。値は、カラーテーマ の UI Colors を参照する数値または文字列です。 - icon:
ポップアップの左上隅に表示できるアイコンです。値は、整数値、あるいはテクスチャ・イメージの番号や名前を参照する文字列(ファイル形式なし)で指定できます。
アイコンを一覧表示するには、ChangeDestination GraphicsRoot/TextureCollect/Textures でテクスチャ・フォルダに移動して List コマンドを実行します。Command Line History ウィンドウに、すべてのテクスチャの番号と名前を含むリストが表示されます。 - message:
このメッセージ文字列は、ポップアップのメイン部分に表示されます。文字列は、"\n" で改行できます。 - messageTextColor:
メッセージの文字色です。値は、カラーテーマ の UI Colors を参照する数値または文字列です。 - timeout:
メッセージボックスが表示される時間を、ミリ秒単位の整数値で指定します。メッセージ領域の上部に、カウントダウン・タイマーが表示され、タイムアウトするとポップアップが閉じます。
タイムアウトによってポップアップが閉じると、true 値の success 要素が返されます (戻り値については後述を参照)。これは「普通に」閉じられたと見なされます。 - timeoutResultCancel:
この要素は、ポップアップがキャンセルされたかのように戻り値を変更できます。success 要素に対して true の代わりに false が返されます。 - timeoutResultID:
タイムアウトによって success 値 = true でポップアップを閉じられた場合、特別な戻り値を定義できます。例えば、値を99に設定すると、タイムアウトで閉じられたとき99が返されます。 - commands:
コマンドは、メッセージボックスの下部にボタンとして表示されます。ここでの入力は、以下のような構造を持つオブジェクトのテーブルです。- value:
結果として返される整数値です(後述を参照)。 - name:
ボタンに表示される文字列です。
- value:
- inputs:
文字列や数値を入力できるユーザ入力欄です。入力欄は、アルファベット順に表示されます。
入力欄は、以下のような構造のテーブルで定義します(例5を参照)。- name:
入力欄のラベルとして表示される文字列です。 - value:
入力欄のデフォルト入力値を表す文字列です。 - blackfilter:
入力できない文字を定義します。 - whitefilter:
入力可能な文字を定義します。 - vkPlugin:
ポップアップで画面キーボード・アイコン(
)がタップされたときに開く入力ポップアップの名前を表す文字列です。例5には、可能な vkPlugin 値のリストが含まれています。 - maxTextLength:
最大入力文字数を指定する整数値です。
- name:
- states:
状態を持つボタンです。状態ボタンには小さなチェックボックスがあり、true または false の状態を取ります。ボタンはアルファベット順に表示されます。
ボタンは、以下のような構造のテーブルで定義します(例4を参照)。- name:
ボタン上に表示される文字列です。 - state:
ボタンのチェックボックスの初期状態です。
- name:
- selectors:
セレクタボタンには、スワイプボタン(タイプ 0)とラジオボタン(タイプ 1)という2種類があり、それぞれ可能な値リストに基づいて値を選択できます。ボタンは、以下のような構造のテーブルで定義します。- name:
スワイプボタン上のテキスト、またはラジオボタン上部のラベルとして表示される文字列です。 - selectedValue:
デフォルトで選択されている値を整数値で指定します。 - type:
セレクタボタンの種類を以下の整数値で指定します。- 0:
ボタンをスワイプボタンとして定義します。 - 1:
ボタンをラジオボタンとして定義します。
- 0:
- values:
これは、セレクタボタンで使用できるさまざまな値を含む別のテーブルです。テーブルの各値要素は、["string"]=integer という構造になっています。文字列は、値に対して表示される名前です。整数は返される値で、selectedValue に用いられます(上述を参照)。使用例については、以下の例6を参照してください。
- name:
- title:
テーブルには、上述の要素の一部またはすべてを含めることができます。
上述の色は、カラーテーマ で定義されている UI Colors の文字列や数値で指定できます(例: "Global.Text" または 1.27)。
メッセージボックスには、少なくとも title、message、および timeout やいくつかの基本的なコマンドボタンが必要です。以下の最初の3例を参照してください。
戻り値
- table:
メッセージボックスからの戻り値は、テーブル形式で返されます。返されるテーブルは、メッセージボックスの要素と一致するように調整されます。例えば、メッセージボックスに選択ボタンがある場合、結果テーブルには選択ボタンからの戻り値を含む別のテーブルが存在します。結果の取得方法については、例を参照してください。
テーブルには、以下の要素を含めることができます。- success:
コマンドボタンのタップまたはタイムアウトによってメッセージボックスが閉じられた場合、ブール値の true を返します(例外については上述の timeoutResultCancel を参照)。 - result:
タップされたコマンドボタンの値またはタイムアウトの結果IDを表す整数値を返します。 - inputs (メッセージボックスに入力欄がある場合のみ):
入力欄の名前とその文字列値のリストを含む、キーと値のペア形式のテーブルです。 - states (メッセージボックスに状態ボタンがある場合のみ):
状態ボタンの名前とそのブール値のリストを含む、キーと値のペア形式のテーブルです。 - selectors (メッセージボックスにセレクタボタンがある場合のみ):
セレクタボタンの名前とその整数値のリストを含む、キーと値のペア形式のテーブルです。
- success:
メッセージボックスに、inputs、states、selectors がないにもかかわらず、スクリプトがテーブル要素を使おうとすると、エラーが送出されます。
結果の抽出方法については、例を参照してください。
例
以下は、メッセージボックスのさまざまな要素を示す6つの例です。要素は組み合わせることができますが、例では機能の違いを強調しています。
例1
1つの確認ボタンを表示する単純なメッセージボックスです。
Lua |
return function () |
例2
この例では、いくつかのテキストと2つのコマンドボタンを含むポップアップが開きます。
Lua |
return function () |
例3
この例では、メッセージボックスを3秒間表示した後、自動的に閉じます。
Lua |
return function () |
例4
この例では、メッセージボックスに状態ボタンを追加します。分かりやすいように、ボタンはテーブルとして追加しています。
Lua |
return function () |
例5
この例では、入力欄を表示しています。
Lua |
return function () |
例6
この例では、さまざまなセレクタボタンを表示しています。
Lua |
return function () |