source: icXML/icXML-devel/src/xercesc/dom/DOMRange.hpp @ 2722

Last change on this file since 2722 was 2722, checked in by cameron, 6 years ago

Original Xerces files with import mods for icxercesc

File size: 21.1 KB
Line 
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
27XERCES_CPP_NAMESPACE_BEGIN
28
29class DOMNode;
30class 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 */
36class CDOM_EXPORT DOMRange {
37protected:
38    // -----------------------------------------------------------------------
39    //  Hidden constructors
40    // -----------------------------------------------------------------------
41    /** @name Hidden constructors */
42    //@{   
43    DOMRange() {}
44    DOMRange(const DOMRange &) {}
45    //@}
46
47private:
48    // -----------------------------------------------------------------------
49    // Unimplemented constructors and operators
50    // -----------------------------------------------------------------------
51    /** @name Unimplemented operators */
52    //@{
53    DOMRange & operator = (const DOMRange &);
54    //@}
55
56public:
57    // -----------------------------------------------------------------------
58    //  All constructors are hidden, just the destructor is available
59    // -----------------------------------------------------------------------
60    /** @name Destructor */
61    //@{
62    /**
63     * Destructor
64     *
65     */
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
528XERCES_CPP_NAMESPACE_END
529
530#endif
Note: See TracBrowser for help on using the repository browser.