Loading...
Searching...
No Matches
juce::XmlElement Class Reference

## 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
for (auto* e : myElement->getChildIterator())
{
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");
}
}
}
juce::String
The JUCE String class!
Definition juce_String.h:67

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 textual XML
auto xmlString = animalsList.toString();
juce::XmlElement::XmlElement
XmlElement(const String &tagName)
Creates an XmlElement with this tag name.
juce::XmlElement::setAttribute
void setAttribute(const Identifier &attributeName, const String &newValue)
Adds a named attribute to the element.

See also
  parseXML, parseXMLIfTagMatches, XmlDocument

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

- juce_core/xml/juce_XmlElement.h

## Classes

struct | TextFormat
| A struct containing options for formatting the text when representing an XML element as a string. More...

## Public Member Functions

| XmlElement (const String &tagName)
| Creates an XmlElement with this tag name.
| XmlElement (const char *tagName)
| Creates an XmlElement with this tag name.
| XmlElement (const Identifier &tagName)
| Creates an XmlElement with this tag name.
| XmlElement (StringRef tagName)
| Creates an XmlElement with this tag name.
| XmlElement (String::CharPointerType tagNameBegin, String::CharPointerType tagNameEnd)
| Creates an XmlElement with this tag name.
| XmlElement (const XmlElement &)
| Creates a (deep) copy of another element.
XmlElement & | operator= (const XmlElement &)
| Creates a (deep) copy of another element.
XmlElement & | operator= (XmlElement &&) noexcept
| Move assignment operator.
| XmlElement (XmlElement &&) noexcept
| Move constructor.
| ~XmlElement () noexcept
| Deleting an XmlElement will also delete all of its child elements.
bool | isEquivalentTo (const XmlElement *other, bool ignoreOrderOfAttributes) const noexcept
| Compares two XmlElements to see if they contain the same text and attributes.
String | toString (const TextFormat &format={}) const
| Returns a text version of this XML element.
void | writeTo (OutputStream &output, const TextFormat &format={}) const
| Writes the document to a stream as UTF-8.
bool | writeTo (const File &destinationFile, const TextFormat &format={}) const
| Writes the document to a file as UTF-8.
const String & | getTagName () const noexcept
| Returns this element's tag type name.
String | getNamespace () const
| Returns the namespace portion of the tag-name, or an empty string if none is specified.
String | getTagNameWithoutNamespace () const
| Returns the part of the tag-name that follows any namespace declaration.
bool | hasTagName (StringRef possibleTagName) const noexcept
| Tests whether this element has a particular tag name.
bool | hasTagNameIgnoringNamespace (StringRef possibleTagName) const
| Tests whether this element has a particular tag name, ignoring any XML namespace prefix.
void | setTagName (StringRef newTagName)
| Changes this elements tag name.
int | getNumAttributes () const noexcept
| Returns the number of XML attributes this element contains.
const String & | getAttributeName (int attributeIndex) const noexcept
| Returns the name of one of the elements attributes.
const String & | getAttributeValue (int attributeIndex) const noexcept
| Returns the value of one of the elements attributes.
bool | hasAttribute (StringRef attributeName) const noexcept
| Checks whether the element contains an attribute with a certain name.
const String & | getStringAttribute (StringRef attributeName) const noexcept
| Returns the value of a named attribute.
String | getStringAttribute (StringRef attributeName, const String &defaultReturnValue) const
| Returns the value of a named attribute.
bool | compareAttribute (StringRef attributeName, StringRef stringToCompareAgainst, bool ignoreCase=false) const noexcept
| Compares the value of a named attribute with a value passed-in.
bool | compareAttribute (const XmlAttribute &attribute, bool ignoreCase=false) const noexcept
| Compares the value of a named attribute with a value passed-in.
int | getIntAttribute (StringRef attributeName, int defaultReturnValue=0) const
| Returns the value of a named attribute as an integer.
double | getDoubleAttribute (StringRef attributeName, double defaultReturnValue=0.0) const
| Returns the value of a named attribute as floating-point.
bool | getBoolAttribute (StringRef attributeName, bool defaultReturnValue=false) const
| Returns the value of a named attribute as a boolean.
void | setAttribute (const Identifier &attributeName, const String &newValue)
| Adds a named attribute to the element.
void | setAttribute (const Identifier &attributeName, int newValue)
| Adds a named attribute to the element, setting it to an integer value.
void | setAttribute (const Identifier &attributeName, double newValue)
| Adds a named attribute to the element, setting it to a floating-point value.
void | removeAttribute (const Identifier &attributeName) noexcept
| Removes a named attribute from the element.
void | removeAllAttributes () noexcept
| Removes all attributes from this element.
XmlElement * | getFirstChildElement () const noexcept
| Returns the first of this element's sub-elements.
XmlElement * | getNextElement () const noexcept
| Returns the next of this element's siblings.
XmlElement * | getNextElementWithTagName (StringRef requiredTagName) const
| Returns the next of this element's siblings which has the specified tag name.
int | getNumChildElements () const noexcept
| Returns the number of sub-elements in this element.
XmlElement * | getChildElement (int index) const noexcept
| Returns the sub-element at a certain index.
XmlElement * | getChildByName (StringRef tagNameToLookFor) const noexcept
| Returns the first sub-element with a given tag-name.
XmlElement * | getChildByAttribute (StringRef attributeName, StringRef attributeValue) const noexcept
| Returns the first sub-element which has an attribute that matches the given value.
void | addChildElement (XmlElement *newChildElement) noexcept
| Appends an element to this element's list of children.
void | insertChildElement (XmlElement *newChildElement, int indexToInsertAt) noexcept
| Inserts an element into this element's list of children.
void | prependChildElement (XmlElement *newChildElement) noexcept
| Inserts an element at the beginning of this element's list of children.
XmlElement * | createNewChildElement (StringRef 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) noexcept
| Replaces one of this element's children with another node.
void | removeChildElement (XmlElement *childToRemove, bool shouldDeleteTheChild) noexcept
| Removes a child element.
void | deleteAllChildElements () noexcept
| Deletes all the child elements in the element.
void | deleteAllChildElementsWithTagName (StringRef tagName) noexcept
| Deletes all the child elements with a given tag name.
bool | containsChildElement (const XmlElement *possibleChild) const noexcept
| Returns true if the given element is a child of this one.
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.
template<class ElementComparator>
void | sortChildElements (ElementComparator &comparator, bool retainOrderOfEquivalentItems=false)
| Sorts the child elements using a comparator.
bool | isTextElement () const noexcept
| Returns true if this element is a section of text.
const String & | getText () const noexcept
| Returns the text for a text element.
void | setText (const String &newText)
| Sets the text in a text element.
String | getAllSubText () const
| Returns all the text from this element's child nodes.
String | getChildElementAllSubText (StringRef childTagName, const String &defaultReturnValue) const
| Returns all the sub-text of a named child element.
void | addTextElement (const String &text)
| Appends a section of text to this element.
void | deleteAllTextElements () noexcept
| Removes all the text elements from this element.
Iterator< GetNextElement > | getChildIterator () const
| Allows iterating the children of an XmlElement using range-for syntax.
Iterator< GetNextElementWithTagName > | getChildWithTagNameIterator (StringRef name) const
| Allows iterating children of an XmlElement with a specific tag using range-for syntax.
AttributeIterator | getAttributeIterator () const
| Allows iterating all attributes of an XmlElement using range-for syntax.

