1 /* 2 * Copyright 2006 Sony Computer Entertainment Inc. 3 * 4 * Licensed under the MIT Open Source License, for details please see license.txt or the website 5 * http://www.opensource.org/licenses/mit-license.php 6 * 7 */ 8 9 #ifndef __DAE_META_ELEMENT_H__ 10 #define __DAE_META_ELEMENT_H__ 11 12 #include <dae/daeTypes.h> 13 #include <dae/daeArrayTypes.h> 14 #include <dae/daeElement.h> 15 #include <dae/daeMetaAttribute.h> 16 #include <dae/daeRefCountedObj.h> 17 18 class DAE; 19 class daeMetaCMPolicy; 20 class daeMetaElementArrayAttribute; 21 22 typedef daeElementRef (*daeElementConstructFunctionPtr)(DAE& dae); 23 24 /** 25 * Each instance of the @c daeMetaElement class describes a C++ COLLADA dom 26 * element type. 27 * @par 28 * The meta information in @c daeMetaElement is a combination of the information 29 * required to create and maintain C++ object instances and 30 * the information necessary to parse and construct a hierarchy of COLLADA 31 * elements. 32 * @par 33 * @c daeMetaElement objects also act as factories for C++ COLLADA dom classes where 34 * each @c daeElement is capable of creating an instance of the class it describes. 35 * Further, each @c daeMetaElement contains references to other @c daeMetaElements 36 * for potential XML children elements. This enables this system to easily 37 * create @c daeElements of the appropriate type while navigating through XML 38 * recursive parse. 39 * @par 40 * See @c daeElement for information about the functionality that every @c daeElement implements. 41 */ 42 class daeMetaElement : public daeRefCountedObj 43 { 44 protected: 45 daeStringRef _name; 46 47 daeElementConstructFunctionPtr _createFunc; 48 daeInt _elementSize; 49 50 daeMetaAttributeRefArray _metaAttributes; 51 daeMetaAttributeRef _metaValue; 52 daeMetaElementArrayAttribute* _metaContents; 53 daeMetaArrayAttribute* _metaContentsOrder; 54 55 daeMetaAttributeRef _metaID; 56 57 daeBool _isTrackableForQueries; 58 daeBool _usesStringContents; 59 60 daeBool _isTransparent; 61 daeBool _isAbstract; 62 daeBool _allowsAny; 63 daeBool _innerClass; 64 65 daeMetaCMPolicy* _contentModel; 66 daeMetaArrayAttribute* _metaCMData; 67 daeUInt _numMetaChoices; 68 69 DAE& dae; 70 71 public: 72 /** 73 * Constructor 74 */ 75 DLLSPEC daeMetaElement(DAE& dae); 76 77 /** 78 * Destructor 79 */ 80 DLLSPEC ~daeMetaElement(); 81 82 public: // public accessors 83 84 /** 85 * Gets the DAE object that owns this daeMetaElement. 86 * @return Returns the owning DAE. 87 */ 88 DAE* getDAE(); 89 90 /** 91 * Determines if elements of this type is an inner class. 92 * @return Returns true if this element type is an inner class. 93 */ getIsInnerClass()94 daeBool getIsInnerClass() { return _innerClass; } 95 /** 96 * Sets if elements of this type are inner classes. 97 * @param abstract True if this type is an inner class. 98 */ setIsInnerClass(daeBool ic)99 void setIsInnerClass( daeBool ic ) { _innerClass = ic; } 100 /** 101 * Determines if elements of this type can be placed in the object model. 102 * @return Returns true if this element type is abstract, false otherwise. 103 */ getIsAbstract()104 daeBool getIsAbstract() { return _isAbstract; } 105 /** 106 * Determines if elements of this type should have an element tag printed when saving. 107 * @return Returns true if this element type should not have a tag, false otherwise. 108 */ getIsTransparent()109 daeBool getIsTransparent() { return _isTransparent; } 110 /** 111 * Sets if elements of this type are abstract. 112 * @param abstract True if this type is abstract. 113 */ setIsAbstract(daeBool abstract)114 void setIsAbstract( daeBool abstract ) { _isAbstract = abstract; } 115 /** 116 * Sets whether or not elements of this type should have an element tag printed when saving. 117 * @param transparent True if this type is transparent. 118 */ setIsTransparent(daeBool transparent)119 void setIsTransparent( daeBool transparent ) { _isTransparent = transparent; } 120 121 /** 122 * Determines if elements of this type should be tracked 123 * for daeDatabase queries. 124 * @return Returns true if this element type should be tracked 125 */ getIsTrackableForQueries()126 daeBool getIsTrackableForQueries() { return _isTrackableForQueries; } 127 128 /** 129 * Sets whether elements of this type should be tracked 130 * for @c daeDatabase queries. 131 * @param trackable Indicates whether this element should be tracked. 132 * A value of true indicates this element type should be tracked and be available for 133 * database queries. 134 */ setIsTrackableForQueries(daeBool trackable)135 void setIsTrackableForQueries(daeBool trackable) { 136 _isTrackableForQueries = trackable; } 137 138 /** 139 * Determines if elements of this type allow for any element as a child. 140 * @return Returns true if this element can have any child element, false otherwise. 141 */ getAllowsAny()142 daeBool getAllowsAny() { return _allowsAny; } 143 /** 144 * Sets if elements of this type allow for any element as a child. 145 * @param allows True if this element allows for any child element, false otherwise. 146 */ setAllowsAny(daeBool allows)147 void setAllowsAny( daeBool allows ) { _allowsAny = allows; } 148 149 /** 150 * Gets the @c daeMetaAttribute for the non-element contents of a @c daeElement. 151 * This corresponds to a @c daeMetaFloatAttribute, @c daeMetaFloatArrayAttribute, 152 * et cetera. 153 * @return Returns the @c daeMetaAttribute pointer for the non-element contents of 154 * this element type. 155 */ getValueAttribute()156 daeMetaAttribute* getValueAttribute() { return _metaValue; } 157 158 /** 159 * Gets the @c daeMetaAttribute for the ID attribute of a @c daeElement. 160 * @return Returns the ID @c daeMetaAttribute, or NULL if the element type 161 * does not have an ID attribute. 162 */ getIDAttribute()163 daeMetaAttribute* getIDAttribute() { return _metaID; } 164 165 /** 166 * Gets the name of this element type. 167 * @return Returns the name of this element type. 168 */ getName()169 daeStringRef getName() { return _name; } 170 171 /** 172 * Sets the name of this element type. 173 * @param s String name to set. 174 */ setName(daeString s)175 void setName(daeString s) { _name = s; } 176 177 /** 178 * Gets the array of all known attributes on this element type. 179 * This includes all meta attributes except those describing child 180 * elements. It does include the value element. 181 * @return Returns the array of @c daeMetaAttributeRefs. 182 */ getMetaAttributes()183 daeMetaAttributeRefArray& getMetaAttributes() { 184 return _metaAttributes; } 185 186 /** 187 * Gets the attribute which has a name as provided by the <tt><i>s</i></tt> parameter. 188 * @param s String containing the desired attribute's name. 189 * @return Returns the corresponding @c daeMetaAttribute, or NULL if none found. 190 */ 191 DLLSPEC daeMetaAttribute* getMetaAttribute(daeString s); 192 193 /** 194 * Sets the size in bytes of each instance of this element type. 195 * Used for factory element creation. 196 * @param size Number of bytes for each C++ element instance. 197 */ setElementSize(daeInt size)198 void setElementSize(daeInt size) {_elementSize = size;} 199 200 /** 201 * Gets the size in bytes of each instance of this element type. 202 * Used for factory element creation. 203 * @return Returns the number of bytes for each C++ element instance. 204 */ getElementSize()205 daeInt getElementSize() { return _elementSize;} 206 207 public: 208 /** 209 * Registers with the reflective object system that the dom class described by this @c daeMetaElement 210 * contains a <tt><i>_contents</i></tt> array. This method is @em only for @c daeMetaElement contstuction, and 211 * should only be called by the system as it sets up the Reflective Object System. 212 * @param offset Byte offset for the contents field in the C++ element class. 213 */ 214 DLLSPEC void addContents(daeInt offset); 215 /** 216 * Registers with the reflective object system the array that stores the _contents ordering. This method is @em 217 * only for @c daeMetaElement contstuction, and should only be called by the system as it sets up the Reflective 218 * Object System. 219 * @param offset Byte offset for the contents order array in the C++ element class. 220 */ 221 DLLSPEC void addContentsOrder( daeInt offset ); 222 /** 223 * Registers with the reflective object system that the dom class described by this @c daeMetaElement 224 * contains at least one choice group in the content model for this element. This method is @em only 225 * for @c daeMetaElement contstuction, and should only be called by the system as it sets up the 226 * Reflective Object System. 227 * @param offset Byte offset for the contents field in the C++ element class. 228 * @param numChoices The number of choice content model blocks there are for this element type. 229 */ 230 DLLSPEC void addCMDataArray( daeInt offset, daeUInt numChoices ); 231 232 /** 233 * Gets the attribute associated with the contents meta information. 234 * @see @c addContents() 235 * @return Returns the @c daeMetaElementArrayAttribute. 236 */ getContents()237 daeMetaElementArrayAttribute* getContents() { return _metaContents; } 238 /** 239 * Gets the attribute associated with the CMData array meta information. 240 * @see @c addCMDataArray() 241 * @return Returns the @c daeMetaArrayAttribute for the CMData of an element. 242 */ getMetaCMData()243 daeMetaArrayAttribute* getMetaCMData() { return _metaCMData; } 244 /** 245 * Gets the number of choice content model blocks there are for this element type. 246 * @return Returns the number of daeMetaChoice's there are in the content model. 247 */ getNumChoices()248 daeUInt getNumChoices() const { return _numMetaChoices; } 249 250 /** 251 * Appends a @c daeMetaAttribute that represents a field corresponding to an 252 * XML attribute to the C++ version of this element type. 253 * @param attr Attribute to append to this element types list 254 * of potential attributes. 255 */ 256 DLLSPEC void appendAttribute(daeMetaAttribute* attr); 257 258 /** 259 * Registers the function that can construct a C++ instance of this class. 260 * Necessary for the factory system such that C++ can still call @c new and the 261 * @c vptr will still be initialized even when constructed via the factory system. 262 * @param func Pointer to a function that does object construction. 263 */ registerClass(daeElementConstructFunctionPtr func)264 void registerClass(daeElementConstructFunctionPtr func) { 265 _createFunc = func; } 266 267 /** 268 * Validates this class to be used by the runtime c++ object model 269 * including factory creation. 270 */ 271 DLLSPEC void validate(); 272 273 /** 274 * Places a child element into the <tt><i>parent</i></tt> element where the 275 * calling object is the @c daeMetaElement for the parent element. 276 * @param parent Element to act as the container. 277 * @param child Child element to place in the parent. 278 * @return Returns true if the operation was successful, false otherwise. 279 */ 280 DLLSPEC daeBool place(daeElement *parent, daeElement *child, daeUInt *ordinal = NULL); 281 /** 282 * Places a child element into the <tt><i>parent</i></tt> element at a specific location 283 * where the calling object is the @c daeMetaElement for the parent element. 284 * @param index The location in the contents array to insert. 285 * @param parent Element to act as the container. 286 * @param child Child element to place in the parent. 287 * @return Returns true if the operation was successful, false otherwise. 288 * @note This should only be called on elements that have a _contents array. Elements without 289 * a _contents array will be placed normally. 290 */ 291 DLLSPEC daeBool placeAt( daeInt index, daeElement *parent, daeElement *child ); 292 /** 293 * Places a child element into the <tt><i>parent</i></tt> element at a specific location which is right 294 * before the marker element. 295 * @param marker The element location in the contents array to insert before. 296 * @param parent Element to act as the container. 297 * @param child Child element to place in the parent. 298 * @return Returns true if the operation was successful, false otherwise. 299 */ 300 DLLSPEC daeBool placeBefore( daeElement* marker, daeElement *parent, daeElement *child, daeUInt *ordinal = NULL ); 301 /** 302 * Places a child element into the <tt><i>parent</i></tt> element at a specific location which is right 303 * after the marker element. 304 * @param marker The element location in the contents array to insert after. 305 * @param parent Element to act as the container. 306 * @param child Child element to place in the parent. 307 * @return Returns true if the operation was successful, false otherwise. 308 */ 309 DLLSPEC daeBool placeAfter( daeElement* marker, daeElement *parent, daeElement *child, daeUInt *ordinal = NULL ); 310 311 /** 312 * Removes a child element from its parent element. 313 * @param parent Element That is the parent. 314 * @param child Child element to remove. 315 * @return Returns true if the operation was successful, false otherwise. 316 */ 317 DLLSPEC daeBool remove( daeElement *parent, daeElement *child ); 318 /** 319 * Gets all of the children from an element of this type. 320 * @param parent The element that you want to get the children from. 321 * @param array The return value. An elementref array to append this element's children to. 322 */ 323 DLLSPEC void getChildren( daeElement* parent, daeElementRefArray &array ); 324 325 /** 326 * Invokes the factory element creation routine set by @c registerConstructor() 327 * to return a C++ COLLADA Object Model instance of this element type. 328 * @return Returns a created @c daeElement of appropriate type via the 329 * object creation function and the <tt> daeElement::setup() </tt> function. 330 */ 331 DLLSPEC daeElementRef create(); 332 333 /** 334 * Looks through the list of potential child elements 335 * for this element type finding the corresponding element type; if a corresponding element type 336 * is found, use that type as a factory and return an instance of that 337 * child type. Typically @c place() is called after @c create(childelementname) 338 * @param childElementTypeName Type name to create. 339 * @return Returns the created element if the type was found as a potential child element. 340 */ 341 DLLSPEC daeElementRef create(daeString childElementTypeName); 342 343 /** 344 * Gets the root of the content model policy tree. 345 * @return Returns the root element of the tree of content model policy elements. 346 */ getCMRoot()347 daeMetaCMPolicy *getCMRoot() { return _contentModel; } 348 /** 349 * Sets the root of the content model policy tree. 350 * @param cm The root element of the tree of content model policy elements. 351 */ 352 DLLSPEC void setCMRoot( daeMetaCMPolicy *cm ); 353 }; 354 355 typedef daeSmartRef<daeMetaElement> daeMetaElementRef; 356 typedef daeTArray<daeMetaElementRef> daeMetaElementRefArray; 357 358 #endif //__DAE_META_ELEMENT_H__ 359 360 361 362 363 364