ofxXmlSettings

ofDocsdocumentation addons ofxXmlSettings ofxXmlSettings

ofxXmlSettings addon allows for reading and writing of xml files in openFrameworks. Most commonly xml settings are used for storing settings between closing and launching apps. XML has the advantage of being easy for people to read and edit but still convenient for manipulating with code.

An xml document is composed of tags with values and other tags inside of them. A tag has a name, attributes, values. If a tag contains other tags they are called its children. If a tag is inside of another, the enclosing tag is called its parent. The tags next to one another are siblings.

<parentTagName

addAttribute( `...` )

int addAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, const __cxx11::string &value)

Adds a new attribute to the tag with with the given string value.

addAttribute( `...` )

int  addAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, const __cxx11::string &value, int which=0)

Adds a new attribute to the tag with the given string value.

addAttribute( `...` )

int addAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, int value)

Adds a new attribute to the tag with with the given int value.

addAttribute( `...` )

int addAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, double value)

Adds a new attribute to the tag with with the given double value.

addAttribute( `...` )

int addAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, int value, int which=0)

Adds a new attribute to the tag with with the given int value. If the tag doesn't exist it is created. If an attribute at index 'which' already exists its value replaced by the provided value

addAttribute( `...` )

int addAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, double value, int which=0)

Adds a new attribute to the tag with the given double value.

addTag( `...` )

int addTag(const __cxx11::string &tag)

Adds an empty tag at the current document level. If you want to add children tags, call pushTag afterwords to begin editing the document with the new tag as root.

Return the number of tags with the same name at the current level.

addValue( `...` )

int addValue(const __cxx11::string &tag, const __cxx11::string &value)

Adds a tag with tag name and string value to the document, returning the number of tags with the same name.

addValue( `...` )

int addValue(const __cxx11::string &tag, int value)

Adds a tag with tag name and integer value to the document, returning the number of tags with the same name.

addValue and setValue are very similar, both add new tags to the current document with the given name and value. The distinction is that if tags exist with the same name at the current document level, addValue will create additional tags, while setValue will replace contents of the tags based on the 'which' parameter.

addValue( `...` )

int addValue(const __cxx11::string &tag, double value)

Adds a tag with tag name and double value to the document, returning the number of tags with the same name.

attributeExists( `...` )

bool attributeExists(const __cxx11::string &tag, const __cxx11::string &attribute, int which=0)

Returns true if a tag has any attributes.

clear( )

void clear()

Removes all tags at the current document level.

clearTagAttributes( `...` )

void clearTagAttributes(const __cxx11::string &tag, int which=0)

Clears all attributes from the given tag name and tag index which.

clearTagContents( `...` )

void clearTagContents(const __cxx11::string &tag, int which=0)

If the given tag exists at the current pushTag level set its contents to empty.

copyXmlToString( `...` )

void copyXmlToString(__cxx11::string &str)

Copies the contents of the ofxXmlSettings into the string str.

getAttribute( `...` )

__cxx11::string  getAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, const __cxx11::string &defaultValue, int which=0)

Returns the value of the attribute on tag at index which as a string.

getAttribute( `...` )

int getAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, int defaultValue, int which=0)

Returns the value of the attribute on tag at index which as an int.

getAttribute( `...` )

double getAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, double defaultValue, int which=0)

Returns the value of the attribute on tag at index which as a double.

getAttributeNames( `...` )

bool getAttributeNames(const __cxx11::string &tag, int &outNames, int which=0)

Returns an array of strings containing all attribute names on the tag. This is useful in conjunction with a loop to get all values of the tags one by one with calls to getAttribute.

getElementForAttribute( )

int * getElementForAttribute()

getNumAttributes( `...` )

int getNumAttributes(const __cxx11::string &tag, int which=0)

Returns the number of attributes on a tag at index which.

getNumTags( `...` )

int getNumTags(const __cxx11::string &tag)

Returns the number of tags with the given name at the current document level. Useful for iterating through a list of sibling tags with the same name.

getPushLevel( )

int getPushLevel()

