Editing PyMaemo/HildonDesktop

Warning: You are not logged in. Your IP address will be recorded in this page's edit history.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.

Learn more about Contributing to the wiki.

== Python bindings for libhildondesktop ==

These bindings allow to create the so called Hildon Home 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 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 (Fremantle only) ===

The code below was based on the C example that can be found on the maemo-examples package sources [https://garage.maemo.org/svn/maemoexamples/branches/fremantle-sdk-testing/maemo-examples/hello-world-home.c].

<pre>
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()
</pre>

=== Testing the example ===

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

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

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:

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

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

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

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:

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

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

[[Image:Hello_world_home_python1.png]]

After clicking on the widget button, you should see:

[[Image:Hello_world_home_python2.png]]

Please note that all contributions to maemo.org wiki may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see maemo.org wiki:Copyrights for details). Do not submit copyrighted work without permission!

Summary:

Cancel | Editing help (opens in new window)

Retrieved from "http://wiki.maemo.org/PyMaemo/HildonDesktop"

Personal tools

Navigation

Views

Editing PyMaemo/HildonDesktop

@@ Line 1: / Line 1: @@
-= Python bindings for libhildondesktop =
+== 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:
+These bindings allow to create the so called Hildon Home 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.
-== Migrating old Widgets to Maemo 5 ==
+=== API changes for Fremantle ===
-The libhildondesktop version in Maemo 5 contains some API changes that also reflect on the Python bindings. Namely, you should pay attention to the following differences when migrating Home/Status Widgets from older Maemo releases to 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.
-* Similarly, 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.
-* The older "hd_plugin_get_objects" function must be removed. Instead, a "hd_plugin_type" variable should contain the main class for the plugin (which will be used internally by the loader to instantiate the 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.
-Additionally, if your code used to work with python-hildondesktop on versions until 0.3.0, you must make the following changes for it to work with the latest version:
+<b>NOTE:</b> this last requirement might change in future, to avoid the mentioned crash.
-* Remove the "__gtype_name__" attribute from the main plugin class. It was used to register a GType for the class, but it caused some problems. Now the GType is registered on the loader.
+=== Example (Fremantle only) ===
-* Remove the "hd_plugin_get_object" function and instead add a "hd_plugin_type" variable that points to the plugin main class.
-== Example - Home widgets (Fremantle only) ==
+The code below was based on the C example that can be found on the maemo-examples package sources [https://garage.maemo.org/svn/maemoexamples/branches/fremantle-sdk-testing/maemo-examples/hello-world-home.c].
 <pre>
+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):
@@ Line 39: / Line 53: @@
 class HelloHomePlugin(hildondesktop.HomePluginItem):
+    __gtype_name__ = 'HelloHomePlugin'
      def __init__(self):
          hildondesktop.HomePluginItem.__init__(self)
-         button = gtk.Button("Hello")
+         button = HelloWorldButton(10)
          button.connect("clicked", hello_world_dialog_show)
          button.show_all()
          self.add(button)
-hd_plugin_type = HelloHomePlugin
+def hd_plugin_get_object():
+    return gobject.new(HelloHomePlugin, plugin_id="hello_world_home")
-# The code below is just for testing purposes.
-# It allows to run the widget as a standalone process.
 if __name__ == "__main__":
-    import gobject
+     obj = hd_plugin_get_object()
-    gobject.type_register(hd_plugin_type)
-     obj = gobject.new(hd_plugin_type, plugin_id="plugin_id")
      obj.show_all()
      gtk.main()
@@ Line 66: / Line 79: @@
 </pre>
-Save the example code shown above as /usr/lib/hildon-desktop/hello_world_home.py inside your FREMANTLE_X86 target. <b>Make sure the script has a valid Python module name, specially it should not have any dots or dashes on its name</b>. To be safe, use only alphanumeric characters and underscore, plus the ".py" extension.
+Save the example code shown above as <b>/usr/lib/hildon-desktop/hello_world_home.py</b> inside your FREMANTLE_X86 target. Next, save the following text as <b>/usr/share/applications/hildon-home/hello_world_home.desktop</b>:
-Next, save the following text as /usr/share/applications/hildon-home/hello_world_home.desktop:
 <pre>
@@ Line 78: / Line 89: @@
 </pre>
-Now start the SDK UI, if it is not already started. See the instructions on the [[Documentation/Maemo_5_Final_SDK_Installation#Starting.2FShutting_down_the_SDK_UI|Maemo 5 SDK documentation page]]
+Make sure the hildon desktop and hildon-home are running. For that, you can use the following commands:
-Now you need to add the newly installed home widget to the desktop. Follow these instructions to add it using the Hildon Desktop interface:
+<pre>
+export DISPLAY=:2 # if you are using scratchbox + Xephyr
+af-sb-init.sh start
+run-standalone.sh maemo-summoner /usr/bin/hildon-home.launch &
+</pre>
+Now you need to add the newly installed home widget to the desktop. For that you can either manually add it to the <b>~/.config/hildon-desktop/home.plugins</b> file, or follow these instructions to add it using the Hildon Desktop interface:
 # Click anywhere on the Maemo desktop background.
@@ Line 96: / Line 113: @@
 [[Image:Hello_world_home_python2.png]]
-== 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 [http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Application_Development/Writing_Desktop_Widgets#Status_Menu_widgets].
-<pre>
-import gtk
-import hildondesktop
-class ExampleStatusPlugin(hildondesktop.StatusMenuItem):
-    def __init__(self):
-        hildondesktop.StatusMenuItem.__init__(self)
-        icon_theme = gtk.icon_theme_get_default()
-        pixbuf = icon_theme.load_icon("general_email", 22, gtk.ICON_LOOKUP_NO_SVG)
-        self.set_status_area_icon(pixbuf)
-        label = gtk.Label("Example message")
-        self.add(label)
-        self.show_all()
-hd_plugin_type = ExampleStatusPlugin
-</pre>
-=== Testing the example ===
-First, install the same packages needed for Home widgets, then save the example above as as <b>/usr/lib/hildon-desktop/hello_world_status_menu.py</b> inside your FREMANTLE_X86 target. Next, save the following text as <b>/usr/share/applications/hildon-status-menu/hello_world_status_menu.desktop</b>:
-<pre>
-[Desktop Entry]
-Name=Hello, World! (Python)
-Comment=Example Status Menu Python plugin
-Type=python
-X-Path=hello_world_status_menu.py
-</pre>
-Now start the SDK UI, if it is not already started. See the instructions on the [[Documentation/Maemo_5_Final_SDK_Installation#Starting.2FShutting_down_the_SDK_UI|Maemo 5 SDK documentation page]]
-The example status menu widget should appear as soon as the .desktop file is saved, as the plugin used in this example is of the permanent category. See the [[Documentation/Maemo_5_Developer_Guide/Application_Development/Writing_Desktop_Widgets#Status_Menu_widgets|Maemo 5 Developer Guide]] for more information of status menu widgets categories.
-This is a screenshot taken on Xephyr showing how the widget will look like:
-[[Image:Status-menu-1.png]]
-When clicked, it will show the specified message, enclosed in a gtk.Label:
-[[Image:Status-menu-2.png]]
-== Debugging tips ==
-If a Python widget breaks for some reason, no error message will appear to the user. To debug the problem (in Scratchbox), you need to look at debug messages sent on the console where the UI was started.
-Debug messages for Home Widgets are shown by default. For Status Menu Widgets, you need to enable debug output by running these commands:
-<pre>
-[sbox]> pkill -f /usr/bin/hildon-status-menu
-[sbox]> DEBUG_OUTPUT=1 /usr/bin/hildon-status-menu &
-</pre>
-They will terminate the running hildon-status-menu process and start a new one with debug output enabled.
-To force reloading a plugin (so that you can get the error messages again), try moving the .desktop file out of the directory and adding it back, e.g.:
-<pre>
-[sbox]> mv /usr/share/applications/hildon-status-menu/hello_world_status_menu.desktop /tmp/
-[sbox]> mv /tmp/hello_world_status_menu.desktop /usr/share/applications/hildon-status-menu/
-</pre>
-This method may not work reliably for hildon-home widgets because the old code may not be fully unloaded. A solution is to reload hildon-home using [http://maemo.org/downloads/product/Maemo5/actman/ Desktop Activity Manager]. Once you store the current desktop (e.g. with "activty new test; activity store test") you can re-load it using "activity load -f test". This will reload hildon-home and all its widgets.
-Another way of debugging python widgets is to add this code at the beginning of the script:
-<source lang="python">
-import sys
-f=open('/tmp/mylog.log', 'at', buffering=1)
-sys.stdout=f
-sys.stderr=f
-</source>
-This will redirect stdout and stderr to <code>/tmp/mylog.log</code>. This means that all exceptions and all other output will be logged there. As a plus, the code can be given to testers and they will be able to report-back with the contents of the logfile.
-However, '''do not''' use this by default in production systems. Use it '''only''' for debugging since the file will consume space in <code>/tmp</code> and will only grow in size.
-[[Category:Python]]