Changeset 7489

Timestamp:

Sep 24, 2010, 4:01:04 PM (14 years ago)

Author:

dafrick

Message:

Mostly more documentation.

Location:

code/trunk

Files:

• doc/api/Groups.dox (modified) (3 diffs)
• src/modules/notifications/Notification.cc (modified) (2 diffs)
• src/modules/notifications/Notification.h (modified) (4 diffs)
• src/modules/notifications/NotificationDispatcher.cc (modified) (1 diff)
• src/modules/notifications/NotificationManager.cc (modified) (2 diffs)
• src/modules/notifications/NotificationManager.h (modified) (1 diff)
• src/modules/notifications/NotificationQueue.cc (modified) (6 diffs)
• src/modules/notifications/NotificationQueue.h (modified) (3 diffs)
• src/modules/notifications/dispatchers/CommandNotification.cc (modified) (2 diffs)
• src/modules/notifications/dispatchers/CommandNotification.h (modified) (2 diffs)
• src/modules/questsystem/QuestEffectBeacon.h (modified) (1 diff)

code/trunk/doc/api/Groups.dox

@@ -129 +129 @@
     You first have to decide on a message, it shouldn't be too long but be long enough to get your point accross.
     Then you have to decide on a sender. The sender is a string by which the different @ref orxonox::NotificationQueue "NotificationQueues" (the entities that display the @ref orxonox::Notification "Notifications") can decide whether they should display the @ref orxonox::Notification "Notification" or not. So the sender is some string that identifies a group of @ref orxonox::Notification "Notifications" that have something in common or some entity that is sending them. For example: All @ref orxonox::Notification "Notifications" sent by any part of the Questsystem have "questsystem" as sender and thus we could create a @ref orxonox::NotificationQueue "NotificationQueue" that only displays @ref orxonox::Notification "Notifications" from the Questsystem, but more to that later.
-    And lastly you have to decide to whom you want to send this @ref orxonox::Notification "Notification". You have to get the clientId of the intended recipient (e.g. trought a @ref orxonox::PlayerInfo "PlayerInfo") or you only send the @ref orxonox::Notification "Notification" locally, either by setting the clientId to Host::getPlayerID() or by setting the variable 'isLocal' to true, and setting clientId to what ever you want, since it will be ignored.
+    And lastly you have to decide to whom you want to send this @ref orxonox::Notification "Notification". You have to get the clientId of the intended recipient (e.g. trough a @ref orxonox::PlayerInfo "PlayerInfo") or you only send the @ref orxonox::Notification "Notification" locally, either by setting the clientId to Host::getPlayerID() or by setting the variable 'isLocal' to true, and setting clientId to what ever you want, since it will be ignored.
     Once you have decided all that you can send the Notification by calling:
     @code
@@ -136 +136 @@
 
     @subsection NotificationsDisplay Displaying notifications
-    Displaying @ref oroxnox::Notification "Notifications" is even easier, all you need to do is to load the NotificationLayer in the level, where you want @ref orxonox::Notification "Notifications" displayed. You can either do this manually by executing the following command in the console:
+    Displaying @ref orxonox::Notification "Notifications" is even easier, all you need to do is to load the NotificationLayer in the level, where you want @ref orxonox::Notification "Notifications" displayed. You can either do this manually by executing the following command in the console:
     @code
     showGUI NotificationLayer false true
@@ -154 +154 @@
 
     @subsection NotificationQueue NotificationQueue
-    The @ref orxonox::NotificationQueue "NotificationQueue" is the entity, that (as said earlier) logically displays @ref orxonox::Notification "Notifications". Furthermore a @ref orxonox::NotificationQueue "NotificationQueue" displays only a subset of all the @ref orxonox::Notification "Notifications". The parameters that reduce the range of @ref orxonox::Notification "Notifications" are:
-    - @b senders The senders, set of targets of a @ref orxonox::NotificationQueue "NotificationQueue" is the set of senders a @ref orxonox::NotificationQueue "NotificationQueue" displays  @ref orxonox::Notification "Notifications" from. E.g. If one would set the senders to "questsystem" then only  @ref orxonox::Notification "Notifications" from the Questsystem wouuld be displayed in that particular queue. If you set senders to "all" then all Notifications will be displayed. Different senders can be concatinated with commas.
-    - @b size The size specifies how many @ref orxonox::Notification "Notifications" are displayed at the most, if there are more @ref orxonox::Notification "Notifications" that could be displayed but the size is smaller than the number of @ref orxonox::Notification "Notifications", then only the most recent are displayed.
+    The @ref orxonox::NotificationQueue "NotificationQueue" is the entity, that (as said earlier) logically displays @ref orxonox::Notification "Notifications". Furthermore a @ref orxonox::NotificationQueue "NotificationQueue" displays only a subset of all the @ref orxonox::Notification "Notifications". The parameters that reduce the range of displayed @ref orxonox::Notification "Notifications" are:
+    - @b senders The senders, the set of targets of a @ref orxonox::NotificationQueue "NotificationQueue" is the set of senders a @ref orxonox::NotificationQueue "NotificationQueue" displays  @ref orxonox::Notification "Notifications" from. E.g. If one would set the senders to "questsystem" then only  @ref orxonox::Notification "Notifications" from the Questsystem would be displayed in that particular queue. If you set senders to "all" then all Notifications will be displayed. Different senders can be concatinated with commas.
+    - @b size The size specifies how many @ref orxonox::Notification "Notifications" are displayed at the most, if there are more @ref orxonox::Notification "Notifications" that could be displayed, then only the most recent are displayed.
     - @b displayTime The display time specifies how long a @ref orxonox::Notification "Notification" is displayed at the most.
 
     @subsection NotificationLayer NotificationLayer
