Development Guides: Simple Applications
Developing a Basic Python Application
Sample Code

Introduction to This Document
This guide explains how to develop a basic Python* application for the Moblin platform. We will guide you through writing and analyzing a Hildon application which was written in Python.

This document assumes that the reader is familiar with the following:
  • Basic Linux knowledge
  • Understanding of Mobile Internet Devices (MIDs)
  • Basic knowledge of development using Python
  • Basic knowledge of GTK

First we will provide a brief introduction to Moblin development. Then we will describe how to develop a basic Python application under the Moblin platform. We use a sample Hildon application, which can be found here.

 

Introduction to Python
Python is an interpreted language, and the interpreter can be used interactively, which makes it easy to write throw-away programs, or to test functions during bottom-up program development[1]. Python is powerful and fully defined on expressions, statements, data types, functions, modules, exceptions, and user-defined classes[1]. Python allows you to split your program into modules that can be reused in other Python programs. Python comes with a large collection of standard modules that you can use as the basis of your programs. Some of these modules provide things like file I/O, system calls, sockets, and even interfaces to graphical user interface (GUI) toolkits, like Gtk[1]. In general, if you'd like to write a small custom database, a specialized GUI application, or a simple game, Python is just the language for you.

For information about basic programming using Python, you may refer to the Python Tutorial at http://docs.python.org/tut or the Python documentation at http://docs.python.org/.

Get Started
Python is a good language for quickly developing applications and prototyping. Python has modules which provides support for file I/O, system calls, threading, GTK (PyGTK), etc[3], so Python can be used to conveniently develop applications for the Moblin platform.

Before developing applications, you need to configure the development environment. We recommend that you develop in the target device's build-environment, which can be created using Moblin Image Creator. This SDK includes guides on installing and using Moblin Image Creator.

Once you have created the development environment, you must make sure you have the required libraries and tools installed. You must make sure Python, together with its core bindings (python-dbus, python-gtk2, python-hildon), are installed[4]. You can use apt or yum (depending on the package manager you are using) to install them. For example, when using apt to install, you can run apt-get install python python-dbus python-gtk2 python-hildon.

Below we provide a simple Python Hildon application, and introduce how to write and execute it on the Moblin platform.

Writing our first Moblin Python Hello World
First, we are going to write a simple hello world python application for the Moblin platform. You should use Moblin Image Creator and chroot into the target file-system. We will be adding all of our code to a script, py-hello-world. First, we will write the script, which will launch a GUI app that displays "Hello World! (hildon)" and can quit. Then we will create a desktop entry file, and save that and the Hello World icons to the appropriate folders. This allows the Hildon Desktop Environment to show the icon from the Home Screen UI. You will be able to select the application's icon to launch the application.

Writing Hello World
Here we actually begin writing the script.

Create the following python script, py-hello-world.py:
#!/usr/bin/python

import gtk, pygtk, hildon

class HildonHelloWorld(hildon.Program):
    def __init__(self):
        hildon.Program.__init__(self)

        self.window = hildon.Window()
        self.add_window(self.window)

        self.window.set_title("Hello World")
        self.window.connect("destroy", gtk.main_quit)

        label = gtk.Label("Hello World! (hildon)")
        self.window.add(label)

        self.window.show_all()

    def run(self):
        gtk.main()

        if __name__ == "__main__":
            app = HildonHelloWorld()
            app.run()

Let's explain the Hildon-specific scripts above, to see how to create a Hildon window in Python.

The required Python modules for a moblin-hildon applications are:
import gtk, pygtk, hildon

We need to create a HildonHelloWorld class, that is derived from the HildonProgram class. The HildonProgram class is a programmer commodity used to apply program-wide settings to all Hildon windows used by the application (for example, this allows you to have a common menu and toolbar on all windows). In addition, HildonProgram also manages other program-wide issues, such as hibernating [4].

The HildonHelloWorld(hildon.Program) class:
class HildonHelloWorld(hildon.Program):
def __init__(self):
    hildon.Program.__init__(self)


In the __init__ method of HildonHelloWorld, create a HildonWindow object and add it into the HildonProgram. The HildonWindow class overloads the GtkWindow class, providing the Hildon theme (look and feel) for top level windows.
self.window = hildon.Window()
self.add_window(self.window)


The Desktop Entry File & Icon Files

Create a desktop file py-hello-world.desktop associated with this Python application. The content of this file is:
[Desktop Entry]
Version=1.0
Type=Application
Encoding=UTF-8
Name=Hello World
Icon=py-hello-world
Exec=py-hello-world
Categories=Mobile;Testing
X-Osso-Service=org.moblin.pyhelloworld

Add this desktop file into /usr/share/mobile-basic-flash/applications/ on the target.

Also, if you downloaded our sample code, add the py-hello-world.png icon files into /usr/share/icons/hicolor/16x16/apps/, /usr/share/icons/hicolor/32x32/apps/, and /usr/share/icons/hicolor/64x64/apps/ on the target.

Adding the D-Bus Service File
In this step, you should create a D-Bus service file, making sure that the value of the "Name" tag is exactly the same as the value of the "X-Osso-Service" tag in the desktop entry file we created above. We will do more with the D-Bus in a later section. For now you should just create the service file associated with this Python application, and call it org.moblin.pyhelloworld.service.

