Utility and Rollout Properties, Methods, and Event Handlers

Creating User Interfaces - Quick Navigation

Properties

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

<rollout>.name String, read-only

<rollout>.title String

<rollout>.open Boolean

<rollout>.scrollPos Integer

<rollout>.height Integer

<rollout>.width Integer

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

<rollout>.inViewport Boolean, read-only

<rollout>.dialogBar Boolean, read-only

<rollout>.inDialog Boolean, read-only

<rollout_floater>.placement Name, enums:{#minimized|#maximized|#normal}

<rollout>.isDisplayed Boolean, read-only

<rollout>.owner Object, read-only

<rollout>.hwnd Integer, read-only

<rollout_floater>.title String

<rollout_floater>.open Boolean, read-only

<rollout_floater>.size Point2

<rollout_floater>.pos Point2

<rollout_floater>.rollouts Array of rollouts in floater, read-only

<rollout_floater>.inViewport Boolean, read-only

<rollout_floater>.dialogBar Boolean, read-only

<rollout_floater>.placementName, enums:{#minimized|#maximized|#normal}

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.

<Point2>GetDialogSize <rollout>

Returns the size of the window's client area. Equivalent to

point2 <rollout>.width <rollout>.height

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.

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:

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

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.

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:

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.

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]

 Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. Please see the Autodesk Creative Commons FAQ for more information.