Changeset 7401 for code/trunk/src/libraries/core/ClassTreeMask.h

Timestamp:

Sep 11, 2010, 12:34:00 AM (14 years ago)

Author:

landauf

Message:

merged doc branch back to trunk

Location:

code/trunk

Files:

• . (modified) (1 prop)
• src/libraries/core/ClassTreeMask.h (modified) (15 diffs)

code/trunk/src/libraries/core/ClassTreeMask.h

@@ -29 +29 @@
 /**
     @file
-    @brief Definition of the ClassTreeMask, ClassTreeMaskNode and ClassTreeMaskIterator classes.
-
-    ClassTreeMask is a class to define a mask of the class-tree beginning with BaseObject.
+    @ingroup Class
+    @brief Declaration of the ClassTreeMask, ClassTreeMaskNode, and ClassTreeMaskIterator classes.
+
+    ClassTreeMask is a class to define a mask of the class-tree beginning with orxonox::BaseObject.
     You can include or exclude classes by calling the corresponding functions with the
-    Identifier of the class.
+    orxonox::Identifier of the class. This mask can then be used to filter out objects that
+    are instances of classes which aren't included in the tree, for example when Loading a
+    level file or if a Trigger should be triggered by only a few classes.
+
+    See the description of orxonox::ClassTreeMask for a short example.
 
     You can work with a ClassTreeMask in the sense of the set-theory, meaning that you can create
     unions, intersections, complements and differences by using overloaded operators.
 
-
+    @par Tree structure
 
     The ClassTreeMask is internally represented by a tree. The nodes in the tree are
@@ -45 +50 @@
     nodes changing the mask. By adding new rules, the tree gets reordered dynamically.
 
-    Adding a new rule overwrites all rules assigned to inherited classes. Use overwrite = false
+    Adding a new rule overwrites all rules assigned to inherited classes. Use <tt>overwrite = false</tt>
     if you don't like this feature. Useless rules that don't change the information of the mask
-    aren't saved in the internal tree. Use clean = false if you wan't to save them.
-
-    With overwrite = false and clean = false it doesn't matter in which way you create the mask.
-    You can manually drop useless rules from the tree by calling clean().
-
-
-
-    Because of the complicated shape of the internal tree, there is an iterator to iterate
-    through all ClassTreeMaskNodes of a mask. It starts with the BaseObject and moves on to
-    the first subclass until it reaches a leaf of the tree. Then the iterator moves one step
-    back and iterates to the second subclass. If there are no more subclasses, it steps another
-    step back, and so on.
-
-    Example: A and B are children of BaseObject, A1 and A2 are children of A, B1 and B2 are children of B.
-    The ClassTreeMaskIterator would move trough the tree in the following order:
-    BaseObject, A, A1, A2, B, B1, B2.
-
-    Note that the iterator doesn't move trough the whole class-tree, but only through the
-    internal tree of the mask, containing the minimal needed set of nodes to describe the mask.
+    aren't saved in the internal tree. Use <tt>clean = false</tt> if you still want to save them.
+
+    With <tt>overwrite = false</tt> and <tt>clean = false</tt> it doesn't matter in which order
+    you create the mask. You can manually drop useless rules from the tree by calling
+    @ref orxonox::ClassTreeMask::clean() "clean()".
+
+    @par Objects
+
+    To iterate through all objects of the classes that were included by a ClassTreeMask,
+    use orxonox::ClassTreeMaskObjectIterator. The description of this class also contains
+    a short example of how to use it.
 */
 
@@ -83 +80 @@
     // ###      ClassTreeMaskNode      ###
     // ###################################
-    //! The ClassTreeMaskNode is a node in the internal tree of the ClassTreeMask, containing the rules of the mask.
     /**
+        @brief The ClassTreeMaskNode is a node in the internal tree of the ClassTreeMask, containing the rules of the mask.
+
         The ClassTreeMaskNode is used to store the rule (included or excluded) for a given
         class (described by the corresponding Identifier). The nodes are used in the internal
@@ -105 +103 @@
             void addSubnode(ClassTreeMaskNode* subnode);
 
-            /** @brief Tells if the rule is "included" or not. @return The rule: true = included, false = excluded */
+            /// Tells if the rule is "included" or not.
             inline bool isIncluded() const { return this->bIncluded_; }
-            /** @brief Tells if the rule is "excluded" or not. @return The inverted rule: true = excluded, false = included */
+            /// Tells if the rule is "excluded" or not.
             inline bool isExcluded() const { return (!this->bIncluded_); }
 
