Managing Multiple Rollouts in a Scripted Utility

MAXScript includes support for managing multiple rollouts in one utility, which is useful in large scripted utilities that are unwieldy in one rollout. There is one main rollout defined by the user-interface items in the utility definition. The other rollouts are defined as nested rollouts within the body of the utility definition. These other rollouts can be added to and removed from the Utilities panel under script control.

You can define extra rollouts with the rollout clause inside a utility definition:

utility foo "name"
(
local ...
spinner ...
...
rollout baz "name"
(
local ...
checkbox ..
on ...
)
...
)

Such nested rollouts can contain anything that a utility definition can contain with the exception of further nested rollouts. Nested rollouts are not automatically opened or closed when the parent utility rollout opens and closes. You need to explicitly do this in the open and close handlers, or other handlers or functions in the utility.

There are two functions for this:

addRollout <rollout> [ rolledUp:<boolean> ] removeRollout <rollout>

The rolledUp: parameter on the addRollout() function specifies whether the rollout is added in a rolled-up state. This defaults to false , so the rollout is added fully opened. The nested rollouts are arranged in the order of addRollout() calls, so take care in sequencing these to ensure the order you want.

The nested rollouts do not automatically get removed when the main utility rollout is closed. You must make sure they are explicitly removed, typically in the close handler for the main utility.

To always open and close extra rollouts when the main utility is opened and closed, place addRollout() and removeRollout() calls in the main utility open and close handlers.

FOR EXAMPLE

   on foo open do
   (
   ...
   addRollout panel_1
   addRollout panel_2 rolledUp:true
   ...
   )
   on foo close do
   (
   ...
   removeRollout panel_1
   removeRollout panel_2
   ...
   )

Calling removeRollout() on an already closed rollout is OK and does nothing. If during utility development, you forget to close a nested rollout, closing the entire MAXScript utility will remove any remaining open scripted rollouts.

Because these rollout definitions are nested within a utility, all the locals, functions, and other items in the utility are visible to nested rollouts, following the standard nested scoping in MAXScript. This means you can "reach out" and access the utility’s locals, user-interface control items, and functions.

Conversely, user-interface control items and locals in nested rollouts are exposed as properties of that rollout, so code in the main utility or other rollouts can "reach in" and access them. In the following example, the spinner bar change handler looks at the state of a check box in the nested rollout baz :

FOR EXAMPLE

   utility foo "name"
   (
   local ...
   local ...
   spinner bar ...
   ...
   rollout baz "name"
   (
   local ...
   checkbox baz_enable ...
   on ...
   )
   ...
   on bar changed val do
   if baz.baz_enable.checked == true then...

You can control the grouping of rollouts by supplying a category:<integer> header parameter before the opening parenthesis of the rollout body. The category numbers order the rollouts. In the following example, the rollouts are defined and added in a certain order, but displayed in another based on their category number:

FOR EXAMPLE

   (
   rollout first_rollout "1st Rollout" category:2
   (
   label rights "First"
   )
   rollout second_rollout "2nd Rollout" category:1
   (
   label second "Second"
   )
   rf = newRolloutFloater "Rollout Order Test" 200 140
   addRollout first_rollout rf
   addRollout second_rollout rf
   )