org.w3c.dom.smil
Interface ElementTimeControl

All Known Subinterfaces:

SVGAnimateColorElement, SVGAnimateElement, SVGAnimateMotionElement, SVGAnimateTransformElement, SVGAnimationElement, SVGSetElement

public interface ElementTimeControl

SMILAnimation supports several methods for controlling the behavior of animation: beginElement() and endElement(), et al. These methods are used to begin and end an animation that has declared the timing to respond to the DOM, using the following syntax:

<animate begin="indefinite" end="indefinite" .../>

Note that only one of begin or end need be specified - either or both can be used. The beginElement() and beginElementAt() methods must do nothing if the animation is not explicitly set with the begin="indefinite" syntax above. The endElement() and endElementAt() methods must do nothing if the animation is not explicitly set with the end="indefinite" syntax above.

Calling beginElement() causes the animation to begin in much the same way that an animation with event-based begin timing begins. The effective begin time is the current presentation time at the time of the DOM method call. Note that beginElement() is subject to the restart attribute in the same manner that event-based begin timing is. If an animation is specified to disallow restarting at a given point, beginElement() methods calls must fail. Refer also to the section Restarting animations.

Calling beginElementAt() has the same effect as beginElement(), except that the effective begin time is offset from the current presentation time by an amount specified as a parameter. Passing a negative value for the offset causes the element to begin as for beginElement(), but has the effect that the element begins at the specified offset into its active duration. The beginElementAt() method must also respect the restart attribute. The restart semantics for a beginElementAt() method call are evaluated at the time of the method call, and not at the effective begin time specified by the offset parameter.

Calling endElement() causes an animation to end the active duration, just as end does. Depending upon the value of the fill attribute, the animation effect may no longer be applied, or it may be frozen at the current effect. Refer also to the section Freezing animations. If an animation is not currently active (i.e. if it has not yet begun or if it is frozen), the endElement() method will fail.

Calling endElementAt() causes an animation to end the active duration, just as endElement() does, but allows the caller to specify a positive offset, to cause the element to end at a point in the future. Other than delaying when the end actually happens, the semantics are identical to those for endElement(). If endElementAt() is called more than once while an element is active, the end time specified by the last method call will determine the end behavior.

The expectation of the following interface is that an instance of the ElementTimeControl interface can be obtained by using binding-specific casting methods on an instance of an animate element. A DOM application can use the hasFeature method of the DOMImplementation interface to determine whether the ElementTimeControl interface is supported or not. The feature string for this interface is "TimeControl".

See Also:

SMIL Animation.

Method Summary

boolean	beginElement() Causes this element to begin the local timeline (subject to restart constraints).
boolean	beginElementAt(float offset) Causes this element to begin the local timeline (subject to restart constraints), at the passed offset from the current time when the method is called.
boolean	endElement() Causes this element to end the local timeline.
boolean	endElementAt(float offset) Causes this element to end the local timeline at the specified offset from the current time when the method is called

Method Detail

beginElement

boolean beginElement()
                     throws DOMException

Causes this element to begin the local timeline (subject to restart constraints).

Returns:

true if the method call was successful and the element was begun. false if the method call failed. Possible reasons for failure include:

• The element does not support the beginElement method. The begin attribute is not set to "indefinite".
• The element is already active and cannot be restarted when it is active. The restart attribute is set to "whenNotActive".
• The element is active or has been active and cannot be restarted. The restart attribute is set to "never".

Throws:

DOMException

beginElementAt

boolean beginElementAt(float offset)
                       throws DOMException

Causes this element to begin the local timeline (subject to restart constraints), at the passed offset from the current time when the method is called. If the offset is >= 0, the semantics are equivalent to an event-base begin with the specified offset. If the offset is < 0, the semantics are equivalent to beginElement(), but the element active duration is evaluated as though the element had begun at the passed (negative) offset from the current time when the method is called.

Parameters:

offset - The offset in seconds at which to begin the element.

Returns:

true if the method call was successful and the element was begun. false if the method call failed. Possible reasons for failure include:

• The element does not support the beginElementAt method. The begin attribute is not set to "indefinite".
• The element is already active and cannot be restarted when it is active. The restart attribute is set to "whenNotActive".
• The element is active or has been active and cannot be restarted. The restart attribute is set to "never".

Throws:

DOMException

endElement

boolean endElement()
                   throws DOMException

Causes this element to end the local timeline.

Returns:

true if the method call was successful and the element was ended. false if method call failed. Possible reasons for failure include:

• The element does not support the endElement method. The end attribute is not set to "indefinite".
• The element is not active.

Throws:

DOMException

endElementAt

boolean endElementAt(float offset)
                     throws DOMException

Causes this element to end the local timeline at the specified offset from the current time when the method is called

Parameters:

offset - The offset in seconds at which to end the element. Must be >= 0.

Returns:

true if the method call was successful and the element was ended. false if method call failed. Possible reasons for failure include:

• The element does not support the endElementAt method. The end attribute is not set to "indefinite".
• The element is not active.

Throws:

DOMException