XmlElement Class Reference

Used to build a tree of elements representing an XML document. More...

List of all members.

Classes
struct	XmlAttributeNode
Public Member Functions
	XmlElement (const String &tagName) throw ()
	Creates an XmlElement with this tag name.
	XmlElement (const XmlElement &other) throw ()
	Creates a (deep) copy of another element.
XmlElement &	operator= (const XmlElement &other) throw ()
	Creates a (deep) copy of another element.
	~XmlElement () throw ()
	Deleting an XmlElement will also delete all its child elements.
bool	isEquivalentTo (const XmlElement *other, bool ignoreOrderOfAttributes) const throw ()
	Compares two XmlElements to see if they contain the same text and attiributes.
const String	createDocument (const String &dtdToUse, bool allOnOneLine=false, bool includeXmlHeader=true, const String &encodingType="UTF-8", int lineWrapLength=60) const
	Returns an XML text document that represents this element.
void	writeToStream (OutputStream &output, const String &dtdToUse, bool allOnOneLine=false, bool includeXmlHeader=true, const String &encodingType="UTF-8", int lineWrapLength=60) const
	Writes the document to a stream as UTF-8.
bool	writeToFile (const File &destinationFile, const String &dtdToUse, const String &encodingType="UTF-8", int lineWrapLength=60) const
	Writes the element to a file as an XML document.
const String &	getTagName () const throw ()
	Returns this element's tag type name.
bool	hasTagName (const String &possibleTagName) const throw ()
	Tests whether this element has a particular tag name.
int	getNumAttributes () const throw ()
	Returns the number of XML attributes this element contains.
const String &	getAttributeName (int attributeIndex) const throw ()
	Returns the name of one of the elements attributes.
const String &	getAttributeValue (int attributeIndex) const throw ()
	Returns the value of one of the elements attributes.
bool	hasAttribute (const String &attributeName) const throw ()
	Checks whether the element contains an attribute with a certain name.
const String &	getStringAttribute (const String &attributeName) const throw ()
	Returns the value of a named attribute.
const String	getStringAttribute (const String &attributeName, const String &defaultReturnValue) const
	Returns the value of a named attribute.
bool	compareAttribute (const String &attributeName, const String &stringToCompareAgainst, bool ignoreCase=false) const throw ()
	Compares the value of a named attribute with a value passed-in.
int	getIntAttribute (const String &attributeName, int defaultReturnValue=0) const
	Returns the value of a named attribute as an integer.
double	getDoubleAttribute (const String &attributeName, double defaultReturnValue=0.0) const
	Returns the value of a named attribute as floating-point.
bool	getBoolAttribute (const String &attributeName, bool defaultReturnValue=false) const
	Returns the value of a named attribute as a boolean.
void	setAttribute (const String &attributeName, const String &newValue)
	Adds a named attribute to the element.
void	setAttribute (const String &attributeName, int newValue)
	Adds a named attribute to the element, setting it to an integer value.
void	setAttribute (const String &attributeName, double newValue)
	Adds a named attribute to the element, setting it to a floating-point value.
void	removeAttribute (const String &attributeName) throw ()
	Removes a named attribute from the element.
void	removeAllAttributes () throw ()
	Removes all attributes from this element.
XmlElement *	getFirstChildElement () const throw ()
	Returns the first of this element's sub-elements.
XmlElement *	getNextElement () const throw ()
	Returns the next of this element's siblings.
XmlElement *	getNextElementWithTagName (const String &requiredTagName) const
	Returns the next of this element's siblings which has the specified tag name.
int	getNumChildElements () const throw ()
	Returns the number of sub-elements in this element.
XmlElement *	getChildElement (int index) const throw ()
	Returns the sub-element at a certain index.
XmlElement *	getChildByName (const String &tagNameToLookFor) const throw ()
	Returns the first sub-element with a given tag-name.
void	addChildElement (XmlElement *const newChildElement) throw ()
	Appends an element to this element's list of children.