## Static Public Member Functions

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

## Constructors and Destructors

## XmlElement() [1/7]

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

explicit

Creates an XmlElement with this tag name.

Referenced by addChildElement(), containsChildElement(), createNewChildElement(), createTextElement(), findParentElementOf(), getChildByAttribute(), getChildByName(), getChildElement(), getFirstChildElement(), getNextElement(), getNextElementWithTagName(), insertChildElement(), isEquivalentTo(), isValidXmlName(), LinkedListPointer< XmlAttributeNode >, LinkedListPointer< XmlElement >::Appender, operator=(), operator=(), prependChildElement(), removeChildElement(), replaceChildElement(), sortChildElements(), XmlElement(), XmlElement(), and ~XmlElement().

## XmlElement() [2/7]

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

explicit

Creates an XmlElement with this tag name.

## XmlElement() [3/7]

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

explicit

Creates an XmlElement with this tag name.

## XmlElement() [4/7]

juce::XmlElement::XmlElement | ( | StringRef | tagName | ) |

explicit

Creates an XmlElement with this tag name.

## XmlElement() [5/7]

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

Creates an XmlElement with this tag name.

## XmlElement() [6/7]

juce::XmlElement::XmlElement | ( | const XmlElement & |  | ) |

Creates a (deep) copy of another element.

References XmlElement().

## XmlElement() [7/7]

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

noexcept

Move constructor.

References XmlElement().

## ~XmlElement()

juce::XmlElement::~XmlElement | ( |  | ) |

