summaryrefslogtreecommitdiffstats
path: root/tdehtml/dom/dom_text.h
blob: c6f92fb1d5d2c77f569e0e7b4fce05f85227bd41 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
/*
 * This file is part of the DOM implementation for KDE.
 *
 * (C) 1999 Lars Knoll (knoll@kde.org)
 *
 * 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 1 Specification (Recommendation)
 * http://www.w3.org/TR/REC-DOM-Level-1/
 * Copyright © World Wide Web Consortium , (Massachusetts Institute of
 * Technology , Institut National de Recherche en Informatique et en
 * Automatique , Keio University ). All Rights Reserved.
 *
 */
#ifndef _DOM_CharacterData_h_
#define _DOM_CharacterData_h_

#include <dom/dom_node.h>

namespace DOM {

class DOMString;
class CharacterDataImpl;

/**
 * The \c CharacterData interface extends Node with a set
 * of attributes and methods for accessing character data in the DOM.
 * For clarity this set is defined here rather than on each object
 * that uses these attributes and methods. No DOM objects correspond
 * directly to \c CharacterData , though \c Text
 * and others do inherit the interface from it. All
 * <code>offset</code>s in this interface start from 0.
 *
 */
class KHTML_EXPORT CharacterData : public Node
{
    friend class CharacterDataImpl;

public:
    CharacterData();
    CharacterData(const CharacterData &other);
    CharacterData(const Node &other) : Node()
         {(*this)=other;}

    CharacterData & operator = (const Node &other);
    CharacterData & operator = (const CharacterData &other);

    ~CharacterData();

    /**
     * The character data of the node that implements this interface.
     * The DOM implementation may not put arbitrary limits on the
     * amount of data that may be stored in a \c CharacterData
     * node. However, implementation limits may mean that the
     * entirety of a node's data may not fit into a single
     * \c DOMString . In such cases, the user may call
     * \c substringData to retrieve the data in appropriately
     * sized pieces.
     *
     * @exception DOMException
     * DOMSTRING_SIZE_ERR: Raised when it would return more characters
     * than fit in a \c DOMString variable on the
     * implementation platform.
     *
     */
    DOMString data() const;

    /**
     * see data
     * @exception DOMException
     * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
     *
     */
    void setData( const DOMString & );

    /**
     * The number of characters that are available through \c data
     * and the \c substringData method below. This
     * may have the value zero, i.e., \c CharacterData
     * nodes may be empty.
     *
     */
    unsigned long length() const;

    /**
     * Extracts a range of data from the node.
     *
     * @param offset Start offset of substring to extract.
     *
     * @param count The number of characters to extract.
     *
     * @return The specified substring. If the sum of \c offset
     * and \c count exceeds the \c length
     *  , then all characters to the end of the data are
     * returned.
     *
     * @exception DOMException
     * INDEX_SIZE_ERR: Raised if the specified offset is negative or
     * greater than the number of characters in \c data ,
     * or if the specified \c count is negative.
     *
     *  DOMSTRING_SIZE_ERR: Raised if the specified range of text does
     * not fit into a \c DOMString .
     *
     */
    DOMString substringData ( const unsigned long offset, const unsigned long count );

    /**
     * Append the string to the end of the character data of the node.
     * Upon success, \c data provides access to the
     * concatenation of \c data and the \c DOMString
     * specified.
     *
     * @param arg The \c DOMString to append.
     *
     * @return
     *
     * @exception DOMException
     * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
     *
     */
    void appendData ( const DOMString &arg );

    /**
     * Insert a string at the specified character offset.
     *
     * @param offset The character offset at which to insert.
     *
     * @param arg The \c DOMString to insert.
     *
     * @return
     *
     * @exception DOMException
     * INDEX_SIZE_ERR: Raised if the specified offset is negative or
     * greater than the number of characters in \c data .
     *
     *  NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
     *
     */
    void insertData ( const unsigned long offset, const DOMString &arg );

    /**
     * Remove a range of characters from the node. Upon success,
     * \c data and \c length reflect the
     * change.
     *
     * @param offset The offset from which to remove characters.
     *
     * @param count The number of characters to delete. If the sum of
     * \c offset and \c count exceeds
     * \c length then all characters from \c offset
     * to the end of the data are deleted.
     *
     * @return
     *
     * @exception DOMException
     * INDEX_SIZE_ERR: Raised if the specified offset is negative or
     * greater than the number of characters in \c data ,
     * or if the specified \c count is negative.
     *
     *  NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
     *
     */
    void deleteData ( const unsigned long offset, const unsigned long count );

    /**
     * Replace the characters starting at the specified character
     * offset with the specified string.
     *
     * @param offset The offset from which to start replacing.
     *
     * @param count The number of characters to replace. If the sum of
     * \c offset and \c count exceeds
     * \c length , then all characters to the end of the data are
     * replaced (i.e., the effect is the same as a \c remove
     * method call with the same range, followed by an
     * \c append method invocation).
     *
     * @param arg The \c DOMString with which the range
     * must be replaced.
     *
     * @return
     *
     * @exception DOMException
     * INDEX_SIZE_ERR: Raised if the specified offset is negative or
     * greater than the number of characters in \c data ,
     * or if the specified \c count is negative.
     *
     *  NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
     *
     */
    void replaceData ( const unsigned long offset, const unsigned long count, const DOMString &arg );

protected:
    CharacterData(CharacterDataImpl *i);
};


class CommentImpl;

/**
 * This represents the content of a comment, i.e., all the characters
 * between the starting ' \c &lt;!-- ' and ending '
 * \c --&gt; '. Note that this is the definition of a comment in
 * XML, and, in practice, HTML, although some HTML tools may implement
 * the full SGML comment structure.
 *
 */
class KHTML_EXPORT Comment : public CharacterData
{
    friend class Document;
    friend class TextImpl;

public:
    Comment();
    Comment(const Comment &other);
    Comment(const Node &other) : CharacterData()
         {(*this)=other;}

    Comment & operator = (const Node &other);
    Comment & operator = (const Comment &other);

    ~Comment();

protected:
    Comment(CommentImpl *i);
};

class TextImpl;

/**
 * The \c Text interface represents the textual content
 * (termed <a href="&xml-spec;#syntax"> character data </a> in XML) of
 * an \c Element or \c Attr . If there is no
 * markup inside an element's content, the text is contained in a
 * single object implementing the \c Text interface that
 * is the only child of the element. If there is markup, it is parsed
 * into a list of elements and \c Text nodes that form the
 * list of children of the element.
 *
 *  When a document is first made available via the DOM, there is only
 * one \c Text node for each block of text. Users may
 * create adjacent \c Text nodes that represent the
 * contents of a given element without any intervening markup, but
 * should be aware that there is no way to represent the separations
 * between these nodes in XML or HTML, so they will not (in general)
 * persist between DOM editing sessions. The \c normalize()
 * method on \c Element merges any such adjacent
 * \c Text objects into a single node for each block of
 * text; this is recommended before employing operations that depend
 * on a particular document structure, such as navigation with
 * \c XPointers.
 *
 */
class KHTML_EXPORT Text : public CharacterData
{
    friend class Document;
    friend class TextImpl;

public:
    Text();
    Text(const Text &other);
    Text(const Node &other) : CharacterData()
         {(*this)=other;}

    Text & operator = (const Node &other);
    Text & operator = (const Text &other);

    ~Text();

    /**
     * Breaks this \c Text node into two Text nodes at the
     * specified offset, keeping both in the tree as siblings. This
     * node then only contains all the content up to the \c offset
     * point. And a new \c Text node, which is
     * inserted as the next sibling of this node, contains all the
     * content at and after the \c offset point.
     *
     * @param offset The offset at which to split, starting from 0.
     *
     * @return The new \c Text node.
     *
     * @exception DOMException
     * INDEX_SIZE_ERR: Raised if the specified offset is negative or
     * greater than the number of characters in \c data .
     *
     *  NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
     *
     */
    Text splitText ( const unsigned long offset );

protected:
    Text(TextImpl *i);

};

} //namespace
#endif