void	insertChildElement (XmlElement *newChildNode, int indexToInsertAt) throw ()
	Inserts an element into this element's list of children.
XmlElement *	createNewChildElement (const String &tagName)
	Creates a new element with the given name and returns it, after adding it as a child element.
bool	replaceChildElement (XmlElement *currentChildElement, XmlElement *newChildNode) throw ()
	Replaces one of this element's children with another node.
void	removeChildElement (XmlElement *childToRemove, bool shouldDeleteTheChild) throw ()
	Removes a child element.
void	deleteAllChildElements () throw ()
	Deletes all the child elements in the element.
void	deleteAllChildElementsWithTagName (const String &tagName) throw ()
	Deletes all the child elements with a given tag name.
bool	containsChildElement (const XmlElement *const possibleChild) const throw ()
	Returns true if the given element is a child of this one.
XmlElement *	findParentElementOf (const XmlElement *elementToLookFor) throw ()
	Recursively searches all sub-elements to find one that contains the specified child element.
template<class ElementComparator >
void	sortChildElements (ElementComparator &comparator, const bool retainOrderOfEquivalentItems=false) throw ()
	Sorts the child elements using a comparator.
bool	isTextElement () const throw ()
	Returns true if this element is a section of text.
const String	getText () const throw ()
	Returns the text for a text element.
void	setText (const String &newText) throw ()
	Sets the text in a text element.
const String	getAllSubText () const throw ()
	Returns all the text from this element's child nodes.
const String	getChildElementAllSubText (const String &childTagName, const String &defaultReturnValue) const throw ()
	Returns all the sub-text of a named child element.
void	addTextElement (const String &text) throw ()
	Appends a section of text to this element.
void	deleteAllTextElements () throw ()
	Removes all the text elements from this element.
Static Public Member Functions
static XmlElement *	createTextElement (const String &text) throw ()
	Creates a text element that can be added to a parent element.

---

Detailed Description

Used to build a tree of elements representing an XML document.

An XML document can be parsed into a tree of XmlElements, each of which represents an XML tag structure, and which may itself contain other nested elements.

An XmlElement can also be converted back into a text document, and has lots of useful methods for manipulating its attributes and sub-elements, so XmlElements can actually be used as a handy general-purpose data structure.

Here's an example of parsing some elements:

    // check we're looking at the right kind of document..
    if (myElement->hasTagName ("ANIMALS"))
    {
        // now we'll iterate its sub-elements looking for 'giraffe' elements..
        forEachXmlChildElement (*myElement, e)
        {
            if (e->hasTagName ("GIRAFFE"))
            {
                // found a giraffe, so use some of its attributes..

                String giraffeName  = e->getStringAttribute ("name");
                int giraffeAge      = e->getIntAttribute ("age");
                bool isFriendly     = e->getBoolAttribute ("friendly");
            }
        }
    }

And here's an example of how to create an XML document from scratch:

    // create an outer node called "ANIMALS"
    XmlElement animalsList ("ANIMALS");

    for (int i = 0; i < numAnimals; ++i)
    {
        // create an inner element..
        XmlElement* giraffe = new XmlElement ("GIRAFFE");

        giraffe->setAttribute ("name", "nigel");
        giraffe->setAttribute ("age", 10);
        giraffe->setAttribute ("friendly", true);

        // ..and add our new element to the parent node
        animalsList.addChildElement (giraffe);
    }

    // now we can turn the whole thing into a text document..
    String myXmlDoc = animalsList.createDocument (String::empty);

See also:

XmlDocument

---

Constructor & Destructor Documentation

XmlElement::XmlElement

(

const String &

tagName

)

throw () [explicit]

Creates an XmlElement with this tag name.

XmlElement::XmlElement

(

const XmlElement &

other

)

throw ()

Creates a (deep) copy of another element.

XmlElement::~XmlElement

(

)

throw ()

Deleting an XmlElement will also delete all its child elements.

---

Member Function Documentation

