ロールアウト句

ロールアウト句は、ロールアウト(ユーティリティはロールアウトの特別な形であるとみなされます)を定義します。次の基本的な 4 つの項目のいずれかになります。

ローカル変数、関数、または構造体の定義 は、スコープがロールアウトである変数、関数、および構造体です。これらのローカルはロールアウトの値が存在する限り存在します。ロールアウトの値は、新しい値がロールアウトの変数名に代入されるまで存在します。ローカル変数は、選択オブジェクトや生成したオブジェクトの配列など、ロールアウトに関連付けられた作業データの保存に特に便利です。ローカルの可視性、外部コードからのロールアウトローカルへのアクセスについては、「ロールアウトコード内のローカル、関数、構造体、ユーザインタフェース項目の可視性」および「外部コードからロールアウトのローカルおよび他の項目へのアクセス」を参照してください。
マウスツールは、3ds Max のビューポートでのマウスクリックに従って一連のアクションを実行するために使用します。詳細は「スクリプト化されたマウスツール」を参照してください。
ユーザインタフェースコントロール項目は、ボタン、スピナー、リストボックスなどのロールアウトに表示される要素です。
イベントハンドラは、特定のユーザインタフェースコントロール項目に関連付けられた特殊な関数です。　イベントハンドラでは、ユーザがユーザインタフェース項目を操作したときに起動する処理を指定します。たとえば、ユーザがボタンを押したり、スピナーを調整した場合に、イベントハンドラが呼び出されます。これらのユーザアクションは名前付きイベントを生成し、ユーザアクションが発生すると指定したオプションのイベントハンドラが呼び出されます。たとえば、DoIt という名前のボタンを押した場合、on DoIt pressed イベントハンドラ式が実行されます。

<rollout_clause> は、次のように定義されます。

<rollout_clause> ::= <local_variable_decl> | <local_function_decl> | <local_struct_decl> | <global_variable_decl> | <mousetool> | <user_interface_item> | <item_group> | <event_handler>

ローカル

<local_variable_decl> 、 <global_variable_decl> 、 <local_function_decl> 、および <local_struct_decl> は、MAXScript 内のローカルおよびグローバル変数、ローカル関数、ローカル構造体の定義とまったく同義です。

<local_variable_decl> ::= local <decl> { , <decl> } 
<decl> ::= <name> [ = <expr> ] -- optional initial value

<global_variable_decl> ::= global <decl> { , <decl> } 
<decl> ::= <name> [ = <expr> ] -- optional initial value

<local_function_decl> ::= [ mapped ](function | fn) <name> { <argument> } = <expr>

<local_struct_decl> ::= struct <name> ( <member> { , <member> } )
<member> ::= ( <name> [ =<expr> ] | <local_function_decl> )

上記の例を、次に順番に示します。

local numSelected
global foo
local numSelected = 0
fn onlyOneSelected = (selection.count == 1)
struct parents (mother="", father="")

スクリプトを作成するときは、ローカル変数およびグローバル変数を明示的に宣言することをお勧めします。暗示的な宣言は簡易的に提供されるものであり、通常、リスナーでインタラクティブに作業する場合や短いスクリプトを作成する場合に使用します。長いスクリプトを作成する場合は、変数を明示的に宣言するとエラーを軽減し、コードが読みやすくなります。また、グローバル変数がどうしても必要な場合を除き、すべての変数をローカルとして宣言することをお勧めします。この理由については、「変数のスコープ」を参照してください。

ユーザインタフェース項目

<user_interface_item> では、個々のボタン、チェックボックス、スピナー、またはその他のロールアウトに表示されるユーザインタフェースコントロール項目を定義します。これらのユーザインタフェースコントロール項目については、「ロールアウトユーザインタフェースコントロール」を参照してください。

<item_group> は、一連のユーザインタフェース項目をロールアウトのラベルのついたボックス内に配置し、大きなロールアウトを意味のあるグループに整理するために使用します。

構文を次に示します。

group <group_label_string> 
( 
{ <user_interface_item> } 
)

group の使用例を次のスクリプトに示します。

例:

utility Infinity "Game Utilities"
(
group "Lighting"
(
label label1d "Number of Day lights:" across:2 offset:[10,0]
label label2d "0" offset:[10,0]
label label1n "Number of Night lights:" across:2 offset:[13,0]
label label2n "0" offset:[10,0]
label label3
Radiobuttons WhichOn "Active Lights:" labels:#("Day","Night")
)
group "Scene Data Dump"
(
Button scenedump "Dump Scene Data"
)
group "Exclusions/Inclusions"
(
Button DispExcl "Unhide Exclusions&Inclusions"
)
group "Camera Mattes"
(
radiobuttons CamMatte labels:#("None","1","2","3","4") columns:3
)
Button resetb "Reset"
)
createDialog infinity

