Controller Time Functions

Time Range Operations:

getTimeRange <controller> [ #selOnly ] [ #allKeys ] [ #children ]

Returns a time Interval value specifying the range of time covered by keys in the controller. The optional symbolic arguments specify options:

#selOnly: return the time range covered by the currently selected keys (in the track view)

#allKeys (default): the time range for all keys in the controller

#children: descends into sub-controllers and returns the total time interval covering all keys in all sub-controllers

setTimeRange <controller> [ <interval> ] [ #linkToKeys ]

Sets the time range to be an interval other than that covered by existing keys, typically to influence when the out-of-range methods take over. If the optional #linkToKeys argument is given any keys exactly at the start or end of the given interval become anchors for the time range and moving them move the time range for the controller.

If you call setTimeRange() with just the single argument, #linkToKeys, it will set the time range to the current start and end keys in all the controllers affected,

For example:

setTimeRange $box* #linkToKeys

This is equivalent to the Recouple Ranges function in the Position Ranges mode in Track View.

Note:

When the #linkToKeys argument is not supplied, only the supplied controller will be affected. When the #linkToKeys argument is supplied, the function will also affect recursively all sub-controllers.

Time Operations:

supportsTimeOperations <ctrl>

returns true or false depending on whether the controller supports the following time operations

deleteTime <controller> <interval> [ #incLeft ] [ #incRight ] [ #noSlide ]

Deletes an interval of time from the controller, removing all the keys with that interval and, by default, sliding the keys to the right of the interval to the left by the width of the interval. The optional symbolic arguments choose one of several options:

#incLeft: includes any key exactly at the start time of the interval

#incRight: includes any key exactly at the end time of the interval

#noSlide: doesn’t slide the later keys to fill in the gap removed- this effectively just deletes any keys in the interval.

The <interval> argument can be specified as an Interval value or as two numbers or time values defining the start and end times. Number values are taken as frame numbers.

reverseTime <controller> <interval> [ #incLeft ] [ #incRight ]

Reverses time in the given interval, essentially swapping keys around so that their time placements are reversed within the interval. The notes on inclusion and interval arguments from deleteTime() apply.

scaleTime <controller> <interval> <float_scale>

Scales the times of the keys within the given interval. Again, the <interval> argument can be specified as an Interval value or as two numbers or time values defining the start and end times. Number values are taken as frame counts.

insertTime <controller> <at_time> <amount_time>

Inserts a block of time at the specified time, effectively moving all later keys out in time by the amount inserted. The times can be numbers or Time values. Numbers are taken as frame counts.

The following script shows example usages of some of the above methods.

Example:

-- controller test bed 1

b=box height:10

at time 5 animate on b.height=50

at time 10 animate on b.height=100

bhc=b.height.controller

bhk=bhc.keys

supportstimeoperations bhc

deletetime bhc 4 5

bhk

deletetime bhc 4 5 #incLeft

bhk

deletetime bhc 1 4 #noslide

bhk

at time 5 animate on b.height=50

deletetime bhc (interval 5 8) #incLeft

bhk

at time 10 animate on b.height=150

for k in bhk do format "%:%\n" k.time k.value

reversetime bhc 5 15 #incLeft #incRight

for k in bhk do format "%:%\n" k.time k.value

insertTime bhc 12 5

bhk

getTimeRange bhc