From 21730dc6548ae85ddb762c05221e9157a14ce7f6 Mon Sep 17 00:00:00 2001 From: dario Date: Wed, 15 Apr 1998 18:55:21 +0000 Subject: [PATCH] doc --- content/base/src/nsDocument.cpp | 2 +- content/base/src/nsDocument.h | 2 +- dom/public/coreDom/nsDOM.h | 20 +++ dom/public/coreDom/nsIDOMAttribute.h | 111 ++++++++++++++- dom/public/coreDom/nsIDOMDocument.h | 172 ++++++++++++++++++++++- dom/public/coreDom/nsIDOMElement.h | 83 +++++++++++ dom/public/coreDom/nsIDOMIterators.h | 81 +++++++++++ dom/public/coreDom/nsIDOMNode.h | 88 ++++++++++++ dom/public/coreDom/nsIDOMText.h | 72 +++++++++- dom/public/nsIScriptContext.h | 54 ++++++- dom/public/nsIScriptObject.h | 27 ++-- dom/public/nsIScriptObjectOwner.h | 29 +++- dom/tests/js/DumpHTML.js | 2 +- dom/tests/js/DumpTree.js | 2 +- dom/tests/js/HTMLString.js | Bin 2270 -> 2269 bytes dom/tests/js/simple.js | 2 +- layout/base/src/nsDocument.cpp | 2 +- layout/base/src/nsDocument.h | 2 +- layout/html/base/src/nsDOMAttributes.cpp | 4 +- layout/html/base/src/nsDOMAttributes.h | 4 +- 20 files changed, 717 insertions(+), 42 deletions(-) diff --git a/content/base/src/nsDocument.cpp b/content/base/src/nsDocument.cpp index 6f94c0a01752..02944ae636f3 100644 --- a/content/base/src/nsDocument.cpp +++ b/content/base/src/nsDocument.cpp @@ -610,7 +610,7 @@ nsresult nsDocument::CreateTreeIterator(nsIDOMNode **aNode, nsIDOMTreeIterator * return NS_ERROR_NOT_IMPLEMENTED; } -nsresult nsDocument::GetElementsByTagName(nsIDOMNodeIterator **aIterator) +nsresult nsDocument::GetElementsByTagName(nsString &aTagname, nsIDOMNodeIterator **aIterator) { //XXX TBI return NS_ERROR_NOT_IMPLEMENTED; diff --git a/content/base/src/nsDocument.h b/content/base/src/nsDocument.h index 7567f3c2a5e1..7897b190d76c 100644 --- a/content/base/src/nsDocument.h +++ b/content/base/src/nsDocument.h @@ -162,7 +162,7 @@ public: nsIDOMAttribute **aAttribute); virtual nsresult CreateAttributeList(nsIDOMAttributeList **aAttributesList); virtual nsresult CreateTreeIterator(nsIDOMNode **aNode, nsIDOMTreeIterator **aTreeIterator); - virtual nsresult GetElementsByTagName(nsIDOMNodeIterator **aIterator); + virtual nsresult GetElementsByTagName(nsString &aTagname, nsIDOMNodeIterator **aIterator); protected: virtual void AddStyleSheetToSet(nsIStyleSheet* aSheet, nsIStyleSet* aSet); // subclass hook diff --git a/dom/public/coreDom/nsDOM.h b/dom/public/coreDom/nsDOM.h index 725b2c900792..cccf9fbd311f 100644 --- a/dom/public/coreDom/nsDOM.h +++ b/dom/public/coreDom/nsDOM.h @@ -29,9 +29,29 @@ class nsString; 0x8f6bca70, 0xce42, 0x11d1, \ {0xb7, 0x24, 0x00, 0x60, 0x08, 0x91, 0xd8, 0xc9} } +/** + * The "DOM" interface provides a number of methods for performing operations that are + * independent of any particular instance of the document object model. + */ class nsIDOM : public nsISupports { public: + /** + * Creates a document of the specified type + * + * @param type [in] The type of document to create, i.e., "HTML" or "XML" + * @param aDocument [out] An instance of an HTML or XML document is created. Documents are a + * special type of DOM object because other objects (such as Elements, + * DocumentFragments, etc.) can only exist within the context of a Document + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult CreateDocument(nsString &type, nsIDOMDocument** aDocument) = 0; + + /** + * Returns TRUE if the current DOM implements a given feature, FALSE otherwise + * + * @param aFeature [in] The package name of the feature to test + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult HasFeature(nsString &aFeature) = 0; }; diff --git a/dom/public/coreDom/nsIDOMAttribute.h b/dom/public/coreDom/nsIDOMAttribute.h index 11c6a9038a93..cd97f20ea72a 100644 --- a/dom/public/coreDom/nsIDOMAttribute.h +++ b/dom/public/coreDom/nsIDOMAttribute.h @@ -30,15 +30,70 @@ class nsIDOMNode; 0x8f6bca77, 0xce42, 0x11d1, \ {0xb7, 0x24, 0x00, 0x60, 0x08, 0x91, 0xd8, 0xc9} } +/** + * The Attribute object represents an attribute in an Element object. Typically the + * allowable values for the attribute are defined in a document type definition. + *

+ * The attribute's effective value is determined as follows: if this attribute has + * been explicitly assigned any value, that value is the attribute's effective value; + * otherwise, if there is a declaration for this attribute, and that declaration + * includes a default value, then that default value is the attribute's effective value; + * otherwise, the attribute has no effective value.) Note, in particular, that an + * effective value of the null string would be returned as a Text node instance whose + * toString method will return a zero length string (as will toString invoked directly + * on this Attribute instance). If the attribute has no effective value, then this + * method will return null. Note the toString method on the Attribute instance can + * also be used to retrieve the string version of the attribute's value(s). + */ class nsIDOMAttribute : public nsISupports { public: + /** + * Return the name of this attribute. + * + * @param aName [out] The attribute name + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetName(nsString &aName) = 0; - //attribute Node value; - virtual nsresult GetValue(nsString &aName /*nsIDOMNode **aValue*/) = 0; - virtual nsresult SetValue(nsString &aName /*nsIDOMNode *aValue*/) = 0; - //attribute boolean specified; + + /** + * Return the value of this attribute. + * + * @param aName [out] The attribute value + * @return NS_OK iff the function succeeds, otherwise an error code + */ + virtual nsresult GetValue(nsString &aName) = 0; + + /** + * Set the value of this attribute. + * + * @param aName [in] The attribute value + * @return NS_OK iff the function succeeds, otherwise an error code + */ + virtual nsresult SetValue(nsString &aName) = 0; + + /** + * If this attribute was explicitly given a value in the original document, + * this will be true; otherwise, it will be false. + * + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetSpecified() = 0; + + /** + * Set the specified value + * + * @param specified [in] The specified value + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult SetSpecified(PRBool specified) = 0; + + /** + * Returns the attribute as a string. Character and general entity + * references will have been replaced with their values in the returned string. + * + * @param aString [out] The attribute as a string + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult ToString(nsString &aString) = 0; }; @@ -47,12 +102,60 @@ public: 0x8f6bca78, 0xce42, 0x11d1, \ {0xb7, 0x24, 0x00, 0x60, 0x08, 0x91, 0xd8, 0xc9} } +/** + * AttributeList objects are used to represent collections of Attribute objects + * which can be accessed by name. The Attribute objects contained in a AttributeList + * may also be accessed by ordinal index. In most cases, AttributeList objects are + * created from Element objects. + */ class nsIDOMAttributeList : public nsISupports { public: + /** + * Retrieve an Attribute instance from the list by its name. If it's not present, + * null is returned. + * + * @param aAttrName [in] The name of atrribute + * @param aAttribute [out] The returned attribute + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetAttribute(nsString &aAttrName, nsIDOMAttribute** aAttribute) = 0; + + /** + * Add a new attribute to the end of the list and associate it with the given name. + * If the name already exists, the previous Attribute object is replaced, and returned. + * If no object of the same name exists, null is returned, and the named Attribute + * is added to the end of the AttributeList object; that is, it is accessible via + * the item method using the index one less than the value returned by getLength. + * + * @param aAttribute [in] The attribute to set + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult SetAttribute(nsIDOMAttribute *attr) = 0; + + /** + * Removes the Attribute instance named name from the list and returns it. + * + * @param aAttrName [in] The name of atrribute + * @param aAttribute [out] The removed attribute + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult Remove(nsString &attrName, nsIDOMAttribute** aAttribute) = 0; + + /** + * Returns the (zero-based) indexth Attribute item in the collection. + * + * @param aIndex [in] The index in the list of attributes + * @param aAttribute [out] The attribute at that index + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult Item(PRUint32 aIndex, nsIDOMAttribute** aAttribute) = 0; + + /** + * Returns the number of Attributes in the AttributeList instance. + * + * @param aLength [out] The attribute list length + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetLength(PRUint32 *aLength) = 0; }; diff --git a/dom/public/coreDom/nsIDOMDocument.h b/dom/public/coreDom/nsIDOMDocument.h index dbe467dafa9e..26257ecece72 100644 --- a/dom/public/coreDom/nsIDOMDocument.h +++ b/dom/public/coreDom/nsIDOMDocument.h @@ -39,10 +39,27 @@ class nsIDOMTreeIterator; 0x8f6bca71, 0xce42, 0x11d1, \ {0xb7, 0x24, 0x00, 0x60, 0x08, 0x91, 0xd8, 0xc9} } +/** + * The DocumentContext object represents information that is not strictly related + * to a document's content; rather, it provides the information about where the + * document came from, and any additional meta-data about the document + */ class nsIDOMDocumentContext : public nsISupports { public: - //attribute Document document; + /** + * Return the root node of a Document Object Model. + * + * @param aDocument [out] The root node of a Document Object Model + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetDocument(nsIDOMDocument **aDocument) = 0; + + /** + * Set the root node of a Document Object Model. + * + * @param aDocument [in] The root node of a Document Object Model + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult SetDocument(nsIDOMDocument *aDocument) = 0; }; @@ -51,10 +68,27 @@ public: 0x8f6bca72, 0xce42, 0x11d1, \ {0xb7, 0x24, 0x00, 0x60, 0x08, 0x91, 0xd8, 0xc9} } +/** + * DocumentFragment is the "lightweight" or "minimal" document object, or the + * handle for a "fragment" as returned by the Range operations, and it + * (as the superclass of Document) anchors the XML/HTML tree in a full-fledged document + */ class nsIDOMDocumentFragment : public nsIDOMNode { public: - //attribute Document masterDoc; + /** + * Return the Document object associated with this DocumentFragment + * + * @param aDocument [out] The main Document + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetMasterDoc(nsIDOMDocument **aDocument) = 0; + + /** + * Set the Document object associated with this DocumentFragment + * + * @param aDocument [in] The main Document + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult SetMasterDoc(nsIDOMDocument *aDocument) = 0; }; @@ -63,33 +97,159 @@ public: 0x8f6bca73, 0xce42, 0x11d1, \ {0xb7, 0x24, 0x00, 0x60, 0x08, 0x91, 0xd8, 0xc9} } +/** + * The Document object 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 Document inherits from DocumentFragment, its children are + * contents of the Document, e.g., the root Element, the XML prolog, any processing + * instructions and or comments, etc. + *

Since Elements, Text nodes, Comments, PIs, etc. cannot exist outside a Document, + * the Document interface also anchors the "factory" methods that create these objects. + */ class nsIDOMDocument : public nsIDOMDocumentFragment { public: - //attribute Node documentType; + /** + * For XML, this provides access to the Document Type Definition (see DocumentType) + * associated with this XML document. For HTML documents and XML documents without + * a document type definition this returns the value null. + * + * @param aDocType [out] The document type + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetDocumentType(nsIDOMNode **aDocType) = 0; + + /** + * For XML, this sets the Document Type Definition (see DocumentType) + * associated with this XML document. For HTML documents and XML documents without + * a document type definition this is a noop. + * + * @param aDocType [in] The document type + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult SetDocumentType(nsIDOMNode *aNode) = 0; - //attribute Element documentElement; + /** + * This is a "convenience" function to jump directly to the child node + * that is the root element of the document + * + * @param aElement [out] The root element + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetDocumentElement(nsIDOMElement **aElement) = 0; + + /** + * This is a "convenience" function to set the child node + * that is the root element of the document + * + * @param aElement [out] The root element + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult SetDocumentElement(nsIDOMElement *aElement) = 0; - //attribute DocumentContext contextInfo; + /** + * Return the DocumentContext + * + * @param aContext [out] The DocumentContext + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetDocumentContext(nsIDOMDocumentContext **aDocContext) = 0; + + /** + * Set the DocumentContext + * + * @param aContext [in] The DocumentContext + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult SetDocumentContext(nsIDOMDocumentContext *aContext) = 0; + /** + * Create and return a new DocumentContext. + * + * @param aDocContext [out] The new context + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult CreateDocumentContext(nsIDOMDocumentContext **aDocContext) = 0; + + /** + * Create an element based on the tagName. Note that the instance returned may + * implement an interface derived from Element. The attributes parameter can be + * null if no attributes are specified for the new Element + * + * @param aTagName [in] The name of the element type to instantiate + * @param aAttributes [in] The set of attributes for the element + * @param aElement [out] The new element + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult CreateElement(nsString &aTagName, nsIDOMAttributeList *aAttributes, nsIDOMElement **aElement) = 0; + + /** + * Create and return a new Text node. + * + * @param aData [in] The data for the node + * @param aTextNode [out] The new text node + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult CreateTextNode(nsString &aData, nsIDOMText** aTextNode) = 0; + + /** + * Create a Comment node given the specified string + * + * @param aData [in] The data for the node + * @param aComment [out] The new Comment object. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult CreateComment(nsString &aData, nsIDOMComment **aComment) = 0; + + /** + * Create a PI node given the specified name and data strings. + * + * @param aName [in] The name part of the PI. + * @param aData [in] The data for the node. + * @param aPI [out] The new PI object + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult CreatePI(nsString &aName, nsString &aData, nsIDOMPI **aPI) = 0; + + /** + * Create an Attribute of the given name and specified value. Note that the + * Attribute instance can then be set on an Element using the setAttribute method + * + * @param aName [in] The name of the attribute + * @param value [in] The value of the attribute. + * @param aAttribute [out] A new Attribute object. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult CreateAttribute(nsString &aName, nsIDOMNode *value, nsIDOMAttribute **aAttribute) = 0; + + /** + * Create an empty AttributeList + * + * @param aAttributesList [out] The new AttributeList + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult CreateAttributeList(nsIDOMAttributeList **aAttributesList) = 0; + + /** + * Create a TreeIterator anchored on a given node. + * + * @param aNode [in] The "root" node of this tree iterator. + * @param aTreeIterator [out] A new TreeIterator object. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult CreateTreeIterator(nsIDOMNode **aNode, nsIDOMTreeIterator **aTreeIterator) = 0; - virtual nsresult GetElementsByTagName(nsIDOMNodeIterator **aIterator) = 0; + + /** + * Returns an iterator through all subordinate Elements with a given tag name. + * + * @param aTagname [in] The name of the tag to match on + * @param aIterator [out] A new NodeIterator object. + * @return NS_OK iff the function succeeds, otherwise an error code + */ + virtual nsresult GetElementsByTagName(nsString &aTagname, nsIDOMNodeIterator **aIterator) = 0; }; #endif // nsIDOMDocument_h__ diff --git a/dom/public/coreDom/nsIDOMElement.h b/dom/public/coreDom/nsIDOMElement.h index e18e13f19402..7d02ea7dc906 100644 --- a/dom/public/coreDom/nsIDOMElement.h +++ b/dom/public/coreDom/nsIDOMElement.h @@ -32,17 +32,100 @@ class nsIDOMNodeIterator; 0x8f6bca79, 0xce42, 0x11d1, \ {0xb7, 0x24, 0x00, 0x60, 0x08, 0x91, 0xd8, 0xc9} } +/** + * By far the vast majority (apart from text) of node types that authors will generally + * encounter when traversing a document will be Element nodes. These objects represent + * both the element itself, as well as any contained nodes. + */ class nsIDOMElement : public nsIDOMNode { public: + /** + * This method returns the string that is the element's name + * + * @param newChild [out] The tag name + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetTagName(nsString &aName) = 0; + + /** + * The attributes for this element. + * + * @param aAttributeList [out] The AttributeList + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetAttributes(nsIDOMAttributeList **aAttributeList) = 0; + + /** + * Retrieves an attribute value by name from an Element object. + * NOTE: the name of this function will change to GetAttribute in a subsequent + * release + * + * @param aName [in] The attribute name + * @param aValue [out] The attribute value as a string + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetDOMAttribute(nsString &aName, nsString &aValue) = 0; + + /** + * Set an attribute value from an Element object. + * NOTE: the name of this function will change to SetAttribute in a subsequent + * release + * + * @param aName [in] The attribute name + * @param aValue [in] The attribute value as a string + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult SetDOMAttribute(nsString &aName, nsString &aValue) = 0; + + /** + * Remove the specified attribute + * + * @param aName [in] The attribute name + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult RemoveAttribute(nsString &aName) = 0; + + /** + * Retrieves an Attribute node by name from an Element object. + * + * @param aName [in] The name of the attribute to retrieve + * @param aAttribute [out] The attribute with the given name + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetAttributeNode(nsString &aName, nsIDOMAttribute **aAttribute) = 0; + + /** + * Set an Attribute node by name from an Element object. + * + * @param aAttribute [in] The attribute to set + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult SetAttributeNode(nsIDOMAttribute *aAttribute) = 0; + + /** + * Removes the specified attribute/value pair from an Element node object. + * + * @param aAttribute [in] The attribute to remove + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult RemoveAttributeNode(nsIDOMAttribute *aAttribute) = 0; + + /** + * Returns an iterator through all subordinate elements with a given tag name. + * + * @param aName [in] The name of the tag to match on + * @param aIterator [out] The iterator + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetElementsByTagName(nsString &aName,nsIDOMNodeIterator **aIterator) = 0; + + /** + * Puts all Tet nodes in the sub-tree underneath this Element into a "normal" + * form where only markup (e.g., tags, comments, PIs, CDATASections, and and + * entity references separates Text nodes. + * + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult Normalize() = 0; }; diff --git a/dom/public/coreDom/nsIDOMIterators.h b/dom/public/coreDom/nsIDOMIterators.h index 5132a5360baf..1313fc303cd2 100644 --- a/dom/public/coreDom/nsIDOMIterators.h +++ b/dom/public/coreDom/nsIDOMIterators.h @@ -30,15 +30,96 @@ class nsIDOMNode; 0x8f6bca75, 0xce42, 0x11d1, \ {0xb7, 0x24, 0x00, 0x60, 0x08, 0x91, 0xd8, 0xc9} } +/** + * A NodeIterator is a very simple iterator class that can be used to provide + * a simple linear view of the document heirarchy. + */ class nsIDOMNodeIterator : public nsISupports { public: + /** + * This method set or unsets some iterator state that controls the + * filter to apply when traversing the document tree. + * + * @param aFilter [in] An integer that uniquely indicates what the filter + * operation will be operating against. + * @param aFilterOn [in] When true, this flag states that the specified item is + * to be filtered, otherwise, it will not be + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult SetFilter(PRInt32 aFilter, PRBool aFilterOn) = 0; + + /** + * This method returns the number of items that will be iterated over if the + * iterator is started at the beginning, and getNextNode() is called repeatedly + * until the end of the sequence is encountered. + * + * @param aLength [out] This method will always return the correct number of items + * in a single threaded environment, but may return misleading + * results in multithreaded, multiuser situations. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetLength(PRUint32 *aLength) = 0; + + /** + * This method returns the Node over which the iterator currentl rests. + * + * @param aNode [out] This method will return the Node at the current position in the interation. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetCurrentNode(nsIDOMNode **aNode) = 0; + + /** + * This method alters the internal state of the iterator such that the node it + * references is the next in the sequence the iterator is presenting relative + * to the current position. When filtering, this will skip any items being filtered. + * + * @param aNode [out] This method returns the node that has been traversed to, + * or null when it is not possible to iterate any further. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetNextNode(nsIDOMNode **aNode) = 0; + + /** + * This method alters the internal state of the iterator such that the node it + * references is the previous node in the sequence the iterator is presenting relative + * to the current position. When filtering, this will skip any items being filtered. + * + * @param aNode [out] This method returns the node that has been traversed to, or + * null when it is not possible to iterate any further. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetPreviousNode(nsIDOMNode **aNode) = 0; + + /** + * This method alters the internal state of the iterator such that the node it + * references is the first node in the sequence the iterator is presenting relative + * to the current position. When filtering, this will skip any items being filtered. + * + * @param aNode [out] This method will only return null when there are no items to iterate over. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult ToFirst(nsIDOMNode **aNode) = 0; + + /** + * This method alters the internal state of the iterator such that the node it + * references is the last node in the sequence the iterator is presenting relative + * to the current position. When filtering, this will skip any items being filtered. + * + * @param aNode [out] This method will only return null when there are no items to iterate over. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult ToLast(nsIDOMNode **aNode) = 0; + + /** + * This method alters the internal state of the iterator such that the node it + * references is the Nth node in the sequence the iterator is presenting relative + * to the current position. When filtering, this will skip any items being filtered. + * + * @param aNth [in] The position to move to + * @param aNode [out] This method will return null when position specified is out + * of the range of legal values. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult MoveTo(int aNth, nsIDOMNode **aNode) = 0; }; diff --git a/dom/public/coreDom/nsIDOMNode.h b/dom/public/coreDom/nsIDOMNode.h index 41690734225d..ec5137010516 100644 --- a/dom/public/coreDom/nsIDOMNode.h +++ b/dom/public/coreDom/nsIDOMNode.h @@ -30,6 +30,11 @@ class nsIDOMNodeIterator; 0x8f6bca74, 0xce42, 0x11d1, \ {0xb7, 0x24, 0x00, 0x60, 0x08, 0x91, 0xd8, 0xc9} } +/** + * The Node object is the primary datatype for the entire Document Object Model. + * It represents a single node in the document tree. Nodes may have, but are + * not required to have, an arbitrary number of child nodes. + */ class nsIDOMNode : public nsISupports { public: // NodeType @@ -42,15 +47,98 @@ public: TEXT = 6 }; + /** + * Returns an indication of the underlying Node object's type. + * + * @param aType [out] The type of the node. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetNodeType(PRInt32 *aType) = 0; + + /** + * Returns the parent of the given Node instance. If this node is the root of the + * document object tree, or if the node has not been added to a document tree, + * null is returned. + * + * @param aNode [out] The parent of the node. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetParentNode(nsIDOMNode **aNode) = 0; + + /** + * Returns a NodeIterator object that will enumerate all children of this node. + * If there are no children, an iterator that will return no nodes is returned. + * The content of the returned NodeIterator is "live" in the sense that changes to the + * children of the Node object that it was created from will be immediately reflected + * in the nodes returned by the iterator; it is not a static snapshot of the content + * of the Node. Similarly, changes made to the nodes returned by the iterator will + * be immediately reflected in the tree, including the set of children of the Node + * that the NodeIterator was created from. + * + * @param aIterator [out] An iterator through the children of the node. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetChildNodes(nsIDOMNodeIterator **aIterator) = 0; + + /** + * Returns true if the node has any children, false if the node has no children at all. + * + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult HasChildNodes() = 0; + + /** + * Returns the first child of a node. If there is no such node, null is returned. + * + * @param aNode [out] The first child of the node, or null. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetFirstChild(nsIDOMNode **aNode) = 0; + + /** + * Returns the node immediately preceding the current node in a breadth-first + * traversal of the tree. If there is no such node, null is returned. + * + * @param aNode [out] The the node immediately preceeding, or null. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetPreviousSibling(nsIDOMNode **aNode) = 0; + + /** + * Returns the node immediately following the current node in a breadth-first + * traversal of the tree. If there is no such node, null is returned. + * + * @param aNode [out] The node immediately following, or null. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetNextSibling(nsIDOMNode **aNode) = 0; + + /** + * Inserts a child node (newChildbefore the existing child node refChild. + * If refChild is null, insert newChild at the end of the list of children. + * + * @param newChild [in] The node to be inserted + * @param refChild [in] The node before which the new node will be inserted + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult InsertBefore(nsIDOMNode *newChild, nsIDOMNode *refChild) = 0; + + /** + * Replaces the child node oldChild with newChild in the set of children of the + * given node, and return the oldChild node. + * + * @param newChild [in] The node to be inserted + * @param oldChild [in] The node to be replaced + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult ReplaceChild(nsIDOMNode *newChild, nsIDOMNode *oldChild) = 0; + + /** + * Removes the child node indicated by oldChild from the list of children and returns it. + * + * @param oldChild [in] The node to be deleted + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult RemoveChild(nsIDOMNode *oldChild) = 0; }; diff --git a/dom/public/coreDom/nsIDOMText.h b/dom/public/coreDom/nsIDOMText.h index 5030ab2760f2..887589599251 100644 --- a/dom/public/coreDom/nsIDOMText.h +++ b/dom/public/coreDom/nsIDOMText.h @@ -30,15 +30,85 @@ class nsIDOMElement; 0x8f6bca7b, 0xce42, 0x11d1, \ {0xb7, 0x24, 0x00, 0x60, 0x08, 0x91, 0xd8, 0xc9} } +/** + * The Text object contains the non-markup content of an Element. If there is no + * markup inside an Element's content, the text will be contained in a single + * Text object that is the child of the Element. Any markup will parse into + * child elements that are siblings of the Text nodes on either side of it, and + * whose content will be represented as Text node children of the markup element. + */ class nsIDOMText : public nsIDOMNode { public: - //attribute UniString data; + /** + * Return the actual content of the text node. Text nodes contain just plain text, + * without markup and without entities, both of which are represented as separate + * objects in the DOM. + * + * @param aString [out] The text data + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult GetData(nsString &aString) = 0; + + /** + * Set the actual content of the text node. Text nodes contain just plain text, + * without markup and without entities, both of which are represented as separate + * objects in the DOM. + * + * @param aString [in] The text data + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult SetData(nsString &aString) = 0; + + /** + * Append the string to the end of the character data in this Text node + * + * @param aData [in] The data to append + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult Append(nsString &aData) = 0; + + /** + * Insert the string at the specified character offset. + * + * @param offset [in] The offset + * @param aData [in] The data to insert + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult Insert(int offset, nsString &aData) = 0; + + /** + * Delete the specified characters range + * + * @param offset [in] The offset where deletion starts + * @param count [out] The number of chracters to delete + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult Delete(int offset, int count) = 0; + + /** + * Replace the characters starting at the specified character offset with + * the specified string. + * + * @param offset [in] Offset at which to start replacing + * @param count [in] Number of characters to replace + * @param aData [in] String to replace previous content with. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult Replace(int offset, int count, nsString &aData) = 0; + + /** + * Insert the specified element in the tree as a sibling of the Text node. + * The result of this operation may be the creation of up to 2 new Text nodes: + * the character data specified by the offset and count will form one Text node + * that will become the child of the inserted element and the remainder of + * the character data (after the offset and count) will form another Text node + * become a sibling of the original Text node. + * + * @param element [in] Element to insert into the tree. + * @param offset [in] Offset at which to insert. + * @param count [in] Number of characters to copy to child Text node of element. + * @return NS_OK iff the function succeeds, otherwise an error code + */ virtual nsresult Splice(nsIDOMElement *element, int offset, int count) = 0; }; diff --git a/dom/public/nsIScriptContext.h b/dom/public/nsIScriptContext.h index 6a5e00d16b02..ebface5eb774 100644 --- a/dom/public/nsIScriptContext.h +++ b/dom/public/nsIScriptContext.h @@ -23,10 +23,6 @@ #include "nsISupports.h" #include "jsapi.h" -// -// This dependency will disappear soon. A more general "global object" -// interface will be defined. nsIWebWidget is too specific -// class nsIWebWidget; #define NS_ISCRIPTCONTEXT_IID \ @@ -34,19 +30,65 @@ class nsIWebWidget; 0x8f6bca7d, 0xce42, 0x11d1, \ {0xb7, 0x24, 0x00, 0x60, 0x08, 0x91, 0xd8, 0xc9} } +/** + * It is used by the application to initialize a runtime and run scripts. + * A script runtime would implement this interface. + *

It does have a bit too much java script information now, that + * should be removed in a short time. Ideally this interface will be + * language neutral + */ class nsIScriptContext : public nsISupports { public: + /** + * Execute a script. + * + * @param aScript a string representing the script to be executed + * @param aScriptSize the length of aScript + * @param aRetValue return value + * + * @return true if the script was valid and got executed + * + **/ virtual PRBool EvaluateString(const char *aScript, PRUint32 aScriptSize, jsval *aRetValue) = 0; + + /** + * Return the global object. + * + **/ virtual JSObject* GetGlobalObject() = 0; + + /** + * Return the JSContext + * + **/ virtual JSContext* GetContext() = 0; + + /** + * Init all DOM classes. + * + **/ virtual nsresult InitAllClasses() = 0; - // This dependency (nsIWebWidget) will disappear soon. A more general "global object" - // interface will be defined. nsIWebWidget is too specific + + /** + * Init this context. + *

+ * The dependency with nsIWebWidget will disappear soon. A more general "global object" + * interface should be defined. nsIWebWidget is too specific. + * + * @param aGlobalObject the gobal object + * + * @return NS_OK if context initialization was successful + * + **/ virtual nsresult InitContext(nsIWebWidget *aGlobalObject) = 0; }; +/** + * Return a new Context + * + */ extern "C" NS_DOM NS_CreateContext(nsIWebWidget *aGlobal, nsIScriptContext **aContext); #endif // nsIScriptContext_h__ diff --git a/dom/public/nsIScriptObject.h b/dom/public/nsIScriptObject.h index f7724bc76a0a..a74b6ffc4b37 100644 --- a/dom/public/nsIScriptObject.h +++ b/dom/public/nsIScriptObject.h @@ -27,19 +27,24 @@ 0x8f6bca7c, 0xce42, 0x11d1, \ {0xb7, 0x24, 0x00, 0x60, 0x08, 0x91, 0xd8, 0xc9} } -// -// The interface a js object can implement -// +/** + * A java script specific interface. + *

+ * It's implemented by an object that has to execute specific java script + * behavior like the array semantic. + *

+ * It is used by the script runtime to collect information about an object + */ class nsIScriptObject : public nsISupports { public: - virtual PRBool AddProperty(JSContext *aContext, jsval aID, jsval *aVp) = 0; - virtual PRBool DeleteProperty(JSContext *aContext, jsval aID, jsval *aVp) = 0; - virtual PRBool GetProperty(JSContext *aContext, jsval aID, jsval *aVp) = 0; - virtual PRBool SetProperty(JSContext *aContext, jsval aID, jsval *aVp) = 0; - virtual PRBool EnumerateProperty(JSContext *aContext) = 0; - virtual PRBool Resolve(JSContext *aContext, jsval aID) = 0; - virtual PRBool Convert(JSContext *aContext, jsval aID) = 0; - virtual void Finalize(JSContext *aContext) = 0; + virtual PRBool AddProperty(JSContext *aContext, jsval aID, jsval *aVp) = 0; + virtual PRBool DeleteProperty(JSContext *aContext, jsval aID, jsval *aVp) = 0; + virtual PRBool GetProperty(JSContext *aContext, jsval aID, jsval *aVp) = 0; + virtual PRBool SetProperty(JSContext *aContext, jsval aID, jsval *aVp) = 0; + virtual PRBool EnumerateProperty(JSContext *aContext) = 0; + virtual PRBool Resolve(JSContext *aContext, jsval aID) = 0; + virtual PRBool Convert(JSContext *aContext, jsval aID) = 0; + virtual void Finalize(JSContext *aContext) = 0; }; #endif // nsIScriptObject_h__ diff --git a/dom/public/nsIScriptObjectOwner.h b/dom/public/nsIScriptObjectOwner.h index dd4b7d48b0d2..5cc1b20373db 100644 --- a/dom/public/nsIScriptObjectOwner.h +++ b/dom/public/nsIScriptObjectOwner.h @@ -32,12 +32,35 @@ class nsIScriptContext; 0x8f6bca7e, 0xce42, 0x11d1, \ {0xb7, 0x24, 0x00, 0x60, 0x08, 0x91, 0xd8, 0xc9} } \ -// -// The interface a content object has to implement -// +/** + * Creates a link between the script object and its native implementation + *

+ * Every object that wants to be exposed in a script environment should + * implement this interface. This interface should guarantee that the same + * script object is returned in the context of the same script. + *

It does have a bit too much java script information now, that + * should be removed in a short time. Ideally this interface will be + * language neutral + */ class nsIScriptObjectOwner : public nsISupports { public: + /** + * Return the script object associated with this object. + * Create a script object if not present. + * + * @param aContext the context the script object has to be created in + * @param aScriptObject on return will contain the script object + * + * @return nsresult NS_OK if the script object is successfully returned + * + **/ virtual nsresult GetScriptObject(JSContext *aContext, void** aScriptObject) = 0; + + /** + * Nuke the current script object. + * Next call to GetScriptObject creates a new script object. + * + **/ virtual nsresult ResetScriptObject() = 0; }; diff --git a/dom/tests/js/DumpHTML.js b/dom/tests/js/DumpHTML.js index 366aacab1896..7f8276e33da2 100644 --- a/dom/tests/js/DumpHTML.js +++ b/dom/tests/js/DumpHTML.js @@ -1,4 +1,4 @@ -/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- +/* -*- Mode: js; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- * * The contents of this file are subject to the Netscape Public License * Version 1.0 (the "NPL"); you may not use this file except in diff --git a/dom/tests/js/DumpTree.js b/dom/tests/js/DumpTree.js index acfdc9840005..cd2d5bb3426a 100644 --- a/dom/tests/js/DumpTree.js +++ b/dom/tests/js/DumpTree.js @@ -1,4 +1,4 @@ -/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- +/* -*- Mode: js; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- * * The contents of this file are subject to the Netscape Public License * Version 1.0 (the "NPL"); you may not use this file except in diff --git a/dom/tests/js/HTMLString.js b/dom/tests/js/HTMLString.js index 8527371fb8efeb52d66813fc3b9b3eeeb9666b63..949e1de42668ec47cb7258fcf557441a4ef8f594 100644 GIT binary patch delta 26 hcmca7cvp~LUrRw(OIN`+KPA;lA**