上記のスクリプトが生成するユーティリティパネルロールアウトは、次の図のようになります。

グループユーザインタフェース項目を使用したゲームユーティリティのロールアウト

注:グループは、技術的にはユーザインタフェースコントロールではありません。インタフェースコントロールであるグループを使用する場合は、GroupBox ユーザインタフェースコントロールの使用を考えてみてください。

内部的には、グループは GroupStartControl クラスと GroupEndControl クラスの 2 つのコントロールとして実装され、グループ化されたユーザインタフェースをカッコのように取り囲みます。

3ds Max 8 以降では、ロールアウトの .controls プロパティを使用してアクセスすれば、 .caption プロパティにアクセスして、これらを変更することができます。この機能は以前のバージョンにはなかったものです。

例:

rollout test "Test"
(
group "Group"
(
button pressme "Press Me"
)
)
createDialog test
test.controls
test.controls[1].caption = "XXX" --this is the GroupStartControl
test.controls[3].caption = "Test me" --this is the GroupEndControl
--Both change the group's caption!

3ds Max 2010 以降では、ユーザインタフェースコントロールのイベントハンドラは、グループの本体に含めることができます。旧バージョンの 3ds Max では、イベントハンドラをグループ内部に含めると、構文エラーが発生していました。

例:

rollout test "Test"
(
group "Group"
(
button pressme "Press Me"
--In versions prior to 3ds Max 2010,
--this would have caused a Syntax Error:
on pressme pressed do print "Pressed!"
) --because the handler is inside the group's body.Now allowed.
)
createDialog test

イベントハンドラ

<event_handler> は、ユーティリティまたはロールアウトに対する特殊な関数定義ローカルで、ユーザがユーザインタフェース項目を操作したときに処理を実行するために使用します。たとえば、イベントハンドラはユーザによるボタンの操作、スピナーの調整、ユーティリティやロールアウトの起動/終了、ロールアウトフロータウィンドウのリサイズや移動の際に呼び出されます。これらのユーザアクションは名前付きのイベントを生成し、アクションが発生するとそのイベントに設定されたイベントハンドラが呼び出されます。イベントハンドラを定義する構文を次に示します。

on <item_name> <event_name> [ <argument> ] do <expr>

<item_name> には、このハンドラが結びついている項目の名前を指定します。 <event_name> には、処理するイベントのタイプを指定し、ハンドラにさまざまな値を渡すためにオプションの <argument> を使用します。指定できるイベントは、項目のタイプによって異なります。指定可能なイベントを次に示します。

pressed changed picked entered selected resized moved open close

各ユーザインタフェース項目のタイプに対して使用できるイベントと渡される引数については、各タイプの説明で定義されています。詳細は、「ロールアウトユーザインタフェースコントロール」を参照してください。ユーティリティやロールアウトで使用できるイベントと渡される引数については、「ユーティリティおよびロールアウトのプロパティ、メソッド、およびイベントハンドラ」を参照してください。

スクリプト化されたロールアウト内のイベントハンドラ関数は、ハンドラをユーザインタフェース項目のプロパティとして参照することでアクセスや呼び出しができます。イベントハンドラ関数は、イベント名をサブプロパティ名として使用して、該当項目のサブプロパティとしてアクセスされます。たとえば、スプリプト化されたロールアウトに foo という名前のチェックボックス項目があり、 on foo changed イベントハンドラを定義した場合は、次のようにイベントハンドラを呼び出すことができます。

foo.changed true -- call foo's 'changed' handler function, passing argument of true

または、スプリプトロールアウトに apply という名前のボタン項目があり、 on apply pressed イベントハンドラを定義した場合は、次のようにイベントハンドラを呼び出すことができます。

例

apply.pressed() -- call apply’s 'pressed' handler function, no argument.

イベントハンドラ関数は、項目のサブプロパティとしてアクセスできます。

例

ApplyPressedEH = apply.pressed

変数 ApplyPressedEH に対する on apply pressed イベントハンドラ関数値のコピーを保存します。イベントハンドラ関数は、この方法でのみ読み込むことができます。このハンドラ関数を別のユーザ定義関数に設定することはできません。