bool CMarkup::IntoElem();

IntoElem makes the main position element the parent element. If there is no main position it returns false and does not affect the current position at all.

Here is an example document with 3 levels, a config element which contains a diagnostics element which contains a file element:

<config>
  <diagnostics d="3">
    <file>C:\temp\a.txt</file>
  </diagnostics>
</config>

Here is the simplest way to navigate to the file element:

xml.ResetPos();
xml.FindElem(); // config
xml.IntoElem();
xml.FindElem(); // diagnostics
xml.IntoElem();
xml.FindElem(); // file

There are other ways of getting there such as:

xml.ResetPos();
xml.FindChildElem();
xml.IntoElem(); // diagnostics
xml.FindChildElem( "file" );
xml.IntoElem(); // file

See Navigating Levels in CMarkup.

OutOfElem is the corresponding method for returning back towards the root of the document. Often when you are looping through a document, processing elements, you make sure your IntoElem calls correspond to your OutOfElem calls. For example:

xml.ResetPos();
xml.FindElem();
xml.IntoElem();
while ( xml.FindElem("diagnostics") )
{
  xml.IntoElem();
  while ( xml.FindElem("file") )
    DoSomethingWithFile(xml);
  xml.OutOfElem();
}
xml.OutOfElem();

Update March 24, 2009: IntoElem can be used with CMarkup release 11.0 developer version file read mode (see C++ XML reader) and file write mode (see C++ XML writer). In the file modes, the meaning of IntoElem is the same as otherwise but its usage is limited to the forward-only purposes of file reading and writing. Once you go "into" an element it leaves the start tag behind, and you cannot access (read or write) the attributes or tag name. In file write mode IntoElem goes "into" the current element (which must have been added without a data value) to add elements and nodes between its start and end tags. In file read mode, IntoElem goes "into" the current element to find elements and nodes between its start and end tags.