CMarkup FindChildElem Method

bool CMarkup::FindChildElem( MCD_CSTR szName = NULL );

Using the child position can save you some lines of code in navigating the document when you are using both the main position and child position and do not want to do an extra IntoElem and OutOfElem to go between them. But keep in mind that this is an optional means of navigation. See Navigating and Getting Information From a Document and Navigating Levels in CMarkup to learn about the CMarkup current position construct.

If there is a main position and no current child position, FindChildElem() locates the first child element under the main position and makes it the child position. If there is a child element, it moves to the next child element. If there is no child element or no next child element, it returns false and leaves the child position where it was.

<TESTDOC>
  <ITEM>one</ITEM>
  <ITEM>two</ITEM>
</TESTDOC>
xml.ResetPos(); // no current position
xml.FindElem(); // main is TESTDOC, no child position
xml.FindChildElem(); // main is TESTDOC, child is first ITEM
xml.FindChildElem(); // main is TESTDOC, child is second ITEM

If there is no current position at all (such as after ResetPos), you can call FindChildElem() to find the first child of the root element (this is shorthand because you can skip the call to FindElem).

xml.ResetPos();
xml.FindChildElem(); // child position is first ITEM

The FindChildElem method has an optional argument which allows you to specify a pathname. The simplest use of the pathname is to pass the tag name. Calling FindChildElem("ITEM") will only succeed if a sibling ITEM element is found after the child position. If there is no main position, it will look for a matching child under the first main level element found.

See the FindElem method documentation for full details of how the pathname argument works. However, note that for the FindChildElem method the element that is found becomes the current child position, not the main position.