This document is released under the FDL license. 2004 The GNOME Project

arturogf@ugr.es

Arturo González Ferrer Universidad de Granada, arturogf@ugr.es

lgs@sicem.biz

Lorenzo Gil Sánchez Universidad de Granada, lgs@sicem.biz 0.5 07 February 2004 0.4 23 January 2004 (added "change-orient" event to callbacks section) arturogf 0.3 20 January 2004 (merge 0.2 with the new version. Some updates on bonobo and .server files. Autotools installation). arturogf 0.2 15 January 2004 (some grammar and structure corrections) lgs 0.1 07 January 2004 (first release) arturogf First release of this document. Next versions will include some improvements in all areas. This article will cover how to make an applet for the GNOME 2.x desktop with the Python programming language. Usually, GNOME applets are made in C, which has the big advantage of generating compiled executables (this means less memory footprint and faster programs) but in the other hand it's more difficult to do it and it takes more time to write the code. Python programs are developed faster, they have fewer lines of code, and it's an object oriented programming language. But it's an interpreted language, so the execution speed can be worse. It's up to the reader to decide if it is worthy writing a GNOME applet in Python. One good aproach is to prototype the applet in Python and then write the final version in C. Here we'll explain the necessary steps to write and deploy a simple applet from scratch using Glade 2 and libglade for the dialogs. Look at the bibliography for an in-deep explanation. Another good source of information is the pyGTK mailing list archives. However, with regard to the code shown at the tutorial, we advise you to better look at the example section, where you will find some releases that do like it has been explained here, so you can see it growing from a prototype to a really functional applet. GNOME 2.x applets need at least two files to get them working: The executable (in this case the applet code) The bonobo server component, that must be placed at /usr/lib/bonobo/servers by default. This file contains all the information about the resources the applet will use for its execution. The simplest applet we can write can be found in the gnome-python package documentation (/usr/share/doc/python2.x-gnome2/examples/applet/applet.py in DEBIAN-based distributions) or simply in the gnome-python tarball from the original GNOME ftp. place this at /usr/bin/pysample.py "hello", "0", sample_factory) First, we need to import some Python modules that we will need. The pyGTK module, needed to specify the GTK version used (we'll be using 2.x in this article), the gnome module, that contains all the useful classes and methods about the gnome desktop, i.e. the applet class, and the gtk module, Python bindings for the GTK toolkit. Then, we define the sample factory function to generate applet objects, with a text label "Sucess!". This function receives the object to be initializated (the applet) and the bonobo activation ID that the new factory will implement. It's all that simple. It returns gtk.TRUE if no errors were reported (see the panelapplet reference manual for details). When we call to gnome.applet.bonobo_factory(). When we call the bonobo_factory method, we need to pass it the following arguments: iid: The bonobo-activation iid of the factory. type : the type of the created object. description. version. factory callback: the name of the factory method. The second thing we need to get the applet running is to construct the bonobo server file. bonobo-activation-server, the GNOME application that tracks information about installed components and brokers components, reads and mantains the component descriptions from /usr/lib/bonobo/servers/*.server. These files provide an XML description of a component's capabilities which can be queried and manipulated by clients using the activation client library. Bonobo-activation-server, also ensures that the minimum neccessary number of servers for your display setup are running. Bonobo activation server is nothing but a daemon implementing a set of CORBA interfaces. These CORBA interfaces implement a name service for the set of CORBA servers installed on your system. GNOME Object Activation Framework daemon (OAFD) knows about all the CORBA servers in your system, running or not. The OAF daemon will activate those servers if you ask for them. Each server is described by its .server file which contains among other things the IDL interfaces it implements, some specific properties and an IID (Implementation ID). Each IID has to be globally unique, and its format is pretty simple: OAFIID:program_name:UUID The bonobo factories are CORBA objects that allow the creation of other new CORBA objects. This is a common practice in GNOME. The use of factories will allow us to use only an executable to get several instances of the component. So we need to define the .server file and place it at the location mentioned before: ]]> The .server file registers two unique OAF identifiers, and give the activation-server the description of how the objects must be created. The first one is the Factory, that is created when the .py script is executed. The second is the applet itself, and is created asking the Factory how to do it. When we do the "add to panel" action in GNOME, it takes the OAF identifiers that are supposed to implement the "IDL:GNOME/Vertigo/PanelAppletShell:1.0" in its "repo_ids" attribute. The submenu is determined by the "panel:category" attribute, the icon from "panel:icon", the text displayed at the menu comes from "name" and the tooltip text from "description". The sample_factory() function is called when a new applet is created. It receives a container that should be populated with the applet contents. A common issue when developping an applet is the debug process which means knowing what it's failing and why. As an applet is nothing but a GTK+ application we can use an additional command line argument like "run-in-window" to put it in window-mode by creating a GTK+ window and inserting the applet in it. if len(sys.argv) == 2 and sys.argv[1] == "run-in-window": main_window = gtk.Window(gtk.WINDOW_TOPLEVEL) main_window.set_title("Python Applet") main_window.connect("destroy", gtk.mainquit) app = gnome.applet.Applet() sample_factory(app, None) app.reparent(main_window) main_window.show_all() gtk.main() sys.exit() We can see how the applet object use the gtk.Widget reparent() method to change its parent to the GTK+ Window "main_window". Now that we know the basic steps to create and run the applet, we're going to structure the code in a simple way. We'll create a sample class, that will contain all the applet code. The new sample_applet_factory will call the class constructor: def sample_applet_factory(applet, iid): Sample(applet,iid) return gtk.TRUE The sample class will have the following skeleton, that we'll explain soon: [import section] class Sample: [class methods] [callbacks methods] ..... [optional timeout callback method] [create popup menu with the applet options] [ __init__ method [some instance variable definitions] [signals handlers definitions] [widget definitions] [optionally reading glade.XML] [signal_autoconnect to handlers] ] The first line of our python script will be the import section. Here we must include all the python modules we will need for our applet to run: import sys import pygtk pygtk.require('2.0') import gtk import gtk.glade import gnome.applet import gnome.ui import os.path import re import gobject import sample_globals as pglobals As we can see, we need some GTK and GNOME modules, the gobject module (only if we subclass the applet from it) and the sample_globals, that is used in order to have a easy installation with autotools. The file sample_globals.py is maked when executing the configure script, and it contains the following in my gnome installation: name = "sample" version = "0.2" image_dir = "/usr/share/pixmaps" glade_dir = "/usr/share/" + name We can use this information to call to gnome.init() or glade.XML() methods and the ones that use images or icons as parameters, such as the about_box or the applet itself WITHOUT using absolute paths. We're going to see these points in a natural order when coding it. Please look at the final example section to see a functional applet i'm doing for check the cpu throttling states on the new centrino processors and speedstep. Visit the cpudyn utility for more info. self.timeout_interval = 1000 self.throttling_states = 0 self.active_t_state = "T0" self.bus_activity = "" self.actual_cpu_state = "C1" self.lack_t_acpi = 0 self.lack_p_acpi = 0 self.dict = {} self.tooltip_text = "" self.checks = [0,0,0,0,0] Here are the different variables that sample objects will use to keep itself updated. First of all, we need to initializate the gnome applet with call to gnome.init(). Once this has been done, we can begin to pack the different widgets our applet will be compound of. and connect some callbacks to events in the common way, not the glade.XML one (see section 4.5.1) # initializate the gnome internals gnome.init("sample", "1.0") self.applet = applet self.tooltips = gtk.Tooltips() self.hbox = gtk.HBox() applet.add(self.hbox) # add the second button event for the popup menu and the enter mouse event to change the tooltip value self.ev_box = gtk.EventBox() self.ev_box.connect("button-press-event",self.button_press) self.ev_box.connect("enter-notify-event", self.update_info) self.hbox.add(self.ev_box) self.prog = gtk.ProgressBar() self.ev_box.add(self.prog) This an example of a simple applet with a gtk.ProgressBar in a hbox, that mantain a gtk.Tooltip to show some info. A common task when programming a gnome applet is to check if something has changed at the system level from time to time. This is resolved with gtk.timeout_add() method with a timeout_interval in milliseconds defined at the class variables section. gtk.timeout_add(self.timeout_interval,self.timeout_callback, self) It's important to do this in order to avoid memory leaks when killing the applet process incorrectly. applet.connect("destroy",self.cleanup) applet.show_all() When connecting events to handlers we know there are at least two options with GTK programming: with or without glade user interface designer. In this example we will look at both possibilities. We'll use glade for the applet preferences window, as we just used the direct way of doing it with the connect() method before in the "GTK widgets" section. It's quite simple to read a glade interface from pyGTK. All we need to do is to call to the gtk.glade.XML() method with the .glade file as parameter. After this, we'll define some variables for every widget we are going to use or modify, with gtk.get_widget('widget name') method. Finally, we must define the callbacks methods in the class definition. Calling signal_autoconnect() with the class instance as parameter, that in this case will be "self". So, we we'll have this at [callbacks methods] section: def on_properties_delete_event(self,widget,event): widget.hide() return gtk.TRUE def on_checkbutton1_toggled(self,widget): self.checks[0] = widget.get_active() print self.checks def on_checkbutton2_toggled(self,widget): self.checks[1] = widget.get_active() print self.checks def on_checkbutton3_toggled(self,widget): self.checks[2] = widget.get_active() print self.checks def on_checkbutton4_toggled(self,widget): self.checks[3] = widget.get_active() print self.checks def on_checkbutton5_toggled(self,widget): self.checks[4] = widget.get_active() print self.checks Those were our callback methods and now we'll see the connection of them to the glade interface: And the [reading glade XML optionally] section: wT = gtk.glade.XML("/path/to/file/glade/file.glade") # the way to do it with sample_globals defined will be something like: # wT = gtk.glade.XML(os.path.join(pglobals.glade_dir, "sample.glade")) #this is optional if you want to have some widget reference kept preferencesDialog = wT.get_widget('properties') self.preferences = preferencesDialog wT.signal_autoconnect(self) We can see that the on_properties_delete_event() handler is used to hide the properties window. It returns gtk.TRUE in order to avoid the destruction of the dialog so we can reuse it later. Remember that returning gtk.TRUE in an event handler stops the event propagation in GTK+. We show this dialog when the user clicks on the popup preferences option. This is the common way of connecting events to handlers, as seen at the "GTK widgets" section. It could be useful when packing some widgets dinamically. self.ev_box = gtk.EventBox() self.ev_box.connect("button-press-event",self.button_press) self.ev_box.connect("enter-notify-event", self.update_info) To finish our work we need to define the handlers for every event we have defined at the "GTK widgets" section or with the glade.XML method. For this task, the pyGTK reference manual (see bibliography) is a must see. We need to know the arguments of the handler method for every signal and every event we are catching. # callback for update the info on the applet periodically def update_info(self,widget,event): info = self.read_proc_info(); self.tooltips.set_tip(self.ev_box, info[0] + " " + info[1]); # callback to create the context menu with 'about' and 'preferences' def button_press(self,widget,event): if event.type == gtk.gdk.BUTTON_PRESS and event.button == 3: self.create_menu() def about_info(self,event,data=None): about = gnome.ui.About("CPU performance stats applet","0.1","GPL","Applet to check throttling and performance states",["Arturo Gonzalez"],["Arturo Gonzalez"],"Arturo Gonzalez",self.logo_pixbuf) about.show() def properties(self,event,data=None): self.preferences.show() This is the callback that should be used in case we need to update some info on the applet from time to time. The important here is the return value of the method. A return value of 0 implies that we want to stop checking the system for changes. If we want to go on checking, we must return a value of 1. def timeout_callback(self,event): self.read_proc_info() ##### here you should update the widgets contents. ##### ##### look at the code of the example section ##### ##### to see an approach to this task ##### return 1 # this function update the info extracted from /proc/acpi def read_proc_info(self): # cpu power in mhz if (os.path.isfile("/proc/cpuinfo")): f_proc = open("/proc/cpuinfo") for line in f_proc: try: line.index("cpu MHz") self.info[5] = line.strip().replace(" ","").split(":")[1] except ValueError: pass else: self.checks # throttling support if (os.path.isfile("/proc/acpi/processor/CPU0/throttling")): f_throt = open("/proc/acpi/processor/CPU0/throttling","r") cont = 1 for line in f_throt: if cont == 1: tmp = re.split('\W+',line) self.throttling_states = int(tmp[2]) else: # search for * and print self.info try: line.index("*") tmp = line.strip().replace(" ","").replace("*","").split(":") self.info[0] = tmp[0] self.info[1] = str(100 - int(tmp[1][:-1])) + "%" print self.info[1] #print self.info break except ValueError: pass cont = cont + 1 f_throt.close() else: self.info[0] = "" self.info[1] = "" # power support if (os.path.isfile("/proc/acpi/processor/CPU0/power")): f_per = open("/proc/acpi/processor/CPU0/power","r") cont = 1 for line in f_per: if cont == 1: tmp = re.split('\W+',line) self.active_cpu_state = tmp[2][1] else: try: line.index("*") self.info[2] = line.strip().replace(" ","").replace("*","").split(":")[0] #print self.info break except ValueError: pass cont = cont + 1 f_per.close() else: self.info[2] = "" # 2.6 sys filesystem if (os.path.isfile("/sys/devices/system/cpu/cpu0/cpufreq/scaling_available_governors")): f_sys = open("/sys/devices/system/cpu/cpu0/cpufreq/scaling_available_governors") for line in f_sys: self.governors = re.split(" ", line) f_sys.close() else: self.governors = "" if (os.path.isfile("/sys/devices/system/cpu/cpu0/cpufreq/scaling_governor")): f_sys = open("/sys/devices/system/cpu/cpu0/cpufreq/scaling_governor") for line in f_sys: self.info[3] = line.strip() f_sys.close() else: self.info[3] = "" if (os.path.isfile("/sys/devices/system/cpu/cpu0/cpufreq/scaling_driver")): f_sys = open("/sys/devices/system/cpu/cpu0/cpufreq/scaling_driver") for line in f_sys: self.info[4] = line.strip() f_sys.close() else: self.info[4] = "" These methods above are from the pycentrino applet 0.3 release, because they are much clearer that in previous versions. We have two main methods: The first one, timeout_callback() is the method called every second, as defined when calling gtk.timeout_add() in the __init__ method. The second one is a function to read from the /proc and/or /sys filesystems and update the content of the instance variable info. Finally, we'll have something like ["T0","0%","C1","powersave","centrino","1400.0"] in the variable. Usually, your applet will be set up on an horizontal panel, but there are cases where you can be interested in placing it on a vertical one. So we need to take this into account when coding the __init__ method, and we also need to hook a callback to the "change-orient" signal, which is triggered when you move the applet from an horizontal panel to a vertical one (or vicerversa) or when you change your panel position, modifying its orientation. The code for this callback: def change_orientation(self,arg1,data): self.orientation = self.applet.get_orient() # first remove the children of the current box for i in range(len(self.numbers)): self.box.remove(self.numbers[i]) # now remove the box itself self.big_evbox.remove(self.box) # time to create the new box if self.orientation == gnome.applet.ORIENT_UP or self.orientation == gnome.applet.ORIENT_DOWN: self.box = gtk.HBox() else: self.box = gtk.VBox() # and now fill it with the numbers for i in range(len(self.numbers)): self.box.pack_start(self.numbers[i]) # final steps self.big_evbox.add(self.box) self.box.show() It's important to realize that deleting all objects inside the HBox or VBox before moving them to the new VBox or HBox is totally necessary. Finally, we only need to show the box. Ok, we have our shiny brand new applet running and we are pretty proud of ourselves. Now it's time to learn how to distribute it so the world can be proud too. You may think 'hey, this is Python code, no compilation it's needed, we can just send them the .py files and the applet will work'. Well, it won't because all the paths are absolute to our own machine configuration, icons are needed and .glade files and .server files as well, so we need to distribute them somehow. In UNIX world, this task is commonly done with the ./configure --prefix=PATH --other-options command, but it's not so common to know the process of having all the correct files working. I did this task with version 1.7 of automake and aclocal and autoconf 2.58, because some Python macros weren't in 1.4 version. This section is based on some documents on the net (look at bibliography) and my own experience. There is a really good document from German Po in Spanish here so If you can read this language it's your lucky day. So, besides giving the user the facility to install our applet, the nice feature of doing the configure process, is that we can refer to our application files relative to a prefix previously defined. Each time we make a pyGTK applet we need to have some files in our project. This is an example of what our project directory should contain: |-- AUTHORS |-- COPYING -> /usr/share/automake-1.7/COPYING |-- ChangeLog |-- INSTALL -> /usr/share/automake-1.7/INSTALL |-- Makefile |-- Makefile.am |-- Makefile.in |-- NEWS |-- README |-- aclocal.m4 |-- config.log |-- config.status |-- configure |-- configure.in |-- images | |-- Makefile | |-- Makefile.am | |-- Makefile.in | |-- bug-buddy.png | |-- centrino.gif | |-- centrino.jpg | |-- green_led_0.gif | |-- green_led_1.gif | |-- green_led_2.gif | |-- green_led_3.gif | |-- green_led_4.gif | |-- green_led_5.gif | |-- green_led_6.gif | |-- green_led_7.gif | |-- green_led_8.gif | `-- green_led_9.gif |-- install-sh -> /usr/share/automake-1.7/install-sh |-- missing -> /usr/share/automake-1.7/missing |-- mkinstalldirs -> /usr/share/automake-1.7/mkinstalldirs |-- py-compile -> /usr/share/automake-1.7/py-compile |-- servers | |-- GNOME_SampleApplet.server | |-- Makefile | |-- Makefile.am | `-- Makefile.in `-- src |-- Makefile |-- Makefile.am |-- Makefile.in |-- sample.glade |-- sample.gladep |-- sample.py |-- sample.pyc |-- sample_globals.py |-- sample_globals.py.in |-- sample_globals.pyc It contains the names of who have been working on the application. It specifies the copy and distribution permissions of the application. It's a good idea allowing automake command generate this file, if you want it GPL. It keep all the changes made to the source and the application itself. It contains instalation instructions for our application. automake provides us with a generic file, but you should personalize for your application. It's a file with recent changes of the application. It contains a general description of the package, and it's possible to include some aditional instructions. This directories will contain the images and icons for our application, the bonobo .server files and the source code and glade files. It contains the verification and construction rules of the project. It is the base for creating the configure script. The rules are written in m4 language. It's the file that automake command will use to generate the Makefile file, needed to construct the application. It must exists a Makefile.am file for every directory in our project. aclocal.m4 will be used by autoconf to search for automake macros. It is generated by aclocal-1.7 command. sample_globals.py.in in the src/ directory, will contain references to @PREFIX@ and @VERSION@ variables, to define others variables, like image_dir, glade_dir, etc...at the final final, without the .in extension When creating these files commented in the previous section, we need to put them on this order: Place a NEWS and AUTHORS file at the root directory. Makefile.am will search for them. The Makefile.am in every directory, the project root directory included. The Makefile.am at the root directory will contain only the subdirs that we need to explore looking for others .am files. The configure.in at the root directory. The aclocal.m4, that we'll obtain by running aclocal-1.7 command at the root directory. Running the command automake-1.7 --add-missing at the root directory will create some files more we'll need: COPYING, INSTALL and some links to other utilities, install.sh, mkinstalldirs, py-compile... It will create also the Makefile.in, that next command, autoconf will need. Running autoconf at the root directory we will have the final configure script. We can have some .in files at the src directory, that could be use to generate them without the .in at 'configure' runtime, like a sample_globals.py.in that contains some variables like version, programname, or image_dir that will be used in execution time by the applet to find the files it needs. So we need to edit these files to get things working. If we look at step 2, we need some Makefile.am files. The one at the root directory will contain this: SUBDIRS = src images servers It's what we need to explore this directories for others Makefile.am files in order to generate Makefiles files correctly. The file at the src/ directory contains: bin_SCRIPTS = sample.py sampledir = $(prefix)/bin sample_PYTHON = \ sample_globals.py uidir = $(datadir)/sample ui_DATA = sample.glade DISTCLEANFILES = \ $(ui_DATA) \ $(bin_SCRIPTS) EXTRA_DIST = \ $(bin_SCRIPTS) \ $(sample_PYTHON) \ $(ui_DATA) These are the variables needed to our simple applet. Look at the gnome-blog source code (bibliography) if you want to do anything out of the scope of this tutorial, like adding gconf support or gettext. Now we must edit the configure.in file at the root directory. It use m4 macros to check the software our application will need. This is the code for our simple applet. However, look at gnome-blog or some others GNU applications to have an idea of how to do it more complicated, or the m4 manual at bibliography section: AC_INIT(src/sample.py) AM_INIT_AUTOMAKE(sample, 0.2) AM_MAINTAINER_MODE dnl check for python -- 'dnl' is used for comments AM_PATH_PYTHON PKG_CHECK_MODULES(PYGTK, pygtk-2.0) AC_SUBST(PYGTK_CFLAGS) AC_SUBST(PYGTK_LIBS) AC_OUTPUT([ Makefile src/Makefile src/sample_globals.py images/Makefile servers/Makefile ]) We have some macros to check the .py and init the automake process, and the check if we have the python interpreter and python modules installed correctly. You can download an example applet i'm doing for checking acpi throttling states in new centrino and speedsteps processors. The 0.1 release is almost done like the steps shown in this article. 0.2 release has a better project structure and some improvements at the presentation and code. 0.3 release manage how to update the image icons that mantains the info from filesystem. Future releases will improve the presentation and will take some other factors into account, as it is totally alpha software now. PyGTK tutorial (spanish translation) Lorenzo Gil Sánchez PyGTK 2.0 Reference Manual John Finlay Mark McLoughlin PanelApplet Reference Manual Bonobo Activation API Reference manual 2.0 Mathieu Lacage Seth Nickell Gnome-blog applet Bonobo tutorial for python Martin Grimme German Poó Caamaño Entendiendo autoconf y automake. René Seindal The GNU m4 manual. A powerful macro processor.