<html>
<head>
<title>Cal3D: cal3d::TiXmlHandle Class Reference</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head>
<body bgcolor="#ffffff">
<table width="100%" border="0" cellspacing="0" cellpadding="5" align="center">
<tr>
<td class="md" align="center">
<small>
<b>- Cal3D 0.11 API Reference -</b>
</small>
</td>
</tr>
</table>
<br>
<!-- Generated by Doxygen 1.5.9 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li class="current"><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div class="tabs">
<ul>
<li><a href="annotated.html"><span>Class List</span></a></li>
<li><a href="classes.html"><span>Class Index</span></a></li>
<li><a href="hierarchy.html"><span>Class Hierarchy</span></a></li>
<li><a href="functions.html"><span>Class Members</span></a></li>
</ul>
</div>
<div class="navpath"><b>cal3d</b>::<a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a>
</div>
</div>
<div class="contents">
<h1>cal3d::TiXmlHandle Class Reference</h1><!-- doxytag: class="cal3d::TiXmlHandle" -->A <a class="el" href="classcal3d_1_1TiXmlHandle.html" title="A TiXmlHandle is a class that wraps a node pointer with null checks; this is an incredibly...">TiXmlHandle</a> is a class that wraps a node pointer with null checks; this is an incredibly useful thing.
<a href="#_details">More...</a>
<p>
<code>#include <<a class="el" href="tinyxml_8h_source.html">tinyxml.h</a>></code>
<p>
<p>
<a href="classcal3d_1_1TiXmlHandle-members.html">List of all members.</a><table border="0" cellpadding="0" cellspacing="0">
<tr><td></td></tr>
<tr><td colspan="2"><br><h2>Public Member Functions</h2></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="2634fbe02d86050ee8f70805ebc8b71c"></a><!-- doxytag: member="cal3d::TiXmlHandle::TiXmlHandle" ref="2634fbe02d86050ee8f70805ebc8b71c" args="(TiXmlNode *node)" -->
</td><td class="memItemRight" valign="bottom"><a class="el" href="classcal3d_1_1TiXmlHandle.html#2634fbe02d86050ee8f70805ebc8b71c">TiXmlHandle</a> (<a class="el" href="classcal3d_1_1TiXmlNode.html">TiXmlNode</a> *node)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Create a handle from any node (at any depth of the tree.) This can be a null pointer. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="291b2a3d55cb89c6037c3e8441db1b89"></a><!-- doxytag: member="cal3d::TiXmlHandle::TiXmlHandle" ref="291b2a3d55cb89c6037c3e8441db1b89" args="(const TiXmlHandle &ref)" -->
</td><td class="memItemRight" valign="bottom"><a class="el" href="classcal3d_1_1TiXmlHandle.html#291b2a3d55cb89c6037c3e8441db1b89">TiXmlHandle</a> (const <a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> &ref)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Copy constructor. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="100b7af03335be71384aab78d91a6b25"></a><!-- doxytag: member="cal3d::TiXmlHandle::FirstChild" ref="100b7af03335be71384aab78d91a6b25" args="() const " -->
<a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classcal3d_1_1TiXmlHandle.html#100b7af03335be71384aab78d91a6b25">FirstChild</a> () const </td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Return a handle to the first child node. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="5cbe65fbc5abf57c918a1f0d797742cf"></a><!-- doxytag: member="cal3d::TiXmlHandle::FirstChild" ref="5cbe65fbc5abf57c918a1f0d797742cf" args="(const char *value) const " -->
<a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classcal3d_1_1TiXmlHandle.html#5cbe65fbc5abf57c918a1f0d797742cf">FirstChild</a> (const char *value) const </td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Return a handle to the first child node with the given name. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="632fa8f8733d3c00b7ff5ccd51861d53"></a><!-- doxytag: member="cal3d::TiXmlHandle::FirstChildElement" ref="632fa8f8733d3c00b7ff5ccd51861d53" args="() const " -->
<a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classcal3d_1_1TiXmlHandle.html#632fa8f8733d3c00b7ff5ccd51861d53">FirstChildElement</a> () const </td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Return a handle to the first child element. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="b65c9982d84ca16e307b52e749e25f90"></a><!-- doxytag: member="cal3d::TiXmlHandle::FirstChildElement" ref="b65c9982d84ca16e307b52e749e25f90" args="(const char *value) const " -->
<a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classcal3d_1_1TiXmlHandle.html#b65c9982d84ca16e307b52e749e25f90">FirstChildElement</a> (const char *value) const </td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Return a handle to the first child element with the given name. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classcal3d_1_1TiXmlHandle.html#a07271ed578719132aea0801b085f681">Child</a> (const char *value, int index) const </td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Return a handle to the "index" child with the given name. <a href="#a07271ed578719132aea0801b085f681"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classcal3d_1_1TiXmlHandle.html#56072f621a2cf3327c9f511b6584ed84">Child</a> (int index) const </td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Return a handle to the "index" child. <a href="#56072f621a2cf3327c9f511b6584ed84"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classcal3d_1_1TiXmlHandle.html#42ddb459febe87a362e733d06159a58b">ChildElement</a> (const char *value, int index) const </td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Return a handle to the "index" child element with the given name. <a href="#42ddb459febe87a362e733d06159a58b"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classcal3d_1_1TiXmlHandle.html#e4fbbf64daf7ce35ffd70e7b421052e1">ChildElement</a> (int index) const </td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Return a handle to the "index" child element. <a href="#e4fbbf64daf7ce35ffd70e7b421052e1"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="97bd5ccdeac46245bef6f53a76002dc9"></a><!-- doxytag: member="cal3d::TiXmlHandle::FirstChild" ref="97bd5ccdeac46245bef6f53a76002dc9" args="(const std::string &_value) const " -->
<a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><b>FirstChild</b> (const std::string &_value) const </td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="5c56af1197ac05b83c585489a32fa16f"></a><!-- doxytag: member="cal3d::TiXmlHandle::FirstChildElement" ref="5c56af1197ac05b83c585489a32fa16f" args="(const std::string &_value) const " -->
<a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><b>FirstChildElement</b> (const std::string &_value) const </td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="b9a20a4e344bdeca9e8b0312ce0c96b6"></a><!-- doxytag: member="cal3d::TiXmlHandle::Child" ref="b9a20a4e344bdeca9e8b0312ce0c96b6" args="(const std::string &_value, int index) const " -->
<a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><b>Child</b> (const std::string &_value, int index) const </td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="63519133949974592d3dc03aed28691f"></a><!-- doxytag: member="cal3d::TiXmlHandle::ChildElement" ref="63519133949974592d3dc03aed28691f" args="(const std::string &_value, int index) const " -->
<a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> </td><td class="memItemRight" valign="bottom"><b>ChildElement</b> (const std::string &_value, int index) const </td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="0f79f079066b18597f83b4f01a00c117"></a><!-- doxytag: member="cal3d::TiXmlHandle::Node" ref="0f79f079066b18597f83b4f01a00c117" args="() const " -->
<a class="el" href="classcal3d_1_1TiXmlNode.html">TiXmlNode</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="classcal3d_1_1TiXmlHandle.html#0f79f079066b18597f83b4f01a00c117">Node</a> () const </td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Return the handle as a <a class="el" href="classcal3d_1_1TiXmlNode.html" title="The parent class for everything in the Document Object Model.">TiXmlNode</a>. This may return null. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="43c162069b1ab50ad576c7b43f07e2e9"></a><!-- doxytag: member="cal3d::TiXmlHandle::Element" ref="43c162069b1ab50ad576c7b43f07e2e9" args="() const " -->
<a class="el" href="classcal3d_1_1TiXmlElement.html">TiXmlElement</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="classcal3d_1_1TiXmlHandle.html#43c162069b1ab50ad576c7b43f07e2e9">Element</a> () const </td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Return the handle as a <a class="el" href="classcal3d_1_1TiXmlElement.html" title="The element is a container class.">TiXmlElement</a>. This may return null. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="50d38c9f81c8fe1eb23a7a5b5094ed1a"></a><!-- doxytag: member="cal3d::TiXmlHandle::Text" ref="50d38c9f81c8fe1eb23a7a5b5094ed1a" args="() const " -->
<a class="el" href="classcal3d_1_1TiXmlText.html">TiXmlText</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="classcal3d_1_1TiXmlHandle.html#50d38c9f81c8fe1eb23a7a5b5094ed1a">Text</a> () const </td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Return the handle as a <a class="el" href="classcal3d_1_1TiXmlText.html" title="XML text.">TiXmlText</a>. This may return null. <br></td></tr>
</table>
<hr><a name="_details"></a><h2>Detailed Description</h2>
A <a class="el" href="classcal3d_1_1TiXmlHandle.html" title="A TiXmlHandle is a class that wraps a node pointer with null checks; this is an incredibly...">TiXmlHandle</a> is a class that wraps a node pointer with null checks; this is an incredibly useful thing.
<p>
Note that <a class="el" href="classcal3d_1_1TiXmlHandle.html" title="A TiXmlHandle is a class that wraps a node pointer with null checks; this is an incredibly...">TiXmlHandle</a> is not part of the TinyXml DOM structure. It is a separate utility class.<p>
Take an example: <div class="fragment"><pre class="fragment">
<Document>
<Element attributeA = "valueA">
<Child attributeB = "value1" />
<Child attributeB = "value2" />
</Element>
<Document>
</pre></div><p>
Assuming you want the value of "attributeB" in the 2nd "Child" element, it's very easy to write a *lot* of code that looks like:<p>
<div class="fragment"><pre class="fragment">
TiXmlElement* root = document.FirstChildElement( "Document" );
if ( root )
{
TiXmlElement* element = root->FirstChildElement( "Element" );
if ( element )
{
TiXmlElement* child = element->FirstChildElement( "Child" );
if ( child )
{
TiXmlElement* child2 = child->NextSiblingElement( "Child" );
if ( child2 )
{
// Finally do something useful.
</pre></div><p>
And that doesn't even cover "else" cases. <a class="el" href="classcal3d_1_1TiXmlHandle.html" title="A TiXmlHandle is a class that wraps a node pointer with null checks; this is an incredibly...">TiXmlHandle</a> addresses the verbosity of such code. A <a class="el" href="classcal3d_1_1TiXmlHandle.html" title="A TiXmlHandle is a class that wraps a node pointer with null checks; this is an incredibly...">TiXmlHandle</a> checks for null pointers so it is perfectly safe and correct to use:<p>
<div class="fragment"><pre class="fragment">
TiXmlHandle docHandle( &document );
TiXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).Element();
if ( child2 )
{
// do something useful
</pre></div><p>
Which is MUCH more concise and useful.<p>
It is also safe to copy handles - internally they are nothing more than node pointers. <div class="fragment"><pre class="fragment">
TiXmlHandle handleCopy = handle;
</pre></div><p>
What they should not be used for is iteration:<p>
<div class="fragment"><pre class="fragment">
int i=0;
while ( true )
{
TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", i ).Element();
if ( !child )
break;
// do something
++i;
}
</pre></div><p>
It seems reasonable, but it is in fact two embedded while loops. The Child method is a linear walk to find the element, so this code would iterate much more than it needs to. Instead, prefer:<p>
<div class="fragment"><pre class="fragment">
TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).FirstChild( "Child" ).Element();
for( child; child; child=child->NextSiblingElement() )
{
// do something
}
</pre></div> <hr><h2>Member Function Documentation</h2>
<a class="anchor" name="56072f621a2cf3327c9f511b6584ed84"></a><!-- doxytag: member="cal3d::TiXmlHandle::Child" ref="56072f621a2cf3327c9f511b6584ed84" args="(int index) const " -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> cal3d::TiXmlHandle::Child </td>
<td>(</td>
<td class="paramtype">int </td>
<td class="paramname"> <em>index</em> </td>
<td> ) </td>
<td> const</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Return a handle to the "index" child.
<p>
The first child is 0, the second 1, etc.
</div>
</div><p>
<a class="anchor" name="a07271ed578719132aea0801b085f681"></a><!-- doxytag: member="cal3d::TiXmlHandle::Child" ref="a07271ed578719132aea0801b085f681" args="(const char *value, int index) const " -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> cal3d::TiXmlHandle::Child </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>value</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>index</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td> const</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Return a handle to the "index" child with the given name.
<p>
The first child is 0, the second 1, etc.
</div>
</div><p>
<a class="anchor" name="e4fbbf64daf7ce35ffd70e7b421052e1"></a><!-- doxytag: member="cal3d::TiXmlHandle::ChildElement" ref="e4fbbf64daf7ce35ffd70e7b421052e1" args="(int index) const " -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> cal3d::TiXmlHandle::ChildElement </td>
<td>(</td>
<td class="paramtype">int </td>
<td class="paramname"> <em>index</em> </td>
<td> ) </td>
<td> const</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Return a handle to the "index" child element.
<p>
The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted.
</div>
</div><p>
<a class="anchor" name="42ddb459febe87a362e733d06159a58b"></a><!-- doxytag: member="cal3d::TiXmlHandle::ChildElement" ref="42ddb459febe87a362e733d06159a58b" args="(const char *value, int index) const " -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classcal3d_1_1TiXmlHandle.html">TiXmlHandle</a> cal3d::TiXmlHandle::ChildElement </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>value</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>index</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td> const</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Return a handle to the "index" child element with the given name.
<p>
The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted.
</div>
</div><p>
<hr>The documentation for this class was generated from the following files:<ul>
<li><a class="el" href="tinyxml_8h_source.html">tinyxml.h</a><li>tinyxml.cpp</ul>
</div>
<hr>
<center>
<small>
Generated at Fri Jul 24 21:14:57 2009 by
<a href="http://gna.org/projects/cal3d/">The Cal3D Team</a>
with
<a href="http://www.doxygen.org/index.html">
Doxygen 1.5.9
</a>
</small>
</center>
</body>
</html>
