|
|
/* * 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., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, 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. * * $Id: dom__doc_h.html 132191 2002-01-17 21:32:13Z dfaure $ */ #ifndef _DOM_Document_h_ #define _DOM_Document_h_ #include#include class KHTMLView; class KHTMLPart; namespace DOM { class DOMString; class DocumentType; class NodeList; class CDATASection; class Comment; class DocumentFragment; class Text; class DOMImplementation; class Element; class Attr; class EntityReference; class ProcessingInstruction; class DocumentImpl; class Range; class NodeIterator; class TreeWalker; class NodeFilter; class DOMImplementationImpl; class DocumentTypeImpl; class Event; class AbstractView; class CSSStyleDeclaration; /** * The DOMImplementation
interface provides a number of * methods for performing operations that are independent of any * particular instance of the document object model. * * The DOM Level 1 does not specify a way of creating a document * instance, and hence document creation is an operation specific to * an implementation. Future Levels of the DOM specification are * expected to provide methods for creating documents directly. * */ class DOMImplementation { friend class Document; public: DOMImplementation(); DOMImplementation(const DOMImplementation &other); DOMImplementation & operator = (const DOMImplementation &other); ~DOMImplementation(); /** * Test if the DOM implementation implements a specific feature. * * @param feature The package name of the feature to test. In * Level 1, the legal values are "HTML" and "XML" * (case-insensitive). * * @param version This is the version number of the package name * to test. In Level 1, this is the string "1.0". If the version * is not specified, supporting any version of the feature will * cause the method to returntrue
. * * @returntrue
if the feature is implemented in * the specified version,false
otherwise. * */ bool hasFeature ( const DOMString &feature, const DOMString &version ); /** * Introduced in DOM Level 2 * This method is from the DOMImplementationCSS interface * * Creates a new CSSStyleSheet. * * @param title The advisory title. See also the Style Sheet Interfaces * section. * * media The comma-separated list of media associated with the new style * sheet. See also the Style Sheet Interfaces section. * * @return A new CSS style sheet. * * @exception SYNTAX_ERR: Raised if the specified media string value has a syntax error and is unparsable. */ CSSStyleSheet createCSSStyleSheet(const DOMString &title, const DOMString &media); /** * @internal * not part of the DOM */ DOMImplementationImpl *handle() const; bool isNull() const; protected: DOMImplementation(DOMImplementationImpl *i); DOMImplementationImpl *impl; }; /** * TheDocument
interface represents the entire HTML or * XML document. Conceptually, it is the root of the document tree, * and provides the primary access to the document's data. * * Since elements, text nodes, comments, processing instructions, * etc. cannot exist outside the context of aDocument
* , theDocument
interface also contains the factory * methods needed to create these objects. TheNode
* objects created have aownerDocument
attribute which * associates them with theDocument
within whose * context they were created. * */ class Document : public Node { friend class ::KHTMLView; friend class ::KHTMLPart; friend class AbstractView; public: Document(); /** * don't create an implementation if false * use at own risk */ Document(bool); Document(const Document &other); Document(const Node &other) : Node() {(*this)=other;} Document & operator = (const Node &other); Document & operator = (const Document &other); ~Document(); /** * The Document Type Declaration (seeDocumentType
* ) associated with this document. For HTML documents as well as * XML documents without a document type declaration this returns *null
. The DOM Level 1 does not support editing * the Document Type Declaration, thereforedocType
* cannot be altered in any way. * */ DocumentType doctype() const; /** * TheDOMImplementation
object that handles this * document. A DOM application may use objects from multiple * implementations. * */ DOMImplementation implementation() const; /** * This is a convenience attribute that allows direct access to * the child node that is the root element of the document. For * HTML documents, this is the element with the tagName "HTML". * */ Element documentElement() const; /** * Creates an element of the type specified. Note that the * instance returned implements the Element interface, so * attributes can be specified directly on the returned object. * * @param tagName The name of the element type to instantiate. For * XML, this is case-sensitive. For HTML, thetagName *
parameter may be provided in any case, but it must be * mapped to the canonical uppercase form by the DOM * implementation. * * @return A newElement
object. * * @exception DOMException * INVALID_CHARACTER_ERR: Raised if the specified name contains an * invalid character. * */ Element createElement ( const DOMString &tagName ); /** * Introduced in DOM Level 2 * Creates an element of the given qualified name and namespace URI. * * @param namespaceURI The namespace URI of the element to create. * * @param qualifiedName The qualified name of the element type to instantiate. * * @return A new Element object with the following attributes: * * @exception INVALID_CHARACTER_ERR Raised if the specified qualified name * contains an illegal character. * * @exception NAMESPACE_ERR Raised if the qualifiedName is malformed, if * the qualifiedName has a prefix and the namespaceURI is null, or if the * qualifiedName has a prefix that is "xml" and the namespaceURI is * different from "http://www.w3.org/XML/1998/namespace" */ Element createElementNS( const DOMString &namespaceURI, const DOMString &qualifiedName ); /** * Creates an emptyDocumentFragment
object. * * @return A newDocumentFragment
. * */ DocumentFragment createDocumentFragment ( ); /** * Creates aText
node given the specified string. * * @param data The data for the node. * * @return The newText
object. * */ Text createTextNode ( const DOMString &data ); /** * Creates aComment
node given the specified * string. * * @param data The data for the node. * * @return The newComment
object. * */ Comment createComment ( const DOMString &data ); /** * Creates aCDATASection
node whose value is the * specified string. * * @param data The data for theCDATASection
* contents. * * @return The newCDATASection
object. * * @exception DOMException * NOT_SUPPORTED_ERR: Raised if this document is an HTML document. * */ CDATASection createCDATASection ( const DOMString &data ); /** * Creates aProcessingInstruction
node given the * specified name and data strings. * * @param target The target part of the processing instruction. * * @param data The data for the node. * * @return The newProcessingInstruction
object. * * @exception DOMException * INVALID_CHARACTER_ERR: Raised if an invalid character is * specified. * * NOT_SUPPORTED_ERR: Raised if this document is an HTML * document. * */ ProcessingInstruction createProcessingInstruction ( const DOMString &target, const DOMString &data ); /** * Creates anAttr
of the given name. Note that the *Attr
instance can then be set on an* Element
using thesetAttribute
method. * * @param name The name of the attribute. * * @return A newAttr
object. * * @exception DOMException * INVALID_CHARACTER_ERR: Raised if the specified name contains an * invalid character. * */ Attr createAttribute ( const DOMString &name ); /** * Introduced in DOM Level 2 * Creates an attribute of the given qualified name and namespace URI. * HTML-only DOM implementations do not need to implement this method. * * @param namespaceURI The namespace URI of the attribute to create. * * @param qualifiedName The qualified name of the attribute to instantiate. * * @return A new Attr object with the following attributes: * Node.nodeName - qualifiedName * Node.namespaceURI - namespaceURI * Node.prefix - prefix, extracted from qualifiedName, or null if there is no prefix * Node.localName - local name, extracted from qualifiedName * Attr.name - qualifiedName * Node.nodeValue - the empty string * * @exception INVALID_CHARACTER_ERR Raised if the specified qualified name * contains an illegal character. * * @exception NAMESPACE_ERR Raised if the qualifiedName is malformed, if * the qualifiedName has a prefix and the namespaceURI is null, if the * qualifiedName has a prefix that is "xml" and the namespaceURI is * different from "http://www.w3.org/XML/1998/namespace", or if the * qualifiedName is "xmlns" and the namespaceURI is different from * "http://www.w3.org/2000/xmlns/". */ Attr createAttributeNS( const DOMString &namespaceURI, const DOMString &qualifiedName ); /** * Creates an EntityReference object. * * @param name The name of the entity to reference. * * @return The newEntityReference
object. * * @exception DOMException * INVALID_CHARACTER_ERR: Raised if the specified name contains an * invalid character. * * NOT_SUPPORTED_ERR: Raised if this document is an HTML * document. * */ EntityReference createEntityReference ( const DOMString &name ); /** * Returns aNodeList
of all theElement *
s with a given tag name in the order in which they * would be encountered in a preorder traversal of the* Document
tree. * * @param tagname The name of the tag to match on. The special * value "*" matches all tags. * * @return A newNodeList
object containing all the * matchedElement
s. * */ NodeList getElementsByTagName ( const DOMString &tagname ); /** * @internal * not part of the DOM */ bool isHTMLDocument() const; /** * Introduced in DOM Level 2 * This method is from the DocumentRange interface * * @return Range * The initial state of the Range returned from this method is such that * both of its boundary-points are positioned at the beginning of the * corresponding Document, before any content. The Range returned can only * be used to select content associated with this Document, or with * DocumentFragments and Attrs for which this Document is the ownerDocument. */ Range createRange(); /** * Introduced in DOM Level 2 * This method is from the DocumentTraversal interface * * Create a new NodeIterator over the subtree rooted at the specified node. * * @param root The node which will be iterated together with its children. * The iterator is initially positioned just before this node. The * whatToShow flags and the filter, if any, are not considered when setting * this position. The root must not be null. * * @param whatToShow This flag specifies which node types may appear in the * logical view of the tree presented by the iterator. See the description * of NodeFilter for the set of possible SHOW_ values. These flags can be * combined using OR. * * @param filter The NodeFilter to be used with this TreeWalker, or null to * indicate no filter. * * @param entityReferenceExpansion The value of this flag determines * whether entity reference nodes are expanded. * * @return NodeIterator The newly created NodeIterator. * * @exception DOMException * NOT_SUPPORTED_ERR: Raised if the specified root is null. */ NodeIterator createNodeIterator(Node root, unsigned long whatToShow, NodeFilter filter, bool entityReferenceExpansion); /** * Introduced in DOM Level 2 * This method is from the DocumentTraversal interface * * Create a new TreeWalker over the subtree rooted at the specified node. * * @param root The node which will serve as the root for the TreeWalker. * The whatToShow flags and the NodeFilter are not considered when setting * this value; any node type will be accepted as the root. The currentNode * of the TreeWalker is initialized to this node, whether or not it is * visible. The root functions as a stopping point for traversal methods * that look upward in the document structure, such as parentNode and * nextNode. The root must not be null. * * @param whatToShow This flag specifies which node types may appear in the * logical view of the tree presented by the tree-walker. See the * description of NodeFilter for the set of possible SHOW_ values. These * flags can be combined using OR. * * @param filter The NodeFilter to be used with this TreeWalker, or null to * indicate no filter. * * @param entityReferenceExpansion If this flag is false, the contents of * EntityReference nodes are not presented in the logical view. * * @return The newly created TreeWalker. * * @exception DOMException * NOT_SUPPORTED_ERR: Raised if the specified root is null. */ TreeWalker createTreeWalker(Node root, unsigned long whatToShow, NodeFilter filter, bool entityReferenceExpansion); /** * Introduced in DOM Level 2 * This method is from the DocumentEvent interface * * The createEvent method is used in creating Events when it is either * inconvenient or unnecessary for the user to create an Event themselves. * In cases where the implementation provided Event is insufficient, users * may supply their own Event implementations for use with the dispatchEvent method. * * @param eventType The eventType parameter specifies the type of Event * interface to be created. If the Event interface specified is supported * by the implementation this method will return a new Event of the * interface type requested. If the Event is to be dispatched via the * dispatchEvent method the appropriate event init method must be called * after creation in order to initialize the Event's values. As an example, * a user wishing to synthesize some kind of UIEvent would call createEvent * with the parameter "UIEvents". The initUIEvent method could then be * called on the newly created UIEvent to set the specific type of UIEvent * to be dispatched and set its context information. * * @return The newly created EventExceptions * * @exception DOMException * NOT_SUPPORTED_ERR: Raised if the implementation does not support the type of Event interface requested */ Event createEvent(const DOMString &eventType); /** * Introduced in DOM Level 2 * This method is from the DocumentView interface * * The default AbstractView for this Document, or null if none available. */ AbstractView defaultView() const; /** * Introduced in DOM Level 2 * This method is from the DocumentStyle interface * * A list containing all the style sheets explicitly linked into or * embedded in a document. For HTML documents, this includes external style * sheets, included via the HTML LINK element, and inline STYLE elements. * In XML, this includes external style sheets, included via style sheet * processing instructions (see [XML-StyleSheet]). */ StyleSheetList styleSheets() const; /** * @return The KHTML view widget of this document. */ KHTMLView *view() const; /** * Introduced in DOM Level 2 * This method is from the DocumentCSS interface * * This method is used to retrieve the override style declaration for a * specified element and a specified pseudo-element. * * @param elt The element whose style is to be modified. This parameter cannot be null. * * @param pseudoElt The pseudo-element or null if none. * * @return The override style declaration. */ CSSStyleDeclaration getOverrideStyle(const Element &elt, const DOMString &pseudoElt); protected: Document( DocumentImpl *i); friend class Node; }; class DocumentFragmentImpl; /** *DocumentFragment
is a "lightweight" or "minimal" *Document
object. It is very common to want to be * able to extract a portion of a document's tree or to create a new * fragment of a document. Imagine implementing a user command like * cut or rearranging a document by moving fragments around. It is * desirable to have an object which can hold such fragments and it is * quite natural to use a Node for this purpose. While it is true that * aDocument
object could fulfil this role, a* Document
object can potentially be a heavyweight object, * depending on the underlying implementation. What is really needed * for this is a very lightweight object.DocumentFragment *
is such an object. * * Furthermore, various operations -- such as inserting nodes as * children of anotherNode
-- may take* DocumentFragment
objects as arguments; this results in all * the child nodes of theDocumentFragment
being moved * to the child list of this node. * * The children of aDocumentFragment
node are zero or * more nodes representing the tops of any sub-trees defining the * structure of the document.DocumentFragment
nodes do * not need to be well-formed XML documents (although they do need to * follow the rules imposed upon well-formed XML parsed entities, * which can have multiple top nodes). For example, a* DocumentFragment
might have only one child and that child * node could be aText
node. Such a structure model * represents neither an HTML document nor a well-formed XML document. * * When aDocumentFragment
is inserted into a* Document
(or indeed any otherNode
that may * take children) the children of theDocumentFragment
* and not theDocumentFragment
itself are inserted * into theNode
. This makes the* DocumentFragment
very useful when the user wishes to create * nodes that are siblings; theDocumentFragment
acts * as the parent of these nodes so that the user can use the standard * methods from theNode
interface, such as* insertBefore()
andappendChild()
. * */ class DocumentFragment : public Node { friend class Document; friend class Range; public: DocumentFragment(); DocumentFragment(const DocumentFragment &other); DocumentFragment(const Node &other) : Node() {(*this)=other;} DocumentFragment & operator = (const Node &other); DocumentFragment & operator = (const DocumentFragment &other); ~DocumentFragment(); protected: DocumentFragment(DocumentFragmentImpl *i); }; class NamedNodeMap; class DOMString; /** * EachDocument
has adoctype
attribute * whose value is eithernull
or aDocumentType *
object. TheDocumentType
interface in the * DOM Level 1 Core provides an interface to the list of entities that * are defined for the document, and little else because the effect of * namespaces and the various XML scheme efforts on DTD representation * are not clearly understood as of this writing. * * The DOM Level 1 doesn't support editingDocumentType *
nodes. * */ class DocumentType : public Node { friend class Document; public: DocumentType(); DocumentType(const DocumentType &other); DocumentType(const Node &other) : Node() {(*this)=other;} DocumentType & operator = (const Node &other); DocumentType & operator = (const DocumentType &other); ~DocumentType(); /** * The name of DTD; i.e., the name immediately following the *DOCTYPE
keyword. * */ DOMString name() const; /** * ANamedNodeMap
containing the general entities, * both external and internal, declared in the DTD. Duplicates are * discarded. For example in: <!DOCTYPE ex SYSTEM "ex.dtd" [ * <!ENTITY foo "foo"> <!ENTITY bar "bar"> <!ENTITY % baz * "baz"> ]> <ex/> the interface provides access tofoo *
andbar
but notbaz
. * Every node in this map also implements theEntity *
interface. * * The DOM Level 1 does not support editing entities, therefore *entities
cannot be altered in any way. * */ NamedNodeMap entities() const; /** * ANamedNodeMap
containing the notations declared * in the DTD. Duplicates are discarded. Every node in this map * also implements theNotation
interface. * * The DOM Level 1 does not support editing notations, therefore *notations
cannot be altered in any way. * */ NamedNodeMap notations() const; protected: DocumentType(DocumentTypeImpl *impl); }; }; //namespace #endif
Generated by: dfaure on kde.faure.org on Thu Jan 17 22:18:15 2002, using kdoc 2.0a53. |