getPushLevel returns the number of tags that have been pushed. Starting at 0 when the file is first populated (eg a call to loadFile). Each time pushTag is called push level increases by one. Each time popTag is called it decreases.

getValue( `...` )

__cxx11::string getValue(const __cxx11::string &tag, const __cxx11::string &defaultValue, int which=0)

Returns the value stored by the requested tag as a string. Refer above for description of how this method works.

getValue( `...` )

int getValue(const __cxx11::string &tag, int defaultValue, int which=0)

Returns the value stored by the requested tag. The data type returned depends on the type provided as the defaultArgument. For example, if the tag is:

<myTag

getValue( `...` )

double getValue(const __cxx11::string &tag, double defaultValue, int which=0)

Returns the value stored by the requested tag as a double. Refer above for description of how this method works.

load( `...` )

bool load(const __cxx11::string &path)

loadFile( `...` )

bool loadFile(const __cxx11::string &xmlFile)

Loads and parses the xml file at the given path. Returns true if the file is found and is correctly formatted xml.

loadFromBuffer( `...` )

bool loadFromBuffer(__cxx11::string buffer)

Populates the ofxXmlSettings object from a string of containing xml.

ofxXmlSettings( `...` )

ofxXmlSettings(const __cxx11::string &xmlFile)

Initializes an xml settings object and loads the file at xmlFile path.

ofxXmlSettings( )

ofxXmlSettings()

Default constructor for ofxXmlSettings. Initializes an empty object with no file set or loaded and no contents.

popTag( )

int popTag()

popTag restores the current document root after a call to pushTag.

pushTag( `...` )

bool pushTag(const __cxx11::string &tag, int which=0)

Pushing and Popping operations are used to set the current document level. Most of the methods in ofxXmlSettings are done in relationship to just the top level tags, so pushing tags is necessary to go deeper into documents. Every pushTag should be matched with a popTag after operations at that level are finished.

pushingTag pushes the given tag which is then treated as the tag as as the document root.

readDoubleAttribute( `...` )

bool readDoubleAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, double &outValue, int which)

readIntAttribute( `...` )

bool readIntAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, int &valueString, int which)

readStringAttribute( `...` )

bool  readStringAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, __cxx11::string &outValue, int which)

readTag( `...` )

bool readTag(const __cxx11::string &tag, int &valHandle, int which=0)

removeAttribute( `...` )

void removeAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, int which=0)

Removes the attribute from tag name at index specified by 'which'.

removeTag( `...` )

void removeTag(const __cxx11::string &tag, int which=0)

Removes a tag from the current level. This differs from clearing it in that the entire tag is removed, rather than just its contents being set to empty.

save( `...` )

bool save(const __cxx11::string &path)

saveFile( `...` )

bool saveFile(const __cxx11::string &xmlFile)

Saves the current state of the xml settings object to file at xmlFile path.

saveFile( )

bool saveFile()

Saves the current state of the xml file to its current path. The current path is defined by whatever path was specified when loadFile(xmlFile) or saveFile(xmlFile) was last called.

setAttribute( `...` )

int setAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, const __cxx11::string &value)

Refer to addAttribute

setAttribute( `...` )

int  setAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, const __cxx11::string &value, int which=0)

Refer to addAttribute

setAttribute( `...` )

int setAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, int value)

Refer to addAttribute

setAttribute( `...` )

int setAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, double value)

Refer to addAttribute

setAttribute( `...` )

int setAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, int value, int which=0)

Returns the value of the attribute on tag as a double.

setAttribute( `...` )

int setAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, double value, int which=0)

Refer to addAttribute

setValue( `...` )

int setValue(const __cxx11::string &tag, const __cxx11::string &value, int which=0)

Sets the value of a tag to a string value. If the tag already exists, the current value is replaced with value otherwise a new tag is created.

The number of tags with the same name at the current document level is returned.

setValue( `...` )

int setValue(const __cxx11::string &tag, int value, int which=0)

Sets the value of a tag to an integer value. If the tag already exists, the current value is replaced with value. Otherwise a new tag is created.

The number of tags with the same name at the current document level is returned.

setValue( `...` )

