1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 #ifndef DOMRange_HEADER_GUARD_

    18 #define DOMRange_HEADER_GUARD_

    19 

    20 /*

    21  * Licensed to the Apache Software Foundation (ASF) under one or more

    22  * contributor license agreements.  See the NOTICE file distributed with

    23  * this work for additional information regarding copyright ownership.

    24  * The ASF licenses this file to You under the Apache License, Version 2.0

    25  * (the "License"); you may not use this file except in compliance with

    26  * the License.  You may obtain a copy of the License at

    27  * 

    28  *      http://www.apache.org/licenses/LICENSE-2.0

    29  * 

    30  * Unless required by applicable law or agreed to in writing, software

    31  * distributed under the License is distributed on an "AS IS" BASIS,

    32  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

    33  * See the License for the specific language governing permissions and

    34  * limitations under the License.

    35  */

    36 

    37 /*

    38  * $Id: DOMRange.hpp 568078 2007-08-21 11:43:25Z amassari $

    39  */

    40 

    41 #include <xercesc/util/XercesDefs.hpp>

    42 

    43 XERCES_CPP_NAMESPACE_BEGIN

    44 

    45 class DOMNode;

    46 class DOMDocumentFragment;

    47 

    48 /**

    49  * <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>.

    50  * @since DOM Level 2

    51  */

    52 class CDOM_EXPORT DOMRange {

    53 protected:

    54     // -----------------------------------------------------------------------

    55     //  Hidden constructors

    56     // -----------------------------------------------------------------------

    57     /** @name Hidden constructors */

    58     //@{    

    59     DOMRange() {}

    60     DOMRange(const DOMRange &) {}

    61     //@}

    62 

    63 private:

    64     // -----------------------------------------------------------------------

    65     // Unimplemented constructors and operators

    66     // -----------------------------------------------------------------------

    67     /** @name Unimplemented operators */

    68     //@{

    69     DOMRange & operator = (const DOMRange &);

    70     //@}

    71 

    72 public:

    73     // -----------------------------------------------------------------------

    74     //  All constructors are hidden, just the destructor is available

    75     // -----------------------------------------------------------------------

    76     /** @name Destructor */

    77     //@{

    78     /**

    79      * Destructor

    80      *

    81      */

    82     virtual ~DOMRange() {};

    83     //@}

    84 

    85     // -----------------------------------------------------------------------

    86     //  Class Types

    87     // -----------------------------------------------------------------------

    88     /** @name Public Contants */

    89     //@{

    90     /**

    91      * Constants CompareHow.

    92      *

    93      * <p><code>START_TO_START:</code>

    94      * Compare start boundary-point of <code>sourceRange</code> to start

    95      * boundary-point of Range on which <code>compareBoundaryPoints</code>

    96      * is invoked.</p>

    97      *

    98      * <p><code>START_TO_END:</code>

    99      * Compare start boundary-point of <code>sourceRange</code> to end

   100      * boundary-point of Range on which <code>compareBoundaryPoints</code>

   101      * is invoked.</p>

   102      *

   103      * <p><code>END_TO_END:</code>

   104      * Compare end boundary-point of <code>sourceRange</code> to end

   105      * boundary-point of Range on which <code>compareBoundaryPoints</code>

   106      * is invoked.</p>

   107      *

   108      * <p><code>END_TO_START:</code>

   109      * Compare end boundary-point of <code>sourceRange</code> to start

   110      * boundary-point of Range on which <code>compareBoundaryPoints</code>

   111      * is invoked.</p>

   112      *

   113      * @since DOM Level 2

   114      */

   115     enum CompareHow {

   116         START_TO_START  = 0,

   117         START_TO_END    = 1,

   118         END_TO_END      = 2,

   119         END_TO_START    = 3

   120     };

   121 

   122     //@}

   123 

   124     // -----------------------------------------------------------------------

   125     //  Virtual DOMRange interface

   126     // -----------------------------------------------------------------------

   127     /** @name Functions introduced in DOM Level 2 */

   128     //@{

   129     // -----------------------------------------------------------------------

   130     //  Getter methods

   131     // -----------------------------------------------------------------------

   132     /**

   133      * DOMNode within which the Range begins

   134      * @exception DOMException

   135      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been

   136      *   invoked on this object.

   137      *

   138      * @since DOM Level 2

   139      */

   140     virtual DOMNode* getStartContainer() const = 0;

   141 

   142     /**

   143      * Offset within the starting node of the Range.

   144      * @exception DOMException

   145      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been

   146      *   invoked on this object.

   147      *

   148      * @since DOM Level 2

   149      */

   150     virtual XMLSize_t getStartOffset() const = 0;

   151 

   152     /**

   153      * DOMNode within which the Range ends

   154      * @exception DOMException

   155      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been

   156      *   invoked on this object.

   157      *

   158      * @since DOM Level 2

   159      */

   160     virtual DOMNode* getEndContainer() const = 0;

   161 

   162     /**

   163      * Offset within the ending node of the Range.

   164      * @exception DOMException

   165      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been

   166      *   invoked on this object.

   167      *

   168      * @since DOM Level 2

   169      */

   170     virtual XMLSize_t getEndOffset() const = 0;

   171 

   172     /**

   173      * TRUE if the Range is collapsed

   174      * @exception DOMException

   175      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been

   176      *   invoked on this object.

   177      *

   178      * @since DOM Level 2

   179      */

   180     virtual bool getCollapsed() const = 0;

   181 

   182     /**

   183      * The deepest common ancestor container of the Range's two

   184      * boundary-points.

   185      * @exception DOMException

   186      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been

   187      *   invoked on this object.

   188      *

   189      * @since DOM Level 2

   190      */

   191     virtual const DOMNode* getCommonAncestorContainer() const = 0;

   192 

   193     // -----------------------------------------------------------------------

   194     //  Setter methods

   195     // -----------------------------------------------------------------------

   196     /**

   197      * Sets the attributes describing the start of the Range.

   198      * @param refNode The <code>refNode</code> value. This parameter must be

   199      *   different from <code>null</code>.

   200      * @param offset The <code>startOffset</code> value.

   201      * @exception DOMRangeException

   202      *   INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor

   203      *   of <code>refNode</code> is an DOMEntity, DOMNotation, or DOMDocumentType

   204      *   node.

   205      * @exception DOMException

   206      *   INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater

   207      *   than the number of child units in <code>refNode</code>. Child units

   208      *   are 16-bit units if <code>refNode</code> is a type of DOMCharacterData

   209      *   node (e.g., a DOMText or DOMComment node) or a DOMProcessingInstruction

   210      *   node. Child units are Nodes in all other cases.

   211      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already

   212      *   been invoked on this object.

   213      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created

   214      *   from a different document than the one that created this range.

   215      *

   216      * @since DOM Level 2

   217      */

   218     virtual void setStart(const DOMNode *refNode, XMLSize_t offset) = 0;

   219 

   220     /**

   221      * Sets the attributes describing the end of a Range.

   222      * @param refNode The <code>refNode</code> value. This parameter must be

   223      *   different from <code>null</code>.

   224      * @param offset The <code>endOffset</code> value.

   225      * @exception DOMRangeException

   226      *   INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor

   227      *   of <code>refNode</code> is an DOMEntity, DOMNotation, or DOMDocumentType

   228      *   node.

   229      * @exception DOMException

   230      *   INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater

   231      *   than the number of child units in <code>refNode</code>. Child units

   232      *   are 16-bit units if <code>refNode</code> is a type of DOMCharacterData

   233      *   node (e.g., a DOMText or DOMComment node) or a DOMProcessingInstruction

   234      *   node. Child units are Nodes in all other cases.

   235      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already

   236      *   been invoked on this object.

   237      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created

   238      *   from a different document than the one that created this range.

   239      *

   240      * @since DOM Level 2

   241      */

   242     virtual void setEnd(const DOMNode *refNode, XMLSize_t offset) = 0;

   243 

   244     /**

   245      * Sets the start position to be before a node

   246      * @param refNode Range starts before <code>refNode</code>

   247      * @exception DOMRangeException

   248      *   INVALID_NODE_TYPE_ERR: Raised if the root container of

   249      *   <code>refNode</code> is not an DOMAttr, DOMDocument, or DOMDocumentFragment

   250      *   node or if <code>refNode</code> is a DOMDocument, DOMDocumentFragment,

   251      *   DOMAttr, DOMEntity, or DOMNotation node.

   252      * @exception DOMException

   253      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been

   254      *   invoked on this object.

   255      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created

   256      *   from a different document than the one that created this range.

   257      *

   258      * @since DOM Level 2

   259      */

   260     virtual void setStartBefore(const DOMNode *refNode) = 0;

   261 

   262     /**

   263      * Sets the start position to be after a node

   264      * @param refNode Range starts after <code>refNode</code>

   265      * @exception DOMRangeException

   266      *   INVALID_NODE_TYPE_ERR: Raised if the root container of

   267      *   <code>refNode</code> is not an DOMAttr, DOMDocument, or DOMDocumentFragment

   268      *   node or if <code>refNode</code> is a DOMDocument, DOMDocumentFragment,

   269      *   DOMAttr, DOMEntity, or DOMNotation node.

   270      * @exception DOMException

   271      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been

   272      *   invoked on this object.

   273      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created

   274      *   from a different document than the one that created this range.

   275      *

   276      * @since DOM Level 2

   277      */

   278     virtual void setStartAfter(const DOMNode *refNode) = 0;

   279 

   280     /**

   281      * Sets the end position to be before a node.

   282      * @param refNode Range ends before <code>refNode</code>

   283      * @exception DOMRangeException

   284      *   INVALID_NODE_TYPE_ERR: Raised if the root container of

   285      *   <code>refNode</code> is not an DOMAttr, DOMDocument, or DOMDocumentFragment

   286      *   node or if <code>refNode</code> is a DOMDocument, DOMDocumentFragment,

   287      *   DOMAttr, DOMEntity, or DOMNotation node.

   288      * @exception DOMException

   289      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been

   290      *   invoked on this object.

   291      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created

   292      *   from a different document than the one that created this range.

   293      *

   294      * @since DOM Level 2

   295      */

   296     virtual void setEndBefore(const DOMNode *refNode) = 0;

   297 

   298     /**

   299      * Sets the end of a Range to be after a node

   300      * @param refNode Range ends after <code>refNode</code>.

   301      * @exception DOMRangeException

   302      *   INVALID_NODE_TYPE_ERR: Raised if the root container of

   303      *   <code>refNode</code> is not a DOMAttr, DOMDocument or DOMDocumentFragment

   304      *   node or if <code>refNode</code> is a DOMDocument, DOMDocumentFragment,

   305      *   DOMAttr, DOMEntity, or DOMNotation node.

   306      * @exception DOMException

   307      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been

   308      *   invoked on this object.

   309      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created

   310      *   from a different document than the one that created this range.

   311      *

   312      * @since DOM Level 2

   313      */

   314     virtual void setEndAfter(const DOMNode *refNode) = 0;

   315 

   316     // -----------------------------------------------------------------------

   317     //  Misc methods

   318     // -----------------------------------------------------------------------

   319     /**

   320      * Collapse a Range onto one of its boundary-points

   321      * @param toStart If TRUE, collapses the Range onto its start; if FALSE,

   322      *   collapses it onto its end.

   323      * @exception DOMException

   324      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been

   325      *   invoked on this object.

   326      *

   327      * @since DOM Level 2

   328      */

   329     virtual void collapse(bool toStart) = 0;

   330 

   331     /**

   332      * Select a node and its contents

   333      * @param refNode The node to select.

   334      * @exception DOMRangeException

   335      *   INVALID_NODE_TYPE_ERR: Raised if an ancestor of <code>refNode</code>

   336      *   is an DOMEntity, DOMNotation or DOMDocumentType node or if

   337      *   <code>refNode</code> is a DOMDocument, DOMDocumentFragment, DOMAttr, DOMEntity,

   338      *   or DOMNotation 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 selectNode(const DOMNode *refNode) = 0;

   348 

   349     /**

   350      * Select the contents within a node

   351      * @param refNode DOMNode to select from

   352      * @exception DOMRangeException

   353      *   INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor

   354      *   of <code>refNode</code> is an DOMEntity, DOMNotation or DOMDocumentType node.

   355      * @exception DOMException

   356      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been

   357      *   invoked on this object.

   358      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created

   359      *   from a different document than the one that created this range.

   360      *

   361      * @since DOM Level 2

   362      */

   363     virtual void selectNodeContents(const DOMNode *refNode) = 0;

   364 

   365     /**

   366      * Compare the boundary-points of two Ranges in a document.

   367      * @param how A code representing the type of comparison, as defined

   368      *   above.

   369      * @param sourceRange The <code>Range</code> on which this current

   370      *   <code>Range</code> is compared to.

   371      * @return  -1, 0 or 1 depending on whether the corresponding

   372      *   boundary-point of the Range is respectively before, equal to, or

   373      *   after the corresponding boundary-point of <code>sourceRange</code>.

   374      * @exception DOMException

   375      *   WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same

   376      *   DOMDocument or DOMDocumentFragment.

   377      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already

   378      *   been invoked on this object.

   379      *

   380      * @since DOM Level 2

   381      */

   382     virtual short compareBoundaryPoints(CompareHow how, const DOMRange* sourceRange) const = 0;

   383 

   384     /**

   385      * Removes the contents of a Range from the containing document or

   386      * document fragment without returning a reference to the removed

   387      * content.

   388      * @exception DOMException

   389      *   NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of

   390      *   the Range is read-only or any of the nodes that contain any of the

   391      *   content of the Range are read-only.

   392      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already

   393      *   been invoked on this object.

   394      *

   395      * @since DOM Level 2

   396      */

   397     virtual void deleteContents() = 0;

   398 

   399     /**

   400      * Moves the contents of a Range from the containing document or document

   401      * fragment to a new DOMDocumentFragment.

   402      * @return A DOMDocumentFragment containing the extracted contents.

   403      * @exception DOMException

   404      *   NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of

   405      *   the Range is read-only or any of the nodes which contain any of the

   406      *   content of the Range are read-only.

   407      *   <br>HIERARCHY_REQUEST_ERR: Raised if a DOMDocumentType node would be

   408      *   extracted into the new DOMDocumentFragment.

   409      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already

   410      *   been invoked on this object.

   411      *

   412      * @since DOM Level 2

   413      */

   414     virtual DOMDocumentFragment* extractContents() = 0;

   415 

   416     /**

   417      * Duplicates the contents of a Range

   418      * @return A DOMDocumentFragment that contains content equivalent to this

   419      *   Range.

   420      * @exception DOMException

   421      *   HIERARCHY_REQUEST_ERR: Raised if a DOMDocumentType node would be

   422      *   extracted into the new DOMDocumentFragment.

   423      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already

   424      *   been invoked on this object.

   425      *

   426      * @since DOM Level 2

   427      */

   428     virtual DOMDocumentFragment* cloneContents() const = 0;

   429 

   430     /**

   431      * Inserts a node into the DOMDocument or DOMDocumentFragment at the start of

   432      * the Range. If the container is a DOMText node, this will be split at the

   433      * start of the Range (as if the DOMText node's splitText method was

   434      * performed at the insertion point) and the insertion will occur

   435      * between the two resulting DOMText nodes. Adjacent DOMText nodes will not be

   436      * automatically merged. If the node to be inserted is a

   437      * DOMDocumentFragment node, the children will be inserted rather than the

   438      * DOMDocumentFragment node itself.

   439      * @param newNode The node to insert at the start of the Range

   440      * @exception DOMException

   441      *   NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of the

   442      *   start of the Range is read-only.

   443      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>newNode</code> and the

   444      *   container of the start of the Range were not created from the same

   445      *   document.

   446      *   <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of

   447      *   the Range is of a type that does not allow children of the type of

   448      *   <code>newNode</code> or if <code>newNode</code> is an ancestor of

   449      *   the container.

   450      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already

   451      *   been invoked on this object.

   452      * @exception DOMRangeException

   453      *   INVALID_NODE_TYPE_ERR: Raised if <code>newNode</code> is an DOMAttr,

   454      *   DOMEntity, DOMNotation, or DOMDocument node.

   455      *

   456      * @since DOM Level 2

   457      */

   458     virtual void insertNode(DOMNode *newNode) = 0;

   459 

   460     /**

   461      * Reparents the contents of the Range to the given node and inserts the

   462      * node at the position of the start of the Range.

   463      * @param newParent The node to surround the contents with.

   464      * @exception DOMException

   465      *   NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of

   466      *   either boundary-point of the Range is read-only.

   467      *   <br>WRONG_DOCUMENT_ERR: Raised if <code> newParent</code> and the

   468      *   container of the start of the Range were not created from the same

   469      *   document.

   470      *   <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of

   471      *   the Range is of a type that does not allow children of the type of

   472      *   <code>newParent</code> or if <code>newParent</code> is an ancestor

   473      *   of the container or if <code>node</code> would end up with a child

   474      *   node of a type not allowed by the type of <code>node</code>.

   475      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already

   476      *   been invoked on this object.

   477      * @exception DOMRangeException

   478      *   BAD_BOUNDARYPOINTS_ERR: Raised if the Range partially selects a

   479      *   non-text node.

   480      *   <br>INVALID_NODE_TYPE_ERR: Raised if <code> node</code> is an DOMAttr,

   481      *   DOMEntity, DOMDocumentType, DOMNotation, DOMDocument, or DOMDocumentFragment node.

   482      *

   483      * @since DOM Level 2

   484      */

   485     virtual void surroundContents(DOMNode *newParent) = 0;

   486 

   487     /**

   488      * Produces a new Range whose boundary-points are equal to the

   489      * boundary-points of the Range.

   490      * @return The duplicated Range.

   491      * @exception DOMException

   492      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been

   493      *   invoked on this object.

   494      *

   495      * @since DOM Level 2

   496      */

   497     virtual DOMRange* cloneRange() const = 0;

   498 

   499     /**

   500      * Returns the contents of a Range as a string. This string contains only

   501      * the data characters, not any markup.

   502      * @return The contents of the Range.

   503      * @exception DOMException

   504      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been

   505      *   invoked on this object.

   506      *

   507      * @since DOM Level 2

   508      */

   509     virtual const XMLCh* toString() const = 0;

   510 

   511     /**

   512      * Called to indicate that the Range is no longer in use and that the

   513      * implementation may relinquish any resources associated with this

   514      * Range. Subsequent calls to any methods or attribute getters on this

   515      * Range will result in a <code>DOMException</code> being thrown with an

   516      * error code of <code>INVALID_STATE_ERR</code>.

   517      * @exception DOMException

   518      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been

   519      *   invoked on this object.

   520      *

   521      * @since DOM Level 2

   522      */

   523     virtual void detach() = 0;

   524 

   525     //@}

   526 

   527     // -----------------------------------------------------------------------

   528     //  Non-standard Extension

   529     // -----------------------------------------------------------------------

   530     /** @name Non-standard Extension */

   531     //@{

   532     /**

   533      * Called to indicate that this Range is no longer in use

   534      * and that the implementation may relinquish any resources associated with it.

   535      * (release() will call detach() where appropriate)

   536      *

   537      * Access to a released object will lead to unexpected result.

   538      */

   539     virtual void release() = 0;

   540     //@}

   541 };

   542 

   543 

   544 XERCES_CPP_NAMESPACE_END

   545 

   546 #endif