noexcept

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

References XmlElement().

## Member Functions

## operator=() [1/2]

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

Creates a (deep) copy of another element.

References XmlElement().

## operator=() [2/2]

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

noexcept

Move assignment operator.

References XmlElement().

## 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

References isEquivalentTo(), and XmlElement().

Referenced by isEquivalentTo().

## toString()

String juce::XmlElement::toString | ( | const TextFormat & | format = {} | ) | const

Returns a text version of this XML element.

If your intention is to write the XML to a file or stream, it's probably more efficient to use writeTo() instead of creating an intermediate string.

See also
  writeTo

## writeTo() [1/2]

void juce::XmlElement::writeTo | ( | OutputStream & | output,
|  | const TextFormat & | format = {} ) const

Writes the document to a stream as UTF-8.

See also
  writeTo, toString

## writeTo() [2/2]

bool juce::XmlElement::writeTo | ( | const File & | destinationFile,
|  | const TextFormat & | format = {} ) const

Writes the document to a file as UTF-8.

See also
  writeTo, toString

## getTagName()

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

inline noexcept

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

## getNamespace()

String juce::XmlElement::getNamespace | ( |  | ) | const

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

## getTagNameWithoutNamespace()

String juce::XmlElement::getTagNameWithoutNamespace | ( |  | ) | const

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

## 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

## setTagName()

void juce::XmlElement::setTagName | ( | StringRef | newTagName | ) |

Changes this elements tag name.

See also
  getTagName

## 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.

## 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

References getAttributeName().

Referenced by getAttributeName().

## 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

References getAttributeValue().

Referenced by getAttributeValue().

## hasAttribute()

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

noexcept

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

References hasAttribute().

Referenced by hasAttribute().

## 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

References getStringAttribute().

Referenced by getStringAttribute(), and getStringAttribute().

## 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

References getStringAttribute().

## compareAttribute() [1/2]

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)

References compareAttribute().

Referenced by compareAttribute(), and compareAttribute().

## compareAttribute() [2/2]

bool juce::XmlElement::compareAttribute | ( | const XmlAttribute & | attribute,
|  | bool | ignoreCase = false ) const

noexcept

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

Parameters

  attribute | the name-value pair to search for in the current element
  ignoreCase | whether the value 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)

References compareAttribute().

## 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

References getIntAttribute().

Referenced by getIntAttribute().

## 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

References getDoubleAttribute().

Referenced by getDoubleAttribute().

## 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

References getBoolAttribute().

Referenced by getBoolAttribute().

## 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

References setAttribute().

Referenced by setAttribute(), setAttribute(), and setAttribute().

## 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

References setAttribute().

## 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

References setAttribute().

## 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

References removeAttribute().

Referenced by removeAttribute().

## removeAllAttributes()

void juce::XmlElement::removeAllAttributes | ( |  | ) |

noexcept

Removes all attributes from this element.

References removeAllAttributes().

Referenced by removeAllAttributes().

## getFirstChildElement()

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

inline noexcept

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

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

See also
  getChildIterator

References getFirstChildElement(), and XmlElement().

Referenced by getChildIterator(), and getFirstChildElement().

## getNextElement()

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

inline noexcept

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();
}
juce::XmlElement::getNextElement
XmlElement * getNextElement() const noexcept
Returns the next of this element's siblings.
Definition juce_XmlElement.h:455

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 getChildIterator() method.

Returns
  the sibling element that follows this one, or a nullptr if this is the last element in its parent

See also
  getNextElement, isTextElement, getChildIterator

References XmlElement().

## 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, getChildIterator

References XmlElement().

## getNumChildElements()

int juce::XmlElement::getNumChildElements | ( |  | ) | const

noexcept

Returns the number of sub-elements in this element.

See also
  getChildElement

Referenced by sortChildElements().

## 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

References getChildElement(), and XmlElement().

Referenced by getChildElement().

## 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

References getChildByName(), and XmlElement().

Referenced by getChildByName(), and getChildWithTagNameIterator().

## 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

References getChildByAttribute(), and XmlElement().

Referenced by getChildByAttribute().

## 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

References addChildElement(), and XmlElement().

Referenced by addChildElement().

## 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

References insertChildElement(), and XmlElement().

Referenced by insertChildElement().

## 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

References prependChildElement(), and XmlElement().

Referenced by prependChildElement().

## 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");
juce::XmlElement::createNewChildElement
XmlElement * createNewChildElement(StringRef tagName)
Creates a new element with the given name and returns it, after adding it as a child element.

