Changeset 7488

Timestamp:

Sep 24, 2010, 12:01:57 PM (14 years ago)

Author:

dafrick

Message:

Some more documentation.
Making NotificationManager Root scope, cleaning up, especially in Notification (now it's just a data structure anymore).

Location:

code/trunk

Files:

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

code/trunk/doc/api/Groups.dox

@@ -153 +153 @@
     The Notifications module has three major parts that interact with each other. First there is the @ref orxonox::NotificationQueue "NotificationQueue", this is the entity that (logically, not effectively) displays @ref orxonox::Notification "Notifications" according to some rules, then there is the NotificationLayer, which is the GUI which (actually) displays @ref orxonox::Notification "Notifications" by visualizing the @ref orxonox::NotificationQueue "NotificationQueues" and as a result also the @ref orxonox::Notification "Notifications", that are displayed by the respective @ref orxonox::NotificationQueue "NotificationQueues" and lastly there is the @ref orxonox::NotificationManager "NotificationManager", which connects these two.
 
+    @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.
+    - @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".
 
-    @subsection NotificationQueue NotificationQueue
-    ...
-
     @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".
 
     @subsection Notification Notification
@@ -172 +175 @@
     @defgroup NotificationDispatchers Dispatchers
     @ingroup Notifications
+
+    @ref orxonox::NotificationDispatcher "NotificationDispatchers" are entities that are instantiated in a level file (through XML) and that dispatch (or send) a specific @ref orxonox::Notification "Notification" upon having received a triggering event.
+
+    At this point there are two @ref orxonox::NotificationDispatcher "NotificationDispatchers", the @ref orxonox::SimpleNotification "SimpleNotification", which just displays a specified message, and the @ref orxonox::CommandNotification "CommandNotification" which displays a message with a binding for a specified command in it.
 */
 

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

@@ -60 +60 @@
         The message of the Notification.
     */
-    Notification::Notification(const std::string & message)
+    Notification::Notification(const std::string& message, const std::string& sender)
     {
         RegisterRootObject(Notification);
         this->initialize();
         this->message_ = message;
+        this->sender_ = sender;
     }
 
@@ -84 +85 @@
         this->message_.clear();
         this->sender_ = NotificationManager::NONE;
-        this->sent_ = false;
-    }
-
-    /**
-    @brief
-        Sends the Notification to the Notificationmanager, which then in turn distributes it to the different NotificationQueues.
-    @param sender
-        The sender the Notification was sent by. Used by the NotificationManager to distributes the notification to the correct NotificationQueues.
-    @return
-        Returns true if successful.
-    */
-    bool Notification::send(const std::string & sender)
-    {
-        if(this->isSent()) //TODO: Needed?
-            return false;
-
-        this->sender_ = sender;
-        bool successful = NotificationManager::getInstance().registerNotification(this);
-        if(!successful)
-            return false;
-        this->sent_ = true;
-
-        COUT(3) << "Notification \"" << this->getMessage() << "\" sent." << std::endl;
-
-        return true;
-    }
-
-    /**
-    @brief
-        Sets the message of the notification.
-    @param message
-        The message to be set.
-    @return
-        Returns true if successful.
-    */
-    bool Notification::setMessage(const std::string & message)
-    {
-        if(this->isSent()) // The message cannot be changed if the message has already been sent.
-            return false;
-        this->message_ = message;
-        return true;
     }
 

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

@@ -54 +54 @@
         public:
             Notification();
-            Notification(const std::string & message);
+            Notification(const std::string& message, const std::string& sender);
             virtual ~Notification();
 
-            bool send(const std::string & sender); //!< Sends the Notification to the Notificationmanager.
-
-            /**
-            @brief Checks whether the Notification was sent.
-            @return Returns true if the Notification was sent already.
-            */
-            inline bool isSent(void) const
-                { return this->sent_; }
             /**
             @brief Returns the message of the Notification.
@@ -75 +67 @@
                 { return this->sender_; }
 
-            bool setMessage(const std::string & message); //!< Sets the message of the notification.
-
         private:
             std::string message_; //!< The Notification message.
             std::string sender_; //!< The sender of the notification.
-            bool sent_; //!< Whether Notification has been sent, if so it cannot be changed.
 
             void initialize(void); //!< Registers the object and sets some default values.

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

@@ -83 +83 @@
         SUPER(NotificationDispatcher, XMLPort, xmlelement, mode);
 
+        XMLPortParam(NotificationDispatcher, "sender", getSender, setSender, xmlelement, mode);
+        
         XMLPortEventSink(NotificationDispatcher, BaseObject, "trigger", trigger, xmlelement, mode); //TODO: Change BaseObject to MultiTrigger as soon as MultiTrigger is the base of all triggers.
     }

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

@@ -49 +49 @@
         A NotificationDispatcher is an entity that, upon being triggered, dispatches (or sends) a specified @ref orxonox::Notification "Notification".
 
+        There is one parameter to be set, the @b sender . The sender specifies the part of Orxonox the sent @ref orxonox::Notification "Notification" comes from. The default value is set by the classes implementing NotificationDispatcher.
+
         Its standard usage is:
         @code
-        <NotificationDispatcher>
+        <NotificationDispatcher sender="me">
             <events>
                 <trigger>
@@ -76 +78 @@
             @return Returns the name of the sender.
             */
