Utility and Rollout Properties, Methods, and Event Handlers

Properties

Several properties are available for scripted utilities and rollouts that provide access to the current state of the rollout.

Rollout Properties:

<rollout>.name String, read-only

The name of the rollout.

<rollout>.title String

Title of rollout.

You cannot change the title of a rollout or rollout floater registered as a dialog bar.

<rollout>.open Boolean

If true , the rollout is open, false it is rolled up. You can assign true or false to this property to open or roll up the rollout.

<rollout>.scrollPos Integer

Scroll position of panel the rollout is in.

Setting this property does nothing if the rollout is a Dialog, dialogBar, or is in an extended viewport. Will always be 0 in these cases.

<rollout>.height Integer

Gets/sets the Height of the rollout in pixels.

<rollout>.width Integer

Gets/sets the Width of the rollout.

Setting this property does nothing if the rollout is in a rolloutfloater, subRollout, or a command panel.

If the rollout is in an extended viewport, the .width and .height properties report the width and height of the viewport. The properties cannot be set for this case.

<rollout>.controls Array of ui elements, read-only

Returns an array of all controls in the rollout.

<rollout>.inViewport Boolean, read-only

Returns True when the rollout is in extended viewport.

<rollout>.dialogBar Boolean, read-only

Returns True when the rollout is registered as a dialog bar.

<rollout>.inDialog Boolean, read-only

Returns True when the rollout is currently displayed in a dialog created using createDialog <rollout>. Always valid.

<rollout>.isDisplayed Boolean, read-only

Returns true if the rollout is currently displayed, false otherwise.

<rollout>.visible Boolean

Gets or sets the visibility of a rollout if it is displayed in a dialog. If true (the default), the rollout is visible in the UI. If false , the rollout is hidden in the UI, but is still accessible via MAXScript. Available in 3ds Max 2021 and higher. Note: This property does not affect rollout visibility in a rollout floater, only in a dialog created with createDialog().

For Example:

rollout test "Test" (
    button bt_test "Show/Hide Rollout"
    on bt_test pressed  do  test.visible = not test.visible
)

createDialog test 

<rollout>.owner Object, read-only

If the rollout is being displayed by a scripted plugin or a Custom Attribute, the property will contain the scripted plugin or CA instance. This property was added in 3ds Max 8 to make it easier to access the variables in a scripted plugin or CA instance when a debugger break occurs in a rollout event handler. In this case, the owner of the event handler is the rollout, so you can access the scripted plugin or CA instance using getVar owner.owner .

<rollout>.hwnd Integer, read-only

Contains the Window HWND handle of the rollout if the rollout is open, or 0 if it is closed.

Available in 3ds Max 2011 and higher.

<rollout>.rolloutFloater RolloutFloater, read-only

Contains the rollout floater the rollout is in, or undefined if the rollout is not in a floater. Available in 3ds Max 2019 and higher.

<rollout>.autoLayoutOnResize Boolean

True if auto layout on resize is enabled for the rollout. Available in 3ds Max 2019 and higher.

Rollout Methods:

Several methods are available for opening and closing utilities, and adding and removing rollouts in the Utilities panel. These methods are:

openUtility <utility>

Opens the utility’s main rollout in the Utilities panel. This is equivalent to selecting the utility from the Utilities list in the MAXScript’s Utilities panel rollout.

closeUtility <utility>

Closes the utility’s main rollout in the Utilities panel. This is equivalent to clicking the Close button in this rollout.

addRollout <rollout> [ rolledUp:<boolean> ]

Adds the rollout to the Utilities panel. 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 extra rollouts are arranged in the order of addRollout() calls, so take care in sequencing these to ensure the order you want.

removeRollout <rollout>

Removes the rollout from the Utilities panel.

See Managing Multiple Rollouts in a Scripted Utility for more information on the addRollout() and removeRollout() methods.

updateRolloutLayout (<rollout_floater> | <rollout>) forceUpdate:<boolean>

Updates the layout of rollouts in the specified rollout floater or rollout in a dialog, unless both the rolloutfloater and rollout have their autoLayoutOnResize properties set to false, and the forceUpdate parameter to the method is false or not specified (the default is false). Available in 3ds Max 2019 and higher. If forceUpdate is true, the layout is updated regardless of autoLayoutOnResize settings.

