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 java.util.Iterator;
33
34 import com.google.gwt.core.client.JavaScriptException;
35 import com.google.gwt.core.client.JavaScriptObject;
36
37 /**
38 * <p>This interface defines a list of SVGTransform objects.</p> <p>The {@link
39 * org.vectomatic.dom.svg.OMSVGTransformList} and {@link org.vectomatic.dom.svg.OMSVGTransform}
40 * interfaces correspond to the various attributes which specify a set of
41 * transformations, such as the <code>transform</code> attribute which is
42 * available for many of SVG's elements.</p> <p>{@link org.vectomatic.dom.svg.OMSVGTransformList}
43 * has the same attributes and methods as other SVGxxxList interfaces. Implementers
44 * may consider using a single base class to implement the various SVGxxxList
45 * interfaces.</p> <p id="ReadOnlyTransformList">An {@link org.vectomatic.dom.svg.OMSVGTransformList}
46 * object can be designated as <em>read only</em>, which means that attempts
47 * to modify the object will result in an exception being thrown, as described
48 * below.</p>
49 */
50 public class OMSVGTransformList implements Iterable<OMSVGTransform> {
51 private JavaScriptObject ot;
52 protected OMSVGTransformList(JavaScriptObject ot) {
53 this.ot = ot;
54 }
55
56 // Implementation of the svg::SVGTransformList W3C IDL interface
57 /**
58 * The number of items in the list.
59 */
60 public final native int getNumberOfItems() /*-{
61 return this.@org.vectomatic.dom.svg.OMSVGTransformList::ot.numberOfItems;
62 }-*/;
63 /**
64 * Clears all existing current items from the list, with the result being
65 * an empty list.
66 * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
67 * corresponds to a <a href="svgdom.html#ReadOnlyNodes">read only attribute</a>
68 * or when the object itself is <a href="#ReadOnlyTransformList">read only</a>.
69 */
70 public final native void clear() throws JavaScriptException /*-{
71 this.@org.vectomatic.dom.svg.OMSVGTransformList::ot.clear();
72 }-*/;
73 /**
74 * Clears all existing current items from the list and re-initializes the
75 * list to hold the single item specified by the parameter. If the inserted
76 * item is already in a list, it is removed from its previous list before
77 * it is inserted into this list. The inserted item is the item itself and
78 * not a copy.
79 * @param newItem The item which should become the only member of the list.
80 * @return The item being inserted into the list.
81 * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
82 * corresponds to a <a href="svgdom.html#ReadOnlyNodes">read only attribute</a>
83 * or when the object itself is <a href="#ReadOnlyTransformList">read only</a>.
84 */
85 public final native OMSVGTransform initialize(OMSVGTransform newItem) throws JavaScriptException /*-{
86 return this.@org.vectomatic.dom.svg.OMSVGTransformList::ot.initialize(newItem);
87 }-*/;
88 /**
89 * Returns the specified item from the list. The returned item is the item
90 * itself and not a copy. Any changes made to the item are immediately reflected
91 * in the list.
92 * @param index The index of the item from the list which is to be returned.
93 * The first item is number 0.
94 * @return The selected item.
95 * @throws DOMException(INDEX_SIZE_ERR) Raised if the index number is greater
96 * than or equal to {@link org.vectomatic.dom.svg.OMSVGTransformList#getNumberOfItems()}.
97 */
98 public final native OMSVGTransform getItem(int index) throws JavaScriptException /*-{
99 return this.@org.vectomatic.dom.svg.OMSVGTransformList::ot.getItem(index);
100 }-*/;
101 /**
102 * Inserts a new item into the list at the specified position. The first item
103 * is number 0. If <var>newItem</var> is already in a list, it is removed
104 * from its previous list before it is inserted into this list. The inserted
105 * item is the item itself and not a copy. If the item is already in this
106 * list, note that the index of the item to insert before is <i>before</i>
107 * the removal of the item.
108 * @param newItem The item which is to be inserted into the list.
109 * @param index The index of the item before which the new item is to be
110 * inserted. The first item is number 0. If the index is equal to 0, then
111 * the new item is inserted at the front of the list. If the index is greater
112 * than or equal to {@link org.vectomatic.dom.svg.OMSVGTransformList#getNumberOfItems()},
113 * then the new item is appended to the end of the list.
114 * @return The inserted item.
115 * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
116 * corresponds to a <a href="svgdom.html#ReadOnlyNodes">read only attribute</a>
117 * or when the object itself is <a href="#ReadOnlyTransformList">read only</a>.
118 */
119 public final native OMSVGTransform insertItemBefore(OMSVGTransform newItem, int index) throws JavaScriptException /*-{
120 return this.@org.vectomatic.dom.svg.OMSVGTransformList::ot.insertItemBefore(newItem, index);
121 }-*/;
122 /**
123 * Replaces an existing item in the list with a new item. If <var>newItem</var>
124 * is already in a list, it is removed from its previous list before it is
125 * inserted into this list. The inserted item is the item itself and not
126 * a copy. If the item is already in this list, note that the index of the
127 * item to replace is <i>before</i> the removal of the item.
128 * @param newItem The item which is to be inserted into the list.
129 * @param index The index of the item which is to be replaced. The first
130 * item is number 0.
131 * @return The inserted item.
132 * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
133 * corresponds to a <a href="svgdom.html#ReadOnlyNodes">read only attribute</a>
134 * or when the object itself is <a href="#ReadOnlyTransformList">read only</a>.
135 * @throws DOMException(INDEX_SIZE_ERR) Raised if the index number is greater
136 * than or equal to {@link org.vectomatic.dom.svg.OMSVGTransformList#getNumberOfItems()}.
137 */
138 public final native OMSVGTransform replaceItem(OMSVGTransform newItem, int index) throws JavaScriptException /*-{
139 return this.@org.vectomatic.dom.svg.OMSVGTransformList::ot.replaceItem(newItem, index);
140 }-*/;
141 /**
142 * Removes an existing item from the list.
143 * @param index The index of the item which is to be removed. The first
144 * item is number 0.
145 * @return The removed item.
146 * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
147 * corresponds to a <a href="svgdom.html#ReadOnlyNodes">read only attribute</a>
148 * or when the object itself is <a href="#ReadOnlyTransformList">read only</a>.
149 * @throws DOMException(INDEX_SIZE_ERR) Raised if the index number is greater
150 * than or equal to {@link org.vectomatic.dom.svg.OMSVGTransformList#getNumberOfItems()}.
151 */
152 public final native OMSVGTransform removeItem(int index) throws JavaScriptException /*-{
153 return this.@org.vectomatic.dom.svg.OMSVGTransformList::ot.removeItem(index);
154 }-*/;
155 /**
156 * Inserts a new item at the end of the list. If <var>newItem</var> is already
157 * in a list, it is removed from its previous list before it is inserted into
158 * this list. The inserted item is the item itself and not a copy.
159 * @param newItem The item which is to be inserted. The first item is number
160 * 0.
161 * @return The inserted item.
162 * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
163 * corresponds to a <a href="svgdom.html#ReadOnlyNodes">read only attribute</a>
164 * or when the object itself is <a href="#ReadOnlyTransformList">read only</a>.
165 */
166 public final native OMSVGTransform appendItem(OMSVGTransform newItem) throws JavaScriptException /*-{
167 return this.@org.vectomatic.dom.svg.OMSVGTransformList::ot.appendItem(newItem);
168 }-*/;
169 /**
170 * <p xmlns:edit="http://xmlns.grorg.org/SVGT12NG/"> Creates an {@link org.vectomatic.dom.svg.OMSVGTransform}
171 * object which is initialized to transform of type SVG_TRANSFORM_MATRIX and
172 * whose values are the given matrix. The values from the parameter <var>matrix</var>
173 * are copied, the <var>matrix</var> parameter is not adopted as <a edit:format="expanded">SVGTransform::matrix</a>.
174 * </p>
175 * @param matrix The matrix which defines the transformation.
176 * @return The returned {@link org.vectomatic.dom.svg.OMSVGTransform} object.
177 */
178 public final native OMSVGTransform createSVGTransformFromMatrix(OMSVGMatrix matrix) /*-{
179 return this.@org.vectomatic.dom.svg.OMSVGTransformList::ot.createSVGTransformFromMatrix(matrix);
180 }-*/;
181 /**
182 * Consolidates the list of separate {@link org.vectomatic.dom.svg.OMSVGTransform}
183 * objects by multiplying the equivalent transformation matrices together
184 * to result in a list consisting of a single {@link org.vectomatic.dom.svg.OMSVGTransform}
185 * object of type SVG_TRANSFORM_MATRIX. The consolidation operation creates
186 * new SVGTransform object as the first and only item in the list. The returned
187 * item is the item itself and not a copy. Any changes made to the item are
188 * immediately reflected in the list.
189 * @return The resulting {@link org.vectomatic.dom.svg.OMSVGTransform} object
190 * which becomes single item in the list. If the list was empty, then a
191 * value of null is returned.
192 * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
193 * corresponds to a <a href="svgdom.html#ReadOnlyNodes">read only attribute</a>
194 * or when the object itself is <a href="#ReadOnlyTransformList">read only</a>.
195 */
196 public final native OMSVGTransform consolidate() throws JavaScriptException /*-{
197 return this.@org.vectomatic.dom.svg.OMSVGTransformList::ot.consolidate();
198 }-*/;
199 /**
200 * Returns an iterator over the {@link org.vectomatic.dom.svg.OMSVGTransform}
201 * elements in this list in proper sequence.
202 *
203 * <p>This implementation returns a straightforward implementation of the
204 * iterator interface, relying on the backing list's {@code getNumberOfItems()},
205 * and {@code getItem(int)} methods.
206 *
207 * <p>Note that the iterator returned by this method will throw an
208 * {@code UnsupportedOperationException} in response to its
209 * {@code remove} method.
210 *
211 * @return an iterator over the {@link org.vectomatic.dom.svg.OMSVGTransform}
212 * elements in this list in proper sequence
213 */
214 @Override
215 public final Iterator<OMSVGTransform> iterator() {
216 return new Iterator<OMSVGTransform>() {
217 private int index;
218 @Override
219 public boolean hasNext() {
220 return index < getNumberOfItems();
221 }
222
223 @Override
224 public OMSVGTransform next() {
225 return getItem(index++);
226 }
227
228 @Override
229 public void remove() {
230 throw new UnsupportedOperationException();
231 }
232 };
233 }
234 /**
235 * Returns a textual description of the transform list for debugging purposes.
236 * @return a textual description of the transform list.
237 */
238 public final String getDescription() {
239 StringBuilder builder = new StringBuilder();
240 for (int i = 0, size = getNumberOfItems(); i < size; i++) {
241 if (i > 0) {
242 builder.append(" ");
243 }
244 builder.append(getItem(i).getDescription());
245 }
246 return builder.toString();
247 }
248 }