001 
002 /*
003  *  JScripter Standard 1.0 - To Script In Java
004  *  Copyright (C) 2008-2011  J.J.Liu<jianjunliu@126.com> <http://www.jscripter.org>
005  *  
006  *  This program is free software: you can redistribute it and/or modify
007  *  it under the terms of the GNU Affero General Public License as published by
008  *  the Free Software Foundation, either version 3 of the License, or
009  *  (at your option) any later version.
010  *  
011  *  This program is distributed in the hope that it will be useful,
012  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
013  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014  *  GNU Affero General Public License for more details.
015  *  
016  *  You should have received a copy of the GNU Affero General Public License
017  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
018  */
019 
020 package js.user;
021 
022 import js.*;
023 import js.core.*;
024 
025 /**
026  * <p>An <b>opaque</b> class representing JavaScript client-side objects of the global 
027  * {@link JsClient#Range} class.</p>
028  * <p>A {@link JsRange} object represents a contiguous range or region of a document, 
029  * such as the region that the user might select with a mouse drag in a web browser 
030  * window. If an implementation supports the <tt>Range</tt> module, the {@link JsDocument} 
031  * object defines a {@link JsDocument#createRange()} method that you can call to create 
032  * a new {@link JsRange} object. Be careful, however, IE defines an incompatible 
033  * {@link JsDocument#createRange()} method that returns a nonstandard object similar to, 
034  * but not compatible with, this class. This class defines a number of methods for 
035  * specifying a selected region of a document and several more methods for implementing 
036  * cut-and-paste operations on the selected region.</p>
037  * <p>A range has two boundary points: a start point and an end point. Each boundary 
038  * point is specified by a combination of a node and an offset within that node. The 
039  * node is typically an {@link JsElement}, {@link JsDocument}, or {@link JsText} node. 
040  * For {@link JsElement} and {@link JsDocument} nodes, the offset refers to the children 
041  * of that node. An offset of 0 specifies a boundary point before the first child of the 
042  * node. An offset of 1 specifies a boundary point after the first child and before the 
043  * second child. If the boundary node is a {@link JsText} node, however, the offset 
044  * specifies a position between two characters of that text.</p>
045  * <p>The properties of a {@link JsRange} object provide a way to obtain boundary nodes 
046  * and offsets of the range. The methods of the class provide a number of ways to set 
047  * the boundaries of a range. Note that the boundaries of a range may be set to nodes 
048  * within a {@link JsDocument} or a {@link JsDocumentFragment}.</p>
049  * <p>Once the boundary points of a range are defined, you can use {@link #deleteContents()}, 
050  * {@link #extractContents()}, {@link #cloneContents()}, and {@link #insertNode(JsNode)} 
051  * to implement cut, copy, and paste operations.</p>
052  * <p>When a document is altered by insertion or deletion, all {@link JsRange} objects 
053  * that represent portions of that document are altered, if necessary, so that their 
054  * boundary points remain valid and they represent as closely as possible the same 
055  * document content.</p>
056  *
057  * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
058  * @see JsDocument#createRange()
059  *
060  * @javascript <b>Opaque</b> types can be resolved but no class objects for them can be
061  * generated into the target codes. Re-compilers must exit with error on the operations of
062  * accessing that kind of class objects.
063  * The <tt>checkcast</tt> operation to the class literal of this interface must be ignored
064  * and <tt>instanceof</tt> to it always <tt>true</tt>.
065  */
066 public class JsRange extends JsClient.Range.Prototype
067 {
068     /**
069      * Compares the start of the specified range to the start of this range. 
070      * This constant number is a legal value for the <tt>how</tt> argument to the 
071      * {@link #compareBoundaryPoints(Number, JsRange)} method specifying how the 
072      * boundary points of two {@link JsRange} objects are compared.
073      * @since 1.0
074      * @see js.dom.DOM2Range.Range#START_TO_START
075      * @see js.dom.DOM2Range.Range.Member#START_TO_START
076      */
077     public static final int START_TO_START = 0;
078     /**
079      * Compares the start of the specified range to the end of this range. 
080      * This constant number is a legal value for the <tt>how</tt> argument to the 
081      * {@link #compareBoundaryPoints(Number, JsRange)} method specifying how the 
082      * boundary points of two {@link JsRange} objects are compared.
083      * @since 1.0
084      * @see js.dom.DOM2Range.Range#START_TO_END
085      * @see js.dom.DOM2Range.Range.Member#START_TO_END
086      */
087     public static final int START_TO_END = 1;
088     /**
089      * Compares the end of the specified range to the end of this range. 
090      * This constant number is a legal value for the <tt>how</tt> argument to the 
091      * {@link #compareBoundaryPoints(Number, JsRange)} method specifying how the 
092      * boundary points of two {@link JsRange} objects are compared.
093      * @since 1.0
094      * @see js.dom.DOM2Range.Range#END_TO_END
095      * @see js.dom.DOM2Range.Range.Member#END_TO_END
096      */
097     public static final int END_TO_END = 2;
098     /**
099      * Compares the end of the specified range to the start of this range. 
100      * This constant number is a legal value for the <tt>how</tt> argument to the 
101      * {@link #compareBoundaryPoints(Number, JsRange)} method specifying how the 
102      * boundary points of two {@link JsRange} objects are compared.
103      * @since 1.0
104      * @see js.dom.DOM2Range.Range#END_TO_START
105      * @see js.dom.DOM2Range.Range.Member#END_TO_START
106      */
107     public static final int END_TO_START = 3;
108 
109     /**
110      * <p>An <b>internal</b> class containing membership data for its enclosing
111      * opaque class.</p>
112      * <p>This class is only used inside of <b>opaque</b> or <b>internal</b> classes or
113      * class members.</p>
114      *
115      * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
116      * 
117      * @javascript Re-compilers must report error on resolving an <b>internal</b> class.
118      */
119     protected static abstract class Members extends JsClient.Range.Prototype.Members
120     {
121         /**
122          * <p>An <b>internal</b> static field defining a member ID of the field name and
123          * used internally to define a member of the same name.</p>
124          * <p>The property, identified by this member, of a {@link JsRange} object 
125          * refers to a read-only boolean value which is <tt>true</tt> if the start and 
126          * the end of the range are at the same point in the document, that is, if the 
127          * range is empty or collapsed.</p> 
128          * @since 1.0
129          * @see JsRange#collapsed
130          * @see JsRange.Member#collapsed
131          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
132          */
133         public final static Mid collapsed                = id("collapsed"               );
134         /**
135          * <p>An <b>internal</b> static field defining a member ID of the field name and
136          * used internally to define a member of the same name.</p>
137          * @since 1.0
138          * @see JsRange#commonAncestorContainer
139          * @see JsRange.Member#commonAncestorContainer
140          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
141          */
142         public final static Mid commonAncestorContainer  = id("commonAncestorContainer" );
143         /**
144          * <p>An <b>internal</b> static field defining a member ID of the field name and
145          * used internally to define a member of the same name.</p>
146          * @since 1.0
147          * @see JsRange#endContainer
148          * @see JsRange.Member#endContainer
149          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
150          */
151         public final static Mid endContainer             = id("endContainer"            );
152         /**
153          * <p>An <b>internal</b> static field defining a member ID of the field name and
154          * used internally to define a member of the same name.</p>
155          * @since 1.0
156          * @see JsRange#endOffset
157          * @see JsRange.Member#endOffset
158          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
159          */
160         public final static Mid endOffset                = id("endOffset"               );
161         /**
162          * <p>An <b>internal</b> static field defining a member ID of the field name and
163          * used internally to define a member of the same name.</p>
164          * @since 1.0
165          * @see JsRange#startContainer
166          * @see JsRange.Member#startContainer
167          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
168          */
169         public final static Mid startContainer           = id("startContainer"          );
170         /**
171          * <p>An <b>internal</b> static field defining a member ID of the field name and
172          * used internally to define a member of the same name.</p>
173          * @since 1.0
174          * @see JsRange#startOffset
175          * @see JsRange.Member#startOffset
176          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
177          */
178         public final static Mid startOffset              = id("startOffset"             );
179     }
180 
181     /**
182      * <p>An <b>opaque</b> class representing members of its enclosing <b>opaque</b> type.</p>
183      * <p>Note that, this class is <b>opaque</b> but its constructors are all <b>internal</b>. 
184      * This class and the subclasses of this class are used to declare either <b>opaque</b> 
185      * <tt>public</tt> instance fields of the opaque type {@link js.Var.Member} or the 
186      * <b>opaque</b> <tt>public</tt> static fields of other <b>opaque</b> types while their 
187      * constructors are used to define the fields inside <b>opaque</b> classes. Under 
188      * either circumstance, the field names must be exactly same as the member names, as 
189      * the <b>opaque</b> fields of <b>opaque</b> types are resolved by re-compilers directly 
190      * based on the field names.</p>
191      *
192      * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
193      * 
194      * @javascript <b>Opaque</b> types can be resolved but no class objects for them can be created
195      * in the target codes. Re-compilers must exit with error on operations accessing that kind 
196      * of class objects.
197      * Re-compilers must resolve an <b>opaque</b> instance field declared by this class in
198      * {@link js.Var.Member} or its subclasses to the JavaScript identifier: 
199      * <pre>q.m</pre>
200      * where <tt>m</tt> is the identifier of the field name and <tt>q</tt> is the identifier
201      * resolved from the instance of the enclosing member. Re-compilers must resolve an 
202      * <b>opaque</b> static field declared by this class in <b>opaque</b> types other than 
203      * {@link js.Var.Member} and its subclasses to the JavaScript identifier: 
204      * <pre>m</pre>
205      * where <tt>m</tt> is the identifier of the field name. And re-compilers must report
206      * error on the access to <b>opaque</b> fields declared by this class under any other 
207      * circumstances.
208      */
209     public static class Member extends JsClient.Range.Prototype.Member
210     {
211         /**
212          * <p>Internally constructs a member based on a qualifying member.</p>
213          * <p>This constructor is <b>internal</b> and only called inside of <b>opaque</b>
214          * or <b>internal</b> classes or class members.</p>
215          * <p>Note that, this constructor is <b>internal</b> but its declaring class is
216          * <b>opaque</b>. This constructor is used to define <b>opaque</b> instance fields 
217          * declared in the declaring class of this constructor itself or its subclasses. 
218          * Under this circumstance, the field names must be exactly same as the member 
219          * names, as the <b>opaque</b> instance fields of the <b>opaque</b> type 
220          * {@link js.Var.Member} or its subclasses are resolved by re-compilers directly
221          * to their names appending to the name resolved from the specified qualifying 
222          * member with a dot in between.</p>
223          * @param q A qualifying member
224          * @param mid The ID of the member to construct
225          * @since 1.0
226          * @javascript Re-compilers must report error on the invocation to an <b>internal</b> constructor.
227          */
228         public Member(JsObject.Member q, Mid mid) {
229             super(q, mid);
230         }
231         /**
232          * <p>Internally constructs a member without a qualifying member.</p>
233          * <p>This constructor is <b>internal</b> and only called inside of <b>opaque</b>
234          * or <b>internal</b> classes or class members.</p>
235          * <p>Note that, this constructor is <b>internal</b> but its declaring class is
236          * <b>opaque</b>. This constructor is used to define <b>opaque</b> static fields, 
237          * declared in <b>opaque</b> types other than the declaring class of this constructor 
238          * itself and its subclasses. Under this circumstance, the field names must be
239          * exactly same as the member names, as the <b>opaque</b> static fields of <b>opaque</b>
240          * types are generally resolved by re-compilers directly to identifiers of their names.</p>
241          * @param mid The ID of the member to construct
242          * @since 1.0
243          * @javascript Re-compilers must report error on the invocation to an <b>internal</b> constructor.
244          */
245         public Member(Mid mid) {
246             super(mid);
247         }
248         @Override
249         /**
250          * <p>Evaluates the property, represented by the current member instance, of the
251          * argument object.</p>
252          * @param o The argument object
253          * @return The value of the current member based on the object argument.
254          * @since 1.0
255          * @javascript Re-compilers must convert the instance invocation of this method into
256          * the JavaScript expression: 
257          * <pre>o.m</pre>
258          * where <tt>m</tt> is the identifier name resolved from the current member
259          * instance of the invocation.
260          */
261         public JsRange with(ObjectLike o) {
262             return new JsRange(super.with(o));
263         }
264 
265         /**
266          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
267          * name of this field, qualified by the current member instance of the field, and 
268          * to access the property of the name on an object.</p>
269          * <p>The property, identified by this member, of a {@link JsRange} object 
270          * refers to a read-only boolean value which is <tt>true</tt> if the start and 
271          * the end of the range are at the same point in the document, that is, if the 
272          * range is empty or collapsed.</p> 
273          * @since 1.0
274          * @javascript Re-compilers must resolve the member of this instance field to the
275          * identifier of the field name appending to the identifier resolved from its 
276          * qualifying member with a dot in between.
277          */
278         public final Value.Boolean.Member collapsed = new Value.Boolean.Member(this, Members.collapsed);
279         /**
280          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
281          * name of this field, qualified by the current member instance of the field, and 
282          * to access the property of the name on an object.</p>
283          * <p>The property, identified by this member, of a {@link JsRange} object is a 
284          * read-only reference to the most deeply nested {@link JsDocument} node that 
285          * contains, that is, is an ancestor of, both the start and end points of the 
286          * range.</p> 
287          * @since 1.0
288          * @javascript Re-compilers must resolve the member of this instance field to the
289          * identifier of the field name appending to the identifier resolved from its 
290          * qualifying member with a dot in between.
291          */
292         public final JsNode.Member commonAncestorContainer = new JsNode.Member(this, Members.commonAncestorContainer);
293         /**
294          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
295          * name of this field, qualified by the current member instance of the field, and 
296          * to access the property of the name on an object.</p>
297          * <p>The property, identified by this member, of a {@link JsRange} object is a 
298          * read-only reference to the {@link JsDocument} node that contains the end 
299          * point of the range.</p> 
300          * @since 1.0
301          * @javascript Re-compilers must resolve the member of this instance field to the
302          * identifier of the field name appending to the identifier resolved from its 
303          * qualifying member with a dot in between.
304          */
305         public final JsNode.Member endContainer = new JsNode.Member(this, Members.endContainer);
306         /**
307          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
308          * name of this field, qualified by the current member instance of the field, and 
309          * to access the property of the name on an object.</p>
310          * <p>The property, identified by this member, of a {@link JsRange} object 
311          * refers to a read-only number that specifies the position of the range's 
312          * ending point within {@link #endContainer}.</p> 
313          * @since 1.0
314          * @javascript Re-compilers must resolve the member of this instance field to the
315          * identifier of the field name appending to the identifier resolved from its 
316          * qualifying member with a dot in between.
317          */
318         public final Value.Number.Member endOffset = new Value.Number.Member(this, Members.endOffset);
319         /**
320          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
321          * name of this field, qualified by the current member instance of the field, and 
322          * to access the property of the name on an object.</p>
323          * <p>The property, identified by this member, of a {@link JsRange} object is a 
324          * read-only reference to the {@link JsDocument} node that contains the starting 
325          * point of the range.</p> 
326          * @since 1.0
327          * @javascript Re-compilers must resolve the member of this instance field to the
328          * identifier of the field name appending to the identifier resolved from its 
329          * qualifying member with a dot in between.
330          */
331         public final JsNode.Member startContainer = new JsNode.Member(this, Members.startContainer);
332         /**
333          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
334          * name of this field, qualified by the current member instance of the field, and 
335          * to access the property of the name on an object.</p>
336          * <p>The property, identified by this member, of a {@link JsRange} object 
337          * refers to a read-only number that specifies the position of the range's 
338          * starting point within {@link #startContainer}.</p> 
339          * @since 1.0
340          * @javascript Re-compilers must resolve the member of this instance field to the
341          * identifier of the field name appending to the identifier resolved from its 
342          * qualifying member with a dot in between.
343          */
344         public final Value.Number.Member startOffset = new Value.Number.Member(this, Members.startOffset);
345     }
346 
347     /**
348      * <p>Casts an <b>opaque</b> object to the current <b>opaque</b> type by wrapping it
349      * with the wrapping constructor.</p>
350      * @param var The argument of an <b>opaque</b> object.
351      * @since 1.0
352      * @javascript Re-compilers must ignore the construction operation of this constructor,
353      * that is, replacing it with its only argument.
354      */
355     public JsRange(JsObject var) {
356         super(var);
357     }
358 
359     /**
360      * <p>An <b>opaque</b> static field defining a member that is named by the field name
361      * without a qualifying member and to access the property of the name on an object.</p>
362      * <p>The property, identified by this member, of a {@link JsRange} object 
363      * refers to a read-only boolean value which is <tt>true</tt> if the start and 
364      * the end of the range are at the same point in the document, that is, if the 
365      * range is empty or collapsed.</p> 
366      * @since 1.0
367      * @javascript Re-compilers must resolve the member of this static field to the
368      * identifier of the field name.
369      */
370     public static final Value.Boolean.Member collapsed = new Value.Boolean.Member(Members.collapsed);
371     /**
372      * <p>An <b>opaque</b> static field defining a member that is named by the field name
373      * without a qualifying member and to access the property of the name on an object.</p>
374      * <p>The property, identified by this member, of a {@link JsRange} object is a 
375      * read-only reference to the most deeply nested {@link JsDocument} node that 
376      * contains, that is, is an ancestor of, both the start and end points of the 
377      * range.</p> 
378      * @since 1.0
379      * @javascript Re-compilers must resolve the member of this static field to the
380      * identifier of the field name.
381      */
382     public static final JsNode.Member commonAncestorContainer = new JsNode.Member(Members.commonAncestorContainer);
383     /**
384      * <p>An <b>opaque</b> static field defining a member that is named by the field name
385      * without a qualifying member and to access the property of the name on an object.</p>
386      * <p>The property, identified by this member, of a {@link JsRange} object is a 
387      * read-only reference to the {@link JsDocument} node that contains the end 
388      * point of the range.</p> 
389      * @since 1.0
390      * @javascript Re-compilers must resolve the member of this static field to the
391      * identifier of the field name.
392      */
393     public static final JsNode.Member endContainer = new JsNode.Member(Members.endContainer);
394     /**
395      * <p>An <b>opaque</b> static field defining a member that is named by the field name
396      * without a qualifying member and to access the property of the name on an object.</p>
397      * <p>The property, identified by this member, of a {@link JsRange} object 
398      * refers to a read-only number that specifies the position of the range's 
399      * ending point within {@link #endContainer}.</p> 
400      * @since 1.0
401      * @javascript Re-compilers must resolve the member of this static field to the
402      * identifier of the field name.
403      */
404     public static final Value.Number.Member endOffset = new Value.Number.Member(Members.endOffset);
405     /**
406      * <p>An <b>opaque</b> static field defining a member that is named by the field name
407      * without a qualifying member and to access the property of the name on an object.</p>
408      * <p>The property, identified by this member, of a {@link JsRange} object is a 
409      * read-only reference to the {@link JsDocument} node that contains the starting 
410      * point of the range.</p> 
411      * @since 1.0
412      * @javascript Re-compilers must resolve the member of this static field to the
413      * identifier of the field name.
414      */
415     public static final JsNode.Member startContainer = new JsNode.Member(Members.startContainer);
416     /**
417      * <p>An <b>opaque</b> static field defining a member that is named by the field name
418      * without a qualifying member and to access the property of the name on an object.</p>
419      * <p>The property, identified by this member, of a {@link JsRange} object 
420      * refers to a read-only number that specifies the position of the range's 
421      * starting point within {@link #startContainer}.</p> 
422      * @since 1.0
423      * @javascript Re-compilers must resolve the member of this static field to the
424      * identifier of the field name.
425      */
426     public static final Value.Number.Member startOffset = new Value.Number.Member(Members.startOffset);
427 
428     @Override
429     /**
430      * <p>Returns the primitive value associated with the current instance, if there is one.
431      * This invocation simply returns the instance itself for the current instance is an 
432      * object and there is no primitive value for it.</p>
433      * @return The current object itself.
434      * @since 1.0
435      * @javascript Re-compilers must convert the instance invocation of this method directly
436      * into a JavaScript invocation on its current object instance without changing the 
437      * method name, but expanding variable arguments, if any, into comma-separated values. 
438      */
439     public JsRange valueOf() {
440         return new JsRange((JsObject)var().valueOf());
441     }
442     public final JsNode var(JsNode.Member r) {
443         return r.with(this);
444     }
445 
446     /**
447      * <p>Gets a new {@link JsDocumentFragment} object that contains a copy of the 
448      * document content within this range.</p>
449      * <p>This method duplicates the contents of this range and returns the results in 
450      * a {@link JsDocumentFragment} object.</p>
451      * @return A new {@link JsDocumentFragment} object that contains a copy of the 
452      * region of the document represented by this range.
453      * @throws RuntimeException JavaScript throws a {@link JsDOMException} object with 
454      * the {@link JsDOMException#code} property of the value {@link JsDOMException#HIERARCHY_REQUEST_ERR} 
455      * if this range includes a {@link JsDocumentFragment} node. See {@link Js#err(Object)} 
456      * for JS Simulation.
457      * @since 1.0
458      * @javascript Re-compilers must convert the instance invocation of this method directly
459      * into a JavaScript invocation on its current object instance without changing the 
460      * method name, but expanding variable arguments, if any, into comma-separated values. 
461      */
462     public final JsDocumentFragment cloneContents() {
463         return new JsDocumentFragment(call(cloneContents));
464     }
465     /**
466      * <p>Creates a new {@link JsRange} object that represents the same region of the 
467      * document as this one.</p>
468      * @return A new {@link JsRange} object that has the same boundary points as this 
469      * range.
470      * @since 1.0
471      * @javascript Re-compilers must convert the instance invocation of this method directly
472      * into a JavaScript invocation on its current object instance without changing the 
473      * method name, but expanding variable arguments, if any, into comma-separated values. 
474      */
475     public final JsRange cloneRange() {
476         return new JsRange(call(cloneRange));
477     }
478     /**
479      * <p>Collapses this range so that one boundary point is the same as the other.</p>
480      * <p>This method sets one boundary point of the range to be the same as the other 
481      * point. The point to be modified is specified by the <tt>toStart</tt> argument. 
482      * After this method returns, the range is said to be collapsed: it represents a 
483      * single point within a document and has no content. When a range is collapsed like 
484      * this, its collapsed property is <tt>true</tt>.</p>
485      * @param toStart If this argument is <tt>true</tt>, the method sets the end point 
486      * of the range to the same value as the starting point. Otherwise, it sets the 
487      * starting point to the same value as the end point.
488      * @since 1.0
489      * @javascript Re-compilers must convert the instance invocation of this method directly
490      * into a JavaScript invocation on its current object instance without changing the 
491      * method name, but expanding variable arguments, if any, into comma-separated values. 
492      */
493     public final void collapse(Boolean toStart) {
494         call(collapse, toStart);
495     }
496     /**
497      * <p>Collapses this range so that one boundary point is the same as the other.</p>
498      * <p>This method sets one boundary point of the range to be the same as the other 
499      * point. The point to be modified is specified by the <tt>toStart</tt> argument. 
500      * After this method returns, the range is said to be collapsed: it represents a 
501      * single point within a document and has no content. When a range is collapsed like 
502      * this, its collapsed property is <tt>true</tt>.</p>
503      * @param toStart If this argument is <tt>true</tt>, the method sets the end point 
504      * of the range to the same value as the starting point. Otherwise, it sets the 
505      * starting point to the same value as the end point.
506      * @since 1.0
507      * @javascript Re-compilers must convert the instance invocation of this method directly
508      * into a JavaScript invocation on its current object instance without changing the 
509      * method name, but expanding variable arguments, if any, into comma-separated values. 
510      */
511     public final void collapse(Value<Boolean> toStart) {
512         collapse(Js.valueOf(toStart));
513     }
514     /**
515      * <p>Collapses this range so that one boundary point is the same as the other.</p>
516      * <p>This method sets one boundary point of the range to be the same as the other 
517      * point. The point to be modified is specified by the <tt>toStart</tt> argument. 
518      * After this method returns, the range is said to be collapsed: it represents a 
519      * single point within a document and has no content. When a range is collapsed like 
520      * this, its collapsed property is <tt>true</tt>.</p>
521      * @param toStart If this argument is <tt>true</tt>, the method sets the end point 
522      * of the range to the same value as the starting point. Otherwise, it sets the 
523      * starting point to the same value as the end point.
524      * @since 1.0
525      * @javascript Re-compilers must convert the instance invocation of this method directly
526      * into a JavaScript invocation on its current object instance without changing the 
527      * method name, but expanding variable arguments, if any, into comma-separated values. 
528      */
529     public final void collapse(JsBoolean toStart) {
530         collapse(Js.valueOf(toStart));
531     }
532     /**
533      * <p>Compares a boundary point of the specified range to a boundary point of this 
534      * range and returns -1, 0, or 1 depending on their order, with the first argument, 
535      * which must be one of the static constants defined in this class, defining which 
536      * points to compare.</p>
537      * <p>This method compares a boundary point of this range to a boundary point of the 
538      * specified <tt>sourceRange</tt> and returns a value that specifies their relative 
539      * order in the document source. The <tt>how</tt> argument specifies which boundary 
540      * points of each range are to be compared. The legal values for this argument, and 
541      * their meanings, are as follows:
542      * <ul>
543      * <li>{@link #START_TO_START}: Compares the start points of the two {@link JsRange} nodes.</li>
544      * <li>{@link #END_TO_END}: Compares the end points of the two {@link JsRange} nodes.</li>
545      * <li>{@link #START_TO_END}: Compares the start point of <tt>sourceRange</tt> to the end point of this range.</li>
546      * <li>{@link #END_TO_START}: Compares the end point of <tt>sourceRange</tt> to the start point of this range.</li>
547      * </ul>
548      * </p>
549      * <p>The return value of this method is a number that specifies the relative position of this range to the specified sourceRange. Therefore, you might expect the range constants for the how argument to specify the boundary point for this range first and the boundary point for sourceRange second. Counterintuitively, however, the Range.START_TO_END constant specifies a comparison of the end point of this range with the start point of the specified sourceRange. Similarly, the Range.END_TO_START constant specifies a comparison of the start point of this range with the end point of the specified range</p>
550      * @param how Specifies how to perform the comparison, that is, which boundary points 
551      * to compare. Legal values are the static constants defined by this class. 
552      * @param sourceRange The range that is to be compared to this range. 
553      * @return The value -1 if the specified boundary point of this range is before the 
554      * specified boundary point of <tt>sourceRange</tt>, 0 if the two specified boundary 
555      * points are the same, or 1 if the specified boundary point of this range is after 
556      * the specified boundary point of <tt>sourceRange</tt>.
557      * @throws RuntimeException JavaScript throws a {@link JsDOMException} object with 
558      * the {@link JsDOMException#code} property of the value {@link JsDOMException#WRONG_DOCUMENT_ERR} 
559      * if <tt>sourceRange</tt> represents a range of a different document than this 
560      * range does. See {@link Js#err(Object)} for JS Simulation.
561      * @since 1.0
562      * @javascript Re-compilers must convert the instance invocation of this method directly
563      * into a JavaScript invocation on its current object instance without changing the 
564      * method name, but expanding variable arguments, if any, into comma-separated values. 
565      */
566     public final Number compareBoundaryPoints(Number how, JsRange sourceRange) {
567         return call(compareBoundaryPoints, new Vars<Object>().add(how).add(sourceRange));
568     }
569     /**
570      * <p>Returns a document fragment.</p>
571      * <p>This method takes a string and uses browser's parser to convert it to a DOM 
572      * tree.</p>
573      * <p>This method is not part of a specification. It's from Gecko DOM Reference of MDC.</p>
574      * @param tagString Text that contains text and tags to be converted to a document 
575      * fragment. 
576      * @return The converted document fragment.
577      * @since 1.0
578      * @see JsNode#insertAdjacentHTML(String, String)
579      * @javascript Re-compilers must convert the instance invocation of this method directly
580      * into a JavaScript invocation on its current object instance without changing the 
581      * method name, but expanding variable arguments, if any, into comma-separated values. 
582      */
583     public final JsDocumentFragment createContextualFragment(String tagString) {
584         return new JsDocumentFragment(call(createContextualFragment, tagString));
585     }
586     /**
587      * <p>Returns a document fragment.</p>
588      * <p>This method takes a string and uses browser's parser to convert it to a DOM 
589      * tree.</p>
590      * <p>This method is not part of a specification. It's from Gecko DOM Reference of MDC.</p>
591      * @param tagString Text that contains text and tags to be converted to a document 
592      * fragment. 
593      * @return The converted document fragment.
594      * @since 1.0
595      * @see JsNode#insertAdjacentHTML(String, String)
596      * @javascript Re-compilers must convert the instance invocation of this method directly
597      * into a JavaScript invocation on its current object instance without changing the 
598      * method name, but expanding variable arguments, if any, into comma-separated values. 
599      */
600     public final JsDocumentFragment createContextualFragment(StringLike tagString) {
601         return createContextualFragment(Js.valueOf(tagString));
602     }
603     /**
604      * <p>Deletes the region of the document represented by this range.</p>
605      * <p>This method deletes all document content represented by this range. When it 
606      * returns, the range is collapsed with both boundary points at the start position. 
607      * Note that the deletion may result in adjacent {@link JsText} nodes that can be 
608      * merged with a call to {@link JsNode#normalize()}.</p>
609      * <p>See {@link #cloneContents()} for a way to copy document content and {@link #extractContents()} 
610      * for a way to copy and delete document content in a single operation.</p>
611      * @throws RuntimeException JavaScript throws a {@link JsDOMException} object with 
612      * the {@link JsDOMException#code} property of the value {@link JsDOMException#NO_MODIFICATION_ALLOWED_ERR} 
613      * if any portion of the document that is represented by this range is read-only. 
614      * See {@link Js#err(Object)} for JS Simulation.
615      * @since 1.0
616      * @see JsNode#normalize()
617      * @see #cloneContents()
618      * @see #extractContents()
619      * @javascript Re-compilers must convert the instance invocation of this method directly
620      * into a JavaScript invocation on its current object instance without changing the 
621      * method name, but expanding variable arguments, if any, into comma-separated values. 
622      */
623     public final void deleteContents() {
624         call(deleteContents);
625     }
626     /**
627      * <p>Tells the implementation that this range will no longer be used and that it 
628      * can stop keeping track of it.</p>
629      * <p>If you call this method for a range, subsequent method calls or property 
630      * lookups on that range throw a {@link JsDOMException} error with the {@link JsDOMException#code} 
631      * property of the value {@link JsDOMException#INVALID_STATE_ERR}.</p>
632      * <p>DOM implementations keep track of all {@link JsRange} objects created for a 
633      * document because they may need to change the range boundary points when the 
634      * document is modified. When you are certain that a {@link JsRange} object isn't 
635      * needed any more, call this method to tell the implementation that it no longer 
636      * needs to keep track of that range. Note that once this method has been called 
637      * for a {@link JsRange} object, any use of that range throws an exception. Calling 
638      * this method is not required but may improve performance in some circumstances 
639      * when the document is being modified. A {@link JsRange} object is not subject to 
640      * immediate garbage collection.</p>
641      * @throws RuntimeException JavaScript throws a {@link JsDOMException} object with 
642      * the {@link JsDOMException#code} property of the value {@link JsDOMException#INVALID_STATE_ERR} 
643      * if it is called on a {@link JsRange} object that has already been detached like 
644      * all {@link JsRange} methods. See {@link Js#err(Object)} for JS Simulation.
645      * @since 1.0
646      * @javascript Re-compilers must convert the instance invocation of this method directly
647      * into a JavaScript invocation on its current object instance without changing the 
648      * method name, but expanding variable arguments, if any, into comma-separated values. 
649      */
650     public final void detach() {
651         call(detach);
652     }
653     /**
654      * <p>Deletes the region of the document represented by this range, but returns the 
655      * contents of that region as a {@link JsDocumentFragment} object, like a combination 
656      * of {@link #cloneContents()} and {@link #deleteContents()}.</p>
657      * <p>This method deletes the specified range of a document and returns a {@link JsDocumentFragment} 
658      * node that contains the deleted content. When this method returns, the range is 
659      * collapsed, and the document may contain adjacent {@link JsText} nodes which can 
660      * be merged with {@link JsNode#normalize()}.</p>
661      * @return A {@link JsDocumentFragment} node that contains the contents of this range.
662      * @throws RuntimeException JavaScript throws a {@link JsDOMException} object with 
663      * the {@link JsDOMException#code} property of the value {@link JsDOMException#NO_MODIFICATION_ALLOWED_ERR} 
664      * if any part of the document content to be extracted is read-only or the value {@link JsDOMException#HIERARCHY_REQUEST_ERR} 
665      * if the range contains a {@link JsDocumentType} node. See {@link Js#err(Object)} 
666      * for JS Simulation.
667      * @since 1.0
668      * @see #cloneContents()
669      * @see #extractContents()
670      * @see JsNode#normalize()
671      * @javascript Re-compilers must convert the instance invocation of this method directly
672      * into a JavaScript invocation on its current object instance without changing the 
673      * method name, but expanding variable arguments, if any, into comma-separated values. 
674      */
675     public final JsDocumentFragment extractContents() {
676         return new JsDocumentFragment(call(extractContents));
677     }
678     /**
679      * <p>Inserts the specified node into the document at the start point of the range.</p>
680      * <p>This method inserts the specified node and all its descendants into the document 
681      * at the start position of this range. When it returns, this range includes the 
682      * newly inserted node. If <tt>newNode</tt> is already part of the document, it is 
683      * removed from its current position and then reinserted at the start of the range. 
684      * If <tt>newNode</tt> is a {@link JsDocumentFragment} node, it is not inserted 
685      * itself, but all of its children are inserted, in order, at the start of the range</p>
686      * <p>If the node that contains the start of the range is a {@link JsText} node, it 
687      * is split into two adjacent nodes before the insertion takes place. If <tt>newNode</tt> 
688      * is a {@link JsText} node, it is not merged with any adjacent {@link JsText} nodes 
689      * after it is inserted. To merge adjacent {@link JsText} nodes, call {@link JsNode#normalize()}.</p>
690      * @param newNode The node to be inserted into the document.
691      * @throws RuntimeException JavaScript throws a {@link JsRangeException} object with 
692      * the {@link JsRangeException#code} property of the value {@link JsRangeException#INVALID_NODE_TYPE_ERR} 
693      * if <tt>newNode</tt> is an {@link JsAttr}, {@link JsDocument}, {@link JsEntity}, or {@link JsNotation} 
694      * node, or a {@link JsDOMException} object with the {@link JsDOMException#code} 
695      * property of the value {@link JsDOMException#HIERARCHY_REQUEST_ERR} if the node 
696      * that contains the start of the range does not allow children, it does not allow 
697      * children of the specified type, or <tt>newNode</tt> is an ancestor of that node, 
698      * the value {@link JsDOMException#NO_MODIFICATION_ALLOWED_ERR} if the node that 
699      * contains the start of the range or any of its ancestors is read-only, or the 
700      * value {@link JsDOMException#WRONG_DOCUMENT_ERR} if <tt>newNode</tt> is part of a 
701      * different document than the range is. See {@link Js#err(Object)} for JS Simulation.
702      * @since 1.0
703      * @see JsNode#normalize()
704      * @javascript Re-compilers must convert the instance invocation of this method directly
705      * into a JavaScript invocation on its current object instance without changing the 
706      * method name, but expanding variable arguments, if any, into comma-separated values. 
707      */
708     public final void insertNode(JsNode newNode) {
709         call(insertNode, newNode);
710     }
711     /**
712      * <p>Sets the boundary points of this range so that it contains the specified node 
713      * and all of its descendants.</p>
714      * <p>This method sets the contents of this range to the specified <tt>refNode</tt>, 
715      * that is, it selects the node and its descendants.</p>
716      * @param refNode The node to be selected, that is, the node that is to become the 
717      * content of this range.
718      * @throws RuntimeException JavaScript throws a {@link JsRangeException} object with 
719      * the {@link JsRangeException#code} property of the value {@link JsRangeException#INVALID_NODE_TYPE_ERR} 
720      * if <tt>refNode</tt> is an {@link JsAttr}, {@link JsDocument}, or {@link JsDocumentFragment} 
721      * node, or a {@link JsDOMException} object with the {@link JsDOMException#code} 
722      * property of the value {@link JsDOMException#WRONG_DOCUMENT_ERR} if <tt>refNode</tt> 
723      * is part of a different document than the one through which this range was created. 
724      * See {@link Js#err(Object)} for JS Simulation.
725      * @since 1.0
726      * @see #selectNodeContents(JsNode)
727      * @javascript Re-compilers must convert the instance invocation of this method directly
728      * into a JavaScript invocation on its current object instance without changing the 
729      * method name, but expanding variable arguments, if any, into comma-separated values. 
730      */
731     public final void selectNode(JsNode refNode) {
732         call(selectNode, refNode);
733     }
734     /**
735      * <p>Sets the boundary points of this range so that it contains all the descendants 
736      * of the specified node but not the node itself.</p>
737      * <p>This method sets the boundary points of this range so that the range contains 
738      * the children of <tt>refNode</tt>.</p>
739      * @param refNode The node whose children are to become the contents of this range.
740      * @throws RuntimeException JavaScript throws a {@link JsRangeException} object with 
741      * the {@link JsRangeException#code} property of the value {@link JsRangeException#INVALID_NODE_TYPE_ERR} 
742      * if <tt>refNode</tt> or one of its ancestors is a {@link JsDocumentType}, {@link JsEntity}, 
743      * or {@link JsNotation} node, or a {@link JsDOMException} object with the {@link JsDOMException#code} 
744      * property of the value {@link JsDOMException#WRONG_DOCUMENT_ERR} if <tt>refNode</tt> 
745      * is part of a different document than the one through which this range was created. 
746      * See {@link Js#err(Object)} for JS Simulation.
747      * @since 1.0
748      * @see #selectNode(JsNode)
749      * @javascript Re-compilers must convert the instance invocation of this method directly
750      * into a JavaScript invocation on its current object instance without changing the 
751      * method name, but expanding variable arguments, if any, into comma-separated values. 
752      */
753     public final void selectNodeContents(JsNode refNode) {
754         call(selectNodeContents, refNode);
755     }
756     /**
757      * <p>Sets the end point of this range to immediately after the specified node.</p>
758      * <p>This method sets the end point of a range by specifying the values of the 
759      * {@link #endContainer} and {@link #endOffset} properties.</p>
760      * @param refNode The node that contains the new end point.
761      * @param offset The position of the end point within <tt>refNode</tt>.
762      * @throws RuntimeException JavaScript throws a {@link JsRangeException} object with 
763      * the {@link JsRangeException#code} property of the value {@link JsRangeException#INVALID_NODE_TYPE_ERR} 
764      * if <tt>refNode</tt> or one of its ancestors is a {@link JsDocumentType} node, or 
765      * a {@link JsDOMException} object with the {@link JsDOMException#code} property of 
766      * the value {@link JsDOMException#WRONG_DOCUMENT_ERR} if <tt>refNode</tt> is part 
767      * of a different document than the one through which this range was created or the 
768      * value {@link JsDOMException#INDEX_SIZE_ERR} if <tt>offset</tt> is negative or is 
769      * greater than the number of children or characters in <tt>refNode</tt>. 
770      * See {@link Js#err(Object)} for JS Simulation.
771      * @since 1.0
772      * @javascript Re-compilers must convert the instance invocation of this method directly
773      * into a JavaScript invocation on its current object instance without changing the 
774      * method name, but expanding variable arguments, if any, into comma-separated values. 
775      */
776     public final void setEnd(JsNode refNode, Number offset) {
777         call(setEnd, new Vars<Object>().add(refNode).add(offset));
778     }
779     /**
780      * <p>Sets the end point of this range to immediately after the specified node.</p>
781      * <p>This method sets the end point of this range to fall immediately after the 
782      * specified <tt>refNode</tt>.</p>
783      * @param refNode The node after which the end point of the range is to be set.
784      * @throws RuntimeException JavaScript throws a {@link JsRangeException} object with 
785      * the {@link JsRangeException#code} property of the value {@link JsRangeException#INVALID_NODE_TYPE_ERR} 
786      * if <tt>refNode</tt> is a {@link JsAttr}, {@link JsDocument} or {@link JsDocumentType} 
787      * node, or the root container of <tt>refNode</tt> is not a {@link JsAttr}, {@link JsDocument} 
788      * or {@link JsDocumentType} node, or a {@link JsDOMException} object with the {@link JsDOMException#code} 
789      * property of the value {@link JsDOMException#WRONG_DOCUMENT_ERR} if <tt>refNode</tt> 
790      * is part of a different document than the one through which this range was created. 
791      * See {@link Js#err(Object)} for JS Simulation.
792      * @since 1.0
793      * @javascript Re-compilers must convert the instance invocation of this method directly
794      * into a JavaScript invocation on its current object instance without changing the 
795      * method name, but expanding variable arguments, if any, into comma-separated values. 
796      */
797     public final void setEndAfter(JsNode refNode) {
798         call(setEndAfter, refNode);
799     }
800     /**
801      * <p>Sets the end point of this range to immediately before the specified node.</p>
802      * <p>This method sets the end point of this range to fall immediately before the 
803      * specified <tt>refNode</tt>.</p>
804      * @param refNode The node before which the end point of the range is to be set.
805      * @throws RuntimeException JavaScript throws a {@link JsRangeException} object with 
806      * the {@link JsRangeException#code} property of the value {@link JsRangeException#INVALID_NODE_TYPE_ERR} 
807      * if <tt>refNode</tt> is a {@link JsAttr}, {@link JsDocument} or {@link JsDocumentType} 
808      * node, or the root container of <tt>refNode</tt> is not a {@link JsAttr}, {@link JsDocument} 
809      * or {@link JsDocumentType} node, or a {@link JsDOMException} object with the {@link JsDOMException#code} 
810      * property of the value {@link JsDOMException#WRONG_DOCUMENT_ERR} if <tt>refNode</tt> 
811      * is part of a different document than the one through which this range was created. 
812      * See {@link Js#err(Object)} for JS Simulation.
813      * @since 1.0
814      * @javascript Re-compilers must convert the instance invocation of this method directly
815      * into a JavaScript invocation on its current object instance without changing the 
816      * method name, but expanding variable arguments, if any, into comma-separated values. 
817      */
818     public final void setEndBefore(JsNode refNode) {
819         call(setEndBefore, refNode);
820     }
821     /**
822      * <p>Sets the start position of this range to the specified offset within the specified node.</p>
823      * <p>This method sets the end point of a range by specifying the values of the 
824      * {@link #startContainer} and {@link #startOffset} properties.</p>
825      * @param refNode The node that contains the new start point.
826      * @param offset The position of the end point within <tt>refNode</tt>.
827      * @throws RuntimeException JavaScript throws a {@link JsRangeException} object with 
828      * the {@link JsRangeException#code} property of the value {@link JsRangeException#INVALID_NODE_TYPE_ERR} 
829      * if <tt>refNode</tt> or one of its ancestors is a {@link JsDocumentType} node, or 
830      * a {@link JsDOMException} object with the {@link JsDOMException#code} property of 
831      * the value {@link JsDOMException#WRONG_DOCUMENT_ERR} if <tt>refNode</tt> is part 
832      * of a different document than the one through which this range was created or the 
833      * value {@link JsDOMException#INDEX_SIZE_ERR} if <tt>offset</tt> is negative or is 
834      * greater than the number of children or characters in <tt>refNode</tt>. 
835      * See {@link Js#err(Object)} for JS Simulation.
836      * @since 1.0
837      * @javascript Re-compilers must convert the instance invocation of this method directly
838      * into a JavaScript invocation on its current object instance without changing the 
839      * method name, but expanding variable arguments, if any, into comma-separated values. 
840      */
841     public final void setStart(JsNode refNode, Number offset) {
842         call(setStart, new Vars<Object>().add(refNode).add(offset));
843     }
844     /**
845      * <p>Sets the start position of this range to immediately after the specified node.</p>
846      * <p>This method sets the start point of this range to fall immediately after the 
847      * specified <tt>refNode</tt>.</p>
848      * @param refNode The node after which the start point of the range is to be set.
849      * @throws RuntimeException JavaScript throws a {@link JsRangeException} object with 
850      * the {@link JsRangeException#code} property of the value {@link JsRangeException#INVALID_NODE_TYPE_ERR} 
851      * if <tt>refNode</tt> is a {@link JsAttr}, {@link JsDocument} or {@link JsDocumentType} 
852      * node, or the root container of <tt>refNode</tt> is not a {@link JsAttr}, {@link JsDocument} 
853      * or {@link JsDocumentType} node, or a {@link JsDOMException} object with the {@link JsDOMException#code} 
854      * property of the value {@link JsDOMException#WRONG_DOCUMENT_ERR} if <tt>refNode</tt> 
855      * is part of a different document than the one through which this range was created. 
856      * See {@link Js#err(Object)} for JS Simulation.
857      * @since 1.0
858      * @javascript Re-compilers must convert the instance invocation of this method directly
859      * into a JavaScript invocation on its current object instance without changing the 
860      * method name, but expanding variable arguments, if any, into comma-separated values. 
861      */
862     public final void setStartAfter(JsNode refNode) {
863         call(setStartAfter, refNode);
864     }
865     /**
866      * <p>Sets the start position of this range to immediately before the specified node.</p>
867      * <p>This method sets the start point of this range to fall immediately before the 
868      * specified <tt>refNode</tt>.</p>
869      * @param refNode The node before which the start point of the range is to be set.
870      * @throws RuntimeException JavaScript throws a {@link JsRangeException} object with 
871      * the {@link JsRangeException#code} property of the value {@link JsRangeException#INVALID_NODE_TYPE_ERR} 
872      * if <tt>refNode</tt> is a {@link JsAttr}, {@link JsDocument} or {@link JsDocumentType} 
873      * node, or the root container of <tt>refNode</tt> is not a {@link JsAttr}, {@link JsDocument} 
874      * or {@link JsDocumentType} node, or a {@link JsDOMException} object with the {@link JsDOMException#code} 
875      * property of the value {@link JsDOMException#WRONG_DOCUMENT_ERR} if <tt>refNode</tt> 
876      * is part of a different document than the one through which this range was created. 
877      * See {@link Js#err(Object)} for JS Simulation.
878      * @since 1.0
879      * @javascript Re-compilers must convert the instance invocation of this method directly
880      * into a JavaScript invocation on its current object instance without changing the 
881      * method name, but expanding variable arguments, if any, into comma-separated values. 
882      */
883     public final void setStartBefore(JsNode refNode) {
884         call(setStartBefore, refNode);
885     }
886     /**
887      * <p>Inserts the specified node into the document at the start position of the 
888      * range and then re-parents all the nodes within the range so that they become 
889      * descendants of the newly inserted node.</p>
890      * <p>This method re-parents the contents of this range to <tt>newParent</tt> and 
891      * then inserts <tt>newParent</tt> into the document at the start position of the 
892      * range. It is useful to place a region of document content within a <tt>&lt;div&gt;</tt> 
893      * or <tt>&lt;span&gt;</tt> element.</p>
894      * <p>If <tt>newParent</tt>  is already part of the document, it is first removed 
895      * from the document, and any children it has are discarded. When this method 
896      * returns, this range begins immediately before <tt>newParent</tt>  and ends 
897      * immediately after it.</p>
898      * @param newParent The node that is to become the new parent of the contents of 
899      * this range.
900      * @throws RuntimeException JavaScript throws a {@link JsRangeException} object with 
901      * the {@link JsRangeException#code} property of the value {@link JsRangeException#INVALID_NODE_TYPE_ERR} 
902      * if <tt>newParent</tt> is a {@link JsAttr}, {@link JsDocument}, {@link JsDocumentFragment}, 
903      * {@link JsDocumentType}, {@link JsEntity}, {@link JsNotation} node, or the value {@link JsRangeException#BAD_BOUNDARYPOINTS_ERR} 
904      * if the range partially selects a node other than a {@link JsText} node, so the 
905      * region of the document it represents cannot be surrounded, or a {@link JsDOMException} 
906      * object with the {@link JsDOMException#code} property of the value {@link JsDOMException#WRONG_DOCUMENT_ERR} 
907      * if <tt>newParent</tt> and this range were created using different {@link JsDocument} 
908      * objects, the value {@link JsDOMException#NO_MODIFICATION_ALLOWED_ERR} if an 
909      * ancestor of a boundary point of the range is read-only and does not allow 
910      * insertions, or the value {@link JsDOMException#HIERARCHY_REQUEST_ERR} if the 
911      * container node of the start of the range does not allow children or does not 
912      * allow children of the type of <tt>newParent</tt> or <tt>newParent</tt> is an 
913      * ancestor of that container node. See {@link Js#err(Object)} for JS Simulation.
914      * @javascript Re-compilers must convert the instance invocation of this method directly
915      * into a JavaScript invocation on its current object instance without changing the 
916      * method name, but expanding variable arguments, if any, into comma-separated values. 
917      */
918     public final void surroundContents(JsNode newParent) {
919         call(surroundContents, newParent);
920     }
921 }