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> ] \
  [ autoLayoutOnResize:<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
   rollout bout "About My Utility"
   (
   button aboutMU "About" width:45 height:20
   on aboutMU pressed do
   messagebox "My First Utility\nby ME\nVersion .1"\
   title:"About My Utility"
   ) -- end rollout bout
   rollout creator "The Teapot"
   (
   group "Object Creator"
   (
   button tea "Teapot"
   spinner rad "Radius" range:[10,50,20] type:#integer
   spinner seg "Segments" range:[4,32,12] type:#integer scale:1
   )
   on tea pressed do
   (
   pot=teapot radius:rad.value
   pot.name="TestPot"
   pot.segs=seg.value
   ) -- end on tea pressed
   on rad changed value do
   pot.radius=value
   on seg changed value do
   pot.segs=seg.value
   ) -- end rollout creator
   on MyUtil open do
   (
   addRollout bout
   addRollout creator
   ) -- 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.