Notifications

Notifications are short messages, that can be sent from anywhere in Orxonox and then are displayed on the screen to inform the user about some occurence he has to know about. More...

Modules
	Dispatchers
	NotificationDispatchers are entities that are instantiated in a level file (through XML) and that dispatch (or send) a specific Notification upon having received a triggering event.

Files
file	NotificationDispatcher.h
	Definition of the NotificationDispatcher class.
file	NotificationListener.h
	Definition of the NotificationListener class.
file	NotificationManager.h
	Definition of the NotificationManager class.
file	NotificationQueue.h
	Definition of the NotificationQueue class.
file	NotificationQueueCEGUI.h
	Definition of the NotificationQueueCEGUI class.

Classes
class	orxonox::Notification
	A Notification represents a short message used to inform the player about something that just happened. More...
struct	orxonox::NotificationContainer
	Container to allow easy handling of the Notifications. More...
struct	orxonox::NotificationContainerCompare
	Struct to allow ordering of NotificationContainers. More...
class	orxonox::NotificationDispatcher
	A NotificationDispatcher is an entity that, upon being triggered, dispatches (or sends) a specified Notification. More...
class	orxonox::NotificationListener
	NotificationListener interface. More...
class	orxonox::NotificationManager
	The Singleton NotificationManager is a NotificationListener and functions as a gateway between Notifications and NotificationQueues. More...
class	orxonox::NotificationQueue
	Displays Notifications from specific senders. More...
class	orxonox::NotificationQueueCEGUI
	Displays Notifications using CEGUI. More...

Detailed Description

Notifications are short messages, that can be sent from anywhere in Orxonox and then are displayed on the screen to inform the user about some occurence he has to know about.

Such an occurence could be, that he just shot and killed his Archnemesis Overlord3, that he just got a new Pickup or that he received a Quest and needs to have a look at the Quest-Menu.

Usage

Let's very briefly talk about what you have to do to either send Notifications from some part of Orxonox or display Notifications on your screen.

Sending notifications

Sending a new Notification from (almost) anywhere in Orxonox is fairly easy. 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 NotificationQueues (the entities that display the Notifications) can decide whether they should display the Notification or not. So the sender is some string that identifies a group of Notifications that have something in common or some entity that is sending them. For example: All Notifications sent by any part of the Questsystem have "questsystem" as sender and thus we could create a NotificationQueue that only displays Notifications from the Questsystem, but more to that later. And lastly you have to decide to whom you want to send this Notification. You have to get the clientId of the intended recipient (e.g. trough a PlayerInfo) or you only send the 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:

NotificationManager::sendNotification(message, clientId, sender, isLocal); // isLocal = false can be ommitted since that is the default value.

Displaying notifications

Displaying Notifications is even easier, all you need to do is to load the NotificationLayer in the level, where you want Notifications displayed. You can either do this manually by executing the following command in the console:

showGUI NotificationLayer false true

Or automatically, by adding a Script to the levelfile that does it for you:

<Script code="showGUI NotificationLayer false true" needsGraphics="true" />

If you want to change the way the Notifications are displayed, you can enter the (at this point rather rudimentary) edit mode and add new NotificationQueues or change position and properties of the existing ones, by executing the following command in the console:

enterEditMode

Technical details

The Notifications module has three major parts that interact with each other. First there is the NotificationQueue, this is the entity that (logically, not effectively) displays Notifications according to some rules, then there is the NotificationLayer, which is the GUI which (actually) displays Notifications by visualizing the NotificationQueues and as a result also the Notifications, that are displayed by the respective NotificationQueues and lastly there is the NotificationManager, which connects these two.

NotificationQueue

The NotificationQueue is the entity, that (as said earlier) logically displays Notifications. Furthermore a NotificationQueue displays only a subset of all the Notifications. The parameters that reduce the range of displayed Notifications are:

• senders The senders, the set of targets of a NotificationQueue is the set of senders a NotificationQueue displays Notifications from. E.g. If one would set the senders to "questsystem" then only 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.
• size The size specifies how many Notifications are displayed at the most, if there are more Notifications that could be displayed, then only the most recent are displayed.
• displayTime The display time specifies how long a Notification is displayed at the most.

NotificationLayer

The NotificationLayer is a GUI sheet, that displays all the NotificationQueues and their 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 NotificationQueues. For every NotificationQueue there is the equivalent representation in the NotificationLayer. So NotificationQueues are not each represented by a GUI sheet, but thely all belong to one and the same GUI sheet, the NotificationLayer.

NotificationManager

The NotificationManager is (hence the name) the managing entity in this setting. It is responsible for the registering and unregistering of NotificationListeners (which the NotificationQueue is) and also informs them about changes related to Notifications. It is also responsible for the creation and destruction of 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 NotificationManager is responsible for sending (and in the process creating) Notifications and is a means for the NotificationQueues to get the information they need about Notifications.

Notification

The 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 NotificationDispatchers.

NotificationDispatcher

NotificationDispatchers are entities that are instantiated in a level file (through XML) and that dispatch (or send) a specific Notification upon having received a triggering event.