Re: Articles due today (And misc. updates)

[Ken VanDine <ken vandine org>]

Here is a draft of my article, feedback is welcome.  But please no
editing yet, I want to run it by one of the indicator authors next
week to make sure I am describing things property.  I am still missing
the C examples, but should have those next week as well.

--Ken

On Fri, Apr 10, 2009 at 10:12 AM, Paul Cutler
<pcutler foresightlinux org> wrote:
> Good morning,
>
> If you are writing or updating articles for our next edition, those
> articles are due today.  Per my email earlier in this week, I was
> recommending a May 15th publication date - so I think we have some
> time built in if you need an extra couple of days.  If you do though,
> please let me know so I can plan accordingly.
>
> I have reached out to Jeff Waugh 3 times in the last week and a half
> about moving GNOME Journal to the blogs.gnome.org infrastructure.
> Unfortunately, I have not received a reply.  If we don't make progress
> on this in the next week or so, we will be publishing the next edition
> in Textile, our current CMS.  (This also gives writers an extra few
> days, if we use the current CMS we can probably the publish date
> forward).
>
> Josh Adams and his firm have volunteered to take a look at the current
> Wordpress theme and some of the CSS work that needs to be done.
> Vincent Untz has been helpful in tracking down where our files are on
> the GNOME servers. I am hopeful a GNOME sysadmin will be able to get
> us a copy of those files or access in the very near future.
>
> I haven't received any feedback on the proposed release cycle - does a
> 60 day cycle sound good?  Do you think it's realistic and attainable?
> If we agree to this, I'll need everyone's help, especially when it
> comes time to call for new articles.  So if you microblog on Twitter
> or identi.ca, or have a blog, the more we can spread the word the
> better.
>
> Thanks!
>
> Paul
> _______________________________________________
> Gnome-journal-list mailing list
> Gnome-journal-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-journal-list
>

An introduction to the message indicator

The messaging indicator, also known as the indicator-applet, is a central place to keep track of messages that you might need to be concerned about.  The focus is on human-to-human messaging, for example; instant messaging, e-mail, social networking, etc.  By tracking these in a single applet, instead of displaying separate icons in the noticiation area or on the panel, we save a considerable amount of realestate and cut down on the clutter.  We also get the benefit of a single place in the panel to find messages waiting review.  For more information on the rationale, check out the specification [1].

Current applications that take advantage of the messaging indicator include:
 * pidgin, with patches to pidgin-libnotify
 * evolution, with evolution-indicator
 * gajim, with patches but already excepted upstream
 * gwibber

To effectively use the messaging indicator with your application, you should keep two things in mind:
 * Default to hiding your applications icon from the notification area
 * Rely on the indicator to for raising/hiding your application as well as quick access to incoming messages

Lets walk through some examples.  The library used to interact with the the messaging indicator is called libindicate, in C.  There are also python bindings to libindicate, called python-indicate.  

Using it is actually pretty simple, you need to create a server and a client.  The server registers itself with the indicator, which displays an item in the messaging menu for the application.  When selecting entry in the message menu, it calls the display method for the server.  This is very useful for access to the application itself, like raising the buddy list in pidgin, etc.  Examples included below in python and you can find examples at the end of the article in C as well.

First we create the server object
<code>
    server = indicate.indicate_server_ref_default()
</code>

Set the message type and subtype, valid types include 
 * "message" -- a user level message.  This includes e-mail, IM and SMS messages.
 * "system" -- a software update or other notification about the system state.
 * "media" -- a notification related media the user is listening to in the background

message.instant, message.micro, and message.im
<code>
    server.set_type("message.im")
</code>

We can get some descriptive information to display in the messaging menu from a desktop file provided by the application
<code>
    server.set_desktop_file("/usr/share/applications/pidgin.desktop")
</code>

Now that all the setup work is done, we just need to connect it to the indicator.  The second arguement to this method call is the name of the method to call when selecting the entry in the messaging menu.  The show method shows the indicator after connecting.
<code>
    server.connect("server-display", server_display)
    server.show()
</code>

The client tells the server there is a message waiting, and when the message is selected in the the messaging menu it calls the display method for the client.  When this method gets called, it also clears the event from the list.

Setup the message object
<code>
    indicator = indicate.IndicatorMessage()
</code>
Then we need to set some properties for the message, available properties are:
 * "subject" -- "message" (optional) -- This is the subject line of an e-mail or message.
 * "sender" -- "message" (required) -- The person who sent the message
 * "body" -- "message" (required) -- The body of the message sent to the user
<code>
    indicator.set_property("subtype", "im")
    indicator.set_property("sender", "Test message")
    indicator.set_property("body", "Test message body")
    indicator.set_property_time("time", time())
</code>

The only things left to do is show the message and connect it to a method.  The second argument in the connect method is the method to call when the message is selected.
<code>
    indicator.show()
    indicator.connect("user-display", display)
</code>

Here is a complete python example:
<code>
#!/usr/bin/env python

import indicate
import gobject
import gtk
from time import time
import os

curdir = os.getcwd()
desktop_file = os.path.join(curdir, "example-indicator.desktop")

def timeout_cb(indicator):
    print "Modifying properties"
    indicator.set_property_time("time", time())
    return True

def display(indicator):
    print "Ah, my indicator has been displayed"
    indicator.hide()

def server_display(server):
    print "Ah, my server has been displayed"


if __name__ == "__main__":
    # Setup the server
    server = indicate.indicate_server_ref_default()
    server.set_type("message.im")
    server.set_desktop_file(desktop_file)
    server.connect("server-display", server_display)
    server.show()

    # Setup the message
    indicator = indicate.IndicatorMessage()
    indicator.set_property("subtype", "im")
    indicator.set_property("sender", "Test message")
    indicator.set_property("body", "Test message body")
    indicator.set_property_time("time", time())
    indicator.show()
    indicator.connect("user-display", display)

    # Loop
    gobject.timeout_add_seconds(5, timeout_cb, indicator)
    gtk.main()

</code>

C example:
<code>
</code>

Example desktop file example-indicator.desktop:
<code>
[Desktop Entry]
Version=1.0
Name=Example Indicator
Type=Application
</code>


CONCLUSION
Add some stuff about porting existing apps to use the MI, either if you are the maintainer or not.  Go do it and submit your patches upstream (and to your distro of choice)

[1] https://wiki.ubuntu.com/MessagingMenu