.. wxPython Phoenix documentation This file was generated by Phoenix's sphinx generator and associated tools, do not edit by hand. Copyright: (c) 2011-2020 by Total Control Software License: wxWindows License .. include:: headings.inc .. _wx.xml.XmlNode: ========================================================================================================================================== |phoenix_title| **wx.xml.XmlNode** ========================================================================================================================================== Represents a node in an ``XML`` document. See :ref:`wx.xml.XmlDocument`. Each node is named and depending on the node type it may also hold content or be given attributes. The two most common node types are ``XML_ELEMENT_NODE`` and ``XML_TEXT_NODE`` . ``XML_ELEMENT_NODE`` represents a pair of ``XML`` element tags, whilst ``XML_TEXT_NODE`` represents the text value that can belong to the element. A ``XML_ELEMENT_NODE`` has a title, and optionally attributes, but does not have any content. A ``XML_TEXT_NODE`` does not have a title or attributes but should normally have content. For example: in the ``XML`` fragment ``hi`` there is an element node with the name ``title`` and a single text node child with the text ``hi`` as content. A ``XML_PI_NODE`` represents a Processing Instruction (``PI``) node with the name parameter set as the target and the contents parameter set as the instructions. Note that whilst the ``PI`` instructions are often in the form of pseudo-attributes, these do not use the node's attribute member. It is the user's responsibility to code and decode the ``PI`` instruction text. The ``XML_DOCUMENT_TYPE_NODE`` is not implemented at this time. Instead, you should get and set the ``DOCTYPE`` values using the :ref:`wx.xml.XmlDocument` class. If ``USE_UNICODE`` is 0, all strings are encoded in the encoding given to :meth:`wx.xml.XmlDocument.Load` (default is ``UTF-8``). .. note:: Once a :ref:`wx.xml.XmlNode` has been added to a :ref:`wx.xml.XmlDocument` it becomes owned by the document and this has two implications. Firstly, the :ref:`wx.xml.XmlDocument` takes responsibility for deleting the node so the user should not ``delete`` it; and secondly, a :ref:`wx.xml.XmlNode` must always be created on the heap and never on the stack. .. seealso:: :ref:`wx.xml.XmlDocument`, :ref:`wx.xml.XmlDoctype`, :ref:`wx.xml.XmlAttribute` | |class_hierarchy| Class Hierarchy ================================= .. raw:: html
Inheritance diagram for class XmlNode:
| |method_summary| Methods Summary ================================ ================================================================================ ================================================================================ :meth:`~wx.xml.XmlNode.__init__` Creates this ``XML`` node and inserts it into the ``XML`` tree as a child of the specified parent. :meth:`~wx.xml.XmlNode.AddAttribute` Appends an attribute with given `name` and `value` to the list of attributes for this node. :meth:`~wx.xml.XmlNode.AddChild` Adds node `child` as the last child of this node. :meth:`~wx.xml.XmlNode.DeleteAttribute` Removes the first attributes which has the given `name` from the list of attributes for this node. :meth:`~wx.xml.XmlNode.GetAttribute` Returns the value of the attribute named `attrName` if it does exist. :meth:`~wx.xml.XmlNode.GetAttributes` Return a pointer to the first attribute of this node. :meth:`~wx.xml.XmlNode.GetChildren` Returns the first child of this node. :meth:`~wx.xml.XmlNode.GetContent` Returns the content of this node. :meth:`~wx.xml.XmlNode.GetDepth` Returns the number of nodes which separate this node from ``grandparent`` . :meth:`~wx.xml.XmlNode.GetLineNumber` Returns line number of the node in the input ``XML`` file or ``-1`` if it is unknown. :meth:`~wx.xml.XmlNode.GetName` Returns the name of this node. :meth:`~wx.xml.XmlNode.GetNext` Returns a pointer to the sibling of this node or ``None`` if there are no siblings. :meth:`~wx.xml.XmlNode.GetNoConversion` Returns a flag indicating whether encoding conversion is necessary when saving. :meth:`~wx.xml.XmlNode.GetNodeContent` Returns the content of the first child node of type ``XML_TEXT_NODE`` or ``XML_CDATA_SECTION_NODE`` . :meth:`~wx.xml.XmlNode.GetParent` Returns a pointer to the parent of this node or ``None`` if this node has no parent. :meth:`~wx.xml.XmlNode.GetType` Returns the type of this node. :meth:`~wx.xml.XmlNode.HasAttribute` Returns ``True`` if this node has a attribute named `attrName`. :meth:`~wx.xml.XmlNode.InsertChild` Inserts the `child` node immediately before `followingNode` in the children list. :meth:`~wx.xml.XmlNode.InsertChildAfter` Inserts the `child` node immediately after `precedingNode` in the children list. :meth:`~wx.xml.XmlNode.IsWhitespaceOnly` Returns ``True`` if the content of this node is a string containing only whitespaces (spaces, tabs, new lines, etc). :meth:`~wx.xml.XmlNode.RemoveChild` Removes the given node from the children list. :meth:`~wx.xml.XmlNode.SetContent` Sets the content of this node. :meth:`~wx.xml.XmlNode.SetName` Sets the name of this node. :meth:`~wx.xml.XmlNode.SetNext` Sets as sibling the given node. :meth:`~wx.xml.XmlNode.SetNoConversion` Sets a flag to indicate whether encoding conversion is necessary when saving. :meth:`~wx.xml.XmlNode.SetParent` Sets as parent the given node. :meth:`~wx.xml.XmlNode.SetType` Sets the type of this node. ================================================================================ ================================================================================ | |property_summary| Properties Summary ===================================== ================================================================================ ================================================================================ :attr:`~wx.xml.XmlNode.Attributes` See :meth:`~wx.xml.XmlNode.GetAttributes` :attr:`~wx.xml.XmlNode.Children` See :meth:`~wx.xml.XmlNode.GetChildren` :attr:`~wx.xml.XmlNode.Content` See :meth:`~wx.xml.XmlNode.GetContent` and :meth:`~wx.xml.XmlNode.SetContent` :attr:`~wx.xml.XmlNode.Depth` See :meth:`~wx.xml.XmlNode.GetDepth` :attr:`~wx.xml.XmlNode.LineNumber` See :meth:`~wx.xml.XmlNode.GetLineNumber` :attr:`~wx.xml.XmlNode.Name` See :meth:`~wx.xml.XmlNode.GetName` and :meth:`~wx.xml.XmlNode.SetName` :attr:`~wx.xml.XmlNode.Next` See :meth:`~wx.xml.XmlNode.GetNext` and :meth:`~wx.xml.XmlNode.SetNext` :attr:`~wx.xml.XmlNode.NoConversion` See :meth:`~wx.xml.XmlNode.GetNoConversion` and :meth:`~wx.xml.XmlNode.SetNoConversion` :attr:`~wx.xml.XmlNode.NodeContent` See :meth:`~wx.xml.XmlNode.GetNodeContent` :attr:`~wx.xml.XmlNode.Parent` See :meth:`~wx.xml.XmlNode.GetParent` and :meth:`~wx.xml.XmlNode.SetParent` :attr:`~wx.xml.XmlNode.Type` See :meth:`~wx.xml.XmlNode.GetType` and :meth:`~wx.xml.XmlNode.SetType` ================================================================================ ================================================================================ | |api| Class API =============== .. class:: wx.xml.XmlNode(object) **Possible constructors**:: XmlNode(parent : XmlNode, type : XmlNodeType, name : str, content: str='', attrs: Optional[XmlAttribute]=None, next: Optional[XmlNode]=None, lineNo: int=-1) -> None XmlNode(type : XmlNodeType, name : str, content: str='', lineNo: int=-1) -> None XmlNode(node : XmlNode) -> None Represents a node in an ``XML`` document. .. method:: __init__(self, *args, **kw) |overload| **Overloaded Implementations:** :html:`

` **__init__** `(self, parent : XmlNode, type : XmlNodeType, name : str, content: str='', attrs: Optional[XmlAttribute]=None, next: Optional[XmlNode]=None, lineNo: int=-1)` Creates this ``XML`` node and inserts it into the ``XML`` tree as a child of the specified parent. Once added, the ``XML`` tree takes ownership of this object and there is no need to delete it. :param `parent`: The parent node to which append this node instance. If this argument is ``None`` this new node will be floating and it can be appended later to another one using the :meth:`AddChild` or :meth:`InsertChild` functions. Otherwise the child is added to the ``XML`` tree by this constructor and it shouldn't be done again. :type `parent`: wx.xml.XmlNode :param `type`: One of the :ref:`wx.xml.XmlNodeType` enumeration value. :type `type`: wx.xml.XmlNodeType :param `name`: The name of the node. This is the string which appears between angular brackets. :type `name`: string :param `content`: The content of the node. Only meaningful when type is ``XML_TEXT_NODE`` or ``XML_CDATA_SECTION_NODE`` . :type `content`: string :param `attrs`: If not ``None``, this :ref:`wx.xml.XmlAttribute` object and its eventual siblings are attached to the node. :type `attrs`: wx.xml.XmlAttribute :param `next`: If not ``None``, this node and its eventual siblings are attached to the node. :type `next`: wx.xml.XmlNode :param `lineNo`: Number of line this node was present at in input file or -1. :type `lineNo`: int :rtype: `None` :html:`