XmlElement& XmlElement::operator=

(

const XmlElement &

other

)

throw ()

Creates a (deep) copy of another element.

bool XmlElement::isEquivalentTo	(	const XmlElement *	other,
		bool	ignoreOrderOfAttributes
	)			const throw ()

Compares two XmlElements to see if they contain the same text and attiributes.

The elements are only considered equivalent if they contain the same attiributes with the same values, and have the same sub-nodes.

Parameters:

	other	the other element to compare to
	ignoreOrderOfAttributes	if true, this means that two elements with the same attributes in a different order will be considered the same; if false, the attributes must be in the same order as well

const String XmlElement::createDocument	(	const String &	dtdToUse,
		bool	allOnOneLine = false,
		bool	includeXmlHeader = true,
		const String &	encodingType = "UTF-8",
		int	lineWrapLength = 60
	)			const

Returns an XML text document that represents this element.

The string returned can be parsed to recreate the same XmlElement that was used to create it.

Parameters:

	dtdToUse	the DTD to add to the document
	allOnOneLine	if true, this means that the document will not contain any linefeeds, so it'll be smaller but not very easy to read.
	includeXmlHeader	whether to add the "<?xml version..etc" line at the start of the document
	encodingType	the character encoding format string to put into the xml header
	lineWrapLength	the line length that will be used before items get placed on a new line. This isn't an absolute maximum length, it just determines how lists of attributes get broken up

See also:

writeToStream, writeToFile

void XmlElement::writeToStream	(	OutputStream &	output,
		const String &	dtdToUse,
		bool	allOnOneLine = false,
		bool	includeXmlHeader = true,
		const String &	encodingType = "UTF-8",
		int	lineWrapLength = 60
	)			const

Writes the document to a stream as UTF-8.

Parameters:

	output	the stream to write to
	dtdToUse	the DTD to add to the document
	allOnOneLine	if true, this means that the document will not contain any linefeeds, so it'll be smaller but not very easy to read.
	includeXmlHeader	whether to add the "<?xml version..etc" line at the start of the document
	encodingType	the character encoding format string to put into the xml header
	lineWrapLength	the line length that will be used before items get placed on a new line. This isn't an absolute maximum length, it just determines how lists of attributes get broken up

See also:

writeToFile, createDocument

bool XmlElement::writeToFile	(	const File &	destinationFile,
		const String &	dtdToUse,
		const String &	encodingType = "UTF-8",
		int	lineWrapLength = 60
	)			const

Writes the element to a file as an XML document.

To improve safety in case something goes wrong while writing the file, this will actually write the document to a new temporary file in the same directory as the destination file, and if this succeeds, it will rename this new file as the destination file (overwriting any existing file that was there).

Parameters:

	destinationFile	the file to write to. If this already exists, it will be overwritten.
	dtdToUse	the DTD to add to the document
	encodingType	the character encoding format string to put into the xml header
	lineWrapLength	the line length that will be used before items get placed on a new line. This isn't an absolute maximum length, it just determines how lists of attributes get broken up

Returns:

true if the file is written successfully; false if something goes wrong in the process

See also:

createDocument

const String& XmlElement::getTagName

(

)

const throw ()

Returns this element's tag type name.

E.g. for an element such as <MOOSE legs="4" antlers="2">, this would return "MOOSE".

See also:

hasTagName

bool XmlElement::hasTagName

(

const String &

possibleTagName

)

const throw ()

Tests whether this element has a particular tag name.

Parameters:

possibleTagName

the tag name you're comparing it with

See also:

getTagName

int XmlElement::getNumAttributes

(

)

const throw ()

Returns the number of XML attributes this element contains.

E.g. for an element such as <MOOSE legs="4" antlers="2">, this would return 2.

const String& XmlElement::getAttributeName

(

int

attributeIndex

)

const throw ()

Returns the name of one of the elements attributes.

E.g. for an element such as <MOOSE legs="4" antlers="2">, then getAttributeName(1) would return "antlers".

