.. wxPython Phoenix documentation
This file was generated by Phoenix's sphinx generator and associated
tools, do not edit by hand.
Copyright: (c) 2011-2018 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`.
Node has a name and may have content and attributes.
Most common node types are ``XML_TEXT_NODE`` (name and attributes are irrelevant) and ``XML_ELEMENT_NODE`` .
Example: in ``<title>hi</title>`` there is an element with the name ``title`` and irrelevant content and one child of type ``XML_TEXT_NODE`` with ``hi`` as content.
The ``XML_PI_NODE`` type sets the name to the ``PI`` target and the contents to the instructions. Note that whilst the ``PI`` instructions are often in the form of pseudo-attributes these do not use the nodes attribute system. It is the users responsibility to code and decode the instruction text.
If ``USE_UNICODE`` is 0, all strings are encoded in the encoding given to :meth:`wx.xml.XmlDocument.Load` (default is ``UTF-8``).
.. seealso:: :ref:`wx.xml.XmlDocument`, :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.png" 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,140,35"/> </map>
</p>
</div>
|
|method_summary| Methods Summary
================================
================================================================================ ================================================================================
:meth:`~wx.xml.XmlNode.__init__` Creates this ``XML`` node and eventually insert it into an existing ``XML`` tree.
:meth:`~wx.xml.XmlNode.AddAttribute` Appends a 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, type, name, content="", attrs=None, next=None,
lineNo=-1)
XmlNode(type, name, content="", lineNo=-1)
XmlNode(node)
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=None, next=None, lineNo=-1)`
Creates this ``XML`` node and eventually insert it into an existing ``XML`` tree.
: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 already 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
:html:`<hr class="overloadsep" /><br />`
**__init__** `(self, type, name, content="", lineNo=-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
: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 ``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
:html:`<hr class="overloadsep" /><br />`
.. method:: AddAttribute(self, *args, **kw)
|overload| Overloaded Implementations:
:html:`<hr class="overloadsep" /><br />`
**AddAttribute** `(self, name, value)`
Appends a attribute with given `name` and `value` to the list of attributes for this node.
:param `name`:
:type `name`: string
:param `value`:
:type `value`: string
: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
:html:`<hr class="overloadsep" /><br />`
.. method:: AddChild(self, child)
Adds node `child` as the last child of this node.
:param `child`:
:type `child`: wx.xml.XmlNode
.. 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: `string`
.. 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: `string`
.. method:: GetDepth(self, grandparent=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: `string`
.. 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: `string`
.. 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)
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.
: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, precedingNode)
Inserts the `child` node immediately after `precedingNode` in the children list.
: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 `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
.. method:: SetName(self, name)
Sets the name of this node.
:param `name`:
:type `name`: string
.. 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
.. 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
.. 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
.. method:: SetType(self, type)
Sets the type of this node.
:param `type`:
:type `type`: wx.xml.XmlNodeType
.. 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`