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 }