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 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 SVGNumber objects.</p> <p>{@link org.vectomatic.dom.svg.OMSVGNumberList}
39   * has the same attributes and methods as other SVGxxxList interfaces. Implementers
40   * may consider using a single base class to implement the various SVGxxxList
41   * interfaces.</p> <p id="ReadOnlyNumberList">An {@link org.vectomatic.dom.svg.OMSVGNumberList}
42   * object can be designated as <em>read only</em>, which means that attempts
43   * to modify the object will result in an exception being thrown, as described
44   * below.</p>
45   */
46  public class OMSVGNumberList implements Iterable<OMSVGNumber> {
47    private JavaScriptObject ot;
48    protected OMSVGNumberList(JavaScriptObject ot) {
49      this.ot = ot;
50    }
51  
52    // Implementation of the svg::SVGNumberList W3C IDL interface
53    /**
54     * The number of items in the list.
55     */
56    public final native int getNumberOfItems() /*-{
57      return this.@org.vectomatic.dom.svg.OMSVGNumberList::ot.numberOfItems;
58    }-*/;
59      /**
60     * Clears all existing current items from the list, with the result being
61     * an empty list.
62     * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
63     * corresponds to a <a href="svgdom.html#ReadOnlyNodes">read only attribute</a>
64     * or when the object itself is   <a href="#ReadOnlyNumberList">read only</a>.
65     */
66    public final native void clear() throws JavaScriptException /*-{
67      this.@org.vectomatic.dom.svg.OMSVGNumberList::ot.clear();
68    }-*/;
69    /**
70     * Clears all existing current items from the list and re-initializes the
71     * list to hold the single item specified by the parameter.  If the inserted
72     * item is already in a list, it is removed from its previous list before
73     * it is inserted into this list.  The inserted item is the item itself and
74     * not a copy.
75     * @param newItem The item which should become the only member of the list.
76     * @return The item being inserted into the list.
77     * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
78     * corresponds to a <a href="svgdom.html#ReadOnlyNodes">read only attribute</a>
79     * or when the object itself is   <a href="#ReadOnlyNumberList">read only</a>.
80     */
81    public final native OMSVGNumber initialize(OMSVGNumber newItem) throws JavaScriptException /*-{
82      return this.@org.vectomatic.dom.svg.OMSVGNumberList::ot.initialize(newItem);
83    }-*/;
84    /**
85     * Returns the specified item from the list.  The returned item is the item
86     * itself and not a copy.  Any changes made to the item are immediately reflected
87     * in the list.
88     * @param index The index of the item from the list which is to be   returned.
89     * The first item is number 0.
90     * @return The selected item.
91     * @throws DOMException(INDEX_SIZE_ERR) Raised if the index number is   greater
92     * than or equal to {@link org.vectomatic.dom.svg.OMSVGNumberList#getNumberOfItems()}.
93     */
94    public final native OMSVGNumber getItem(int index) throws JavaScriptException /*-{
95      return this.@org.vectomatic.dom.svg.OMSVGNumberList::ot.getItem(index);
96    }-*/;
97    /**
98     * Inserts a new item into the list at the specified position. The first item
99     * is number 0. If <var>newItem</var> is already in a list, it is removed
100    * from its previous list before it is inserted into this list. The inserted
101    * item is the item itself and not a copy. If the item is already in this
102    * list, note that the index of the item to insert before is <i>before</i>
103    * the removal of the item.
104    * @param newItem The item which is to be inserted into the list.
105    * @param index The index of the item before which the new item is to be 
106    * inserted. The first item is number 0.  If the index is equal to 0,   then
107    * the new item is inserted at the front of the list. If the index   is greater
108    * than or equal to {@link org.vectomatic.dom.svg.OMSVGNumberList#getNumberOfItems()},
109    * then the new item is   appended to the end of the list.
110    * @return The inserted item.
111    * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
112    * corresponds to a <a href="svgdom.html#ReadOnlyNodes">read only attribute</a>
113    * or when the object itself is   <a href="#ReadOnlyNumberList">read only</a>.
114    */
115   public final native OMSVGNumber insertItemBefore(OMSVGNumber newItem, int index) throws JavaScriptException /*-{
116     return this.@org.vectomatic.dom.svg.OMSVGNumberList::ot.insertItemBefore(newItem, index);
117   }-*/;
118   /**
119    * Replaces an existing item in the list with a new item. If <var>newItem</var>
120    * is already in a list, it is removed from its previous list before it is
121    * inserted into this list.  The inserted item is the item itself and not
122    * a copy.  If the item is already in this list, note that the index of the
123    * item to replace is <i>before</i> the removal of the item.
124    * @param newItem The item which is to be inserted into the list.
125    * @param index The index of the item which is to be replaced. The first 
126    * item is number 0.
127    * @return The inserted item.
128    * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
129    * corresponds to a <a href="svgdom.html#ReadOnlyNodes">read only attribute</a>
130    * or when the object itself is   <a href="#ReadOnlyNumberList">read only</a>.
131    * @throws DOMException(INDEX_SIZE_ERR) Raised if the index number is   greater
132    * than or equal to {@link org.vectomatic.dom.svg.OMSVGNumberList#getNumberOfItems()}.
133    */
134   public final native OMSVGNumber replaceItem(OMSVGNumber newItem, int index) throws JavaScriptException /*-{
135     return this.@org.vectomatic.dom.svg.OMSVGNumberList::ot.replaceItem(newItem, index);
136   }-*/;
137   /**
138    * Removes an existing item from the list.
139    * @param index The index of the item which is to be removed. The first  
140    * item is number 0.
141    * @return The removed item.
142    * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
143    * cannot be modified.
144    * @throws DOMException(INDEX_SIZE_ERR) Raised if the index number is   greater
145    * than or equal to {@link org.vectomatic.dom.svg.OMSVGNumberList#getNumberOfItems()}.
146    */
147   public final native OMSVGNumber removeItem(int index) throws JavaScriptException /*-{
148     return this.@org.vectomatic.dom.svg.OMSVGNumberList::ot.removeItem(index);
149   }-*/;
150   /**
151    * Inserts a new item at the end of the list. If <var>newItem</var> is already
152    * in a list, it is removed from its previous list before it is inserted into
153    * this list.  The inserted item is the item itself and not a copy.
154    * @param newItem The item which is to be inserted. The first item is   number
155    * 0.
156    * @return The inserted item.
157    * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
158    * cannot be modified.
159    */
160   public final native OMSVGNumber appendItem(OMSVGNumber newItem) throws JavaScriptException /*-{
161     return this.@org.vectomatic.dom.svg.OMSVGNumberList::ot.appendItem(newItem);
162   }-*/;
163   
164   // Helper methods
165   /**
166    * Inserts a new value into the list at the specified position. The first value
167    * is number 0. The value is wrapped into a {@link org.vectomatic.dom.svg.OMSVGNumber}
168    * @param svg The {@link org.vectomatic.dom.svg.OMSVGSVGElement} used to
169    * instantiate the float wrapper.
170    * @param value The value which is to be inserted into the list.
171    * @param index The index of the value before which the new value is to be 
172    * inserted. The first value is number 0.  If the index is equal to 0,   then
173    * the new value is inserted at the front of the list. If the index   is greater
174    * than or equal to {@link org.vectomatic.dom.svg.OMSVGNumberList#getNumberOfItems()},
175    * then the new value is   appended to the end of the list.
176    * @return The inserted value wrapper.
177    * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
178    * corresponds to a <a href="svgdom.html#ReadOnlyNodes">read only attribute</a>
179    * or when the object itself is   <a href="#ReadOnlyNumberList">read only</a>.
180    */
181   public final OMSVGNumber insertItemBefore(OMSVGSVGElement svg, float value, int index) throws JavaScriptException {
182 	 return insertItemBefore(svg.createSVGNumber(value), index);
183   }
184   /**
185    * Inserts a new value at the end of the list. The value is wrapped into 
186    * a {@link org.vectomatic.dom.svg.OMSVGNumber}
187    * @param svg The {@link org.vectomatic.dom.svg.OMSVGSVGElement} used to
188    * instantiate the float wrapper.
189    * @param value The value which is to be inserted. The first value is   number
190    * 0.
191    * @return The inserted value wrapper.
192    * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
193    * cannot be modified.
194    */
195   public final OMSVGNumber appendItem(OMSVGSVGElement svg, float value) throws JavaScriptException {
196 	 return appendItem(svg.createSVGNumber(value));
197   }
198   /**
199    * Inserts an array of values at the end of the list. The values are wrapped into 
200    * {@link org.vectomatic.dom.svg.OMSVGNumber} objects
201    * @param svg The {@link org.vectomatic.dom.svg.OMSVGSVGElement} used to
202    * instantiate the float wrappers.
203    * @param values The array of values which is to be inserted. The first value is   number
204    * 0.
205    * @return The array of inserted value wrappers.
206    * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
207    * cannot be modified.
208    */
209   public final OMSVGNumber[] appendItems(OMSVGSVGElement svg, float[] values) throws JavaScriptException {
210 	 OMSVGNumber[] newItems = new OMSVGNumber[values.length];
211 	 for (int i = 0; i < values.length; i++) {
212 		newItems[i] = appendItem(svg, values[i]);
213 	 }
214 	 return newItems;
215   }
216   
217   /**
218    * Replaces an existing value in the list with a new value. The new value is wrapped into 
219    * a {@link org.vectomatic.dom.svg.OMSVGNumber}. If <var>value</var>
220    * is already in a list, it is removed from its previous list before it is
221    * inserted into this list.
222    * @param svg The {@link org.vectomatic.dom.svg.OMSVGSVGElement} used to
223    * instantiate the float wrapper.
224    * @param value The value which is to be inserted into the list.
225    * @param index The index of the value which is to be replaced. The first 
226    * item is number 0.
227    * @return The inserted value wrapper.
228    * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised when the list
229    * corresponds to a <a href="svgdom.html#ReadOnlyNodes">read only attribute</a>
230    * or when the object itself is   <a href="#ReadOnlyNumberList">read only</a>.
231    * @throws DOMException(INDEX_SIZE_ERR) Raised if the index number is   greater
232    * than or equal to {@link org.vectomatic.dom.svg.OMSVGNumberList#getNumberOfItems()}.
233    */
234   public final OMSVGNumber replaceItem(OMSVGSVGElement svg, float value, int index) throws JavaScriptException {
235 	 return replaceItem(svg.createSVGNumber(value), index);
236   }
237   
238   /**
239    * Returns an iterator over the {@link org.vectomatic.dom.svg.OMSVGNumber}
240    * elements in this list in proper sequence.
241    *
242    * <p>This implementation returns a straightforward implementation of the
243    * iterator interface, relying on the backing list's {@code getNumberOfItems()},
244    * and {@code getItem(int)} methods.
245    *
246    * <p>Note that the iterator returned by this method will throw an
247    * {@code UnsupportedOperationException} in response to its
248    * {@code remove} method.
249    *
250    * @return an iterator over the {@link org.vectomatic.dom.svg.OMSVGNumber}
251    * elements in this list in proper sequence
252    */
253   @Override
254   public final Iterator<OMSVGNumber> iterator() {
255 	return new Iterator<OMSVGNumber>() {
256 		private int index;
257 		@Override
258 		public boolean hasNext() {
259 			return index < getNumberOfItems();
260 		}
261 
262 		@Override
263 		public OMSVGNumber next() {
264 			return getItem(index++);
265 		}
266 
267 		@Override
268 		public void remove() {
269 			throw new UnsupportedOperationException();
270 		}
271 	};
272   }
273 }