org.w3c.dom.smil.ElementTimeControl Maven / Gradle / Ivy

/*
 * Copyright (c) 2001 World Wide Web Consortium,
 * (Massachusetts Institute of Technology, Institut National de
 * Recherche en Informatique et en Automatique, Keio University). All
 * Rights Reserved. This program is distributed under the W3C's Software
 * Intellectual Property License. This program is distributed in the
 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 * PURPOSE.
 * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
 *
 */
package org.w3c.dom.smil;

import org.w3c.dom.DOMException;

/**
 * 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 SMIL Animation.
 */
public interface ElementTimeControl {
    /**
     * Causes this element to begin the local timeline (subject to restart constraints).
     * @return 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".
     * 
     * @raise DOMException SYNTAX_ERR: The element was not defined
     * with the appropriate syntax to allow beginElement calls.
     */
    public boolean beginElement()
	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.
     *
     * @param offset The offset in seconds at which to begin the element.
     * @return 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".
     *      
     * @raise DOMException SYNTAX_ERR: The element was not defined with the appropriate
     * syntax to allow beginElementAt calls.
     */
    public boolean beginElementAt(float offset)
	throws DOMException;
    
    /**
     * Causes this element to end the local timeline.
     *
     * @return 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.
     * 
     * @raise DOMException SYNTAX_ERR: The element was not defined with the
     *                     appropriate syntax to allow endElement
     *                     calls.
     */    
    public boolean endElement()
	throws DOMException;
    
    /**
     * Causes this element to end the local timeline at the specified offset
     * from the current time when the method is called
     *
     * @param offset The offset in seconds at which to end the element.
     *               Must be >= 0.
     * @return 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.
     * 
     * @raise DOMException SYNTAX_ERR: The element was not defined with the
     * appropriate syntax to allow
     * endElementAt calls.
     */
    public boolean endElementAt(float offset)
	throws DOMException;
    
}