![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/src/dom/dom.h b/src/dom/dom.h
index 8a11ea0b00738a287e4675d5d68f6c2100853af1..21ea446696523ed3f72c92facf5a3fbce65aa801 100644 (file)
--- a/src/dom/dom.h
+++ b/src/dom/dom.h
* which are provided for reference. Most important is this one:
*
* http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/idl-definitions.html
+ *
+ * More thorough explanations of the various classes and their algorithms
+ * can be found there.
+ *
*
* Authors:
* Bob Jamison
*
- * Copyright (C) 2006 Bob Jamison
+ * Copyright (C) 2006-2008 Bob Jamison
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ *
+ * =======================================================================
+ * NOTES:
+ *
+ * Notice that many of the classes defined here are pure virtual. In other
+ * words, they are purely unimplemented interfaces. For the implementations
+ * of them, look in domimpl.h and domimpl.cpp.
+ *
+ * Also, note that there is a domptr.cpp file that has a couple of necessary
+ * functions which cannot be in a .h file.
+ *
+ * Some of the comments below are quoted from the W3C spec:
+ * http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html
+ *
*/
#include <vector>
-//# include this before the #ifdefs below
-#include "domconfig.h"
+#include "domptr.h"
-#ifdef DOM_STRING_OWN
-#include "domstring.h"
+
+/**
+ * What type of string do we want? Pick one of the following
+ * Then below, select one of the corresponding typedefs.
+ */
+
+#ifdef DOM_STANDALONE
+#include <string>
#else
-#ifdef DOM_STRING_GLIBMM
#include <glibmm.h>
-#else
-#include <string>
-#endif
#endif
//# Unfortunate hack for a name collision
{
-
-#ifdef DOM_STRING_OWN
+/**
+ * This is the org::w3c::dom::DOMString definition.
+ * Which type do we want?
+ */
+#ifdef DOM_STANDALONE
+typedef std::string DOMString;
+typedef unsigned short XMLCh;
#else
-#ifdef DOM_STRING_GLIBMM
typedef Glib::ustring DOMString;
typedef gunichar XMLCh;
-#else
-typedef std::string DOMString;
-typedef unsigned short XMLCh;
-#endif
#endif
-
/**
- *
+ * At least 64 bit time stamp value.
*/
typedef unsigned long long DOMTimeStamp;
/**
- *
+ * This is used for storing refs to user-supplied data.
*/
typedef void DOMUserData;
-/*#########################################################################
-## NodePtr
-#########################################################################*/
-
-/**
- * A simple Smart Pointer class that handles Nodes and all of its
- * descendants
- */
-template<class T> class Ptr
-{
-public:
-
- /**
- * Simple constructor
- */
- Ptr()
- { _ref = 0; }
-
- /**
- * Constructor upon a reference
- */
- template<class Y> Ptr(const Ptr<Y> &other)
- {
- _ref = other._ref;
- incrementRefCount(_ref);
- }
-
- /**
- * Constructor upon a reference
- */
- Ptr(T * refArg, bool addRef = true)
- {
- _ref = refArg;
- if(addRef)
- incrementRefCount(_ref);
- }
-
-
- /**
- * Copy constructor
- */
- Ptr(const Ptr &other)
- {
- _ref = other._ref;
- incrementRefCount(_ref);
- }
-
- /**
- * Destructor
- */
- ~Ptr()
- {
- decrementRefCount(_ref);
- }
-
-
- /**
- * Assignment operator
- */
- template<class Y> Ptr &operator=(const Ptr<Y> &other)
- {
- decrementRefCount(_ref);
- _ref = other._ref;
- incrementRefCount(_ref);
- return *this;
- }
-
- /**
- * Assignment operator
- */
- Ptr &operator=(const Ptr &other)
- {
- decrementRefCount(_ref);
- _ref = other._ref;
- incrementRefCount(_ref);
- return *this;
- }
-
- /**
- * Assignment operator
- */
- template<class Y> Ptr &operator=(Y * ref)
- {
- decrementRefCount(_ref);
- _ref = ref;
- incrementRefCount(_ref);
- return *this;
- }
-
- /**
- * Assignment operator
- */
- template<class Y> Ptr &operator=(const Y * ref)
- {
- decrementRefCount(_ref);
- _ref = (Y *) ref;
- incrementRefCount(_ref);
- return *this;
- }
-
- /**
- * Return the reference
- */
- T * get() const
- {
- return _ref;
- }
-
- /**
- * Dereference operator
- */
- T &operator*() const
- {
- return *_ref;
- }
-
- /**
- * Point-to operator
- */
- T *operator->() const
- {
- return _ref;
- }
-
- /**
- * NOT bool operator. How to check if we are null without a comparison
- */
- bool operator! () const
- {
- return (_ref == 0);
- }
-
- /**
- * Swap what I reference with the other guy
- */
- void swap(Ptr &other)
- {
- T *tmp = _ref;
- _ref = other._ref;
- other._ref = tmp;
- }
-
- //The referenced item
- T *_ref;
-};
-
-
-/**
- * Global definitions. Many of these are used to mimic behaviour of
- * a real pointer
- */
-
-/**
- * Equality
- */
-template<class T, class U> inline bool
- operator==(const Ptr<T> &a, const Ptr<U> &b)
-{
- return a.get() == b.get();
-}
-
-/**
- * Inequality
- */
-template<class T, class U> inline bool
- operator!=(const Ptr<T> &a, const Ptr<U> &b)
-{
- return a.get() != b.get();
-}
-
-/**
- * Equality
- */
-template<class T> inline bool
- operator==(const Ptr<T> &a, T * b)
-{
- return a.get() == b;
-}
-
-/**
- * Inequality
- */
-template<class T> inline bool
- operator!=(const Ptr<T> &a, T * b)
-{
- return a.get() != b;
-}
-
-/**
- * Equality
- */
-template<class T> inline bool
- operator==(T * a, const Ptr<T> &b)
-{
- return a == b.get();
-}
-
-/**
- * Inequality
- */
-template<class T> inline bool
- operator!=(T * a, const Ptr<T> &b)
-{
- return a != b.get();
-}
-
-
-/**
- * Less than
- */
-template<class T> inline bool
- operator<(const Ptr<T> &a, const Ptr<T> &b)
-{
- return std::less<T *>()(a.get(), b.get());
-}
-
-/**
- * Swap
- */
-template<class T> void
- swap(Ptr<T> &a, Ptr<T> &b)
-{
- a.swap(b);
-}
-
-
-/**
- * Get the pointer globally, for <algo>
- */
-template<class T> T *
- get_pointer(const Ptr<T> &p)
-{
- return p.get();
-}
-
-/**
- * Static cast
- */
-template<class T, class U> Ptr<T>
- static_pointer_cast(const Ptr<U> &p)
-{
- return static_cast<T *>(p.get());
-}
-
-/**
- * Const cast
- */
-template<class T, class U> Ptr<T>
- const_pointer_cast(const Ptr<U> &p)
-{
- return const_cast<T *>(p.get());
-}
-
-/**
- * Dynamic cast
- */
-template<class T, class U> Ptr<T>
- dynamic_pointer_cast(const Ptr<U> &p)
-{
- return dynamic_cast<T *>(p.get());
-}
/**
- *
+ * This is used for opaque references to arbitrary objects from
+ * the DOM tree.
*/
typedef void DOMObject;
+/**
+ * Forward references. These are needed because of extensive
+ * inter-referencing within the DOM tree.
+ */
class NodeList;
class NamedNodeMap;
class DOMException;
class DOMLocator;
class DOMConfiguration;
+/**
+ * Smart pointer definitions. Most methods that return references to
+ * Nodes of various types, will return one of these smart pointers instead,
+ * to allow refcounting and GC.
+ */
class Node;
typedef Ptr<Node> NodePtr;
class CharacterData;
/*#########################################################################
## DOMException
#########################################################################*/
+
/**
- * This is the only non-interface class
+ * An Exception class. Not an interface, since this is something that
+ * all implementations must support.
*/
class DOMException
{
{}
/**
- *
+ * What type of exception? One of the ExceptionCodes above.
*/
unsigned short code;
/**
- *
+ * Some text describing the context that generated this exception.
*/
DOMString msg;
## DOMStringList
#########################################################################*/
+/**
+ * This holds a list of DOMStrings. This is likely the response to a query,
+ * or the value of an attribute.
+ */
class DOMStringList
{
public:
/**
- *
+ * Get the nth string of the list
*/
virtual DOMString item(unsigned long index)
{
}
/**
- *
+ * How many strings in this list?
*/
virtual unsigned long getLength()
{
}
/**
- *
+ * Is the argument string present in this list? Lexically, not identically.
*/
virtual bool contains(const DOMString &str)
{
/*#########################################################################
## NameList
#########################################################################*/
-class NamePair
-{
-public:
- NamePair(const DOMString &theNamespaceURI, const DOMString &theName)
- {
- namespaceURI = theNamespaceURI;
- name = theName;
- }
- NamePair(const NamePair &other)
- {
- namespaceURI = other.namespaceURI;
- name = other.name;
- }
- NamePair &operator=(const NamePair &other)
- {
- namespaceURI = other.namespaceURI;
- name = other.name;
- return *this;
- }
- virtual ~NamePair() {}
-
- DOMString namespaceURI;
- DOMString name;
-};
-
+/**
+ * Constains a list of namespaced names.
+ */
class NameList
{
+private:
+
+ class NamePair
+ {
+ public:
+ NamePair(const DOMString &theNamespaceURI, const DOMString &theName)
+ {
+ namespaceURI = theNamespaceURI;
+ name = theName;
+ }
+ NamePair(const NamePair &other)
+ {
+ namespaceURI = other.namespaceURI;
+ name = other.name;
+ }
+ NamePair &operator=(const NamePair &other)
+ {
+ namespaceURI = other.namespaceURI;
+ name = other.name;
+ return *this;
+ }
+ virtual ~NamePair() {}
+
+ DOMString namespaceURI;
+ DOMString name;
+ };
+
public:
/**
- *
+ * Returns a name at the given index. If out of range, return -1.
*/
virtual DOMString getName(unsigned long index)
{
}
/**
- *
+ * Returns a namespace at the given index. If out of range, return -1.
*/
virtual DOMString getNamespaceURI(unsigned long index)
{
}
/**
- *
+ * Return the number of entries in this list.
*/
virtual unsigned long getLength()
{
}
/**
- *
+ * Return whether the name argument is present in the list.
+ * This is done lexically, not identically.
*/
virtual bool contains(const DOMString &name)
{
}
/**
- *
+ * Return whether the namespaced name argument is present in the list.
+ * This is done lexically, not identically.
*/
virtual bool containsNS(const DOMString namespaceURI,const DOMString &name)
{
*
*/
virtual ~NameList() {}
+
+
protected:
std::vector<NamePair> namePairs;
## DOMImplementationList
#########################################################################*/
+/**
+ * Contains a list of DOMImplementations, with accessors.
+ */
class DOMImplementationList
{
public:
/**
- *
+ * Return a DOMImplementation at the given index. If
+ * out of range, return NULL.
*/
virtual DOMImplementation *item(unsigned long index)
{
}
/**
- *
+ * Return the number of DOMImplementations in this list.
*/
virtual unsigned long getLength()
{
}
-
-
//##################
//# Non-API methods
//##################
## DOMImplementationSource
#########################################################################*/
+/**
+ * This is usually the first item to be called when creating a Document.
+ * You will either find one DOMImplementation with a given set of features,
+ * or return a list that match. Using "" will get any implementation
+ * available.
+ */
class DOMImplementationSource
{
public:
/**
- *
+ * Return the first DOMImplementation with the given set of features.
+ * Use "" to fetch any implementation.
*/
virtual DOMImplementation *getDOMImplementation(const DOMString &features) = 0;
/**
- *
+ * Return a list of DOMImplementations with the given set of features.
+ * Use "" to fetch any implementation.
*/
virtual DOMImplementationList getDOMImplementationList(const DOMString &features) = 0;
/*#########################################################################
## DOMImplementation
#########################################################################*/
+
/**
- *
+ * This is the class that actually creates a Document.
*/
class DOMImplementation
{
public:
+
/**
- *
+ * Determine if this implementation has the given feature and version.
*/
virtual bool hasFeature(const DOMString& feature, const DOMString& version) = 0;
/**
- *
+ * Create a document type to be used in creating documents.
*/
virtual DocumentTypePtr createDocumentType(
const DOMString& qualifiedName,
throw(DOMException) = 0;
/**
- *
+ * Create a DOM document.
*/
virtual DocumentPtr createDocument(const DOMString& namespaceURI,
const DOMString& qualifiedName,
DocumentTypePtr doctype)
throw(DOMException) = 0;
/**
- *
+ * Return the thing which is the feature of this implementation. Since
+ * this is a "one size fits all" call, you will need to typecast the
+ * result to the expected type.
*/
virtual DOMObject *getFeature(const DOMString& feature,
const DOMString& version) = 0;
/**
* The basic Node class, which is the root of most other
- * classes in DOM.
+ * classes in DOM. Thus it is by far the most important, and the one
+ * whose implementation we must perform correctly.
*/
class Node
{
public:
+ /**
+ * Which of the DOM Core node types is this node?
+ */
typedef enum
{
ELEMENT_NODE = 1,
} NodeType;
/**
- *
+ * Return the name of this node.
*/
virtual DOMString getNodeName() = 0;
/**
- *
+ * Return the value of this node. The interpretation of the
+ * value is type-specific.
*/
virtual DOMString getNodeValue() throw (DOMException) = 0;
/**
- *
+ * Set the value of this node. The interpretation of the
+ * value is type-specific.
*/
virtual void setNodeValue(const DOMString& val) throw (DOMException) = 0;
/**
- *
+ * Return the type of this Node. One of the NodeType values above.
*/
virtual unsigned short getNodeType() = 0;
/**
- *
+ * Return the parent which references this node as a child in the DOM
+ * tree. Return NULL if there is none.
*/
virtual NodePtr getParentNode() = 0;
/**
- *
+ * Return a list of the children of this Node.
+ * NOTE: the spec expects this to be a "live" list that always
+ * reflects an accurate list of what the Node current possesses, not
+ * a snapshot. How do we do this?
*/
virtual NodeList getChildNodes() = 0;
/**
- *
+ * Return the first sibling of the chidren of this node. Return
+ * null if there is none.
*/
virtual NodePtr getFirstChild() = 0;
/**
- *
+ * Return the last sibling of the children of this node. Return
+ * null if there is none.
*/
virtual NodePtr getLastChild() = 0;
/**
- *
+ * Return the node that is previous to this one in the parent's
+ * list of children. Return null if there is none.
*/
virtual NodePtr getPreviousSibling() = 0;
/**
- *
+ * Return the node that is after this one in the parent's list
+ * of children. Return null if there is none.
*/
virtual NodePtr getNextSibling() = 0;
/**
- *
+ * Get the list of all attributes of this node.
*/
virtual NamedNodeMap &getAttributes() = 0;
/**
- *
+ * Return the document that created or inherited this node.
*/
virtual DocumentPtr getOwnerDocument() = 0;
/**
- *
+ * Insert a node as a new child. Place it before the referenced child.
+ * Place it at the end if the referenced child does not exist.
*/
virtual NodePtr insertBefore(const NodePtr newChild,
const NodePtr refChild)
throw(DOMException) = 0;
/**
- *
+ * Insert a node as a new child. Replace the referenced child with it.
+ * Place it at the end if the referenced child does not exist.
*/
virtual NodePtr replaceChild(const NodePtr newChild,
const NodePtr oldChild)
throw(DOMException) = 0;
/**
- *
+ * Remove a node from the list of children. Do nothing if the
+ * node is not a member of the child list.
*/
virtual NodePtr removeChild(const NodePtr oldChild)
throw(DOMException) = 0;
/**
- *
+ * Add the node to the end of this node's child list.
*/
virtual NodePtr appendChild(const NodePtr newChild)
throw(DOMException) = 0;
/**
- *
+ * Return true if this node has one or more children, else return false.
*/
virtual bool hasChildNodes() = 0;
/**
- *
+ * Return a new node which has the name, type, value, attributes, and
+ * child list as this one.
+ * If 'deep' is true, continue cloning recursively with this node's children,
+ * so that the child list also contains clones of their respective nodes.
*/
virtual NodePtr cloneNode(bool deep) = 0;
/**
- *
+ * Adjust this node and its children to have its namespaces and
+ * prefixes in "canonical" order.
*/
virtual void normalize() = 0;
/**
- *
+ * Return true if the named feature is supported by this node,
+ * else false.
*/
virtual bool isSupported(const DOMString& feature,
const DOMString& version) = 0;
/**
- *
+ * Return the namespace of this node. This would be whether the
+ * namespace were declared explicitly on this node, it has a namespace
+ * prefix, or it is inherits the namespace from an ancestor node.
*/
virtual DOMString getNamespaceURI() = 0;
/**
- *
+ * Return the namespace prefix of this node, if any. For example, if
+ * the tag were <svg:image> then the prefix would be "svg"
*/
virtual DOMString getPrefix() = 0;
/**
- *
+ * Sets the namespace prefix of this node to the given value. This
+ * does not change the namespaceURI value.
*/
virtual void setPrefix(const DOMString& val) throw(DOMException) = 0;
/**
- *
+ * Return the local name of this node. This is merely the name without
+ * any namespace or prefix.
*/
virtual DOMString getLocalName() = 0;
/**
- *
+ * Return true if this node has one or more attributes, else false.
*/
virtual bool hasAttributes() = 0;
/**
- *
+ * Return the base URI of this node. This is basically the "location" of this
+ * node, and is used in resolving the relative locations of other URIs.
*/
virtual DOMString getBaseURI() = 0;
+ /**
+ * DocumentPosition.
+ * This is used to describe the position of one node relative
+ * to another in a document
+ */
typedef enum
{
DOCUMENT_POSITION_DISCONNECTED = 0x01,
/**
- *
+ * Get the position of this node relative to the node argument.
*/
virtual unsigned short compareDocumentPosition(
const NodePtr other) = 0;
/**
- *
+ * This is a DOM L3 method. Return the text value of this node and its
+ * children. This is done by concatenating all of the TEXT_NODE and
+ * CDATA_SECTION nodes of this node and its children, in order, together.
+ * Very handy.
*/
virtual DOMString getTextContent() throw(DOMException) = 0;
/**
- *
+ * This is a DOM L3 method. Remember, this is a destructive call. This
+ * will replace all of the child nodes of this node with a single TEXT_NODE
+ * with the given text value.
*/
virtual void setTextContent(const DOMString &val) throw(DOMException) = 0;
/**
- *
+ * This will search the tree from this node up, for a prefix that
+ * has been assigned to the namespace argument. Return "" if not found.
*/
virtual DOMString lookupPrefix(const DOMString &namespaceURI) =0;
/**
- *
+ * Return true if this node is in the namespace of the argument, without
+ * requiring an explicit namespace declaration or a suffix.
*/
virtual bool isDefaultNamespace(const DOMString &namespaceURI) =0;
/**
- *
+ * This will search the tree from this node up, for a namespace that
+ * has been assigned the suffix in the argument. Return "" if not found.
*/
virtual DOMString lookupNamespaceURI(const DOMString &prefix) =0;
/**
- *
+ * Return true if the argument node is equal to this one. Use W3C rules
+ * for equality.
*/
virtual bool isEqualNode(const NodePtr node) =0;
/**
- *
+ * Return an opaque reference to the named feature. Return null if
+ * not supported. Using other than "" for the version will look for
+ * a feature with the given version.
*/
virtual DOMObject *getFeature(const DOMString &feature,
const DOMString &version) =0;
/**
- *
+ * Store a user data reference in this node, using the given key.
+ * A handler is an optional function object that will be called during
+ * future settings of this value. See UserDataHandler for more info.
*/
virtual DOMUserData *setUserData(const DOMString &key,
const DOMUserData *data,
/**
- *
+ * Return a reference to the named user data object. Return null
+ * if it does not exist.
*/
- virtual DOMUserData *getUserData(const DOMString &namespaceURI) =0;
+ virtual DOMUserData *getUserData(const DOMString &key) =0;
//##################
//# Non-API methods
#########################################################################*/
/**
- *
+ * Contains a list of Nodes. This is the standard API container for Nodes,
+ * and is used in lieu of other lists, arrays, etc, in order to provide
+ * a consistent API and algorithm.
*/
class NodeList
{
public:
+
/**
- *
+ * Retrieve the Node at the given index. Return NULL
+ * if out of range.
*/
virtual NodePtr item(unsigned long index)
{
}
/**
- *
+ * Get the number of nodes in this list
*/
virtual unsigned long getLength()
{
return (unsigned long) nodes.size();
}
+
//##################
//# Non-API methods
//##################
-
/**
*
*/
## NamedNodeMap
#########################################################################*/
-class NamedNodeMapEntry
-{
-public:
- NamedNodeMapEntry(const DOMString &theNamespaceURI,
- const DOMString &theName,
- const NodePtr theNode)
- {
- namespaceURI = theNamespaceURI;
- name = theName;
- node = theNode;
- }
- NamedNodeMapEntry(const NamedNodeMapEntry &other)
- {
- assign(other);
- }
- NamedNodeMapEntry &operator=(const NamedNodeMapEntry &other)
- {
- assign(other);
- return *this;
- }
- virtual ~NamedNodeMapEntry()
- {
- }
- void assign(const NamedNodeMapEntry &other)
- {
- namespaceURI = other.namespaceURI;
- name = other.name;
- node = other.node;
- }
- DOMString namespaceURI;
- DOMString name;
- NodePtr node;
-};
-
/**
- *
+ * Contains a mapping from name->NodePtr. Used for various purposes. For
+ * example, a list of Attributes is a NamedNodeMap.
*/
class NamedNodeMap
{
+private:
+
+ /**
+ * table entry. Not an API item
+ */
+ class NamedNodeMapEntry
+ {
+ public:
+ NamedNodeMapEntry(const DOMString &theNamespaceURI,
+ const DOMString &theName,
+ const NodePtr theNode)
+ {
+ namespaceURI = theNamespaceURI;
+ name = theName;
+ node = theNode;
+ }
+ NamedNodeMapEntry(const NamedNodeMapEntry &other)
+ {
+ assign(other);
+ }
+ NamedNodeMapEntry &operator=(const NamedNodeMapEntry &other)
+ {
+ assign(other);
+ return *this;
+ }
+ virtual ~NamedNodeMapEntry()
+ {
+ }
+ void assign(const NamedNodeMapEntry &other)
+ {
+ namespaceURI = other.namespaceURI;
+ name = other.name;
+ node = other.node;
+ }
+ DOMString namespaceURI;
+ DOMString name;
+ NodePtr node;
+ };
+
+
public:
/**
- *
+ * Return the named node. Return nullptr if not found.
*/
virtual NodePtr getNamedItem(const DOMString& name)
{
}
/**
- *
+ * Adds a node using its nodeName attribute. If a node with that name is already
+ * present in this map, it is replaced by the new one. Replacing a node by itself
+ * has no effect.
*/
virtual NodePtr setNamedItem(NodePtr arg) throw(DOMException)
{
/**
- *
+ * Removes a node specified by name.
*/
virtual NodePtr removeNamedItem(const DOMString& name) throw(DOMException)
{
}
/**
- *
+ * Retrieves an item at the given index. If out of bounds, return NULL
*/
virtual NodePtr item(unsigned long index)
{
}
/**
- *
+ * Return the number of items in this map
*/
virtual unsigned long getLength()
{
}
/**
- *
+ * Retrieves a node specified by local name and namespace URI.
*/
virtual NodePtr getNamedItemNS(const DOMString& namespaceURI,
const DOMString& localName)
}
/**
- *
+ * Adds a node using its namespaceURI and localName. If a node with that
+ * namespace URI and that local name is already present in this map, it is
+ * replaced by the new one. Replacing a node by itself has no effect.
*/
virtual NodePtr setNamedItemNS(NodePtr arg) throw(DOMException)
{
}
/**
- *
+ * Removes a node specified by local name and namespace URI.
*/
virtual NodePtr removeNamedItemNS(const DOMString& namespaceURI,
const DOMString& localName)
return NULL;
}
+
//##################
//# Non-API methods
//##################
#########################################################################*/
/**
- *
+ * This is the base class for other text-oriented Nodes, such as TEXT_NODE
+ * or CDATA_SECTION_NODE. No DOM objects correspond directly to CharacterData.
*/
class CharacterData : virtual public Node
{
public:
/**
- *
+ * This is an alias for getNodeValue()
*/
virtual DOMString getData() throw(DOMException) = 0;
/**
- *
+ * This is an alias for setNodeValue()
*/
virtual void setData(const DOMString& val) throw(DOMException) = 0;
/**
- *
+ * Return the number of characters contained in this node's data
*/
virtual unsigned long getLength() = 0;
/**
- *
+ * Return a substring of this node's data, starting at offset, and
+ * continuing for 'count' characters. Throw an exception if this goes
+ * out of range.
*/
virtual DOMString substringData(unsigned long offset,
unsigned long count)
throw(DOMException) = 0;
/**
- *
+ * Append the argument string to the end of the node's current data.
*/
virtual void appendData(const DOMString& arg) throw(DOMException) = 0;
/**
- *
+ * Insert the argument string at the offset position into the node's
+ * current data. If the position is out of range, throw an Exception.
*/
virtual void insertData(unsigned long offset,
const DOMString& arg)
throw(DOMException) = 0;
/**
- *
+ * Delete 'count' characters from the node's data starting from the
+ * offset position. If this goes out of range, throw an Exception.
*/
virtual void deleteData(unsigned long offset,
unsigned long count)
throw(DOMException) = 0;
/**
- *
+ * Replace the 'count' characters at the offset position with the given
+ * argument string. If this goes out of range, throw an Exception.
*/
virtual void replaceData(unsigned long offset,
unsigned long count,
};
-typedef Ptr<CharacterData> CharacterDataPtr;
-
-
/*#########################################################################
#########################################################################*/
/**
- *
+ * The Attr interface represents an attribute in an Element object.
+ * Typically the allowable values for the attribute are defined in a
+ * schema associated with the document.
+ * Since Attrs are not considered to be part of the DOM tree, parent,
+ * previousSibling, and nextSibling are null.
*/
class Attr : virtual public Node
{
public:
/**
- *
+ * Returns the name of this attribute. If Node.localName is different
+ * from null, this attribute is a qualified name.
*/
virtual DOMString getName() = 0;
/**
- *
+ * True if this attribute was explicitly given a value in the instance document,
+ * false otherwise. If the application changed the value of this attribute node
+ * (even if it ends up having the same value as the default value) then it is set
+ * to true. The implementation may handle attributes with default values from
+ * other schemas similarly but applications should use
+ * Document.normalizeDocument() to guarantee this information is up-to-date.
*/
virtual bool getSpecified() = 0;
/**
- *
+ * Returns the value of the attribute
*/
virtual DOMString getValue() = 0;
/**
- *
+ * Sets the value of the attribute
*/
virtual void setValue(const DOMString& val) throw(DOMException) = 0;
/**
- *
+ * Return the Element that possesses this attribute
*/
virtual ElementPtr getOwnerElement() = 0;
/**
- *
+ * The type information associated with this attribute.
*/
virtual TypeInfo &getSchemaTypeInfo() = 0;
/**
- *
+ * Returns whether this attribute is known to be of type ID (i.e. to contain an
+ * identifier for its owner element) or not. When it is and its value is unique,
+ * the ownerElement of this attribute can be retrieved using the method
+ * Document.getElementById.
*/
virtual bool getIsId() = 0;
#########################################################################*/
/**
- *
+ * The Element interface represents an element in an XML document.
+ * Elements may have attributes associated with them; since the Element interface
+ * inherits from Node, the generic Node interface attribute attributes may be
+ * used to retrieve the set of all attributes for an element. There are methods
+ * on the Element interface to retrieve either an Attr object by name or an
+ * attribute value by name. In XML, where an attribute value may contain entity
+ * references, an Attr object should be retrieved to examine the possibly fairly
+ * complex sub-tree representing the attribute value. On the other hand, in HTML,
+ * where all attributes have simple string values, methods to directly access an
+ * attribute value can safely be used as a convenience.
*/
class Element : virtual public Node
{
/**
- *
+ * The name of the element. If Node.localName is different from null,
+ * this attribute is a qualified name.
*/
virtual DOMString getTagName() = 0;
/**
- *
+ * Retrieves an attribute value by name.
*/
virtual DOMString getAttribute(const DOMString& name) = 0;
/**
- *
+ * Adds a new attribute. If an attribute with that name is already present in the
+ * element, its value is changed to be that of the value parameter. This value is
+ * a simple string; it is not parsed as it is being set. So any markup (such as
+ * syntax to be recognized as an entity reference) is treated as literal text,
+ * and needs to be appropriately escaped by the implementation when it is written
+ * out. In order to assign an attribute value that contains entity references,
+ * the user must create an Attr node plus any Text and EntityReference nodes,
+ * build the appropriate subtree, and use setAttributeNode to assign it as the
+ * value of an attribute.
*/
virtual void setAttribute(const DOMString& name,
const DOMString& value)
throw(DOMException) = 0;
/**
- *
+ * Removes an attribute by name. If no attribute with this name is found,
+ * this method has no effect.
*/
virtual void removeAttribute(const DOMString& name)
throw(DOMException) = 0;
/**
- *
+ * Retrieves an attribute node by name.
*/
virtual AttrPtr getAttributeNode(const DOMString& name) = 0;
/**
- *
+ * Adds a new attribute node. If an attribute with that name (nodeName)
+ * is already present in the element, it is replaced by the new one.
+ * Replacing an attribute node by itself has no effect.
*/
virtual AttrPtr setAttributeNode(AttrPtr newAttr)
throw(DOMException) = 0;
/**
- *
+ * Removes the specified attribute node.
*/
virtual AttrPtr removeAttributeNode(AttrPtr oldAttr)
throw(DOMException) = 0;
/**
- *
+ * Returns a NodeList of all descendant Elements with a given tag name,
+ * in document order.
*/
virtual NodeList getElementsByTagName(const DOMString& name) = 0;
/**
- *
+ * Retrieves an attribute value by local name and namespace URI.
+ * Per [XML Namespaces], applications must use the value null as the
+ * namespaceURI parameter for methods if they wish to have no namespace.
*/
virtual DOMString getAttributeNS(const DOMString& namespaceURI,
const DOMString& localName) = 0;
/**
- *
+ * Adds a new attribute. If an attribute with the same local name and namespace
+ * URI is already present on the element, its prefix is changed to be the prefix
+ * part of the qualifiedName, and its value is changed to be the value parameter.
+ * This value is a simple string; it is not parsed as it is being set. So any
+ * markup (such as syntax to be recognized as an entity reference) is treated as
+ * literal text, and needs to be appropriately escaped by the implementation when
+ * it is written out. In order to assign an attribute value that contains entity
+ * references, the user must create an Attr node plus any Text and
+ * EntityReference nodes, build the appropriate subtree, and use
+ * setAttributeNodeNS or setAttributeNode to assign it as the value of an
+ * attribute.
*/
virtual void setAttributeNS(const DOMString& namespaceURI,
const DOMString& qualifiedName,
throw(DOMException) = 0;
/**
- *
+ * Removes an attribute by local name and namespace URI.
*/
virtual void removeAttributeNS(const DOMString& namespaceURI,
const DOMString& localName)
throw(DOMException) = 0;
/**
- *
+ * Retrieves an Attr node by local name and namespace URI.
*/
virtual AttrPtr getAttributeNodeNS(const DOMString& namespaceURI,
const DOMString& localName) = 0;
/**
- *
+ * Adds a new attribute. If an attribute with that local name and
+ * that namespace URI is already present in the element, it is
+ * replaced by the new one. Replacing an attribute node by itself has no effect.
*/
virtual AttrPtr setAttributeNodeNS(AttrPtr newAttr)
throw(DOMException) = 0;
/**
- *
+ * Returns a NodeList of all the descendant Elements with a given
+ * local name and namespace URI in document order.
*/
virtual NodeList getElementsByTagNameNS(const DOMString& namespaceURI,
const DOMString& localName) = 0;
/**
- *
+ * Returns true when an attribute with a given name is specified on
+ * this element or has a default value, false otherwise.
*/
virtual bool hasAttribute(const DOMString& name) = 0;
/**
- *
+ * Returns true when an attribute with a given local name and namespace
+ * URI is specified on this element or has a default value, false otherwise.
*/
virtual bool hasAttributeNS(const DOMString& namespaceURI,
const DOMString& localName) = 0;
/**
- *
+ * The type information associated with this element.
*/
virtual TypeInfo &getSchemaTypeInfo() = 0;
/**
- *
+ * If the parameter isId is true, this method declares the specified
+ * attribute to be a user-determined ID attribute.
*/
virtual void setIdAttribute(const DOMString &name,
bool isId) throw (DOMException) = 0;
/**
- *
+ * If the parameter isId is true, this method declares the specified
+ * attribute to be a user-determined ID attribute.
*/
virtual void setIdAttributeNS(const DOMString &namespaceURI,
const DOMString &localName,
bool isId) throw (DOMException) = 0;
/**
- *
+ * If the parameter isId is true, this method declares the specified
+ * attribute to be a user-determined ID attribute.
*/
virtual void setIdAttributeNode(const AttrPtr idAttr,
bool isId) throw (DOMException) = 0;
#########################################################################*/
/**
- *
+ * The Text interface inherits from CharacterData and represents the textual
+ * content (termed character data in XML) of an Element or Attr. If there is no
+ * markup inside an element's content, the text is contained in a single object
+ * implementing the Text interface that is the only child of the element. If
+ * there is markup, it is parsed into the information items (elements, comments,
+ * etc.) and Text nodes that form the list of children of the element.
*/
class Text : virtual public CharacterData
{
public:
/**
- *
+ * Breaks this node into two nodes at the specified offset, keeping both in the
+ * tree as siblings. After being split, this node will contain all the content up
+ * to the offset point. A new node of the same type, which contains all the
+ * content at and after the offset point, is returned. If the original node had a
+ * parent node, the new node is inserted as the next sibling of the original
+ * node. When the offset is equal to the length of this node, the new node has no
+ * data.
*/
virtual TextPtr splitText(unsigned long offset)
throw(DOMException) = 0;
/**
- *
+ * Returns whether this text node contains element content whitespace, often
+ * abusively called "ignorable whitespace". The text node is determined to
+ * contain whitespace in element content during the load of the document or if
+ * validation occurs while using Document.normalizeDocument().
*/
virtual bool getIsElementContentWhitespace()= 0;
/**
- *
+ * Returns all text of Text nodes logically-adjacent text nodes
+ * to this node, concatenated in document order.
*/
virtual DOMString getWholeText() = 0;
/**
+ * Replaces the text of the current node and all logically-adjacent text nodes
+ * with the specified text. All logically-adjacent text nodes are removed
+ * including the current node unless it was the recipient of the replacement text.
*
+ * This method returns the node which received the replacement text. The returned
+ * node is:
+ * o null, when the replacement text is the empty string;
+ * o the current node, except when the current node is read-only;
+ * o a new Text node of the same type (Text or CDATASection) as
+ * the current node inserted at the location of the replacement.
*/
virtual TextPtr replaceWholeText(const DOMString &content)
throw(DOMException) = 0;
#########################################################################*/
/**
- *
+ * This interface inherits from CharacterData and represents the content of a
+ * comment, i.e., all the characters between the starting '<!--' and ending '-->'.
+ * Note that this is the definition of a comment in XML, and, in practice,
+ * HTML, although some HTML tools may implement the full SGML comment structure.
*/
class Comment : virtual public CharacterData
{
#########################################################################*/
/**
- *
+ * The TypeInfo interface represents a type referenced from Element or Attr nodes,
+ * specified in the schemas associated with the document. The type is a pair of
+ * a namespace URI and name properties, and depends on the document's schema.
*/
class TypeInfo
{
public:
/**
- *
+ * The name of a type declared for the associated element or attribute,
+ * or null if unknown.
*/
virtual DOMString getTypeName()
{ return typeName; }
/**
- *
+ * The namespace of the type declared for the associated element
+ * or attribute or null if the element does not have declaration or
+ * if no namespace information is available.
*/
virtual DOMString getTypeNamespace()
{ return typeNameSpace; }
+ /**
+ * These are the available values for the derivationMethod parameter used by the
+ * method TypeInfo.isDerivedFrom(). It is a set of possible types of derivation,
+ * and the values represent bit positions. If a bit in the derivationMethod
+ * parameter is set to 1, the corresponding type of derivation will be taken into
+ * account when evaluating the derivation between the reference type definition
+ * and the other type definition. When using the isDerivedFrom method, combining
+ * all of them in the derivationMethod parameter is equivalent to invoking the
+ * method for each of them separately and combining the results with the OR
+ * boolean function. This specification only defines the type of derivation for
+ * XML Schema.
+ */
typedef enum
{
DERIVATION_RESTRICTION = 0x00000001,
/**
- *
+ * This method returns if there is a derivation between the reference
+ * type definition, i.e. the TypeInfo on which the method is being called,
+ * and the other type definition, i.e. the one passed as parameters.
*/
- virtual bool isDerivedFrom(const DOMString &typeNamespaceArg,
- const DOMString &typeNameArg,
- DerivationMethod derivationMethod)
- { (void)typeNamespaceArg; (void)typeNameArg; (void)derivationMethod; return false; }
+ virtual bool isDerivedFrom(const DOMString &/*typeNamespaceArg*/,
+ const DOMString &/*typeNameArg*/,
+ DerivationMethod /*derivationMethod*/)
+ { return false; }
//##################
//# Non-API methods
#########################################################################*/
/**
- *
+ * When associating an object to a key on a node using Node.setUserData() the
+ * application can provide a handler that gets called when the node the object is
+ * associated to is being cloned, imported, or renamed. This can be used by the
+ * application to implement various behaviors regarding the data it associates to
+ * the DOM nodes. This interface defines that handler.
*/
class UserDataHandler
{
public:
+ /**
+ * An integer indicating the type of operation being performed on a node.
+ */
typedef enum
{
NODE_CLONED = 1,
/**
- *
+ * This method is called whenever the node for which this handler
+ * is registered is imported or cloned.
*/
virtual void handle(unsigned short operation,
const DOMString &key,
#########################################################################*/
/**
- *
+ * DOMError is an interface that describes an error.
*/
class DOMError
{
public:
+ /**
+ * An integer indicating the severity of the error.
+ */
typedef enum
{
SEVERITY_WARNING = 1,
/**
- *
+ * The severity of the error, either SEVERITY_WARNING, SEVERITY_ERROR,
+ * or SEVERITY_FATAL_ERROR.
*/
virtual unsigned short getSeverity() =0;
/**
- *
+ * An implementation specific string describing the error that occurred.
*/
virtual DOMString getMessage() =0;
/**
- *
+ * A DOMString indicating which related data is expected in relatedData.
+ * Users should refer to the specification of the error in order to find
+ * its DOMString type and relatedData definitions if any.
*/
virtual DOMString getType() =0;
/**
- *
+ * The related platform dependent exception if any.
*/
virtual DOMObject *getRelatedException() =0;
/**
- *
+ * The related DOMError.type dependent data if any.
*/
virtual DOMObject *getRelatedData() =0;
/**
- *
+ * The location of the error.
*/
virtual DOMLocator *getLocation() =0;
#########################################################################*/
/**
- *
+ * DOMErrorHandler is a callback interface that the DOM implementation can call
+ * when reporting errors that happens while processing XML data, or when doing
+ * some other processing (e.g. validating a document). A DOMErrorHandler object
+ * can be attached to a Document using the "error-handler" on the
+ * DOMConfiguration interface. If more than one error needs to be reported during
+ * an operation, the sequence and numbers of the errors passed to the error
+ * handler are implementation dependent.
*/
class DOMErrorHandler
{
public:
+
/**
- *
+ * This method is called on the error handler when an error occurs.
+ * If an exception is thrown from this method, it is considered to be
+ * equivalent of returning true.
*/
virtual bool handleError(const DOMError *error) =0;
+
//##################
//# Non-API methods
//##################
-
/**
*
*/
#########################################################################*/
/**
- *
+ * DOMLocator is an interface that describes a location (e.g. where an error occurred).
*/
class DOMLocator
{
public:
/**
- *
+ * The line number this locator is pointing to, or -1 if there is
+ * no column number available.
*/
virtual long getLineNumber() =0;
/**
- *
+ * The column number this locator is pointing to, or -1 if there is
+ * no column number available.
*/
virtual long getColumnNumber() =0;
/**
- *
+ * The byte offset into the input source this locator is pointing to
+ * or -1 if there is no byte offset available.
*/
virtual long getByteOffset() =0;
/**
- *
+ * The UTF-16, as defined in [Unicode] and Amendment 1 of [ISO/IEC 10646],
+ * offset into the input source this locator is pointing to or -1
+ * if there is no UTF-16 offset available.
*/
virtual long getUtf16Offset() =0;
/**
- *
+ * The node this locator is pointing to, or null if no node is available.
*/
virtual NodePtr getRelatedNode() =0;
/**
- *
+ * The URI this locator is pointing to, or null if no URI is available.
*/
virtual DOMString getUri() =0;
#########################################################################*/
/**
+ * The DOMConfiguration interface represents the configuration of a document and
+ * maintains a table of recognized parameters. Using the configuration, it is
+ * possible to change Document.normalizeDocument() behavior, such as replacing
+ * the CDATASection nodes with Text nodes or specifying the type of the schema
+ * that must be used when the validation of the Document is requested.
+ * DOMConfiguration objects are also used in [DOM Level 3 Load and Save] in the
+ * DOMParser and DOMSerializer interfaces.
*
+ * Look here for a list of valid parameters:
+ * http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#DOMConfiguration
*/
class DOMConfiguration
{
public:
/**
- *
+ * Set the value of a parameter.
*/
virtual void setParameter(const DOMString &name,
const DOMUserData *value)
throw (DOMException) =0;
/**
- *
+ * Return the value of a parameter if known.
*/
virtual DOMUserData *getParameter(const DOMString &name)
throw (DOMException) =0;
/**
- *
+ * Check if setting a parameter to a specific value is supported.
*/
virtual bool canSetParameter(const DOMString &name,
const DOMUserData *data) =0;
/**
- *
+ * The list of the parameters supported by this DOMConfiguration
+ * object and for which at least one value can be set by the application.
+ * Note that this list can also contain parameter names defined outside
+ * this specification.
*/
virtual DOMStringList *getParameterNames() =0;
/*#########################################################################
## CDATASection
#########################################################################*/
+
/**
- *
+ * CDATA sections are used to escape blocks of text containing characters that
+ * would otherwise be regarded as markup. The only delimiter that is recognized
+ * in a CDATA section is the "]]>" string that ends the CDATA section. CDATA
+ * sections cannot be nested. Their primary purpose is for including material
+ * such as XML fragments, without needing to escape all the delimiters.
*/
class CDATASection : virtual public Text
{
#########################################################################*/
/**
- *
+ * Each Document has a doctype attribute whose value is either null or a
+ * DocumentType object. The DocumentType interface in the DOM Core provides an
+ * interface to the list of entities that are defined for the document, and
+ * little else because the effect of namespaces and the various XML schema
+ * efforts on DTD representation are not clearly understood as of this writing.
*/
class DocumentType : virtual public Node
{
public:
/**
- *
+ * The name of DTD; i.e., the name immediately following the DOCTYPE keyword.
*/
virtual DOMString getName() = 0;
/**
- *
+ * A NamedNodeMap containing the general entities, both external and
+ * internal, declared in the DTD. Parameter entities are not contained.
+ * Duplicates are discarded.
*/
virtual NamedNodeMap getEntities() = 0;
/**
- *
+ * A NamedNodeMap containing the notations declared in the DTD. Duplicates
+ * are discarded. Every node in this map also implements the
+ * Notation interface.
*/
virtual NamedNodeMap getNotations() = 0;
/**
- *
+ * The public identifier of the external subset.
*/
virtual DOMString getPublicId() = 0;
/**
- *
+ * The system identifier of the external subset. This may be an
+ * absolute URI or not.
*/
virtual DOMString getSystemId() = 0;
/**
- *
+ * The internal subset as a string, or null if there is none. This
+ * does not contain the delimiting square brackets.
*/
virtual DOMString getInternalSubset() = 0;
#########################################################################*/
/**
- *
+ * This interface represents a notation declared in the DTD. A notation either
+ * declares, by name, the format of an unparsed entity (see section 4.7 of the
+ * XML 1.0 specification [XML 1.0]), or is used for formal declaration of
+ * processing instruction targets (see section 2.6 of the XML 1.0 specification
+ * [XML 1.0]). The nodeName attribute inherited from Node is set to the declared
+ * name of the notation.
*/
class Notation : virtual public Node
{
public:
/**
- *
+ * The public identifier of this notation. If the public identifier was
+ * not specified, this is null.
*/
virtual DOMString getPublicId() = 0;
/**
- *
+ * The system identifier of this notation. If the system identifier was
+ * not specified, this is null. This may be an absolute URI or not.
*/
virtual DOMString getSystemId() = 0;
#########################################################################*/
/**
- *
+ * This interface represents a known entity, either parsed or unparsed, in an XML
+ * document. Note that this models the entity itself not the entity declaration.
*/
class Entity : virtual public Node
{
public:
/**
- *
+ * The public identifier associated with the entity if specified,
+ * and null otherwise.
*/
virtual DOMString getPublicId() = 0;
/**
- *
+ * The system identifier associated with the entity if specified,
+ * and null otherwise. This may be an absolute URI or not.
*/
virtual DOMString getSystemId() = 0;
/**
- *
+ * For unparsed entities, the name of the notation for the entity.
+ * For parsed entities, this is null.
*/
virtual DOMString getNotationName() = 0;
/**
- *
+ * An attribute specifying the encoding used for this entity at the
+ * time of parsing, when it is an external parsed entity. This is null
+ * if it an entity from the internal subset or if it is not known.
*/
virtual DOMString getInputEncoding() = 0;
/**
- *
+ * An attribute specifying, as part of the text declaration, the encoding
+ * of this entity, when it is an external parsed entity. This is null otherwise.
*/
virtual DOMString getXmlEncoding() = 0;
/**
- *
+ * An attribute specifying, as part of the text declaration, the version
+ * number of this entity, when it is an external parsed entity.
+ * This is null otherwise.
*/
virtual DOMString getXmlVersion() = 0;
/*#########################################################################
## EntityReference
#########################################################################*/
+
/**
- *
+ * EntityReference nodes may be used to represent an entity reference in the tree.
*/
class EntityReference : virtual public Node
{
#########################################################################*/
/**
- *
+ * The ProcessingInstruction interface represents a "processing instruction",
+ * used in XML as a way to keep processor-specific information in the text of the
+ * document.
*/
class ProcessingInstruction : virtual public Node
{
public:
/**
- *
+ * The target of this processing instruction. XML defines this as being
+ * the first token following the markup that begins the processing instruction.
*/
virtual DOMString getTarget() = 0;
/**
- *
+ * The content of this processing instruction. This is from the first non
+ * white space character after the target to the character immediately
+ * preceding the ?>.
*/
virtual DOMString getData() = 0;
/**
- *
+ * Sets the content above.
*/
virtual void setData(const DOMString& val) throw(DOMException) = 0;
/*#########################################################################
## DocumentFragment
#########################################################################*/
+
/**
- *
+ * DocumentFragment is a "lightweight" or "minimal" Document object. It is very
+ * common to want to be able to extract a portion of a document's tree or to
+ * create a new fragment of a document. Imagine implementing a user command like
+ * cut or rearranging a document by moving fragments around. It is desirable to
+ * have an object which can hold such fragments and it is quite natural to use a
+ * Node for this purpose. While it is true that a Document object could fulfill
+ * this role, a Document object can potentially be a heavyweight object,
+ * depending on the underlying implementation. What is really needed for this is
+ * a very lightweight object. DocumentFragment is such an object.
*/
class DocumentFragment : virtual public Node
{
#########################################################################*/
/**
+ * From the spec:
+ *
+ * The Document interface represents the entire HTML or XML document.
+ * Conceptually, it is the root of the document tree, and provides the primary
+ * access to the document's data.
+ *
+ * Since elements, text nodes, comments, processing instructions, etc. cannot
+ * exist outside the context of a Document, the Document interface also contains
+ * the factory methods needed to create these objects. The Node objects created
+ * have a ownerDocument attribute which associates them with the Document within
+ * whose context they were created.
*
*/
class Document : virtual public Node
public:
/**
- *
+ * The Document Type Declaration (see DocumentType) associated with this document.
*/
virtual DocumentTypePtr getDoctype() = 0;
/**
- *
+ * The DOMImplementation object that handles this document. A DOM application
+ * may use objects from multiple implementations.
*/
virtual DOMImplementation *getImplementation() = 0;
/**
- *
+ * This is a convenience attribute that allows direct access to the child
+ * node that is the document element of the document.
*/
virtual ElementPtr getDocumentElement() = 0;
/**
- *
+ * Creates an element of the type specified.
*/
virtual ElementPtr createElement(const DOMString& tagName)
throw(DOMException) = 0;
/**
- *
+ * Creates a new, empty DocumentFragment
*/
virtual DocumentFragmentPtr createDocumentFragment() = 0;
/**
- *
+ * Creates an Text node with the text data specified.
*/
- virtual TextPtr createTextNode(const DOMString& data) = 0;
+ virtual TextPtr createTextNode(const DOMString& text) = 0;
/**
- *
+ * Creates a new Comment node with the argument text
*/
- virtual CommentPtr createComment(const DOMString& data) = 0;
+ virtual CommentPtr createComment(const DOMString& text) = 0;
/**
- *
+ * Creates a new CDATASection node with the argument text
*/
- virtual CDATASectionPtr createCDATASection(const DOMString& data)
+ virtual CDATASectionPtr createCDATASection(const DOMString& text)
throw(DOMException) = 0;
/**
- *
+ * Creates a new ProcessingInstruction
*/
virtual ProcessingInstructionPtr
createProcessingInstruction(const DOMString& target,
throw(DOMException) = 0;
/**
- *
+ * Creates a new Attr with the given name, but no value.
*/
virtual AttrPtr createAttribute(const DOMString& name)
throw(DOMException) = 0;
/**
- *
+ * Creates a new EntityReference
*/
virtual EntityReferencePtr createEntityReference(const DOMString& name)
throw(DOMException) = 0;
/**
- *
+ * Searches the Document in document order for all elements with the given
+ * tag name
*/
virtual NodeList getElementsByTagName(const DOMString& tagname) = 0;
/**
- *
+ * Imports a node from another document to this document, without altering or
+ * removing the source node from the original document; this method creates a new
+ * copy of the source node. The returned node has no parent; (parentNode is
+ * null). For all nodes, importing a node creates a node object owned by the
+ * importing document, with attribute values identical to the source node's
+ * nodeName and nodeType, plus the attributes related to namespaces (prefix,
+ * localName, and namespaceURI). As in the cloneNode operation, the source node
+ * is not altered. User data associated to the imported node is not carried over.
+ * However, if any UserDataHandlers has been specified along with the associated
+ * data these handlers will be called with the appropriate parameters before this
+ * method returns. Additional information is copied as appropriate to the
+ * nodeType, attempting to mirror the behavior expected if a fragment of XML or
+ * HTML source was copied from one document to another, recognizing that the two
+ * documents may have different DTDs in the XML case. The following list
+ * describes the specifics for each type of node.
*/
virtual NodePtr importNode(const NodePtr importedNode,
bool deep)
throw(DOMException) = 0;
/**
- *
+ * Creates a new Element with the given namespace and qualifiedName.
+ * Use "" for no namespace
*/
virtual ElementPtr createElementNS(const DOMString& namespaceURI,
const DOMString& qualifiedName)
throw(DOMException) = 0;
/**
- *
+ * Creates a new Attr with the given namespace and qualifiedName.
*/
virtual AttrPtr createAttributeNS(const DOMString& namespaceURI,
const DOMString& qualifiedName)
throw(DOMException) = 0;
/**
- *
+ * Searches the Document in document order for all elements with the given
+ * namespace and tag name
*/
virtual NodeList getElementsByTagNameNS(const DOMString& namespaceURI,
const DOMString& localName) = 0;
/**
- *
+ * Gets the element with the given id if it exists, else null.
*/
virtual ElementPtr getElementById(const DOMString& elementId) = 0;
/**
- *
+ * Return the input encoding of this Document
*/
virtual DOMString getInputEncoding() = 0;
/**
- *
+ * Return the XML encoding of this Document
*/
virtual DOMString getXmlEncoding() = 0;
/**
- *
+ * An attribute specifying, as part of the XML declaration, whether
+ * this document is standalone. This is false when unspecified.
*/
virtual bool getXmlStandalone() = 0;
/**
- *
+ * Sets whether this is a standalone XML document. No validation is
+ * done here.
*/
virtual void setXmlStandalone(bool val) throw (DOMException) = 0;
/**
- *
+ * Gets the version (1.0, 1.1, etc) of this document.
*/
virtual DOMString getXmlVersion() = 0;
/**
- *
+ * Sets the XML version of this document.
*/
virtual void setXmlVersion(const DOMString &version)
throw (DOMException) = 0;
/**
- *
+ * An attribute specifying whether error checking is enforced or not. When set to
+ * false, the implementation is free to not test every possible error case
+ * normally defined on DOM operations, and not raise any DOMException on DOM
+ * operations or report errors while using Document.normalizeDocument(). In case
+ * of error, the behavior is undefined. This attribute is true by default.
*/
virtual bool getStrictErrorChecking() = 0;
/**
- *
+ * Sets the value described above.
*/
virtual void setStrictErrorChecking(bool val) = 0;
/**
- *
+ * Gets the document URI (the base location) of this Document.
*/
virtual DOMString getDocumentURI() = 0;
/**
- *
+ * Sets the document URI (the base location) of this Document to the
+ * argument uri.
*/
virtual void setDocumentURI(const DOMString &uri) = 0;
/**
- *
+ * Attempts to adopt a node from another document to this document. If supported,
+ * it changes the ownerDocument of the source node, its children, as well as the
+ * attached attribute nodes if there are any. If the source node has a parent it
+ * is first removed from the child list of its parent. This effectively allows
+ * moving a subtree from one document to another (unlike importNode() which
+ * create a copy of the source node instead of moving it). When it fails,
+ * applications should use Document.importNode() instead. Note that if the
+ * adopted node is already part of this document (i.e. the source and target
+ * document are the same), this method still has the effect of removing the
+ * source node from the child list of its parent, if any.
*/
virtual NodePtr adoptNode(const NodePtr source) throw (DOMException) = 0;
/**
- *
+ * Get the configuration item associated with this Document
*/
virtual DOMConfiguration *getDomConfig() = 0;
/**
- *
+ * This method acts as if the document was going through a save and load cycle,
+ * putting the document in a "normal" form. As a consequence, this method updates
+ * the replacement tree of EntityReference nodes and normalizes Text nodes, as
+ * defined in the method Node.normalize(). Otherwise, the actual result depends
+ * on the features being set on the Document.domConfig object and governing what
+ * operations actually take place. Noticeably this method could also make the
+ * document namespace well-formed according to the algorithm described in
+ * Namespace Normalization, check the character normalization, remove the
+ * CDATASection nodes, etc. See DOMConfiguration for details.
*/
virtual void normalizeDocument() = 0;
/**
+ *
+ * Rename an existing node of type ELEMENT_NODE or ATTRIBUTE_NODE. When possible
+ * this simply changes the name of the given node, otherwise this creates a new
+ * node with the specified name and replaces the existing node with the new node
+ * as described below. If simply changing the name of the given node is not
+ * possible, the following operations are performed: a new node is created, any
+ * registered event listener is registered on the new node, any user data
+ * attached to the old node is removed from that node, the old node is removed
+ * from its parent if it has one, the children are moved to the new node, if the
+ * renamed node is an Element its attributes are moved to the new node, the new
+ * node is inserted at the position the old node used to have in its parent's
+ * child nodes list if it has one, the user data that was attached to the old
+ * node is attached to the new node. When the node being renamed is an Element
+ * only the specified attributes are moved, default attributes originated from
+ * the DTD are updated according to the new element name. In addition, the
+ * implementation may update default attributes from other schemas. Applications
+ * should use Document.normalizeDocument() to guarantee these attributes are
+ * up-to-date. When the node being renamed is an Attr that is attached to an
+ * Element, the node is first removed from the Element attributes map. Then, once
+ * renamed, either by modifying the existing node or creating a new one as
+ * described above, it is put back.
+ *
+ * In addition,
+ * a user data event NODE_RENAMED is fired,
+ * when the implementation supports the feature "MutationNameEvents",
+ * each mutation operation involved in this method fires the appropriate
+ * event, and in the end the event {http://www.w3.org/2001/xml-events,
+ * DOMElementNameChanged} or {http://www.w3.org/2001/xml-events,
+ * DOMAttributeNameChanged} is fired.
*
*/
virtual NodePtr renameNode(const NodePtr n,