Changeset 7484 for code/trunk/src/modules/notifications

Timestamp:

Sep 23, 2010, 1:00:42 PM (14 years ago)

Author:

dafrick

Message:

Doing some documentation.

Location:

code/trunk/src/modules/notifications

Files:

• Notification.cc (modified) (2 diffs)
• Notification.h (modified) (2 diffs)
• NotificationDispatcher.cc (modified) (2 diffs)
• NotificationDispatcher.h (modified) (2 diffs)
• NotificationManager.cc (modified) (3 diffs)
• NotificationManager.h (modified) (3 diffs)
• NotificationQueue.cc (modified) (1 diff)
• NotificationQueue.h (modified) (2 diffs)
• dispatchers/CommandNotification.cc (modified) (1 diff)
• dispatchers/CommandNotification.h (modified) (2 diffs)
• dispatchers/SimpleNotification.h (modified) (1 diff)

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

@@ -50 +50 @@
         RegisterRootObject(Notification);
         this->initialize();
-        this->registerVariables();
     }
 
@@ -122 +121 @@
     bool Notification::setMessage(const std::string & message)
     {
-        if(this->isSent()) //!< The message cannot be changed if the message has already been sent.
+        if(this->isSent()) // The message cannot be changed if the message has already been sent.
             return false;
         this->message_ = message;

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

@@ -47 +47 @@
     /**
     @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 NotificationQueue (depending on which senders the specific NotificationQueue accepts).
+        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).
     @author
         Damian 'Mozork' Frick
@@ -83 +83 @@
             bool sent_; //!< Whether Notification has been sent, if so it cannot be changed.
 
-            void initialize(void);
-            void registerVariables(void);
+            void initialize(void); //!< Registers the object and sets some default values.
 
     };

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

@@ -93 +93 @@
     }
 
+    /**
+    @brief
+        Registers variables for synchronisation.
+    */
     void NotificationDispatcher::registerVariables(void)
     {
@@ -113 +117 @@
         else if(GameMode::isServer())
         {
+            //TODO: This may fail if the object has not been synchronized, yet.
             callMemberNetworkFunction(NotificationDispatcher, dispatch, this->getObjectID(), clientId, clientId);
         }

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

@@ -47 +47 @@
     /**
     @brief
-        A NotificationDispatcher is an entity that, upon being triggered, dispatches (or sends) a specified Notification.
+        A NotificationDispatcher is an entity that, upon being triggered, dispatches (or sends) a specified @ref orxonox::Notification "Notification".
+
+        Its standard usage is:
+        @code
+        <NotificationDispatcher>
+            <events>
+                <trigger>
+                    <PlayerTrigger />
+                </trigger>
+            </event>
+        </NotificationDispatcher>
+        @endcode
+        But keep in mind, that NotificationDispatcher is an abstract class and in this example @ref orxonox::PlayerTrigger "PlayerTrigger" stands for any event that is caused by a @ref orxonox::PlayerTrigger "PlayerTrigger", so instead of @ref orxonox::PlayerTrigger "PlayerTrigger", there could be a @ref orxonox::DistanceTrigger "DistanceTrigger", or a @ref orxonox::DistanceMultiTrigger "DistanceMutliTrigger", or even an @ref orxonox::EventListener "EventListener" that waits for an event coming from any kind of @ref orxonox::PlayerTrigger "PlayerTrigger".
     @author
         Damian 'Mozork' Frick
@@ -73 +85 @@
             std::string sender_; //!< The name of the sender of the Notification dispatched by this NotificationDispatcher.
 
-           void registerVariables(void);
+            void registerVariables(void); //!< Register some variables for synchronisation.
 
             /**

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

@@ -60 +60 @@
     ManageScopedSingleton(NotificationManager, ScopeID::Graphics, false);
 
+    // Setting console command to enter the edit mode.
     SetConsoleCommand("enterEditMode", &NotificationManager::enterEditMode);
 
@@ -106 +107 @@
     }
 
+    /**
+    @brief
+        Sends a Notification with the specified message to the specified client from the specified sender.
+    @param message
+        The message that should be sent.
+    @param clientId
+        The id of the client the notification should be sent to.
+    @param sender
+        The sender that sent the notification.
+    */
     /*static*/ void NotificationManager::sendNotification(const std::string& message, unsigned int clientId, const std::string& sender)
     {
+        // If we're in standalone mode or we're already no the right client we create and send the Notification.
         if(GameMode::isStandalone() || Host::getPlayerID() == clientId)
         {
@@ -113 +125 @@
             notification->send(sender);
         }
+        // If we're on the server (and the server is not the intended recipient of the Notification) we send it over the network.
         else if(GameMode::isServer())
         {

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

@@ -50 +50 @@
     /**
     @brief
-        The Singleton NotificationManager functions as a gateway between Notifications and NotificationListeners.
-        It receives, organizes Notifications and the redistributes them to the specific NotificationListeners.
+        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.
     @author
         Damian 'Mozork' Frick
@@ -65 +66 @@
             virtual void preDestroy(void); //!< Is called before the object is destroyed.
 
+            /**
+            @brief Get the instance of the NotificationManager Singleton.
+            @return Returns a reference to the NotificationManager.
+            */
             static NotificationManager& getInstance() { return Singleton<NotificationManager>::getInstance(); } // tolua_export
 
@@ -70 +75 @@
             static const std::string NONE; //!< Static string to indicare a sender that sends to no specific NotificationListener.
 
+            //! Sends a Notification with the specified message to the specified client from the specified sender.
             static void sendNotification(const std::string& message, unsigned int clientId, const std::string& sender = NotificationManager::NONE);
 

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

@@ -52 +52 @@
         Constructor. Creates and initializes the object.
     @param name
-        The name of the new NotificationQueue.
+        The name of the new NotificationQueue. It needs to be unique
     @param senders
         The senders that are targets of this NotificationQueue, i.e. the names of senders whose Notifications this NotificationQueue displays.

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

@@ -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; } // Ordered by time.
     };
 
     /**
     @brief
-        Displays Notifications from specific senders.
+        Displays @ref orxonox::Notification "Notifications" from specific senders.
+
+        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.
     @author
         Damian 'Mozork' Frick

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

@@ -80 +80 @@
     }
 
+    /**
+    @brief
+        Register some variables for synchronisation.
+    */
     void CommandNotification::registerVariables(void)
     {

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

@@ -47 +47 @@
         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.
+
+        In use it would like this:
+        @code
+        <CommandNotification preMessage="Please press " command="someCommand" postMessage=" to do something." >
+            <events>
+                <trigger>
+                    <PlayerTrigger />
+                </trigger>
+            </events>
+        </CommandNotification>
+        @endcode
+        Upon being triggered this would display the @ref orxonox::Notification "Notification" "Please press {the binding of the specified command} to do something".
+        For more information on what can be used for @code <PlayerTrigger /> @endcode see the @ref orxonox::NotificationDispatcher "NotificationDispatcher" documentation.
     @author
         Damian 'Mozork' Frick
@@ -86 +99 @@
             std::string postMessage_; //!< The last part of the displayed message.
 
-            void registerVariables(void);
+            void registerVariables(void); //!< Register some variables for synchronisation.
 
             /**

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

@@ -46 +46 @@
     @brief
         The SimpleNotification class enables the sending of (in XML) predefined Notifications upon some kind of triggering event.
+
+        In use it would like this:
+        @code
+        <SimpleNotification message="some message..." >
+            <events>
+                <trigger>
+                    <PlayerTrigger />
+                </trigger>
+            </events>
+        </SimpleNotification>
+        @endcode
+        For more information on what can be used for @code <PlayerTrigger /> @endcode see the @ref orxonox::NotificationDispatcher "NotificationDispatcher" documentation.
     @author
         Damian 'Mozork' Frick