View Javadoc

1   /**********************************************
2    * Copyright (C) 2010 Lukas Laag
3    * This file is part of lib-gwt-svg.
4    * 
5    * libgwtsvg is free software: you can redistribute it and/or modify
6    * it under the terms of the GNU Lesser General Public License as published by
7    * the Free Software Foundation, either version 3 of the License, or
8    * (at your option) any later version.
9    * 
10   * libgwtsvg is distributed in the hope that it will be useful,
11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13   * GNU Lesser General Public License for more details.
14   * 
15   * You should have received a copy of the GNU Lesser General Public License
16   * along with libgwtsvg.  If not, see http://www.gnu.org/licenses/
17   **********************************************/
18  /*
19   * Copyright (c) 2004 World Wide Web Consortium,
20   *
21   * (Massachusetts Institute of Technology, European Research Consortium for
22   * Informatics and Mathematics, Keio University). All Rights Reserved. This
23   * work is distributed under the W3C(r) Software License [1] in the hope that
24   * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
25   * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
26   *
27   * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
28   */
29  
30  package org.vectomatic.dom.svg;
31  
32  import org.vectomatic.dom.svg.impl.SVGElement;
33  import org.vectomatic.dom.svg.impl.SVGUseElement;
34  
35  import com.google.gwt.dom.client.EventTarget;
36  
37  /**
38   * <p>For each <a href='http://www.w3.org/TR/SVG11/struct.html#UseElement'
39   * title='use element specification'>use</a> element, the SVG DOM maintains
40   * a shadow tree (the "instance tree") of objects of type {@link org.vectomatic.dom.svg.OMSVGElementInstance}.
41   * An {@link org.vectomatic.dom.svg.OMSVGElementInstance} represents a single
42   * node in the instance tree. The root object in the instance tree is pointed
43   * to by the {@link org.vectomatic.dom.svg.impl.SVGUseElement#getInstanceRoot()}
44   * attribute on the {@link org.vectomatic.dom.svg.impl.SVGUseElement} object
45   * for the corresponding <a href='http://www.w3.org/TR/SVG11/struct.html#UseElement'
46   * title='use element specification'>use</a> element.</p> <p>If the <a href='http://www.w3.org/TR/SVG11/struct.html#UseElement'
47   * title='use element specification'>use</a> element references a simple graphics
48   * element such as a <a href='http://www.w3.org/TR/SVG11/shapes.html#RectElement'
49   * title='rect element specification'>rect</a>, then there is only a single
50   * {@link org.vectomatic.dom.svg.OMSVGElementInstance} object, and the {@link
51   * org.vectomatic.dom.svg.OMSVGElementInstance#getCorrespondingElement()}
52   * attribute on this {@link org.vectomatic.dom.svg.OMSVGElementInstance} object
53   * is the {@link org.vectomatic.dom.svg.impl.SVGRectElement} that corresponds
54   * to the referenced <a href='http://www.w3.org/TR/SVG11/shapes.html#RectElement'
55   * title='rect element specification'>rect</a> element.</p> <p>If the <a href='http://www.w3.org/TR/SVG11/struct.html#UseElement'
56   * title='use element specification'>use</a> element references a <a href='http://www.w3.org/TR/SVG11/struct.html#GElement'
57   * title='g element specification'>g</a> which contains two <a href='http://www.w3.org/TR/SVG11/shapes.html#RectElement'
58   * title='rect element specification'>rect</a> elements, then the instance
59   * tree contains three {@link org.vectomatic.dom.svg.OMSVGElementInstance}
60   * objects, a root {@link org.vectomatic.dom.svg.OMSVGElementInstance} object
61   * whose {@link org.vectomatic.dom.svg.OMSVGElementInstance#getCorrespondingElement()}
62   * is the {@link org.vectomatic.dom.svg.impl.SVGGElement} object for the <a
63   * href='http://www.w3.org/TR/SVG11/struct.html#GElement' title='g element
64   * specification'>g</a>, and then two child {@link org.vectomatic.dom.svg.OMSVGElementInstance}
65   * objects, each of which has its {@link org.vectomatic.dom.svg.OMSVGElementInstance#getCorrespondingElement()}
66   * that is an {@link org.vectomatic.dom.svg.impl.SVGRectElement} object.</p>
67   * <p>If the referenced object is itself a <a href='http://www.w3.org/TR/SVG11/struct.html#UseElement'
68   * title='use element specification'>use</a>, or if there are <a href='http://www.w3.org/TR/SVG11/struct.html#UseElement'
69   * title='use element specification'>use</a> subelements within the referenced
70   * object, the instance tree will contain recursive expansion of the indirect
71   * references to form a complete tree. For example, if a <a href='http://www.w3.org/TR/SVG11/struct.html#UseElement'
72   * title='use element specification'>use</a> element references a <a href='http://www.w3.org/TR/SVG11/struct.html#GElement'
73   * title='g element specification'>g</a>, and the <a href='http://www.w3.org/TR/SVG11/struct.html#GElement'
74   * title='g element specification'>g</a> itself contains a <a href='http://www.w3.org/TR/SVG11/struct.html#UseElement'
75   * title='use element specification'>use</a>, and that <a href='http://www.w3.org/TR/SVG11/struct.html#UseElement'
76   * title='use element specification'>use</a> references a <a href='http://www.w3.org/TR/SVG11/shapes.html#RectElement'
77   * title='rect element specification'>rect</a>, then the instance tree for
78   * the original (outermost) <a href='http://www.w3.org/TR/SVG11/struct.html#UseElement'
79   * title='use element specification'>use</a> will consist of a hierarchy of
80   * {@link org.vectomatic.dom.svg.OMSVGElementInstance} objects, as follows:</p>
81   * <pre>SVGElementInstance #1 (parentNode=null, firstChild=#2, correspondingElement
82   * is the 'g')
83   * SVGElementInstance #2 (parentNode=#1, firstChild=#3, correspondingElement
84   * is the other 'use')
85   * SVGElementInstance #3 (parentNode=#2, firstChild=null, correspondingElement
86   * is the 'rect')
87   * </pre>
88   */
89  public class OMSVGElementInstance extends EventTarget {
90    protected OMSVGElementInstance() {
91    }
92  
93    // Implementation of the svg::SVGElementInstance W3C IDL interface
94    /**
95     * The corresponding element to which this object is an instance. For example,
96     * if a <a href='http://www.w3.org/TR/SVG11/struct.html#UseElement' title='use
97     * element specification'>use</a> element references a <a href='http://www.w3.org/TR/SVG11/shapes.html#RectElement'
98     * title='rect element specification'>rect</a> element, then an {@link org.vectomatic.dom.svg.OMSVGElementInstance}
99     * is created, with its {@link org.vectomatic.dom.svg.OMSVGElementInstance#getCorrespondingElement()}
100    * being the {@link org.vectomatic.dom.svg.OMSVGElementInstance} object for
101    * the <a href='http://www.w3.org/TR/SVG11/shapes.html#RectElement' title='rect
102    * element specification'>rect</a> element.
103    */
104   public final OMSVGElement getCorrespondingElement() {
105     return (OMSVGElement) OMNode.convert(getCorrespondingElement_());
106   };
107   /**
108    * The corresponding <a href='http://www.w3.org/TR/SVG11/struct.html#UseElement'
109    * title='use element specification'>use</a> element to which this {@link
110    * org.vectomatic.dom.svg.OMSVGElementInstance} object belongs. When <a href='http://www.w3.org/TR/SVG11/struct.html#UseElement'
111    * title='use element specification'>use</a> elements are nested (e.g., a
112    * <a href='http://www.w3.org/TR/SVG11/struct.html#UseElement' title='use
113    * element specification'>use</a> references another <a href='http://www.w3.org/TR/SVG11/struct.html#UseElement'
114    * title='use element specification'>use</a> which references a graphics element
115    * such as a <a href='http://www.w3.org/TR/SVG11/shapes.html#RectElement'
116    * title='rect element specification'>rect</a>), then the {@link org.vectomatic.dom.svg.OMSVGElementInstance#getCorrespondingUseElement()}
117    * is the outermost <a href='http://www.w3.org/TR/SVG11/struct.html#UseElement'
118    * title='use element specification'>use</a> (i.e., the one which indirectly
119    * references the <a href='http://www.w3.org/TR/SVG11/shapes.html#RectElement'
120    * title='rect element specification'>rect</a>, not the one with the direct
121    * reference).
122    */
123   public final OMSVGUseElement getCorrespondingUseElement() {
124     return (OMSVGUseElement) OMNode.convert(getCorrespondingUseElement_());
125   };
126   /**
127    * The parent of this {@link org.vectomatic.dom.svg.OMSVGElementInstance}
128    * within the instance tree. All {@link org.vectomatic.dom.svg.OMSVGElementInstance}
129    * objects have a parent except the {@link org.vectomatic.dom.svg.OMSVGElementInstance}
130    * which corresponds to the element which was directly referenced by the <a
131    * href='http://www.w3.org/TR/SVG11/struct.html#UseElement' title='use element
132    * specification'>use</a> element, in which case {@link org.vectomatic.dom.svg.OMSVGElementInstance#getParentNode()}
133    * is null.
134    */
135   public final native OMSVGElementInstance getParentNode() /*-{
136     return this.parentNode;
137   }-*/;
138   /**
139    * An {@link org.vectomatic.dom.svg.OMSVGElementInstanceList} that contains
140    * all children of this {@link org.vectomatic.dom.svg.OMSVGElementInstance}
141    * within the instance tree. If there are no children, this is an {@link org.vectomatic.dom.svg.OMSVGElementInstanceList}
142    * containing no entries (i.e., an empty list).
143    */
144   public final native OMSVGElementInstanceList getChildNodes() /*-{
145     return this.childNodes;
146   }-*/;
147   /**
148    * The first child of this {@link org.vectomatic.dom.svg.OMSVGElementInstance}
149    * within the instance tree. If there is no such {@link org.vectomatic.dom.svg.OMSVGElementInstance},
150    * this returns null.
151    */
152   public final native OMSVGElementInstance getFirstChild() /*-{
153     return this.firstChild;
154   }-*/;
155   /**
156    * The last child of this {@link org.vectomatic.dom.svg.OMSVGElementInstance}
157    * within the instance tree. If there is no such {@link org.vectomatic.dom.svg.OMSVGElementInstance},
158    * this returns null.
159    */
160   public final native OMSVGElementInstance getLastChild() /*-{
161     return this.lastChild;
162   }-*/;
163   /**
164    * The {@link org.vectomatic.dom.svg.OMSVGElementInstance} immediately preceding
165    * this {@link org.vectomatic.dom.svg.OMSVGElementInstance}. If there is no
166    * such {@link org.vectomatic.dom.svg.OMSVGElementInstance}, this returns
167    * null.
168    */
169   public final native OMSVGElementInstance getPreviousSibling() /*-{
170     return this.previousSibling;
171   }-*/;
172   /**
173    * The {@link org.vectomatic.dom.svg.OMSVGElementInstance} immediately following
174    * this {@link org.vectomatic.dom.svg.OMSVGElementInstance}. If there is no
175    * such {@link org.vectomatic.dom.svg.OMSVGElementInstance}, this returns
176    * null.
177    */
178   public final native OMSVGElementInstance getNextSibling() /*-{
179     return this.nextSibling;
180   }-*/;
181 
182   private final native SVGElement getCorrespondingElement_() /*-{
183     return this.correspondingElement;
184   }-*/;
185   private final native SVGUseElement getCorrespondingUseElement_() /*-{
186     return this.correspondingUseElement;
187   }-*/;
188 
189 }