Change Handlers

Change handlers are scripts that will be called on the occurrence of some event, such as when the Time Slider is scrolled, when a viewport is redrawn, when a property is changed, or when some predefined action happens, such as File Open or Render.

General Callbacks

General callbacks are called when certain MAX events happen, such as Render, File Open, File Reset, etc. The script callback events can usually be called before and after the command events. Table 17.1 provides a list of the most commonly used events.

Usually callbacks call functions. To add callbacks, you use CALLBACKS.ADDSCRIPT. You must specify callbacks.addscript <event> <string> <id>, where <event> is the event at which you want the callback to execute; <string> is the script itself in a string format; and id> is the callback identification, which is its name.

You will now write a script that will tell us how many objects are selected. In the Listener, type:

callbacks.addscript #selectionsetchanged \
 “format \”There are % objects selected.\\n\“ selection.count” id:#test

This will create a callback; whenever you click in the screen, it will list how many objects are selected.

To remove a callback, use CALLBACKS.REMOVESCRIPT. You then specify the ID or the event you want to remove. You can use CALLBACKS.SHOW() to list all callbacks.

Hands-on MAXScript: Creating a Timer

Let’s create a script that will count the time you take working in each scene. It will use a persistent global variable that will store the number of seconds you worked. This variable will be incremented using a #filepresave callback.

Locate the file timer_functions.ms on the CD that accompanies this book. Run it and copy it to your Startup\Scripts folder. This file defines two functions that will store the time and calculate the elapsed time between two intervals. It’s very similar to the one you created in Chapter 13.

Now you will create another script file that includes the callbacks. Either open the file timer_callbacks.ms from the CD that accompanies this book, or start a new script and type everything shown in Listing 17.1.

fn calculate_time_working =
 (
 end_max_working = right_now()
 session_time = elapsed_time start_max_working end_max_working
 time_working += session_time
 start_max_working = right_now()
 )
fn reset_time_working =
 (
 global start_max_working
 start_max_working = right_now()
 persistent global time_working = 0
 callbacks.removescripts id:#start_max_working
 callbacks.removescripts id:#end_max_working
 callbacks.addscript #systempostnew “reset_time_working()” \
 id:#start_max_working
 callbacks.addscript #systempostreset “reset_time_working()” \
 id:#start_max_working
 callbacks.addscript #systemprenew “calculate_time_working()” \
 id:#end_max_working
 callbacks.addscript #filepreopen “calculate_time_working()” \
 id:#end_max_working
 callbacks.addscript #systemprereset “calculate_time_working()” \
 id:#end_max_working
 callbacks.addscript #filepresave “calculate_time_working()” \
 id:#end_max_working
 )
reset_time_working()

(Remember, the backslash at the end of a line means that the line is continued.) OK, first, you defined two functions. One resets the system and restarts all variables; the other calculates the elapsed time and adds it to the persistent variable.

The first function (calculate_time_working) simply calculates the elapsed time since the last time it was called and adds this value to the persistent variable time_working. Since this variable is persistent, it will be stored and saved with the program, and it can be restored the next time this file is opened.

The second function (reset_time_working) creates the persistent global variable and resets it to zero. Then, it removes all previous callbacks and defines them again. Notice that when we create a new MAX file, some callbacks (#systempostnew and #systempostreset) will reset the timer and restart themselves. Before saving the file, other callbacks (#systemprenew, #filepreopen, #systemprereset, and #filepresave) will call the calculate_time_working function, which will update the timer.

Also, place this script in the Startup folder, so it will be automatically loaded. You can make a script to display the time_working variable value, and even display it in hours, minutes, seconds format, or have it placed in the Scene Properties.

	WARNING You cannot use persistent and id at the same time in a callback. If you do so, the callback will not be saved. If you need a callback to be saved, use persistent; don’t assign it an ID.

When

WHEN is a change handler that also responds to an event, but this event is a scene node event. You can define actions to happen when objects are deleted, when objects are modified, when parameters are changed, etc.

For example, create a sphere and name it “Ball.” In the Listener, enter the following line, which will create a handler that will warn you if this object is deleted:

when $Ball deleted do messagebox “Object Ball has been deleted.”

Now, delete the object and see the message displayed.

The WHEN handler is capable of much more. You can define very complex handlers that can be driven by almost any parameter in MAX. However, WHEN handlers are not persistent and will be discarded when the file is closed.

Working with MAX Files

MAXScript allows you to work with MAX files and all other supported file types. You can open, save, merge, import, export, and Xref files within MAXScript.

These operations are useful for automating tasks, such as rendering queues and batch file conversions; they save tremendous amounts of time.

Opening and Saving

You can open MAX files using LOADMAXFILE. All you need to specify is the filename and path. If no path is specified, MAXScript will use the default Scenes Path in MAX.

	NOTE It is necessary to specify the extension when using LOADMAXFILE. Also remember to use \\ instead of a single backslash.

© 2000, Frol (selection, edition, publication)