Editing PyMaemo/Using Python in Maemo

text=This document is outdated and will not work for [[Open development/Maemo roadmap/Fremantle|Maemo 5 (fremantle)]]}}

The <code>import</code> command will import <code>.pyo</code> files even if the interpreted is called without the <code>-O</code> or <code>-OO</code> option. This is a difference from the standard Python behavior.

Follow the instructions on http://pymaemo.garage.maemo.org/installation.html.

<source lang="python">

#!/usr/bin/env python2.5

import gtk

window = gtk.Window(gtk.WINDOW_TOPLEVEL)

 

 

</source>

 

 

[[Image:hello_world_1_small.jpg|frame|center|alt=Screenshot of "Hello World!" application|Figure 1: Plain PyGTK "Hello World!" application]]

The reason for using the <code>run-standalone.sh</code> command to execute the application is that it adds the Hildon theming. Figure 2 illustrates how the application looks if run without the <code>run-standalone.sh</code> command:

[[Image:hello_world_1_no_theme_small.jpg|frame|center|alt=Screenshot of unthemed application|Figure 2: Application without the Hildon theme]]

text=The <code>run-standalone.sh</code> command is only available if you run applications from the Scratchbox console.}}

The <code>HildonWindow</code> class overloads the <code>GtkWindow</code> class, providing the Hildon theme (look and feel) for top level windows. In order to use the facilities provided by the Hildon framework (and to integrate cleanly in it), the application must use a <code>HildonWindow</code> instead of a <code>GtkWindow</code>. With a <code>HildonWindow</code> class the application has, for example, access to Hildon menus and toolbars.