-    The NotificationLayer is a GUI sheet, that displays all the @ref orxonox::NotificationQueue "NotificationQueues" and their @ref orxonox::Notification "Notifications". In its normal mode of operation it is transparent to input, meaning that it only functions as a means of displaying, however if switched to edit mode the NotificationLayer no longer is transparent to input and allows for the adding, removal and modification of @ref orxonox::NotificationQueue "NotificationQueues".
+    The NotificationLayer is a GUI sheet, that displays all the @ref orxonox::NotificationQueue "NotificationQueues" and their @ref orxonox::Notification "Notifications". In its normal mode of operation it is transparent to input, meaning that it only functions as a means of displaying, however if switched to edit mode the NotificationLayer no longer is transparent to input and allows for the adding, removal and modification of @ref orxonox::NotificationQueue "NotificationQueues". For every @ref orxonox::NotificationQueue "NotificationQueue" there is the equivalent representation in the NotificationLayer. So @ref orxonox::NotificationQueue "NotificationQueues" are not each represented by a GUI sheet, but thely all belong to one and the same GUI sheet, the NotificationLayer.
 
     @subsection NotificationManager NotificationManager
-    The @ref orxonox::NotificationManager "NotificationManager" is (hence the name) the managing entity in this setting. It is responsible for the registering and unregistering of @ref orxonox::NotificationListener "NotificationListeners" (which the @ref orxonox::NotificationQueue "NotificationQueue" is) and also informs them about changes related to @ref orxonox::Notification "Notifications". It is also responsible for the creation and destruction of @ref orxonox::NotificationQueue "NotificationQueues" through the NotificationLayer and is also the point of approach for the NotificationLayer to get information it needs. Finally the @ref orxonox::NotificationManager "NotificationManager" is responsible for sending (and in the process creating) @ref orxonox::Notification "Notifications" and is a means for the @ref orxonox::NotificationQueue "NotificationQueues" to get the information they need about @ref orxonox::Notification "Notifications".
+    The @ref orxonox::NotificationManager "NotificationManager" is (hence the name) the managing entity in this setting. It is responsible for the registering and unregistering of @ref orxonox::NotificationListener "NotificationListeners" (which the @ref orxonox::NotificationQueue "NotificationQueue" is) and also informs them about changes related to @ref orxonox::Notification "Notifications". It is also responsible for the creation and destruction of @ref orxonox::NotificationQueue "NotificationQueues" through the NotificationLayer and is also the point of approach for the NotificationLayer to get information it needs to display the queues. Finally the @ref orxonox::NotificationManager "NotificationManager" is responsible for sending (and in the process creating) @ref orxonox::Notification "Notifications" and is a means for the @ref orxonox::NotificationQueue "NotificationQueues" to get the information they need about @ref orxonox::Notification "Notifications".
 
     @subsection Notification Notification
-    The @ref orxonox::Notification "Notification" class is more or less a data structure that groups the notification message and the sender, and possibly other future parameters together to form a comprehensive structure that we call Notification.
+    The @ref orxonox::Notification "Notification" class is more or less a data structure that groups the notification message and the sender, and possibly other future parameters, together to form a comprehensive structure that we call Notification.
 
     Additionally there is another important class of objects belonging to the Notifications module. The @ref orxonox::NotificationDispatcher "NotificationDispatchers".

code/trunk/src/modules/notifications/Notification.cc

@@ -35 +35 @@
 
 #include "core/CoreIncludes.h"
-#include "network/NetworkFunction.h"
-#include "network/Host.h"
 #include "NotificationManager.h"
 
