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
TreeWalker objects are used to navigate a document tree or subtree using the view of the document def...
Introduced in DOM Level 2.
Definition: dom2_events.h:116
Generic embedded object.
Definition: html_object.h:268
The CSSStyleDeclaration interface represents a single CSS declaration block .
Definition: css_value.h:59
This represents the content of a comment, i.e., all the characters between the starting ' <!...
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
The DOMImplementation interface provides a number of methods for performing operations that are indep...
Definition: dom_doc.h:78
This library provides a full-featured HTML parser and widget.
The Attr interface represents an attribute in an Element object.
Definition: dom_element.h:89
This class is khtml's main class.
Definition: khtml_part.h:208
NodeIterators are used to step through a set of nodes, e.g.
The StyleSheet interface is the abstract base interface for any type of style sheet.
Renders and displays HTML in a QScrollArea.
Definition: khtmlview.h:97
An HTMLDocument is the root of the HTML hierarchy and holds the entire content.
Definition: html_document.h:74
The Text interface represents the textual content (termed character data in XML) of an Element or At...
Definition: dom_text.h:273
Comment
The Document interface represents the entire HTML or XML document.
Definition: dom_doc.h:246
The StyleSheetList interface provides the abstraction of an ordered collection of style sheets.
CDATA sections are used to escape blocks of text containing characters that would otherwise be regard...
Definition: dom_xml.h:65
DocumentFragment is a "lightweight" or "minimal" Document object.
Definition: dom_doc.h:1042
The ProcessingInstruction interface represents a "processing instruction", used in XML as a way to ke...
Definition: dom_xml.h:264
The CSSStyleSheet interface is a concrete interface used to represent a CSS style sheet i....
This class implements the basic string we use in the DOM.
Definition: dom_string.h:44
Create a frame.
Definition: html_base.h:165
Q_SCRIPTABLE Q_NOREPLY void abort()
The NodeList interface provides the abstraction of an ordered collection of nodes,...
Definition: dom_node.h:976
Inline subwindows.
Definition: html_base.h:368
Objects implementing the NamedNodeMap interface are used to represent collections of nodes that can b...
Definition: dom_node.h:64
The Node interface is the primary datatype for the entire Document Object Model.
Definition: dom_node.h:278
Filters are objects that know how to "filter out" nodes.
Introduced in DOM Level 2.
Definition: dom2_views.h:42
EntityReference objects may be inserted into the structure model when an entity reference is in the s...
Definition: dom_xml.h:190
Each Document has a doctype attribute whose value is either null or a DocumentType object.
Definition: dom_doc.h:1102
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Sep 27 2023 04:05:41 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.