int setValue(const __cxx11::string &tag, double value, int which=0)

Sets the value of a tag to an integer value. If the tag already exists, the current value is replaced with value otherwise a new tag is created.

The number of tags with the same name at the current document level is returned.

setVerbose( `...` )

void setVerbose(bool _verbose)

tagExists( `...` )

bool tagExists(const __cxx11::string &tag, int which=0)

Returns true if the given tag exists at the current pushTag level.

writeAttribute( `...` )

int  writeAttribute(const __cxx11::string &tag, const __cxx11::string &attribute, const __cxx11::string &valueString, int which=0)

writeTag( `...` )

int writeTag(const __cxx11::string &tag, const __cxx11::string &valueString, int which=0)

~ofxXmlSettings( )

~ofxXmlSettings()

#class ofxXmlSettings

##InlineDescription

##Description

~~~~{.xml}
<parentTagName>
	<tagName attributeName="attributeValue">TagValue</tagName>
	<siblingTag />
</parentName> 
~~~~

A very simple example for saving and loading values using ofxXmlSettings variable would look like this:
~~~~{.cpp}
//put some some settings into a file
ofxXmlSettings settings;
settings.setValue("settings:blinkRate", 10);
settings.setValue("settings:gravity", 9.8);
settings.setValue("settings:sceneName", "field");
settings.saveFile("settings.xml"); //puts settings.xml file in the bin/data folder
~~~~

The file this generates would look like this
~~~~{.xml}
<settings>
	<blinkRate>10</blinkRate>
	<gravity>9.8</gravity>
	<sceneName>field</sceneName>
</settings>
~~~~

To load the file again, use a snippet like the following
~~~~{.cpp}
//now load that same file and get the values out
ofxXmlSettings settings;
settings.loadFile("settings.xml");
int blinkRate = settings.getValue("settings:blinkRate", 0.0);
float gravity = settings.getValue("settings:gravity", 0);
string sceneName = settings.getValue("settings:sceneName", "defaultScene");
~~~~

A more complex example involving saving an array.
~~~~{.cpp}
ofxXmlSettings positions;
positions.addTag("positions");
positions.pushTag("positions");
//points is a vector<ofPoint> that we want to save to a file
for(int i = 0; i < points.size(); i++){
	//each position tag represents one point
	positions.addTag("position");
	positions.pushTag("position",i);
	//so set the three values in the file
	positions.addValue("X", points[i].x);
	positions.addValue("Y", points[i].y);
	positions.addValue("Z", points[i].z);
	positions.popTag();//pop position
}
positions.popTag(); //pop position
positions.saveFile("positions.xml");

//This is how you would load that very same file	
ofxXmlSettings settings;
if(settings.loadFile("positions.xml")){
	settings.pushTag("positions");
	int numberOfSavedPoints = settings.getNumTags("position");
	for(int i = 0; i < numberOfSavedPoints; i++){
		settings.pushTag("position", i);
		
		ofPoint p;
		p.x = settings.getValue("X", 0);
		p.y = settings.getValue("Y", 0);
		p.z = settings.getValue("Z", 0);
		
		points.push_back(p);
		settings.popTag();
	}
	
	settings.popTag(); //pop position
}
else{
	ofLogError("Position file did not load!");
}
~~~~

What is this "which" argument I see everywhere used for?

Most of the time you can ignore this and treat it as if it weren't there. But if specified it selects the nth tag with the same tag name at the current root of the document Normally this just means the top level tags in the document - but if you use the pushTag and popTag you can temporarily set the root of the document to be that specified tag. The main idea is to allow you to have multiple tags with the same name.

Here is an example:

~~~~{.xml}
<time>102229</time>  <-- which = 0
<time>298292</time>  <-- which = 1
<time>393393</time>  <-- which = 2
<time>447373</time>  <-- which = 3
~~~~

But if we wanted to group these into multiple <recording> tags and have multiple time values inside
we can use push and pop to move into the recording tags as if they were the document root
~~~~{.xml}
<recording> <-- we temporarily push into here with pushTag("recording", 0);
	<time>19222</time>  <-- to set this we call setValue("time", 19222, 0);   ( which = 0 )
	<time>23232</time>  <-- to set this we call setValue("time", 23232, 1);   ( which = 1 )