The required code change is simple: replace the <code>GtkWindow</code> with <code>HildonWindow</code> and import the <code>hildon</code> module. The following example illustrates the required changes (also downloadable [http://pymaemo.garage.maemo.org/documentation/pymaemo_tutorial/examples/hello_world_1.py here]):

<source lang="python">

#!/usr/bin/env python2.5

 

 

 

 

Note how the borders are now drawn in the right way, since the program is using the <code>HildonWindow</code> class.

The <code>HildonProgram</code> 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, <code>HildonProgram</code> also manages other program-wide issues, such as hibernating.

 

 

 

 

 

  def run(self):

    self.window.show_all()

    gtk.main()

app = HelloWorldApp()

app.run()

</source>

# Download the source package [gpodder-0.8.0.tar.gz here] or directly from the project's page, <code>http://gpodder.berlios.de/</code>.

# Extract the <code>gpodder-0.8.0.tar.gz</code> file. The <code>gpodder-0.8.0</code> directory will be created.

# In the <code>gpodder-0.8.0</code> directory, use the Scratchbox console to run the following commands: <code>python2.5 setup.py install</code> and <code>run-standalone.sh gpodder</code>

[[Image:gpodder_1_small.jpg|frame|center|alt=Screenshot of gPodder running on Maemo without any modifications|Figure 4: gPodder running on Maemo without any modifications]]

Most of the code changes are made in the <code>gpodder-0.8.0/src/gpodder/gpodder.py</code> file. It contains the following classes:

class Gpodder(SimpleGladeApp)

class Gpodderchannel(SimpleGladeApp)

class Gpodderproperties(SimpleGladeApp)

class Gpodderepisode(SimpleGladeApp)

class Gpoddersync(SimpleGladeApp)

class Gpodderopmllister(SimpleGladeApp)

Open the <code>gpodder-0.8.0/data/gpodder.glade</code> file using the ''[http://glade.gnome.org/ Glade User Interface Designer]'' (another option is ''[http://gazpacho.sicem.biz/ Gazpacho]''). You can see that there is one class for each <code>GtkWindow</code> defined in it, as shown in Figure 5:

[[Image:gpodder_glade_1.png|frame|center|alt=Screenshot of Glade showing a list of windows defined in gPodder's glade file|Figure 5: Windows defined in gPodder's glade file]]

In addition to loading the window description from <code>gpodder.glade</code>, the <code>SimpleGladeApp</code> class also makes all window elements directly accessible from <code>self</code>, ignoring the element's hierarchy. Figure 6 illustrates part of the element's hierarchy for the gPodder window, and how to access the elements from inside a <code>Gpodder</code> method.

[[Image:gpodder_glade_2.png|frame|center|alt=Screenshot of widget tree for the gPodder window|Figure 6: Widget tree for the gPodder window]]

The first code change in the porting exercise is to make gPodder use <code>HildonProgram</code> and <code>HildonWindow</code> classes instead of the <code>GtkWindow</code> class.

Start by modifying the <code>gpodder.py</code> file (in the <code>gpodder-0.8.0/src/gpodder</code> directory). Since you want to use Hildon elements, you have to import its module. The following example illustrates the import, with ''++'' indicating new lines:

61 |from libipodsync import gPodder_iPodSync

62 |from libipodsync import ipod_supported

63 |

++ |import hildon

++ |

64 |# for isDebugging:

65 |import libgpodder

Second, add a <code>HildonProgram</code> (<code>self.app</code>) and a <code>HildonWindow</code> (<code>self.window</code>). The following example illustrates the added objects:

115 |        if libgpodder.isDebugging():

116 |            print "A new %s has been created" % self.__class__.__name__

117 |

++ |        self.app = hildon.Program()

++ |

++ |        self.window = hildon.Window()

++ |        self.window.set_title(self.gPodder.get_title())

++ |        self.app.add_window(self.window)

++ |

++ |        self.vMain.reparent(self.window)

++ |        self.gPodder.destroy()

++ |

++ |        self.window.show_all()

++ |

118 |        #self.gPodder.set_title( self.gPodder.get_title())

119 |        #self.statusLabel.set_text( "Welcome to gPodder! Suggestions? Mail to: thp@perli.net")

120 |        # set up the rendering of the comboAvailable combobox

The <code>gPodder</code> class (<code>self</code>) has its <code>close_gpodder</code> method connected to the <code>destroy</code> signal from the original <code>gPodder</code> Gtk window. This means that you have to remove the connection from <code>gPodder</code> and put it in the new <code>Hildonwindow</code> (<code>self.window</code>).

To remove the signal connection from the original <code>gPodder</code> Gtk window, open the <code>gpodder.glade</code> file (in the <code>gpodder-0.8.0/data</code> directory) and remove the connection, as shown in Figure 7.

[[Image:gpodder_glade_3.png|frame|center|alt=destroy signal for gPodder window|Figure 7: destroy signal for gPodder window]]

The following example illustrates how you connect <code>Gpodder.close_gpodder</code> to the new <code>HildonProgram</code> (<code>self.app</code>):

119 |

120 |        self.window = hildon.Window()

121 |        self.window.set_title(self.gPodder.get_title())

++ |        self.window.connect("destroy", self.close_gpodder)

122 |        self.app.add_window(self.window)

123 |

124 |        self.vMain.reparent(self.window)

The change from <code>GtkWindow</code> to <code>HildonProgram</code>/<code>HildonWindow</code> is now complete. Figure 8 illustrates the results if you run gPodder again.

text=Don't forget to run <code>python2.5 setup.py install</code> before lauching gPodder again, otherwise you will still be using the old, unmodified, version.}}

[[Image:gpodder_2_small.jpg|frame|border|center|middle|alt=Screenshot of gPodder using HildonProgram and HildonWindow|Figure 8: gPodder using <code>HildonProgram</code> and <code>HildonWindow</code>]]

This section describes how you make gPodder use Hildon's title area as its menu bar, instead of using its own GTK+ menu (a <code>GtkMenuBar</code> object).

In the <code>gpodder.glade</code> file, you can see that the <code>gPodder</code> window has a menu bar (a <code>GtkMenuBar</code> object) called <code>mainMenu</code>. You must move all its children (<code>menuPodcasts</code>, <code>menuChannels</code> and <code>menuHelp</code>) to the <code>HildonWindow</code>'s menu and then destroy the empty <code>mainMenu</code> menu.

To achieve this, add the following lines to the <code>gpodder.py</code> file:

125 |        self.vMain.reparent(self.window)

126 |        self.gPodder.destroy()

127 |

++ |        menu = gtk.Menu()

++ |        for child in self.mainMenu.get_children():

++ |            child.reparent(menu)

++ |        self.window.set_menu(menu)

++ |

++ |        self.mainMenu.destroy()

++ |

128 |        self.window.show_all()

129 |

130 |        #self.gPodder.set_title( self.gPodder.get_title())

[[Image:gpodder_3_small.jpg|frame|center|alt=Screenshot of gPodder using HildonWindow's menu bar|Figure 9: gPodder using HildonWindow's menu bar]]

Hildon has a set of widgets for common operations, such as a color selection dialog, file chooser dialog and a time picker. Most of them provide the same functionality (or extension) as the existing GTK+ widgets. For example, <code>HildonFileChooserDialog</code> has the same purpose as <code>GtkFileChooserDialog</code>.

[[Image:gpodder_4_small.jpg|frame|center|alt=Screenshot of gPodder using GTK's file chooser dialog|Figure 10: gPodder using GTK's file chooser dialog]]

Make it use a <code>HildonFileChooserDialog</code> instead. The following example illustrates the code changes needed in <code>gpodder-0.8.0/src/gpodder/gpodder.py</code>:

579    |        if len( self.channels) == 0:

580    |          self.showMessage( _("Your channel list is empty. Nothing to export."))

581    |          return

582 -- |        dlg = gtk.FileChooserDialog( title=_("Export to OPML"), parent = None,[...]

583 -- |        dlg.add_button( gtk.STOCK_CANCEL, gtk.RESPONSE_CANCEL)

584 -- |        dlg.add_button( gtk.STOCK_SAVE, gtk.RESPONSE_OK)

    ++ |        dlg = hildon.FileChooserDialog(self.window, gtk.FILE_CHOOSER_ACTION_SAVE);

585    |        response = dlg.run()

586    |        if response == gtk.RESPONSE_OK:

587    |            foutname = dlg.get_filename()

Figure 11 illustrates the results when you select ''Menu > Channels > Export List'':

[[Image:gpodder_5_small.jpg|frame|center|alt=Screenshot of gPodder using Hildon's file chooser dialog|Figure 11: gPodder using Hildon's file chooser dialog]]

* Main window (<code>gPodder</code>) Make the tab names shorter. Replace “''Downloaded Podcasts''” with “''Downloaded''” and “''Available Podcasts''” with “''Podcasts''” to make the tab names stay within screen boundaries. Figure 12 shows the tab names before (left) and after (right) that change.

[[Image:gpodder_6_small.jpg|frame|center|alt=Screenshot of gPodder with shortened tab names|Figure 12: gPodder with shortened tab names]]

To make gPodder respond correctly when the user presses the <var>Full screen</var> hardware key you have to make the following changes to <code>gpodder-0.8.0/src/gpodder/gpodder.py</code>:

120 |        self.window = hildon.Window()

121 |        self.window.set_title(self.gPodder.get_title())

122 |        self.window.connect("destroy", self.close_gpodder)

++ |        self.window.connect("key-press-event", self.on_key_press)

++ |        self.window.connect("window-state-event", self.on_window_state_change)

++ |        self.window_in_fullscreen = False #The window isn't in full screen mode initially.

123 |        self.app.add_window(self.window)

124 |

125 |        self.vMain.reparent(self.window)

575 |            self.showMessage( _("Could not delete channel.\nProbably no channel is selected."))

576 |    #-- Gpodder.on_itemRemoveChannel_activate }

577 |

++ |    def on_window_state_change(self, widget, event, *args):

++ |        if event.new_window_state & gtk.gdk.WINDOW_STATE_FULLSCREEN:

++ |            self.window_in_fullscreen = True

++ |        else:

++ |            self.window_in_fullscreen = False

++ |

578 |    #-- Gpodder.on_itemExportChannels_activate {

579 |    def on_itemExportChannels_activate(self, widget, *args):

580 |        if libgpodder.isDebugging():

581 |        else:

582 |            self.window_in_fullscreen = False

583 |

++ |    def on_key_press(self, widget, event, *args):

++ |        if event.keyval == gtk.keysyms.F6:

++ |            # The "Full screen" hardware key has been pressed

++ |            if self.window_in_fullscreen:

++ |                self.window.unfullscreen ()

++ |            else:

++ |                self.window.fullscreen ()

++ |

584 |    #-- Gpodder.on_itemExportChannels_activate {

585 |    def on_itemExportChannels_activate(self, widget, *args):

586 |        if libgpodder.isDebugging():

text=The ''Full screen'' hardware key maps to the F6 key on the SDK.}}

[[Image:gpodder_7_small.jpg|frame|center|alt=Screenshot of gPodder in full screen mode|Figure 13: gPodder in full screen mode]]

This section describes how remote procedure calls are implemented using LibOSSO. The example is divided in two different sample applications: <code>osso_test_sender.py</code> and <code>osso_test_receiver.py</code>.

Create a <code>osso_test_sender.py</code> file with the following content (or download it [http://pymaemo.garage.maemo.org/documentation/pymaemo_tutorial/examples/osso_test_sender.py here]).

 

 

osso_c = osso.Context("osso_test_sender", "0.0.1", False)

window = hildon.Window()

window.connect("destroy", gtk.main_quit)

send_button = gtk.Button("Send RPC")

window.add(send_button)

send_button.connect("clicked", send_rpc, osso_c)

window.show_all()

gtk.main()

</source>

Create a <var>osso_test_receiver.py</var> file with the following content (or download it [http://pymaemo.garage.maemo.org/documentation/pymaemo_tutorial/examples/osso_test_receiver.py here]). '''Don't forget to set this file as executable, otherwise D-Bus will not be able to start it. You can do this using: <code>chmod +x osso_test_receiver.py</code>'''

<source lang="python">

#!/usr/bin/python2.5

import osso

import gtk

    osso_sysnote = osso.SystemNote(osso_c)

    osso_sysnote.system_note_infoprint("osso_test_receiver: Received an RPC to %s." % method)

osso_rpc = osso.Rpc(osso_c)

osso_rpc.set_rpc_callback("spam.eggs.osso_test_receiver",

    "/spam/eggs/osso_test_receiver",

    "spam.eggs.osso_test_receiver", callback_func, osso_c)

The receiver also must register itself as a D-Bus service. Create a <code>osso_test_receiver.service</code> file with the following content.

 

 

Add the <code>osso_test_receiver.service</code> file to <code>/usr/share/dbus-1/services</code>.

First make sure that D-Bus recognises the new D-Bus service ( <code>spam.eggs.osso_test_receiver</code>). To do this, restart your Maemo environment (which, in turn, will restart D-Bus) by using the following command on the Scratchbox console:

Then run <code>osso_test_sender.py</code> with the following command (assuming that it is in your home directory):

Figure 14 illustrates what now happens every time you click the ''Send RPC'' button.

[[Image:libosso_tutorial_small.jpg|frame|center|alt=Screenshot of LibOSSO sample application|Figure 14: LibOSSO sample application]]

This section describes the process of creating a Maemo package by showing how to package a simple "hello world" style application. Create a <code>hello-pymaemo</code> file (without the "<code>.py</code>" suffix) with the following content.

<source lang="python">

#!/usr/bin/env python2.5

 

 

 

 

Make the file executable by running the <code>chmod +x hello-pymaemo</code> command. This ensures that you can run the script in the same way as a regular binary application.

 

You must have an icon for the application. The icon is shown in the menu entry and in the task navigator bar. The icon must be a 26×26 pixels PNG image with a transparent background, such as the [http://www.maemo.org/platform/docs/python-bora/images/pymaemo_bora/hello_icon_26x26.png  example icon] shown in Figure 15:

[[Image:hello_icon_26x26.jpg|frame|center|alt=Hello PyMaemo icon|Figure 15: Hello PyMaemo icon]]

Name the icon <code>hello_icon_26x26.png</code>.

The menu entry is a <code>.desktop</code> file with the following content for the application:

[Desktop Entry]

Version=1.0.0

Encoding=UTF-8

Name=Hello PyMaemo!

Exec=/usr/bin/hello-pymaemo

Icon=hello_icon_26x26

Type=Application

text=Be very careful when writing a desktop file, since the system is very sensitive to typographical errors and misplaced whitespaces in it. A faulty desktop file will simply fail to show its menu entry without yielding any errors.}}

{| class="wikitable"

|+ Table 1. <code>.desktop</code> file fields

| <code>Version</code>

| <code>Encoding</code>

|Character encoding. Must always be <code>UTF8</code>.

| <code>Name</code>

| <code>Exec</code>

| <code>Icon</code>

| Application's icon. Only the name of the file '''without''' its suffix (<code>.png</code>).

| <code>Type</code>

| "<code>Application</code>"since it is an entry for an application

Use Python Distribution Utilities ("Distutils") to copy the files to their proper locations. Create a <code>setup.py</code> file with the following content.

from distutils.core import setup

setup(name='hello-pymaemo',

      version='1.0.0',

</source>

In the Scratchbox console, issue the <code>python2.5 setup.py install</code> command to achieve the following result:

 

After you have run the command, the application is actually installed in your system (in Scratchbox, you have to run <code>af-sb-init.sh restart</code> before calling your application from the menu). You can access it from the ''Extras'' menu.

 

When creating a Debian package, the first step is to put all files (the hello-pymaemo script, and the png, desktop and service files) in an empty directory called <code>hello-pymaemo-1.0.0</code>. The directory name must follow the <code><package-name>-<app-version></code> convention. This means that the package you are creating for the hello world application is called <code>hello-pymaemo</code>.

As Debian packages use makefiles (<code>Makefile</code>) instead of Python Distutils (<code>setup.py</code>), you have to write a <code>Makefile</code> to act as an interface between the Debian package system and the <code>setup.py</code>. The file is very simple; it merely issues commands to <code>setup.py</code> according to make's target. If you have no knowledge of make files, see Chapters 1 and 2 in ''GNU Make Manual''<ref name="make">[http://www.gnu.org/software/make/manual GNU Make Manual]</ref>.

all:

python2.5 setup.py build

clean:

python2.5 setup.py clean --all

install:

python2.5 setup.py install --root $(DESTDIR)

In Scratchbox console (inside the <code>hello-pymaemo-1.0.0</code> directory), enter the following command:

Type of package: single binary, multiple binary, library, or kernel module?  [s/m/l/k] s

Maintainer name : unknown

Email-Address  : your.email@somewhere.com

Date            : Thu, 18 May 2006 13:58:04 -0300

Package Name    : hello-pymaemo

Version        : 1.0.0

Type of Package : Single

Hit <enter> to confirm:

Done. Please edit the files in the debian/ subdirectory now.

You should also check that the hello-pymaemo Makefiles install into $DESTDIR and not in / .

Choose "single binary" as package type. In case the "<code>--root $(DESTDIR)</code>" part of the makefile is not clear to you, the last sentece in the output is meant to clarify the situation.

The <code>dh_make</code> command creates a <code>debian</code> subdirectory containing multiple configuration text files, most of which are templates that can be removed, since the application does not use them. In addition, the command makes a copy of the original directory, calling it <code>hello-pymaemo-1.0.0.orig</code>.

Table 2 lists the files needed in <code>hello-pymaemo-1.0.0/debian</code> (others can be removed):

{| class="wikitable"

|+ Table 2. Required files for the example application package

! File in <code>./debian</code>

| <code>changelog</code>

| <code>compat</code>

| <code>control</code>

| <code>copyright</code>

| <code>rules</code>

The key files in <code>./debian</code> are <code>control</code> and <code>rules</code>. They contain a generic template showing what they must look like. In <code>control</code>, you must simply fill in the blanks and, in <code>rules</code>, you essentially need to remove unwanted and unnecessary code.

The following example illustrates what the <code>control</code> file for the example application must contain:

Source: hello-pymaemo

Section: user/other

Priority: optional

Maintainer: My Name <your.email@somewhere.com>

Build-Depends: debhelper (>= 4.0.0), python2.5-dev

Standards-Version: 3.6.0

Package: hello-pymaemo

Depends: python2.5, python2.5-hildon, python2.5-gtk2

Description: A simple "Hello Python for Maemo!"

A very simple application consisting of a single button, containing the

text "Hello Python for Maemo!".

</pre>

The <code>XB-Maemo-Icon-26</code> field contains the application icon file (in this case, <code>hello_icon_26x26.png</code>) encoded in base64. This is the icon that is shown in the Application Installer, next to the package name. To do this encoding in Linux, you can use either <code>uuencode</code> or <code>openssl</code> (there can be more suitable applications). Maemos's Scratchbox rootstrap is delivered with <code>uuencode</code>. Do not forget to put a white space at the beginning of each line containing the icon-encoded text. The white space serves as indentation. The same rule stands for the long package description (<code> A very simple application[...]</code>).

The Application Installer only shows packages in the <code>user</code> section. Thus, your <code>Section:</code> field in the <code>control</code> file must have the <code>Section: user/<SUBSECTION></code> syntax, where <code><SUBSECTION></code> is arbitrary.

The following example illustrates the <code>rules</code> file for the example application:

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

The main point is that the <code>binary-arch</code> target was emptied and the <code>binary-indep</code> filled, since the application being 100% Python means that it is 100% architecture-independent.

The system displays some output, including a couple of warnings near the end of it (about <code>XB-Maemo-Icon-26</code.) but that is normal. The parent directory now has a <code>hello-pymaemo_1.0.0-1_all.deb</code> file - your Debian package. This is the file that is distributed to Maemo devices and installed using the Application Installer.

[[Image:packaging_1_small.jpg|frame|center|alt=Screenshot of the "Hello World!" properly installed|Figure 14: The "Hello World!" properly installed]]