*** About ***

This is an OSD (On Screen Display) GNOME component.  It displays messages
overlaid on your screen, using  shaped windows and pango for rendering.  It was
inspired by XOSD (http://www.ignavus.net/software.html).  At least the concept,
because I didn't even look at the API.

Yes, it totally lacks any usability studies.  But well, I like it, and that's
what matters, for now, until GNOME gurus find a definitive notification system.


*** Installation ***

  Requirements: gnome-python >= 2.6.0

  Just ./configure && make && sudo make install.

  Warning: You might need to run gconftool-2 --shutdown, if you're installing
from a running gnome session.


*** Usage ***

It uses bonobo as main API, so it's very easy to use.  Look at gnome-osd-client
to see how it works.

Alternatively, pygtk programmers may use the gnomeosd.gosd module
directly, but it lacks certain features of the daemon, such as:
	- Automatic hiding of messages;
	- Preventing messages from different apps overwriting each other.
        - Animations
        - etc.


Programs/plugins included:

  - gnome-osd-client: a simple command-line client interface. Usage:
	gnome-osd-client <marked-up-text>
		| <marked-up-text>: message to display in pango markup[1]
        or:
	gnome-osd-client -f <message>
		| <message>: message to display. See the section
                             "Message Protocol" below for more information.

	This gets installed to your PATH, so you may use it in shell scripts.


 - xchatosd.py: xchat plugin that monitors IRC messages with your name
        (usually highlighted in xchat), and notifies you on screen,
        optionally showing the full message.  You have to install this
        yourself, by copying to ~/.xchat2/.

        This gets installed to $prefix/share/gnome-osd/
 
 - rbosd.py: rhythmbox OSD song notification.  You have to install this
        yourself, somewhere.  To start, simply run the program with no
        arguments.  From there on, every time rhythmbox changes song,
        you get an OSD message notifying you of this.

        This gets installed to $prefix/share/gnome-osd/


*** Message Protocol  ***

The protocol used by Gnome OSD is XML based (surprise!).

<message ..attributes..> ...pango markup[1]... </message>

The <message> XML element accepts the following attributes:

        - 'id': this allows you to create or use alternative OSD
instance; By specifying different IDs, you can keep several messages
on the screen at the same time.  But for each ID, only one message can
be displayed at a time.  If not specified, id='default' is assumed.

        - 'inherit': Can be used in conjunction with 'id', to specify
that the new OSD instance (which must not already exist) inherits
properties from the instance identified by 'inherit'.  If not
specified, inherit='default'.

        - Any gnome-osd gconf key name[2]: These control several
message properties.  This can only be used for messages with ID
'default'.  Property overrides are remembered across messages for the
same ID.  For instance, if you specify animations='false' for
id='foo', next message with id='foo' will have animations turned off
by default.

Example:
gnome-osd-client -f "<message id='myplugin' osd_fake_translucent_bg='on'
 osd_vposition='center' animations='off' hide_timeout='1000'
 osd_halignment='right'>Volume: 96%</message>"


[1] http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
[2] Run "gconf-editor /apps/gnome-osd" for a list, with respective documentation.
