Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: code/branches/doc/src/orxonox/interfaces/Pickupable.h @ 7297

Last change on this file since 7297 was 7297, checked in by landauf, 14 years ago

fixed lots of Doxygen warnings

Note: Doxygen prints a warning if only a part of the parameters of a function are documented.

Added documentation for missing parameters (as good as I could), removed documentation of obsolete parameters and fixed names of renamed parameters.
Some parameters are tagged with "FIXME", please replace this with an appropriate documentation if you know what it does.

  • Property svn:eol-style set to native
File size: 8.2 KB
Line 
1/*
2 *   ORXONOX - the hottest 3D action shooter ever to exist
3 *                    > www.orxonox.net <
4 *
5 *
6 *   License notice:
7 *
8 *   This program is free software; you can redistribute it and/or
9 *   modify it under the terms of the GNU General Public License
10 *   as published by the Free Software Foundation; either version 2
11 *   of the License, or (at your option) any later version.
12 *
13 *   This program is distributed in the hope that it will be useful,
14 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
15 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 *   GNU General Public License for more details.
17 *
18 *   You should have received a copy of the GNU General Public License
19 *   along with this program; if not, write to the Free Software
20 *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
21 *
22 *   Author:
23 *      Damian 'Mozork' Frick
24 *   Co-authors:
25 *      ...
26 *
27 */
28
29/**
30    @file Pickupable.h
31    @brief Definition of the Pickupable class.
32*/
33
34#ifndef _Pickupable_H__
35#define _Pickupable_H__
36
37#include "OrxonoxPrereqs.h"
38
39#include <list>
40#include "core/Super.h"
41
42#include "core/OrxonoxClass.h"
43#include "Rewardable.h"
44
45namespace orxonox // tolua_export
46{ // tolua_export
47
48    /**
49    @brief
50        An Interface (or more precisely an abstract class) to model and represent different (all kinds of) pickups.
51    @author
52        Damian 'Mozork' Frick
53    */
54    class _OrxonoxExport Pickupable  // tolua_export
55        : virtual public OrxonoxClass, public Rewardable
56    {  // tolua_export
57        protected:
58            Pickupable(); //!< Default constructor.
59
60        public:
61            virtual ~Pickupable(); //!< Default destructor.
62
63            /**
64            @brief Get whether the pickup is currently in use or not.
65            @return Returns true if the pickup is currently in use.
66            */
67            inline bool isUsed(void) { return this->used_; }  // tolua_export
68            /**
69            @brief  Should be called when the pickup has transited from used to unused or the other way around.
70                    Any Class overwriting this method must call its SUPER function by adding SUPER(Classname, changedUsed); to their changdeUsed method.
71            */
72            virtual void changedUsed(void) {}
73
74            /**
75            @brief Get the carrier of the pickup.
76            @return Returns a pointer to the carrier of the pickup.
77            */
78            inline PickupCarrier* getCarrier(void)
79                { return this->carrier_; }
80            /**
81            @brief Should be called when the pickup has changed its PickupCarrier.
82                   Any Class overwriting this method must call its SUPER function by adding SUPER(Classname, changedCarrier); to their changedCarrier method.
83            */
84            virtual void changedCarrier(void) {}
85
86            /**
87            @brief Returns whether the Pickupable is currently picked up.
88            @return Returns true if the Pickupable is currently picked up, false if not.
89            */
90            inline bool isPickedUp(void) { return this->pickedUp_; }  // tolua_export
91            /**
92            @brief  Should be called when the pickup has transited from picked up to dropped or the other way around.
93                    Any Class overwriting this method must call its SUPER function by adding SUPER(Classname, changedPickedUp); to their changedPickedUp method.
94            */
95            virtual void changedPickedUp(void) {}
96
97            /**
98            @brief Returns whether the Pickupable can be used.
99            @return Returns true if it can be used.
100            */
101            inline bool isUsable(void) { return this->enabled_; } // tolua_export
102           
103            /**
104            @brief Returns whether the Pickupable can be unused.
105            @return Returns true if it can be unused.
106            */
107            inline bool isUnusable(void) { return this->enabled_; } // tolua_export
108
109            /**
110            @brief Returns whether the Pickupable is enabled.
111                   Once a Pickupable is disabled it cannot be enabled again. A Pickupable that is disabled can neither be used nor unused.
112            @return Returns true if the Pickupable is enabled.
113            */
114            inline bool isEnabled(void)
115                { return this->enabled_; }
116
117            bool pickup(PickupCarrier* carrier); //!< Can be called to pick up a Pickupable.
118            bool drop(bool createSpawner = true); //!< Can be called to drop a Pickupable.
119
120            virtual bool isTarget(PickupCarrier* carrier) const; //!< Get whether the given PickupCarrier is a target of this pickup.
121            bool isTarget(const Identifier* identifier) const; //!< Get whether a given class, represented by the input Identifier, is a target of this Pickupable.
122            bool addTarget(PickupCarrier* target); //!< Add a PickupCarrier as target of this pickup.
123            bool addTarget(Identifier* identifier); //!< Add a class, representetd by the input Identifier, as target of this pickup.
124
125            Pickupable* clone(void); //!< Creates a duplicate of the Pickupable.
126            virtual void clone(OrxonoxClass*& item); //!< Creates a duplicate of the input OrxonoxClass.
127
128            /**
129            @brief Get the PickupIdentifier of this Pickupable.
130            @return Returns a pointer to the PickupIdentifier of this Pickupable.
131            */
132            virtual const PickupIdentifier* getPickupIdentifier(void)
133                { return this->pickupIdentifier_; }
134
135            bool setUsed(bool used); //!< Sets the Pickupable to used or unused, depending on the input.
136            bool setPickedUp(bool pickedUp); //!< Helper method to set the Pickupable to either picked up or not picked up.
137            //TODO: private?
138            bool setCarrier(PickupCarrier* carrier, bool tell = true); //!< Sets the carrier of the pickup.
139
140            //TODO: private?
141            virtual void carrierDestroyed(void); //!< Is called by the PickupCarrier when it is being destroyed.
142
143            void destroy(void); //!< Is called internally within the pickup module to destroy pickups.
144
145        protected:
146            /**
147            @brief Helper method to initialize the PickupIdentifier.
148            */
149            void initializeIdentifier(void) {}
150
151            virtual void preDestroy(void); //!< A method that is called by OrxonoxClass::destroy() before the object is actually destroyed.
152            virtual void destroyPickup(void); //!< Destroys a Pickupable.
153
154            /**
155            @brief Sets the Pickuapble to disabled.
156            */
157            inline void setDisabled(void)
158                { this->enabled_ = false; }
159
160            /**
161            @brief Facilitates the creation of a PickupSpawner upon dropping of the Pickupable.
162                   This method must be implemented by any class directly inheriting from Pickupable. It is most easily done by just creating a new DroppedPickup, e.g.:
163                   DroppedPickup(BaseObject* creator, Pickupable* pickup, PickupCarrier* carrier, float triggerDistance);
164            @return Returns true if a spawner was created, false if not.
165            */
166            virtual bool createSpawner(void) = 0;
167
168            PickupIdentifier* pickupIdentifier_; //!< The PickupIdentifier of this Pickupable.
169
170        private:
171
172            bool used_; //!< Whether the Pickupable is currently in use or not.
173            bool pickedUp_; //!< Whether the Pickupable is currently picked up or not.
174
175            bool enabled_; //!< Whether the Pickupable is enabled or not.
176
177            PickupCarrier* carrier_; //!< The PickupCarrier of the Pickupable.
178            std::list<Identifier*> targets_; //!< The possible targets of this Pickupable.
179
180            bool beingDestroyed_; //!< Is true if the Pickupable is in the process of being destroyed.
181
182        // For implementing the Rewardable interface:
183        public:
184            virtual bool reward(PlayerInfo* player); //!< Method to transcribe a Pickupable as a Rewardable to the player.
185
186    };  // tolua_export
187
188    SUPER_FUNCTION(10, Pickupable, changedUsed, false);
189    SUPER_FUNCTION(12, Pickupable, changedCarrier, false);
190    SUPER_FUNCTION(13, Pickupable, changedPickedUp, false);
191}  // tolua_export
192
193#endif /* _Pickupable_H__ */
Note: See TracBrowser for help on using the repository browser.