juce::XmlElement Class Reference

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

#include <juce_XmlElement.h>

Collaboration diagram for juce::XmlElement:

Classes
struct	XmlAttributeNode

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

Static Public Member Functions
static XmlElement *	createTextElement (const String &text)
	Creates a text element that can be added to a parent element. More...
static bool	isValidXmlName (StringRef possibleName) noexcept
	Checks if a given string is a valid XML name. More...

Private Member Functions
	XmlElement (int) noexcept
	XmlElement (const wchar_t *)=delete
void	copyChildrenAndAttributesFrom (const XmlElement &)
XmlAttributeNode *	getAttribute (StringRef) const noexcept
void	getChildElementsAsArray (XmlElement **) const noexcept
void	reorderChildElements (XmlElement **, int) noexcept
void	writeElementAsText (OutputStream &, int indentationLevel, int lineWrapLength) const

Private Attributes
LinkedListPointer< XmlAttributeNode >	attributes
LinkedListPointer< XmlElement >	firstChildElement
LinkedListPointer< XmlElement >	nextListItem
String	tagName

Friends
class	LinkedListPointer< XmlAttributeNode >
class	LinkedListPointer< XmlElement >
class	LinkedListPointer< XmlElement >::Appender
class	NamedValueSet
class	XmlDocument

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());

See also

XmlDocument

{Core}

Constructor & Destructor Documentation

XmlElement() [1/9]

juce::XmlElement::XmlElement ( const String &  tagName )

explicit

Creates an XmlElement with this tag name.

XmlElement() [2/9]

juce::XmlElement::XmlElement ( const char *  tagName )

explicit

Creates an XmlElement with this tag name.

XmlElement() [3/9]

juce::XmlElement::XmlElement ( const Identifier &  tagName )

explicit

Creates an XmlElement with this tag name.

XmlElement() [4/9]

juce::XmlElement::XmlElement ( StringRef  tagName )

explicit

Creates an XmlElement with this tag name.

XmlElement() [5/9]

juce::XmlElement::XmlElement	(	String::CharPointerType	tagNameBegin,
		String::CharPointerType	tagNameEnd
	)

Creates an XmlElement with this tag name.

XmlElement() [6/9]

juce::XmlElement::XmlElement

(

const XmlElement &

)

Creates a (deep) copy of another element.

XmlElement() [7/9]

juce::XmlElement::XmlElement ( XmlElement &&  )

noexcept

Move constructor.

~XmlElement()

juce::XmlElement::~XmlElement ( )

noexcept

Deleting an XmlElement will also delete all of its child elements.

XmlElement() [8/9]

juce::XmlElement::XmlElement ( int  )

privatenoexcept

XmlElement() [9/9]

juce::XmlElement::XmlElement ( const wchar_t *  )

privatedelete

Member Function Documentation

addChildElement()

void juce::XmlElement::addChildElement ( XmlElement *  newChildElement )

noexcept

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.

Note that due to the XmlElement using a singly-linked-list, prependChildElement() is an O(1) operation, but addChildElement() is an O(N) operation - so if you're adding large number of elements, you may prefer to do so in reverse order!

See also

getFirstChildElement, getNextElement, getNumChildElements, getChildElement, removeChildElement

addTextElement()

void juce::XmlElement::addTextElement

(

const String &

text

)

Appends a section of text to this element.

See also

isTextElement, getText, getAllSubText

compareAttribute()

bool juce::XmlElement::compareAttribute ( StringRef  attributeName, StringRef  stringToCompareAgainst, bool  ignoreCase = false  ) const

noexcept

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)

containsChildElement()

bool juce::XmlElement::containsChildElement ( const XmlElement *  possibleChild ) const

noexcept

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

copyChildrenAndAttributesFrom()

void juce::XmlElement::copyChildrenAndAttributesFrom ( const XmlElement &  )

private

createDocument()

