KHtml

dom2_range.h
1 /*
2  * This file is part of the DOM implementation for KDE.
3  *
4  * Copyright 1999 Lars Knoll ([email protected])
5  * Copyright 2000 Gunnstein Lye ([email protected])
6  * Copyright 2000 Frederik Holljen ([email protected])
7  * Copyright 2001 Peter Kelly ([email protected])
8  *
9  * This library is free software; you can redistribute it and/or
10  * modify it under the terms of the GNU Library General Public
11  * License as published by the Free Software Foundation; either
12  * version 2 of the License, or (at your option) any later version.
13  *
14  * This library is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17  * Library General Public License for more details.
18  *
19  * You should have received a copy of the GNU Library General Public License
20  * along with this library; see the file COPYING.LIB. If not, write to
21  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
22  * Boston, MA 02110-1301, USA.
23  *
24  * This file includes excerpts from the Document Object Model (DOM)
25  * Level 2 Specification (Candidate Recommendation)
26  * https://www.w3.org/TR/2000/CR-DOM-Level-2-20000510/
27  * Copyright © 2000 W3C® (MIT, INRIA, Keio), All Rights Reserved.
28  *
29  */
30 #ifndef _dom2_range_h_
31 #define _dom2_range_h_
32 
33 #include <dom/dom_doc.h>
34 #include <dom/dom_misc.h>
35 
36 namespace DOM
37 {
38 
39 class DocumentFragment;
40 class Node;
41 class DOMString;
42 class DocumentImpl;
43 class RangeImpl;
44 
45 class DOMException;
46 
47 // Introduced in DOM Level 2:
48 class KHTML_EXPORT RangeException
49 {
50 public:
51  RangeException(unsigned short _code)
52  {
53  code = _code;
54  }
55  RangeException(const RangeException &other)
56  {
57  code = other.code;
58  }
59 
60  RangeException &operator = (const RangeException &other)
61  {
62  code = other.code;
63  return *this;
64  }
65 
66  virtual ~RangeException() {}
67  /**
68  * An integer indicating the type of error generated.
69  *
70  */
71  enum RangeExceptionCode {
72  BAD_BOUNDARYPOINTS_ERR = 1,
73  INVALID_NODE_TYPE_ERR = 2,
74  _EXCEPTION_OFFSET = 2000,
75  _EXCEPTION_MAX = 2999
76  };
77  unsigned short code;
78 
79  /// Returns the name of this error
80  DOMString codeAsString() const;
81 
82  /// Returns the name of given DOM error code
83  static DOMString codeAsString(int rangeCode);
84 
85  /** @internal - checks to see whether internal code is a Range one */
86  static bool isRangeExceptionCode(int exceptioncode);
87 };
88 
89 class KHTML_EXPORT Range
90 {
91  friend class DocumentImpl;
92  friend class Document;
93  friend class RangeImpl;
94 public:
95  Range();
96  Range(const Document rootContainer);
97  Range(const Range &other);
98  Range(const Node startContainer, const long startOffset, const Node endContainer, const long endOffset);
99 
100  Range &operator = (const Range &other);
101 
102  ~Range();
103 
104  /**
105  * Node within which the range begins
106  *
107  */
108  Node startContainer() const;
109 
110  /**
111  * Offset within the starting node of the range.
112  *
113  */
114  long startOffset() const;
115 
116  /**
117  * Node within which the range ends
118  *
119  */
120  Node endContainer() const;
121 
122  /**
123  * Offset within the ending node of the range.
124  *
125  */
126  long endOffset() const;
127 
128  /**
129  * true if the range is collapsed
130  *
131  */
132  bool collapsed() const;
133 
134  /**
135  * Gets the common ancestor container of the range's two end-points.
136  * Also sets it.
137  *
138  */
139  // ### BIC make const in the next release
140  Node commonAncestorContainer();
141 
142  /**
143  * Sets the attributes describing the start of the range.
144  *
145  * @param refNode The \c refNode value. This parameter
146  * must be different from \c null .
147  *
148  * @param offset The \c startOffset value.
149  *
150  * @return
151  *
152  * @exception RangeException
153  * NULL_NODE_ERR: Raised if \c refNode is \c null .
154  *
155  * INVALID_NODE_TYPE_ERR: Raised if \c refNode or an
156  * ancestor of \c refNode is an Attr, Entity,
157  * Notation, or DocumentType node.
158  *
159  * If an offset is out-of-bounds, should it just be fixed up or
160  * should an exception be raised.
161  *
162  */
163  void setStart(const Node &refNode, long offset);
164 
165  /**
166  * Sets the attributes describing the end of a range.
167  *
168  * @param refNode The \c refNode value. This parameter
169  * must be different from \c null .
170  *
171  * @param offset The \c endOffset value.
172  *
173  * @return
174  *
175  * @exception RangeException
176  * NULL_NODE_ERR: Raised if \c refNode is \c null .
177  *
178  * INVALID_NODE_TYPE_ERR: Raised if \c refNode or an
179  * ancestor of \c refNode is an Attr, Entity,
180  * Notation, or DocumentType node.
181  *
182  */
183  void setEnd(const Node &refNode, long offset);
184 
185  /**
186  * Sets the start position to be before a node
187  *
188  * @param refNode Range starts before \c refNode
189  *
190  * @return
191  *
192  * @exception RangeException
193  * INVALID_NODE_TYPE_ERR: Raised if an ancestor of \c refNode
194  * is an Attr, Entity, Notation, or DocumentType node or
195  * if \c refNode is a Document, DocumentFragment,
196  * Attr, Entity, or Notation node.
197  *
198  */
199  void setStartBefore(const Node &refNode);
200 
201  /**
202  * Sets the start position to be after a node
203  *
204  * @param refNode Range starts after \c refNode
205  *
206  * @return
207  *
208  * @exception RangeException
209  * INVALID_NODE_TYPE_ERR: Raised if an ancestor of \c refNode
210  * is an Attr, Entity, Notation, or DocumentType node or
211  * if \c refNode is a Document, DocumentFragment,
212  * Attr, Entity, or Notation node.
213  *
214  */
215  void setStartAfter(const Node &refNode);
216 
217  /**
218  * Sets the end position to be before a node.
219  *
220  * @param refNode Range ends before \c refNode
221  *
222  * @return
223  *
224  * @exception RangeException
225  * INVALID_NODE_TYPE_ERR: Raised if an ancestor of \c refNode
226  * is an Attr, Entity, Notation, or DocumentType node or
227  * if \c refNode is a Document, DocumentFragment,
228  * Attr, Entity, or Notation node.
229  *
230  */
231  void setEndBefore(const Node &refNode);
232 
233  /**
234  * Sets the end of a range to be after a node
235  *
236  * @param refNode Range ends after \c refNode .
237  *
238  * @return
239  *
240  * @exception RangeException
241  * INVALID_NODE_TYPE_ERR: Raised if an ancestor of \c refNode
242  * is an Attr, Entity, Notation or DocumentType node or if
243  * \c refNode is a Document, DocumentFragment, Attr,
244  * Entity, or Notation node.
245  *
246  */
247  void setEndAfter(const Node &refNode);
248 
249  /**
250  * Collapse a range onto one of its end-points
251  *
252  * @param toStart If true, collapses the Range onto its start; if
253  * false, collapses it onto its end.
254  *
255  * @return
256  *
257  */
258  void collapse(bool toStart);
259 
260  /**
261  * Select a node and its contents
262  *
263  * @param refNode The node to select.
264  *
265  * @return
266  *
267  * @exception RangeException
268  * INVALID_NODE_TYPE_ERR: Raised if an ancestor of \c refNode
269  * is an Attr, Entity, Notation or DocumentType node or if
270  * \c refNode is a Document, DocumentFragment, Attr,
271  * Entity, or Notation node.
272  *
273  */
274  void selectNode(const Node &refNode);
275 
276  /**
277  * Select the contents within a node
278  *
279  * @param refNode Node to select from
280  *
281  * @return
282  *
283  * @exception RangeException
284  * INVALID_NODE_TYPE_ERR: Raised if \c refNode or an
285  * ancestor of \c refNode is an Attr, Entity, Notation
286  * or DocumentType node.
287  *
288  */
289  void selectNodeContents(const Node &refNode);
290 
291  enum CompareHow {
292  START_TO_START = 0,
293  START_TO_END = 1,
294  END_TO_END = 2,
295  END_TO_START = 3
296  };
297 
298  /**
299  * Compare the end-points of two ranges in a document.
300  *
301  * @param how
302  *
303  * @param sourceRange
304  *
305  * @return -1, 0 or 1 depending on whether the corresponding
306  * end-point of the Range is before, equal to, or after the
307  * corresponding end-point of \c sourceRange .
308  *
309  * @exception DOMException
310  * WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the
311  * same document or document fragment.
312  *
313  */
314  short compareBoundaryPoints(CompareHow how, const Range &sourceRange);
315 
316  /**
317  * @internal
318  * not part of the DOM
319  *
320  * Compare the boundary-points of a range.
321  *
322  * Return true if the startContainer is before the endContainer,
323  * or if they are equal.
324  * Return false if the startContainer is after the endContainer.
325  *
326  */
327  bool boundaryPointsValid();
328 
329  /**
330  * Removes the contents of a range from the containing document or
331  * document fragment without returning a reference to the removed
332  * content.
333  *
334  * @return
335  *
336  * @exception DOMException
337  * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the
338  * content of the range is read-only or any of the nodes that
339  * contain any of the content of the range are read-only.
340  *
341  */
342  void deleteContents();
343 
344  /**
345  * Moves the contents of a range from the containing document or
346  * document fragment to a new DocumentFragment.
347  *
348  * @return A DocumentFragment containing the extracted contents.
349  *
350  * @exception DOMException
351  * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the
352  * content of the range is read-only or any of the nodes which
353  * contain any of the content of the range are read-only.
354  *
355  * HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be
356  * extracted into the new DocumentFragment.
357  *
358  */
359  DocumentFragment extractContents();
360 
361  /**
362  * Duplicates the contents of a range
363  *
364  * @return A DocumentFragment containing contents equivalent to
365  * those of this range.
366  *
367  * @exception DOMException
368  * HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be
369  * extracted into the new DocumentFragment.
370  *
371  */
372  DocumentFragment cloneContents();
373 
374  /**
375  * Inserts a node into the document or document fragment at the
376  * start of the range.
377  *
378  * @param newNode The node to insert at the start of the range
379  *
380  * @return
381  *
382  * @exception DOMException
383  * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of
384  * the start of the range is read-only.
385  *
386  * WRONG_DOCUMENT_ERR: Raised if \c newNode and the
387  * container of the start of the Range were not created from the
388  * same document.
389  *
390  * HIERARCHY_REQUEST_ERR: Raised if the container of the start of
391  * the Range is of a type that does not allow children of the type
392  * of \c newNode or if \c newNode is an
393  * ancestor of the container .
394  *
395  * @exception RangeException
396  * INVALID_NODE_TYPE_ERR: Raised if \c node is an
397  * Attr, Entity, Notation, DocumentFragment, or Document node.
398  *
399  */
400  void insertNode(const Node &newNode);
401 
402  /**
403  * Reparents the contents of the range to the given node and
404  * inserts the node at the position of the start of the range.
405  *
406  * @param newParent The node to surround the contents with.
407  *
408  * @return
409  *
410  * @exception DOMException
411  * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of
412  * either end-point of the range is read-only.
413  *
414  * WRONG_DOCUMENT_ERR: Raised if \c newParent and the
415  * container of the start of the Range were not created from the
416  * same document.
417  *
418  * HIERARCHY_REQUEST_ERR: Raised if the container of the start of
419  * the Range is of a type that does not allow children of the type
420  * of \c newParent or if \c newParent is
421  * an ancestor of the container or if \c node would
422  * end up with a child node of a type not allowed by the type of
423  * \c node .
424  *
425  * @exception RangeException
426  * BAD_ENDPOINTS_ERR: Raised if the range partially selects a
427  * non-text node.
428  *
429  * INVALID_NODE_TYPE_ERR: Raised if \c node is an
430  * Attr, Entity, DocumentType, Notation, Document, or
431  * DocumentFragment node.
432  *
433  */
434  void surroundContents(const Node &newParent);
435 
436  /**
437  * Produces a new range whose end-points are equal to the
438  * end-points of the range.
439  *
440  * @return The duplicated range.
441  *
442  */
443  Range cloneRange();
444 
445  /**
446  * Returns the contents of a range as a string.
447  *
448  * @return The contents of the range.
449  *
450  */
451  DOMString toString();
452 
453  /**
454  * @internal Not part of DOM
455  */
456  DOMString toHTML();
457 
458  /* Mozilla extension - only works for HTML documents. */
459  DocumentFragment createContextualFragment(const DOMString &html);
460 
461  /**
462  * Called to indicate that the range is no longer in use and that
463  * the implementation may relinquish any resources associated with
464  * this range. Subsequent calls to any methods or attribute getters
465  * on this range will result in a DOMException being thrown with an
466  * error code of INVALID_STATE_ERR.
467  *
468  */
469  void detach();
470 
471  /**
472  * not part of the DOM
473  * true if the range is detached
474  *
475  */
476  bool isDetached() const;
477 
478  /**
479  * @internal
480  * not part of the DOM
481  */
482  RangeImpl *handle() const;
483  bool isNull() const;
484  Range(RangeImpl *i);
485 protected:
486  RangeImpl *impl;
487 private:
488  void throwException(int exceptioncode) const;
489 };
490 
491 } // namespace
492 
493 #endif
This library provides a full-featured HTML parser and widget.
char * toString(const T &value)
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Oct 16 2021 22:47:52 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.