-            const std::string& getSender(void)
+            const std::string& getSender(void) const
                 { return this->sender_; }
+                        /**
+            @brief Set the sender of the Notification dispatched by this NotificationDispatcher.
+            @param sender The name of the sender.
+            */
+            void setSender(const std::string& sender)
+                { this->sender_ = sender; }
 
             void dispatch(unsigned int clientId); //!< Dispatches a specific Notification.
@@ -86 +94 @@
 
             void registerVariables(void); //!< Register some variables for synchronisation.
-
-            /**
-            @brief Set the sender of the Notification dispatched by this NotificationDispatcher.
-            @param sender The name of the sender.
-            */
-            void setSender(const std::string& sender)
-                { this->sender_ = sender; }
 
             /**

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

@@ -58 +58 @@
     DeclareToluaInterface(Notifications);
 
-    ManageScopedSingleton(NotificationManager, ScopeID::Graphics, false);
+    ManageScopedSingleton(NotificationManager, ScopeID::Root, false);
 
     // Setting console command to enter the edit mode.
@@ -88 +88 @@
         ModifyConsoleCommand("enterEditMode").setObject(NULL);
 
+        // Destroys all Notifications.
+        for(std::multimap<std::time_t, Notification*>::iterator it = this->allNotificationsList_.begin(); it!= this->allNotificationsList_.end(); it++)
+            it->second->destroy();
+        this->allNotificationsList_.clear();
+
         COUT(3) << "NotificationManager destroyed." << std::endl;
     }
@@ -98 +103 @@
     {
         // 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(); )
-        {
-            NotificationQueue* queue = (*it).second;
-            it++;
-            queue->destroy();
+        for(std::map<const std::string, NotificationQueue*>::iterator it = this->queues_.begin(); it != this->queues_.end(); it++)
+        {
+            it->second->destroy(true);
         }
         this->queues_.clear();
@@ -124 +127 @@
         if(GameMode::isStandalone() || isLocal || Host::getPlayerID() == clientId)
         {
-            Notification* notification = new Notification(message);
-            notification->send(sender);
+            Notification* notification = new Notification(message, sender);
+            if(NotificationManager::getInstance().registerNotification(notification))
+                COUT(3) << "Notification \"" << notification->getMessage() << "\" sent." << std::endl;
         }
         // If we're on the server (and the server is not the intended recipient of the Notification) we send it over the network.

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

@@ -38 +38 @@
 
 #include "core/CoreIncludes.h"
+#include "core/GameMode.h"
 #include "core/GUIManager.h"
 #include "core/LuaState.h"
@@ -112 +113 @@
         this->targets_.clear();
 
-        if(this->registered_) // If the 
-        {
-            this->clear();
+        if(this->registered_) // If the NotificationQueue is registered.
+        {
+            this->clear(true);
 
             // Unregister with the NotificationManager.
             NotificationManager::getInstance().unregisterListener(this);
             NotificationManager::getInstance().unregisterQueue(this);
-
-            // Remove the NotificationQueue in lua.
+        }
+    }
+
+    /**
+    @brief
+        Destroys the NotificationQueue.
+        Used in lua and NotificationManager.
+    @param noGraphics
+        If this is set to true (false is default), then the queue is not removed in lua. This is used to destroy the queue, after the GUIManager has been destroyed.
+    */
+    void NotificationQueue::destroy(bool noGraphics)
+    {
+        // Remove the NotificationQueue in lua.
+        if(GameMode::showsGraphics() && !noGraphics)
             GUIManager::getInstance().getLuaState()->doString("NotificationLayer.removeQueue(\"" + this->getName() +  "\")");
-        }
+
+        this->OrxonoxClass::destroy();
     }
 
@@ -131 +145 @@
     void NotificationQueue::create(void)
     {
-        GUIManager::getInstance().getLuaState()->doString("NotificationLayer.createQueue(\"" + this->getName() +  "\", " + multi_cast<std::string>(this->getMaxSize()) + ")");
+        if(GameMode::showsGraphics())
+            GUIManager::getInstance().getLuaState()->doString("NotificationLayer.createQueue(\"" + this->getName() +  "\", " + multi_cast<std::string>(this->getMaxSize()) + ")");
     }
 
