Progress Bar Display

This group of functions let you display a progress bar for operations that may be time consuming, similar to the progress bar 3ds Max uses for IK, Preview Rendering and Reduce Key computations.

The functions are:

progressStart "caption"

Initially displays the progress bar with the caption given.

progressUpdate <percent>

Updates the bar display to show the given percentage complete (in the range 0-100). This function also checks to see if the user has clicked the Cancel button in the progress bar and returns true if the computation should continue and false if the user has requested a cancel. You can also call getProgressCancel() , described below, to check the cancel status, which is a low overhead function and so may be called more frequently than progressUpdate() .

progressEnd()

Signals the end of the operation and removes the progress bar display.

getProgressCancel()

A low-overhead function that checks whether the user has canceled the operation via the Cancel button in the progress bar. You may want to call this function frequently within deep loops in your code to reduce cancel latency for the user, because you should only call progressUpdate() as needed to show significant progress bar changes to keep overhead low. The getProgressCancel() function, as well as progressUpdate() , displays a confirmation dialog if the use hits the cancel button and returns the cancel status from that confirmation. Unlike progressUpdate() , this function returns true if the user has made a confirmed cancel request and false otherwise.

setProgressCancel <boolean>

Sets or clears the Cancel flag for the progress bar. By passing a value of true , the Cancel flag is set and will be detected by progressUpdate() and getProgressCancel() . By passing a value of false , the Cancel flag is cleared if set.

The following 3ds Max system global variable is associated with the Progress Bar display:

escapeEnable

Lets you get and set a Boolean value defining whether ESC key interrupt detection is on or off. Setting enableEscape to false turns ESC key interrupt detection off, setting it to true turns it on again. This variable is useful when used in conjunction with a Progress Bar. You can set enableEscape to false when you don't want the user to be able to interrupt a script running a long computation and you have set up a progress bar with its own Cancel button.

NOTES ON CALCULATING PERCENTAGES:

When calculating the percentage from a current Integer value and a total Integer value, the order the values are multiplied and divided does matter. Dividing them first and then multiplying by 100.0 would always return 0.0 because an Integer divided by an Integer yields an Integer, and since the result is less than zero, it is rounded down to zero. If the total value is 20, for each value between 1 and 19, you would get

1/20*100.0 -> 0*100.0 -> 0.0
2/20*100.0 -> 0*100.0 -> 0.0
3/20*100.0 -> 0*100.0 -> 0.0
...
19/20*100.0-> 0*100.0 -> 0.0
20/20*100.0-> 1*100.0 -> 100.0

but

100.0*1/20 -> 100.0/20 -> 5.0
100.0*2/20 -> 200.0/20 -> 10.0
100.0*3/20 -> 300.0/20 -> 15.0
...
100.0*19/20-> 1900.0/20-> 95.0
100.0*20/20-> 2000.0/20-> 100.0

When starting with the Float value 100.0, the final result is implicitly converted to a Float because a Float multiplied by an Integer returns a Float, and a Float divided by an Integer still returns a Float.

Progress Bar Display

See Also