Utility and Rollout Properties, Methods, and Event Handlers

Properties

Several properties are available for scripted utilities and rollouts which 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.

Note:

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.

Note:

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

 

<rollout>.scrollPos Integer

Scroll position of panel the rollout is in.

Note:

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

Get/Set the Height of the rollout in pixels.

Note:

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

Get / Set the Width of the rollout.

Notes:

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 via createDialog <rollout>. Always valid.

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

This property gets/sets whether the dialog is minimized, maximized, or normal. This property will return 'undefined' if the rollout is a not in a dialog, or the dialog is a dialogBar or is in a viewport.

This property is valid if the rollout is in a dialog and is not a dialogBar or in a viewport. When setting this property, values that the dialogs's creation style settings don't support are ignored. For example, if you set the property value to #maximized and #style_maximizebox was not specified in createDialog's style argument, no action occurs.

Note:

This property is available in 3ds Max 6 and higher.

 

<rollout>.isDisplayed Boolean, read-only

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

<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 via getVar owner.owner.

Rollout floater Properties:

<rollout_floater>.title String

Title of the floater.

Note:

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

 

<rollout_floater>.open Boolean, read-only

True if floater is open.

<rollout_floater>.size Point2

Size in pixels.

Note:

If a rollout floater is in an extended viewport, the size and position properties report the size and position of the viewport. The properties cannot be set for this case.

 

<rollout_floater>.pos Point2

Position in pixels.

Note:

If a rollout floater is in an extended viewport, the size and position properties report the size and position of the viewport. The properties cannot be set for this case.

 

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

Returns an array of all rollouts in the floater.

<rollout_floater>.inViewport Boolean, read-only

True if floater is in extended viewport.

<rollout_floater>.dialogBar Boolean, read-only

True if floater is registered as a dialog bar.

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

This property gets/sets whether the dialog is minimized, maximized, or normal. This property will return 'undefined' if the rollout is a not in a dialog, or the dialog is a dialogBar or is in a viewport.

This property is valid for Rolloutfloaters that are not a dialogBar nor in a viewport.

Note:

This property is available in 3ds Max 6 and higher.

 

Notes:

A rollout in a subrollout cannot be registered as a dialogbar or a view window. A rollout or rollout floater cannot be registered as both a dialogbar and a view window.

You can implement a form of rollout state save and restore for your scripted rollouts by recording the open state of all rollouts and the scrollPos of the entire panel during close handler processing, and then reset the values in the open handler.

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

 

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

new.gif 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:

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 utility will not close unless the "OK To Close" check button is pressed:

Example:

utility ui_oktoclose "OKToClose Test"

(

checkbutton a2 "OK To Close"

on ui_oktoclose oktoclose do a2.state

)

In the following example the on a 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.

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]

See also

CreateDialog

Rollout Floater Windows