References createNewChildElement(), and XmlElement().

Referenced by createNewChildElement().

## 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.

References replaceChildElement(), and XmlElement().

Referenced by replaceChildElement().

## 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

References removeChildElement(), and XmlElement().

Referenced by removeChildElement().

## deleteAllChildElements()

void juce::XmlElement::deleteAllChildElements | ( |  | ) |

noexcept

Deletes all the child elements in the element.

See also
  removeChildElement, deleteAllChildElementsWithTagName

References deleteAllChildElements().

Referenced by deleteAllChildElements().

## deleteAllChildElementsWithTagName()

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

noexcept

Deletes all the child elements with a given tag name.

See also
  removeChildElement

References deleteAllChildElementsWithTagName().

Referenced by deleteAllChildElementsWithTagName().

## containsChildElement()

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

noexcept

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

References containsChildElement(), and XmlElement().

Referenced by containsChildElement().

## 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.

References findParentElementOf(), and XmlElement().

Referenced by findParentElementOf().

## 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 getNumChildElements(), juce::sortArray(), sortChildElements(), and XmlElement().

Referenced by sortChildElements().

## 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

## 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

References getText().

Referenced by getText().

## 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.

References setText().

Referenced by setText().

## 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>
x
float x
Definition juce_UnityPluginInterface.h:197

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

References getAllSubText().

Referenced by getAllSubText().

## 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

References getChildElementAllSubText().

Referenced by getChildElementAllSubText().

## addTextElement()

void juce::XmlElement::addTextElement | ( | const String & | text | ) |

Appends a section of text to this element.

See also
  isTextElement, getText, getAllSubText

References addTextElement().

Referenced by addTextElement().

## deleteAllTextElements()

void juce::XmlElement::deleteAllTextElements | ( |  | ) |

noexcept

Removes all the text elements from this element.

See also
  isTextElement, getText, getAllSubText, addTextElement

References deleteAllTextElements().

Referenced by deleteAllTextElements().

## createTextElement()

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

static

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

References createTextElement(), and XmlElement().

Referenced by createTextElement().

## isValidXmlName()

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

static noexcept

Checks if a given string is a valid XML name.

References isValidXmlName(), and XmlElement().

Referenced by isValidXmlName().

## getChildIterator()

Iterator< GetNextElement > juce::XmlElement::getChildIterator | ( |  | ) | const

inline

Allows iterating the children of an XmlElement using range-for syntax.

void doSomethingWithXmlChildren (const XmlElement& myParentXml)
{
for (auto* element : myParentXml.getChildIterator())
doSomethingWithXmlElement (element);
}
juce::XmlElement::getChildIterator
Iterator< GetNextElement > getChildIterator() const
Allows iterating the children of an XmlElement using range-for syntax.
Definition juce_XmlElement.h:840

References getFirstChildElement().

## getChildWithTagNameIterator()

Iterator< GetNextElementWithTagName > juce::XmlElement::getChildWithTagNameIterator | ( | StringRef | name | ) | const

inline

Allows iterating children of an XmlElement with a specific tag using range-for syntax.

void doSomethingWithXmlChildren (const XmlElement& myParentXml)
{
for (auto* element : myParentXml.getChildWithTagNameIterator ("MYTAG"))
doSomethingWithXmlElement (element);
}
juce::XmlElement::getChildWithTagNameIterator
Iterator< GetNextElementWithTagName > getChildWithTagNameIterator(StringRef name) const
Allows iterating children of an XmlElement with a specific tag using range-for syntax.
Definition juce_XmlElement.h:855

References getChildByName(), and name.

## getAttributeIterator()

AttributeIterator juce::XmlElement::getAttributeIterator | ( |  | ) | const

inline

Allows iterating all attributes of an XmlElement using range-for syntax.

void doSomethingWithXmlAttributes (const XmlElement& myParentXml)
{
for (const auto& attribute : myParentXml.getAttributeIterator())
{
// Name and value are available as attribute.name and attribute.value
}
}
juce::XmlElement::getAttributeIterator
AttributeIterator getAttributeIterator() const
Allows iterating all attributes of an XmlElement using range-for syntax.
Definition juce_XmlElement.h:872

### Purchase

Get JUCE

### Discover

What's New in JUCE Features

### Learn

Documentaion Tutorials Made with JUCE Resources

### Support

JUCE Forum Newsletter Archive

### About

Contact Us JUCE Legal JUCE Licensing FAQ

### Events

Audio Developer Conference
© Raw Material Software Limited