See also:

getAttributeValue, getStringAttribute

const String& XmlElement::getAttributeValue

(

int

attributeIndex

)

const throw ()

Returns the value of one of the elements attributes.

E.g. for an element such as <MOOSE legs="4" antlers="2">, then getAttributeName(1) would return "2".

See also:

getAttributeName, getStringAttribute

bool XmlElement::hasAttribute

(

const String &

attributeName

)

const throw ()

Checks whether the element contains an attribute with a certain name.

const String& XmlElement::getStringAttribute

(

const String &

attributeName

)

const throw ()

Returns the value of a named attribute.

Parameters:

attributeName

the name of the attribute to look up

const String XmlElement::getStringAttribute	(	const String &	attributeName,
		const String &	defaultReturnValue
	)			const

Returns the value of a named attribute.

Parameters:

	attributeName	the name of the attribute to look up
	defaultReturnValue	a value to return if the element doesn't have an attribute with this name

bool XmlElement::compareAttribute	(	const String &	attributeName,
		const String &	stringToCompareAgainst,
		bool	ignoreCase = false
	)			const throw ()

Compares the value of a named attribute with a value passed-in.

Parameters:

	attributeName	the name of the attribute to look up
	stringToCompareAgainst	the value to compare it with
	ignoreCase	whether the comparison should be case-insensitive

Returns:

true if the value of the attribute is the same as the string passed-in; false if it's different (or if no such attribute exists)

int XmlElement::getIntAttribute	(	const String &	attributeName,
		int	defaultReturnValue = 0
	)			const

Returns the value of a named attribute as an integer.

This will try to find the attribute and convert it to an integer (using the String::getIntValue() method).

Parameters:

	attributeName	the name of the attribute to look up
	defaultReturnValue	a value to return if the element doesn't have an attribute with this name

See also:

setAttribute

double XmlElement::getDoubleAttribute	(	const String &	attributeName,
		double	defaultReturnValue = 0.0
	)			const

Returns the value of a named attribute as floating-point.

This will try to find the attribute and convert it to an integer (using the String::getDoubleValue() method).

Parameters:

	attributeName	the name of the attribute to look up
	defaultReturnValue	a value to return if the element doesn't have an attribute with this name

See also:

setAttribute

bool XmlElement::getBoolAttribute	(	const String &	attributeName,
		bool	defaultReturnValue = false
	)			const

Returns the value of a named attribute as a boolean.

This will try to find the attribute and interpret it as a boolean. To do this, it'll return true if the value is "1", "true", "y", etc, or false for other values.

Parameters:

	attributeName	the name of the attribute to look up
	defaultReturnValue	a value to return if the element doesn't have an attribute with this name

void XmlElement::setAttribute	(	const String &	attributeName,
		const String &	newValue
	)

Adds a named attribute to the element.

If the element already contains an attribute with this name, it's value will be updated to the new value. If there's no such attribute yet, a new one will be added.

Note that there are other setAttribute() methods that take integers, doubles, etc. to make it easy to store numbers.

Parameters:

	attributeName	the name of the attribute to set
	newValue	the value to set it to

See also:

removeAttribute

void XmlElement::setAttribute	(	const String &	attributeName,
		int	newValue
	)

Adds a named attribute to the element, setting it to an integer value.

If the element already contains an attribute with this name, it's value will be updated to the new value. If there's no such attribute yet, a new one will be added.

Note that there are other setAttribute() methods that take integers, doubles, etc. to make it easy to store numbers.

Parameters:

	attributeName	the name of the attribute to set
	newValue	the value to set it to

void XmlElement::setAttribute	(	const String &	attributeName,
		double	newValue
	)

Adds a named attribute to the element, setting it to a floating-point value.

If the element already contains an attribute with this name, it's value will be updated to the new value. If there's no such attribute yet, a new one will be added.

Note that there are other setAttribute() methods that take integers, doubles, etc. to make it easy to store numbers.

