Spinner

A spinner item is used to place a 3ds Max value spinner on the rollout. The user can drag the spinner arrows or type values into the spinner edit field.

The syntax is:

spinner <name> [ <caption> ] [ range:[min,max,val] ] [type:<name>] [scale:<float>] [ fieldWidth:<integer>] [indeterminate:<boolean>] [controller:(<controller>)]

The default alignment of spinner items is #right.

Example:

spinner frab_amt "Frab %:" range:[0,100,10] type:#integer

spinner ball_radius "Ball radius" controller:($ball.radius.controller)

on frab_amt changed val do frabulate selection val

Parameters

range:

A Point3 value containing the minimum, maximum, and initial values for the spinner in the x, y, and z components, respectively. Defaults to [0,100,0].

type:

The type of the spinner: #float, #integer, or #worldunits. Defaults to #float. If type is #worldunits, the value is displayed in the current 3ds Max display units, but the value is always in internal system units.

scale:

The scale of the spinner specifies the smallest value increment. Defaults to 0.1 for floats, 1 for integers.

fieldwidth:

The width in pixels of the spinner text-edit field. By default, the spinner is placed so the left edge of the edit field is exactly in the center of the rollout and right edge is placed at the right margin. You can control how wide the field is using this parameter.

Indeterminate:

When set to true, the spinner edit field is blank.

controller:

Links the spinner to the specified controller. This can be a new controller or 'undefined' to disconnect. This lets you establish a direct link between the spinner and the controller. Changes to the spinner will automatically update the controller (and its controlled objects). Changes to the controller automatically update the spinner. For example, say you have a sphere called $ball with a float controller already assigned to its radius, then the following code:

utility foo "foo"

(

spinner ball_radius "Ball radius" range:[0,1000,1] \

controller:($ball.radius.controller)

)

sets up a spinner that automatically affects and tracks the radius of the scene node $ball. Any changes to the spinner update $ball's radius. Any other changes to $ball's radius, say in the Modify panel or because of animation, will update the spinner. Note that this links to controllers, so the specified controller must already exist before creating the spinner user-interface item. You can either specify a controller already assigned to the parameter you want to link to, or you can create the controller in your script and then assign that controller to the parameter of interest.

setKeyBrackets:

When set to true (on) or false (off), it will turn on and off the red keyframe brackets that signal a keyframe is present for animated parameters. This allows you to simulate keyframe notification in scripted rollouts by setting this spinner property on or off, most likely in a time change callback function.

For example:

utility foo "foo"

(

local myController=bezier_float()

spinner ball_radius "Ball radius" range:[0,1000,1] \

controller:myController

button apply "Apply Radius Controller"

on apply pressed do

(

animate off at time 0 $ball.radius=myController.value

$ball.radius.controller=myController

)

)

Properties

<spinner>.range Point3

The current range and value for the spinner, as a Point3 like the range: parameter.

<spinner>.value Float

The current value of the spinner.

<spinner>.setKeyBrackets Boolean

When set to true (on) or false (off), it will turn on and off the red keyframe brackets that signal a keyframe is present for animated parameters. This allows you to simulate keyframe notification in scripted rollouts by setting this spinner property on or off, most likely in a time change callback function.

<spinner>.indeterminate Boolean

When set to true, the spinner edit field is blank. The value of the spinner is unchanged and remains accessible when a spinner is set to indeterminate. Setting the spinner's value sets indeterminate to false.

Events

on <spinner> changed <arg> [<inSpin_arg>] do <expr>

Called when the user spins the spinner, or when the user enters a value in the spinner field then presses ENTER or presses TAB to move the cursor out of the field. The <arg> argument will contain the new value of the spinner.

The optional <inSpin_arg> argument will contain true if the value was changed by spinning using the mouse and the arrows and false if the value was entered using the keyboard and the value field. Available in 3ds Max 8 and higher.

 

on <spinner> entered [<inSpin_arg>] [<inCancel_arg>] do <expr>

Called when the user types a number into a spinners edit field and then presses ENTER or presses TAB to move the cursor out of the field. Also called when the spinner is released. The on <spinner> changed and <spinner> buttonUp handlers, if supplied, have already been called at this point and the spinner's value property is up to date.

The optional first <inSpin_arg> argument will contain true if the value was entered by spinning the arrows and releasing the mouse and false if the value was entered using the keyboard and the value field. Available in 3ds Max 8 and higher.

The optional second <inCancel_arg> argument will contain true if the value change was canceled with a mouse right-click and false if no cancel was performed. Available in 3ds Max 8 and higher.

 

on <spinner> buttondown do <expr>

Called when the user first clicks the spinner.

 

on <spinner> buttonup [<inCancel_arg>] do <expr>

Called when the user releases the spinner.

The optional <inCancel_arg> argument will contain true if the value change was canceled with a mouse right-click and false if no cancel was performed. Available in 3ds Max 8 and higher.

 

Notes:

The buttonDown and buttonUp events effectively notify you of the start and end of a spinner "twiddle", allowing you to perform some setup for the adjustment. A typical use for this is to bring scene nodes that are being modified in the on <spinner> changed handler into the foreground plane to speed up screen redraw.

If you are using a spinner to interactive adjust a property of an on-screen object, you can improve the interactive speed by moving the object to the foreground plane. Objects placed in the foreground plane are redrawn individually and so interactive changes to them are much faster. An object is moved to the foreground or background plane using the flagForeground() method:

flagForeground <node> <boolean> -- mapped

The boolean argument puts the scene node(s) into the foreground plane if true, or into the background plane if false.

You should be judicious in putting objects in the foreground plane, because putting too many objects in the foreground plane reduces the foreground plane's effectiveness. Remember to return objects to the background plane when you don't need to interactively control them any more.

For example:

spinner foo "height: "

on foo buttonDown do flagForeground $baz...* true

on foo buttonUp do flagForeground $baz...* false

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types