Source

Think of a Source as a source of notifications - many notifications can come from the same source (for example many email notifications coming from your one email client).
In fact, all notifications require a source.

You can also think of a Source as the icon in the message tray (that you click on to show its notifications).

The basic Source class is MessageTray.Source. To be used, it needs to know what icon to show in the Message Tray.

The Source provides the icon in the message tray.

GNOME 3.6

In GNOME 3.6, the way to do this is to feed the icon's name into MessageTray.Source's constructor (along with the title of the source):

Alternatively if you wanted something more fancy, you could override Source.createIcon(size) in a subclass to return an icon of the appropriate size for the source.

GNOME 3.2, 3.4

In GNOME 3.2 and 3.4, you tell the Source what icon it should show in the message tray with one of two methods:

a. when you create a notification for the source, set the icon explicitly in the notification, OR
b. subclass it, implement the createNotificationIcon() function and call _setSummaryIcon with it in the constructor.

Method b. is the one most commonly used, but to do method a) you feed in an object as the fourth parameter to MessageTray.Notification with an 'icon' property (explained a bit more in the Notification section):

Notification

Recall that every notification must belong to a source. Once a notification is added to its source, it can also be "notified".

When a notification is "notified", it pops up from the bottom of the screen showing the user the notification's title and the first line of its details (if they fit).

A notification upon being notified (above); the same notification being opened from its source (below).

Hovering the mouse over the notification will expand it, showing the full summary of the notification.

Actually clicking on the notification will usually dismiss it (unless you override this behaviour).

After a while the notification will time out, dropping back down off the screen.

After this happens there are a couple of options:

if the notification is set as "transient", it will disappear forever. Make a notification transient with notification.setTransient(true).

otherwise (the default), it will now reside in the message tray. Clicking on the notification's icon in the message tray will show the notification, from which it may be dismissed (by clicking on it).

if you want a notification to never be able to be dismissed (by clicking on it after clicking on its source in the message tray), you can set the notification to be "resident". Do this with notification.setResident(true).

The base notification class is MessageTray.Notification, and it allows the construction of very versatile notifications.
At its most basic, the notification has a text title and a text summary:

However, it is also possible to construct much more complex notifications. One can add buttons to the notification with notification.addButton, add extra text labels to it with notification.addBody, or extra actors (entry boxes, pictures, ...) to it with notification.addActor.

For an example of a notification with buttons on it, see the Telepathy Client AudieoVideoNotification (in telepathyClient.js), which has two buttons for the user to accept or reject a call.

AudioVideoNotification has had buttons added

For an example of a very complex notification, see the TelepathyClient.ChatNotification in telepathyClient.js. This adds chat texts to a scrollable area, and adds an entry box for typing chat messages.