Changes

Created page with "THIS DOCUMENT IS A DRAFT = Technical Details = == Description == This feature consists in extending the current notification system, therefore the implemented protocol will st..."
THIS DOCUMENT IS A DRAFT

= Technical Details =

== Description ==

This feature consists in extending the current notification system, therefore the implemented protocol will strictically stick to the "Desktop Notification Protocol" [1], please read this protocol carefully before further reading.

== Features to be implemented ==

=== Standard protocol based ===

The new protocol features to be implemented are:

* Message bubble display, respecting sugar current GUI style and discoverability principles.
* Summary and Body displaying.
* Markup capabilities for the body data, this includes links and excludes images. (image tags should be filtered out)
* Notifications replacement.
* Notifications cancelation.
* Notifications queue based on urgency level hint.

=== Custom ===

* Save the current message information into a journal entry as plain text file.
* Notifications history.

== Sugar scope ==

The current notification service it is splitted in two modules:

* The service backend it being implemented on jarabe.model.notifications
* The service front-end it is implemented on jarabe.frame.frame and its visual elements are defined at jarabe.frame.notification

There is no need to change this modules disposition.

= User Interface Description =

== Description ==

This section describes the graphic elements of interface.

=== The message bubble ===

The extensions should not change any current graphical aspect of the UI. Notification icons will still be displayed at the frame corners where:

* Top left corner is reserved for sugar-shell notifications.
* Top right corner is reserved for friends and presence service notifications.
* Top bottom left is reserved for clipboard.
* Bottom right corner is reserved for devices and networking notifications.

If any notification contains summary or body information, a message palette (the "bubble") will be displayed when cursor activates it by:

* Clicking on the icon.
* Moving the cursor on top of the icon.

This message palette will contain [2]:

* Icon
* Summary text
* Body markup text
* One button for closing the notification. (it will remove the notification icon also)
* One button for saving its content on a journal entry.

=== Notification history ===

This aspect of the feature is still being discussed. Please look at [3] for the last proposal made by Gary Martin.

== Notifications Behaviour ==

It will describe the flow of the notifications from the sender to the display.

If notifications overlap is not considered a problem, there could be no queue at all. Notifications will be displayed when they arrive. If overlap is considered a problem a queueing system will be required, _please_ remember that notifications should not be a common event, therefore we _do not_ need any over complexed queue management algorithm, even though there is the one-in-a-million probability that some notifications never gets to be displayed.

=== Notifications queueing ===

When the notification back-end recieves a new notification _with_ a message, the notification will be queued. The position in the queue can be altered depending on the notification urgency level.

* Notifications of level 0, will simply be queue and wait until it is displayed.
* Notifications of level 1, will be queued ahead of any notification of level 0, but behing of any other notification with the same or a higher level.
* Notifications of level 3, will be queued ahead of any other notification except for the ones with the same urgency level. Notifications of level 3 will force the message palette display.

The notification displaying will depend exclusively on the queue order. Notification that contains no messages could be displayed directly if their respective corner is available (without any current message notification, to avoid overlap. Overlap it is not a problem on icon only by icon only notifications otherwise it will be queued and displayed when the corner is available.

=== Emptying the queue ===

The process goes like this:

* The notification is initially shown only as pulsing icon.
* If it contains a message, the message palette should appear when the user activates it.
* The notifications should be automatically removed after the time specified by the expiration time or a maximum time defined by notification back-end. if it contains a message, it could also be removed explicitly by the user.
* If it contains a message, the notification should stored on a historical registry.

=== Historical registry ===

The notifications historical registry should contain the N last messages, These messages could be removed manually, massively or automatically (when the N maximum amount is reached).

=== Canceling Notifications ===

Notification cancellation should remove the notification from the queue or stop displaying it (In case its being shown).

=== Replacing Notifications ===

This should update the elements of the notification (i,e icons, summary and body).

= Feature Usage =

== Who could or should use this feature ==

* Clipboard, when its being use.
* Filetransfer, when a file sending request is recieved.
* The journal, when its getting close to critical storage state. (before the journal-is-full modal window shows up)
* The XS register, when it gets registered or when it fails to. It could make even more sense if we implemented the automatic registration.
* Automatic system updater, when running notification.
* Automatic backup system, when running or finished a backup.
* Network manager, when connected to a new wireless network or failing to.
* Network manager again, when connecting to a GSM service or failing to.
* Device manager, when a new stored device has been plugin or removed.
* Battery manager, whenrunning out of battery or being connecting to the main power supply.
* Sugar-shell, when important-to-the-user errors occurs. i,e failure on launching activities.
* (Possibly new feature) Sending laptop usage and educational tips.
* Activities related notifications (i,e: messaging clients).
* Use your imagination.

== Usage mechanisms ==

Notification messages usage should respond to the stardard dbus methods.

=== Sending a notification ===

(Example provided by Gonzalo Odiard)

import dbus

BUS_NAME = 'org.freedesktop.Notifications'
OBJ_PATH = '/org/freedesktop/Notifications'
IFACE_NAME = 'org.freedesktop.Notifications'

bus = dbus.SessionBus()
notify_obj = bus.get_object(BUS_NAME,OBJ_PATH)
notifications = dbus.Interface(notify_obj,IFACE_NAME)
notification_id = notifications.Notify("HelloWorld",0,'',"Summary","Body",[],{},-1)

=== Canceling a notification ===

notifications.CloseNotification(notification_id)

=== Notification replacement ===

notifications.Notify("HelloWorld",notification_id,'',"New summary","New body",[],{},-1)

= Resources =

1. http://library.gnome.org/devel/notification-spec/

2. http://people.sugarlabs.org/~tch/images/Screenshot-30.png/

3. http://wiki.sugarlabs.org/go/File:Corner_notification_message_only_history.png/
572

edits