Spinner UI Control

Creating User Interfaces - Quick Navigation

A spinner control is used to place a 3ds Max value spinner in a 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>] [toolTip:<string>] [indeterminate:<boolean>] [controller:(<controller>)] [setKeyBrackets:<boolean>] 	 

The default alignment of spinner items is #right .

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.

tooltip: 

Specifies the tooltip text to be displayed when the mouse hovers over the spinner.

Available in 3ds Max 2010 and higher.

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.

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 .

<spinner>.tooltip String 

Get/set the tooltip text to be displayed when the mouse hovers over the spinner.

Available in 3ds Max 2010 and higher.

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.

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.

spinner foo "height: "
on foo buttonDown do flagForeground $baz...* true
on foo buttonUp do flagForeground $baz...* false

 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.