You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tdelibs/tdehtml/dom/dom2_range.h

476 lines
13 KiB

/*
* This file is part of the DOM implementation for KDE.
*
* (C) 1999 Lars Knoll (knoll@kde.org)
* (C) 2000 Gunnstein Lye (gunnstein@netcom.no)
* (C) 2000 Frederik Holljen (frederik.holljen@hig.no)
* (C) 2001 Peter Kelly (pmk@post.com)
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public License
* along with this library; see the file COPYING.LIB. If not, write to
* the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
* Boston, MA 02110-1301, USA.
*
* This file includes excerpts from the Document Object Model (DOM)
* Level 2 Specification (Candidate Recommendation)
* http://www.w3.org/TR/2000/CR-DOM-Level-2-20000510/
* Copyright <EFBFBD> 2000 W3C<EFBFBD> (MIT, INRIA, Keio), All Rights Reserved.
*
*/
#ifndef _dom2_range_h_
#define _dom2_range_h_
#include <dom/dom_doc.h>
#include <dom/dom_misc.h>
namespace DOM {
class DocumentFragment;
class Node;
class DOMString;
class DocumentImpl;
class RangeImpl;
class DOMException;
// Introduced in DOM Level 2:
class TDEHTML_EXPORT RangeException {
public:
RangeException(unsigned short _code) { code = _code; }
RangeException(const RangeException &other) { code = other.code; }
RangeException & operator = (const RangeException &other)
{ code = other.code; return *this; }
virtual ~RangeException() {}
/**
* An integer indicating the type of error generated.
*
*/
enum RangeExceptionCode {
BAD_BOUNDARYPOINTS_ERR = 1,
INVALID_NODE_TYPE_ERR = 2,
_EXCEPTION_OFFSET = 2000,
_EXCEPTION_MAX = 2999
};
unsigned short code;
};
class TDEHTML_EXPORT Range
{
friend class DocumentImpl;
friend class Document;
friend class RangeImpl;
public:
Range();
Range(const Document rootContainer);
Range(const Range &other);
Range(const Node startContainer, const long startOffset, const Node endContainer, const long endOffset);
Range & operator = (const Range &other);
~Range();
/**
* Node within which the range begins
*
*/
Node startContainer() const;
/**
* Offset within the starting node of the range.
*
*/
long startOffset() const;
/**
* Node within which the range ends
*
*/
Node endContainer() const;
/**
* Offset within the ending node of the range.
*
*/
long endOffset() const;
/**
* true if the range is collapsed
*
*/
bool collapsed() const;
/**
* Gets the common ancestor container of the range's two end-points.
* Also sets it.
*
*/
// ### BIC make const in the next release
Node commonAncestorContainer();
/**
* Sets the attributes describing the start of the range.
*
* @param refNode The \c refNode value. This parameter
* must be different from \c null .
*
* @param offset The \c startOffset value.
*
* @return
*
* @exception RangeException
* NULL_NODE_ERR: Raised if \c refNode is \c null .
*
* INVALID_NODE_TYPE_ERR: Raised if \c refNode or an
* ancestor of \c refNode is an Attr, Entity,
* Notation, or DocumentType node.
*
* If an offset is out-of-bounds, should it just be fixed up or
* should an exception be raised.
*
*/
void setStart ( const Node &refNode, long offset );
/**
* Sets the attributes describing the end of a range.
*
* @param refNode The \c refNode value. This parameter
* must be different from \c null .
*
* @param offset The \c endOffset value.
*
* @return
*
* @exception RangeException
* NULL_NODE_ERR: Raised if \c refNode is \c null .
*
* INVALID_NODE_TYPE_ERR: Raised if \c refNode or an
* ancestor of \c refNode is an Attr, Entity,
* Notation, or DocumentType node.
*
*/
void setEnd ( const Node &refNode, long offset );
/**
* Sets the start position to be before a node
*
* @param refNode Range starts before \c refNode
*
* @return
*
* @exception RangeException
* INVALID_NODE_TYPE_ERR: Raised if an ancestor of \c refNode
* is an Attr, Entity, Notation, or DocumentType node or
* if \c refNode is a Document, DocumentFragment,
* Attr, Entity, or Notation node.
*
*/
void setStartBefore ( const Node &refNode );
/**
* Sets the start position to be after a node
*
* @param refNode Range starts after \c refNode
*
* @return
*
* @exception RangeException
* INVALID_NODE_TYPE_ERR: Raised if an ancestor of \c refNode
* is an Attr, Entity, Notation, or DocumentType node or
* if \c refNode is a Document, DocumentFragment,
* Attr, Entity, or Notation node.
*
*/
void setStartAfter ( const Node &refNode );
/**
* Sets the end position to be before a node.
*
* @param refNode Range ends before \c refNode
*
* @return
*
* @exception RangeException
* INVALID_NODE_TYPE_ERR: Raised if an ancestor of \c refNode
* is an Attr, Entity, Notation, or DocumentType node or
* if \c refNode is a Document, DocumentFragment,
* Attr, Entity, or Notation node.
*
*/
void setEndBefore ( const Node &refNode );
/**
* Sets the end of a range to be after a node
*
* @param refNode Range ends after \c refNode .
*
* @return
*
* @exception RangeException
* INVALID_NODE_TYPE_ERR: Raised if an ancestor of \c refNode
* is an Attr, Entity, Notation or DocumentType node or if
* \c refNode is a Document, DocumentFragment, Attr,
* Entity, or Notation node.
*
*/
void setEndAfter ( const Node &refNode );
/**
* Collapse a range onto one of its end-points
*
* @param toStart If true, collapses the Range onto its start; if
* false, collapses it onto its end.
*
* @return
*
*/
void collapse ( bool toStart );
/**
* Select a node and its contents
*
* @param refNode The node to select.
*
* @return
*
* @exception RangeException
* INVALID_NODE_TYPE_ERR: Raised if an ancestor of \c refNode
* is an Attr, Entity, Notation or DocumentType node or if
* \c refNode is a Document, DocumentFragment, Attr,
* Entity, or Notation node.
*
*/
void selectNode ( const Node &refNode );
/**
* Select the contents within a node
*
* @param refNode Node to select from
*
* @return
*
* @exception RangeException
* INVALID_NODE_TYPE_ERR: Raised if \c refNode or an
* ancestor of \c refNode is an Attr, Entity, Notation
* or DocumentType node.
*
*/
void selectNodeContents ( const Node &refNode );
enum CompareHow {
START_TO_START = 0,
START_TO_END = 1,
END_TO_END = 2,
END_TO_START = 3
};
/**
* Compare the end-points of two ranges in a document.
*
* @param how
*
* @param sourceRange
*
* @return -1, 0 or 1 depending on whether the corresponding
* end-point of the Range is before, equal to, or after the
* corresponding end-point of \c sourceRange .
*
* @exception DOMException
* WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the
* same document or document fragment.
*
*/
short compareBoundaryPoints ( CompareHow how, const Range &sourceRange );
/**
* @internal
* not part of the DOM
*
* Compare the boundary-points of a range.
*
* Return true if the startContainer is before the endContainer,
* or if they are equal.
* Return false if the startContainer is after the endContainer.
*
*/
bool boundaryPointsValid ( );
/**
* Removes the contents of a range from the containing document or
* document fragment without returning a reference to the removed
* content.
*
* @return
*
* @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.
*
*/
void deleteContents ( );
/**
* Moves the contents of a range from the containing document or
* document fragment to a new DocumentFragment.
*
* @return A DocumentFragment 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 DocumentType node would be
* extracted into the new DocumentFragment.
*
*/
DocumentFragment extractContents ( );
/**
* Duplicates the contents of a range
*
* @return A DocumentFragment containing contents equivalent to
* those of this range.
*
* @exception DOMException
* HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be
* extracted into the new DocumentFragment.
*
*/
DocumentFragment cloneContents ( );
/**
* Inserts a node into the document or document fragment at the
* start of the range.
*
* @param newNode The node to insert at the start of the range
*
* @return
*
* @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 \c 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 \c newNode or if \c newNode is an
* ancestor of the container .
*
* @exception RangeException
* INVALID_NODE_TYPE_ERR: Raised if \c node is an
* Attr, Entity, Notation, DocumentFragment, or Document node.
*
*/
void insertNode ( const Node &newNode );
/**
* 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.
*
* @return
*
* @exception DOMException
* NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of
* either end-point of the range is read-only.
*
* WRONG_DOCUMENT_ERR: Raised if \c 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 \c newParent or if \c newParent is
* an ancestor of the container or if \c node would
* end up with a child node of a type not allowed by the type of
* \c node .
*
* @exception RangeException
* BAD_ENDPOINTS_ERR: Raised if the range partially selects a
* non-text node.
*
* INVALID_NODE_TYPE_ERR: Raised if \c node is an
* Attr, Entity, DocumentType, Notation, Document, or
* DocumentFragment node.
*
*/
void surroundContents ( const Node &newParent );
/**
* Produces a new range whose end-points are equal to the
* end-points of the range.
*
* @return The duplicated range.
*
*/
Range cloneRange ( );
/**
* Returns the contents of a range as a string.
*
* @return The contents of the range.
*
*/
DOMString toString ( );
/**
* @internal Not part of DOM
*/
DOMString toHTML ( );
/* Mozilla extension - only works for HTML documents. */
DocumentFragment createContextualFragment (const DOMString &html);
/**
* 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.
*
*/
void detach ( );
/**
* not part of the DOM
* true if the range is detached
*
*/
bool isDetached() const;
/**
* @internal
* not part of the DOM
*/
RangeImpl *handle() const;
bool isNull() const;
protected:
RangeImpl *impl;
Range(RangeImpl *i);
private:
void throwException(int exceptioncode) const;
};
} // namespace
#endif