[Orxonox-commit 2781] r7484 - in code/trunk: doc/api src/modules/notifications src/modules/notifications/dispatchers src/modules/objects src/modules/questsystem src/orxonox/interfaces
dafrick at orxonox.net
dafrick at orxonox.net
Thu Sep 23 13:00:42 CEST 2010
Author: dafrick
Date: 2010-09-23 13:00:42 +0200 (Thu, 23 Sep 2010)
New Revision: 7484
Modified:
code/trunk/doc/api/Groups.dox
code/trunk/src/modules/notifications/Notification.cc
code/trunk/src/modules/notifications/Notification.h
code/trunk/src/modules/notifications/NotificationDispatcher.cc
code/trunk/src/modules/notifications/NotificationDispatcher.h
code/trunk/src/modules/notifications/NotificationManager.cc
code/trunk/src/modules/notifications/NotificationManager.h
code/trunk/src/modules/notifications/NotificationQueue.cc
code/trunk/src/modules/notifications/NotificationQueue.h
code/trunk/src/modules/notifications/dispatchers/CommandNotification.cc
code/trunk/src/modules/notifications/dispatchers/CommandNotification.h
code/trunk/src/modules/notifications/dispatchers/SimpleNotification.h
code/trunk/src/modules/objects/Script.h
code/trunk/src/modules/questsystem/QuestEffectBeacon.cc
code/trunk/src/modules/questsystem/QuestManager.h
code/trunk/src/orxonox/interfaces/NotificationListener.h
Log:
Doing some documentation.
Modified: code/trunk/doc/api/Groups.dox
===================================================================
--- code/trunk/doc/api/Groups.dox 2010-09-23 09:21:01 UTC (rev 7483)
+++ code/trunk/doc/api/Groups.dox 2010-09-23 11:00:42 UTC (rev 7484)
@@ -335,7 +335,9 @@
@section SampleQuest Sample quest
To get your head around all of this and see some of the things mentioned here in action you might want to check out the "The Tale of Princess Aeryn"-Quest (Levelfile: princessaeryn.oxw) in the level-folder.
+*/
+/**
@defgroup QuestEffects Effects
@ingroup Questsystem
Modified: code/trunk/src/modules/notifications/Notification.cc
===================================================================
--- code/trunk/src/modules/notifications/Notification.cc 2010-09-23 09:21:01 UTC (rev 7483)
+++ code/trunk/src/modules/notifications/Notification.cc 2010-09-23 11:00:42 UTC (rev 7484)
@@ -49,7 +49,6 @@
{
RegisterRootObject(Notification);
this->initialize();
- this->registerVariables();
}
/**
@@ -121,7 +120,7 @@
*/
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;
return true;
Modified: code/trunk/src/modules/notifications/Notification.h
===================================================================
--- code/trunk/src/modules/notifications/Notification.h 2010-09-23 09:21:01 UTC (rev 7483)
+++ code/trunk/src/modules/notifications/Notification.h 2010-09-23 11:00:42 UTC (rev 7484)
@@ -46,7 +46,7 @@
/**
@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
*/
@@ -82,8 +82,7 @@
std::string sender_; //!< The sender of the notification.
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.
};
Modified: code/trunk/src/modules/notifications/NotificationDispatcher.cc
===================================================================
--- code/trunk/src/modules/notifications/NotificationDispatcher.cc 2010-09-23 09:21:01 UTC (rev 7483)
+++ code/trunk/src/modules/notifications/NotificationDispatcher.cc 2010-09-23 11:00:42 UTC (rev 7484)
@@ -92,6 +92,10 @@
XMLPortEventState(NotificationDispatcher, BaseObject, "trigger", trigger, xmlelement, mode);
}
+ /**
+ @brief
+ Registers variables for synchronisation.
+ */
void NotificationDispatcher::registerVariables(void)
{
registerVariable(this->sender_, VariableDirection::ToClient);
@@ -112,6 +116,7 @@
}
else if(GameMode::isServer())
{
+ //TODO: This may fail if the object has not been synchronized, yet.
callMemberNetworkFunction(NotificationDispatcher, dispatch, this->getObjectID(), clientId, clientId);
}
}
Modified: code/trunk/src/modules/notifications/NotificationDispatcher.h
===================================================================
--- code/trunk/src/modules/notifications/NotificationDispatcher.h 2010-09-23 09:21:01 UTC (rev 7483)
+++ code/trunk/src/modules/notifications/NotificationDispatcher.h 2010-09-23 11:00:42 UTC (rev 7484)
@@ -46,7 +46,19 @@
/**
@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
*/
@@ -72,7 +84,7 @@
protected:
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.
/**
@brief Set the sender of the Notification dispatched by this NotificationDispatcher.
Modified: code/trunk/src/modules/notifications/NotificationManager.cc
===================================================================
--- code/trunk/src/modules/notifications/NotificationManager.cc 2010-09-23 09:21:01 UTC (rev 7483)
+++ code/trunk/src/modules/notifications/NotificationManager.cc 2010-09-23 11:00:42 UTC (rev 7484)
@@ -59,6 +59,7 @@
ManageScopedSingleton(NotificationManager, ScopeID::Graphics, false);
+ // Setting console command to enter the edit mode.
SetConsoleCommand("enterEditMode", &NotificationManager::enterEditMode);
registerStaticNetworkFunction(NotificationManager::sendNotification);
@@ -105,13 +106,25 @@
this->queues_.clear();
}
+ /**
+ @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)
{
Notification* notification = new Notification(message);
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())
{
callStaticNetworkFunction(NotificationManager::sendNotification, clientId, message, clientId, sender);
Modified: code/trunk/src/modules/notifications/NotificationManager.h
===================================================================
--- code/trunk/src/modules/notifications/NotificationManager.h 2010-09-23 09:21:01 UTC (rev 7483)
+++ code/trunk/src/modules/notifications/NotificationManager.h 2010-09-23 11:00:42 UTC (rev 7484)
@@ -49,8 +49,9 @@
/**
@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
*/
@@ -64,11 +65,16 @@
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
static const std::string ALL; //!< Static string to indicate a sender that sends to all NotificationListeners.
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);
bool registerNotification(Notification* notification); //!< Registers a Notification within the NotificationManager.
Modified: code/trunk/src/modules/notifications/NotificationQueue.cc
===================================================================
--- code/trunk/src/modules/notifications/NotificationQueue.cc 2010-09-23 09:21:01 UTC (rev 7483)
+++ code/trunk/src/modules/notifications/NotificationQueue.cc 2010-09-23 11:00:42 UTC (rev 7484)
@@ -51,7 +51,7 @@
@brief
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.
The senders need to be seperated by commas.
Modified: code/trunk/src/modules/notifications/NotificationQueue.h
===================================================================
--- code/trunk/src/modules/notifications/NotificationQueue.h 2010-09-23 09:21:01 UTC (rev 7483)
+++ code/trunk/src/modules/notifications/NotificationQueue.h 2010-09-23 11:00:42 UTC (rev 7484)
@@ -53,19 +53,25 @@
//! Container to allow easy handling.
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.
};
//! Struct to allow ordering of NotificationContainers.
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
*/
Modified: code/trunk/src/modules/notifications/dispatchers/CommandNotification.cc
===================================================================
--- code/trunk/src/modules/notifications/dispatchers/CommandNotification.cc 2010-09-23 09:21:01 UTC (rev 7483)
+++ code/trunk/src/modules/notifications/dispatchers/CommandNotification.cc 2010-09-23 11:00:42 UTC (rev 7484)
@@ -79,6 +79,10 @@
XMLPortParam(CommandNotification, "postMessage", setPostMessage, getPostMessage, xmlelement, mode);
}
+ /**
+ @brief
+ Register some variables for synchronisation.
+ */
void CommandNotification::registerVariables(void)
{
registerVariable(this->command_, VariableDirection::ToClient);
Modified: code/trunk/src/modules/notifications/dispatchers/CommandNotification.h
===================================================================
--- code/trunk/src/modules/notifications/dispatchers/CommandNotification.h 2010-09-23 09:21:01 UTC (rev 7483)
+++ code/trunk/src/modules/notifications/dispatchers/CommandNotification.h 2010-09-23 11:00:42 UTC (rev 7484)
@@ -46,6 +46,19 @@
@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.
+
+ 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
*/
@@ -85,7 +98,7 @@
std::string preMessage_; //!< The first part of the displayed message.
std::string postMessage_; //!< The last part of the displayed message.
- void registerVariables(void);
+ void registerVariables(void); //!< Register some variables for synchronisation.
/**
@brief Set the command, whose key is displayed.
Modified: code/trunk/src/modules/notifications/dispatchers/SimpleNotification.h
===================================================================
--- code/trunk/src/modules/notifications/dispatchers/SimpleNotification.h 2010-09-23 09:21:01 UTC (rev 7483)
+++ code/trunk/src/modules/notifications/dispatchers/SimpleNotification.h 2010-09-23 11:00:42 UTC (rev 7484)
@@ -45,6 +45,18 @@
/**
@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
*/
Modified: code/trunk/src/modules/objects/Script.h
===================================================================
--- code/trunk/src/modules/objects/Script.h 2010-09-23 09:21:01 UTC (rev 7483)
+++ code/trunk/src/modules/objects/Script.h 2010-09-23 11:00:42 UTC (rev 7484)
@@ -80,6 +80,7 @@
This would hide the QuestGUI as soon as a Pawn got in range of the DistanceTrigger. The mode is 'normal', it is specified here, but could be ommitted as well, since it is the default. OnLoad is false, that is why it can't be ommitted. Also needsGraphics is set to true because showGUI needs graphics to work.
@author
Benjamin Knecht
+ @author
Damian 'Mozork' Frick
*/
class _ObjectsExport Script : public BaseObject, public Synchronisable, public ClientConnectionListener
Modified: code/trunk/src/modules/questsystem/QuestEffectBeacon.cc
===================================================================
--- code/trunk/src/modules/questsystem/QuestEffectBeacon.cc 2010-09-23 09:21:01 UTC (rev 7483)
+++ code/trunk/src/modules/questsystem/QuestEffectBeacon.cc 2010-09-23 11:00:42 UTC (rev 7484)
@@ -51,7 +51,6 @@
@brief
Constructor. Registers the object and initializes defaults.
*/
- //TODO: Make just BaseObject?
QuestEffectBeacon::QuestEffectBeacon(BaseObject* creator) : StaticEntity(creator)
{
RegisterObject(QuestEffectBeacon);
Modified: code/trunk/src/modules/questsystem/QuestManager.h
===================================================================
--- code/trunk/src/modules/questsystem/QuestManager.h 2010-09-23 09:21:01 UTC (rev 7483)
+++ code/trunk/src/modules/questsystem/QuestManager.h 2010-09-23 11:00:42 UTC (rev 7484)
@@ -49,7 +49,7 @@
/**
@brief
Is a Singleton and manages @ref orxonox::Quest "Quests", by registering every @ref orxonox::Quest "Quest" / @ref orxonox::QuestHint "QuestHint" (through registerX()) and making them globally accessible (through findX()).
- @ref orxonox::Quest "Quests" (and @ref orxonox::QuestHint 2) are registered in the QuestManager with their id, and can be accessed in the same way.
+ @ref orxonox::Quest "Quests" (and @ref orxonox::QuestHint "QuestHints") are registered in the QuestManager with their id, and can be accessed in the same way.
@author
Damian 'Mozork' Frick
*/
Modified: code/trunk/src/orxonox/interfaces/NotificationListener.h
===================================================================
--- code/trunk/src/orxonox/interfaces/NotificationListener.h 2010-09-23 09:21:01 UTC (rev 7483)
+++ code/trunk/src/orxonox/interfaces/NotificationListener.h 2010-09-23 11:00:42 UTC (rev 7484)
@@ -27,8 +27,9 @@
*/
/**
- @file
+ @file NotificationListener.h
@brief Definition of the NotificationListener class.
+ @ingroup Notifications
*/
#ifndef _NotificationListener_H__
@@ -51,17 +52,35 @@
/**
@brief
NotificationListener interface.
+
+ The NotificationListener interface presents a means to being informed when @ref orxonox::Notification "Notifications" in the target set of this NotificationListener change. (e.g. @ref orxonox::Notification "Notifications" were added or removed)
+ When inheriting from a NotificationListener it is important to register (in the constructor) and unregister (in the destructor) it to and from the @ref orxonox::NotificationManager "NotificationManager".
@author
Fabian 'x3n' Landau
*/
+ //TODO: Needed? Remove or move some NotificationQueue things over here.
class _OrxonoxExport NotificationListener : virtual public OrxonoxClass
{
public:
NotificationListener();
virtual ~NotificationListener() {}
- virtual const std::set<std::string> & getTargetsSet() = 0;
+ /**
+ @brief Get the senders that are targets of this NotificationListener.
+ @return Returns the set of senders that are targets of this NotificationListener.
+ */
+ virtual const std::set<std::string> & getTargetsSet(void) = 0;
+
+ /**
+ @brief Updates the whole NotificationListener.
+ This is called by the @ref orxonox::NotificationManager "NotificationManager" when the @ref orxonox::Notification "Notifications" have changed so much, that the NotificationListener may have to re-initialize his operations.
+ */
virtual void update(void) = 0;
+ /**
+ @brief Updates the NotificationListener, when a new Notification has come in at the specified time.
+ @param notification A pointer to the @ref orxonox::Notification "Notification".
+ @param time The time the @ref orxonox::Notification "Notification" has come in.
+ */
virtual void update(Notification* notification, const std::time_t & time) = 0;
};
}
More information about the Orxonox-commit
mailing list