` **__init__** `(self, type : XmlNodeType, name : str, content: str='', lineNo: int=-1)` A simplified version of the first constructor form, assuming a ``None`` parent. :param `type`: One of the :ref:`wx.xml.XmlNodeType` enumeration value. :type `type`: wx.xml.XmlNodeType :param `name`: The name of the node. This is the string which appears between angular brackets. :type `name`: string :param `content`: The content of the node. Only meaningful when type is ``XML_TEXT_NODE`` or ``XML_CDATA_SECTION_NODE`` . :type `content`: string :param `lineNo`: Number of line this node was present at in input file or -1. :type `lineNo`: int :rtype: `None` :html:`

` **__init__** `(self, node : XmlNode)` Copy constructor. Note that this does NOT copy siblings and parent pointer, i.e. :meth:`GetParent` and :meth:`GetNext` will return ``None`` after using copy constructor and are never unmodified by :meth:`operator=` . On the other hand, it DOES copy children and attributes. :param `node`: :type `node`: wx.xml.XmlNode :rtype: `None` :html:`

` .. method:: AddAttribute(self, *args, **kw) |overload| **Overloaded Implementations:** :html:`

` **AddAttribute** `(self, name : str, value : str)` Appends an attribute with given `name` and `value` to the list of attributes for this node. :param `name`: :type `name`: string :param `value`: :type `value`: string :rtype: `None` :html:`

