khtml/dom/dom_xml.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_XML_h
  30 #define _DOM_XML_h
  31
  32 #include <dom/dom_text.h>
  33 #include <dom/css_stylesheet.h>
  34
  35 namespace DOM {
  36
  37 class CDATASectionImpl;
  38 class EntityImpl;
  39 class EntityReferenceImpl;
  40 class NotationImpl;
  41 class ProcessingInstructionImpl;
  42
  43
  44
  45 /**
  46  * CDATA sections are used to escape blocks of text containing
  47  * characters that would otherwise be regarded as markup. The only
  48  * delimiter that is recognized in a CDATA section is the "]]&gt;"
  49  * string that ends the CDATA section. CDATA sections can not be
  50  * nested. The primary purpose is for including material such as XML
  51  * fragments, without needing to escape all the delimiters.
  52  *
  53  *  The \c DOMString attribute of the \c Text
  54  * node holds the text that is contained by the CDATA section. Note
  55  * that this may contain characters that need to be escaped outside of
  56  * CDATA sections and that, depending on the character encoding
  57  * ("charset") chosen for serialization, it may be impossible to write
  58  * out some characters as part of a CDATA section.
  59  *
  60  *  The \c CDATASection interface inherits the
  61  * \c CharacterData interface through the \c Text
  62  * interface. Adjacent \c CDATASections nodes are not
  63  * merged by use of the Element.normalize() method.
  64  *
  65  */
  66 class KHTML_EXPORT CDATASection : public Text
  67 {
  68     friend class Document;
  69 public:
  70     CDATASection();
  71     CDATASection(const CDATASection &other);
  72     CDATASection(const Node &other) : Text()
  73          {(*this)=other;}
  74
  75     CDATASection & operator = (const Node &other);
  76     CDATASection & operator = (const CDATASection &other);
  77
  78     ~CDATASection();
  79 protected:
  80     CDATASection(CDATASectionImpl *i);
  81 };
  82
  83 class DOMString;
  84
  85 /**
  86  * This interface represents an entity, either parsed or unparsed, in
  87  * an XML document. Note that this models the entity itself not the
  88  * entity declaration. \c Entity declaration modeling has
  89  * been left for a later Level of the DOM specification.
  90  *
  91  *  The \c nodeName attribute that is inherited from
  92  * \c Node contains the name of the entity.
  93  *
  94  *  An XML processor may choose to completely expand entities before
  95  * the structure model is passed to the DOM; in this case there will
  96  * be no \c EntityReference nodes in the document tree.
  97  *
  98  *  XML does not mandate that a non-validating XML processor read and
  99  * process entity declarations made in the external subset or declared
 100  * in external parameter entities. This means that parsed entities
 101  * declared in the external subset need not be expanded by some
 102  * classes of applications, and that the replacement value of the
 103  * entity may not be available. When the replacement value is
 104  * available, the corresponding \c Entity node's child
 105  * list represents the structure of that replacement text. Otherwise,
 106  * the child list is empty.
 107  *
 108  *  The resolution of the children of the \c Entity (the
 109  * replacement value) may be lazily evaluated; actions by the user
 110  * (such as calling the \c childNodes method on the
 111  * \c Entity Node) are assumed to trigger the evaluation.
 112  *
 113  *  The DOM Level 1 does not support editing \c Entity
 114  * nodes; if a user wants to make changes to the contents of an
 115  * \c Entity , every related \c EntityReference node
 116  * has to be replaced in the structure model by a clone of the
 117  * \c Entity 's contents, and then the desired changes must be
 118  * made to each of those clones instead. All the descendants of an
 119  * \c Entity node are readonly.
 120  *
 121  *  An \c Entity node does not have any parent.
 122  *
 123  */
 124 class KHTML_EXPORT Entity : public Node
 125 {
 126 public:
 127     Entity();
 128     Entity(const Entity &other);
 129     Entity(const Node &other) : Node()
 130          {(*this)=other;}
 131
 132     Entity & operator = (const Node &other);
 133     Entity & operator = (const Entity &other);
 134
 135     ~Entity();
 136
 137     /**
 138      * The public identifier associated with the entity, if specified.
 139      * If the public identifier was not specified, this is \c null .
 140      *
 141      */
 142     DOMString publicId() const;
 143
 144     /**
 145      * The system identifier associated with the entity, if specified.
 146      * If the system identifier was not specified, this is \c null .
 147      *
 148      */
 149     DOMString systemId() const;
 150
 151     /**
 152      * For unparsed entities, the name of the notation for the entity.
 153      * For parsed entities, this is \c null .
 154      *
 155      */
 156     DOMString notationName() const;
 157 protected:
 158     Entity(EntityImpl *i);
 159 };
 160
 161
 162 /**
 163  * \c EntityReference objects may be inserted into the
 164  * structure model when an entity reference is in the source document,
 165  * or when the user wishes to insert an entity reference. Note that
 166  * character references and references to predefined entities are
 167  * considered to be expanded by the HTML or XML processor so that
 168  * characters are represented by their Unicode equivalent rather than
 169  * by an entity reference. Moreover, the XML processor may completely
 170  * expand references to entities while building the structure model,
 171  * instead of providing \c EntityReference objects. If it
 172  * does provide such objects, then for a given \c EntityReference
 173  * node, it may be that there is no \c Entity node
 174  * representing the referenced entity; but if such an \c Entity
 175  * exists, then the child list of the \c EntityReference
 176  * node is the same as that of the \c Entity node.
 177  * As with the \c Entity node, all descendants of the
 178  * \c EntityReference are readonly.
 179  *
 180  *  The resolution of the children of the \c EntityReference
 181  * (the replacement value of the referenced \c Entity
 182  * ) may be lazily evaluated; actions by the user (such as
 183  * calling the \c childNodes method on the
 184  * \c EntityReference node) are assumed to trigger the
 185  * evaluation.
 186  *
 187  */
 188 class KHTML_EXPORT EntityReference : public Node
 189 {
 190     friend class Document;
 191 public:
 192     EntityReference();
 193     EntityReference(const EntityReference &other);
 194     EntityReference(const Node &other) : Node()
 195          {(*this)=other;}
 196
 197     EntityReference & operator = (const Node &other);
 198     EntityReference & operator = (const EntityReference &other);
 199
 200     ~EntityReference();
 201 protected:
 202     EntityReference(EntityReferenceImpl *i);
 203 };
 204
 205 class DOMString;
 206
 207 /**
 208  * This interface represents a notation declared in the DTD. A
 209  * notation either declares, by name, the format of an unparsed entity
 210  * (see section 4.7 of the XML 1.0 specification), or is used for
 211  * formal declaration of Processing Instruction targets (see section
 212  * 2.6 of the XML 1.0 specification). The \c nodeName
 213  * attribute inherited from \c Node is set to the declared
 214  * name of the notation.
 215  *
 216  *  The DOM Level 1 does not support editing \c Notation
 217  * nodes; they are therefore readonly.
 218  *
 219  *  A \c Notation node does not have any parent.
 220  *
 221  */
 222 class KHTML_EXPORT Notation : public Node
 223 {
 224 public:
 225     Notation();
 226     Notation(const Notation &other);
 227     Notation(const Node &other) : Node()
 228          {(*this)=other;}
 229
 230     Notation & operator = (const Node &other);
 231     Notation & operator = (const Notation &other);
 232
 233     ~Notation();
 234
 235     /**
 236      * The public identifier of this notation. If the public
 237      * identifier was not specified, this is \c null .
 238      *
 239      */
 240     DOMString publicId() const;
 241
 242     /**
 243      * The system identifier of this notation. If the system
 244      * identifier was not specified, this is \c null .
 245      *
 246      */
 247     DOMString systemId() const;
 248 protected:
 249     Notation(NotationImpl *i);
 250 };
 251
 252
 253 /**
 254  * The \c ProcessingInstruction interface represents a
 255  * &quot;processing instruction&quot;, used in XML as a way to keep
 256  * processor-specific information in the text of the document.
 257  *
 258  */
 259 class KHTML_EXPORT ProcessingInstruction : public Node
 260 {
 261     friend class Document;
 262 public:
 263     ProcessingInstruction();
 264     ProcessingInstruction(const ProcessingInstruction &other);
 265     ProcessingInstruction(const Node &other) : Node()
 266          {(*this)=other;}
 267
 268     ProcessingInstruction & operator = (const Node &other);
 269     ProcessingInstruction & operator = (const ProcessingInstruction &other);
 270
 271     ~ProcessingInstruction();
 272
 273     /**
 274      * The target of this processing instruction. XML defines this as
 275      * being the first token following the markup that begins the
 276      * processing instruction.
 277      *
 278      */
 279     DOMString target() const;
 280
 281     /**
 282      * The content of this processing instruction. This is from the
 283      * first non white space character after the target to the
 284      * character immediately preceding the \c ?&gt; .
 285      *
 286      */
 287     DOMString data() const;
 288
 289     /**
 290      * see data
 291      * @exception DOMException
 292      * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
 293      *
 294      */
 295     void setData( const DOMString & );
 296
 297     /**
 298      * Introduced in DOM Level 2
 299      * This method is from the LinkStyle interface
 300      *
 301      * The style sheet.
 302      */
 303     StyleSheet sheet() const;
 304
 305 protected:
 306     ProcessingInstruction(ProcessingInstructionImpl *i);
 307 };
 308
 309 } //namespace
 310 #endif