-            /** @brief Returns the Identifier of the class the rule refers to. @return The Identifier representing the class */
+            /// Returns the Identifier of the class the rule refers to.
             inline const Identifier* getClass() const { return this->subclass_; }
 
-            /** @brief Returns true if the Node has some subnodes. */
+            /// Returns true if the node has some subnodes.
             inline bool hasSubnodes() const { return !this->subnodes_.empty(); }
 
@@ -119 +117 @@
             void deleteAllSubnodes();
 
-            const Identifier* subclass_;                //!< The Identifier of the subclass the rule refers to
-            bool bIncluded_;                            //!< The rule: included or excluded
-            std::list<ClassTreeMaskNode*> subnodes_;    //!< A list containing all subnodes in the tree
+            const Identifier* subclass_;                ///< The Identifier of the subclass the rule refers to
+            bool bIncluded_;                            ///< The rule: included or excluded
+            std::list<ClassTreeMaskNode*> subnodes_;    ///< A list containing all subnodes of this node
     };
 
@@ -128 +126 @@
     // ###    ClassTreeMaskIterator    ###
     // ###################################
-    //! The ClassTreeMaskIterator moves through all ClassTreeMaskNodes of the internal tree of a ClassTreeMask, containing the rules.
     /**
+        @brief The ClassTreeMaskIterator moves through all ClassTreeMaskNodes of the internal tree of a ClassTreeMask which contains the rules.
+
         Because of the complicated shape of the internal rule-tree of ClassTreeMask, an
         iterator is used to move through all nodes of the tree. It starts with the BaseObject
@@ -135 +134 @@
         iterator moves one step back and iterates to the second subclass. If there are no more
         subclasses, it steps another step back, and so on.
+
+        Example: A and B are children of BaseObject, A1 and A2 are children of A, B1 and B2 are children of B.
+        The ClassTreeMaskIterator would move trough the tree in the following order:
+        BaseObject, A, A1, A2, B, B1, B2.
+
+        Note that the iterator doesn't move trough the whole class-tree, but only through the
+        internal tree of the mask, containing the minimal needed set of nodes to describe the mask.
     */
     class _CoreExport ClassTreeMaskIterator
@@ -150 +156 @@
 
         private:
-            std::stack<std::pair<std::list<ClassTreeMaskNode*>::iterator, std::list<ClassTreeMaskNode*>::iterator> > nodes_;    //!< A stack to store list-iterators
-            std::list<ClassTreeMaskNode*> rootlist_;                                                                            //!< A list for internal use (it only stores the root-node)
+            std::stack<std::pair<std::list<ClassTreeMaskNode*>::iterator, std::list<ClassTreeMaskNode*>::iterator> > nodes_;    ///< A stack to store list-iterators
+            std::list<ClassTreeMaskNode*> rootlist_;                                                                            ///< A list for internal use (it only stores the root-node)
     };
 
@@ -158 +164 @@
     // ###        ClassTreeMask        ###
     // ###################################
-    //! The ClassTreeMask is a set of rules, containing the information for each class whether it's included or not.
     /**
+        @brief The ClassTreeMask is a set of rules, containing the information for each class whether it's included or not.
+
         With a ClassTreeMask, you can include or exclude subtrees of the class-tree, starting
         with a given subclass, described by the corresponding Identifier. To minimize the size
         of the mask, the mask saves only relevant rules. But you can manually add rules that
-        don't change the information of the mask by using clean = false. If you want to drop
+        don't change the information of the mask by using <tt>clean = false</tt>. If you want to drop
         useless rules, call the clean() function.
+
+        Example:
+        @code
+        ClassTreeMask mymask;
+        mymask.exclude(Class(A));
+        mymask.exclude(Class(B));
+        mymask.include(Class(ChildOfA));
+        @endcode
+
+        In this example, the classes A and B are excluded from the mask, but one of the child
+        classes of A is included again.
     */
     class _CoreExport ClassTreeMask
@@ -189 +207 @@
             bool isExcluded(const Identifier* subclass) const;
 
-            /** @brief Begin of the ClassTreeMaskObjectIterator. */
+            /// Begin of the ClassTreeMaskObjectIterator.
             inline const ClassTreeMask& begin() const { return (*this); }
-            /** @brief End of the ClassTreeMaskObjectIterator. */
+            /// End of the ClassTreeMaskObjectIterator.
             inline BaseObject*          end()   const { return 0; }
 
