OpenShot Library | OpenShotAudio  0.2.1
juce::XmlElement Class Reference

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

#include <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. 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...
 
XmlElementoperator= (const XmlElement &)
 Creates a (deep) copy of another element. More...
 
XmlElementoperator= (XmlElement &&) noexcept
 Move assignment operator.
 
 XmlElement (XmlElement &&) noexcept
 Move constructor.
 
 ~XmlElement () noexcept
 Deleting an XmlElement will also delete all of its child elements. More...
 
bool isEquivalentTo (const XmlElement *other, bool ignoreOrderOfAttributes) const noexcept
 Compares two XmlElements to see if they contain the same text and attributes. More...
 
String toString (const TextFormat &format={}) const
 Returns a text version of this XML element. More...
 
void writeTo (OutputStream &output, const TextFormat &format={}) const
 Writes the document to a stream as UTF-8. More...
 
bool writeTo (const File &destinationFile, const TextFormat &format={}) const
 Writes the document to a file as UTF-8. More...
 
const StringgetTagName () const noexcept
 Returns this element's tag type name. More...
 
String getNamespace () const
 Returns the namespace portion of the tag-name, or an empty string if none is specified. More...
 
String getTagNameWithoutNamespace () const
 Returns the part of the tag-name that follows any namespace declaration. 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 setTagName (StringRef newTagName)
 Changes this elements tag name. More...
 
int getNumAttributes () const noexcept
 Returns the number of XML attributes this element contains. More...
 
const StringgetAttributeName (int attributeIndex) const noexcept
 Returns the name of one of the elements attributes. More...
 
const StringgetAttributeValue (int attributeIndex) const noexcept
 Returns the value of one of the elements attributes. More...
 
bool hasAttribute (StringRef attributeName) const noexcept
 Checks whether the element contains an attribute with a certain name. More...
 