</recording> <-- we pop back out here with popTag();
~~~~

~~~~{.xml}
<recording>  <-- we temporarily push into here with pushTag("recording", 1); <-- now we use 1 to select the 2nd recording tag
	<time>33342</time>  <-- setValue("time", 33342, 0);   ( which = 0 )
	<time>22722</time>  <-- setValue("time", 22722, 0);   ( which = 1 )
</recording>
~~~~

##Methods

###int addAttribute(&tag, &attribute, &value)

_inlined_description: _

_description: _

Adds a new attribute to the tag with with the given string value.

###int addAttribute(&tag, &attribute, &value, which = 0)

_inlined_description: _

_description: _

Adds a new attribute to the tag with the given string value.

###int addAttribute(&tag, &attribute, value)

_inlined_description: _

_description: _

Adds a new attribute to the tag with with the given int value.

###int addAttribute(&tag, &attribute, value)

_inlined_description: _

_description: _

Adds a new attribute to the tag with with the given double value.

###int addAttribute(&tag, &attribute, value, which = 0)

_inlined_description: _

_description: _

Adds a new attribute to the tag with with the given int value. If the tag doesn't exist it is created. If an attribute at index 'which' already exists its value replaced by the provided value

###int addAttribute(&tag, &attribute, value, which = 0)

_inlined_description: _

_description: _

Adds a new attribute to the tag with the given double value.

###int addTag(&tag)

_inlined_description: _

_description: _

Adds an empty tag at the current document level. If you want to add children tags, call pushTag afterwords to begin editing the document with the new tag as root.

Return the number of tags with the same name at the current level.

###int addValue(&tag, &value)

_inlined_description: _

_description: _

Adds a tag with tag name and string value to the document, returning the number of tags with the same name.

###int addValue(&tag, value)

_inlined_description: _

_description: _

Adds a tag with tag name and integer value to the document, returning the number of tags with the same name.

addValue and setValue are very similar, both add new tags to the current document with the given name and value.  The distinction is that if tags exist with the same name at the current document level, addValue will create additional tags, while setValue will replace contents of the tags based on the 'which' parameter.

###int addValue(&tag, value)

_inlined_description: _

_description: _

Adds a tag with tag name and double value to the document, returning the number of tags with the same name.

###bool attributeExists(&tag, &attribute, which = 0)

_inlined_description: _

_description: _

Returns true if a tag has any attributes.

###void clear()

_inlined_description: _

_description: _

Removes all tags at the current document level.

###void clearTagAttributes(&tag, which = 0)

_inlined_description: _

_description: _

Clears all attributes from the given tag name and tag index which.

###void clearTagContents(&tag, which = 0)

_inlined_description: _

_description: _

If the given tag exists at the current pushTag level set its contents to empty.

###void copyXmlToString(&str)

_inlined_description: _

_description: _

Copies the contents of the ofxXmlSettings into the string str.

###__cxx11::string getAttribute(&tag, &attribute, &defaultValue, which = 0)

_inlined_description: _

_description: _

Returns the value of the attribute on tag at index which as a string.

###int getAttribute(&tag, &attribute, defaultValue, which = 0)

_inlined_description: _

_description: _

Returns the value of the attribute on tag at index which as an int.

###double getAttribute(&tag, &attribute, defaultValue, which = 0)

_inlined_description: _

_description: _

Returns the value of the attribute on tag at index which as a double.

###bool getAttributeNames(&tag, &outNames, which = 0)

_inlined_description: _

_description: _

Returns an array of strings containing all attribute names on the tag.  This is useful in conjunction with a loop to get all values of the tags one by one with calls to getAttribute.

###int * getElementForAttribute()

_inlined_description: _

_description: _

###int getNumAttributes(&tag, which = 0)

_inlined_description: _

_description: _

Returns the number of attributes on a tag at index which.

###int getNumTags(&tag)

_inlined_description: _

_description: _

