Source: dom/dom_element.h

# Source: dom/dom_element.h |
Annotated List
Files
Globals
Hierarchy
Index

    /*
     * This file is part of the DOM implementation for KDE.
     *
     * (C) 1999 Lars Knoll (knoll@kde.org)
     *
     * This library is free software; you can redistribute it and/or
     * modify it under the terms of the GNU Library General Public
     * License as published by the Free Software Foundation; either
     * version 2 of the License, or (at your option) any later version.
     *
     * This library is distributed in the hope that it will be useful,
     * but WITHOUT ANY WARRANTY; without even the implied warranty of
     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     * Library General Public License for more details.
     *
     * You should have received a copy of the GNU Library General Public License
     * along with this library; see the file COPYING.LIB.  If not, write to
     * the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
     * Boston, MA 02111-1307, USA.
     *
     * This file includes excerpts from the Document Object Model (DOM)
     * Level 1 Specification (Recommendation)
     * http://www.w3.org/TR/REC-DOM-Level-1/
     * Copyright © World Wide Web Consortium , (Massachusetts Institute of
     * Technology , Institut National de Recherche en Informatique et en
     * Automatique , Keio University ). All Rights Reserved.
     *
     * $Id: dom_element.h,v 1.26.2.1 2003/05/18 12:34:37 mueller Exp $
     */
    #ifndef _DOM_ELEMENT_h_
    #define _DOM_ELEMENT_h_

    #include
    #include

    namespace DOM {

    class DOMString;
    class AttrImpl;
    class Element;
    class ElementImpl;
    class NamedAttrMapImpl;
    class DocumentImpl;

    /**
     * The  Attr  interface represents an attribute in an
     *  Element  object. Typically the allowable values for
     * the attribute are defined in a document type definition.
     *
     *   Attr  objects inherit the  Node
     * interface, but since they are not actually child nodes of the
     * element they describe, the DOM does not consider them part of the
     * document tree. Thus, the  Node  attributes
     * parentNode  ,  previousSibling  , and
     * nextSibling  have a null value for  Attr
     * objects. The DOM takes the view that attributes are properties of
     * elements rather than having a separate identity from the elements
     * they are associated with; this should make it more efficient to
     * implement such features as default attributes associated with all
     * elements of a given type. Furthermore,  Attr  nodes
     * may not be immediate children of a  DocumentFragment
     * . However, they can be associated with  Element  nodes
     * contained within a  DocumentFragment  . In short,
     * users and implementors of the DOM need to be aware that  Attr
     *  nodes have some things in common with other objects
     * inheriting the  Node  interface, but they also are
     * quite distinct.
     *
     *  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 does not exist on this element in the
     * structure model until it has been explicitly added. Note that the
     *  nodeValue  attribute on the  Attr
     * instance can also be used to retrieve the string version of the
     * attribute's value(s).
     *
     *  In XML, where the value of an attribute can contain entity
     * references, the child nodes of the  Attr  node provide
     * a representation in which entity references are not expanded. These
     * child nodes may be either  Text  or
     * EntityReference  nodes. Because the attribute type may be
     * unknown, there are no tokenized attribute values.
     *
     */
    class Attr : public Node
    {
        friend class Element;
        friend class Document;
        friend class DocumentImpl;
        friend class HTMLDocument;
        friend class ElementImpl;
        friend class NamedAttrMapImpl;

    public:
        Attr();
        Attr(const Node &other) : Node()
            {(*this)=other;}
        Attr(const Attr &other);

        Attr & operator = (const Node &other);
        Attr & operator = (const Attr &other);

        ~Attr();

        /**
         * Returns the name of this attribute.
         *
         */
        DOMString name() const;

        /**
         * If this attribute was explicitly given a value in the original
         * document, this is  true  ; otherwise, it is
         * false  . Note that the implementation is in charge of
         * this attribute, not the user. If the user changes the value of
         * the attribute (even if it ends up having the same value as the
         * default value) then the  specified  flag is
         * automatically flipped to  true  . To re-specify
         * the attribute as the default value from the DTD, the user must
         * delete the attribute. The implementation will then make a new
         * attribute available with  specified  set to
         * false  and the default value (if one exists).
         *
         *  In summary:   If the attribute has an assigned
         * value in the document then  specified  is
         * true  , and the value is the assigned value.
         *
         *    If the attribute has no assigned value in the
         * document and has a default value in the DTD, then
         * specified  is  false  , and the value is
         * the default value in the DTD.
         *
         *    If the attribute has no assigned value in the
         * document and has a value of #IMPLIED in the DTD, then the
         * attribute does not appear in the structure model of the
         * document.
         *
         *
         *
         */
        bool specified() const;

        /**
         * On retrieval, the value of the attribute is returned as a
         * string. Character and general entity references are replaced
         * with their values.
         *
         *  On setting, this creates a  Text  node with the
         * unparsed contents of the string.
         *
         */
        DOMString value() const;

        /**
         * see @ref value
         */
        void setValue( const DOMString & );

        /**
         * Introduced in DOM Level 2
         *
         * The Element node this attribute is attached to or null if this attribute
         * is not in use.
         */
        Element ownerElement() const;

    protected:

        Attr( AttrImpl *_impl );
    };

    class NodeList;
    class Attr;
    class DOMString;

    /**
     * By far the vast majority of objects (apart from text) that authors
     * encounter when traversing a document are  Element
     * nodes. Assume the following XML document: <elementExample
     * id="demo"> <subelement1/>
     * <subelement2><subsubelement/></subelement2>
     * </elementExample>
     *
     *  When represented using DOM, the top node is an  Element
     *  node for "elementExample", which contains two
     * child  Element  nodes, one for "subelement1"
     * and one for "subelement2". "subelement1"
     * contains no child nodes.
     *
     *  Elements may have attributes associated with them; since the
     *  Element  interface inherits from  Node
     * , the generic  Node  interface method
     * getAttributes  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 : public Node
    {
        friend class Document;
        friend class HTMLDocument;
    //    friend class AttrImpl;
        friend class Attr;

    public:
        Element();
        Element(const Node &other) : Node()
            {(*this)=other;}
        Element(const Element &other);

        Element & operator = (const Node &other);
        Element & operator = (const Element &other);

        ~Element();

        /**
         * The name of the element. For example, in: <elementExample
         * id="demo"> ... </elementExample> ,
         * tagName  has the value  "elementExample"
         *  . Note that this is case-preserving in XML, as are all
         * of the operations of the DOM. The HTML DOM returns the
         * tagName  of an HTML element in the canonical uppercase
         * form, regardless of the case in the source HTML document.
         *
         */
        DOMString tagName() const;

        /**
         * Retrieves an attribute value by name.
         *
         * @param name The name of the attribute to retrieve.
         *
         * @return The  Attr  value as a string, or the empty
         * string if that attribute does not have a specified or default
         * value.
         *
         */
        DOMString getAttribute ( const DOMString &name );

        /**
         * 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.
         *
         * @param name The name of the attribute to create or alter.
         *
         * @param value Value to set in string form.
         *
         * @return
         *
         * @exception DOMException
         * INVALID_CHARACTER_ERR: Raised if the specified name contains an
         * invalid character.
         *
         *  NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
         *
         */
        void setAttribute ( const DOMString &name, const DOMString &value );

        /**
         * Removes an attribute by name. If the removed attribute has a
         * default value it is immediately replaced.
         *
         * @param name The name of the attribute to remove.
         *
         * @return
         *
         * @exception DOMException
         * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
         *
         */
        void removeAttribute ( const DOMString &name );

        /**
         * Retrieves an  Attr  node by name.
         *
         * @param name The name of the attribute to retrieve.
         *
         * @return The  Attr  node with the specified
         * attribute name or  null  if there is no such
         * attribute.
         *
         */
        Attr getAttributeNode ( const DOMString &name );

        /**
         * Adds a new attribute. If an attribute with that name is already
         * present in the element, it is replaced by the new one.
         *
         * @param newAttr The  Attr  node to add to the
         * attribute list.
         *
         * @return If the  newAttr  attribute replaces an
         * existing attribute with the same name, the previously existing
         *  Attr  node is returned, otherwise  null
         *  is returned.
         *
         * @exception DOMException
         * WRONG_DOCUMENT_ERR: Raised if  newAttr  was
         * created from a different document than the one that created the
         * element.
         *
         *  NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
         *
         *  INUSE_ATTRIBUTE_ERR: Raised if  newAttr  is
         * already an attribute of another  Element  object.
         * The DOM user must explicitly clone  Attr  nodes to
         * re-use them in other elements.
         *
         */
        Attr setAttributeNode ( const Attr &newAttr );

        /**
         * Removes the specified attribute.
         *
         * @param oldAttr The  Attr  node to remove from the
         * attribute list. If the removed  Attr  has a
         * default value it is immediately replaced.
         *
         * @return The  Attr  node that was removed.
         *
         * @exception DOMException
         * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
         *
         *  NOT_FOUND_ERR: Raised if  oldAttr  is not an
         * attribute of the element.
         *
         */
        Attr removeAttributeNode ( const Attr &oldAttr );

        /**
         * Returns a  NodeList  of all descendant elements
         * with a given tag name, in the order in which they would be
         * encountered in a preorder traversal of the  Element
         *  tree.
         *
         * @param name The name of the tag to match on. The special value
         * "*" matches all tags.
         *
         * @return A list of matching  Element  nodes.
         *
         */
        NodeList getElementsByTagName ( const DOMString &name );

        /**
         * Introduced in DOM Level 2
         * Returns a NodeList of all the descendant Elements with a given local
         * name and namespace URI in the order in which they are encountered in a
         * preorder traversal of this Element tree.
         *
         * @param namespaceURI The namespace URI of the elements to match on. The
         * special value "*" matches all namespaces.
         *
         * @param localName The local name of the elements to match on. The special
         * value "*" matches all local names.
         *
         * @return A new NodeList object containing all the matched Elements.
         */
        NodeList getElementsByTagNameNS ( const DOMString &namespaceURI,
                                          const DOMString &localName );

        /**
         * Introduced in DOM Level 2.
         *
         * No Exceptions.
         *
         * Retrieves an attribute value by local name and namespace URI. HTML-only
         * DOM implementations do not need to implement this method.
         *
         * @param namespaceURI The namespace URI of the attribute to retrieve.
         *
         * @param localName The local name of the attribute to retrieve.
         *
         * @return The Attr value as a string, or the empty string if that
         * attribute does not have a specified or default value.
         */
        DOMString getAttributeNS ( const DOMString &namespaceURI,
                                   const DOMString &localName );

        /**
         * Introduced in DOM Level 2
         *
         * 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.
         *
         * HTML-only DOM implementations do not need to implement this method.
         *
         * @param namespaceURI The namespace URI of the attribute to create or
         * alter.
         *
         * @param qualifiedName The qualified name of the attribute to create or
         * alter.
         *
         * @param value The value to set in string form.
         *
         * @exception DOMException
         * INVALID_CHARACTER_ERR: Raised if the specified qualified name contains
         * an illegal character.
         *
         * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
         *
         * NAMESPACE_ERR: Raised if the qualifiedName is malformed, if the
         * qualifiedName has a prefix and the namespaceURI is null, if the
         * qualifiedName has a prefix that is "xml" and the namespaceURI is
         * different from "http://www.w3.org/XML/1998/namespace", or if the
         * qualifiedName is "xmlns" and the namespaceURI is different from
         * "http://www.w3.org/2000/xmlns/".
         */
        void setAttributeNS ( const DOMString &namespaceURI,
                              const DOMString &qualifiedName,
                              const DOMString &value );

        /**
         * Introduced in DOM Level 2
         *
         * Removes an attribute by local name and namespace URI. If the removed
         * attribute has a default value it is immediately replaced. The replacing
         * attribute has the same namespace URI and local name, as well as the
         * original prefix.
         *
         * HTML-only DOM implementations do not need to implement this method.
         *
         * @param namespaceURI The namespace URI of the attribute to remove.
         *
         * @param localName The local name of the attribute to remove.
         *
         * @exception DOMException
         * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
         */
        void removeAttributeNS ( const DOMString &namespaceURI,
                                 const DOMString &localName );

        /**
         * Introduced in DOM Level 2
         *
         * Retrieves an Attr node by local name and namespace URI. HTML-only DOM
         * implementations do not need to implement this method.
         *
         * @param namespaceURI The namespace URI of the attribute to retrieve.
         *
         * @param localName The local name of the attribute to retrieve.
         *
         * @return The Attr node with the specified attribute local name and
         * namespace URI or null if there is no such attribute.
         */
        Attr getAttributeNodeNS ( const DOMString &namespaceURI,
                                  const DOMString &localName );

        /**
         * Introduced in DOM Level 2
         *
         * 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.
         *
         * HTML-only DOM implementations do not need to implement this method.
         *
         * @param newAttr The Attr node to add to the attribute list.
         *
         * @return If the newAttr attribute replaces an existing attribute with the
         * same local name and namespace URI, the replaced Attr node is returned,
         * otherwise null is returned.
         *
         * @exception DOMException
         * WRONG_DOCUMENT_ERR: Raised if newAttr was created from a different
         * document than the one that created the element.
         *
         * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
         *
         * INUSE_ATTRIBUTE_ERR: Raised if newAttr is already an attribute of
         * another Element object. The DOM user must explicitly clone Attr nodes to
         * re-use them in other elements.
         */
        Attr setAttributeNodeNS ( const Attr &newAttr );

        /**
         * Returns true when an attribute with a given name is specified on this
         * element or has a default value, false otherwise.
         * Introduced in DOM Level 2.
         *
         * @param name The name of the attribute to look for.
         *
         * @return true if an attribute with the given name is specified on this
         * element or has a default value, false otherwise.
         */
        bool hasAttribute( const DOMString& name );

        /**
         * Introduced in DOM Level 2
         *
         * 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.
         * HTML-only DOM implementations do not need to implement this method.
         *
         * @param namespaceURI The namespace URI of the attribute to look for.
         *
         * @param localName The local name of the attribute to look for.
         *
         * @return true if an attribute with the given local name and namespace URI
         * is specified or has a default value on this element, false otherwise.
         */
        bool hasAttributeNS ( const DOMString &namespaceURI,
                              const DOMString &localName );

        /**
         * Introduced in DOM Level 2
         * This method is from the CSSStyleDeclaration interface
         *
         * The style attribute
         */
        CSSStyleDeclaration style (  );

        /**
         * @internal
         * not part of the DOM
         */
        bool isHTMLElement() const;

        /**
         * KHTML extension to DOM
         * This method returns the associated form element.
         * returns null if this element is not a form-like element
         * or if this elment is not in the scope of a form element.
         */
        Element form() const;

        static bool khtmlValidAttrName(const DOMString &name);
        static bool khtmlValidPrefix(const DOMString &name);
        static bool khtmlValidQualifiedName(const DOMString &name);

        static bool khtmlMalformedQualifiedName(const DOMString &name);
        static bool khtmlMalformedPrefix(const DOMString &name);
    protected:
        Element(ElementImpl *_impl);
    };

    } //namespace
    #endif

Generated by: root on macppc.ports.openbsd.org on Sat Sep 6 10:37:43 2003, using kdoc 2.0a54.