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