Returns the number of tags with the given name at the current document level. Useful for iterating through a list of sibling tags with the same name.

###int getPushLevel()

_inlined_description: _

_description: _

###__cxx11::string getValue(&tag, &defaultValue, which = 0)

_inlined_description: _

_description: _

Returns the value stored by the requested tag as a string. Refer above for description of how this method works.

###int getValue(&tag, defaultValue, which = 0)

_inlined_description: _

_description: _

Returns the value stored by the requested tag. The data type returned depends on the type provided as the defaultArgument. For example, if the tag is:
~~~~{.xml}
<myTag>9.8</myTag>   
~~~~

The value can be interpreted in three different ways, as a float, int, or string by changing the default type provided to the call.

~~~~{.cpp}
//returns "9.8"
string myString = settings.getValue("myTag", "");
//returns the integer value 9
int myInt = settings.getValue("myTag", 0);
//returns the double value 9.8
double myDouble = settings.getValue("myTag", 0.0);
~~~~

###double getValue(&tag, defaultValue, which = 0)

_inlined_description: _

_description: _

Returns the value stored by the requested tag as a double. Refer above for description of how this method works.

###bool load(&path)

_inlined_description: _

_description: _

###bool loadFile(&xmlFile)

_inlined_description: _

_description: _

Loads and parses the xml file at the given path.  Returns true if the file is found and is correctly formatted xml.

###bool loadFromBuffer(buffer)

_inlined_description: _

_description: _

Populates the ofxXmlSettings object from a string of containing xml.

### ofxXmlSettings(&xmlFile)

_inlined_description: _

_description: _

Initializes an xml settings object and loads the file at xmlFile path.

### ofxXmlSettings()

_inlined_description: _

_description: _

Default constructor for ofxXmlSettings.  Initializes an empty object with no file set or loaded and no contents.

###int popTag()

_inlined_description: _

_description: _

popTag restores the current document root after a call to pushTag.

###bool pushTag(&tag, which = 0)

_inlined_description: _

_description: _

pushingTag pushes the given tag which is then treated as the tag as as the document root.

###bool readDoubleAttribute(&tag, &attribute, &outValue, which)

_inlined_description: _

_description: _

###bool readIntAttribute(&tag, &attribute, &valueString, which)

_inlined_description: _

_description: _

###bool readStringAttribute(&tag, &attribute, &outValue, which)

_inlined_description: _

_description: _

###bool readTag(&tag, &valHandle, which = 0)

_inlined_description: _

_description: _

###void removeAttribute(&tag, &attribute, which = 0)

_inlined_description: _

_description: _

Removes the attribute from tag name at index specified by 'which'.

###void removeTag(&tag, which = 0)

_inlined_description: _

_description: _

Removes a tag from the current level. This differs from clearing it in that the entire tag is removed, rather than just its contents being set to empty.

###bool save(&path)

_inlined_description: _

_description: _

###bool saveFile(&xmlFile)

_inlined_description: _

_description: _

Saves the current state of the xml settings object to file at xmlFile path.

###bool saveFile()

_inlined_description: _

_description: _

Saves the current state of the xml file to its current path. The current path is defined by whatever path was specified when loadFile(xmlFile) or saveFile(xmlFile) was last called.

###int setAttribute(&tag, &attribute, &value)

_inlined_description: _

_description: _

Refer to addAttribute

###int setAttribute(&tag, &attribute, &value, which = 0)

_inlined_description: _

_description: _

Refer to addAttribute

###int setAttribute(&tag, &attribute, value)

_inlined_description: _

_description: _

Refer to addAttribute

###int setAttribute(&tag, &attribute, value)

_inlined_description: _

_description: _

Refer to addAttribute

###int setAttribute(&tag, &attribute, value, which = 0)

_inlined_description: _

_description: _

Returns the value of the attribute on tag as a double.

###int setAttribute(&tag, &attribute, value, which = 0)

_inlined_description: _

_description: _

Refer to addAttribute

###int setValue(&tag, &value, which = 0)

_inlined_description: _

_description: _

