Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Changes between Version 8 and Version 9 of code/doc/Identifier


Ignore:
Timestamp:
Sep 28, 2008, 7:17:36 PM (16 years ago)
Author:
landauf
Comment:

—

Legend:

Unmodified
Added
Removed
Modified

  • code/doc/Identifier

    v8 v9  
    11= Identifier =
    22[[TracNav(TracNav/TOC_Development)]]
     3[[TOC]]
    34
    45== Description ==
    56
    6 The [wiki:Identifier] is a construct to identify the class of an object. All classes derived from OrxonoxClass have an Identifier, representing the class in the running game. The Identifier additionally stores all objects of its class in a [wiki:ObjectList list], knows the name of the class, can have a [wiki:ClassFactory], knows all parents and children, stores [wiki:ConfigValueContainer config-values] and shell-functions and provides several other functionalities.
     7The Identifier is a construct to identify the class of an object at runtime. All classes derived from OrxonoxClass have an Identifier. The Identifier additionally stores all objects of its class in a [wiki:ObjectListBase list], knows the name of the class, can have a [wiki:ClassFactory], knows all parents and children, stores [wiki:ConfigValueContainer config-values], [wiki:XMLPort XMLPort-containers], [wiki:ConsoleCommand console-commands] and provides several other functionalities.
    78
    8 You can get the Identifier of a given class with the macro Class(classname). If you only know the string, so if the class isn't hardcoded, use the macro ID("classname"). You have to include [wiki:CoreIncludes CoreIncludes.h] to use the macros.
     9== Usage ==
     10=== Identifier of a class ===
     11You can get the Identifier of a given class with the macro '''Class('''''classname''''')'''. If you only know the string, so if the class isn't hardcoded, use the macro '''ClassByString('''''"classname"''''')'''. You have to include [wiki:CoreIncludes CoreIncludes.h] to use the macros.
    912
    10 A new class that wants an Identifier must use a macro (!RegisterObject(classname) or !RegisterRootObject(interfacename)) from [wiki:CoreIncludes]. Read the related Wiki-page for more information.
     13{{{
     14#include "core/CoreIncludes.h"
    1115
    12 [wiki:Identifier Identifiers] can be compared by using functions like isA(...) or isChildOf(...) to retrieve information about the class-hierarchy.
     16// Variant 1:
     17Identifier* identifierOfMyClass = Class(MyClass);
    1318
    14 You can't create an Identifier directly, because it's an abstract class. There only exist [wiki:ClassIdentifier ClassIdentifiers], but you can't create them too, because they have private constructors. Identifiers are created by [wiki:IdentifierDistributor], a helper class to warrant the uniqueness of an Identifier for a class.
     19// Variant 2:
     20std::string classname = "OtherClass";
     21Identifier* identifierOfOtherClass = ClassByString(classname);
     22}}}
    1523
    16 The [wiki:SubclassIdentifier] is a class, that can store and act like an Identifier, but has a given base-class. Read the related Wiki-page for more information.
     24=== Identifier of an object ===
     25To retrieve the Identifier of an object, use object->'''getIdentifier()''':
     26{{{
     27OrxonoxClass* object = new SomeClass();
     28Identifier* identifierOfSomeClass = object->getIdentifier();
     29}}}
    1730
    18 == Functions ==
     31=== Name of a class ===
     32Use '''getName()''':
     33{{{
     34OrxonoxClass* object = new SomeClass();
     35object->getIdentifier()->getName(); // returns "SomeClass"
    1936
    20  * '''Macro''': (Include [wiki:CoreIncludes CoreIncludes.h] to use this)
    21    * Identifier* myidentifier = Class(BaseObject);
    22    * Identifier* myidentifier = ID("BaseObject");
     37Class(MyClass)->getName(); // returns "MyClass"
     38}}}
    2339
    24  * '''Comparison''':
    25    * ''myidentifier'''''->isA('''''other''''')''': Compares the Identifier (''myidentifier'') with another Identifier (''other''). If ''myidentifier'' represents exactly the same or an inheriting class, the function returns true.
    26    * ''myidentifier'''''->isExactlyA('''''other''''')''': If ''myidentifier'' and ''other'' represent both the same class, the function returns true.
    27    * ''myidentifier'''''->isChildOf('''''other''''')''': If the class represented by ''myidentifier'' is a child of the class represented by ''other'', the function returns true.
    28    * ''myidentifier'''''->isDirectChildOf('''''other''''')''': Like isChildOf(...), but the class represented by ''myidentifier'' must be inherited directly without other classes between (class ''myidentifierclass'' : public ''otherclass'').
    29    * ''myidentifier'''''->isParentOf('''''other''''')''': If the class represented by ''myidentifier'' is a parent of the class represented by ''other'', meaning the other class is a child, the function returns true.
    30    * ''myidentifier'''''->isDirectParentOf('''''other''''')''': Like isParentOf(...), but the class represented by ''myidentifier'' must be a direct parent without other classes between (class ''otherclass'' : public ''myidentifierclass'').
     40=== New classes ===
     41A new class that wants an Identifier must call RegisterObject(classname) in the constructor. A new interface has to inherit virtually from [wiki:OrxonoxClass] and call RegisterRootObject(interfacename) from in the constructor. Both macros are located in [wiki:CoreIncludes]. Read the related Wiki-page for more information.
    3142
    32  * '''Fabricate''':
    33    * fabricate() returns a new object of the class represented by the Identifier (see [wiki:ClassFactory]).
     43{{{
     44#include "core/CoreIncludes.h"
    3445
    35  * '''Name''':
    36    * getName() returns the name of the represented class.
     46// Constructor:
     47MyClass::MyClass()
     48{
     49    RegisterObject(MyClass);
     50}
     51}}}
    3752
    38  * '''Class-hierarchy''': You can retrieve lists and iterators (begin and end) of:
    39    * '''parents''': getParents(), getParentsBegin(), getParentsEnd()
    40    * '''directParents''': getDirectParents(), getDirectParentsBegin(), getDirectParentsEnd()
    41    * '''children''': getChildren(), getChildrenBegin(), getChildrenEnd()
    42    * '''directChildren''': getDirectChildren(), getDirectChildrenBegin(), getDirectChildrenEnd()
     53=== Creating an object with fabricate() ===
     54You can create an object of a class represented by an Identifier by calling fabricate(). This function creates a new instance and returns a [wiki:BaseObject] pointer.
     55
     56'''Important''': If you have to cast the BaseObject-pointer to the real class, use '''dynamic_cast'''.
     57{{{
     58Identifier* identifier = Class(MyClass);
     59
     60// Create an instance of MyClass:
     61BaseObject* object = identifier->fabricate();
     62
     63// Cast the pointer from BaseObject to MyClass:
     64MyClass* object2 = dynamic_cast<MyClass*>(object);
     65}}}
     66
     67=== Comparison ===
     68Different Identifiers can be compared by using functions like isA(...) or isChildOf(...) to retrieve information about the class-hierarchy:
     69
     70 * ''myidentifier'''''->isA('''''other''''')''': Compares the Identifier (''myidentifier'') with another Identifier (''other''). If ''myidentifier'' represents exactly the same or an inheriting class, the function returns true.
     71 * ''myidentifier'''''->isExactlyA('''''other''''')''': If ''myidentifier'' and ''other'' represent both the same class, the function returns true.
     72 * ''myidentifier'''''->isChildOf('''''other''''')''': If the class represented by ''myidentifier'' is a child of the class represented by ''other'', the function returns true.
     73 * ''myidentifier'''''->isDirectChildOf('''''other''''')''': Like isChildOf(...), but the class represented by ''myidentifier'' must be inherited directly without other classes between (class ''myidentifierclass'' : public ''otherclass'').
     74 * ''myidentifier'''''->isParentOf('''''other''''')''': If the class represented by ''myidentifier'' is a parent of the class represented by ''other'', meaning the other class is a child, the function returns true.
     75 * ''myidentifier'''''->isDirectParentOf('''''other''''')''': Like isParentOf(...), but the class represented by ''myidentifier'' must be a direct parent without other classes between (class ''otherclass'' : public ''myidentifierclass'').
     76
     77A more graphical explanation:
     78{{{
     79#!html
     80<span style="color:#008000;">Green:</span> If you call <b>comparisonFunction(Class(MyClass))</b> on a <span style="color:#008000;">green</span> class, the function returns true.<br />
     81<span style="color:#A00000;">Red:</span> If you call <b>comparisonFunction(Class(MyClass))</b> on a <span style="color:#A00000;">red</span> class, the function returns false.<br />
     82<br />
     83comparisionFunction is either isA, isExactlyA, isChildOf, isDirectChildOf, isParentOf or isDirectParentOf.<br />
     84<br />
     85<table><tr><td>
     86<b>isA</b>(MyClass):</td><td>
     87<span style="color:#A00000;">ParentOfParent</span> | <span style="color:#A00000;">Parent</span> | <b>[</b><span style="color:#008000;">MyClass</span> | <span style="color:#008000;">Child</span> | <span style="color:#008000;">ChildOfChild</span><b>]</b><br />
     88</td></tr><tr><td>
     89<b>isExactlyA</b>(MyClass):</td><td>
     90<span style="color:#A00000;">ParentOfParent</span> | <span style="color:#A00000;">Parent</span> | <b>[</b><span style="color:#008000;">MyClass</span><b>]</b> | <span style="color:#A00000;">Child</span> | <span style="color:#A00000;">ChildOfChild</span><br />
     91</td></tr><tr><td>
     92<b>isChildOf</b>(MyClass):</td><td>
     93<span style="color:#A00000;">ParentOfParent</span> | <span style="color:#A00000;">Parent</span> | <span style="color:#A00000;">MyClass</span> | <b>[</b><span style="color:#008000;">Child</span> | <span style="color:#008000;">ChildOfChild</span><b>]</b><br />
     94</td></tr><tr><td>
     95<b>isDirectChildOf</b>(MyClass):</td><td>
     96<span style="color:#A00000;">ParentOfParent</span> | <span style="color:#A00000;">Parent</span> | <span style="color:#A00000;">MyClass</span> | <b>[</b><span style="color:#008000;">Child</span><b>]</b> | <span style="color:#A00000;">ChildOfChild</span><br />
     97</td></tr><tr><td>
     98<b>isParentOf</b>(MyClass):</td><td>
     99<b>[</b><span style="color:#008000;">ParentOfParent</span> | <span style="color:#008000;">Parent</span><b>]</b> | <span style="color:#A00000;">MyClass</span> | <span style="color:#A00000;">Child</span> | <span style="color:#A00000;">ChildOfChild</span><br />
     100</td></tr><tr><td>
     101<b>isDirectParentOf</b>(MyClass):</td><td>
     102<span style="color:#A00000;">ParentOfParent</span> | <b>[</b><span style="color:#008000;">Parent</span><b>]</b> | <span style="color:#A00000;">MyClass</span> | <span style="color:#A00000;">Child</span> | <span style="color:#A00000;">ChildOfChild</span><br />
     103</td></tr></table>
     104}}}
     105
     106=== More Functions ===
     107'''Hierarchy''': Every Identifier provides sets of all parents and children:
     108 * getParents()
     109 * getChildren()
     110 * getDirectParents()
     111 * getDirectChildren()
     112
     113'''Identifiers''': There is also a static map containg all existing Identifiers:
     114 * Identifier::getIdentifierMap()
     115 * Identifier::getLowercaseIdentifierMap()
     116
     117'''ConfigValues''': Every Identifier stores the [wiki:ConfigValueContainer config-values] of the class:
     118 * getConfigValueMap()
     119 * getLowercaseConfigValueMap()
     120 * hasConfigValues()
     121
     122'''ConsoleCommands''': Also, Identifiers store the [wiki:ConsoleCommand console-commands] of the class:
     123 * getConsoleCommandMap()
     124 * getLowercaseConsoleCommandMap()
     125 * hasConsoleCommands()
     126
     127'''XMLPort Params''': The same for [wiki:XMLPort XMLPort params]:
     128 * getXMLPortParamMap
     129
     130'''XMLPort Objects''': And [wiki:XMLPort XMLPort objects]:
     131 * getXMLPortObjectMap
     132
     133== Class Identifier ==
     134Every Identifier is in fact a [wiki:ClassIdentifier]. Identifier itself is the abstract baseclass of !ClassIdentifier. ClassIdentifier is a template. This is needed to take care of the class-specific parts of the Identifier. Read the related Wiki-page for more information.
     135
     136== Subclass Identifier ==
     137The [wiki:SubclassIdentifier] is a class, that can act like an Identifier, but has a given base-class. Read the related Wiki-page for more information.
    43138
    44139== Examples ==
    … …  
    74169// Creates a new instance of A1 and casts it to Interface1
    75170Identifier* myidentifier = Class(A3);
    76 Interface1* newobject = (Interface1)(myidentifier->fabricate());
    77 }}}
    78 
    79 {{{
    80 #!cpp
    81 Identifier* myidentifier = Class(BaseObject);
    82 for (std::list<const Identifier*>::const_iterator it = myidentifier->getDirectChildrenBegin(); it != myidentifier->getDirectChildrenEnd(); ++it)
    83   cout << (*it)->getName() << std::endl;
    84 
    85 /*
    86 returns all direct children of BaseObject:
    87 A1
    88 A2
    89 A3
    90 */
     171Interface1* newobject = dynamic_cast<Interface1*>(myidentifier->fabricate());
    91172}}}
    92173