KHtml

dom_text.h
1 /*
2  * This file is part of the DOM implementation for KDE.
3  *
4  * Copyright 1999 Lars Knoll ([email protected])
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Library General Public
8  * License as published by the Free Software Foundation; either
9  * version 2 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Library General Public License for more details.
15  *
16  * You should have received a copy of the GNU Library General Public License
17  * along with this library; see the file COPYING.LIB. If not, write to
18  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19  * Boston, MA 02110-1301, USA.
20  *
21  * This file includes excerpts from the Document Object Model (DOM)
22  * Level 1 Specification (Recommendation)
23  * https://www.w3.org/TR/REC-DOM-Level-1/
24  * Copyright © World Wide Web Consortium , (Massachusetts Institute of
25  * Technology , Institut National de Recherche en Informatique et en
26  * Automatique , Keio University ). All Rights Reserved.
27  *
28  */
29 #ifndef _DOM_CharacterData_h_
30 #define _DOM_CharacterData_h_
31 
32 #include <dom/dom_node.h>
33 
34 namespace DOM
35 {
36 
37 class DOMString;
38 class CharacterDataImpl;
39 
40 /**
41  * The \c CharacterData interface extends Node with a set
42  * of attributes and methods for accessing character data in the DOM.
43  * For clarity this set is defined here rather than on each object
44  * that uses these attributes and methods. No DOM objects correspond
45  * directly to \c CharacterData , though \c Text
46  * and others do inherit the interface from it. All
47  * <code>offset</code>s in this interface start from 0.
48  *
49  */
50 class KHTML_EXPORT CharacterData : public Node
51 {
52  friend class CharacterDataImpl;
53 
54 public:
55  CharacterData();
56  CharacterData(const CharacterData &other);
57  CharacterData(const Node &other) : Node()
58  {
59  (*this) = other;
60  }
61 
62  CharacterData &operator = (const Node &other);
63  CharacterData &operator = (const CharacterData &other);
64 
65  ~CharacterData();
66 
67  /**
68  * The character data of the node that implements this interface.
69  * The DOM implementation may not put arbitrary limits on the
70  * amount of data that may be stored in a \c CharacterData
71  * node. However, implementation limits may mean that the
72  * entirety of a node's data may not fit into a single
73  * \c DOMString . In such cases, the user may call
74  * \c substringData to retrieve the data in appropriately
75  * sized pieces.
76  *
77  * @exception DOMException
78  * DOMSTRING_SIZE_ERR: Raised when it would return more characters
79  * than fit in a \c DOMString variable on the
80  * implementation platform.
81  *
82  */
83  DOMString data() const;
84 
85  /**
86  * see data
87  * @exception DOMException
88  * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
89  *
90  */
91  void setData(const DOMString &);
92 
93  /**
94  * The number of characters that are available through \c data
95  * and the \c substringData method below. This
96  * may have the value zero, i.e., \c CharacterData
97  * nodes may be empty.
98  *
99  */
100  unsigned long length() const;
101 
102  /**
103  * Extracts a range of data from the node.
104  *
105  * @param offset Start offset of substring to extract.
106  *
107  * @param count The number of characters to extract.
108  *
109  * @return The specified substring. If the sum of \c offset
110  * and \c count exceeds the \c length
111  * , then all characters to the end of the data are
112  * returned.
113  *
114  * @exception DOMException
115  * INDEX_SIZE_ERR: Raised if the specified offset is negative or
116  * greater than the number of characters in \c data ,
117  * or if the specified \c count is negative.
118  *
119  * DOMSTRING_SIZE_ERR: Raised if the specified range of text does
120  * not fit into a \c DOMString .
121  *
122  */
123  DOMString substringData(const unsigned long offset, const unsigned long count);
124 
125  /**
126  * Append the string to the end of the character data of the node.
127  * Upon success, \c data provides access to the
128  * concatenation of \c data and the \c DOMString
129  * specified.
130  *
131  * @param arg The \c DOMString to append.
132  *
133  * @return
134  *
135  * @exception DOMException
136  * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
137  *
138  */
139  void appendData(const DOMString &arg);
140 
141  /**
142  * Insert a string at the specified character offset.
143  *
144  * @param offset The character offset at which to insert.
145  *
146  * @param arg The \c DOMString to insert.
147  *
148  * @return
149  *
150  * @exception DOMException
151  * INDEX_SIZE_ERR: Raised if the specified offset is negative or
152  * greater than the number of characters in \c data .
153  *
154  * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
155  *
156  */
157  void insertData(const unsigned long offset, const DOMString &arg);
158 
159  /**
160  * Remove a range of characters from the node. Upon success,
161  * \c data and \c length reflect the
162  * change.
163  *
164  * @param offset The offset from which to remove characters.
165  *
166  * @param count The number of characters to delete. If the sum of
167  * \c offset and \c count exceeds
168  * \c length then all characters from \c offset
169  * to the end of the data are deleted.
170  *
171  * @return
172  *
173  * @exception DOMException
174  * INDEX_SIZE_ERR: Raised if the specified offset is negative or
175  * greater than the number of characters in \c data ,
176  * or if the specified \c count is negative.
177  *
178  * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
179  *
180  */
181  void deleteData(const unsigned long offset, const unsigned long count);
182 
183  /**
184  * Replace the characters starting at the specified character
185  * offset with the specified string.
186  *
187  * @param offset The offset from which to start replacing.
188  *
189  * @param count The number of characters to replace. If the sum of
190  * \c offset and \c count exceeds
191  * \c length , then all characters to the end of the data are
192  * replaced (i.e., the effect is the same as a \c remove
193  * method call with the same range, followed by an
194  * \c append method invocation).
195  *
196  * @param arg The \c DOMString with which the range
197  * must be replaced.
198  *
199  * @return
200  *
201  * @exception DOMException
202  * INDEX_SIZE_ERR: Raised if the specified offset is negative or
203  * greater than the number of characters in \c data ,
204  * or if the specified \c count is negative.
205  *
206  * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
207  *
208  */
209  void replaceData(const unsigned long offset, const unsigned long count, const DOMString &arg);
210 
211 protected:
212  CharacterData(CharacterDataImpl *i);
213 };
214 
215 class CommentImpl;
216 
217 /**
218  * This represents the content of a comment, i.e., all the characters
219  * between the starting ' \c &lt;!-- ' and ending '
220  * \c --&gt; '. Note that this is the definition of a comment in
221  * XML, and, in practice, HTML, although some HTML tools may implement
222  * the full SGML comment structure.
223  *
224  */
225 class KHTML_EXPORT Comment : public CharacterData
226 {
227  friend class Document;
228  friend class TextImpl;
229 
230 public:
231  Comment();
232  Comment(const Comment &other);
233  Comment(const Node &other) : CharacterData()
234  {
235  (*this) = other;
236  }
237 
238  Comment &operator = (const Node &other);
239  Comment &operator = (const Comment &other);
240 
241  ~Comment();
242 
243 protected:
244  Comment(CommentImpl *i);
245 };
246 
247 class TextImpl;
248 
249 /**
250  * The \c Text interface represents the textual content
251  * (termed <a href="&xml-spec;#syntax"> character data </a> in XML) of
252  * an \c Element or \c Attr . If there is no
253  * markup inside an element's content, the text is contained in a
254  * single object implementing the \c Text interface that
255  * is the only child of the element. If there is markup, it is parsed
256  * into a list of elements and \c Text nodes that form the
257  * list of children of the element.
258  *
259  * When a document is first made available via the DOM, there is only
260  * one \c Text node for each block of text. Users may
261  * create adjacent \c Text nodes that represent the
262  * contents of a given element without any intervening markup, but
263  * should be aware that there is no way to represent the separations
264  * between these nodes in XML or HTML, so they will not (in general)
265  * persist between DOM editing sessions. The \c normalize()
266  * method on \c Element merges any such adjacent
267  * \c Text objects into a single node for each block of
268  * text; this is recommended before employing operations that depend
269  * on a particular document structure, such as navigation with
270  * \c XPointers.
271  *
272  */
273 class KHTML_EXPORT Text : public CharacterData
274 {
275  friend class Document;
276  friend class TextImpl;
277 
278 public:
279  Text();
280  Text(const Text &other);
281  Text(const Node &other) : CharacterData()
282  {
283  (*this) = other;
284  }
285 
286  Text &operator = (const Node &other);
287  Text &operator = (const Text &other);
288 
289  ~Text();
290 
291  /**
292  * Breaks this \c Text node into two Text nodes at the
293  * specified offset, keeping both in the tree as siblings. This
294  * node then only contains all the content up to the \c offset
295  * point. And a new \c Text node, which is
296  * inserted as the next sibling of this node, contains all the
297  * content at and after the \c offset point.
298  *
299  * @param offset The offset at which to split, starting from 0.
300  *
301  * @return The new \c Text node.
302  *
303  * @exception DOMException
304  * INDEX_SIZE_ERR: Raised if the specified offset is negative or
305  * greater than the number of characters in \c data .
306  *
307  * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
308  *
309  */
310  Text splitText(const unsigned long offset);
311 
312 protected:
313  Text(TextImpl *i);
314 
315 };
316 
317 } //namespace
318 #endif
The Node interface is the primary datatype for the entire Document Object Model.
Definition: dom_node.h:278
This represents the content of a comment, i.e., all the characters between the starting &#39; <!– &#39; and ...
Definition: dom_text.h:225
The Text interface represents the textual content (termed character data in XML) of an Element or At...
Definition: dom_text.h:273
This class implements the basic string we use in the DOM.
Definition: dom_string.h:44
The Document interface represents the entire HTML or XML document.
Definition: dom_doc.h:246
This library provides a full-featured HTML parser and widget.
The CharacterData interface extends Node with a set of attributes and methods for accessing character...
Definition: dom_text.h:50
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Oct 26 2021 22:48:01 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.