@@ -44 +42 @@
     /**
     @brief
-        Default constructor. Initializes the object.
-    */
-    Notification::Notification()
-    {
-        RegisterRootObject(Notification);
-        this->initialize();
-    }
-
-    /**
-    @brief
-        Constructor. Creates a Notification with the input message.
-    @param creator
-        The creator.
+        Constructor. Creates a Notification with the input message and sender.
     @param message
         The message of the Notification.
+    @param sender
+        The sender of the Notification.
     */
     Notification::Notification(const std::string& message, const std::string& sender)

code/trunk/src/modules/notifications/Notification.h

@@ -39 +39 @@
 
 #include <string>
-#include "core/BaseObject.h"
+#include "core/OrxonoxClass.h"
 
 namespace orxonox
@@ -46 +46 @@
     /**
     @brief
-        A Notification is a short message used to inform the player about something that just happened. A Notification can be sent from any part of orxonox and is then displayed in the proper @ref orxonox::NotificationQueue "NotificationQueue" (depending on which senders the specific @ref orxonox::NotificationQueue "NotificationQueue" accepts).
+        A Notification represents a short message used to inform the player about something that just happened. With the @ref orxonox::NotificationManager "NotificationManager" a Notification can be sent from any part of orxonox and is then displayed by the proper @ref orxonox::NotificationQueue "NotificationQueue(s)" (depending on which senders the specific @ref orxonox::NotificationQueue "NotificationQueues" accepts).
+
+        A Notification is just a datastructure that is used internally by the Notifications module.
     @author
         Damian 'Mozork' Frick
@@ -53 +55 @@
     {
         public:
-            Notification();
             Notification(const std::string& message, const std::string& sender);
             virtual ~Notification();
 
             /**
-            @brief Returns the message of the Notification.
+            @brief Get the message of the Notification.
             @return Returns the message of the Notification.
             */
@@ -64 +65 @@
                 { return this->message_; }
 
+            /**
+            @brief Get the sender of the Notification.
+            @return Returns the sender of the Notification.
+            */
             inline const std::string & getSender(void) const
                 { return this->sender_; }

code/trunk/src/modules/notifications/NotificationDispatcher.cc

@@ -44 +44 @@
 #include "worldentities/pawns/Pawn.h"
 
-#include "Notification.h"
 #include "NotificationManager.h"
 

code/trunk/src/modules/notifications/NotificationManager.cc

@@ -104 +104 @@
         // Destroys all NotificationQueues that have been registered with the NotificationManager.
         for(std::map<const std::string, NotificationQueue*>::iterator it = this->queues_.begin(); it != this->queues_.end(); it++)
-        {
             it->second->destroy(true);
-        }
+
         this->queues_.clear();
     }
@@ -343 +342 @@
     void NotificationManager::enterEditMode(void)
     {
-        GUIManager::getInstance().hideGUI("NotificationLayer");
-        GUIManager::getInstance().showGUI("NotificationLayer", false, false);
-        GUIManager::getInstance().getLuaState()->doString("NotificationLayer.enterEditMode()");
+        if(GameMode::showsGraphics())
+        {
+            GUIManager::getInstance().hideGUI("NotificationLayer");
+            GUIManager::getInstance().showGUI("NotificationLayer", false, false);
+            GUIManager::getInstance().getLuaState()->doString("NotificationLayer.enterEditMode()");
+        }
     }
 

code/trunk/src/modules/notifications/NotificationManager.h

@@ -52 +52 @@
         The Singleton NotificationManager functions as a gateway between @ref orxonox::Notification "Notifications" and @ref orxonox::NotificationListener "NotificationListeners".
         It receives, organizes @ref orxonox::Notification "Notifications" and the redistributes them to the specific @ref orxonox::NotificationListener "NotificationListeners".
-        It also provides a static function to send @ref orxonox::Notification "Notifications" and works as a liaison between the @ref orxonox>>NotificationQueue "NotificationQueues" and the GUI that displays notification, called NotificationLayer.
+        It also provides a static function to send @ref orxonox::Notification "Notifications" and works as a liaison between the @ref orxonox::NotificationQueue "NotificationQueues" and the GUI that displays notification, called NotificationLayer.
     @author
         Damian 'Mozork' Frick

code/trunk/src/modules/notifications/NotificationQueue.cc

@@ -90 +90 @@
         this->create(); // Creates the NotificationQueue in lua.
 
-        // register the NotificationQueue as NotificationListener with the NotificationManager.
+        // Register the NotificationQueue as NotificationListener with the NotificationManager.
         bool listenerRegistered = NotificationManager::getInstance().registerListener(this);
         if(!listenerRegistered) // If the registration has failed.
@@ -96 +96 @@
             this->registered_ = false;
             // Remove the NotificationQueue in lua.
