xref: /external/collada/include/dae/daeElement.h

/*
* Copyright 2006 Sony Computer Entertainment Inc.
*
* Licensed under the MIT Open Source License, for details please see license.txt or the website
* http://www.opensource.org/licenses/mit-license.php
*
*/

#ifndef __DAE_ELEMENT_H__
#define __DAE_ELEMENT_H__
#include <string>
#include <dae/daeTypes.h>
#include <dae/daeMemorySystem.h>
#include <wchar.h>
#include <dae/daeArray.h>
#include <dae/daeRefCountedObj.h>
#include <dae/daeSmartRef.h>

//#ifndef NO_MALLOC_HEADER
//#include <malloc.h>
//#endif

namespace COLLADA_TYPE
{
	typedef int TypeEnum;
}

class DAE;
class daeMetaElement;
class daeMetaAttribute;
class daeDocument;
class daeURI;

/**
 * The @c daeElement class represents an instance of a COLLADA "Element";
 * it is the main base class for the COLLADA Dom.
 * Features of this class include:
 * - Uses factory concepts defined via daeMetaElement
 * - Composed of attributes, content elements and content values
 * - Reference counted via daeSmartRef
 * - Contains information for XML base URI, and XML containing element
 */
class DLLSPEC daeElement : public daeRefCountedObj
{
public:
	/**
	 * Macro that defines new and delete overrides for this class
	 */
	DAE_ALLOC
protected:
	daeElement* _parent;
	daeDocument* _document;
	daeMetaElement* _meta;
	daeString _elementName;
	daeBoolArray _validAttributeArray; // This is now obsolete and can be removed
	void* _userData;

protected:
	daeElement( const daeElement &cpy ) : daeRefCountedObj() { (void)cpy; };
	virtual daeElement &operator=( const daeElement &cpy ) { (void)cpy; return *this; }

	void init();

	// These functions are called internally.
	void setDocument( daeDocument* c, bool notifyDocument );
	daeElement* simpleAdd(daeString name, int index = -1);

public:
	/**
	 * Element Constructor.
	 * @note This should not be used externally.
	 * Use factories to create elements
	 */
	daeElement();
	/**
	 * Element Constructor.
	 * @note This should not be used externally.
	 * Use factories to create elements
	 */
	daeElement(DAE& dae);

	/**
	 * Element Destructor.
	 * @note This should not be used externally,
	 * if daeSmartRefs are being used.
	 */
	virtual ~daeElement();

	/**
	 * Sets up a @c daeElement. Called on all @c daeElements as part of their initialization.
	 * @param meta Meta element to use to configure this element.
	 * @note Should not be called externally.
	 */
	void setup(daeMetaElement* meta);

	// These functions are for adding child elements. They return null if adding
	// the element failed.
	daeElement* add(daeString name, int index = -1);
	daeElement* add(daeElement* elt, int index = -1);
	daeElement* addBefore(daeElement* elt, daeElement* index);
	daeElement* addAfter(daeElement* elt, daeElement* index);

	// These functions are deprecated. Use 'add' instead.
	daeElement* createAndPlace(daeString elementName);
	daeElement* createAndPlaceAt(daeInt index, daeString elementName);
	daeBool placeElement(daeElement* element);
	daeBool placeElementAt(daeInt index, daeElement* element);
	daeBool placeElementBefore( daeElement* marker, daeElement *element );
	daeBool placeElementAfter( daeElement* marker, daeElement *element );

	/**
	 * Finds the last index into the array of children of the name specified.
	 * @param elementName The name to look for.
	 * @return Returns the index into the children array of the last element with name elementName. -1 if
	 *         there are no children of name elementName.
	 */
	daeInt findLastIndexOf( daeString elementName );

	/**
	 * Removes the specified element from it parent, the @c this element.
	 * This function is the opposite of @c placeElement().  It removes the specified
	 * element from the <tt><i> _contents </i></tt> array, and from wherever else it appears
	 * inside of the @c this element.  Use this function instead of @c clear(), @c remove() or @c delete()
	 * if you want to keep the <tt><i> _contents </i></tt> field up-to-date.
	 *
	 * @param element Element to be removed in the @c this container.
	 * @return Returns true if the element was successfully removed, false otherwise.
	 */
	daeBool removeChildElement(daeElement* element);

	/**
	 * Removes the specified element from its parent element.
	 * This function is the opposite of @c placeElement().  It removes the specified
	 * element from both the <tt><i> _contents </i></tt> array and from wherever else it appears
	 * inside of its parent. The function itself finds the parent, and is defined as a static method,
	 * since removing the element from its parent may result in the deletion of the element.
	 * If the element has no parent, nothing is done.
	 *
	 * Use this function instead of @c clear(), @c remove() or @c delete()
	 * if you want to keep <tt><i> _contents </i></tt> up-to-date.
	 *
	 * @param element Element to remove from its parent container, the function finds the parent element.
	 * @return Returns true if the element was successfully removed, false otherwise.
	 */
	static daeBool removeFromParent(daeElement* element)
	{
		if(element != NULL && element->_parent != NULL)
			return(element->_parent->removeChildElement(element));
		return false;
	};

