KHtml

dom_doc.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_Document_h_
30 #define _DOM_Document_h_
31 
32 #include <dom/dom_node.h>
33 #include <dom/css_stylesheet.h>
34 
35 class KHTMLView;
36 class KHTMLPart;
37 
38 namespace DOM
39 {
40 
41 class DOMString;
42 class DocumentType;
43 class NodeList;
44 class CDATASection;
45 class Comment;
46 class DocumentFragment;
47 class Text;
48 class DOMImplementation;
49 class Element;
50 class Attr;
51 class EntityReference;
52 class ProcessingInstruction;
53 class DocumentImpl;
54 class Range;
55 class NodeIterator;
56 class TreeWalker;
57 class NodeFilter;
58 class DOMImplementationImpl;
59 class DocumentTypeImpl;
60 class Event;
61 class AbstractView;
62 class CSSStyleDeclaration;
63 class HTMLElementImpl;
64 class HTMLFrameElement;
65 class HTMLElementImpl;
66 class HTMLIFrameElement;
67 class HTMLObjectElement;
68 class HTMLDocument;
69 
70 /**
71  * The \c DOMImplementation interface provides a number of
72  * methods for performing operations that are independent of any
73  * particular instance of the document object model.
74  *
75  * DOM Level 2 and newer provide means for creating documents directly,
76  * which was not possible with DOM Level 1.
77  */
78 class KHTML_EXPORT DOMImplementation
79 {
80  friend class Document;
81 public:
84 
85  DOMImplementation &operator = (const DOMImplementation &other);
87 
88  /**
89  * Test if the DOM implementation implements a specific feature.
90  *
91  * @param feature The package name of the feature to test. In
92  * Level 1, the legal values are "HTML" and "XML"
93  * (case-insensitive).
94  *
95  * @param version This is the version number of the package name
96  * to test. In Level 1, this is the string "1.0". If the version
97  * is not specified, supporting any version of the feature will
98  * cause the method to return \c true .
99  *
100  * @return \c true if the feature is implemented in
101  * the specified version, \c false otherwise.
102  *
103  */
104  bool hasFeature(const DOMString &feature, const DOMString &version);
105 
106  /**
107  * Introduced in DOM Level 2
108  *
109  * Creates an empty DocumentType node. Entity declarations and notations
110  * are not made available. Entity reference expansions and default
111  * attribute additions do not occur. It is expected that a future version
112  * of the DOM will provide a way for populating a DocumentType.
113  *
114  * HTML-only DOM implementations do not need to implement this method.
115  *
116  * @param qualifiedName The qualified name of the document type to be
117  * created.
118  *
119  * @param publicId The external subset public identifier.
120  *
121  * @param systemId The external subset system identifier.
122  *
123  * @return A new DocumentType node with Node.ownerDocument set to null.
124  *
125  * @exception DOMException
126  * INVALID_CHARACTER_ERR: Raised if the specified qualified name contains
127  * an illegal character.
128  *
129  * NAMESPACE_ERR: Raised if the qualifiedName is malformed.
130  */
131  DocumentType createDocumentType(const DOMString &qualifiedName,
132  const DOMString &publicId,
133  const DOMString &systemId);
134 
135  /**
136  * Introduced in DOM Level 2
137  *
138  * Creates an XML Document object of the specified type with its document
139  * element. HTML-only DOM implementations do not need to implement this
140  * method.
141  *
142  * @param namespaceURI The namespace URI of the document element to create.
143  *
144  * @param qualifiedName The qualified name of the document element to be
145  * created.
146  *
147  * @param doctype The type of document to be created or null. When doctype
148  * is not null, its Node.ownerDocument attribute is set to the document
149  * being created.
150  *
151  * @return A new Document object.
152  *
153  * @exception DOMException
154  * INVALID_CHARACTER_ERR: Raised if the specified qualified name contains
155  * an illegal character.
156  *
157  * NAMESPACE_ERR: Raised if the qualifiedName is malformed, if the
158  * qualifiedName has a prefix and the namespaceURI is null, or if the
159  * qualifiedName has a prefix that is "xml" and the namespaceURI is
160  * different from "http://www.w3.org/XML/1998/namespace" [Namespaces].
161  *
162  * WRONG_DOCUMENT_ERR: Raised if doctype has already been used with a
163  * different document or was created from a different implementation.
164  */
165  Document createDocument(const DOMString &namespaceURI,
166  const DOMString &qualifiedName,
167  const DocumentType &doctype);
168 
169  /**
170  * Introduced in DOM Level 3
171  * This method makes available a DOMImplementation's specialized
172  * interface.
173  *
174  * @param feature The name of the feature requested (case-insensitive)
175  *
176  * @return Returns an alternate DOMImplementation which implements
177  * the specialized APIs of the specified feature, if any, or null
178  * if there is no alternate DOMImplementation object which implements
179  * interfaces associated with that feature. Any alternate DOMImplementation
180  * returned by this method must delegate to the primary core DOMImplementation
181  * and not return results inconsistent with the primary DOMImplementation.
182  */
183  DOMImplementation getInterface(const DOMString &feature) const;
184 
185  /**
186  * Introduced in DOM Level 2
187  * This method is from the DOMImplementationCSS interface
188  *
189  * Creates a new CSSStyleSheet.
190  *
191  * @param title The advisory title. See also the Style Sheet Interfaces
192  * section.
193  *
194  * @param media The comma-separated list of media associated with the
195  * new style sheet. See also the Style Sheet Interfaces section.
196  *
197  * @return A new CSS style sheet.
198  *
199  * @exception SYNTAX_ERR: Raised if the specified media string value has a syntax error and is unparsable.
200  */
201  CSSStyleSheet createCSSStyleSheet(const DOMString &title, const DOMString &media);
202 
203  /**
204  * Introduced in DOM Level 2
205  * This method is from the HTMLDOMImplementation interface
206  *
207  * Creates an HTMLDocument with the minimal tree made of these
208  * elements: HTML,HEAD,TITLE and BODY.
209  * It extends the core interface which can be used to create an
210  * XHTML document by passing the XHTML namespace as the namespace
211  * for the root element.
212  *
213  * @param title The title of the document to be set as the content
214  * of the TITLE element, through a child Text node.
215  *
216  * @return the HTMLdocument
217  */
218  HTMLDocument createHTMLDocument(const DOMString &title);
219 
220  /**
221  * @internal
222  * not part of the DOM
223  */
224  DOMImplementationImpl *handle() const;
225  bool isNull() const;
226 
227 protected:
228  DOMImplementation(DOMImplementationImpl *i);
229  DOMImplementationImpl *impl;
230 };
231 
232 /**
233  * The \c Document interface represents the entire HTML or
234  * XML document. Conceptually, it is the root of the document tree,
235  * and provides the primary access to the document's data.
236  *
237  * Since elements, text nodes, comments, processing instructions,
238  * etc. cannot exist outside the context of a \c Document
239  * , the \c Document interface also contains the factory
240  * methods needed to create these objects. The \c Node
241  * objects created have a \c ownerDocument attribute which
242  * associates them with the \c Document within whose
243  * context they were created.
244  *
245  */
246 class KHTML_EXPORT Document : public Node
247 {
248  friend class ::KHTMLView;
249  friend class ::KHTMLPart;
250  friend class AbstractView;
251  friend class DOMImplementation;
252  friend class HTMLFrameElement;
253  friend class HTMLIFrameElement;
254  friend class HTMLObjectElement;
255 
256 public:
257  Document();
258  /**
259  * don't create an implementation if false
260  * use at own risk
261  */
262  Document(bool);
263  Document(const Document &other);
264  Document(const Node &other) : Node()
265  {
266  (*this) = other;
267  }
268 
269  Document &operator = (const Node &other);
270  Document &operator = (const Document &other);
271 
272  ~Document();
273 
274  /**
275  * The Document Type Declaration (see \c DocumentType
276  * ) associated with this document. For HTML documents as well as
277  * XML documents without a document type declaration this returns
278  * \c null . The DOM Level 1 does not support editing
279  * the Document Type Declaration, therefore \c docType
280  * cannot be altered in any way.
281  *
282  */
283  DocumentType doctype() const;
284 
285  /**
286  * The \c DOMImplementation object that handles this
287  * document. A DOM application may use objects from multiple
288  * implementations.
289  *
290  */
291  DOMImplementation implementation() const;
292 
293  /**
294  * This is a convenience attribute that allows direct access to
295  * the child node that is the root element of the document. For
296  * HTML documents, this is the element with the tagName "HTML".
297  *
298  */
299  Element documentElement() const;
300 
301  /**
302  * Creates an element of the type specified. Note that the
303  * instance returned implements the Element interface, so
304  * attributes can be specified directly on the returned object.
305  *
306  * @param tagName The name of the element type to instantiate. For
307  * XML, this is case-sensitive. For HTML, the \c tagName
308  * parameter may be provided in any case, but it must be
309  * mapped to the canonical uppercase form by the DOM
310  * implementation.
311  *
312  * @return A new \c Element object.
313  *
314  * @exception DOMException
315  * INVALID_CHARACTER_ERR: Raised if the specified name contains an
316  * invalid character.
317  *
318  */
319  Element createElement(const DOMString &tagName);
320 
321  /**
322  * Introduced in DOM Level 2
323  * Creates an element of the given qualified name and namespace URI.
324  *
325  * @param namespaceURI The namespace URI of the element to create.
326  *
327  * @param qualifiedName The qualified name of the element type to instantiate.
328  *
329  * @return A new Element object with the following attributes:
330  *
331  * @exception INVALID_CHARACTER_ERR Raised if the specified qualified name
332  * contains an illegal character.
333  *
334  * @exception NAMESPACE_ERR Raised if the qualifiedName is malformed, if
335  * the qualifiedName has a prefix and the namespaceURI is null, or if the
336  * qualifiedName has a prefix that is "xml" and the namespaceURI is
337  * different from "http://www.w3.org/XML/1998/namespace"
338  */
339  Element createElementNS(const DOMString &namespaceURI,
340  const DOMString &qualifiedName);
341 
342  /**
343  * Creates an empty \c DocumentFragment object.
344  *
345  * @return A new \c DocumentFragment .
346  *
347  */
348  DocumentFragment createDocumentFragment();
349 
350  /**
351  * Creates a \c Text node given the specified string.
352  *
353  * @param data The data for the node.
354  *
355  * @return The new \c Text object.
356  *
357  */
358  Text createTextNode(const DOMString &data);
359 
360  /**
361  * Creates a \c Comment node given the specified
362  * string.
363  *
364  * @param data The data for the node.
365  *
366  * @return The new \c Comment object.
367  *
368  */
369  Comment createComment(const DOMString &data);
370 
371  /**
372  * Creates a \c CDATASection node whose value is the
373  * specified string.
374  *
375  * @param data The data for the \c CDATASection
376  * contents.
377  *
378  * @return The new \c CDATASection object.
379  *
380  * @exception DOMException
381  * NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
382  *
383  */
384  CDATASection createCDATASection(const DOMString &data);
385 
386  /**
387  * Creates a \c ProcessingInstruction node given the
388  * specified name and data strings.
389  *
390  * @param target The target part of the processing instruction.
391  *
392  * @param data The data for the node.
393  *
394  * @return The new \c ProcessingInstruction object.
395  *
396  * @exception DOMException
397  * INVALID_CHARACTER_ERR: Raised if an invalid character is
398  * specified.
399  *
400  * NOT_SUPPORTED_ERR: Raised if this document is an HTML
401  * document.
402  *
403  */
404  ProcessingInstruction createProcessingInstruction(const DOMString &target,
405  const DOMString &data);
406 
407  /**
408  * Creates an \c Attr of the given name. Note that the
409  * \c Attr instance can then be set on an \c Element
410  * using the \c setAttribute method.
411  *
412  * @param name The name of the attribute.
413  *
414  * @return A new \c Attr object.
415  *
416  * @exception DOMException
417  * INVALID_CHARACTER_ERR: Raised if the specified name contains an
418  * invalid character.
419  *
420  */
421  Attr createAttribute(const DOMString &name);
422 
423  /**
424  * Introduced in DOM Level 2
425  * Creates an attribute of the given qualified name and namespace URI.
426  * HTML-only DOM implementations do not need to implement this method.
427  *
428  * @param namespaceURI The namespace URI of the attribute to create.
429  *
430  * @param qualifiedName The qualified name of the attribute to instantiate.
431  *
432  * @return A new Attr object with the following attributes:
433  * Node.nodeName - qualifiedName
434  * Node.namespaceURI - namespaceURI
435  * Node.prefix - prefix, extracted from qualifiedName, or null if there is
436  * no prefix
437  * Node.localName - local name, extracted from qualifiedName
438  * Attr.name - qualifiedName
439  * Node.nodeValue - the empty string
440  *
441  * @exception INVALID_CHARACTER_ERR Raised if the specified qualified name
442  * contains an illegal character.
443  *
444  * @exception NAMESPACE_ERR Raised if the qualifiedName is malformed, if
445  * the qualifiedName has a prefix and the namespaceURI is null, if the
446  * qualifiedName has a prefix that is "xml" and the namespaceURI is
447  * different from "http://www.w3.org/XML/1998/namespace", or if the
448  * qualifiedName is "xmlns" and the namespaceURI is different from
449  * "http://www.w3.org/2000/xmlns/".
450  */
451  Attr createAttributeNS(const DOMString &namespaceURI,
452  const DOMString &qualifiedName);
453 
454  /**
455  * Creates an EntityReference object.
456  *
457  * @param name The name of the entity to reference.
458  *
459  * @return The new \c EntityReference object.
460  *
461  * @exception DOMException
462  * INVALID_CHARACTER_ERR: Raised if the specified name contains an
463  * invalid character.
464  *
465  * NOT_SUPPORTED_ERR: Raised if this document is an HTML
466  * document.
467  *
468  */
469  EntityReference createEntityReference(const DOMString &name);
470 
471  /**
472  * Moved from HTMLDocument in DOM Level 2
473  * Returns the Element whose \c id is given by
474  * elementId. If no such element exists, returns \c null
475  * . Behavior is not defined if more than one element has
476  * this \c id .
477  *
478  * @param elementId The unique \c id value for an
479  * element.
480  *
481  * @return The matching element.
482  *
483  */
484  Element getElementById(const DOMString &elementId) const;
485 
486  /**
487  * No Exceptions.
488  *
489  * Returns a \c NodeList of all the \c Element 's
490  * with a given tag name in the order in which they
491  * would be encountered in a preorder traversal of the
492  * \c Document tree.
493  *
494  * @param tagname The name of the tag to match on. The special
495  * value "*" matches all tags.
496  *
497  * @return A new \c NodeList object containing all the
498  * matched \c Element s.
499  *
500  */
501  NodeList getElementsByTagName(const DOMString &tagname);
502 
503  /**
504  * Introduced in DOM Level 2
505  * No Exceptions
506  *
507  * Returns a NodeList of all the Elements with a given local name and
508  * namespace URI in the order in which they are encountered in a preorder
509  * traversal of the Document tree.
510  *
511  * @param namespaceURI The namespace URI of the elements to match on. The
512  * special value "*" matches all namespaces.
513  *
514  * @param localName The local name of the elements to match on. The special
515  * value "*" matches all local names.
516  *
517  * @return A new NodeList object containing all the matched Elements.
518  */
519  NodeList getElementsByTagNameNS(const DOMString &namespaceURI,
520  const DOMString &localName);
521 
522  /**
523  * Introduced in HTML 5.
524  * No Exceptions.
525  *
526  * Returns a \c NodeList of all the \c Element 's
527  * with a given class name in the order in which they
528  * would be encountered in a preorder traversal of the
529  * \c Document tree.
530  *
531  * @param tagname An unordered set of unique space-separated
532  * tokens representing classes.
533  *
534  * @return A new \c NodeList object containing all the
535  * matched \c Element s.
536  *
537  * @since 4.1
538  */
539  NodeList getElementsByClassName(const DOMString &className);
540 
541  /**
542  * Introduced in DOM Level 2
543  *
544  * Imports a node from another document to this document. The returned node
545  * has no parent; (parentNode is null). The source node is not altered or
546  * removed from the original document; this method creates a new copy of
547  * the source node.
548  *
549  * For all nodes, importing a node creates a node object owned by the
550  * importing document, with attribute values identical to the source node's
551  * nodeName and nodeType, plus the attributes related to namespaces
552  * (prefix, localName, and namespaceURI).
553  *
554  * As in the cloneNode operation on a Node, the source node is not altered.
555  * Additional information is copied as appropriate to the nodeType,
556  * attempting to mirror the behavior expected if a fragment of XML or HTML
557  * source was copied from one document to another, recognizing that the two
558  * documents may have different DTDs in the XML case. The following list
559  * describes the specifics for each type of node.
560  *
561  * ATTRIBUTE_NODE
562  * The ownerElement attribute is set to null and the specified flag is set
563  * to true on the generated Attr. The descendants of the source Attr are
564  * recursively imported and the resulting nodes reassembled to form the
565  * corresponding subtree. Note that the deep parameter has no effect on
566  * Attr nodes; they always carry their children with them when imported.
567  *
568  * DOCUMENT_FRAGMENT_NODE
569  * If the deep option was set to true, the descendants of the source
570  * element are recursively imported and the resulting nodes reassembled to
571  * form the corresponding subtree. Otherwise, this simply generates an
572  * empty DocumentFragment.
573  *
574  * DOCUMENT_NODE
575  * Document nodes cannot be imported.
576  *
577  * DOCUMENT_TYPE_NODE
578  * DocumentType nodes cannot be imported.
579  *
580  * ELEMENT_NODE
581  * Specified attribute nodes of the source element are imported, and the
582  * generated Attr nodes are attached to the generated Element. Default
583  * attributes are not copied, though if the document being imported into
584  * defines default attributes for this element name, those are assigned. If
585  * the importNode deep parameter was set to true, the descendants of the
586  * source element are recursively imported and the resulting nodes
587  * reassembled to form the corresponding subtree.
588  *
589  * ENTITY_NODE
590  * Entity nodes can be imported, however in the current release of the DOM
591  * the DocumentType is readonly. Ability to add these imported nodes to a
592  * DocumentType will be considered for addition to a future release of the
593  * DOM.
594  * On import, the publicId, systemId, and notationName attributes are
595  * copied. If a deep import is requested, the descendants of the source
596  * Entity are recursively imported and the resulting nodes reassembled to
597  * form the corresponding subtree.
598  *
599  * ENTITY_REFERENCE_NODE Only the EntityReference itself is copied, even if
600  * a deep import is requested, since the source and destination documents
601  * might have defined the entity differently. If the document being
602  * imported into provides a definition for this entity name, its value is
603  * assigned.
604  *
605  * NOTATION_NODE
606  * Notation nodes can be imported, however in the current release of the
607  * DOM the DocumentType is readonly. Ability to add these imported nodes to
608  * a DocumentType will be considered for addition to a future release of
609  * the DOM.
610  * On import, the publicId and systemId attributes are copied.
611  * Note that the deep parameter has no effect on Notation nodes since they
612  * never have any children.
613  *
614  * PROCESSING_INSTRUCTION_NODE
615  * The imported node copies its target and data values from those of the
616  * source node.
617  *
618  * TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE
619  * These three types of nodes inheriting from CharacterData copy their data
620  * and length attributes from those of the source node.
621  *
622  * @param importedNode The node to import.
623  *
624  * @param deep If true, recursively import the subtree under the specified
625  * node; if false, import only the node itself, as explained above. This
626  * has no effect on Attr, EntityReference, and Notation nodes.
627  *
628  * @return The imported node that belongs to this Document.
629  *
630  * @exception DOMException
631  * NOT_SUPPORTED_ERR: Raised if the type of node being imported is not
632  * supported.
633  */
634  Node importNode(const Node &importedNode, bool deep);
635 
636  /**
637  * @internal
638  * not part of the DOM
639  */
640  bool isHTMLDocument() const;
641 
642  /**
643  * Introduced in DOM Level 2
644  * This method is from the DocumentRange interface
645  *
646  * @return Range
647  * The initial state of the Range returned from this method is such that
648  * both of its boundary-points are positioned at the beginning of the
649  * corresponding Document, before any content. The Range returned can only
650  * be used to select content associated with this Document, or with
651  * DocumentFragments and Attrs for which this Document is the ownerDocument.
652  */
653  Range createRange();
654 
655  /**
656  * Introduced in DOM Level 2
657  * This method is from the DocumentTraversal interface
658  *
659  * Create a new NodeIterator over the subtree rooted at the specified node.
660  *
661  * @param root The node which will be iterated together with its children.
662  * The iterator is initially positioned just before this node. The
663  * whatToShow flags and the filter, if any, are not considered when setting
664  * this position. The root must not be null.
665  *
666  * @param whatToShow This flag specifies which node types may appear in the
667  * logical view of the tree presented by the iterator. See the description
668  * of NodeFilter for the set of possible SHOW_ values. These flags can be
669  * combined using OR.
670  *
671  * @param filter The NodeFilter to be used with this NodeIterator, or null to
672  * indicate no filter.
673  *
674  * @param entityReferenceExpansion The value of this flag determines
675  * whether entity reference nodes are expanded.
676  *
677  * @return NodeIterator The newly created NodeIterator.
678  *
679  * @exception DOMException
680  * NOT_SUPPORTED_ERR: Raised if the specified root is null.
681  */
682  NodeIterator createNodeIterator(Node root, unsigned long whatToShow,
683  NodeFilter filter,
684  bool entityReferenceExpansion);
685 
686  /**
687  * Introduced in DOM Level 2
688  * This method is from the DocumentTraversal interface
689  *
690  * Create a new TreeWalker over the subtree rooted at the specified node.
691  *
692  * @param root The node which will serve as the root for the TreeWalker.
693  * The whatToShow flags and the NodeFilter are not considered when setting
694  * this value; any node type will be accepted as the root. The currentNode
695  * of the TreeWalker is initialized to this node, whether or not it is
696  * visible. The root functions as a stopping point for traversal methods
697  * that look upward in the document structure, such as parentNode and
698  * nextNode. The root must not be null.
699  *
700  * @param whatToShow This flag specifies which node types may appear in the
701  * logical view of the tree presented by the tree-walker. See the
702  * description of NodeFilter for the set of possible SHOW_ values. These
703  * flags can be combined using OR.
704  *
705  * @param filter The NodeFilter to be used with this TreeWalker, or null to
706  * indicate no filter.
707  *
708  * @param entityReferenceExpansion If this flag is false, the contents of
709  * EntityReference nodes are not presented in the logical view.
710  *
711  * @return The newly created TreeWalker.
712  *
713  * @exception DOMException
714  * NOT_SUPPORTED_ERR: Raised if the specified root is null.
715  */
716  TreeWalker createTreeWalker(Node root, unsigned long whatToShow,
717  NodeFilter filter,
718  bool entityReferenceExpansion);
719 
720  /**
721  * Introduced in DOM Level 2
722  * This method is from the DocumentEvent interface
723  *
724  * The createEvent method is used in creating Events when it is either
725  * inconvenient or unnecessary for the user to create an Event themselves.
726  * In cases where the implementation provided Event is insufficient, users
727  * may supply their own Event implementations for use with the
728  * dispatchEvent method.
729  *
730  * @param eventType The eventType parameter specifies the type of Event
731  * interface to be created. If the Event interface specified is supported
732  * by the implementation this method will return a new Event of the
733  * interface type requested. If the Event is to be dispatched via the
734  * dispatchEvent method the appropriate event init method must be called
735  * after creation in order to initialize the Event's values. As an example,
736  * a user wishing to synthesize some kind of UIEvent would call createEvent
737  * with the parameter "UIEvents". The initUIEvent method could then be
738  * called on the newly created UIEvent to set the specific type of UIEvent
739  * to be dispatched and set its context information.
740  *
741  * @return The newly created EventExceptions
742  *
743  * @exception DOMException
744  * NOT_SUPPORTED_ERR: Raised if the implementation does not support the
745  * type of Event interface requested
746  */
747  Event createEvent(const DOMString &eventType);
748 
749  /**
750  * Introduced in DOM Level 2
751  * This method is from the DocumentView interface
752  *
753  * The default AbstractView for this Document, or null if none available.
754  */
755  AbstractView defaultView() const;
756 
757  /**
758  * Introduced in DOM Level 2
759  * This method is from the DocumentStyle interface
760  *
761  * A list containing all the style sheets explicitly linked into or
762  * embedded in a document. For HTML documents, this includes external style
763  * sheets, included via the HTML LINK element, and inline STYLE elements.
764  * In XML, this includes external style sheets, included via style sheet
765  * processing instructions (see [XML-StyleSheet]).
766  */
767  StyleSheetList styleSheets() const;
768 
769  /**
770  * CSS3 mechanism for selecting alternate stylesheets using the DOM.
771  * Might change without further notice.
772  */
773 
774  DOMString preferredStylesheetSet();
775  DOMString selectedStylesheetSet();
776  void setSelectedStylesheetSet(const DOMString &aString);
777 
778  /**
779  * Adds a new style sheet to the list of style sheets.
780  *
781  * The new style sheet will be applied after all author and implicit
782  * style sheets, but before the user style sheet.
783  *
784  * Create new style sheets with e. g.
785  * \c DOMImplementation::createCSSStyleSheet
786  *
787  * This is not part of the official DOM.
788  *
789  * @param sheet style sheet
790  * @exception DOMException
791  */
792  void addStyleSheet(const StyleSheet &sheet);
793 
794  /**
795  * Removes a style sheet to the list of style sheets.
796  *
797  * Only sheets added by \c addStyleSheet may be removed.
798  *
799  * This is not part of the official DOM.
800  *
801  * @param sheet style sheet to remove
802  * @exception DOMException
803  * NOT_FOUND_ERR \c sheet is not contained in the list of style sheets or
804  * it has not been added by \c addStyleSheet
805  */
806  void removeStyleSheet(const StyleSheet &sheet);
807 
808  /**
809  * @return The KHTML view widget of this document.
810  */
811  KHTMLView *view() const;
812 
813  /**
814  * Introduced in DOM Level 2
815  * This method is from the DocumentCSS interface
816  *
817  * This method is used to retrieve the override style declaration for a
818  * specified element and a specified pseudo-element.
819  *
820  * @param elt The element whose style is to be modified. This parameter
821  * cannot be null.
822  *
823  * @param pseudoElt The pseudo-element or null if none.
824  *
825  * @return The override style declaration.
826  */
827  CSSStyleDeclaration getOverrideStyle(const Element &elt,
828  const DOMString &pseudoElt);
829 
830  /**
831  * Introduced in DOM Level 3
832  * This method is from the DocumentLS interface
833  *
834  * Indicates whether the method DocumentLS.load() should be synchronous or
835  * asynchronous. When the async attribute is set to true the load method
836  * returns control to the caller before the document has completed loading.
837  * The default value of this attribute is true.
838  */
839  bool async() const;
840 
841  /**
842  * Introduced in DOM Level 3
843  * This method is from the DocumentLS interface
844  *
845  * see async
846  *
847  * @exception DOMException
848  * NOT_SUPPORTED_ERR: Raised if the implementation doesn't support the mode
849  * the attribute is being set to.
850  */
851  void setAsync(bool);
852 
853  /**
854  * Introduced in DOM Level 3
855  * This method is from the DocumentLS interface
856  *
857  * If the document is currently being loaded as a result of the method load
858  * being invoked the loading and parsing is immediately aborted. The
859  * possibly partial result of parsing the document is discarded and the
860  * document is cleared.
861  */
862  void abort();
863 
864  /**
865  * Introduced in DOM Level 3
866  * This method is from the DocumentLS interface
867  *
868  * Replaces the content of the document with the result of parsing the
869  * given URI. Invoking this method will either block the caller or return
870  * to the caller immediately depending on the value of the async attribute.
871  * Once the document is fully loaded a "load" event (as defined in
872  * [DOM Level 3 Events], except that the Event.targetNode will be the
873  * document, not an element) will be dispatched on the document. If an
874  * error occurs, an implementation dependent "error" event will be
875  * dispatched on the document. If this method is called on a document that
876  * is currently loading, the current load is interrupted and the new URI
877  * load is initiated.
878  *
879  * When invoking this method the parameters used in the DOMParser interface
880  * are assumed to have their default values with the exception that the
881  * parameters "entities", "normalize-characters",
882  * "check-character-normalization" are set to "false".
883  *
884  * The result of a call to this method is the same the result of a call to
885  * DOMParser.parseWithContext with an input stream referencing the URI that
886  * was passed to this call, the document as the context node, and the
887  * action ACTION_REPLACE_CHILDREN.
888  *
889  * @param uri of type DOMString
890  * The URI reference for the XML file to be loaded. If this is a relative
891  * URI, the base URI used by the implementation is implementation dependent.
892  *
893  * @return If async is set to true load returns true if the document load
894  * was successfully initiated. If an error occurred when initiating the
895  * document load, load returns false.
896  * If async is set to false load returns true if the document was
897  * successfully loaded and parsed. If an error occurred when either loading
898  * or parsing the URI, load returns false.
899  */
900  void load(const DOMString &uri);
901 
902  /**
903  * Introduced in DOM Level 3
904  * This method is from the DocumentLS interface
905  *
906  * Replace the content of the document with the result of parsing the input
907  * string, this method is always synchronous. This method always parses
908  * from a DOMString, which means the data is always UTF-16. All other
909  * encoding information is ignored.
910  *
911  * The parameters used in the DOMParser interface are assumed to have their
912  * default values when invoking this method.
913  *
914  * The result of a call to this method is the same as the result of a call
915  * to DOMParser.parseWithContext with an input stream containing the string
916  * passed to this call, the document as the context node, and the action
917  * ACTION_REPLACE_CHILDREN.
918  *
919  * @param source A string containing an XML document.
920  */
921  void loadXML(const DOMString &source);
922 
923  /**
924  * Introduced in Selectors Level 1.
925  *
926  * Returns the first (in document order) element matching the given
927  * CSS selector @p query.
928  *
929  * @since 4.5
930  */
931  Element querySelector(const DOMString &query) const;
932 
933  /**
934  * Introduced in Selectors Level 1.
935  *
936  * Returns all (in document order) elements matching the given
937  * CSS selector @p query. Note that the returned NodeList is
938  * static and not live, and will not be updated when the document
939  * changes
940  *
941  * @since 4.5
942  */
943  NodeList querySelectorAll(const DOMString &query) const;
944 
945  /**
946  * not part of the official DOM
947  *
948  * Documents are read-only by default, but they can be made editable by
949  * entering "design mode".
950  *
951  * @return whether this document is in design mode.
952  */
953  bool designMode() const;
954 
955  /**
956  * not part of the official DOM
957  *
958  * @param enable @p true to enable design mode, @p false to disable.
959  * @see designMode
960  */
961  void setDesignMode(bool enable);
962 
963  /**
964  * not part of the DOM
965  *
966  * completes a given URL
967  */
968  DOMString completeURL(const DOMString &url);
969 
970  DOMString toString() const;
971 
972  /**
973  * not part of the DOM
974  *
975  * javascript editing command support
976  */
977  bool execCommand(const DOMString &command, bool userInterface, const DOMString &value);
978  bool queryCommandEnabled(const DOMString &command);
979  bool queryCommandIndeterm(const DOMString &command);
980  bool queryCommandState(const DOMString &command);
981  bool queryCommandSupported(const DOMString &command);
982  DOMString queryCommandValue(const DOMString &command);
983 
984  /**
985  * not part of the DOM
986  *
987  * Updates the rendered display after one or more changes to
988  * the DOM structure
989  */
990  void updateRendering();
991 
993 protected:
994 
995  friend class Node;
996 };
997 
998 class DocumentFragmentImpl;
999 
1000 /**
1001  * \c DocumentFragment is a "lightweight" or "minimal"
1002  * \c Document object. It is very common to want to be
1003  * able to extract a portion of a document's tree or to create a new
1004  * fragment of a document. Imagine implementing a user command like
1005  * cut or rearranging a document by moving fragments around. It is
1006  * desirable to have an object which can hold such fragments and it is
1007  * quite natural to use a Node for this purpose. While it is true that
1008  * a \c Document object could fulfil this role, a
1009  * \c Document object can potentially be a heavyweight object,
1010  * depending on the underlying implementation. What is really needed
1011  * for this is a very lightweight object. \c DocumentFragment
1012  * is such an object.
1013  *
1014  * Furthermore, various operations -- such as inserting nodes as
1015  * children of another \c Node -- may take
1016  * \c DocumentFragment objects as arguments; this results in all
1017  * the child nodes of the \c DocumentFragment being moved
1018  * to the child list of this node.
1019  *
1020  * The children of a \c DocumentFragment node are zero or
1021  * more nodes representing the tops of any sub-trees defining the
1022  * structure of the document. \c DocumentFragment nodes do
1023  * not need to be well-formed XML documents (although they do need to
1024  * follow the rules imposed upon well-formed XML parsed entities,
1025  * which can have multiple top nodes). For example, a
1026  * \c DocumentFragment might have only one child and that child
1027  * node could be a \c Text node. Such a structure model
1028  * represents neither an HTML document nor a well-formed XML document.
1029  *
1030  * When a \c DocumentFragment is inserted into a
1031  * \c Document (or indeed any other \c Node that may
1032  * take children) the children of the \c DocumentFragment
1033  * and not the \c DocumentFragment itself are inserted
1034  * into the \c Node . This makes the
1035  * \c DocumentFragment very useful when the user wishes to create
1036  * nodes that are siblings; the \c DocumentFragment acts
1037  * as the parent of these nodes so that the user can use the standard
1038  * methods from the \c Node interface, such as
1039  * \c insertBefore() and \c appendChild() .
1040  *
1041  */
1042 class KHTML_EXPORT DocumentFragment : public Node
1043 {
1044  friend class Document;
1045  friend class HTMLElementImpl;
1046  friend class Range;
1047 
1048 public:
1049  DocumentFragment();
1050  DocumentFragment(const DocumentFragment &other);
1051  DocumentFragment(const Node &other) : Node()
1052  {
1053  (*this) = other;
1054  }
1055 
1056  DocumentFragment &operator = (const Node &other);
1057  DocumentFragment &operator = (const DocumentFragment &other);
1058 
1059  ~DocumentFragment();
1060 
1061  /**
1062  * Introduced in Selectors Level 1.
1063  *
1064  * Returns the first (in document order) element in this fragment
1065  * matching the given CSS selector @p query.
1066  *
1067  * @since 4.5
1068  */
1069  Element querySelector(const DOMString &query) const;
1070 
1071  /**
1072  * Introduced in Selectors Level 1.
1073  *
1074  * Returns all (in document order) elements in this fragment matching the
1075  * given CSS selector @p query. Note that the returned NodeList is
1076  * static and not live, and will not be updated when the document
1077  * changes
1078  *
1079  * @since 4.5
1080  */
1081  NodeList querySelectorAll(const DOMString &query) const;
1082 protected:
1083  DocumentFragment(DocumentFragmentImpl *i);
1084 };
1085 
1086 class NamedNodeMap;
1087 class DOMString;
1088 
1089 /**
1090  * Each \c Document has a \c doctype attribute
1091  * whose value is either \c null or a \c DocumentType
1092  * object. The \c DocumentType interface in the
1093  * DOM Level 1 Core provides an interface to the list of entities that
1094  * are defined for the document, and little else because the effect of
1095  * namespaces and the various XML scheme efforts on DTD representation
1096  * are not clearly understood as of this writing.
1097  *
1098  * The DOM Level 1 doesn't support editing \c DocumentType
1099  * nodes.
1100  *
1101  */
1102 class KHTML_EXPORT DocumentType : public Node
1103 {
1104  friend class Document;
1105  friend class DOMImplementation;
1106 public:
1107  DocumentType();
1108  DocumentType(const DocumentType &other);
1109 
1110  DocumentType(const Node &other) : Node()
1111  {
1112  (*this) = other;
1113  }
1114  DocumentType &operator = (const Node &other);
1115  DocumentType &operator = (const DocumentType &other);
1116 
1117  ~DocumentType();
1118 
1119  /**
1120  * The name of DTD; i.e., the name immediately following the
1121  * \c DOCTYPE keyword.
1122  *
1123  */
1124  DOMString name() const;
1125 
1126  /**
1127  * A \c NamedNodeMap containing the general entities,
1128  * both external and internal, declared in the DTD. Duplicates are
1129  * discarded. For example in: &lt;!DOCTYPE ex SYSTEM "ex.dtd" [
1130  * &lt;!ENTITY foo "foo"> &lt;!ENTITY bar "bar"> &lt;!ENTITY % baz
1131  * "baz"> ]> &lt;ex/> the interface provides access to \c foo
1132  * and \c bar but not \c baz .
1133  * Every node in this map also implements the \c Entity
1134  * interface.
1135  *
1136  * The DOM Level 1 does not support editing entities, therefore
1137  * \c entities cannot be altered in any way.
1138  *
1139  */
1140  NamedNodeMap entities() const;
1141 
1142  /**
1143  * A \c NamedNodeMap containing the notations declared
1144  * in the DTD. Duplicates are discarded. Every node in this map
1145  * also implements the \c Notation interface.
1146  *
1147  * The DOM Level 1 does not support editing notations, therefore
1148  * \c notations cannot be altered in any way.
1149  *
1150  */
1151  NamedNodeMap notations() const;
1152 
1153  /**
1154  * Introduced in DOM Level 2
1155  *
1156  * The public identifier of the external subset.
1157  */
1158  DOMString publicId() const;
1159 
1160  /**
1161  * Introduced in DOM Level 2
1162  *
1163  * The system identifier of the external subset.
1164  */
1165  DOMString systemId() const;
1166 
1167  /**
1168  * Introduced in DOM Level 2
1169  *
1170  * The internal subset as a string.
1171  *
1172  * Note: The actual content returned depends on how much information is
1173  * available to the implementation. This may vary depending on various
1174  * parameters, including the XML processor used to build the document.
1175  */
1176  DOMString internalSubset() const;
1177 
1178 protected:
1179  DocumentType(DocumentTypeImpl *impl);
1180 };
1181 
1182 } //namespace
1183 #endif
The ProcessingInstruction interface represents a "processing instruction", used in XML as a way to ke...
Definition: dom_xml.h:264
The Node interface is the primary datatype for the entire Document Object Model.
Definition: dom_node.h:278
An HTMLDocument is the root of the HTML hierarchy and holds the entire content.
Definition: html_document.h:74
The CSSStyleDeclaration interface represents a single CSS declaration block .
Definition: css_value.h:59
Introduced in DOM Level 2.
Definition: dom2_views.h:42
This class is khtml&#39;s main class.
Definition: khtml_part.h:208
The DOMImplementation interface provides a number of methods for performing operations that are indep...
Definition: dom_doc.h:78
DocumentFragment is a "lightweight" or "minimal" Document object.
Definition: dom_doc.h:1042
Renders and displays HTML in a QScrollArea.
Definition: khtmlview.h:97
Create a frame.
Definition: html_base.h:165
EntityReference objects may be inserted into the structure model when an entity reference is in the s...
Definition: dom_xml.h:190
Objects implementing the NamedNodeMap interface are used to represent collections of nodes that can b...
Definition: dom_node.h:64
The CSSStyleSheet interface is a concrete interface used to represent a CSS style sheet i...
This represents the content of a comment, i.e., all the characters between the starting &#39; <!– &#39; and ...
Definition: dom_text.h:225
By far the vast majority of objects (apart from text) that authors encounter when traversing a docume...
Definition: dom_element.h:212
Comment
The Text interface represents the textual content (termed character data in XML) of an Element or At...
Definition: dom_text.h:273
TreeWalker objects are used to navigate a document tree or subtree using the view of the document def...
The Attr interface represents an attribute in an Element object.
Definition: dom_element.h:89
The StyleSheetList interface provides the abstraction of an ordered collection of style sheets...
This class implements the basic string we use in the DOM.
Definition: dom_string.h:44
CDATA sections are used to escape blocks of text containing characters that would otherwise be regard...
Definition: dom_xml.h:65
The Document interface represents the entire HTML or XML document.
Definition: dom_doc.h:246
Filters are objects that know how to "filter out" nodes.
Each Document has a doctype attribute whose value is either null or a DocumentType object...
Definition: dom_doc.h:1102
Generic embedded object.
Definition: html_object.h:268
The NodeList interface provides the abstraction of an ordered collection of nodes, without defining or constraining how this collection is implemented.
Definition: dom_node.h:976
This library provides a full-featured HTML parser and widget.
Introduced in DOM Level 2.
Definition: dom2_events.h:116
The StyleSheet interface is the abstract base interface for any type of style sheet.
NodeIterators are used to step through a set of nodes, e.g.
Inline subwindows.
Definition: html_base.h:368
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Oct 25 2021 22:48:13 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.