Utility Clauses

Creating User Interfaces - Quick Navigation

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
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.

Utility Clauses

See Also