	/**
	 * Returns the number of attributes in this element.
	 * @return The number of attributes this element has.
	 */
	size_t getAttributeCount();

	/**
	 * Returns the daeMetaAttribute object corresponding to the attribute specified.
	 * @param name The name of the attribute to find.
	 * @return Returns the corresponding daeMetaAttribute object or NULL if this element
	 * doesn't have the specified attribute.
	 */
	daeMetaAttribute* getAttributeObject(daeString name);

	/**
	 * Returns the daeMetaAttribute object corresponding to attribute i.
	 * @param i The index of the attribute to find.
	 * @return Returns the corresponding daeMetaAttribute object
	 */
	daeMetaAttribute* getAttributeObject(size_t i);

	/**
	 * Returns the name of the attribute at the specified index.
	 * @param i The index of the attribute whose name should be retrieved.
	 * @return Returns the name of the attribute, or "" if the index is out of range.
	 */
	std::string getAttributeName(size_t i);

	/**
	 * Checks if this element can have the attribute specified.
	 * @param name The name of the attribute to look for.
	 * @return Returns true is this element can have an attribute with the name specified. False otherwise.
	 */
	daeBool hasAttribute(daeString name);

	/**
	 * Checks if an attribute has been set either by being loaded from the COLLADA document or set
	 * programmatically.
	 * @param name The name of the attribute to check.
	 * @return Returns true if the attribute has been set. False if the attribute hasn't been set
	 * or doesn't exist for this element.
	 */
	daeBool isAttributeSet(daeString name);

	/**
	 * Gets an attribute's value as a string.
	 * @param name The name of the attribute.
	 * @return The value of the attribute. Returns an empty string if this element doesn't
	 * have the specified attribute.
	 */
	std::string getAttribute(daeString name);

	/**
	 * Just like the previous method, this method gets an attribute's value as a string. It
	 * takes the string as a reference parameter instead of returning it, for extra efficiency.
	 * @param name The name of the attribute.
	 * @param A string in which to store the value of the attribute. This will be set to an empty
	 * string if this element doesn't have the specified attribute.
	 */
	void getAttribute(daeString name, std::string& value);

	/**
	 * Gets an attribute's value as a string.
	 * @param i The index of the attribute to retrieve.
	 * @return The value of the attribute.
	 */
	std::string getAttribute(size_t i);

	/**
	 * Just like the previous method, this method gets an attribute's value as a string. It
	 * takes the string as a reference parameter instead of returning it, for extra efficiency.
	 * @param i The index of the attribute to retrieve.
	 * @param A string in which to store the value of the attribute.
	 */
	void getAttribute(size_t i, std::string& value);

	struct DLLSPEC attr {
		attr();
		attr(const std::string& name, const std::string& value);

		std::string name;
		std::string value;
	};

	/**
	 * Returns an array containing all the attributes of this element.
	 * @return A daeArray of attr objects.
	 */
	daeTArray<attr> getAttributes();

	/**
	 * Just like the previous method, this method returns an array containing all the attributes
	 * of this element. It returns the result via a reference parameter for extra efficiency.
	 * @param attrs The array of attr objects to return.
	 */
	void getAttributes(daeTArray<attr>& attrs);

	/**
	 * Sets the attribute to the specified value.
	 * @param name Attribute to set.
	 * @param value Value to apply to the attribute.
	 * @return Returns true if the attribute was found and the value was set, false otherwise.
	 */
	virtual daeBool setAttribute(daeString name, daeString value);

	/**
	 * Sets the attribute at the specified index to the given value.
	 * @param i Index of the attribute to set.
	 * @param value Value to apply to the attribute.
	 * @return Returns true if the attribute was found and the value was set, false otherwise.
	 */
	virtual daeBool setAttribute(size_t i, daeString value);

	/**
	 * Returns the daeMetaAttribute object corresponding to the character data for this element.
	 * @return Returns a daeMetaAttribute object or NULL if this element doesn't have
	 * character data.
	 */
	daeMetaAttribute* getCharDataObject();

	/**
	 * Checks if this element can have character data.
	 * @return Returns true if this element can have character data, false otherwise.
	 */
	daeBool hasCharData();

	/**
	 * Returns this element's character data as a string.
	 * @return A string containing this element's character data, or an empty string
	 * if this element can't have character data.
	 */
	std::string getCharData();