The content of this file is:
[D-Bus Service]
Name=org.moblin.pyhelloworld
Exec=/usr/bin/py-hello-world

Then add this service file into /usr/share/dbus-1/services/ on the target.

Finally, add the Python script py-hello-world into /usr/bin/ on the target.

Now, restart the Moblin desktop and you will find the icon associated with py-hello-world.


Figure 3-1: A screenshot of Moblin desktop. You can see the Hello World desktop icon, "Hello World", on the bottom row.


Adding a GtkMenu
A Hildon-based application uses a standard GtkMenu widget to create its menu. You can add the menu to HildonProgram as a common menu which will appear in all the HildonWindow registered to this HildonProgram.

We will continue working with our py-hello-world.py sample. To create the menu, open the file and add the method _add_menu into the HildonHelloWorld class. The scripts are:
def _add_menu(self):
    menu = gtk.Menu()
    mnuItmQuit = gtk.MenuItem("Quit")
    mnuItmQuit.connect("activate", gtk.main_quit)
    menu.add(mnuItmQuit)

    self.set_common_menu(menu)

In the _add_menu method, we first create a GtkMenu widget, and add the Quit menu item. We need to connect the Quit item to the quit signal and add this menu item to the menu. We will add the menu to HildonHelloWorld as a common menu.

Then call this method in the __init__ method:
self._add_menu()

Adding a GtkToolbar
The Hildon-based application uses a standard GtkToolbar widget to create its toolbar. You can add the toolbar to the HildonProgram as a common toolbar which will appear in all the HildonWindow registered to this HildonProgram.

We will continue working with our py-hello-world.py sample. To create the toolbar, open the file and add the _add_toolbar method into the HildonHelloWorld class. The scripts are:
def _add_toolbar(self):
    toolbar = gtk.Toolbar()
    tlbItmQuit = gtk.ToolButton(gtk.STOCK_QUIT)
    tlbItmQuit.connect("clicked", gtk.main_quit)
    toolbar.insert(tlbItmQuit, -1)

    self.set_common_toolbar(toolbar)
    toolbar.show_all()

In the _add_toolbar method, we created a GtkToolbar widget and the "Quit" toolbar item. Now we need to connect the quit signal to the "Quit" item and add this toolbar item to the toolbar. Then we need to add the toolbar to HildonHelloWorld, as a common toolbar and display the GtkToolbar.

Then call this method in the __init__ method:
self._add_toolbar()

From the Moblin desktop, click the Hello World icon to run our application. This is a screenshot of the Python application. Notice that the application has a menu at the top with a "Quit" button and a toolbar at the bottom.


Figure 3-2: Python application.


Adding D-Bus to our Hello World
In the last step, we will add a D-Bus class to our Hello World application and create a D-Bus service file.

Exporting DBus Object
Moblin uses D-Bus as the primary interprocess communication mechanism for applications. More detailed information on D-Bus can be found at the document D-Bus Programming. Here we describe how to initialize a D-Bus object in Python. One symptom of missing this initialization is that the application will start from the task navigator, but will close automatically after a while.

Create a DBusObject class derived from the dbus.service.Object class, which is a base class for exporting your own Objects across D-Bus. With the DBusObject class, the Python application is able to connect to the D-Bus session message bus, export methods, do the remote procedure call, etc. You can refer to the dbus.service help doc within Python for more detailed information.

We will continue working with our py-hello-world.py sample. To create the D-Bus object class, open the file and add the this class to the script:
import dbus, dbus.service, dbus.glib

class DBusObject(dbus.service.Object):
    def __init__(self, app):
        self.app = app
        self.name = 'org.moblin.pyhelloworld'
        self.path = '/org/moblin/pyhelloworld'
        bus_name = dbus.service.BusName(self.name, bus = dbus.SessionBus())
        dbus.service.Object.__init__(self, bus_name, self.path)

In the __init__ method of DBusObject, we need to export the service across the bus:
bus_name = dbus.service.BusName(self.name, bus = dbus.SessionBus())

Then we need to export the D-Bus object on the bus connection created above:
dbus.service.Object.__init__(self, bus_name, self.path)

Note: The application D-Bus name "org.moblin.pyhelloworld" should be consistent with the service file name.

Then create a DBusObject object in the __init__ method of HildonHelloWorld:
self.dbus_obj = DBusObject(self)

If you restart the Hello World Python application, registering it to the D-Bus will make sure that the task navigator will not kill it.


Python Binding Libraries
Besides standard modules, there are many Python bindings you can leverage to make your programs, such as Python GStreamer*, Python Gtk, Python D-Bus, and Python Banshee-Helix. If you want to see if there are Python bindings for an existing project, you can go to the web site for the project and check if there is a Python sub-project inside.


Reference Documents
The following documents were used as references in the writing of this document. Refer to these documents for further details.

  1. Python Tutorial - http://docs.python.org/tut
  2. Documents for Python -  http://docs.python.org/
  3. GTK+ for Python - http://pygtk.org/
  4. Using Python in Maemo - http://pymaemo.garage.maemo.org/documentation/pymaemo_tutorial/python_maemo_howto.html