Sets the value of a tag to a string value.  If the tag already exists, the current value is replaced with value otherwise a new tag is created.

The number of tags with the same name at the current document level is returned.

###int setValue(&tag, value, which = 0)

_inlined_description: _

_description: _

Sets the value of a tag to an integer value.  If the tag already exists, the current value is replaced with value. Otherwise a new tag is created.

The number of tags with the same name at the current document level is returned.

###int setValue(&tag, value, which = 0)

_inlined_description: _

_description: _

Sets the value of a tag to an integer value.  If the tag already exists, the current value is replaced with value otherwise a new tag is created.

The number of tags with the same name at the current document level is returned.

###void setVerbose(_verbose)

_inlined_description: _

_description: _

###bool tagExists(&tag, which = 0)

_inlined_description: _

_description: _

Returns true if the given tag exists at the current pushTag level.

###int writeAttribute(&tag, &attribute, &valueString, which = 0)

_inlined_description: _

_description: _

###int writeTag(&tag, &valueString, which = 0)

_inlined_description: _

_description: _

### ~ofxXmlSettings()

_inlined_description: _

_description: _

##Variables

###bool bDocLoaded

_inlined_description: _

_description: _

###TiXmlDocument doc

_inlined_description: _

_description: _

###int level

_inlined_description: _

_description: _

###TiXmlHandle storedHandle

_inlined_description: _

_description: _

Docs 0.11.0

addAttribute( ... )

addAttribute( ... )

addAttribute( ... )

addAttribute( ... )

addAttribute( ... )

addAttribute( ... )

addTag( ... )

addValue( ... )

addValue( ... )

addValue( ... )

attributeExists( ... )

clear( )

clearTagAttributes( ... )

clearTagContents( ... )

copyXmlToString( ... )

getAttribute( ... )

getAttribute( ... )

getAttribute( ... )

getAttributeNames( ... )

getElementForAttribute( )

getNumAttributes( ... )

getNumTags( ... )

getPushLevel( )

getValue( ... )

getValue( ... )

getValue( ... )

load( ... )

loadFile( ... )

loadFromBuffer( ... )

ofxXmlSettings( ... )

ofxXmlSettings( )

popTag( )

pushTag( ... )

readDoubleAttribute( ... )

readIntAttribute( ... )

readStringAttribute( ... )

readTag( ... )

removeAttribute( ... )

removeTag( ... )

save( ... )

saveFile( ... )

saveFile( )

setAttribute( ... )

setAttribute( ... )

setAttribute( ... )

setAttribute( ... )

setAttribute( ... )

setAttribute( ... )

setValue( ... )

setValue( ... )

setValue( ... )

setVerbose( ... )

tagExists( ... )

writeAttribute( ... )

writeTag( ... )

~ofxXmlSettings( )

Variables

Methods

See also

addAttribute( `...` )

addAttribute( `...` )

addAttribute( `...` )

addAttribute( `...` )

addAttribute( `...` )

addAttribute( `...` )

addTag( `...` )

addValue( `...` )

addValue( `...` )

addValue( `...` )

attributeExists( `...` )

clearTagAttributes( `...` )

clearTagContents( `...` )

copyXmlToString( `...` )

getAttribute( `...` )

getAttribute( `...` )

getAttribute( `...` )

getAttributeNames( `...` )

getNumAttributes( `...` )

getNumTags( `...` )

getValue( `...` )

getValue( `...` )

getValue( `...` )

load( `...` )

loadFile( `...` )

loadFromBuffer( `...` )

ofxXmlSettings( `...` )

pushTag( `...` )

readDoubleAttribute( `...` )

readIntAttribute( `...` )

readStringAttribute( `...` )

readTag( `...` )

removeAttribute( `...` )

removeTag( `...` )

save( `...` )

saveFile( `...` )

setAttribute( `...` )

setAttribute( `...` )

setAttribute( `...` )

setAttribute( `...` )

setAttribute( `...` )

setAttribute( `...` )

setValue( `...` )

setValue( `...` )

setValue( `...` )

setVerbose( `...` )

tagExists( `...` )

writeAttribute( `...` )

writeTag( `...` )