Event Handlers

In addition to the event handlers you specify for particular user-interface items in a rollout, you can define handler functions that are called when an entire rollout is first opened ( open ) or explicitly closed ( close ) by the user. These event handlers are useful for initialization code or for cleaning up when a rollout closes, and are necessary when managing multiple rollouts in one scripted utility. If a rollout floater window is resized or moved, an event handler ( resized or moved, respectively) is called on the first rollout in the rollout floater window. An additional event handler ( oktoclose ) is called to verify that it is OK to close a rollout.

The syntax is as follows:

on <rollout_or_utility> open do <expr>

Called when the rollout or utility is opened.

on <rollout_or_utility> close do <expr>

Called when the rollout or utility is closed.

on <rollout_or_utility> oktoclose do <expr>

Called when the user clicks the rollout’s Close button so the script writer can decide whether to allow the close to proceed. If the expression evaluates to the value true , the rollout is allowed to close. If the expression evaluates to the value false , the action attempting the close is ignored and the rollout or utility is left open.

In the following example the utility will not close unless the "OK To Close" check button is pressed:

FOR EXAMPLE

   utility ui_oktoclose "OKToClose Test"
   (
   checkbutton a2 "OK To Close"
   on ui_oktoclose oktoclose do a2.state
   )

on <rollout_or_utility> help do <expr>

Called when dialog/rollout floater/rollout has focus and F1 is pressed.

If a rollout or a rollout control in a rollout has focus, the code looks to see if a 'help' event handler is defined for that rollout.

If not, if the rollout is in a rollout floater, the floater will get the message and will check for the 'help' event handler on the first rollout in the floater, and if present will call it.

If the rollout is in a subrollout, MAXScript explicitly performs the same check and calls the handler on the first rollout in the subrollout.

If no 'help' event handler is found, the message ends up in the 3ds Max window and the 3ds Max help will be called.

on <rollout_or_utility> rolledUp <arg> do <expr>

Called when the rollout or utility is rolled up or down. The argument will contain true when the rollout is rolled down (open) and false when the rollout is rolled up (closed).

FOR EXAMPLE

   rollout test "Test"
   (
   button btn_test "Press Me"
   on test rolledUp state do
   if state then print "Rolled Down!" else print "Rolled Up!"
   )
   nf = newRolloutFloater "Test" 200 200
   addRollout test nf

on <rollout> resized <arg> do <expr>

Called on first rollout in a rollout floater window when it is resized either by the user or by a script changing the size property of the rollout floater window. Changing the rollout floater window size in the resized event handler expression will not cause the resized event handler to be called again. The value of < arg > is the current width and height of the rollout floater window.

FOR EXAMPLE

   global my_rof_size
   ...
   on my_rollout resized size do
   (
   my_rof_size = size -- save the new window size
   )

on <rollout> moved <arg> do <expr>

Called on first rollout in a rollout floater window when it is moved either by the user or by a script changing the pos property of the rollout floater window. The value of < arg > is the current position of the rollout floater window on the screen in pixels.

The following example keeps a log file of its actions, and uses the rollout open and close handlers to open and close the log file:

FOR EXAMPLE

   utility frab "Optimal Frabulator"
   (
   local log
   spinner frab_x ...
   button do_it "Enfrabulate now"
   ...
   on do_it pressed do
   (
   frabulate selection
   format "selection frabbed at %\n" localTime to:log
   )
   on frab open do log = createFile "frabulator.log"
   on frab close do close log
   )

In the following example, the on resized event handler is called when the rollout floater window is resized. Because the event is generated only for the first rollout in a rollout floater window, the on b resized event handler is never called.

FOR EXAMPLE

   rollout a "Rollout A"
   (
   button a1 "a1"
   on a resized val do (format "A: %\n" val)
   )
   --
   rollout b "Rollout B"
   (
   button b1 "b1"
   on b resized val do (format "B: %\n" val)
   )
   --
   rof=newrolloutfloater "test" 200 200
   addrollout a rof
   addrollout b rof
   rof.size=[300,300]