` **AddAttribute** `(self, attr : XmlAttribute)` Appends given attribute to the list of attributes for this node. :param `attr`: :type `attr`: wx.xml.XmlAttribute :rtype: `None` :html:`

` .. method:: AddChild(self, child : XmlNode) Adds node `child` as the last child of this node. Once added, the ``XML`` tree takes ownership of this object and there is no need to delete it. :param `child`: :type `child`: wx.xml.XmlNode :rtype: `None` .. note:: Note that this function works in O(n) time where `n` is the number of existing children. Consequently, adding large number of child nodes using this method can be expensive, because it has O(n^2) time complexity in number of nodes to be added. Use :meth:`InsertChildAfter` to populate ``XML`` tree in linear time. .. seealso:: :meth:`InsertChild` , :meth:`InsertChildAfter` .. method:: DeleteAttribute(self, name : str) Removes the first attributes which has the given `name` from the list of attributes for this node. :param `name`: :type `name`: string :rtype: `bool` .. method:: GetAttribute(self, attrName : str, defaultVal: str='') Returns the value of the attribute named `attrName` if it does exist. If it does not exist, the `defaultVal` is returned. :param `attrName`: :type `attrName`: string :param `defaultVal`: :type `defaultVal`: string :rtype: `str` .. method:: GetAttributes(self) Return a pointer to the first attribute of this node. :rtype: :ref:`wx.xml.XmlAttribute` .. method:: GetChildren(self) Returns the first child of this node. To get a pointer to the second child of this node (if it does exist), use the :meth:`GetNext` function on the returned value. :rtype: :ref:`wx.xml.XmlNode` .. method:: GetContent(self) Returns the content of this node. Can be an empty string. Be aware that for nodes of type ``XML_ELEMENT_NODE`` (the most used node type) the content is an empty string. See :meth:`GetNodeContent` for more details. :rtype: `str` .. method:: GetDepth(self, grandparent: Optional[XmlNode]=None) Returns the number of nodes which separate this node from ``grandparent`` . This function searches only the parents of this node until it finds `grandparent` or the ``None`` node (which is the parent of non-linked nodes or the parent of a :ref:`wx.xml.XmlDocument`'s root element node). :param `grandparent`: :type `grandparent`: wx.xml.XmlNode :rtype: `int` .. method:: GetLineNumber(self) Returns line number of the node in the input ``XML`` file or ``-1`` if it is unknown. :rtype: `int` .. method:: GetName(self) Returns the name of this node. Can be an empty string (e.g. for nodes of type ``XML_TEXT_NODE`` or ``XML_CDATA_SECTION_NODE`` ). :rtype: `str` .. method:: GetNext(self) Returns a pointer to the sibling of this node or ``None`` if there are no siblings. :rtype: :ref:`wx.xml.XmlNode` .. method:: GetNoConversion(self) Returns a flag indicating whether encoding conversion is necessary when saving. The default is ``False``. You can improve saving efficiency considerably by setting this value. :rtype: `bool` .. method:: GetNodeContent(self) Returns the content of the first child node of type ``XML_TEXT_NODE`` or ``XML_CDATA_SECTION_NODE`` . This function is very useful since the ``XML`` snippet ``"tagnametagcontent/tagname"`` is represented by expat with the following tag tree: .. code-block:: text XML_ELEMENT_NODE name="tagname", content="" |-- XML_TEXT_NODE name="", content="tagcontent" or eventually: .. code-block:: text XML_ELEMENT_NODE name="tagname", content="" |-- XML_CDATA_SECTION_NODE name="", content="tagcontent" An empty string is returned if the node has no children of type ``XML_TEXT_NODE`` or ``XML_CDATA_SECTION_NODE`` , or if the content of the first child of such types is empty. :rtype: `str` .. method:: GetParent(self) Returns a pointer to the parent of this node or ``None`` if this node has no parent. :rtype: :ref:`wx.xml.XmlNode` .. method:: GetType(self) Returns the type of this node. :rtype: :ref:`wx.xml.XmlNodeType` .. method:: HasAttribute(self, attrName : str) Returns ``True`` if this node has a attribute named `attrName`. :param `attrName`: :type `attrName`: string :rtype: `bool` .. method:: InsertChild(self, child : XmlNode, followingNode : XmlNode) Inserts the `child` node immediately before `followingNode` in the children list. Once inserted, the ``XML`` tree takes ownership of the new child and there is no need to delete it. :param `child`: :type `child`: wx.xml.XmlNode :param `followingNode`: :type `followingNode`: wx.xml.XmlNode :rtype: `bool` :returns: ``True`` if `followingNode` has been found and the `child` node has been inserted. .. note:: For historical reasons, `followingNode` may be ``None``. In that case, then `child` is prepended to the list of children and becomes the first child of this node, i.e. it behaves identically to using the first children (as returned by :meth:`GetChildren` ) for `followingNode`). .. seealso:: :meth:`AddChild` , :meth:`InsertChildAfter` .. method:: InsertChildAfter(self, child : XmlNode, precedingNode : XmlNode) Inserts the `child` node immediately after `precedingNode` in the children list. Once inserted, the ``XML`` tree takes ownership of the new child and there is no need to delete it. :param `child`: The child to insert. :type `child`: wx.xml.XmlNode :param `precedingNode`: The node to insert `child` after. As a special case, this can be ``None`` if this node has no children yet – in that case, `child` will become this node's only child node. :type `precedingNode`: wx.xml.XmlNode :rtype: `bool` :returns: ``True`` if `precedingNode` has been found and the `child` node has been inserted. .. versionadded:: 2.8.8 .. seealso:: :meth:`InsertChild` , :meth:`AddChild` .. method:: IsWhitespaceOnly(self) Returns ``True`` if the content of this node is a string containing only whitespaces (spaces, tabs, new lines, etc). Note that this function is locale-independent since the parsing of ``XML`` documents must always produce the exact same tree regardless of the locale it runs under. :rtype: `bool` .. method:: RemoveChild(self, child : XmlNode) Removes the given node from the children list. Returns ``True`` if the node was found and removed or ``False`` if the node could not be found. Note that the caller is responsible for deleting the removed node in order to avoid memory leaks. :param `child`: :type `child`: wx.xml.XmlNode :rtype: `bool` .. method:: SetContent(self, con : str) Sets the content of this node. :param `con`: :type `con`: string :rtype: `None` .. method:: SetName(self, name : str) Sets the name of this node. :param `name`: :type `name`: string :rtype: `None` .. method:: SetNext(self, next : XmlNode) Sets as sibling the given node. The caller is responsible for deleting any previously present sibling node. :param `next`: :type `next`: wx.xml.XmlNode :rtype: `None` .. method:: SetNoConversion(self, noconversion : bool) Sets a flag to indicate whether encoding conversion is necessary when saving. The default is ``False``. You can improve saving efficiency considerably by setting this value. :param `noconversion`: :type `noconversion`: bool :rtype: `None` .. method:: SetParent(self, parent : XmlNode) Sets as parent the given node. The caller is responsible for deleting any previously present parent node. :param `parent`: :type `parent`: wx.xml.XmlNode :rtype: `None` .. method:: SetType(self, type : XmlNodeType) Sets the type of this node. :param `type`: :type `type`: wx.xml.XmlNodeType :rtype: `None` .. attribute:: Attributes See :meth:`~wx.xml.XmlNode.GetAttributes` .. attribute:: Children See :meth:`~wx.xml.XmlNode.GetChildren` .. attribute:: Content See :meth:`~wx.xml.XmlNode.GetContent` and :meth:`~wx.xml.XmlNode.SetContent` .. attribute:: Depth See :meth:`~wx.xml.XmlNode.GetDepth` .. attribute:: LineNumber See :meth:`~wx.xml.XmlNode.GetLineNumber` .. attribute:: Name See :meth:`~wx.xml.XmlNode.GetName` and :meth:`~wx.xml.XmlNode.SetName` .. attribute:: Next See :meth:`~wx.xml.XmlNode.GetNext` and :meth:`~wx.xml.XmlNode.SetNext` .. attribute:: NoConversion See :meth:`~wx.xml.XmlNode.GetNoConversion` and :meth:`~wx.xml.XmlNode.SetNoConversion` .. attribute:: NodeContent See :meth:`~wx.xml.XmlNode.GetNodeContent` .. attribute:: Parent See :meth:`~wx.xml.XmlNode.GetParent` and :meth:`~wx.xml.XmlNode.SetParent` .. attribute:: Type See :meth:`~wx.xml.XmlNode.GetType` and :meth:`~wx.xml.XmlNode.SetType`