• Intro
• Downloads
• Community
• Development
• News
• TALK

PyMaemo/HildonDesktop

Python bindings for libhildondesktop

These bindings allow to create the so called Hildon Home and Status Menu applets (or widgets, in Maemo 5). It consists of two binary packages:

• python-hildondesktop: the actual Python bindings. Can be used to write standalone widgets, or ones that can be added by the user using the "Add widget" option in Maemo 5.
• hildon-desktop-python-loader: this is a Hildon Desktop loader for Python plugins.

API changes for Fremantle

The libhildondesktop version in Fremantle contains some API changes that also reflect on the Python bindings. Namely, you should pay attention to the following differences when migrating Home Widgets from older Maemo releases to Fremantle:

• The base class for Home Widgets is now called "HomePluginItem", instead of the older "HomeItem" name.
• The base class for Status menu widgets is now called "StatusMenuItem", instead of the older "StatusBarItem".
• The callback function that is called by the load is now called "hd_plugin_get_object", instead of the older "hd_plugin_get_objects". This is so because in fremantle the plugin is can create only one plugin object.
• Also note that the "hd_plugin_get_object" function should return a single object, instead of a list.
• The returned object must be instantiated using the gobject.new() function (see the example below). This is necessary because the plugin-id property needs to be set, otherwise the hildon-home process will crash.

NOTE: this last requirement might change in future, to avoid the mentioned crash.

Example - Home widgets (Fremantle only)

The code below was based on the C example that can be found on the maemo-examples package sources [1].

import gobject
import gtk
import hildondesktop

class HelloWorldButton(gtk.Button):
    def __init__(self, padding):
        gtk.Button.__init__(self)
        icon_theme = gtk.icon_theme_get_default()
        icon = icon_theme.load_icon("hello", 40, 0)
        if icon is None:
            icon = icon_theme.load_icon("qgn_list_gene_default_app", 40, 0)
        icon_image = gtk.Image()
        icon_image.set_from_pixbuf(icon)
        icon_image.set_padding(padding, padding)
        self.add(icon_image)
        self.show_all()

class HelloWorldDialog(gtk.Dialog):
    def __init__(self):
        gtk.Dialog.__init__(self, "Hello World", None,
                            gtk.DIALOG_DESTROY_WITH_PARENT | gtk.DIALOG_NO_SEPARATOR,
                            ("Close", gtk.RESPONSE_OK))
        self.vbox.add(gtk.Label("Hello World!"))
        self.show_all()

def hello_world_dialog_show(button):
    dialog = HelloWorldDialog()
    dialog.run()
    dialog.destroy()

class HelloHomePlugin(hildondesktop.HomePluginItem):
    __gtype_name__ = 'HelloHomePlugin'

    def __init__(self):
        hildondesktop.HomePluginItem.__init__(self)
        button = HelloWorldButton(10)
        button.connect("clicked", hello_world_dialog_show)
        button.show_all()
        self.add(button)

def hd_plugin_get_object():
    return gobject.new(HelloHomePlugin, plugin_id="hello_world_home")

if __name__ == "__main__":
    obj = hd_plugin_get_object()
    obj.show_all()
    gtk.main()

Testing the example

First, add Fremantle extras-devel to the /etc/apt/sources.list in your scratchbox target and install the required packages:

[sbox]> fakeroot apt-get install python-hildondesktop hildon-desktop-python-loader

Save the example code shown above as /usr/lib/hildon-desktop/hello_world_home.py inside your FREMANTLE_X86 target. Next, save the following text as /usr/share/applications/hildon-home/hello_world_home.desktop:

[Desktop Entry]
Name=Hello, World! (Python)
Comment=Example Home Python plugin
Type=python
X-Path=hello_world_home.py

Make sure the hildon desktop and hildon-home are running. For that, you can use the following commands:

[sbox]> export DISPLAY=:2 # if you are using scratchbox + Xephyr
[sbox]> af-sb-init.sh start
[sbox]> run-standalone.sh maemo-summoner /usr/bin/hildon-home.launch &

Now you need to add the newly installed home widget to the desktop. For that you can either manually add it to the ~/.config/hildon-desktop/home.plugins file, or follow these instructions to add it using the Hildon Desktop interface:

1. Click anywhere on the Maemo desktop background.
2. You should see a "engine" icon on the top right. Click on it.
3. It will be shown a menu bar containing "Desktop menu" and "Done". Click on "Desktop menu".
4. You should now see a menu with 4 buttons. Click on the "Add widget" button.
5. A menu containing the list of installed widgets will appear. Select the one we installed, called "Hello, World! (Python)".
6. Finally, click on "Done".

You should then see the following (the images look distorted because they were taken on Xephyr):

After clicking on the widget button, you should see:

Example - Status menu widgets (Fremantle only)

The code below was based on the C example that can be found on the Maemo 5 Developer Guide [2].

import gobject
import gtk
import hildondesktop

class ExampleStatusPlugin(hildondesktop.StatusMenuItem):
    __gtype_name__ = 'ExampleStatusPlugin'

    def __init__(self):
        hildondesktop.StatusMenuItem.__init__(self)
        
        STATUS_AREA_EXAMPLE_ICON_SIZE = 22
        icon_theme = gtk.icon_theme_get_default()
        pixbuf = icon_theme.load_icon("general_email", STATUS_AREA_EXAMPLE_ICON_SIZE, gtk.ICON_LOOKUP_NO_SVG)
        self.set_status_area_icon(pixbuf)
        
        label = gtk.Label("Example message")
        self.add(label)
        self.show_all()

def hd_plugin_get_object():
    return gobject.new(ExampleStatusPlugin, plugin_id="example_status_plugin")

if __name__ == "__main__":
    obj = hd_plugin_get_object()
    obj.show_all()
    gtk.main()

Testing the example

First, install the same packages needed for Home widgets, then save the example above as as /usr/lib/hildon-desktop/hello_world_status_menu.py inside your FREMANTLE_X86 target. Next, save the following text as /usr/share/applications/hildon-status-menu/hello_world_status_menu.desktop:

[Desktop Entry]
Name=Hello, World! (Python)
Comment=Example Status Menu Python plugin
Type=python
X-Path=hello_world_status_menu.py

Make sure the hildon desktop and hildon-status-menu are running. For that, you can use the following commands:

[sbox]> export DISPLAY=:2 # if you are using scratchbox + Xephyr
[sbox]> af-sb-init.sh start
[sbox]> run-standalone.sh maemo-summoner /usr/bin/hildon-home.launch &

The example status menu widget should appear as soon as hildon-status-menu process is started, as the plugin used in this example is of the permanent category. See [3] for more information of status menu widgets categories.

This is a screenshot taken on Xephyr showing how the widget will look like:

When clicked, it will show the specified message, enclosed in a gtk.Label: