khtml/dom/dom_text.h

   1 /*
   2  * This file is part of the DOM implementation for KDE.
   3  *
   4  * Copyright 1999 Lars Knoll (knoll@kde.org)
   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  * http://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 class DOMString;
  37 class CharacterDataImpl;
  38
  39 /**
  40  * The \c CharacterData interface extends Node with a set
  41  * of attributes and methods for accessing character data in the DOM.
  42  * For clarity this set is defined here rather than on each object
  43  * that uses these attributes and methods. No DOM objects correspond
  44  * directly to \c CharacterData , though \c Text
  45  * and others do inherit the interface from it. All
  46  * <code>offset</code>s in this interface start from 0.
  47  *
  48  */
  49 class KHTML_EXPORT CharacterData : public Node
  50 {
  51     friend class CharacterDataImpl;
  52
  53 public:
  54     CharacterData();
  55     CharacterData(const CharacterData &other);
  56     CharacterData(const Node &other) : Node()
  57          {(*this)=other;}
  58
  59     CharacterData & operator = (const Node &other);
  60     CharacterData & operator = (const CharacterData &other);
  61
  62     ~CharacterData();
  63
  64     /**
  65      * The character data of the node that implements this interface.
  66      * The DOM implementation may not put arbitrary limits on the
  67      * amount of data that may be stored in a \c CharacterData
  68      * node. However, implementation limits may mean that the
  69      * entirety of a node's data may not fit into a single
  70      * \c DOMString . In such cases, the user may call
  71      * \c substringData to retrieve the data in appropriately
  72      * sized pieces.
  73      *
  74      * @exception DOMException
  75      * DOMSTRING_SIZE_ERR: Raised when it would return more characters
  76      * than fit in a \c DOMString variable on the
  77      * implementation platform.
  78      *
  79      */
  80     DOMString data() const;
  81
  82     /**
  83      * see data
  84      * @exception DOMException
  85      * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
  86      *
  87      */
  88     void setData( const DOMString & );
  89
  90     /**
  91      * The number of characters that are available through \c data
  92      * and the \c substringData method below. This
  93      * may have the value zero, i.e., \c CharacterData
  94      * nodes may be empty.
  95      *
  96      */
  97     unsigned long length() const;
  98
  99     /**
 100      * Extracts a range of data from the node.
 101      *
 102      * @param offset Start offset of substring to extract.
 103      *
 104      * @param count The number of characters to extract.
 105      *
 106      * @return The specified substring. If the sum of \c offset
 107      * and \c count exceeds the \c length
 108      *  , then all characters to the end of the data are
 109      * returned.
 110      *
 111      * @exception DOMException
 112      * INDEX_SIZE_ERR: Raised if the specified offset is negative or
 113      * greater than the number of characters in \c data ,
 114      * or if the specified \c count is negative.
 115      *
 116      *  DOMSTRING_SIZE_ERR: Raised if the specified range of text does
 117      * not fit into a \c DOMString .
 118      *
 119      */
 120     DOMString substringData ( const unsigned long offset, const unsigned long count );
 121
 122     /**
 123      * Append the string to the end of the character data of the node.
 124      * Upon success, \c data provides access to the
 125      * concatenation of \c data and the \c DOMString
 126      * specified.
 127      *
 128      * @param arg The \c DOMString to append.
 129      *
 130      * @return
 131      *
 132      * @exception DOMException
 133      * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
 134      *
 135      */
 136     void appendData ( const DOMString &arg );
 137
 138     /**
 139      * Insert a string at the specified character offset.
 140      *
 141      * @param offset The character offset at which to insert.
 142      *
 143      * @param arg The \c DOMString to insert.
 144      *
 145      * @return
 146      *
 147      * @exception DOMException
 148      * INDEX_SIZE_ERR: Raised if the specified offset is negative or
 149      * greater than the number of characters in \c data .
 150      *
 151      *  NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
 152      *
 153      */
 154     void insertData ( const unsigned long offset, const DOMString &arg );
 155
 156     /**
 157      * Remove a range of characters from the node. Upon success,
 158      * \c data and \c length reflect the
 159      * change.
 160      *
 161      * @param offset The offset from which to remove characters.
 162      *
 163      * @param count The number of characters to delete. If the sum of
 164      * \c offset and \c count exceeds
 165      * \c length then all characters from \c offset
 166      * to the end of the data are deleted.
 167      *
 168      * @return
 169      *
 170      * @exception DOMException
 171      * INDEX_SIZE_ERR: Raised if the specified offset is negative or
 172      * greater than the number of characters in \c data ,
 173      * or if the specified \c count is negative.
 174      *
 175      *  NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
 176      *
 177      */
 178     void deleteData ( const unsigned long offset, const unsigned long count );
 179
 180     /**
 181      * Replace the characters starting at the specified character
 182      * offset with the specified string.
 183      *
 184      * @param offset The offset from which to start replacing.
 185      *
 186      * @param count The number of characters to replace. If the sum of
 187      * \c offset and \c count exceeds
 188      * \c length , then all characters to the end of the data are
 189      * replaced (i.e., the effect is the same as a \c remove
 190      * method call with the same range, followed by an
 191      * \c append method invocation).
 192      *
 193      * @param arg The \c DOMString with which the range
 194      * must be replaced.
 195      *
 196      * @return
 197      *
 198      * @exception DOMException
 199      * INDEX_SIZE_ERR: Raised if the specified offset is negative or
 200      * greater than the number of characters in \c data ,
 201      * or if the specified \c count is negative.
 202      *
 203      *  NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
 204      *
 205      */
 206     void replaceData ( const unsigned long offset, const unsigned long count, const DOMString &arg );
 207
 208 protected:
 209     CharacterData(CharacterDataImpl *i);
 210 };
 211
 212
 213 class CommentImpl;
 214
 215 /**
 216  * This represents the content of a comment, i.e., all the characters
 217  * between the starting ' \c &lt;!-- ' and ending '
 218  * \c --&gt; '. Note that this is the definition of a comment in
 219  * XML, and, in practice, HTML, although some HTML tools may implement
 220  * the full SGML comment structure.
 221  *
 222  */
 223 class KHTML_EXPORT Comment : public CharacterData
 224 {
 225     friend class Document;
 226     friend class TextImpl;
 227
 228 public:
 229     Comment();
 230     Comment(const Comment &other);
 231     Comment(const Node &other) : CharacterData()
 232          {(*this)=other;}
 233
 234     Comment & operator = (const Node &other);
 235     Comment & operator = (const Comment &other);
 236
 237     ~Comment();
 238
 239 protected:
 240     Comment(CommentImpl *i);
 241 };
 242
 243 class TextImpl;
 244
 245 /**
 246  * The \c Text interface represents the textual content
 247  * (termed <a href="&xml-spec;#syntax"> character data </a> in XML) of
 248  * an \c Element or \c Attr . If there is no
 249  * markup inside an element's content, the text is contained in a
 250  * single object implementing the \c Text interface that
 251  * is the only child of the element. If there is markup, it is parsed
 252  * into a list of elements and \c Text nodes that form the
 253  * list of children of the element.
 254  *
 255  *  When a document is first made available via the DOM, there is only
 256  * one \c Text node for each block of text. Users may
 257  * create adjacent \c Text nodes that represent the
 258  * contents of a given element without any intervening markup, but
 259  * should be aware that there is no way to represent the separations
 260  * between these nodes in XML or HTML, so they will not (in general)
 261  * persist between DOM editing sessions. The \c normalize()
 262  * method on \c Element merges any such adjacent
 263  * \c Text objects into a single node for each block of
 264  * text; this is recommended before employing operations that depend
 265  * on a particular document structure, such as navigation with
 266  * \c XPointers.
 267  *
 268  */
 269 class KHTML_EXPORT Text : public CharacterData
 270 {
 271     friend class Document;
 272     friend class TextImpl;
 273
 274 public:
 275     Text();
 276     Text(const Text &other);
 277     Text(const Node &other) : CharacterData()
 278          {(*this)=other;}
 279
 280     Text & operator = (const Node &other);
 281     Text & operator = (const Text &other);
 282
 283     ~Text();
 284
 285     /**
 286      * Breaks this \c Text node into two Text nodes at the
 287      * specified offset, keeping both in the tree as siblings. This
 288      * node then only contains all the content up to the \c offset
 289      * point. And a new \c Text node, which is
 290      * inserted as the next sibling of this node, contains all the
 291      * content at and after the \c offset point.
 292      *
 293      * @param offset The offset at which to split, starting from 0.
 294      *
 295      * @return The new \c Text node.
 296      *
 297      * @exception DOMException
 298      * INDEX_SIZE_ERR: Raised if the specified offset is negative or
 299      * greater than the number of characters in \c data .
 300      *
 301      *  NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
 302      *
 303      */
 304     Text splitText ( const unsigned long offset );
 305
 306 protected:
 307     Text(TextImpl *i);
 308
 309 };
 310
 311 } //namespace
 312 #endif