/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /* * $Id: DOMRange.hpp 932887 2010-04-11 13:04:59Z borisk $ */ #if !defined(XERCESC_INCLUDE_GUARD_DOMRANGE_HPP) #define XERCESC_INCLUDE_GUARD_DOMRANGE_HPP #include XERCES_CPP_NAMESPACE_BEGIN class DOMNode; class DOMDocumentFragment; /** *

See also the Document Object Model (DOM) Level 2 Traversal and Range Specification. * @since DOM Level 2 */ class CDOM_EXPORT DOMRange { protected: // ----------------------------------------------------------------------- // Hidden constructors // ----------------------------------------------------------------------- /** @name Hidden constructors */ //@{ DOMRange() {} DOMRange(const DOMRange &) {} //@} private: // ----------------------------------------------------------------------- // Unimplemented constructors and operators // ----------------------------------------------------------------------- /** @name Unimplemented operators */ //@{ DOMRange & operator = (const DOMRange &); //@} public: // ----------------------------------------------------------------------- // All constructors are hidden, just the destructor is available // ----------------------------------------------------------------------- /** @name Destructor */ //@{ /** * Destructor * */ virtual ~DOMRange() {}; //@} // ----------------------------------------------------------------------- // Class Types // ----------------------------------------------------------------------- /** @name Public Constants */ //@{ /** * Constants CompareHow. * *

START_TO_START: * Compare start boundary-point of sourceRange to start * boundary-point of Range on which compareBoundaryPoints * is invoked.

* *

START_TO_END: * Compare start boundary-point of sourceRange to end * boundary-point of Range on which compareBoundaryPoints * is invoked.

* *

END_TO_END: * Compare end boundary-point of sourceRange to end * boundary-point of Range on which compareBoundaryPoints * is invoked.

* *

END_TO_START: * Compare end boundary-point of sourceRange to start * boundary-point of Range on which compareBoundaryPoints * is invoked.

* * @since DOM Level 2 */ enum CompareHow { START_TO_START = 0, START_TO_END = 1, END_TO_END = 2, END_TO_START = 3 }; //@} // ----------------------------------------------------------------------- // Virtual DOMRange interface // ----------------------------------------------------------------------- /** @name Functions introduced in DOM Level 2 */ //@{ // ----------------------------------------------------------------------- // Getter methods // ----------------------------------------------------------------------- /** * DOMNode within which the Range begins * @exception DOMException * INVALID_STATE_ERR: Raised if detach() has already been * invoked on this object. * * @since DOM Level 2 */ virtual DOMNode* getStartContainer() const = 0; /** * Offset within the starting node of the Range. * @exception DOMException * INVALID_STATE_ERR: Raised if detach() has already been * invoked on this object. * * @since DOM Level 2 */ virtual XMLSize_t getStartOffset() const = 0; /** * DOMNode within which the Range ends * @exception DOMException * INVALID_STATE_ERR: Raised if detach() has already been * invoked on this object. * * @since DOM Level 2 */ virtual DOMNode* getEndContainer() const = 0; /** * Offset within the ending node of the Range. * @exception DOMException * INVALID_STATE_ERR: Raised if detach() has already been * invoked on this object. * * @since DOM Level 2 */ virtual XMLSize_t getEndOffset() const = 0; /** * TRUE if the Range is collapsed * @exception DOMException * INVALID_STATE_ERR: Raised if detach() has already been * invoked on this object. * * @since DOM Level 2 */ virtual bool getCollapsed() const = 0; /** * The deepest common ancestor container of the Range's two * boundary-points. * @exception DOMException * INVALID_STATE_ERR: Raised if detach() has already been * invoked on this object. * * @since DOM Level 2 */ virtual const DOMNode* getCommonAncestorContainer() const = 0; // ----------------------------------------------------------------------- // Setter methods // ----------------------------------------------------------------------- /** * Sets the attributes describing the start of the Range. * @param refNode The refNode value. This parameter must be * different from null. * @param offset The startOffset value. * @exception DOMRangeException * INVALID_NODE_TYPE_ERR: Raised if refNode or an ancestor * of refNode is an DOMEntity, DOMNotation, or DOMDocumentType * node. * @exception DOMException * INDEX_SIZE_ERR: Raised if offset is negative or greater * than the number of child units in refNode. Child units * are 16-bit units if refNode is a type of DOMCharacterData * node (e.g., a DOMText or DOMComment node) or a DOMProcessingInstruction * node. Child units are Nodes in all other cases. *
INVALID_STATE_ERR: Raised if detach() has already * been invoked on this object. *
WRONG_DOCUMENT_ERR: Raised if refNode was created * from a different document than the one that created this range. * * @since DOM Level 2 */ virtual void setStart(const DOMNode *refNode, XMLSize_t offset) = 0; /** * Sets the attributes describing the end of a Range. * @param refNode The refNode value. This parameter must be * different from null. * @param offset The endOffset value. * @exception DOMRangeException * INVALID_NODE_TYPE_ERR: Raised if refNode or an ancestor * of refNode is an DOMEntity, DOMNotation, or DOMDocumentType * node. * @exception DOMException * INDEX_SIZE_ERR: Raised if offset is negative or greater * than the number of child units in refNode. Child units * are 16-bit units if refNode is a type of DOMCharacterData * node (e.g., a DOMText or DOMComment node) or a DOMProcessingInstruction * node. Child units are Nodes in all other cases. *
INVALID_STATE_ERR: Raised if detach() has already * been invoked on this object. *
WRONG_DOCUMENT_ERR: Raised if refNode was created * from a different document than the one that created this range. * * @since DOM Level 2 */ virtual void setEnd(const DOMNode *refNode, XMLSize_t offset) = 0; /** * Sets the start position to be before a node * @param refNode Range starts before refNode * @exception DOMRangeException * INVALID_NODE_TYPE_ERR: Raised if the root container of * refNode is not an DOMAttr, DOMDocument, or DOMDocumentFragment * node or if refNode is a DOMDocument, DOMDocumentFragment, * DOMAttr, DOMEntity, or DOMNotation node. * @exception DOMException * INVALID_STATE_ERR: Raised if detach() has already been * invoked on this object. *
WRONG_DOCUMENT_ERR: Raised if refNode was created * from a different document than the one that created this range. * * @since DOM Level 2 */ virtual void setStartBefore(const DOMNode *refNode) = 0; /** * Sets the start position to be after a node * @param refNode Range starts after refNode * @exception DOMRangeException * INVALID_NODE_TYPE_ERR: Raised if the root container of * refNode is not an DOMAttr, DOMDocument, or DOMDocumentFragment * node or if refNode is a DOMDocument, DOMDocumentFragment, * DOMAttr, DOMEntity, or DOMNotation node. * @exception DOMException * INVALID_STATE_ERR: Raised if detach() has already been * invoked on this object. *
WRONG_DOCUMENT_ERR: Raised if refNode was created * from a different document than the one that created this range. * * @since DOM Level 2 */ virtual void setStartAfter(const DOMNode *refNode) = 0; /** * Sets the end position to be before a node. * @param refNode Range ends before refNode * @exception DOMRangeException * INVALID_NODE_TYPE_ERR: Raised if the root container of * refNode is not an DOMAttr, DOMDocument, or DOMDocumentFragment * node or if refNode is a DOMDocument, DOMDocumentFragment, * DOMAttr, DOMEntity, or DOMNotation node. * @exception DOMException * INVALID_STATE_ERR: Raised if detach() has already been * invoked on this object. *
WRONG_DOCUMENT_ERR: Raised if refNode was created * from a different document than the one that created this range. * * @since DOM Level 2 */ virtual void setEndBefore(const DOMNode *refNode) = 0; /** * Sets the end of a Range to be after a node * @param refNode Range ends after refNode. * @exception DOMRangeException * INVALID_NODE_TYPE_ERR: Raised if the root container of * refNode is not a DOMAttr, DOMDocument or DOMDocumentFragment * node or if refNode is a DOMDocument, DOMDocumentFragment, * DOMAttr, DOMEntity, or DOMNotation node. * @exception DOMException * INVALID_STATE_ERR: Raised if detach() has already been * invoked on this object. *
WRONG_DOCUMENT_ERR: Raised if refNode was created * from a different document than the one that created this range. * * @since DOM Level 2 */ virtual void setEndAfter(const DOMNode *refNode) = 0; // ----------------------------------------------------------------------- // Misc methods // ----------------------------------------------------------------------- /** * Collapse a Range onto one of its boundary-points * @param toStart If TRUE, collapses the Range onto its start; if FALSE, * collapses it onto its end. * @exception DOMException * INVALID_STATE_ERR: Raised if detach() has already been * invoked on this object. * * @since DOM Level 2 */ virtual void collapse(bool toStart) = 0; /** * Select a node and its contents * @param refNode The node to select. * @exception DOMRangeException * INVALID_NODE_TYPE_ERR: Raised if an ancestor of refNode * is an DOMEntity, DOMNotation or DOMDocumentType node or if * refNode is a DOMDocument, DOMDocumentFragment, DOMAttr, DOMEntity, * or DOMNotation node. * @exception DOMException * INVALID_STATE_ERR: Raised if detach() has already been * invoked on this object. *
WRONG_DOCUMENT_ERR: Raised if refNode was created * from a different document than the one that created this range. * * @since DOM Level 2 */ virtual void selectNode(const DOMNode *refNode) = 0; /** * Select the contents within a node * @param refNode DOMNode to select from * @exception DOMRangeException * INVALID_NODE_TYPE_ERR: Raised if refNode or an ancestor * of refNode is an DOMEntity, DOMNotation or DOMDocumentType node. * @exception DOMException * INVALID_STATE_ERR: Raised if detach() has already been * invoked on this object. *
WRONG_DOCUMENT_ERR: Raised if refNode was created * from a different document than the one that created this range. * * @since DOM Level 2 */ virtual void selectNodeContents(const DOMNode *refNode) = 0; /** * Compare the boundary-points of two Ranges in a document. * @param how A code representing the type of comparison, as defined * above. * @param sourceRange The Range on which this current * Range is compared to. * @return -1, 0 or 1 depending on whether the corresponding * boundary-point of the Range is respectively before, equal to, or * after the corresponding boundary-point of sourceRange. * @exception DOMException * WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same * DOMDocument or DOMDocumentFragment. *
INVALID_STATE_ERR: Raised if detach() has already * been invoked on this object. * * @since DOM Level 2 */ virtual short compareBoundaryPoints(CompareHow how, const DOMRange* sourceRange) const = 0; /** * Removes the contents of a Range from the containing document or * document fragment without returning a reference to the removed * content. * @exception DOMException * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of * the Range is read-only or any of the nodes that contain any of the * content of the Range are read-only. *
INVALID_STATE_ERR: Raised if detach() has already * been invoked on this object. * * @since DOM Level 2 */ virtual void deleteContents() = 0; /** * Moves the contents of a Range from the containing document or document * fragment to a new DOMDocumentFragment. * @return A DOMDocumentFragment containing the extracted contents. * @exception DOMException * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of * the Range is read-only or any of the nodes which contain any of the * content of the Range are read-only. *
HIERARCHY_REQUEST_ERR: Raised if a DOMDocumentType node would be * extracted into the new DOMDocumentFragment. *
INVALID_STATE_ERR: Raised if detach() has already * been invoked on this object. * * @since DOM Level 2 */ virtual DOMDocumentFragment* extractContents() = 0; /** * Duplicates the contents of a Range * @return A DOMDocumentFragment that contains content equivalent to this * Range. * @exception DOMException * HIERARCHY_REQUEST_ERR: Raised if a DOMDocumentType node would be * extracted into the new DOMDocumentFragment. *
INVALID_STATE_ERR: Raised if detach() has already * been invoked on this object. * * @since DOM Level 2 */ virtual DOMDocumentFragment* cloneContents() const = 0; /** * Inserts a node into the DOMDocument or DOMDocumentFragment at the start of * the Range. If the container is a DOMText node, this will be split at the * start of the Range (as if the DOMText node's splitText method was * performed at the insertion point) and the insertion will occur * between the two resulting DOMText nodes. Adjacent DOMText nodes will not be * automatically merged. If the node to be inserted is a * DOMDocumentFragment node, the children will be inserted rather than the * DOMDocumentFragment node itself. * @param newNode The node to insert at the start of the Range * @exception DOMException * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of the * start of the Range is read-only. *
WRONG_DOCUMENT_ERR: Raised if newNode and the * container of the start of the Range were not created from the same * document. *
HIERARCHY_REQUEST_ERR: Raised if the container of the start of * the Range is of a type that does not allow children of the type of * newNode or if newNode is an ancestor of * the container. *
INVALID_STATE_ERR: Raised if detach() has already * been invoked on this object. * @exception DOMRangeException * INVALID_NODE_TYPE_ERR: Raised if newNode is an DOMAttr, * DOMEntity, DOMNotation, or DOMDocument node. * * @since DOM Level 2 */ virtual void insertNode(DOMNode *newNode) = 0; /** * Reparents the contents of the Range to the given node and inserts the * node at the position of the start of the Range. * @param newParent The node to surround the contents with. * @exception DOMException * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of * either boundary-point of the Range is read-only. *
WRONG_DOCUMENT_ERR: Raised if newParent and the * container of the start of the Range were not created from the same * document. *
HIERARCHY_REQUEST_ERR: Raised if the container of the start of * the Range is of a type that does not allow children of the type of * newParent or if newParent is an ancestor * of the container or if node would end up with a child * node of a type not allowed by the type of node. *
INVALID_STATE_ERR: Raised if detach() has already * been invoked on this object. * @exception DOMRangeException * BAD_BOUNDARYPOINTS_ERR: Raised if the Range partially selects a * non-text node. *
INVALID_NODE_TYPE_ERR: Raised if node is an DOMAttr, * DOMEntity, DOMDocumentType, DOMNotation, DOMDocument, or DOMDocumentFragment node. * * @since DOM Level 2 */ virtual void surroundContents(DOMNode *newParent) = 0; /** * Produces a new Range whose boundary-points are equal to the * boundary-points of the Range. * @return The duplicated Range. * @exception DOMException * INVALID_STATE_ERR: Raised if detach() has already been * invoked on this object. * * @since DOM Level 2 */ virtual DOMRange* cloneRange() const = 0; /** * Returns the contents of a Range as a string. This string contains only * the data characters, not any markup. * @return The contents of the Range. * @exception DOMException * INVALID_STATE_ERR: Raised if detach() has already been * invoked on this object. * * @since DOM Level 2 */ virtual const XMLCh* toString() const = 0; /** * Called to indicate that the Range is no longer in use and that the * implementation may relinquish any resources associated with this * Range. Subsequent calls to any methods or attribute getters on this * Range will result in a DOMException being thrown with an * error code of INVALID_STATE_ERR. * @exception DOMException * INVALID_STATE_ERR: Raised if detach() has already been * invoked on this object. * * @since DOM Level 2 */ virtual void detach() = 0; //@} // ----------------------------------------------------------------------- // Non-standard Extension // ----------------------------------------------------------------------- /** @name Non-standard Extension */ //@{ /** * Called to indicate that this Range is no longer in use * and that the implementation may relinquish any resources associated with it. * (release() will call detach() where appropriate) * * Access to a released object will lead to unexpected result. */ virtual void release() = 0; //@} }; XERCES_CPP_NAMESPACE_END #endif