@@ -226 +241 @@
 
         // Push the Notification to the GUI.
-        GUIManager::getInstance().getLuaState()->doString("NotificationLayer.pushNotification(\"" + this->getName() + "\", \"" + notification->getMessage() + "\")");
+        if(GameMode::showsGraphics())
+            GUIManager::getInstance().getLuaState()->doString("NotificationLayer.pushNotification(\"" + this->getName() + "\", \"" + notification->getMessage() + "\")");
     }
 
@@ -254 +270 @@
 
         // Pops the Notification from the GUI.
-        GUIManager::getInstance().getLuaState()->doString("NotificationLayer.popNotification(\"" + this->getName() + "\")");
+        if(GameMode::showsGraphics())
+            GUIManager::getInstance().getLuaState()->doString("NotificationLayer.popNotification(\"" + this->getName() + "\")");
     }
 
@@ -276 +293 @@
 
         // Removes the Notification from the GUI.
-        GUIManager::getInstance().getLuaState()->doString("NotificationLayer.removeNotification(\"" + this->getName() + "\", " + multi_cast<std::string>(index) + ")");
+        if(GameMode::showsGraphics())
+            GUIManager::getInstance().getLuaState()->doString("NotificationLayer.removeNotification(\"" + this->getName() + "\", " + multi_cast<std::string>(index) + ")");
     }
 
@@ -282 +300 @@
     @brief
         Clears the NotificationQueue by removing all NotificationContainers.
-    */
-    void NotificationQueue::clear(void)
+    @param noGraphics
+        If this is eset to true the GUI is not informed of the clearing of the NotificationQueue. This is needed only internally.
+    */
+    void NotificationQueue::clear(bool noGraphics)
     {
         this->ordering_.clear();
@@ -295 +315 @@
 
         // Clear the NotificationQueue in the GUI.
-        GUIManager::getInstance().getLuaState()->doString("NotificationLayer.clearQueue(\"" + this->getName() + "\")");
+        if(GameMode::showsGraphics() && !noGraphics)
+            GUIManager::getInstance().getLuaState()->doString("NotificationLayer.clearQueue(\"" + this->getName() + "\")");
     }
 

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

@@ -69 +69 @@
 
         There are quite some parameters that influence the behaviour of the NotificationQueue:
-        - 'name': The name of the NotificationQueue. It needs to be unique.
-        - 'senders': The senders that are targets of this NotificationQueue, i.e. the names of senders whose Notifications this NotificationQueue displays.
-        - 'size': The size of the NotificationQueue, it specifies how many @ref orxonox::Notification "Notifications" are displayed at once at the most.
-        - 'displayTime': The time a @ref orxonox::Notification "Notification" is displayed with this NotificationQueue.
+        - @b name The name of the NotificationQueue. It needs to be unique.
+        - @b senders The senders that are targets of this NotificationQueue, i.e. the names of senders whose Notifications this NotificationQueue displays.
+        - @b size The size of the NotificationQueue, it specifies how many @ref orxonox::Notification "Notifications" are displayed at once at the most.
+        - @b displayTime The time a @ref orxonox::Notification "Notification" is displayed with this NotificationQueue.
 
     @author
@@ -85 +85 @@
             virtual ~NotificationQueue();
 
-            /**
-            @brief Destroys the NotificationQueue.
-                   Used in lua.
-            */
-            void destroy(void) { this->OrxonoxClass::destroy(); } // tolua_export
+            //! Destroys the NotificationQueue.
+            void destroy(bool noGraphics = false); // tolua_export
 
             virtual void tick(float dt); //!< To update from time to time.
@@ -168 +165 @@
             void remove(const std::multiset<NotificationContainer*, NotificationContainerCompare>::iterator& containerIterator); //!< Removes the Notification that is stored in the input NotificationContainer.
 
-            void clear(void); //!< Clears the NotificationQueue by removing all NotificationContainers.
+            void clear(bool noGraphics = false); //!< Clears the NotificationQueue by removing all NotificationContainers.
 
     }; // tolua_export

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

@@ -50 +50 @@
         In use it would like this:
         @code
-        <CommandNotification preMessage="Please press " command="someCommand" postMessage=" to do something." >
+        <CommandNotification preMessage="Please press " command="someCommand" postMessage=" to do something." sender="me">
             <events>
                 <trigger>

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

@@ -49 +49 @@
         In use it would like this:
         @code
-        <SimpleNotification message="some message..." >
+        <SimpleNotification message="some message..." sender="me">
             <events>
                 <trigger>