@@ -228 +246 @@
             bool nodeExists(const Identifier* subclass);
 
-            ClassTreeMaskNode* root_;   //!< The root-node of the internal rule-tree, usually BaseObject
+            ClassTreeMaskNode* root_;   ///< The root-node of the internal rule-tree, usually BaseObject
     };
 
@@ -235 +253 @@
     // ### ClassTreeMaskObjectIterator ###
     // ###################################
-    //! The ClassTreeMaskObjectIterator iterates through all objects of all classes, included by a ClassTreeMask.
     /**
-        The ClassTreeMaskObjectIterator iterates through all objects of all classes,
-        included by a ClassTreeMask. This is done the following way:
-
+        @brief The ClassTreeMaskObjectIterator iterates through all objects of the classes that were included by a ClassTreeMask.
+
+        This is done the following way:
+        @code
         ClassTreeMask mask;
         for (ClassTreeMaskObjectIterator it = mask.begin(); it != mask.end(); ++it)
             it->doSomething();
-
-        Note: The ClassTreeMaskObjectIterator handles all objects as BaseObjects. If
+        @endcode
+
+        @note The ClassTreeMaskObjectIterator handles all objects as BaseObjects. If
               you want to use another class, you should use a dynamic_cast.
 
-        Performance of ClassTreeMaskObjectIterator is good as long as you don't exclude
+        The performance of ClassTreeMaskObjectIterator is good as long as you don't exclude
         subclasses of included classes. Of course you can still exlucde subclasses, but
         if this is done more often, we need a new implementation using a second ObjectList
@@ -255 +274 @@
     {
         public:
-            /** @brief Defaultconstructor: Does nothing. */
+            /// Default-constructor: Does nothing.
             inline ClassTreeMaskObjectIterator() {}
-            /** @brief Constructor: Initializes the iterator from a given ClassTreeMask. @param mask The mask */
+            /// Copy-Constructor: Initializes the iterator from another ClassTreeMask.
             inline ClassTreeMaskObjectIterator(const ClassTreeMask& mask) { (*this) = mask; }
 
@@ -264 +283 @@
             const ClassTreeMaskObjectIterator& operator++();
 
-            /** @brief Returns true if the ClassTreeMaskObjectIterator points at the given object. @param pointer The pointer of the object */
+            /// Returns true if the ClassTreeMaskObjectIterator points at the given object.
             inline bool operator==(BaseObject* pointer) const { return (this->objectIterator_ && (*this->objectIterator_) == pointer) || (!this->objectIterator_ && pointer == 0); }
-            /** @brief Returns true if the ClassTreeMaskObjectIterator doesn't point at the given object. @param pointer The pointer of the object */
+            /// Returns true if the ClassTreeMaskObjectIterator doesn't point at the given object.
             inline bool operator!=(BaseObject* pointer) const { return (this->objectIterator_ && (*this->objectIterator_) != pointer) || (!this->objectIterator_ && pointer != 0); }
-            /** @brief Returns true if the ClassTreeMaskObjectIterator hasn't already reached the end. */
+            /// Returns true if the ClassTreeMaskObjectIterator hasn't already reached the end.
             inline operator bool() const { return (this->objectIterator_); }
-            /** @brief Returns the object the ClassTreeMaskObjectIterator currently points at. */
+            /// Returns the object the ClassTreeMaskObjectIterator currently points at.
             inline BaseObject* operator*() const { return (*this->objectIterator_); }
-            /** @brief Returns the object the ClassTreeMaskObjectIterator currently points at. */
+            /// Returns the object the ClassTreeMaskObjectIterator currently points at.
             inline BaseObject* operator->() const { return (*this->objectIterator_); }
 
@@ -278 +297 @@
             void create(ClassTreeMaskNode* node);
 
-            std::list<std::pair<const Identifier*, bool> >           subclasses_;       //!< A list of all Identifiers through which objects the iterator should iterate
-            std::list<std::pair<const Identifier*, bool> >::iterator subclassIterator_; //!< The current class of the iterator
-            Iterator<BaseObject>                                     objectIterator_;   //!< The current object of the iterator
+            std::list<std::pair<const Identifier*, bool> >           subclasses_;       ///< A list of all Identifiers through which objects the iterator should iterate
+            std::list<std::pair<const Identifier*, bool> >::iterator subclassIterator_; ///< The current class of the iterator
+            Iterator<BaseObject>                                     objectIterator_;   ///< The current object of the iterator
     };
 }