	/**
	 * Similar to the previous method, but fills a string passed in by the user for efficiency.
	 * @param data The string to be filled with this element's character content. The
	 * string is set to an empty string if this element can't have character data.
	 */
	void getCharData(std::string& data);

	/**
	 * Sets this element's character data.
	 * @param data The new character data of this element.
	 * @return Returns true if this element can have character data and the character data
	 * was successfully changed, false otherwise.
	 */
	daeBool setCharData(const std::string& data);

	// These functions are deprecated.
	daeMemoryRef getAttributeValue(daeString name); // Use getAttribute or getAttributeObject instead.
	daeBool hasValue(); // Use hasCharData instead.
	daeMemoryRef getValuePointer(); // Use getCharData or getCharDataObject instead.

	/**
	 * Finds the database document associated with @c this element.
	 * @return Returns the @c daeDocument representing the containing file or database
	 * group.
	 */
	daeDocument* getDocument() const { return _document; }

	/**
	 * Deprecated.
	 */
	daeDocument* getCollection() const { return _document; }

	/**
	 * Get the associated DAE object.
	 * @return The associated DAE object.
	 */
	DAE* getDAE();

	/**
	 * Sets the database document associated with this element.
	 * @param c The daeDocument to associate with this element.
	 */
	void setDocument(daeDocument* c) { setDocument( c, true ); }
	/**
	 * Deprecated.
	 */
	void setCollection(daeDocument* c );

	/**
	 * Gets the URI of the document containing this element, note that this is NOT the URI of the element.
	 * @return Returns a pointer to the daeURI of the document containing this element.
	 */
	daeURI*	getDocumentURI() const;

	/**
	 * Creates an element via the element factory system.  This creation
	 * is based @em only on potential child elements of this element.
	 * @param elementName Class name of the subelement to create.
	 * @return Returns the created @c daeElement, if it was successfully created.
	 */
	daeSmartRef<daeElement> createElement(daeString elementName);

	/**
	 * Gets the container element for @c this element.
	 * If @c createAndPlace() was used to create the element, its parent is the the caller of @c createAndPlace().
	 * @return Returns the parent element, if @c this is not the top level element.
	 */
	daeElement* getParentElement() { return _parent;}
	/**
	 * Deprecated. Use getParentElement()
	 * @deprecated
	 */
	daeElement* getXMLParentElement() { return _parent;}
	/**
	 * Sets the parent element for this element.
	 * @param newParent The element which is the new parent element for this element.
	 * @note This function is called internally and not meant to be called form the client application.
	 */
	void setParentElement( daeElement *parent ) { _parent = parent; }

	// These are helper structures to let the xml hierarchy search functions know when we've
	// found a match. You can implement a custom matcher by inheriting from this structure,
	// just like matchName and matchType.
	struct DLLSPEC matchElement {
		virtual bool operator()(daeElement* elt) const = 0;
		virtual ~matchElement() { };
	};

	// Matches an element by name
	struct DLLSPEC matchName : public matchElement {
		matchName(daeString name);
		virtual bool operator()(daeElement* elt) const;
		std::string name;
	};

	// Matches an element by schema type
	struct DLLSPEC matchType : public matchElement {
		matchType(daeInt typeID);
		virtual bool operator()(daeElement* elt) const;
		daeInt typeID;
	};

	// Returns a matching child element. By "child", I mean one hierarchy level beneath the
	// current element. This function is basically the same as getDescendant, except that it
	// only goes one level deep.
	daeElement* getChild(const matchElement& matcher);

	// Performs a breadth-first search and returns a matching descendant element. A "descendant
	// element" is an element beneath the current element in the xml hierarchy.
	daeElement* getDescendant(const matchElement& matcher);

	// Returns the parent element.
	daeElement* getParent();

	// Searches up through the xml hiearchy and returns a matching element.
	daeElement* getAncestor(const matchElement& matcher);

	// These functions perform the same as the functions above, except that they take the element
	// name to match as a string. This makes these functions a little simpler to use if you're
	// matching based on element name, which is assumed to be the most common case. Instead of
	// "getChild(matchName(eltName))", you can just write "getChild(eltName)".
	daeElement* getChild(daeString eltName);
	daeElement* getDescendant(daeString eltName);
	daeElement* getAncestor(daeString eltName);

	/**
	 * Gets the associated Meta information for this element.  This
	 * Meta also acts as a factory.  See @c daeMetaElement documentation for more
	 * information.
	 * @return Returns the associated meta information.
	 */
	inline daeMetaElement* getMeta() { return _meta; }

	// These functions are deprecated. Use typeID instead.
	virtual COLLADA_TYPE::TypeEnum getElementType() const { return (COLLADA_TYPE::TypeEnum)0; }
	daeString getTypeName() const;

