1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 /* 19 * $Id: DOMRange.hpp 932887 2010-04-11 13:04:59Z borisk $ 20 */ 21 22 #if !defined(XERCESC_INCLUDE_GUARD_DOMRANGE_HPP) 23 #define XERCESC_INCLUDE_GUARD_DOMRANGE_HPP 24 25 #include <xercesc/util/XercesDefs.hpp> 26 27 XERCES_CPP_NAMESPACE_BEGIN 28 29 class DOMNode; 30 class DOMDocumentFragment; 31 32 /** 33 * <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>. 34 * @since DOM Level 2 35 */ 36 class CDOM_EXPORT DOMRange { 37 protected: 38 // ----------------------------------------------------------------------- 39 // Hidden constructors 40 // ----------------------------------------------------------------------- 41 /** @name Hidden constructors */ 42 //@{ DOMRange()43 DOMRange() {} DOMRange(const DOMRange &)44 DOMRange(const DOMRange &) {} 45 //@} 46 47 private: 48 // ----------------------------------------------------------------------- 49 // Unimplemented constructors and operators 50 // ----------------------------------------------------------------------- 51 /** @name Unimplemented operators */ 52 //@{ 53 DOMRange & operator = (const DOMRange &); 54 //@} 55 56 public: 57 // ----------------------------------------------------------------------- 58 // All constructors are hidden, just the destructor is available 59 // ----------------------------------------------------------------------- 60 /** @name Destructor */ 61 //@{ 62 /** 63 * Destructor 64 * 65 */ ~DOMRange()66 virtual ~DOMRange() {}; 67 //@} 68 69 // ----------------------------------------------------------------------- 70 // Class Types 71 // ----------------------------------------------------------------------- 72 /** @name Public Constants */ 73 //@{ 74 /** 75 * Constants CompareHow. 76 * 77 * <p><code>START_TO_START:</code> 78 * Compare start boundary-point of <code>sourceRange</code> to start 79 * boundary-point of Range on which <code>compareBoundaryPoints</code> 80 * is invoked.</p> 81 * 82 * <p><code>START_TO_END:</code> 83 * Compare start boundary-point of <code>sourceRange</code> to end 84 * boundary-point of Range on which <code>compareBoundaryPoints</code> 85 * is invoked.</p> 86 * 87 * <p><code>END_TO_END:</code> 88 * Compare end boundary-point of <code>sourceRange</code> to end 89 * boundary-point of Range on which <code>compareBoundaryPoints</code> 90 * is invoked.</p> 91 * 92 * <p><code>END_TO_START:</code> 93 * Compare end boundary-point of <code>sourceRange</code> to start 94 * boundary-point of Range on which <code>compareBoundaryPoints</code> 95 * is invoked.</p> 96 * 97 * @since DOM Level 2 98 */ 99 enum CompareHow { 100 START_TO_START = 0, 101 START_TO_END = 1, 102 END_TO_END = 2, 103 END_TO_START = 3 104 }; 105 106 //@} 107 108 // ----------------------------------------------------------------------- 109 // Virtual DOMRange interface 110 // ----------------------------------------------------------------------- 111 /** @name Functions introduced in DOM Level 2 */ 112 //@{ 113 // ----------------------------------------------------------------------- 114 // Getter methods 115 // ----------------------------------------------------------------------- 116 /** 117 * DOMNode within which the Range begins 118 * @exception DOMException 119 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 120 * invoked on this object. 121 * 122 * @since DOM Level 2 123 */ 124 virtual DOMNode* getStartContainer() const = 0; 125 126 /** 127 * Offset within the starting node of the Range. 128 * @exception DOMException 129 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 130 * invoked on this object. 131 * 132 * @since DOM Level 2 133 */ 134 virtual XMLSize_t getStartOffset() const = 0; 135 136 /** 137 * DOMNode within which the Range ends 138 * @exception DOMException 139 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 140 * invoked on this object. 141 * 142 * @since DOM Level 2 143 */ 144 virtual DOMNode* getEndContainer() const = 0; 145 146 /** 147 * Offset within the ending node of the Range. 148 * @exception DOMException 149 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 150 * invoked on this object. 151 * 152 * @since DOM Level 2 153 */ 154 virtual XMLSize_t getEndOffset() const = 0; 155 156 /** 157 * TRUE if the Range is collapsed 158 * @exception DOMException 159 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 160 * invoked on this object. 161 * 162 * @since DOM Level 2 163 */ 164 virtual bool getCollapsed() const = 0; 165 166 /** 167 * The deepest common ancestor container of the Range's two 168 * boundary-points. 169 * @exception DOMException 170 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 171 * invoked on this object. 172 * 173 * @since DOM Level 2 174 */ 175 virtual const DOMNode* getCommonAncestorContainer() const = 0; 176 177 // ----------------------------------------------------------------------- 178 // Setter methods 179 // ----------------------------------------------------------------------- 180 /** 181 * Sets the attributes describing the start of the Range. 182 * @param refNode The <code>refNode</code> value. This parameter must be 183 * different from <code>null</code>. 184 * @param offset The <code>startOffset</code> value. 185 * @exception DOMRangeException 186 * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor 187 * of <code>refNode</code> is an DOMEntity, DOMNotation, or DOMDocumentType 188 * node. 189 * @exception DOMException 190 * INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater 191 * than the number of child units in <code>refNode</code>. Child units 192 * are 16-bit units if <code>refNode</code> is a type of DOMCharacterData 193 * node (e.g., a DOMText or DOMComment node) or a DOMProcessingInstruction 194 * node. Child units are Nodes in all other cases. 195 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 196 * been invoked on this object. 197 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 198 * from a different document than the one that created this range. 199 * 200 * @since DOM Level 2 201 */ 202 virtual void setStart(const DOMNode *refNode, XMLSize_t offset) = 0; 203 204 /** 205 * Sets the attributes describing the end of a Range. 206 * @param refNode The <code>refNode</code> value. This parameter must be 207 * different from <code>null</code>. 208 * @param offset The <code>endOffset</code> value. 209 * @exception DOMRangeException 210 * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor 211 * of <code>refNode</code> is an DOMEntity, DOMNotation, or DOMDocumentType 212 * node. 213 * @exception DOMException 214 * INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater 215 * than the number of child units in <code>refNode</code>. Child units 216 * are 16-bit units if <code>refNode</code> is a type of DOMCharacterData 217 * node (e.g., a DOMText or DOMComment node) or a DOMProcessingInstruction 218 * node. Child units are Nodes in all other cases. 219 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 220 * been invoked on this object. 221 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 222 * from a different document than the one that created this range. 223 * 224 * @since DOM Level 2 225 */ 226 virtual void setEnd(const DOMNode *refNode, XMLSize_t offset) = 0; 227 228 /** 229 * Sets the start position to be before a node 230 * @param refNode Range starts before <code>refNode</code> 231 * @exception DOMRangeException 232 * INVALID_NODE_TYPE_ERR: Raised if the root container of 233 * <code>refNode</code> is not an DOMAttr, DOMDocument, or DOMDocumentFragment 234 * node or if <code>refNode</code> is a DOMDocument, DOMDocumentFragment, 235 * DOMAttr, DOMEntity, or DOMNotation node. 236 * @exception DOMException 237 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 238 * invoked on this object. 239 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 240 * from a different document than the one that created this range. 241 * 242 * @since DOM Level 2 243 */ 244 virtual void setStartBefore(const DOMNode *refNode) = 0; 245 246 /** 247 * Sets the start position to be after a node 248 * @param refNode Range starts after <code>refNode</code> 249 * @exception DOMRangeException 250 * INVALID_NODE_TYPE_ERR: Raised if the root container of 251 * <code>refNode</code> is not an DOMAttr, DOMDocument, or DOMDocumentFragment 252 * node or if <code>refNode</code> is a DOMDocument, DOMDocumentFragment, 253 * DOMAttr, DOMEntity, or DOMNotation node. 254 * @exception DOMException 255 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 256 * invoked on this object. 257 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 258 * from a different document than the one that created this range. 259 * 260 * @since DOM Level 2 261 */ 262 virtual void setStartAfter(const DOMNode *refNode) = 0; 263 264 /** 265 * Sets the end position to be before a node. 266 * @param refNode Range ends before <code>refNode</code> 267 * @exception DOMRangeException 268 * INVALID_NODE_TYPE_ERR: Raised if the root container of 269 * <code>refNode</code> is not an DOMAttr, DOMDocument, or DOMDocumentFragment 270 * node or if <code>refNode</code> is a DOMDocument, DOMDocumentFragment, 271 * DOMAttr, DOMEntity, or DOMNotation node. 272 * @exception DOMException 273 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 274 * invoked on this object. 275 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 276 * from a different document than the one that created this range. 277 * 278 * @since DOM Level 2 279 */ 280 virtual void setEndBefore(const DOMNode *refNode) = 0; 281 282 /** 283 * Sets the end of a Range to be after a node 284 * @param refNode Range ends after <code>refNode</code>. 285 * @exception DOMRangeException 286 * INVALID_NODE_TYPE_ERR: Raised if the root container of 287 * <code>refNode</code> is not a DOMAttr, DOMDocument or DOMDocumentFragment 288 * node or if <code>refNode</code> is a DOMDocument, DOMDocumentFragment, 289 * DOMAttr, DOMEntity, or DOMNotation node. 290 * @exception DOMException 291 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 292 * invoked on this object. 293 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 294 * from a different document than the one that created this range. 295 * 296 * @since DOM Level 2 297 */ 298 virtual void setEndAfter(const DOMNode *refNode) = 0; 299 300 // ----------------------------------------------------------------------- 301 // Misc methods 302 // ----------------------------------------------------------------------- 303 /** 304 * Collapse a Range onto one of its boundary-points 305 * @param toStart If TRUE, collapses the Range onto its start; if FALSE, 306 * collapses it onto its end. 307 * @exception DOMException 308 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 309 * invoked on this object. 310 * 311 * @since DOM Level 2 312 */ 313 virtual void collapse(bool toStart) = 0; 314 315 /** 316 * Select a node and its contents 317 * @param refNode The node to select. 318 * @exception DOMRangeException 319 * INVALID_NODE_TYPE_ERR: Raised if an ancestor of <code>refNode</code> 320 * is an DOMEntity, DOMNotation or DOMDocumentType node or if 321 * <code>refNode</code> is a DOMDocument, DOMDocumentFragment, DOMAttr, DOMEntity, 322 * or DOMNotation node. 323 * @exception DOMException 324 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 325 * invoked on this object. 326 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 327 * from a different document than the one that created this range. 328 * 329 * @since DOM Level 2 330 */ 331 virtual void selectNode(const DOMNode *refNode) = 0; 332 333 /** 334 * Select the contents within a node 335 * @param refNode DOMNode to select from 336 * @exception DOMRangeException 337 * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor 338 * of <code>refNode</code> is an DOMEntity, DOMNotation or DOMDocumentType node. 339 * @exception DOMException 340 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 341 * invoked on this object. 342 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 343 * from a different document than the one that created this range. 344 * 345 * @since DOM Level 2 346 */ 347 virtual void selectNodeContents(const DOMNode *refNode) = 0; 348 349 /** 350 * Compare the boundary-points of two Ranges in a document. 351 * @param how A code representing the type of comparison, as defined 352 * above. 353 * @param sourceRange The <code>Range</code> on which this current 354 * <code>Range</code> is compared to. 355 * @return -1, 0 or 1 depending on whether the corresponding 356 * boundary-point of the Range is respectively before, equal to, or 357 * after the corresponding boundary-point of <code>sourceRange</code>. 358 * @exception DOMException 359 * WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same 360 * DOMDocument or DOMDocumentFragment. 361 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 362 * been invoked on this object. 363 * 364 * @since DOM Level 2 365 */ 366 virtual short compareBoundaryPoints(CompareHow how, const DOMRange* sourceRange) const = 0; 367 368 /** 369 * Removes the contents of a Range from the containing document or 370 * document fragment without returning a reference to the removed 371 * content. 372 * @exception DOMException 373 * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of 374 * the Range is read-only or any of the nodes that contain any of the 375 * content of the Range are read-only. 376 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 377 * been invoked on this object. 378 * 379 * @since DOM Level 2 380 */ 381 virtual void deleteContents() = 0; 382 383 /** 384 * Moves the contents of a Range from the containing document or document 385 * fragment to a new DOMDocumentFragment. 386 * @return A DOMDocumentFragment containing the extracted contents. 387 * @exception DOMException 388 * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of 389 * the Range is read-only or any of the nodes which contain any of the 390 * content of the Range are read-only. 391 * <br>HIERARCHY_REQUEST_ERR: Raised if a DOMDocumentType node would be 392 * extracted into the new DOMDocumentFragment. 393 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 394 * been invoked on this object. 395 * 396 * @since DOM Level 2 397 */ 398 virtual DOMDocumentFragment* extractContents() = 0; 399 400 /** 401 * Duplicates the contents of a Range 402 * @return A DOMDocumentFragment that contains content equivalent to this 403 * Range. 404 * @exception DOMException 405 * HIERARCHY_REQUEST_ERR: Raised if a DOMDocumentType node would be 406 * extracted into the new DOMDocumentFragment. 407 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 408 * been invoked on this object. 409 * 410 * @since DOM Level 2 411 */ 412 virtual DOMDocumentFragment* cloneContents() const = 0; 413 414 /** 415 * Inserts a node into the DOMDocument or DOMDocumentFragment at the start of 416 * the Range. If the container is a DOMText node, this will be split at the 417 * start of the Range (as if the DOMText node's splitText method was 418 * performed at the insertion point) and the insertion will occur 419 * between the two resulting DOMText nodes. Adjacent DOMText nodes will not be 420 * automatically merged. If the node to be inserted is a 421 * DOMDocumentFragment node, the children will be inserted rather than the 422 * DOMDocumentFragment node itself. 423 * @param newNode The node to insert at the start of the Range 424 * @exception DOMException 425 * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of the 426 * start of the Range is read-only. 427 * <br>WRONG_DOCUMENT_ERR: Raised if <code>newNode</code> and the 428 * container of the start of the Range were not created from the same 429 * document. 430 * <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of 431 * the Range is of a type that does not allow children of the type of 432 * <code>newNode</code> or if <code>newNode</code> is an ancestor of 433 * the container. 434 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 435 * been invoked on this object. 436 * @exception DOMRangeException 437 * INVALID_NODE_TYPE_ERR: Raised if <code>newNode</code> is an DOMAttr, 438 * DOMEntity, DOMNotation, or DOMDocument node. 439 * 440 * @since DOM Level 2 441 */ 442 virtual void insertNode(DOMNode *newNode) = 0; 443 444 /** 445 * Reparents the contents of the Range to the given node and inserts the 446 * node at the position of the start of the Range. 447 * @param newParent The node to surround the contents with. 448 * @exception DOMException 449 * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of 450 * either boundary-point of the Range is read-only. 451 * <br>WRONG_DOCUMENT_ERR: Raised if <code> newParent</code> and the 452 * container of the start of the Range were not created from the same 453 * document. 454 * <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of 455 * the Range is of a type that does not allow children of the type of 456 * <code>newParent</code> or if <code>newParent</code> is an ancestor 457 * of the container or if <code>node</code> would end up with a child 458 * node of a type not allowed by the type of <code>node</code>. 459 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 460 * been invoked on this object. 461 * @exception DOMRangeException 462 * BAD_BOUNDARYPOINTS_ERR: Raised if the Range partially selects a 463 * non-text node. 464 * <br>INVALID_NODE_TYPE_ERR: Raised if <code> node</code> is an DOMAttr, 465 * DOMEntity, DOMDocumentType, DOMNotation, DOMDocument, or DOMDocumentFragment node. 466 * 467 * @since DOM Level 2 468 */ 469 virtual void surroundContents(DOMNode *newParent) = 0; 470 471 /** 472 * Produces a new Range whose boundary-points are equal to the 473 * boundary-points of the Range. 474 * @return The duplicated Range. 475 * @exception DOMException 476 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 477 * invoked on this object. 478 * 479 * @since DOM Level 2 480 */ 481 virtual DOMRange* cloneRange() const = 0; 482 483 /** 484 * Returns the contents of a Range as a string. This string contains only 485 * the data characters, not any markup. 486 * @return The contents of the Range. 487 * @exception DOMException 488 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 489 * invoked on this object. 490 * 491 * @since DOM Level 2 492 */ 493 virtual const XMLCh* toString() const = 0; 494 495 /** 496 * Called to indicate that the Range is no longer in use and that the 497 * implementation may relinquish any resources associated with this 498 * Range. Subsequent calls to any methods or attribute getters on this 499 * Range will result in a <code>DOMException</code> being thrown with an 500 * error code of <code>INVALID_STATE_ERR</code>. 501 * @exception DOMException 502 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 503 * invoked on this object. 504 * 505 * @since DOM Level 2 506 */ 507 virtual void detach() = 0; 508 509 //@} 510 511 // ----------------------------------------------------------------------- 512 // Non-standard Extension 513 // ----------------------------------------------------------------------- 514 /** @name Non-standard Extension */ 515 //@{ 516 /** 517 * Called to indicate that this Range is no longer in use 518 * and that the implementation may relinquish any resources associated with it. 519 * (release() will call detach() where appropriate) 520 * 521 * Access to a released object will lead to unexpected result. 522 */ 523 virtual void release() = 0; 524 //@} 525 }; 526 527 528 XERCES_CPP_NAMESPACE_END 529 530 #endif 531