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.impl;
31  
32  import org.vectomatic.dom.svg.OMSVGAnimatedBoolean;
33  import org.vectomatic.dom.svg.OMSVGAnimatedEnumeration;
34  import org.vectomatic.dom.svg.OMSVGAnimatedLength;
35  import org.vectomatic.dom.svg.OMSVGPoint;
36  import org.vectomatic.dom.svg.OMSVGRect;
37  import org.vectomatic.dom.svg.OMSVGStringList;
38  
39  import com.google.gwt.core.client.JavaScriptException;
40  
41  /**
42   * <p>The {@link org.vectomatic.dom.svg.impl.SVGTextContentElement} is inherited
43   * by various text-related interfaces, such as {@link org.vectomatic.dom.svg.impl.SVGTextElement},
44   * {@link org.vectomatic.dom.svg.impl.SVGTSpanElement}, {@link org.vectomatic.dom.svg.impl.SVGTRefElement},
45   * {@link org.vectomatic.dom.svg.impl.SVGAltGlyphElement} and {@link org.vectomatic.dom.svg.impl.SVGTextPathElement}.</p>
46   * <p>For the methods on this interface that refer to an index to a character
47   * or a number of characters, these references are to be interpreted as an
48   * index to a UTF-16 code unit or a number of UTF-16 code units, respectively.
49   * This is for consistency with DOM Level 2 Core, where methods on the <code>CharacterData</code>
50   * interface use UTF-16 code units as indexes and counts within the character
51   * data. Thus for example, if the text content of a <a href='http://www.w3.org/TR/SVG11/text.html#TextElement'
52   * title='text element specification'>text</a> element is a single non-BMP
53   * character, such as U+10000, then invoking {@link org.vectomatic.dom.svg.impl.SVGTextContentElement#getNumberOfChars()}
54   * on that element will return 2 since there are two UTF-16 code units (the
55   * surrogate pair) used to represent that one character.</p>
56   */
57  public class SVGTextContentElement extends SVGElement {
58    protected SVGTextContentElement() {
59    }
60  
61    // Implementation of the svg::SVGTextContentElement W3C IDL interface
62    /**
63     * Corresponds to attribute <span class='attr-name'>'textLength'</span> on
64     * the given element.
65     */
66    public final native OMSVGAnimatedLength getTextLength() /*-{
67      return this.textLength;
68    }-*/;
69    /**
70     * Corresponds to attribute <span class='attr-name'>'lengthAdjust'</span>
71     * on the given element.  The value must be one of the length adjust constants
72     * defined on this interface.
73     */
74    public final native OMSVGAnimatedEnumeration getLengthAdjust() /*-{
75      return this.lengthAdjust;
76    }-*/;
77    /**
78     * Returns the total number of characters available for rendering within the
79     * current element, which includes referenced characters from <a href='http://www.w3.org/TR/SVG11/text.html#TRefElement'
80     * title='tref element specification'>tref</a> reference, regardless of whether
81     * they will be rendered. Effectively, this is equivalent to the length of
82     * the <a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#Node3-textContent">Node::textContent</a>
83     * attribute from DOM Level 3 Core ([<a href="refs.html#ref-DOM3">DOM3</a>],
84     * section 1.4), if that attribute also expanded <a href='http://www.w3.org/TR/SVG11/text.html#TRefElement'
85     * title='tref element specification'>tref</a> elements.
86     * @return Total number of characters.
87     */
88    public final native int getNumberOfChars() /*-{
89      return this.getNumberOfChars();
90    }-*/;
91    /**
92     * The total sum of all of the advance values from rendering all of the characters
93     * within this element, including the advance value on the glyphs (horizontal
94     * or vertical), the effect of properties <code>kerning</code>, <code>letter-spacing</code>
95     * and <code>word-spacing</code> and adjustments due to attributes <code>tspan/dx</code>
96     * and <code>tspan/dy</code> on <a href='http://www.w3.org/TR/SVG11/text.html#TSpanElement'
97     * title='tspan element specification'>tspan</a> elements. For non-rendering
98     * environments, the user agent shall make reasonable assumptions about glyph
99     * metrics.
100    * @return The text advance distance.
101    */
102   public final native float getComputedTextLength() /*-{
103     return this.getComputedTextLength();
104   }-*/;
105   /**
106    * The total sum of all of the advance values from rendering the specified
107    * substring of the characters, including the advance value on the glyphs
108    * (horizontal or vertical), the effect of properties <code>kerning</code>,
109    * <code>letter-spacing</code> and <code>word-spacing</code> and adjustments
110    * due to attributes <code>tspan/dx</code> and <code>tspan/dy</code> on <a
111    * href='http://www.w3.org/TR/SVG11/text.html#TSpanElement' title='tspan element
112    * specification'>tspan</a> elements. For non-rendering environments, the
113    * user agent shall make reasonable assumptions about glyph metrics.  If multiple
114    * consecutive characters are rendered inseparably (e.g., as a single glyph
115    * or a sequence of glyphs, or because the range encompasses half of a surrogate
116    * pair), and nchars is greater than 0 then the measured range shall be expanded
117    * so that each of the inseparable characters are included.
118    * @param charnum The index of the first character in the substring, where
119    * the first character has an index of 0.
120    * @param nchars The number of characters in the substring. If nchars   specifies
121    * more characters than are available, then the substring will   consist of
122    * all characters starting with charnum until the end of the   list of characters.
123    * @return The text advance distance.
124    * @throws DOMException(INDEX_SIZE_ERR) Raised if <var>charnum</var> or  
125    * <var>nchars</var> is negative or if <var>charnum</var> is greater than
126    * or equal to the number of characters at this node.
127    */
128   public final native float getSubStringLength(int charnum, int nchars) throws JavaScriptException /*-{
129     return this.getSubStringLength(charnum, nchars);
130   }-*/;
131   /**
132    * Returns the current text position before rendering the character in the
133    * user coordinate system for rendering the glyph(s) that correspond to the
134    * specified character. The current text position has already taken into account
135    * the effects of any inter-character adjustments due to properties <code>kerning</code>,
136    * <code>letter-spacing</code> and <code>word-spacing</code> and adjustments
137    * due to attributes <span class='attr-name'>'x'</span>, <span class='attr-name'>'y'</span>,
138    * <span class='attr-name'>'dx'</span> and <span class='attr-name'>'dy'</span>.
139    * If multiple consecutive characters are rendered inseparably (e.g., as a
140    * single glyph or a sequence of glyphs), then each of the inseparable characters
141    * will return the start position for the first glyph.
142    * @param charnum The index of the character, where the first character has
143    * an index of 0.
144    * @return The character's start position.
145    * @throws DOMException(INDEX_SIZE_ERR) Raised if the <var>charnum</var> is
146    * negative or if <var>charnum</var> is greater than or equal to the   number
147    * of characters at this node.
148    */
149   public final native OMSVGPoint getStartPositionOfChar(int charnum) throws JavaScriptException /*-{
150     return this.getStartPositionOfChar(charnum);
151   }-*/;
152   /**
153    * Returns the current text position after rendering the character in the
154    * user coordinate system for rendering the glyph(s) that correspond to the
155    * specified character. This current text position does <em>not</em> take
156    * into account the effects of any inter-character adjustments to prepare
157    * for the next character, such as properties <code>kerning</code>, <code>letter-spacing</code>
158    * and <code>word-spacing</code> and adjustments due to attributes <span class='attr-name'>'x'</span>,
159    * <span class='attr-name'>'y'</span>, <span class='attr-name'>'dx'</span>
160    * and <span class='attr-name'>'dy'</span>. If multiple consecutive characters
161    * are rendered inseparably (e.g., as a single glyph or a sequence of glyphs),
162    * then each of the inseparable characters will return the end position for
163    * the last glyph.
164    * @param charnum The index of the character, where the first character has
165    * an index of 0.
166    * @return The character's end position.
167    * @throws DOMException(INDEX_SIZE_ERR) Raised if the <var>charnum</var> is
168    * negative or if <var>charnum</var> is greater than or equal to the   number
169    * of characters at this node.
170    */
171   public final native OMSVGPoint getEndPositionOfChar(int charnum) throws JavaScriptException /*-{
172     return this.getEndPositionOfChar(charnum);
173   }-*/;
174   /**
175    * Returns a tightest rectangle which defines the minimum and maximum X and
176    * Y values in the user coordinate system for rendering the glyph(s) that
177    * correspond to the specified character. The calculations assume that all
178    * glyphs occupy the full standard glyph cell for the font. If multiple consecutive
179    * characters are rendered inseparably (e.g., as a single glyph or a sequence
180    * of glyphs), then each of the inseparable characters will return the same
181    * extent.
182    * @param charnum The index of the character, where the first character has
183    * an index of 0.
184    * @return The rectangle which encloses all of the rendered glyph(s).
185    * @throws DOMException(INDEX_SIZE_ERR) Raised if the <var>charnum</var> is
186    * negative or if <var>charnum</var> is greater than or equal to the   number
187    * of characters at this node.
188    */
189   public final native OMSVGRect getExtentOfChar(int charnum) throws JavaScriptException /*-{
190     return this.getExtentOfChar(charnum);
191   }-*/;
192   /**
193    * Returns the rotation value relative to the current user coordinate system
194    * used to render the glyph(s) corresponding to the specified character. If
195    * multiple glyph(s) are used to render the given character and the glyphs
196    * each have different rotations (e.g., due to text-on-a-path), the user agent
197    * shall return an average value (e.g., the rotation angle at the midpoint
198    * along the path for all glyphs used to render this character). The rotation
199    * value represents the rotation that is supplemental to any rotation due
200    * to properties <code>glyph-orientation-horizontal</code> and <code>glyph-orientation-vertical</code>;
201    * thus, any glyph rotations due to these properties are not included into
202    * the returned rotation value. If multiple consecutive characters are rendered
203    * inseparably (e.g., as a single glyph or a sequence of glyphs), then each
204    * of the inseparable characters will return the same rotation value.
205    * @param charnum The index of the character, where the first character has
206    * an index of 0.
207    * @return The rotation angle.
208    * @throws DOMException(INDEX_SIZE_ERR) Raised if the <var>charnum</var> is
209    * negative or if <var>charnum</var> is greater than or equal to the   number
210    * of characters at this node.
211    */
212   public final native float getRotationOfChar(int charnum) throws JavaScriptException /*-{
213     return this.getRotationOfChar(charnum);
214   }-*/;
215   /**
216    * Returns the index of the character whose corresponding glyph cell bounding
217    * box contains the specified point. The calculations assume that all glyphs
218    * occupy the full standard glyph cell for the font. If no such character
219    * exists, a value of -1 is returned. If multiple such characters exist, the
220    * character within the element whose glyphs were rendered last (i.e., take
221    * into account any reordering such as for bidirectional text) is used. If
222    * multiple consecutive characters are rendered inseparably (e.g., as a single
223    * glyph or a sequence of glyphs), then the user agent shall allocate an equal
224    * percentage of the text advance amount to each of the contributing characters
225    * in determining which of the characters is chosen.
226    * @param point A point in user space.
227    * @return The index of the character which is at the given point, where 
228    * the first character has an index of 0.
229    */
230   public final native int getCharNumAtPosition(OMSVGPoint point) /*-{
231     return this.getCharNumAtPosition(point);
232   }-*/;
233   /**
234    * Causes the specified substring to be selected just as if the user selected
235    * the substring interactively.
236    * @param charnum The index of the start character which is at the given 
237    * point, where the first character has an index of 0.
238    * @param nchars The number of characters in the substring. If nchars   specifies
239    * more characters than are available, then the substring   will consist of
240    * all characters starting with charnum until the end   of the list of characters.
241    * @throws DOMException(INDEX_SIZE_ERR) Raised if <var>charnum</var> or  
242    * <var>nchars</var> is negative or if <var>charnum</var> is greater   than
243    * or equal to the number of characters at this node.
244    */
245   public final native void selectSubString(int charnum, int nchars) throws JavaScriptException /*-{
246     this.selectSubString(charnum, nchars);
247   }-*/;
248 
249   // Implementation of the svg::SVGExternalResourcesRequired W3C IDL interface
250   /**
251    * Corresponds to attribute {@link org.vectomatic.dom.svg.itf.ISVGExternalResourcesRequired#getExternalResourcesRequired()}
252    * on the given element. Note that the SVG DOM defines the attribute {@link
253    * org.vectomatic.dom.svg.itf.ISVGExternalResourcesRequired#getExternalResourcesRequired()}
254    * as being of type {@link org.vectomatic.dom.svg.OMSVGAnimatedBoolean}, whereas
255    * the SVG language definition says that {@link org.vectomatic.dom.svg.itf.ISVGExternalResourcesRequired#getExternalResourcesRequired()}
256    * is not animated. Because the SVG language definition states that {@link
257    * org.vectomatic.dom.svg.itf.ISVGExternalResourcesRequired#getExternalResourcesRequired()}
258    * cannot be animated, the {@link org.vectomatic.dom.svg.OMSVGAnimatedBoolean#getAnimVal()}
259    * will always be the same as the {@link org.vectomatic.dom.svg.OMSVGAnimatedBoolean#getBaseVal()}.
260    */
261   public final native OMSVGAnimatedBoolean getExternalResourcesRequired() /*-{
262     return this.externalResourcesRequired;
263   }-*/;
264 
265   // Implementation of the svg::SVGLangSpace W3C IDL interface
266   /**
267    * Corresponds to attribute <code>xml:lang</code> on the given element.
268    */
269   public final native String getXmllang() /*-{
270     return this.xmllang;
271   }-*/;
272   /**
273    * Corresponds to attribute <code>xml:lang</code> on the given element.
274    * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised on an   attempt
275    * to change the value of a <a href="svgdom.html#ReadOnlyNodes">read only
276    * attribute</a>.
277    */
278   public final native void setXmllang(String value) throws JavaScriptException /*-{
279     this.xmllang = value;
280   }-*/;
281   /**
282    * Corresponds to attribute <code>xml:space</code> on the given element.
283    */
284   public final native String getXmlspace() /*-{
285     return this.xmlspace;
286   }-*/;
287   /**
288    * Corresponds to attribute <code>xml:space</code> on the given element.
289    * @throws DOMException(NO_MODIFICATION_ALLOWED_ERR) Raised on an   attempt
290    * to change the value of a <a href="svgdom.html#ReadOnlyNodes">read only
291    * attribute</a>.
292    */
293   public final native void setXmlspace(String value) throws JavaScriptException /*-{
294     this.xmlspace = value;
295   }-*/;
296 
297   // Implementation of the svg::SVGTests W3C IDL interface
298   /**
299    * Corresponds to attribute {@link org.vectomatic.dom.svg.itf.ISVGTests#getRequiredFeatures()}
300    * on the given element.
301    */
302   public final native OMSVGStringList getRequiredFeatures() /*-{
303     return @org.vectomatic.dom.svg.OMNode::convertList(Lcom/google/gwt/core/client/JavaScriptObject;)(this.requiredFeatures);
304   }-*/;
305   /**
306    * Corresponds to attribute {@link org.vectomatic.dom.svg.itf.ISVGTests#getRequiredExtensions()}
307    * on the given element.
308    */
309   public final native OMSVGStringList getRequiredExtensions() /*-{
310     return @org.vectomatic.dom.svg.OMNode::convertList(Lcom/google/gwt/core/client/JavaScriptObject;)(this.requiredExtensions);
311   }-*/;
312   /**
313    * Corresponds to attribute {@link org.vectomatic.dom.svg.itf.ISVGTests#getSystemLanguage()}
314    * on the given element.
315    */
316   public final native OMSVGStringList getSystemLanguage() /*-{
317     return @org.vectomatic.dom.svg.OMNode::convertList(Lcom/google/gwt/core/client/JavaScriptObject;)(this.systemLanguage);
318   }-*/;
319   /**
320    * Returns true if the user agent supports the given extension, specified
321    * by a URI.
322    * @param extension The name of the extension, expressed as a URI.
323    * @return True or false, depending on whether the given extension is   supported.
324    */
325   public final native boolean hasExtension(String extension) /*-{
326     return this.hasExtension(extension);
327   }-*/;
328 
329 }