	/**
	 * Returns this element's type ID. Every element is an instance of a type specified in
	 * the Collada schema, and every schema type has a unique ID.
	 * @return The element's type ID.
	 */
	virtual daeInt typeID() const = 0;

	/**
	 * Gets this element's name.
	 * @return Returns the string for the name.
	 * @remarks This function returns NULL if the element's name is identical to it's type's name.
	 */
	daeString getElementName() const;
	/**
	 * Sets this element's name.
	 * @param nm Specifies the string to use as the element's name.
	 * @remarks Use caution when using this function since you can easily create invalid COLLADA documents.
	 */
	void setElementName( daeString nm );

	/**
	 * Gets the element ID if it exists.
	 * @return Returns the value of the ID attribute, if there is such
	 * an attribute on this element type.
	 * @return the string for the element ID if it exists.
	 */
	daeString getID() const;

	/**
	 * Gets the children/sub-elements of this element.
	 * This is a helper function used to easily access an element's children without the use of the
	 * _meta objects.  This function adds the convenience of the _contents array to elements that do
	 * not contain a _contents array.
	 * @return The return value.  An elementref array to append this element's children to.
	 */
	daeTArray< daeSmartRef<daeElement> > getChildren();

	/**
	 * Same as the previous function, but returns the result via a parameter instead
	 * of a return value, for extra efficiency.
	 * @param array The return value.  An elementref array to append this element's children to.
	 */
	//void getChildren( daeElementRefArray &array );
	void getChildren( daeTArray<daeSmartRef<daeElement> > &array );

	/**
	 * Gets all the children of a particular type.
	 * @return An array containing the matching child elements.
	 */
	template<typename T>
	daeTArray< daeSmartRef<T> > getChildrenByType() {
		daeTArray< daeSmartRef<T> > result;
		getChildrenByType(result);
		return result;
	}

	/**
	 * Same as the previous function, but returns the result via a parameter instead
	 * of a return value, for extra efficiency.
	 * @return An array containing the matching child elements.
	 */
	template<typename T>
	void getChildrenByType(daeTArray< daeSmartRef<T> >& matchingChildren) {
		matchingChildren.setCount(0);
		daeTArray< daeSmartRef<daeElement> > children;
		getChildren(children);
		for (size_t i = 0; i < children.getCount(); i++)
			if (children[i]->typeID() == T::ID())
				matchingChildren.append((T*)children[i].cast());
	}

	/**
	 * Clones/deep copies this @c daeElement and all of it's subtree.
	 * @param idSuffix A string to append to the copied element's ID, if one exists.
	 *        Default is no ID mangling.
	 * @param nameSuffix A string to append to the copied element's name, if one exists.
	 *        Default is no name mangling.
	 * @return Returns a @c daeElement smartref of the copy of this element.
	 */
	daeSmartRef<daeElement> clone( daeString idSuffix = NULL, daeString nameSuffix = NULL );

	// Class for reporting info about element comparisons
	struct DLLSPEC compareResult {
		int compareValue; // > 0 if elt1 > elt2,
		                  // < 0 if elt1 < elt2,
		                  // = 0 if elt1 = elt2
		daeElement* elt1;
		daeElement* elt2;
		bool nameMismatch; // true if the names didn't match
		std::string attrMismatch; // The name of the mismatched attribute, or "" if there was no attr mismatch
		bool charDataMismatch; // true if the char data didn't match
		bool childCountMismatch; // true if the number of children didn't match

		compareResult();
		std::string format(); // Write to a string
	};

	// Function for doing a generic, recursive comparison of two xml elements. It
	// also provides a full element ordering, so that you could store elements in
	// a map or a set. Return val is > 0 if elt1 > elt2, < 0 if elt1 < elt2, and 0
	// if elt1 == elt2.
	static int compare(daeElement& elt1, daeElement& elt2);

	// Same as the previous function, but returns a full compareResult object.
	static compareResult compareWithFullResult(daeElement& elt1, daeElement& elt2);

	/**
	 * Sets the user data pointer attached to this element.
	 * @param data User's custom data to store.
	 */
	void setUserData(void* data);

	/**
	 * Gets the user data pointer attached to this element.
	 * @return User data pointer previously set with setUserData.
	 */
	void* getUserData();

public:
	// This function is called internally
	static void deleteCMDataArray(daeTArray<daeCharArray*>& cmData);
};

#include <dae/daeSmartRef.h>
typedef daeSmartRef<daeElement> daeElementRef;
typedef daeSmartRef<const daeElement> daeElementConstRef;
//#include <dae/daeArray.h>
typedef daeTArray<daeElementRef> daeElementRefArray;

#endif //__DAE_ELEMENT_H__