Source for org.w3c.dom.ranges.Range

   1: /*
   2:  * Copyright (c) 2000 World Wide Web Consortium,
   3:  * (Massachusetts Institute of Technology, Institut National de
   4:  * Recherche en Informatique et en Automatique, Keio University). All
   5:  * Rights Reserved. This program is distributed under the W3C's Software
   6:  * Intellectual Property License. This program is distributed in the
   7:  * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
   8:  * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
   9:  * PURPOSE.
  10:  * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
  11:  */
  12: 
  13: package org.w3c.dom.ranges;
  14: 
  15: import org.w3c.dom.Node;
  16: import org.w3c.dom.DOMException;
  17: import org.w3c.dom.DocumentFragment;
  18: 
  19: /**
  20:  * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>Document Object Model (DOM) Level 2 Traversal and Range Specification</a>.
  21:  * @since DOM Level 2
  22:  */
  23: public interface Range {
  24:     /**
  25:      * Node within which the Range begins
  26:      * @exception DOMException
  27:      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  28:      *   invoked on this object.
  29:      */
  30:     public Node getStartContainer()
  31:                        throws DOMException;
  32: 
  33:     /**
  34:      * Offset within the starting node of the Range.
  35:      * @exception DOMException
  36:      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  37:      *   invoked on this object.
  38:      */
  39:     public int getStartOffset()
  40:                        throws DOMException;
  41: 
  42:     /**
  43:      * Node within which the Range ends
  44:      * @exception DOMException
  45:      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  46:      *   invoked on this object.
  47:      */
  48:     public Node getEndContainer()
  49:                        throws DOMException;
  50: 
  51:     /**
  52:      * Offset within the ending node of the Range.
  53:      * @exception DOMException
  54:      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  55:      *   invoked on this object.
  56:      */
  57:     public int getEndOffset()
  58:                        throws DOMException;
  59: 
  60:     /**
  61:      * TRUE if the Range is collapsed
  62:      * @exception DOMException
  63:      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  64:      *   invoked on this object.
  65:      */
  66:     public boolean getCollapsed()
  67:                        throws DOMException;
  68: 
  69:     /**
  70:      * The deepest common ancestor container of the Range's two
  71:      * boundary-points.
  72:      * @exception DOMException
  73:      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  74:      *   invoked on this object.
  75:      */
  76:     public Node getCommonAncestorContainer()
  77:                        throws DOMException;
  78: 
  79:     /**
  80:      * Sets the attributes describing the start of the Range.
  81:      * @param refNode The <code>refNode</code> value. This parameter must be
  82:      *   different from <code>null</code>.
  83:      * @param offset The <code>startOffset</code> value.
  84:      * @exception RangeException
  85:      *   INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor
  86:      *   of <code>refNode</code> is an Entity, Notation, or DocumentType
  87:      *   node.
  88:      * @exception DOMException
  89:      *   INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater
  90:      *   than the number of child units in <code>refNode</code>. Child units
  91:      *   are 16-bit units if <code>refNode</code> is a type of CharacterData
  92:      *   node (e.g., a Text or Comment node) or a ProcessingInstruction
  93:      *   node. Child units are Nodes in all other cases.
  94:      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
  95:      *   been invoked on this object.
  96:      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
  97:      *   from a different document than the one that created this range.
  98:      */
  99:     public void setStart(Node refNode,
 100:                          int offset)
 101:                          throws RangeException, DOMException;
 102: 
 103:     /**
 104:      * Sets the attributes describing the end of a Range.
 105:      * @param refNode The <code>refNode</code> value. This parameter must be
 106:      *   different from <code>null</code>.
 107:      * @param offset The <code>endOffset</code> value.
 108:      * @exception RangeException
 109:      *   INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor
 110:      *   of <code>refNode</code> is an Entity, Notation, or DocumentType
 111:      *   node.
 112:      * @exception DOMException
 113:      *   INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater
 114:      *   than the number of child units in <code>refNode</code>. Child units
 115:      *   are 16-bit units if <code>refNode</code> is a type of CharacterData
 116:      *   node (e.g., a Text or Comment node) or a ProcessingInstruction
 117:      *   node. Child units are Nodes in all other cases.
 118:      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
 119:      *   been invoked on this object.
 120:      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
 121:      *   from a different document than the one that created this range.
 122:      */
 123:     public void setEnd(Node refNode,
 124:                        int offset)
 125:                        throws RangeException, DOMException;
 126: 
 127:     /**
 128:      * Sets the start position to be before a node
 129:      * @param refNode Range starts before <code>refNode</code>
 130:      * @exception RangeException
 131:      *   INVALID_NODE_TYPE_ERR: Raised if the root container of
 132:      *   <code>refNode</code> is not an Attr, Document, or DocumentFragment
 133:      *   node or if <code>refNode</code> is a Document, DocumentFragment,
 134:      *   Attr, Entity, or Notation node.
 135:      * @exception DOMException
 136:      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 137:      *   invoked on this object.
 138:      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
 139:      *   from a different document than the one that created this range.
 140:      */
 141:     public void setStartBefore(Node refNode)
 142:                                throws RangeException, DOMException;
 143: 
 144:     /**
 145:      * Sets the start position to be after a node
 146:      * @param refNode Range starts after <code>refNode</code>
 147:      * @exception RangeException
 148:      *   INVALID_NODE_TYPE_ERR: Raised if the root container of
 149:      *   <code>refNode</code> is not an Attr, Document, or DocumentFragment
 150:      *   node or if <code>refNode</code> is a Document, DocumentFragment,
 151:      *   Attr, Entity, or Notation node.
 152:      * @exception DOMException
 153:      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 154:      *   invoked on this object.
 155:      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
 156:      *   from a different document than the one that created this range.
 157:      */
 158:     public void setStartAfter(Node refNode)
 159:                               throws RangeException, DOMException;
 160: 
 161:     /**
 162:      * Sets the end position to be before a node.
 163:      * @param refNode Range ends before <code>refNode</code>
 164:      * @exception RangeException
 165:      *   INVALID_NODE_TYPE_ERR: Raised if the root container of
 166:      *   <code>refNode</code> is not an Attr, Document, or DocumentFragment
 167:      *   node or if <code>refNode</code> is a Document, DocumentFragment,
 168:      *   Attr, Entity, or Notation node.
 169:      * @exception DOMException
 170:      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 171:      *   invoked on this object.
 172:      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
 173:      *   from a different document than the one that created this range.
 174:      */
 175:     public void setEndBefore(Node refNode)
 176:                              throws RangeException, DOMException;
 177: 
 178:     /**
 179:      * Sets the end of a Range to be after a node
 180:      * @param refNode Range ends after <code>refNode</code>.
 181:      * @exception RangeException
 182:      *   INVALID_NODE_TYPE_ERR: Raised if the root container of
 183:      *   <code>refNode</code> is not an Attr, Document or DocumentFragment
 184:      *   node or if <code>refNode</code> is a Document, DocumentFragment,
 185:      *   Attr, Entity, or Notation node.
 186:      * @exception DOMException
 187:      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 188:      *   invoked on this object.
 189:      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
 190:      *   from a different document than the one that created this range.
 191:      */
 192:     public void setEndAfter(Node refNode)
 193:                             throws RangeException, DOMException;
 194: 
 195:     /**
 196:      * Collapse a Range onto one of its boundary-points
 197:      * @param toStart If TRUE, collapses the Range onto its start; if FALSE,
 198:      *   collapses it onto its end.
 199:      * @exception DOMException
 200:      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 201:      *   invoked on this object.
 202:      */
 203:     public void collapse(boolean toStart)
 204:                          throws DOMException;
 205: 
 206:     /**
 207:      * Select a node and its contents
 208:      * @param refNode The node to select.
 209:      * @exception RangeException
 210:      *   INVALID_NODE_TYPE_ERR: Raised if an ancestor of <code>refNode</code>
 211:      *   is an Entity, Notation or DocumentType node or if
 212:      *   <code>refNode</code> is a Document, DocumentFragment, Attr, Entity,
 213:      *   or Notation node.
 214:      * @exception DOMException
 215:      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 216:      *   invoked on this object.
 217:      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
 218:      *   from a different document than the one that created this range.
 219:      */
 220:     public void selectNode(Node refNode)
 221:                            throws RangeException, DOMException;
 222: 
 223:     /**
 224:      * Select the contents within a node
 225:      * @param refNode Node to select from
 226:      * @exception RangeException
 227:      *   INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor
 228:      *   of <code>refNode</code> is an Entity, Notation or DocumentType node.
 229:      * @exception DOMException
 230:      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 231:      *   invoked on this object.
 232:      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
 233:      *   from a different document than the one that created this range.
 234:      */
 235:     public void selectNodeContents(Node refNode)
 236:                                    throws RangeException, DOMException;
 237: 
 238:     // CompareHow
 239:     /**
 240:      * Compare start boundary-point of <code>sourceRange</code> to start
 241:      * boundary-point of Range on which <code>compareBoundaryPoints</code>
 242:      * is invoked.
 243:      */
 244:     public static final short START_TO_START            = 0;
 245:     /**
 246:      * Compare start boundary-point of <code>sourceRange</code> to end
 247:      * boundary-point of Range on which <code>compareBoundaryPoints</code>
 248:      * is invoked.
 249:      */
 250:     public static final short START_TO_END              = 1;
 251:     /**
 252:      * Compare end boundary-point of <code>sourceRange</code> to end
 253:      * boundary-point of Range on which <code>compareBoundaryPoints</code>
 254:      * is invoked.
 255:      */
 256:     public static final short END_TO_END                = 2;
 257:     /**
 258:      * Compare end boundary-point of <code>sourceRange</code> to start
 259:      * boundary-point of Range on which <code>compareBoundaryPoints</code>
 260:      * is invoked.
 261:      */
 262:     public static final short END_TO_START              = 3;
 263: 
 264:     /**
 265:      * Compare the boundary-points of two Ranges in a document.
 266:      * @param how A code representing the type of comparison, as defined
 267:      *   above.
 268:      * @param sourceRange The <code>Range</code> on which this current
 269:      *   <code>Range</code> is compared to.
 270:      * @return  -1, 0 or 1 depending on whether the corresponding
 271:      *   boundary-point of the Range is respectively before, equal to, or
 272:      *   after the corresponding boundary-point of <code>sourceRange</code>.
 273:      * @exception DOMException
 274:      *   WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same
 275:      *   Document or DocumentFragment.
 276:      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
 277:      *   been invoked on this object.
 278:      */
 279:     public short compareBoundaryPoints(short how,
 280:                                        Range sourceRange)
 281:                                        throws DOMException;
 282: 
 283:     /**
 284:      * Removes the contents of a Range from the containing document or
 285:      * document fragment without returning a reference to the removed
 286:      * content.
 287:      * @exception DOMException
 288:      *   NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of
 289:      *   the Range is read-only or any of the nodes that contain any of the
 290:      *   content of the Range are read-only.
 291:      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
 292:      *   been invoked on this object.
 293:      */
 294:     public void deleteContents()
 295:                                throws DOMException;
 296: 
 297:     /**
 298:      * Moves the contents of a Range from the containing document or document
 299:      * fragment to a new DocumentFragment.
 300:      * @return A DocumentFragment containing the extracted contents.
 301:      * @exception DOMException
 302:      *   NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of
 303:      *   the Range is read-only or any of the nodes which contain any of the
 304:      *   content of the Range are read-only.
 305:      *   <br>HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be
 306:      *   extracted into the new DocumentFragment.
 307:      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
 308:      *   been invoked on this object.
 309:      */
 310:     public DocumentFragment extractContents()
 311:                                             throws DOMException;
 312: 
 313:     /**
 314:      * Duplicates the contents of a Range
 315:      * @return A DocumentFragment that contains content equivalent to this
 316:      *   Range.
 317:      * @exception DOMException
 318:      *   HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be
 319:      *   extracted into the new DocumentFragment.
 320:      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
 321:      *   been invoked on this object.
 322:      */
 323:     public DocumentFragment cloneContents()
 324:                                           throws DOMException;
 325: 
 326:     /**
 327:      * Inserts a node into the Document or DocumentFragment at the start of
 328:      * the Range. If the container is a Text node, this will be split at the
 329:      * start of the Range (as if the Text node's splitText method was
 330:      * performed at the insertion point) and the insertion will occur
 331:      * between the two resulting Text nodes. Adjacent Text nodes will not be
 332:      * automatically merged. If the node to be inserted is a
 333:      * DocumentFragment node, the children will be inserted rather than the
 334:      * DocumentFragment node itself.
 335:      * @param newNode The node to insert at the start of the Range
 336:      * @exception DOMException
 337:      *   NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of the
 338:      *   start of the Range is read-only.
 339:      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>newNode</code> and the
 340:      *   container of the start of the Range were not created from the same
 341:      *   document.
 342:      *   <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of
 343:      *   the Range is of a type that does not allow children of the type of
 344:      *   <code>newNode</code> or if <code>newNode</code> is an ancestor of
 345:      *   the container.
 346:      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
 347:      *   been invoked on this object.
 348:      * @exception RangeException
 349:      *   INVALID_NODE_TYPE_ERR: Raised if <code>newNode</code> is an Attr,
 350:      *   Entity, Notation, or Document node.
 351:      */
 352:     public void insertNode(Node newNode)
 353:                            throws DOMException, RangeException;
 354: 
 355:     /**
 356:      * Reparents the contents of the Range to the given node and inserts the
 357:      * node at the position of the start of the Range.
 358:      * @param newParent The node to surround the contents with.
 359:      * @exception DOMException
 360:      *   NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of
 361:      *   either boundary-point of the Range is read-only.
 362:      *   <br>WRONG_DOCUMENT_ERR: Raised if <code> newParent</code> and the
 363:      *   container of the start of the Range were not created from the same
 364:      *   document.
 365:      *   <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of
 366:      *   the Range is of a type that does not allow children of the type of
 367:      *   <code>newParent</code> or if <code>newParent</code> is an ancestor
 368:      *   of the container or if <code>node</code> would end up with a child
 369:      *   node of a type not allowed by the type of <code>node</code>.
 370:      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
 371:      *   been invoked on this object.
 372:      * @exception RangeException
 373:      *   BAD_BOUNDARYPOINTS_ERR: Raised if the Range partially selects a
 374:      *   non-text node.
 375:      *   <br>INVALID_NODE_TYPE_ERR: Raised if <code> node</code> is an Attr,
 376:      *   Entity, DocumentType, Notation, Document, or DocumentFragment node.
 377:      */
 378:     public void surroundContents(Node newParent)
 379:                                  throws DOMException, RangeException;
 380: 
 381:     /**
 382:      * Produces a new Range whose boundary-points are equal to the
 383:      * boundary-points of the Range.
 384:      * @return The duplicated Range.
 385:      * @exception DOMException
 386:      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 387:      *   invoked on this object.
 388:      */
 389:     public Range cloneRange()
 390:                             throws DOMException;
 391: 
 392:     /**
 393:      * Returns the contents of a Range as a string. This string contains only
 394:      * the data characters, not any markup.
 395:      * @return The contents of the Range.
 396:      * @exception DOMException
 397:      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 398:      *   invoked on this object.
 399:      */
 400:     public String toString()
 401:                            throws DOMException;
 402: 
 403:     /**
 404:      * Called to indicate that the Range is no longer in use and that the
 405:      * implementation may relinquish any resources associated with this
 406:      * Range. Subsequent calls to any methods or attribute getters on this
 407:      * Range will result in a <code>DOMException</code> being thrown with an
 408:      * error code of <code>INVALID_STATE_ERR</code>.
 409:      * @exception DOMException
 410:      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 411:      *   invoked on this object.
 412:      */
 413:     public void detach()
 414:                        throws DOMException;
 415: 
 416: }