.. 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  ``<title>hi</title>``   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. 








         



.. 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

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>XmlNode</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.xml.XmlNode_inheritance.svg" alt="Inheritance diagram of XmlNode" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.xml.XmlNode.html" title="Represents a node in an ``XML`` document." alt="" coords="5,5,154,34"/> </map> 
   </p>
   </div>

|


|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 nullptr 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 nullptr 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, type, name, content='', attrs=nullptr, next=nullptr,
               lineNo=-1) -> None
       
       XmlNode(type, name, content='', lineNo=-1) -> None
       
       XmlNode(node) -> None
       
   
   Represents a node in an ``XML`` document.



   .. method:: __init__(self, *args, **kw)



      |overload| **Overloaded Implementations:**

      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, parent, type, name, content='', attrs=nullptr, next=nullptr, lineNo=-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 nullptr 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 nullptr, this :ref:`wx.xml.XmlAttribute`  object and its eventual siblings are attached to the node.   
      :type `attrs`: wx.xml.XmlAttribute
      :param `next`: If not nullptr, 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:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, type, name, content='', lineNo=-1)`
      
      A simplified version of the first constructor form, assuming a nullptr 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:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, node)`
      
      Copy constructor. 
                       
      
      Note that this does NOT copy siblings and parent pointer, i.e. :meth:`GetParent`   and :meth:`GetNext`   will return nullptr 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:`<hr class="overloadsep" /><br />`






   .. method:: AddAttribute(self, *args, **kw)



      |overload| **Overloaded Implementations:**

      :html:`<hr class="overloadsep" /><br />`

      
      **AddAttribute** `(self, name, value)`
      
      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:`<hr class="overloadsep" /><br />`

      
      **AddAttribute** `(self, attr)`
      
      Appends given attribute to the list of attributes for this node. 
                       
      
      
      :param `attr`: 
      :type `attr`: wx.xml.XmlAttribute
      
      
      
      
      :rtype: `None`     
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: AddChild(self, child)

      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)

      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, defaultVal='')

      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=nullptr)

      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 nullptr 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 nullptr 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 nullptr 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)

      Returns ``True`` if this node has a attribute named `attrName`. 
                 


      :param `attrName`: 
      :type `attrName`: string




      :rtype: `bool`








   .. method:: InsertChild(self, child, followingNode)

      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 nullptr. 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, precedingNode)

      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 nullptr 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)

      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)

      Sets the content of this node. 
                 


      :param `con`: 
      :type `con`: string




      :rtype: `None`     








   .. method:: SetName(self, name)

      Sets the name of this node. 
                 


      :param `name`: 
      :type `name`: string




      :rtype: `None`     








   .. method:: SetNext(self, next)

      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)

      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)

      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)

      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`

