Changeset 7206 for code/trunk/src/modules/pickup

Timestamp:

Aug 23, 2010, 11:43:10 AM (14 years ago)

Author:

dafrick

Message:

Cleaning up and documenting PickupManager.
Also discovered and fixed a small bug.

Location:

code/trunk/src/modules/pickup

Files:

• PickupManager.cc (modified) (3 diffs)
• PickupManager.h (modified) (2 diffs)

code/trunk/src/modules/pickup/PickupManager.cc

@@ -157 +157 @@
     }
 
+    /**
+    @brief
+        Get the PickupRepresentation of an input Pickupable.
+        This method spares us the hassle to export the PickupIdentifier class to lua.
+    @param pickup
+        The Pickupable whose PickupRepresentation should be returned.
+    @return
+        Returns the PickupRepresentation of the input Pickupable or NULL if an error occurred.
+    */
+    orxonox::PickupRepresentation* PickupManager::getPickupRepresentation(orxonox::Pickupable* pickup)
+    {
+        if(pickup != NULL)
+            return this->getRepresentation(pickup->getPickupIdentifier());
+        
+        return NULL;
+    }
+
+    /**
+    @brief
+        Update the list of picked up Pickupables and get the number of Pickupables in the list.
+        This method is used in lua to populate the PickupInventory. The intended usage is to call this method to update the list of Pickupables and then use popPickup() to get the individual Pickupables.
+    @return
+        Returns the number of the players picked up Pickupables.
+    */
     int PickupManager::getNumPickups(void)
     {
-        this->pickupsList_.clear();
+        this->pickupsList_.clear(); // Clear the list if Pickupables.
 
         PlayerInfo* player = GUIManager::getInstance().getPlayer(PickupManager::guiName_s);
         PickupCarrier* carrier = NULL;
         if (player != NULL)
-            carrier =  dynamic_cast<PickupCarrier*>(player->getControllableEntity());
+            carrier =  orxonox_cast<PickupCarrier*>(player->getControllableEntity());
         else
             return 0;
 
-        std::vector<PickupCarrier*>* carriers = this->getAllCarriers(carrier);
+        std::vector<PickupCarrier*>* carriers = this->getAllCarriers(carrier); // Get a list of all the entities which carry the players Pickupables.
+        // Iterate through all the carriers and add their Pickupable to the list.
         for(std::vector<PickupCarrier*>::iterator it = carriers->begin(); it != carriers->end(); it++)
         {
@@ -175 +200 @@
             {
                 CollectiblePickup* collectible = orxonox_cast<CollectiblePickup*>(*pickup);
+                // If the Pickupable is in a PickupCollection it is not added to the list and thus not displayed in the PickupInventory.
                 if(collectible == NULL || !collectible->isInCollection())
                     this->pickupsList_.insert(std::pair<Pickupable*, WeakPtr<Pickupable> >(*pickup, WeakPtr<Pickupable>(*pickup)));
@@ -181 +207 @@
         delete carriers;
 
-        this->pickupsIterator_ = this->pickupsList_.begin();
+        this->pickupsIterator_ = this->pickupsList_.begin(); //Set the iterator to the start of the list.
         return this->pickupsList_.size();
     }
 
-    std::vector<PickupCarrier*>* PickupManager::getAllCarriers(PickupCarrier* carrier)
-    {
-        //TODO: More efficiently.
-        std::vector<PickupCarrier*>* carriers = new std::vector<PickupCarrier*>();
-        carriers->insert(carriers->end(), carrier);
-        std::vector<PickupCarrier*>* children = carrier->getCarrierChildren();
+    /**
+    @brief
+        Helper method. Get all the PickupCarriers that carry Pickupables, recursively.
+    @param carrier
+        The PickupCarrier whose children should be added to the list of PickupCarriers.
+    @param carriers
+        The list of PickupCarriers, used in "recursive-mode".
+        For the first instance this is just NULL (which is default and can be omitted) upon which a new list is allocated.
+    @return
+        Returns the list of PickupCarriers.
+    */
+    std::vector<PickupCarrier*>* PickupManager::getAllCarriers(PickupCarrier* carrier, std::vector<PickupCarrier*>* carriers)
+    {
+        if(carriers == NULL) // Create a new list if no list was passed.
+            carriers = new std::vector<PickupCarrier*>();
+
+        carriers->insert(carriers->end(), carrier); // Add the input PickupCarrier to the list.
+
+        std::vector<PickupCarrier*>* children = carrier->getCarrierChildren(); // Get the children of the input PickupCarrier.
+        // Iterate through the children and add them (and their children) to the list by recursively executing getAllCarriers().
         for(std::vector<PickupCarrier*>::iterator it = children->begin(); it != children->end(); it++)
-        {
-            std::vector<PickupCarrier*>* childrensChildren = this->getAllCarriers(*it);
-            for(std::vector<PickupCarrier*>::iterator it2 = childrensChildren->begin(); it2 != childrensChildren->end(); it2++)
-            {
-                carriers->insert(carriers->end(), *it2);
-            }
-            delete childrensChildren;
-        }
+            this->getAllCarriers(*it, carriers);
         delete children;
+
         return carriers;
     }
 
+    /**
+    @brief
+        Drop the input Pickupable.
+        This method checks whether the inout Pickupable still exists and drops it, if so.
+    @param pickup
+        The Pickupable to be dropped.
+    */
     void PickupManager::dropPickup(orxonox::Pickupable* pickup)
     {
-        std::map<Pickupable*, WeakPtr<Pickupable> >::iterator it = this->pickupsList_.find(pickup);
-        if(pickup == NULL || it == this->pickupsList_.end() || it->second.get() == NULL)
-            return;
-
-        if(!pickup->isPickedUp())
-            return;
-
-        PickupCarrier* carrier = pickup->getCarrier();
-        if(pickup != NULL && carrier != NULL)
-        {
-            pickup->drop(carrier);
-        }
-    }
-
+        if(pickup == NULL)
+            return;
+
+        std::map<Pickupable*, WeakPtr<Pickupable> >::iterator it = this->pickupsList_.find(pickup); // Get the WeakPointer of the Pickupable.
+        // If either the input Pickupable is not in the PickupManagers list or it no longer exists, the method returns.
+        if(it == this->pickupsList_.end() || it->second.get() == NULL)
+            return;
+
+        pickup->drop(); // The Pickupable is dropped.
+    }
+
+    /**
+    @brief
+        Use (or unuse) the input Pickupable.
+        This method checks whether the input Pickupable still exists and uses (or unuses) it, if so,
+    @param pickup
+        The Pickupable to be used (or unused).
+    @param use
+        If true the input Pickupable is used, if false it is unused.
+    */
     void PickupManager::usePickup(orxonox::Pickupable* pickup, bool use)
     {
-        std::map<Pickupable*, WeakPtr<Pickupable> >::iterator it = this->pickupsList_.find(pickup);
-        if(pickup == NULL || it == this->pickupsList_.end() || it->second.get() == NULL)
-            return;
-
-        if(!pickup->isPickedUp())
-            return;
-
-        PickupCarrier* carrier = pickup->getCarrier();
-        if(pickup != NULL && carrier != NULL)
-            pickup->setUsed(use);
+        if(pickup == NULL)
+            return;
+        
+        std::map<Pickupable*, WeakPtr<Pickupable> >::iterator it = this->pickupsList_.find(pickup); // Get the WeakPointer of the Pickupable.
+        // If either the input Pickupable is not in the PickupManagers list or it no longer exists, the method returns.
+        if(it == this->pickupsList_.end() || it->second.get() == NULL)
+            return;
+
+        pickup->setUsed(use); // The Pickupable is used (or unused).
+    }
+
+    /**
+    @brief
+        Check whether the input Pickupable is valid, meaning that it is in the PickupManager's list and still exists.
+    @param pickup
+        The Pickupable.
+    @return
+        Returns true if the input Pickupable is still valid, false if not.
+    */
+    bool PickupManager::isValidPickup(orxonox::Pickupable* pickup)
+    {
+        std::map<Pickupable*, WeakPtr<Pickupable> >::iterator it = this->pickupsList_.find(pickup); // Get the WeakPointer of the Pickupable.
+        if(it == this->pickupsList_.end()) // If the Pickupable is not in the PickupManager's list.
+            return false;
+        return it->second.get() != NULL; // Returns whether the Pickupable still exists.
     }
 

code/trunk/src/modules/pickup/PickupManager.h

@@ -52 +52 @@
         Manages Pickupables.
         In essence has two tasks to fulfill. Firstly it must link Pickupables (through their PickupIdentifiers) and their PickupRepresentations. Secondly it manages the PickupInventory.
-        //TODO: Manage Pickup GUI.
     @author
         Damian 'Mozork' Frick
@@ -72 +71 @@
 
             // tolua_begin
-            int getNumPickups(void);
+            orxonox::PickupRepresentation* getPickupRepresentation(orxonox::Pickupable* pickup); //!< Get the PickupRepresentation of an input Pickupable.
+
+            int getNumPickups(void); //!< Update the list of picked up Pickupables and get the number of Pickupables in the list.
+            /**
+            @brief Get the next Pickupable in the list.
+                   Use this, after having called getNumPickups() to access all the Pickupables individually and in succession.
+            @return Returns the next Pickupable in the list.
+            */
             orxonox::Pickupable* popPickup(void) { return (this->pickupsIterator_++)->first; }
-            orxonox::PickupRepresentation* getPickupRepresentation(orxonox::Pickupable* pickup) { if(pickup != NULL) return this->getRepresentation(pickup->getPickupIdentifier()); return NULL; }
 
-            void dropPickup(orxonox::Pickupable* pickup);
-            void usePickup(orxonox::Pickupable* pickup, bool use);
-            bool isValidPickup(orxonox::Pickupable* pickup) { std::map<Pickupable*, WeakPtr<Pickupable> >::iterator it = this->pickupsList_.find(pickup); if(it == this->pickupsList_.end()) return false; return it->second.get() != NULL; }
+            void dropPickup(orxonox::Pickupable* pickup); //!< Drop the input Pickupable.
+            void usePickup(orxonox::Pickupable* pickup, bool use); //!< Use (or unuse) the input Pickupable.
+            bool isValidPickup(orxonox::Pickupable* pickup); //!< Check whether the input Pickupable is valid, meaning that it is in the PickupManager's list and still exists.
             // tolua_end
 
         private:
             static PickupManager* singletonPtr_s;
-            static const std::string guiName_s;
+            static const std::string guiName_s; //!< The name of the PickupInventory
 
             PickupRepresentation* defaultRepresentation_; //!< The default PickupRepresentation.
             std::map<const PickupIdentifier*, PickupRepresentation*, PickupIdentifierCompare> representations_; //!< Map linking PickupIdentifiers (representing types if Pickupables) and PickupRepresentations.
 
-            std::map<Pickupable*, WeakPtr<Pickupable> > pickupsList_;
-            std::map<Pickupable*, WeakPtr<Pickupable> >::iterator pickupsIterator_;
+            std::map<Pickupable*, WeakPtr<Pickupable> > pickupsList_; //!< A list of all the picked up Pickupables.
+            std::map<Pickupable*, WeakPtr<Pickupable> >::iterator pickupsIterator_; //!< An iterator pointing to the current Pickupable in pickupsList_.
 
-            std::vector<PickupCarrier*>* getAllCarriers(PickupCarrier* carrier);
+            std::vector<PickupCarrier*>* getAllCarriers(PickupCarrier* carrier, std::vector<PickupCarrier*>* carriers = NULL); //!< Helper method. Get all the PickupCarriers that carry Pickupables, recursively.
 
     }; // tolua_export