Scripted Utility Panels

A scripted utility panel is created using the utility definition construct in MAXScript.

The top-level syntax is as follows:

utility <var_name> <description_string> [rolledUp:<boolean> ] [silentErrors:<boolean> ]
( 
<utility_body> 
) 

The <var_name> is the name of an automatically created global variable to hold the value that represents the scripted utility panel.

The <description_string> is a string which is used as the description for the utility in the Utilities list in the MAXScript rollout.

The optional rolledUp: parameter specifies whether the utility rollout is initially rolled up. If set to true , the utility rollout is initially rolled up. The default value is false .

The optional silentErrors: parameter controls whether MAXScript runtime error messages are displayed while executing the scripted utility. If this parameter is set to false , error messages are displayed to Listener and possibly to a pop-up error dialog, and continued execution of the utility is terminated. If this parameter is set to true , error messages will not be displayed, and continued execution of the utility is permitted. Setting this parameter to true is useful for distributed scripted plug-ins that may confuse the user with MAXScript error messages. The default value is false .

The <utility_body> is inside the required parentheses and is a sequence of clauses that defines the user-interface items that will appear in the utility, along with functions and event handlers that process user interactions, as defined in detail in Utility Clauses.

Here is a short example that implements a utility for spreading the positions of the objects in the current selection. It installs a Spread objects entry in the Utilities list. When opened, the Spread objects rollout has three check boxes and one spread amount spinner. The spread spinner event handler is called whenever the user adjusts the spinner, and the event handler expression computes a new position for the objects in the selection, testing the state of each check box to control the spread.

EXAMPLE

   utility spread "Spread objects" -- define the utility name and description string
   (
   local last_amt = 0 -- define and initialize local variable
   checkbox x "Spread in x" -- create 3 checkboxes
   checkbox y "Spread in y"
   checkbox z "Spread in z"
   spinner spread "Spread amount:" range:[-1000,1000,0] -- create a spinner
   on spread changed amt do -- when spinner value changes...
   (
   delta = amt - last_amt -- calculate difference in current and previous
   for obj in selection do -- values for each selected object
   (
   -- calculate new position based on current position and selection center
   p = obj.pos + normalize (obj.pos - selection.center) * delta
   if x.checked then obj.pos.x = p.x -- if checkbox x checked, apply X position
   if y.checked then obj.pos.y = p.y -- if checkbox y checked, apply Y position
   if z.checked then obj.pos.z = p.z -- if checkbox z checked, apply Z position
   )
   last_amt = amt -- store spinner value as previous value
   ) -- end of "on spread changed"
   ) -- end of utility definition

The Utilities panel rollout created by the previous script looks like the following figure. The Close button is automatically created by MAXScript in the utility rollout, and closes the rollout.

Spread objects rollout

Evaluating a utility definition does several things. It creates a new value which is an instance of the Rollout class and contains the utility definition. It assigns this value to the named global variable and installs the utility description in the Utilities list in the MAXScript rollout. At this point, the user can select the utility from the Utilities list and the utility’s rollout(s) will open.

If a scripted utility already exists with the same description, the old rollout(s) is replaced with the new one(s), even if it is currently open in the Utilities panel. This allows you to incrementally develop a utility. Each time you modify and evaluate its definition, the old version is replaced with the new one.