String juce::XmlElement::createDocument	(	StringRef	dtdToUse,
		bool	allOnOneLine = false,
		bool	includeXmlHeader = true,
		StringRef	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

createNewChildElement()

XmlElement* juce::XmlElement::createNewChildElement

(

StringRef

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");

createTextElement()

static XmlElement* juce::XmlElement::createTextElement ( const String &  text )

static

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

deleteAllChildElements()

void juce::XmlElement::deleteAllChildElements ( )

noexcept

Deletes all the child elements in the element.

See also

removeChildElement, deleteAllChildElementsWithTagName

deleteAllChildElementsWithTagName()

void juce::XmlElement::deleteAllChildElementsWithTagName ( StringRef  tagName )

noexcept

Deletes all the child elements with a given tag name.

See also

removeChildElement

deleteAllTextElements()

void juce::XmlElement::deleteAllTextElements ( )

noexcept

Removes all the text elements from this element.

See also

isTextElement, getText, getAllSubText, addTextElement

findParentElementOf()

XmlElement* juce::XmlElement::findParentElementOf ( const XmlElement *  childToSearchFor )

noexcept

Recursively searches all sub-elements of this one, looking for an element which is the direct parent of the specified element.

Because elements don't store a pointer to their parent, if you have one and need to find its parent, the only way to do so is to exhaustively search the whole tree for it.

If the given child is found somewhere in this element's hierarchy, then this method will return its parent. If not, it will return nullptr.

getAllSubText()

String juce::XmlElement::getAllSubText

(

)

const

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>there</x> world</xyz>

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

Note that leading and trailing whitespace will be included in the string - to remove if, just call String::trim() on the result.

See also

isTextElement, getChildElementAllSubText, getText, addTextElement

getAttribute()

XmlAttributeNode* juce::XmlElement::getAttribute ( StringRef  ) const

privatenoexcept

getAttributeName()

const String& juce::XmlElement::getAttributeName ( int  attributeIndex ) const

noexcept

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

getAttributeValue()

const String& juce::XmlElement::getAttributeValue ( int  attributeIndex ) const

noexcept

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

getBoolAttribute()

bool juce::XmlElement::getBoolAttribute	(	StringRef	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

getChildByAttribute()

XmlElement* juce::XmlElement::getChildByAttribute ( StringRef  attributeName, StringRef  attributeValue  ) const

noexcept

Returns the first sub-element which has an attribute that matches the given value.

Parameters

attributeName	the name of the attribute to check
attributeValue	the target value of the attribute

Returns

the first element with this attribute value, or nullptr if none is found

See also

getChildByName

getChildByName()

XmlElement* juce::XmlElement::getChildByName ( StringRef  tagNameToLookFor ) const

noexcept

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 nullptr if none is found

See also

getNextElement, isTextElement, getChildElement, getChildByAttribute

getChildElement()

XmlElement* juce::XmlElement::getChildElement ( int  index ) const

noexcept

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 nullptr if the index is out-of-range

See also

getNextElement, isTextElement, getChildByName

getChildElementAllSubText()

String juce::XmlElement::getChildElementAllSubText	(	StringRef	childTagName,
		const String &	defaultReturnValue
	)		const

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

getChildElementsAsArray()

void juce::XmlElement::getChildElementsAsArray ( XmlElement **  ) const

privatenoexcept

getDoubleAttribute()

double juce::XmlElement::getDoubleAttribute	(	StringRef	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 a double (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

getFirstChildElement()

XmlElement* juce::XmlElement::getFirstChildElement ( ) const

inlinenoexcept

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

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

See also

forEachXmlChildElement

getIntAttribute()

int juce::XmlElement::getIntAttribute	(	StringRef	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

getNamespace()

String juce::XmlElement::getNamespace

(

)

const

Returns the namespace portion of the tag-name, or an empty string if none is specified.

getNextElement()

XmlElement* juce::XmlElement::getNextElement ( ) const

inlinenoexcept

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 != nullptr)
{
    ...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 a nullptr if this is the last element in its parent

See also

getNextElement, isTextElement, forEachXmlChildElement

getNextElementWithTagName()

XmlElement* juce::XmlElement::getNextElementWithTagName

(

StringRef

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

getNumAttributes()

int juce::XmlElement::getNumAttributes ( ) const

noexcept

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.

getNumChildElements()

int juce::XmlElement::getNumChildElements ( ) const

noexcept

Returns the number of sub-elements in this element.

See also

getChildElement

getStringAttribute() [1/2]

const String& juce::XmlElement::getStringAttribute ( StringRef  attributeName ) const

noexcept

Returns the value of a named attribute.

Parameters

attributeName

the name of the attribute to look up

getStringAttribute() [2/2]

String juce::XmlElement::getStringAttribute	(	StringRef	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

getTagName()

const String& juce::XmlElement::getTagName ( ) const

inlinenoexcept

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

getTagNameWithoutNamespace()

String juce::XmlElement::getTagNameWithoutNamespace

(

)

const

Returns the part of the tag-name that follows any namespace declaration.

getText()

const String& juce::XmlElement::getText ( ) const

noexcept

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.

Note that leading and trailing whitespace will be included in the string - to remove if, just call String::trim() on the result.

See also

isTextElement, getAllSubText, getChildElementAllSubText

hasAttribute()

bool juce::XmlElement::hasAttribute ( StringRef  attributeName ) const

noexcept

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

hasTagName()

bool juce::XmlElement::hasTagName ( StringRef  possibleTagName ) const

noexcept

Tests whether this element has a particular tag name.

Parameters

possibleTagName

the tag name you're comparing it with

See also

getTagName

hasTagNameIgnoringNamespace()

bool juce::XmlElement::hasTagNameIgnoringNamespace

(

StringRef

possibleTagName

)

const

Tests whether this element has a particular tag name, ignoring any XML namespace prefix.

So a test for e.g. "xyz" will return true for "xyz" and also "foo:xyz", "bar::xyz", etc.

See also

getTagName

insertChildElement()

void juce::XmlElement::insertChildElement ( XmlElement *  newChildElement, int  indexToInsertAt  )

noexcept

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

newChildElement	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

isEquivalentTo()

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

noexcept

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

The elements are only considered equivalent if they contain the same attributes 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

isTextElement()

bool juce::XmlElement::isTextElement ( ) const

noexcept

Returns true if this element is a section of text.

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

See also

getAllText, addTextElement, deleteAllTextElements

isValidXmlName()

static bool juce::XmlElement::isValidXmlName ( StringRef  possibleName )

staticnoexcept

Checks if a given string is a valid XML name.

operator=() [1/2]

XmlElement& juce::XmlElement::operator=

(

const XmlElement &

)

Creates a (deep) copy of another element.

operator=() [2/2]

XmlElement& juce::XmlElement::operator= ( XmlElement &&  )

noexcept

Move assignment operator.

prependChildElement()

void juce::XmlElement::prependChildElement ( XmlElement *  newChildElement )

noexcept

Inserts an element at the beginning of 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.

Note that due to the XmlElement using a singly-linked-list, prependChildElement() is an O(1) operation, but addChildElement() is an O(N) operation - so if you're adding large number of elements, you may prefer to do so in reverse order!

See also

addChildElement, insertChildElement

removeAllAttributes()

void juce::XmlElement::removeAllAttributes ( )

noexcept

Removes all attributes from this element.

removeAttribute()

void juce::XmlElement::removeAttribute ( const Identifier &  attributeName )

noexcept

Removes a named attribute from the element.

Parameters

attributeName

the name of the attribute to remove

See also

removeAllAttributes

removeChildElement()

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

noexcept

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

reorderChildElements()

void juce::XmlElement::reorderChildElements ( XmlElement **  , int    )

privatenoexcept

replaceChildElement()

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

noexcept

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.

setAttribute() [1/3]

void juce::XmlElement::setAttribute	(	const Identifier &	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

setAttribute() [2/3]

void juce::XmlElement::setAttribute	(	const Identifier &	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

setAttribute() [3/3]

void juce::XmlElement::setAttribute	(	const Identifier &	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

setTagName()

void juce::XmlElement::setTagName

(

StringRef

newTagName

)

Changes this elements tag name.

See also

getTagName

setText()

void juce::XmlElement::setText

(

const String &

newText

)

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. If you're trying to add text inside a normal element, you probably want to use addTextElement() instead.

sortChildElements()

template<class ElementComparator >

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

inline

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.

References juce::sortArray().

writeElementAsText()

void juce::XmlElement::writeElementAsText ( OutputStream &  , int  indentationLevel, int  lineWrapLength  ) const

private

writeToFile()

bool juce::XmlElement::writeToFile	(	const File &	destinationFile,
		StringRef	dtdToUse,
		StringRef	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

writeToStream()

void juce::XmlElement::writeToStream	(	OutputStream &	output,
		StringRef	dtdToUse,
		bool	allOnOneLine = false,
		bool	includeXmlHeader = true,
		StringRef	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

Friends And Related Function Documentation

LinkedListPointer< XmlAttributeNode >

friend class LinkedListPointer< XmlAttributeNode >

friend

LinkedListPointer< XmlElement >

friend class LinkedListPointer< XmlElement >

friend

LinkedListPointer< XmlElement >::Appender

friend class LinkedListPointer< XmlElement >::Appender

friend

NamedValueSet

friend class NamedValueSet

friend

XmlDocument

friend class XmlDocument

friend

Member Data Documentation

attributes

LinkedListPointer<XmlAttributeNode> juce::XmlElement::attributes

private

firstChildElement

LinkedListPointer<XmlElement> juce::XmlElement::firstChildElement

private

nextListItem

LinkedListPointer<XmlElement> juce::XmlElement::nextListItem

private

tagName

String juce::XmlElement::tagName

private

---

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

• juce_XmlElement.h