Utility Clauses

The <utility_body> of a scripted utility definition is composed of a sequence of utility clauses as follows:

<utility_body> ::= { <utility_clause> }+

where

<utility_clause> ::= <rollout_clause> | <nested_rollout>

A <utility_clause> can contain one or more instances of <rollout_clause> or <nested_rollout>. A nested rollout is basically another self-contained rollout definition which can be used to construct scripted utilities with multiple rollouts or populate rollout floater windows that may be associated with the utility. A <nested_rollout> is defined as follows:

rollout <var_name> <description_string>
[ rolledUp:<boolean> ] [ silentErrors:<boolean> ]
( <rollout_body> )

where

<rollout_body> ::= { <utility_clause> }+

In other words, a rollout definition is identical to a utility definition except its description string is not displayed in the Utilities list in the MAXScript rollout. In fact, a utility can just be considered a special case of a rollout, and both are instances of the Rollout class.

As an example, consider the following script. In this script, line 1 defines the start of the utility, and the utility body is lines 2 through 42. The following line ranges are utility clauses: 3 (a rollout clause), 5 to 9 (a nested rollout), 11 to 30 (a nested rollout), 32 to 35 (a rollout clause), and 37 to 40 (a rollout clause).

Script:

utility MyUtil "My Utility"

(

local pot

(

messagebox "My First Utility\nby ME\nVersion .1" \

)--end rollout bout

rollout creator "The Teapot"

(

group "Object Creator"

(

button tea "Teapot"

spinner seg "Segments" range:[4,32,12] type:#integer scale:1

)

on tea pressed do

(

pot.name="TestPot"

pot.segs=seg.value

) -- end on tea pressed

on seg changed value do

pot.segs=seg.value

) -- end rollout creator

on MyUtil open do

(

) -- end on MyUtil open

on MyUtil close do

(

removeRollout bout

removeRollout creator

) -- end on MyUtil close

)--end utility MyUtil

The Utilities panel rollouts created by the previous script look like the following:

Multiple rollouts defined in a utility

You can also define rollouts outside utility definitions when you want to add them to a rollout floater window that may not be associated with a scripted utility. This is described more fully in Rollout Floater Windows.

A value is created for a utility or rollout when the script defining the utility or rollout is executed. In general, the lifetime of a utility value is the entire 3ds Max session, unless a new utility with the same name is executed. The lifetime of a rollout defined in a utility is the lifetime of the utility value. The lifetime of a rollout defined outside a utility is the lifetime of the context the rollout was defined in. For more information, see Scope of Variables.