X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4c43dd9078b2f9f8bb280020a878932272d0163e..066f3611df971be93b2ec46b82c2f05f3ff9a422:/docs/latex/wx/xmlnode.tex diff --git a/docs/latex/wx/xmlnode.tex b/docs/latex/wx/xmlnode.tex index 19c62b2423..342474454d 100644 --- a/docs/latex/wx/xmlnode.tex +++ b/docs/latex/wx/xmlnode.tex @@ -1,15 +1,25 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: xmlnode.tex +%% Purpose: wxXmlNode documentation +%% Author: Francesco Montorsi +%% Created: 2006-04-18 +%% RCS-ID: $Id$ +%% Copyright: (c) 2006 Francesco Montorsi +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \section{\class{wxXmlNode}}\label{wxxmlnode} Represents a node in an XML document. See \helpref{wxXmlDocument}{wxxmldocument}. -Node has a name and may have content -and properties. Most common node types are {\tt wxXML\_TEXT\_NODE} (name and -properties are irrelevant) and {\tt wxXML\_ELEMENT\_NODE} (e.g. in {\tt hi} there is -an element with name="title", irrelevant content and one child ({\tt wxXML\_TEXT\_NODE} +Node has a name and may have content and attributes. Most common node types are +{\tt wxXML\_TEXT\_NODE} (name and attributes are irrelevant) and +{\tt wxXML\_ELEMENT\_NODE} (e.g. in {\tt hi} there is an element +with name="title", irrelevant content and one child ({\tt wxXML\_TEXT\_NODE} with content="hi"). -If wxUSE\_UNICODE is 0, all strings are encoded in the encoding given to Load -(default is UTF-8). +If \texttt{wxUSE\_UNICODE} is 0, all strings are encoded in the encoding given to +\helpref{wxXmlDocument::Load}{wxxmldocumentload} (default is UTF-8). \wxheading{Derived from} @@ -20,9 +30,13 @@ No base class +\wxheading{Library} + +\helpref{wxXml}{librarieslist} + \wxheading{Constants} -The following are the node types supported by wxXmlNode: +The following are the node types supported by \helpref{wxXmlNode}{wxxmlnode}: {\small \begin{verbatim} @@ -47,7 +61,7 @@ enum wxXmlNodeType \wxheading{See also} -\helpref{wxXmlDocument}{wxxmldocument}, \helpref{wxXmlProperty}{wxxmlproperty} +\helpref{wxXmlDocument}{wxxmldocument}, \helpref{wxXmlAttribute}{wxxmlattribute} \latexignore{\rtfignore{\wxheading{Members}}} @@ -55,39 +69,46 @@ enum wxXmlNodeType \membersection{wxXmlNode::wxXmlNode}\label{wxxmlnodewxxmlnode} - -\func{}{wxXmlNode}{\param{wxXmlNode* }{parent}, \param{wxXmlNodeType }{type}, \param{const wxString\& }{name}, \param{const wxString\& }{content = wxEmptyString}, \param{wxXmlProperty* }{props = NULL}, \param{wxXmlNode* }{next = NULL}} +\func{}{wxXmlNode}{\param{wxXmlNode* }{parent}, \param{wxXmlNodeType }{type}, \param{const wxString\& }{name}, \param{const wxString\& }{content = wxEmptyString}, \param{wxXmlAttribute* }{attrs = \NULL}, \param{wxXmlNode* }{next = \NULL}} \wxheading{Parameters} -\docparam{parent}{The parent node. Can be NULL.} +\docparam{parent}{The parent node to which append this node instance. +If this argument is \NULL this new node will be {\it floating} and it can be appended later to +another one using the \helpref{AddChild}{wxxmlnodeaddchild} or \helpref{InsertChild}{wxxmlnodeinsertchild} +functions. Otherwise the child is already added to the XML tree by this +constructor and it shouldn't be done again.} \docparam{type}{One of the wxXmlNodeType enumeration value.} \docparam{name}{The name of the node. This is the string which appears between angular brackets.} -\docparam{content}{The content of the node. Only meaningful when {\it type} is {\tt wxXML\_TEXT\_NODE} or {\tt wxXML\_CDATA\_SECTION\_NODE}.} -\docparam{props}{If not NULL, this wxXmlProperty object and its eventual siblings are attached to -the node.} -\docparam{next}{If not NULL, this node and its eventual siblings are attached to +\docparam{content}{The content of the node. Only meaningful when {\it type} is +{\tt wxXML\_TEXT\_NODE} or {\tt wxXML\_CDATA\_SECTION\_NODE}.} +\docparam{attrs}{If not \NULL, this \helpref{wxXmlAttribute}{wxxmlattribute} object +and its eventual siblings are attached to the node.} +\docparam{next}{If not \NULL, this node and its eventual siblings are attached to the node.} +Creates this XML node and eventually insert it into an existing XML tree. + \func{}{wxXmlNode}{\param{const wxXmlNode\& }{node}} Copy constructor. Note that this does NOT copy syblings -and parent pointer, i.e. \helpref{GetParent()}{wxxmlnodegetparent} and \helpref{GetNext()}{wxxmlnodegetnext} will return NULL +and parent pointer, i.e. \helpref{GetParent()}{wxxmlnodegetparent} and +\helpref{GetNext()}{wxxmlnodegetnext} will return \NULL after using copy ctor and are never unmodified by operator=. -On the other hand, it DOES copy children and properties. +On the other hand, it DOES copy children and attributes. \func{}{wxXmlNode}{\param{wxXmlNodeType }{type}, \param{const wxString\& }{name}, \param{const wxString\& }{content = wxEmptyString}} -A simplified version of the first constructor form. +A simplified version of the first constructor form, assuming a \NULL parent. \membersection{wxXmlNode::\destruct{wxXmlNode}}\label{wxxmlnodedtor} \func{}{\destruct{wxXmlNode}}{\void} -The virtual destructor. Deletes attached children and properties. +The virtual destructor. Deletes attached children and attributes. \membersection{wxXmlNode::AddChild}\label{wxxmlnodeaddchild} @@ -96,21 +117,21 @@ The virtual destructor. Deletes attached children and properties. Adds the given node as child of this node. To attach a second children to this node, use the \helpref{SetNext()}{wxxmlnodesetnext} function of the {\it child} node. -\membersection{wxXmlNode::AddProperty}\label{wxxmlnodeaddproperty} +\membersection{wxXmlNode::AddAttribute}\label{wxxmlnodeaddattribute} -\func{void}{AddProperty}{\param{const wxString\& }{name}, \param{const wxString\& }{value}} +\func{void}{AddAttribute}{\param{const wxString\& }{name}, \param{const wxString\& }{value}} -Appends a property with given {\it name} and {\it value} to the list of properties for this node. +Appends a attribute with given {\it name} and {\it value} to the list of attributes for this node. -\func{void}{AddProperty}{\param{wxXmlProperty* }{prop}} +\func{void}{AddAttribute}{\param{wxXmlAttribute* }{attr}} -Appends the given property to the list of properties for this node. +Appends given attribute to the list of attributes for this node. -\membersection{wxXmlNode::DeleteProperty}\label{wxxmlnodedeleteproperty} +\membersection{wxXmlNode::DeleteAttribute}\label{wxxmlnodedeleteattribute} -\func{bool}{DeleteProperty}{\param{const wxString\& }{name}} +\func{bool}{DeleteAttribute}{\param{const wxString\& }{name}} -Removes the first properties which has the given {\it name} from the list of properties for this node. +Removes the first attributes which has the given {\it name} from the list of attributes for this node. \membersection{wxXmlNode::GetChildren}\label{wxxmlnodegetchildren} @@ -125,6 +146,43 @@ To get a pointer to the second child of this node (if it does exist), use the \constfunc{wxString}{GetContent}{\void} Returns the content of this node. Can be an empty string. +Be aware that for nodes of type \texttt{wxXML\_ELEMENT\_NODE} (the most used node type) the +content is an empty string. See \helpref{GetNodeContent()}{wxxmlnodegetnodecontent} for more details. + + +\membersection{wxXmlNode::GetDepth}\label{wxxmlnodegetdepth} + +\constfunc{int}{GetDepth}{\param{wxXmlNode* }{grandparent = NULL}} + +Returns the number of nodes which separe this node from {\tt grandparent}. + +This function searches only the parents of this node until it finds {\tt grandparent} +or the \NULL node (which is the parent of non-linked nodes or the parent of a +\helpref{wxXmlDocument}{wxxmldocument}'s root node). + + +\membersection{wxXmlNode::GetNodeContent}\label{wxxmlnodegetnodecontent} + +\constfunc{wxString}{GetNodeContent}{\void} + +Returns the content of the first child node of type \texttt{wxXML\_TEXT\_NODE} or \texttt{wxXML\_CDATA\_SECTION\_NODE}. +This function is very useful since the XML snippet \texttt{``tagcontent"} is represented by +expat with the following tag tree: + +\begin{verbatim} +wxXML_ENTITY_NODE name="tagname", content="" +|-- wxXML_TEXT_NODE name="", content="tagcontent" +\end{verbatim} + +or eventually: + +\begin{verbatim} +wxXML_ENTITY_NODE name="tagname", content="" +|-- wxXML_CDATA_SECTION_NODE name="", content="tagcontent" +\end{verbatim} + +An empty string is returned if the node has no children of type \texttt{wxXML\_TEXT\_NODE} or \texttt{wxXML\_CDATA\_SECTION\_NODE}, or if the content of the first child of such types is empty. + \membersection{wxXmlNode::GetName}\label{wxxmlnodegetname} @@ -136,31 +194,31 @@ Returns the name of this node. Can be an empty string (e.g. for nodes of type {\ \constfunc{wxXmlNode*}{GetNext}{\void} -Returns a pointer to the sibling of this node or NULL if there are no siblings. +Returns a pointer to the sibling of this node or \NULL if there are no siblings. \membersection{wxXmlNode::GetParent}\label{wxxmlnodegetparent} \constfunc{wxXmlNode*}{GetParent}{\void} -Returns a pointer to the parent of this node or NULL if this node has no parent. +Returns a pointer to the parent of this node or \NULL if this node has no parent. -\membersection{wxXmlNode::GetPropVal}\label{wxxmlnodegetpropval} +\membersection{wxXmlNode::GetAttribute}\label{wxxmlnodegetattribute} -\constfunc{bool}{GetPropVal}{\param{const wxString\& }{propName}, \param{wxString* }{value}} +\constfunc{bool}{GetAttribute}{\param{const wxString\& }{attrName}, \param{wxString* }{value}} -Returns \true if a property named {\it propName} could be found. -If the {\it value} pointer is not NULL, the value of that property is saved there. +Returns \true if a attribute named {\it attrName} could be found. +If the {\it value} pointer is not \NULL, the value of that attribute is saved there. -\constfunc{wxString}{GetPropVal}{\param{const wxString\& }{propName}, \param{const wxString\& }{defaultVal}} +\constfunc{wxString}{GetAttribute}{\param{const wxString\& }{attrName}, \param{const wxString\& }{defaultVal}} -Returns the value of the property named {\it propName} if it does exist. +Returns the value of the attribute named {\it attrName} if it does exist. If it does not exist, the {\it defaultVal} is returned. -\membersection{wxXmlNode::GetProperties}\label{wxxmlnodegetproperties} +\membersection{wxXmlNode::GetAttributes}\label{wxxmlnodegetattributes} -\constfunc{wxXmlProperty*}{GetProperties}{\void} +\constfunc{wxXmlAttribute *}{GetAttributes}{\void} -Return a pointer to the first property of this node. +Return a pointer to the first attribute of this node. \membersection{wxXmlNode::GetType}\label{wxxmlnodegettype} @@ -169,17 +227,28 @@ Return a pointer to the first property of this node. Returns the type of this node. -\membersection{wxXmlNode::HasProp}\label{wxxmlnodehasprop} +\membersection{wxXmlNode::HasAttribute}\label{wxxmlnodehasattribute} -\constfunc{bool}{HasProp}{\param{const wxString\& }{propName}} +\constfunc{bool}{HasAttribute}{\param{const wxString\& }{attrName}} -Returns \true if this node has a property named {\it propName}. +Returns \true if this node has a attribute named {\it attrName}. \membersection{wxXmlNode::InsertChild}\label{wxxmlnodeinsertchild} -\func{void}{InsertChild}{\param{wxXmlNode* }{child}, \param{wxXmlNode* }{before\_node}} +\func{bool}{InsertChild}{\param{wxXmlNode* }{child}, \param{wxXmlNode* }{before\_node}} Inserts the {\it child} node after {\it before\_node} in the children list. +If {\it before\_node} is \NULL, then {\it child} is prepended to the list of children and +becomes the first child of this node. +Returns \true if {\it before\_node} has been found and the {\it child} node has been inserted. + +\membersection{wxXmlNode::IsWhitespaceOnly}\label{wxxmlnodecontainsiswhitespaceonly} + +\constfunc{bool}{IsWhitespaceOnly}{\void} + +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. \membersection{wxXmlNode::RemoveChild}\label{wxxmlnoderemovechild} @@ -188,6 +257,8 @@ Inserts the {\it child} node after {\it before\_node} in the children list. 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 reponsible for deleting the removed node in order to avoid memory leaks. + \membersection{wxXmlNode::SetChildren}\label{wxxmlnodesetchildren} \func{void}{SetChildren}{\param{wxXmlNode* }{child}} @@ -221,12 +292,12 @@ sibling node. Sets as parent the given node. The caller is responsible to delete any previously present parent node. -\membersection{wxXmlNode::SetProperties}\label{wxxmlnodesetproperties} +\membersection{wxXmlNode::SetAttributes}\label{wxxmlnodesetattributes} -\func{void}{SetProperties}{\param{wxXmlProperty* }{prop}} +\func{void}{SetAttributes}{\param{wxXmlAttribute* }{attr}} -Sets as first property the given wxXmlProperty object. -The caller is responsible to delete any previously present properties attached to this node. +Sets as first attribute the given wxXmlAttribute object. +The caller is responsible to delete any previously present attributes attached to this node. \membersection{wxXmlNode::SetType}\label{wxxmlnodesettype} @@ -236,7 +307,7 @@ Sets the type of this node. \membersection{wxXmlNode::operator=}\label{wxxmlnodeoperatorassign} -\func{wxXmlNode\& operator}{operator=}{\param{const wxXmlNode\& }{node}} +\func{wxXmlNode\&}{operator=}{\param{const wxXmlNode\& }{node}} See the copy constructor for more info.