Rollout Floater Windows

MAXScript lets you create modeless floating dialog windows known as Rollout Floaters and populate them with rollouts defined using rollout definitions.

The user can resize a rollout floater window vertically by dragging on the lower window edge.

There are two functions and a special class in support of this, as follows:

newRolloutFloater <title_string> <width_integer> <height_integer> [<top_integer> <left_integer>] \
     [lockHeight:<boolean>] [lockWidth:<boolean>] [autoLayoutOnResize:<boolean>] scrollBar:<on|off|#on|#off|#asNeeded>

Creates and opens a new rollout floater window with the title and width and height given. If you don't supply top and left coordinates, the window will open centered in the screen. The width of the 3ds Max command panel is 218, in case you want to duplicate its width for precisely accommodating Utilities panel rollouts. This method returns a RolloutFloater value to which you add rollouts.

The lockHeight and lockWidth arguments specify whether to lock the height and width of the rollout floater (that is, whether to disable resizing). Available in 3ds Max 2019 and higher. The defaults are lockHeight:false and lockWidth:true.

The autoLayoutOnResize argument specifies whether to automatically re-layout the contained rollout when the rollout floater is resized. Available in 3ds Max 2019 and higher. The default is true.

The scrollBar argument specifies whether to add a scrollbar to the floater to scroll the contained rollout. Available in 3ds Max 2019 and higher. The default is #asNeeded, where a scrollbar will only be displayed when the rollout floater is smaller than the contained rollout.

closeRolloutFloater <rolloutFloater>

Closes the rollout floater window. The user can also do this by clicking the close box on the window. Once closed, the window is no longer usable. All the close handlers in the rollout floater window's rollouts are called and they are released for use in other rollout floater windows or scripted utilities.

The existing functions for adding and removing rollouts to the Utilities panel are extended to work with rollout floater windows:

addRollout <rollout> [ <rolloutFloater> ] [rolledUp:<boolean> ] [border:<boolean>]

If the optional second argument is specified, it must be a RolloutFloater value as returned from the newRolloutFloater() function. The rollout specified by the first argument is appended after any rollouts previously in the window.

If the optional rolledUp: keyword argument is specified, the rollout will be initially rolled up (closed) when the argument is True or rolled down (open) when False.

If the optional border: keyword argument is specified and set to False in 3ds Max 2009 and higher, the rollout will have no border. If the keyword argument is not supplied or set to True, a border will be drawn around the rollout.

removeRollout <rollout> [ <rolloutFloater> ]

Removes the rollout from the given rollout floater window.

In both functions above, if the optional <rolloutFloater> is not supplied the rollout is added to, or removed from, the Utilities panel, as described in Managing Multiple Rollouts in a Scripted Utility.

Rollout floater properties:

<rolloutFloater>.title String

The Title of the floater.

Note:

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

<rolloutFloater>.size Point2

The current size of the rollout floater window in pixels. The first component of the Point2 is the width, the second the height. This property is read/write.

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.

<rolloutFloater>.pos Point2

The current screen position of the rollout floater window in pixels. This property is read/write.

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.

When a rollout floater window is resized, either by the user or by a script changing the size property, a resized event is generated for the first rollout in the rollout floater window. Likewise, when a rollout floater window is moved, either by the user or by a script changing the pos property, a moved event is generated for the first rollout in the rollout floater window. The event handler for the resized and moved events are described in Utility and Rollout properties, Methods, and Event Handlers.

<rolloutFloater>.inViewport Boolean, read-only.

Returns True if the floater is in extended viewport.

<rolloutFloater>.open Boolean, read-only.

Returns True if the floater is open.

<rolloutFloater>.visible Boolean

Get/Set the visibility of the Rollout Floater. Available in 3ds Max 2014 and higher.

When set to True (default), the Rollout Floater will be displayed.

When set to False, the Rollout Floater will not be drawn, but it and its rollouts will still be accessible through MAXScript.

Note: This can be used as an alternative to placing the Rollout Floater off-screen, a hack sometimes used in older versions of 3ds Max. Since 3ds Max 2014, any off-screen dialogs will be automatically moved back into view.

<rolloutFloater>.dialogBar Boolean, read-only.

Returns True if the rollout floater is used as a dialog bar.

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

Returns an array of all rollouts in the floater.

<rolloutFloater>.placementName, 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 not in a dialog, 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.

Note:

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.

<rolloutFloater>.lockHeight Boolean

True if floater height cannot be changed by dragging its borders. Available in 3ds Max 2019 and higher.

<rolloutFloater>.lockWidth Boolean

True if floater width cannot be changed by dragging its borders. Available in 3ds Max 2019 and higher.

<rolloutFloater>.autoLayoutOnResize Boolean

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

<rolloutFloater>.hwnd IntegerPtr, read-only

Contains the window pointer for the floater as an integer pointer, if the floater is open, or undefined if the floater is closed.

Available in 3ds Max 2020 and higher.

FOR EXAMPLE:

   rollout grin "Grin Control"
   (
   slider happy "Happy" orient:#vertical across:5
   slider sad "Sad" orient:#vertical
   slider oo "OO" orient:#vertical
   slider ee "EE" orient:#vertical
   slider oh "OH" orient:#vertical
   /*
   on happy changed val do object.xform1.center = ...
   on sad changed val do object.xform2.gizmo.rotation = ...
   ...
   */
   )
   theNewFloater = newRolloutFloater "Grinning" 300 220
   addRollout grin theNewFloater