Parameters:

	attributeName	the name of the attribute to set
	newValue	the value to set it to

void XmlElement::removeAttribute

(

const String &

attributeName

)

throw ()

Removes a named attribute from the element.

Parameters:

attributeName

the name of the attribute to remove

See also:

removeAllAttributes

void XmlElement::removeAllAttributes

(

)

throw ()

Removes all attributes from this element.

XmlElement* XmlElement::getFirstChildElement

(

)

const throw ()

Returns the first of this element's sub-elements.

see getNextElement() for an example of how to iterate the sub-elements.

See also:

forEachXmlChildElement

XmlElement* XmlElement::getNextElement

(

)

const throw ()

Returns the next of this element's siblings.

This can be used for iterating an element's sub-elements, e.g.

        XmlElement* child = myXmlDocument->getFirstChildElement();

        while (child != 0)
        {
            ...do stuff with this child..

            child = child->getNextElement();
        }

Note that when iterating the child elements, some of them might be text elements as well as XML tags - use isTextElement() to work this out.

Also, it's much easier and neater to use this method indirectly via the forEachXmlChildElement macro.

Returns:

the sibling element that follows this one, or zero if this is the last element in its parent

See also:

getNextElement, isTextElement, forEachXmlChildElement

XmlElement* XmlElement::getNextElementWithTagName

(

const String &

requiredTagName

)

const

Returns the next of this element's siblings which has the specified tag name.

This is like getNextElement(), but will scan through the list until it finds an element with the given tag name.

See also:

getNextElement, forEachXmlChildElementWithTagName

int XmlElement::getNumChildElements

(

)

const throw ()

Returns the number of sub-elements in this element.

See also:

getChildElement

XmlElement* XmlElement::getChildElement

(

int

index

)

const throw ()

Returns the sub-element at a certain index.

It's not very efficient to iterate the sub-elements by index - see getNextElement() for an example of how best to iterate.

Returns:

the n'th child of this element, or 0 if the index is out-of-range

See also:

getNextElement, isTextElement, getChildByName

XmlElement* XmlElement::getChildByName

(

const String &

tagNameToLookFor

)

const throw ()

Returns the first sub-element with a given tag-name.

Parameters:

tagNameToLookFor

the tag name of the element you want to find

Returns:

the first element with this tag name, or 0 if none is found

See also:

getNextElement, isTextElement, getChildElement

void XmlElement::addChildElement

(

XmlElement *const

newChildElement

)

throw ()

Appends an element to this element's list of children.

Child elements are deleted automatically when their parent is deleted, so make sure the object that you pass in will not be deleted by anything else, and make sure it's not already the child of another element.

See also:

getFirstChildElement, getNextElement, getNumChildElements, getChildElement, removeChildElement

void XmlElement::insertChildElement	(	XmlElement *	newChildNode,
		int	indexToInsertAt
	)			throw ()

Inserts an element into this element's list of children.

Child elements are deleted automatically when their parent is deleted, so make sure the object that you pass in will not be deleted by anything else, and make sure it's not already the child of another element.

Parameters:

	newChildNode	the element to add
	indexToInsertAt	the index at which to insert the new element - if this is below zero, it will be added to the end of the list

See also:

addChildElement, insertChildElement

XmlElement* XmlElement::createNewChildElement

(

const String &

tagName

)

Creates a new element with the given name and returns it, after adding it as a child element.

This is a handy method that means that instead of writing this:

        XmlElement* newElement = new XmlElement ("foobar");
        myParentElement->addChildElement (newElement);

..you could just write this:

        XmlElement* newElement = myParentElement->createNewChildElement ("foobar");

bool XmlElement::replaceChildElement	(	XmlElement *	currentChildElement,
		XmlElement *	newChildNode
	)			throw ()

Replaces one of this element's children with another node.

If the current element passed-in isn't actually a child of this element, this will return false and the new one won't be added. Otherwise, the existing element will be deleted, replaced with the new one, and it will return true.