const StringgetStringAttribute (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...
 
bool compareAttribute (StringRef attributeName, StringRef stringToCompareAgainst, bool ignoreCase=false) const noexcept
 Compares the value of a named attribute with a value passed-in. More...
 
int getIntAttribute (StringRef attributeName, int defaultReturnValue=0) const
 Returns the value of a named attribute as an integer. More...
 
double getDoubleAttribute (StringRef attributeName, double defaultReturnValue=0.0) const
 Returns the value of a named attribute as floating-point. More...
 
bool getBoolAttribute (StringRef attributeName, bool defaultReturnValue=false) const
 Returns the value of a named attribute as a boolean. 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 removeAttribute (const Identifier &attributeName) noexcept
 Removes a named attribute from the element. More...
 
void removeAllAttributes () noexcept
 Removes all attributes from this element. More...
 
XmlElementgetFirstChildElement () const noexcept
 Returns the first of this element's sub-elements. More...
 
XmlElementgetNextElement () const noexcept
 Returns the next of this element's siblings. More...
 
XmlElementgetNextElementWithTagName (StringRef requiredTagName) const
 Returns the next of this element's siblings which has the specified tag name. More...
 
int getNumChildElements () const noexcept
 Returns the number of sub-elements in this element. More...
 
XmlElementgetChildElement (int index) const noexcept
 Returns the sub-element at a certain index. More...
 
XmlElementgetChildByName (StringRef tagNameToLookFor) const noexcept
 Returns the first sub-element with a given tag-name. More...
 
XmlElementgetChildByAttribute (StringRef attributeName, StringRef attributeValue) const noexcept
 Returns the first sub-element which has an attribute that matches the given value. More...
 
void addChildElement (XmlElement *newChildElement) noexcept
 Appends an element to this element's list of children. More...
 
void insertChildElement (XmlElement *newChildElement, int indexToInsertAt) noexcept
 Inserts an element into this element's list of children. More...
 
void prependChildElement (XmlElement *newChildElement) noexcept
 Inserts an element at the beginning of this element's list of children. More...
 
XmlElementcreateNewChildElement (StringRef tagName)
 Creates a new element with the given name and returns it, after adding it as a child element. More...
 
bool replaceChildElement (XmlElement *currentChildElement, XmlElement *newChildNode) noexcept
 Replaces one of this element's children with another node. More...
 
void removeChildElement (XmlElement *childToRemove, bool shouldDeleteTheChild) noexcept
 Removes 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...
 
bool containsChildElement (const XmlElement *possibleChild) const noexcept
 Returns true if the given element is a child of this one. More...
 
XmlElementfindParentElementOf (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...
 
template<class ElementComparator >
void sortChildElements (ElementComparator &comparator, bool retainOrderOfEquivalentItems=false)
 Sorts the child elements using a comparator. More...
 
bool isTextElement () const noexcept
 Returns true if this element is a section of text. More...
 
const StringgetText () const noexcept
 Returns the text for a text element. More...
 
void setText (const String &newText)
 Sets the text in a text element. More...
 
String getAllSubText () const
 Returns all the text from this element's child nodes. More...
 
String getChildElementAllSubText (StringRef childTagName, const String &defaultReturnValue) const
 Returns all the sub-text of a named child element. More...
 
void addTextElement (const String &text)
 Appends a section of text to this element. More...
 
void deleteAllTextElements () noexcept
 Removes all the text elements from this element. More...
 
 JUCE_DEPRECATED (String createDocument(StringRef dtdToUse, bool allOnOneLine=false, bool includeXmlHeader=true, StringRef encodingType="UTF-8", int lineWrapLength=60) const)
 This has been deprecated in favour of the toString() method. More...
 
 JUCE_DEPRECATED (void writeToStream(OutputStream &output, StringRef dtdToUse, bool allOnOneLine=false, bool includeXmlHeader=true, StringRef encodingType="UTF-8", int lineWrapLength=60) const)
 This has been deprecated in favour of the writeTo() method. More...
 
 JUCE_DEPRECATED (bool writeToFile(const File &destinationFile, StringRef dtdToUse, StringRef encodingType="UTF-8", int lineWrapLength=60) const)
 This has been deprecated in favour of the writeTo() method. More...
 

Static Public Member Functions

static XmlElementcreateTextElement (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.
 

Friends

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

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 textual XML
auto xmlString = animalsList.toString();
See also
parseXML, parseXMLIfTagMatches, XmlDocument

Definition at line 141 of file juce_XmlElement.h.

Constructor & Destructor Documentation

◆ XmlElement() [1/6]

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

Creates an XmlElement with this tag name.

Definition at line 76 of file juce_XmlElement.cpp.

References isValidXmlName().

Referenced by createNewChildElement(), createTextElement(), and XmlElement().

◆ XmlElement() [2/6]

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

Creates an XmlElement with this tag name.

Definition at line 82 of file juce_XmlElement.cpp.

References isValidXmlName().

◆ XmlElement() [3/6]

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

Creates an XmlElement with this tag name.

Definition at line 94 of file juce_XmlElement.cpp.

References isValidXmlName().

◆ XmlElement() [4/6]

juce::XmlElement::XmlElement ( StringRef  tagName)
explicit

Creates an XmlElement with this tag name.

Definition at line 88 of file juce_XmlElement.cpp.

References isValidXmlName().

◆ XmlElement() [5/6]

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

Creates an XmlElement with this tag name.

Definition at line 100 of file juce_XmlElement.cpp.

References isValidXmlName(), and XmlElement().

◆ XmlElement() [6/6]

juce::XmlElement::XmlElement ( const XmlElement other)

Creates a (deep) copy of another element.

Definition at line 110 of file juce_XmlElement.cpp.

◆ ~XmlElement()

juce::XmlElement::~XmlElement ( )
noexcept

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

Definition at line 161 of file juce_XmlElement.cpp.

References juce::LinkedListPointer< ObjectType >::deleteAll().

Member Function Documentation

◆ operator=()

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

Creates a (deep) copy of another element.

Definition at line 116 of file juce_XmlElement.cpp.

References deleteAllChildElements(), and removeAllAttributes().

◆ 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
otherthe other element to compare to
ignoreOrderOfAttributesif 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

Definition at line 771 of file juce_XmlElement.cpp.

References compareAttribute(), juce::LinkedListPointer< ObjectType >::get(), and getNumAttributes().

◆ 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

Definition at line 352 of file juce_XmlElement.cpp.

References juce::MemoryOutputStream::toUTF8(), and writeTo().

Referenced by juce::PropertySet::setValue(), writeTo(), and juce::NetworkServiceDiscovery::Advertiser::~Advertiser().

◆ writeTo() [1/2]

◆ writeTo() [2/2]

◆ 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

Definition at line 232 of file juce_XmlElement.h.

Referenced by juce::ValueTree::fromXml(), and juce::XmlDocument::getLastParseError().

◆ getNamespace()

String juce::XmlElement::getNamespace ( ) const

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

Definition at line 481 of file juce_XmlElement.cpp.

References juce::String::upToFirstOccurrenceOf().

◆ getTagNameWithoutNamespace()

String juce::XmlElement::getTagNameWithoutNamespace ( ) const

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

Definition at line 486 of file juce_XmlElement.cpp.

References juce::String::fromLastOccurrenceOf().

Referenced by hasTagNameIgnoringNamespace().

◆ hasTagName()

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

Tests whether this element has a particular tag name.

Parameters
possibleTagNamethe tag name you're comparing it with
See also
getTagName

Definition at line 470 of file juce_XmlElement.cpp.

Referenced by hasTagNameIgnoringNamespace(), juce::AudioDeviceManager::initialise(), and juce::ChannelRemappingAudioSource::restoreFromXml().

◆ 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

Definition at line 491 of file juce_XmlElement.cpp.

References getTagNameWithoutNamespace(), and hasTagName().

◆ setTagName()

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

Changes this elements tag name.

See also
getTagName

Definition at line 506 of file juce_XmlElement.cpp.

References juce::StringPool::getGlobalPool(), juce::StringPool::getPooledString(), and isValidXmlName().

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

Definition at line 513 of file juce_XmlElement.cpp.

Referenced by isEquivalentTo().

◆ 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

Definition at line 524 of file juce_XmlElement.cpp.

◆ 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

Definition at line 532 of file juce_XmlElement.cpp.

◆ hasAttribute()

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

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

Definition at line 549 of file juce_XmlElement.cpp.

Referenced by juce::AudioDeviceManager::initialise().

◆ getStringAttribute() [1/2]

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

Returns the value of a named attribute.

Parameters
attributeNamethe name of the attribute to look up

Definition at line 555 of file juce_XmlElement.cpp.

Referenced by juce::NetworkServiceDiscovery::AvailableServiceList::getServices(), getText(), juce::AudioDeviceManager::initialise(), and juce::ChannelRemappingAudioSource::restoreFromXml().

◆ getStringAttribute() [2/2]

String juce::XmlElement::getStringAttribute ( StringRef  attributeName,
const String defaultReturnValue 
) const

Returns the value of a named attribute.

Parameters
attributeNamethe name of the attribute to look up
defaultReturnValuea value to return if the element doesn't have an attribute with this name

Definition at line 563 of file juce_XmlElement.cpp.

◆ 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
attributeNamethe name of the attribute to look up
stringToCompareAgainstthe value to compare it with
ignoreCasewhether 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)

Definition at line 603 of file juce_XmlElement.cpp.

Referenced by isEquivalentTo().

◆ 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
attributeNamethe name of the attribute to look up
defaultReturnValuea value to return if the element doesn't have an attribute with this name
See also
setAttribute

Definition at line 571 of file juce_XmlElement.cpp.

Referenced by juce::NetworkServiceDiscovery::AvailableServiceList::getServices(), and juce::AudioDeviceManager::initialise().

◆ 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
attributeNamethe name of the attribute to look up
defaultReturnValuea value to return if the element doesn't have an attribute with this name
See also
setAttribute

Definition at line 579 of file juce_XmlElement.cpp.

Referenced by juce::AudioDeviceManager::initialise().

◆ 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
attributeNamethe name of the attribute to look up
defaultReturnValuea value to return if the element doesn't have an attribute with this name

Definition at line 587 of file juce_XmlElement.cpp.

◆ 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
attributeNamethe name of the attribute to set
newValuethe value to set it to
See also
removeAttribute

Definition at line 615 of file juce_XmlElement.cpp.

Referenced by juce::NetworkServiceDiscovery::Advertiser::Advertiser(), juce::NamedValueSet::copyToXmlAttributes(), juce::PropertiesFile::save(), setAttribute(), setText(), and juce::NetworkServiceDiscovery::Advertiser::~Advertiser().

◆ 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
attributeNamethe name of the attribute to set
newValuethe value to set it to

Definition at line 640 of file juce_XmlElement.cpp.

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
attributeNamethe name of the attribute to set
newValuethe value to set it to

Definition at line 645 of file juce_XmlElement.cpp.

References setAttribute().

◆ removeAttribute()

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

Removes a named attribute from the element.

Parameters
attributeNamethe name of the attribute to remove
See also
removeAllAttributes

Definition at line 650 of file juce_XmlElement.cpp.

◆ removeAllAttributes()

void juce::XmlElement::removeAllAttributes ( )
noexcept

Removes all attributes from this element.

Definition at line 662 of file juce_XmlElement.cpp.

Referenced by operator=().

◆ 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

Definition at line 409 of file juce_XmlElement.h.

◆ 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

Definition at line 437 of file juce_XmlElement.h.

◆ 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

Definition at line 496 of file juce_XmlElement.cpp.

◆ getNumChildElements()

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

Returns the number of sub-elements in this element.

See also
getChildElement

Definition at line 668 of file juce_XmlElement.cpp.

Referenced by getAllSubText().

◆ 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

Definition at line 673 of file juce_XmlElement.cpp.

◆ getChildByName()

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

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

Parameters
tagNameToLookForthe 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

Definition at line 678 of file juce_XmlElement.cpp.

Referenced by getChildElementAllSubText().

◆ 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
attributeNamethe name of the attribute to check
attributeValuethe target value of the attribute
Returns
the first element with this attribute value, or nullptr if none is found
See also
getChildByName

Definition at line 689 of file juce_XmlElement.cpp.

References juce::StringRef::isEmpty().

◆ 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

Definition at line 700 of file juce_XmlElement.cpp.

Referenced by addTextElement(), and createNewChildElement().

◆ 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
newChildElementthe element to add
indexToInsertAtthe 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

Definition at line 711 of file juce_XmlElement.cpp.

◆ 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

Definition at line 722 of file juce_XmlElement.cpp.

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

Definition at line 733 of file juce_XmlElement.cpp.

References addChildElement(), and XmlElement().

Referenced by juce::PropertiesFile::save().

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

Definition at line 740 of file juce_XmlElement.cpp.

◆ removeChildElement()

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

Removes a child element.

Parameters
childToRemovethe child to look for and remove
shouldDeleteTheChildif true, the child will be deleted, if false it'll just remove it

Definition at line 757 of file juce_XmlElement.cpp.

References containsChildElement().

Referenced by deleteAllChildElementsWithTagName(), and deleteAllTextElements().

◆ deleteAllChildElements()

void juce::XmlElement::deleteAllChildElements ( )
noexcept

Deletes all the child elements in the element.

See also
removeChildElement, deleteAllChildElementsWithTagName

Definition at line 844 of file juce_XmlElement.cpp.

Referenced by operator=().

◆ deleteAllChildElementsWithTagName()

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

Deletes all the child elements with a given tag name.

See also
removeChildElement

Definition at line 849 of file juce_XmlElement.cpp.

References removeChildElement().

◆ containsChildElement()

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

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

Definition at line 862 of file juce_XmlElement.cpp.

Referenced by removeChildElement().

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

Definition at line 867 of file juce_XmlElement.cpp.

◆ 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
comparatorthe comparator to use for comparing elements.
retainOrderOfEquivalentItemsif 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.

Definition at line 610 of file juce_XmlElement.h.

◆ 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

Definition at line 904 of file juce_XmlElement.cpp.

Referenced by juce::ValueTree::fromXml(), getAllSubText(), getText(), and setText().

◆ 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

Definition at line 911 of file juce_XmlElement.cpp.

References getStringAttribute(), and isTextElement().

Referenced by getAllSubText().

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

Definition at line 920 of file juce_XmlElement.cpp.

References isTextElement(), and setAttribute().

◆ 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

Definition at line 928 of file juce_XmlElement.cpp.

References getNumChildElements(), getText(), isTextElement(), and juce::MemoryOutputStream::toUTF8().

◆ 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

Definition at line 944 of file juce_XmlElement.cpp.

References getChildByName().

◆ addTextElement()

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

Appends a section of text to this element.

See also
isTextElement, getText, getAllSubText

Definition at line 974 of file juce_XmlElement.cpp.

References addChildElement(), and createTextElement().

◆ deleteAllTextElements()

void juce::XmlElement::deleteAllTextElements ( )
noexcept

Removes all the text elements from this element.

See also
isTextElement, getText, getAllSubText, addTextElement

Definition at line 979 of file juce_XmlElement.cpp.

References removeChildElement().

◆ createTextElement()

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

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

Definition at line 952 of file juce_XmlElement.cpp.

References XmlElement().

Referenced by addTextElement(), and juce::XmlDocument::getLastParseError().

◆ JUCE_DEPRECATED() [1/3]

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

This has been deprecated in favour of the toString() method.

◆ JUCE_DEPRECATED() [2/3]

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

This has been deprecated in favour of the writeTo() method.

◆ JUCE_DEPRECATED() [3/3]

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

This has been deprecated in favour of the writeTo() method.


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