Difference between revisions of "DOM guide: Working with elements"

From COLLADA Public Wiki
Jump to: navigation, search
(Navigating the Object Model: rewrite based on Talk page discussion)
m (Navigating the Object Model: typo)
Line 26: Line 26:
 
*'''getDocumentURI''' is a helper method if you need only the document's name.
 
*'''getDocumentURI''' is a helper method if you need only the document's name.
  
*'''getParentElement''' returns the parent element, which allows you to traverse up the tree to the root. If this method returns NULL, the element is the root of the tree. If the root element belongs to a document ('''getDocument''' or getDocumentURI''' are non-NULL) then it is safe to assume that the element is a '''domCOLLADA''' element, which is an element that is the root of a COLLADA document.
+
*'''getParentElement''' returns the parent element, which allows you to traverse up the tree to the root. If this method returns NULL, the element is the root of the tree. If the root element belongs to a document ('''getDocument''' or '''getDocumentURI''' are non-NULL) then it is safe to assume that the element is a '''domCOLLADA''' element, which is an element that is the root of a COLLADA document.
  
 
*'''getChildren''' populates an array with the children of an element. This allows you to iterate over all the children of an element and traverse down the element hierarchy. This array is ordered the same as it would be if the element were written to a [[COLLADA instance document]]. This array is the same as the '''_contents''' array, if an element's type has a '''_contents''' array.
 
*'''getChildren''' populates an array with the children of an element. This allows you to iterate over all the children of an element and traverse down the element hierarchy. This array is ordered the same as it would be if the element were written to a [[COLLADA instance document]]. This array is the same as the '''_contents''' array, if an element's type has a '''_contents''' array.

Revision as of 19:39, 27 March 2007

daeElement is the base class for all COLLADA Object Model classes. The daeElement class uses the Reflective Object System (ROS) to provide considerable functionality without the need to use the generated subclass.

Determining an Element's Type

There are three approaches to determining the type of a daeElement:

  • Using the daeElement::getElementType method, which returns an enumerated value respresenting the element's type. The values returned by this function are in the dom/domTypes.h header. This is the easiest approach.
  • Using the daeElement::getTypeName method, which returns a daeString containing the type name. To determine the type, compare this string with the constant strings defined in dom/domConstants.h.
  • By comparing _meta. The _meta is a pointer to a daeMetaElement, which is the class that contains all the ROS information for an element type. By doing a pointer comparison on daeElement::getMeta and the generated class's static dom*::_Meta, it is possible to find the element type. This is the approach that the daeSafeCast method uses to ensure type safety. (See also: DOM meta system.)

NOTE: The daeSafeCast and daeElement::getElementType approaches are newer additions to the COLLADA DOM. When looking at older source code using the DOM, expect to see the older methods used frequently for type checking.

Determining an Element's Name

Use the daeElement:getElementName method to retrieve the name of an element. The element name is the XML tag that would be present in a COLLADA instance document. For the majority of elements in the COLLADA DOM, getElementName returns NULL, indicating that the element's name is the same as its type name, available from daeElement::getTypeName.

Accessing Element Data

The easist way to access element data is to cast the daeElement to its strongly typed subclass. However, at times, it might not be possible to do the cast or it might be more convenient not to cast. The daeElement class provides methods to access and manipulate data directly for such situations.

Navigating the Object Model

daeElement provides the following methods for accessing various information about an element:

  • getDocument provides access to the COLLADA document that the element belongs to.
  • getDocumentURI is a helper method if you need only the document's name.
  • getParentElement returns the parent element, which allows you to traverse up the tree to the root. If this method returns NULL, the element is the root of the tree. If the root element belongs to a document (getDocument or getDocumentURI are non-NULL) then it is safe to assume that the element is a domCOLLADA element, which is an element that is the root of a COLLADA document.
  • getChildren populates an array with the children of an element. This allows you to iterate over all the children of an element and traverse down the element hierarchy. This array is ordered the same as it would be if the element were written to a COLLADA instance document. This array is the same as the _contents array, if an element's type has a _contents array.

Accessing Attributes

The daeElement class provides many functions for accessing the attributes that an element may have:

  • setAttribute takes both the attribute name and the new value as a string arguments. The COLLADA DOM converts the value from string to the data type of the attribute. This method returns false if the element does not have an attribute with the specified name.
  • hasAttribute queries the existence of an attribute.
  • isAttributeSet returns true if the attribute exists and has been set. The attribute can be set when loading the document or programmatically. Attributes with default values are always considered set.
  • getAttributeValue returns a byte pointer to the memory used to store the specified attribute. The client application is responsible for type casting this pointer to the appropriate type before using it. One common mistake occurs when dealing with string attributes. Remember that this function returns a pointer to the data and that daeString is a pointer itself, therefore this function returns a pointer to a pointer.

Accessing the Value

  • The daeElement::hasValue method is used to query if an element has a value.
  • The daeElement::getValuePointer method works the same as daeElement::getAttributeValue except that it returns a pointer to the value field.