1/*
2 * Copyright (c) 2000 World Wide Web Consortium,
3 * (Massachusetts Institute of Technology, Institut National de
4 * Recherche en Informatique et en Automatique, Keio University). All
5 * Rights Reserved. This program is distributed under the W3C's Software
6 * Intellectual Property License. This program is distributed in the
7 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
8 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
9 * PURPOSE. See W3C License http://www.w3.org/Consortium/Legal/ for more
10 * details.
11 */
12
13package org.w3c.dom.smil;
14
15import org.w3c.dom.DOMException;
16
17/**
18 */
19public interface ElementTimeControl {
20    /**
21     *  Causes this element to begin the local timeline (subject to sync
22     * constraints).
23     * @return  <code>true</code> if the method call was successful and the
24     *   element was begun. <code>false</code> if the method call failed.
25     *   Possible reasons for failure include:  The element doesn't support
26     *   the <code>beginElement</code> method. (the <code>begin</code>
27     *   attribute is not set to <code>"indefinite"</code> )  The element is
28     *   already active and can't be restart when it is active. (the
29     *   <code>restart</code> attribute is set to <code>"whenNotActive"</code>
30     *    )  The element is active or has been active and can't be restart.
31     *   (the <code>restart</code> attribute is set to <code>"never"</code> ).
32     *
33     * @exception DOMException
34     *    SYNTAX_ERR: The element was not defined with the appropriate syntax
35     *   to allow <code>beginElement</code> calls.
36     */
37    public boolean beginElement()
38                                throws DOMException;
39
40    /**
41     *  Causes this element to begin the local timeline (subject to sync
42     * constraints), at the passed offset from the current time when the
43     * method is called. If the offset is &gt;= 0, the semantics are
44     * equivalent to an event-base begin with the specified offset. If the
45     * offset is &lt; 0, the semantics are equivalent to beginElement(), but
46     * the element active duration is evaluated as though the element had
47     * begun at the passed (negative) offset from the current time when the
48     * method is called.
49     * @param offset  The offset in seconds at which to begin the element.
50     * @return  <code>true</code> if the method call was successful and the
51     *   element was begun. <code>false</code> if the method call failed.
52     *   Possible reasons for failure include:  The element doesn't support
53     *   the <code>beginElementAt</code> method. (the <code>begin</code>
54     *   attribute is not set to <code>"indefinite"</code> )  The element is
55     *   already active and can't be restart when it is active. (the
56     *   <code>restart</code> attribute is set to <code>"whenNotActive"</code>
57     *    )  The element is active or has been active and can't be restart.
58     *   (the <code>restart</code> attribute is set to <code>"never"</code> ).
59     *
60     * @exception DOMException
61     *    SYNTAX_ERR: The element was not defined with the appropriate syntax
62     *   to allow <code>beginElementAt</code> calls.
63     */
64    public boolean beginElementAt(float offset)
65                                  throws DOMException;
66
67    /**
68     *  Causes this element to end the local timeline (subject to sync
69     * constraints).
70     * @return  <code>true</code> if the method call was successful and the
71     *   element was ended. <code>false</code> if method call failed.
72     *   Possible reasons for failure include:  The element doesn't support
73     *   the <code>endElement</code> method. (the <code>end</code> attribute
74     *   is not set to <code>"indefinite"</code> )  The element is not active.
75     *
76     * @exception DOMException
77     *    SYNTAX_ERR: The element was not defined with the appropriate syntax
78     *   to allow <code>endElement</code> calls.
79     */
80    public boolean endElement()
81                              throws DOMException;
82
83    /**
84     *  Causes this element to end the local timeline (subject to sync
85     * constraints) at the specified offset from the current time when the
86     * method is called.
87     * @param offset  The offset in seconds at which to end the element. Must
88     *   be &gt;= 0.
89     * @return  <code>true</code> if the method call was successful and the
90     *   element was ended. <code>false</code> if method call failed.
91     *   Possible reasons for failure include:  The element doesn't support
92     *   the <code>endElementAt</code> method. (the <code>end</code>
93     *   attribute is not set to <code>"indefinite"</code> )  The element is
94     *   not active.
95     * @exception DOMException
96     *    SYNTAX_ERR: The element was not defined with the appropriate syntax
97     *   to allow <code>endElementAt</code> calls.
98     */
99    public boolean endElementAt(float offset)
100                                throws DOMException;
101
102}
103
104