void XmlElement::removeChildElement	(	XmlElement *	childToRemove,
		bool	shouldDeleteTheChild
	)			throw ()

Removes a child element.

Parameters:

	childToRemove	the child to look for and remove
	shouldDeleteTheChild	if true, the child will be deleted, if false it'll just remove it

void XmlElement::deleteAllChildElements

(

)

throw ()

Deletes all the child elements in the element.

See also:

removeChildElement, deleteAllChildElementsWithTagName

void XmlElement::deleteAllChildElementsWithTagName

(

const String &

tagName

)

throw ()

Deletes all the child elements with a given tag name.

See also:

removeChildElement

bool XmlElement::containsChildElement

(

const XmlElement *const

possibleChild

)

const throw ()

Returns true if the given element is a child of this one.

XmlElement* XmlElement::findParentElementOf

(

const XmlElement *

elementToLookFor

)

throw ()

Recursively searches all sub-elements to find one that contains the specified child element.

template<class ElementComparator >

void XmlElement::sortChildElements	(	ElementComparator &	comparator,
		const bool	retainOrderOfEquivalentItems = false
	)			throw ()

Sorts the child elements using a comparator.

This will use a comparator object to sort the elements into order. The object passed must have a method of the form:

        int compareElements (const XmlElement* first, const XmlElement* second);

..and this method must return:

• a value of < 0 if the first comes before the second
• a value of 0 if the two objects are equivalent
• a value of > 0 if the second comes before the first

To improve performance, the compareElements() method can be declared as static or const.

Parameters:

	comparator	the comparator to use for comparing elements.
	retainOrderOfEquivalentItems	if this is true, then items which the comparator says are equivalent will be kept in the order in which they currently appear in the array. This is slower to perform, but may be important in some cases. If it's false, a faster algorithm is used, but equivalent elements may be rearranged.

bool XmlElement::isTextElement

(

)

const throw ()

Returns true if this element is a section of text.

Elements can either be an XML tag element or a secton of text, so this is used to find out what kind of element this one is.

See also:

getAllText, addTextElement, deleteAllTextElements

const String XmlElement::getText

(

)

const throw ()

Returns the text for a text element.

Note that if you have an element like this:

 <xyz>hello</xyz>

then calling getText on the "xyz" element won't return "hello", because that is actually stored in a special text sub-element inside the xyz element. To get the "hello" string, you could either call getText on the (unnamed) sub-element, or use getAllSubText() to do this automatically.

See also:

isTextElement, getAllSubText, getChildElementAllSubText

void XmlElement::setText

(

const String &

newText

)

throw ()

Sets the text in a text element.

Note that this is only a valid call if this element is a text element. If it's not, then no action will be performed.

const String XmlElement::getAllSubText

(

)

const throw ()

Returns all the text from this element's child nodes.

This iterates all the child elements and when it finds text elements, it concatenates their text into a big string which it returns.

E.g.

 <xyz> hello <x></x> there </xyz>

if you called getAllSubText on the "xyz" element, it'd return "hello there".

See also:

isTextElement, getChildElementAllSubText, getText, addTextElement

const String XmlElement::getChildElementAllSubText	(	const String &	childTagName,
		const String &	defaultReturnValue
	)			const throw ()

Returns all the sub-text of a named child element.

If there is a child element with the given tag name, this will return all of its sub-text (by calling getAllSubText() on it). If there is no such child element, this will return the default string passed-in.

See also:

getAllSubText

void XmlElement::addTextElement

(

const String &

text

)

throw ()

Appends a section of text to this element.

See also:

isTextElement, getText, getAllSubText

void XmlElement::deleteAllTextElements

(

)

throw ()

Removes all the text elements from this element.

See also:

isTextElement, getText, getAllSubText, addTextElement

static XmlElement* XmlElement::createTextElement

(

const String &

text

)

throw () [static]

Creates a text element that can be added to a parent element.

---

The documentation for this class was generated from the following file:

• juce_XmlElement.h