-            GUIManager::getInstance().getLuaState()->doString("NotificationLayer.removeQueue(\"" + this->getName() +  "\")");
+            if(GameMode::showsGraphics())
+                GUIManager::getInstance().getLuaState()->doString("NotificationLayer.removeQueue(\"" + this->getName() +  "\")");
             NotificationManager::getInstance().unregisterQueue(this);
             COUT(1) << "Error: NotificationQueue '" << this->getName() << "' could not be registered." << std::endl;
@@ -210 +211 @@
     void NotificationQueue::update(Notification* notification, const std::time_t & time)
     {
+        assert(notification);
+
         this->push(notification, time);
 
@@ -226 +229 @@
     void NotificationQueue::push(Notification* notification, const std::time_t & time)
     {
+        assert(notification);
+
         NotificationContainer* container = new NotificationContainer;
         container->notification = notification;
@@ -254 +259 @@
         // Get all the NotificationContainers that were sent the same time the NotificationContainer we want to pop was sent.
         std::pair<std::multiset<NotificationContainer*, NotificationContainerCompare>::iterator, std::multiset<NotificationContainer*, NotificationContainerCompare>::iterator> iterators = this->ordering_.equal_range(container);
-        // Iterate thourgh all suspects and remove the container as soon as we find it.
+        // Iterate through all suspects and remove the container as soon as we find it.
         for(std::multiset<NotificationContainer*, NotificationContainerCompare>::iterator it = iterators.first; it != iterators.second; it++)
         {
@@ -311 +316 @@
 
         this->notifications_.clear();
-
         this->size_ = 0;
 

code/trunk/src/modules/notifications/NotificationQueue.h

@@ -43 +43 @@
 #include <vector>
 
+#include "NotificationManager.h"
+
 #include "tools/interfaces/Tickable.h"
-
 #include "interfaces/NotificationListener.h"
-#include "NotificationManager.h"
 
 namespace orxonox // tolua_export
@@ -54 +54 @@
     struct NotificationContainer
     {
-        Notification* notification; // The Notification displayed.
-        time_t time; // The time the Notification was sent and thus first displayed.
+        Notification* notification; //!< The Notification displayed.
+        time_t time; //!< The time the Notification was sent and thus first displayed.
     };
 
@@ -61 +61 @@
     struct NotificationContainerCompare {
         bool operator() (const NotificationContainer* const & a, const NotificationContainer* const & b) const
-            { return a->time < b->time; } // Ordered by time.
+            { return a->time < b->time; } //!< Ordering by time.
     };
 

code/trunk/src/modules/notifications/dispatchers/CommandNotification.cc

@@ -64 +64 @@
     CommandNotification::~CommandNotification()
     {
-        
+
     }
 
@@ -114 +114 @@
         Returns a human readable version of the input binding.
     */
+    //TODO: Move to KeyBinderManager...
     const std::string& CommandNotification::bindingNiceifyer(const std::string& binding)
     {

code/trunk/src/modules/notifications/dispatchers/CommandNotification.h

@@ -46 +46 @@
     @brief
         This class implements a method of displaying a Notification with information to an input command and the key the command is mapped to.
-        The message that is displayed is a string made out uf the concatenation of the preMessage, the key the specified command is mapped to and the postMessage.
+        The message that is displayed is a string made out of the concatenation of the preMessage, the key the specified command is mapped to and the postMessage.
 
         In use it would like this:
@@ -120 +120 @@
                  { this->postMessage_ = message; }
 
-            const std::string& bindingNiceifyer(const std::string& binding);
+            const std::string& bindingNiceifyer(const std::string& binding); //!< Transforms the input binding into a human readable form.
 
     };

code/trunk/src/modules/questsystem/QuestEffectBeacon.h

@@ -56 +56 @@
     @brief
         A QuestEffectBeacon is a physical entity in the game which can (under some condition(s)) invoke a number of @ref orxonox::QuestEffect "QuestEffects" on players meeting the condition(s).
-        The conditions under which the @ref orxonox::QuestEffect "QuestEffects" are invoked on the player are defined by @ref orxonox::Trigger "Triggers" (or really any kind of entity firing events, e.g. @ref oroxnox::EventListener "EventListeners"). The trigger the event originates from, however has to be a @ref orxonox::PlayerTrigger PlayerTrigger.
+        The conditions under which the @ref orxonox::QuestEffect "QuestEffects" are invoked on the player are defined by @ref orxonox::Trigger "Triggers" (or really any kind of entity firing events, e.g. @ref orxonox::EventListener "EventListeners"). The trigger the event originates from, however has to be a @ref orxonox::PlayerTrigger PlayerTrigger.
         A QuestEffectBeacon can be executed a defined number of times.
         A QuestEffectBeacon can be inactive or active. While inactive it can't be executed.