Python on dev@iostream.pl

2026-06-28

Sun, 28 Jun 2026 16:08:00 +0200

Listbox, anyone?

Many popular UI toolkits have their listbox control implemented to be as simple in use as possible. The most common operations are: creating the control, adding the data rows, deleting and editing data, handling the selection. Almost all toolkits provide single functions or suitable methods to realize above operations.

Gtk+ is quite different: it requires more abstract way of thinking and additional objects to be created, but the lists and trees are more flexible and elegant.

Storing the data

Before we can display a single string, let’s first earn a PhD in data models.

Unlike the the other toolkits, the gtk+ list allows to display a few values per a row. Gtk+ list also distinguishes between the types of data, while other lists treat its row data as a single string.

In fact, the TreeView widget will be used to display elements. The model lets the display widget know about data types to be used in the control, it also determines the type of the control (if it should be a list or a tree). Besides, the model is used to store all the data (it is common to find a “store” term instead of “model” in various papers or in someone’s code)

A store/model can be created by calling a proper constructor with at least one data type (to be used in the list) as argument:

store = Gtk.ListStore(type1, ...)

Example:

store = Gtk.ListStore(int, str, str)

Created store will contain one integer value and two strings per row. Although pygtk reference recommends to use build-in GObject types (for instance, gobject.TYPE_INT and gobject.TYPE_STRING instead of int and str respectively), python built-in types are also allowed (GObject names really matter in C or C++)

Adding the data rows

The method append from Gtk.ListStore class allows to append one row at the end of the store. Sequence with all values should be passed as a parameter:

store.append([val1, ...])

Example:

store.append([7, "str1", "str2"])

Columns and renderers

Control widget should know about columns it should display, their order and how to present data from the store. Gtk+ provides the column widget (Gtk.TreeViewColumn) to manage displaying the cells of data and renderer widgets (Gtk.CellRenderer and its derivatives) to realize rendering of particular cells.

Column widget is usually created by calling a constructor of Gtk.TreeViewColumn with a header title passed as the argument:

column = Gtk.TreeViewColumn(title)

Example:

column = Gtk.TreeViewColumn("Column header")

Column header is visible by default — passing an empty string to the constructor will not get rid of it.

Cell renderer should be one of Gtk.CellRendererAccel, Gtk.CellRendererCombo, Gtk.CellRendererPixbuf, Gtk.CellRendererProgress, Gtk.CellRendererSpin, Gtk.CellRendererText, Gtk.CellRendererToggle. The renderer object is usually created by calling the constructor with no parameters

Example:

renderer = Gtk.CellRendererText()

Renderers should be added to the column widgets: pack_start and pack_end methods are used to do the packing.

column.pack_start(renderer)

column.pack_end(renderer)

Example:

column1 = Gtk.TreeViewColumn("Column1")
renderer1 = Gtk.CellRendererText()
renderer2 = Gtk.CellRendererText()
renderer3 = Gtk.CellRendererText()
column1.pack_start(renderer1)
column1.pack_start(renderer2)
column1.pack_end(renderer3)

The column widget must know which data column from the model should be connected to any of these renderers. This could be done by calling set_attributes method:

column.set_attributes(renderer, ...)

All optional parameters are “key = value” pairs, where key is the data type and value is number of column in the store

Example:

column1.set_attributes(renderer1, text = 2)
column1.set_attributes(renderer2, text = 0)
column1.set_attributes(renderer3, text = 1)

TreeView control

The last step is to create a control and add all columns. Constructor of the control takes the store as first parameter:

listControl = Gtk.TreeView(model=store)

The method append_column adds given column to the tree/list control:

listControl.append_column(column)

Summary: at least, four objects should be created to have the tree/list control working: a model which determines types of data and stores all the rows, a renderer, which takes care of displaying the cells, a column, which glues together model columns and suitable renderers and a treeview control itself.

Working examples

Following examples illustrate the creation and displaying of the lists.

Very simple list control

The simplest list control contains only one column and displays only one value per row

#!/usr/bin/env python3
 
import gi

gi.require_version("Gtk", "3.0")
from gi.repository import Gtk
 
class ListBoxViewer1:
 def destroyCallback(self, widget, data=None):
 Gtk.main_quit()
 
 def __init__(self):
 self.listStore = Gtk.ListStore(str)
 self.listStore.append(["String 1"])
 self.listStore.append(["String 2"])
 self.listStore.append(["String 3"])
 self.listStore.append(["String 4"])
 self.listStore.append(["String 5"])
 self.listColumn = Gtk.TreeViewColumn("Sample column")
 self.textRenderer = Gtk.CellRendererText()
 self.listColumn.pack_start(self.textRenderer, True)
 self.listColumn.set_attributes(self.textRenderer, text = 0)
 self.mainWindow = Gtk.Window(type=Gtk.WindowType.TOPLEVEL)
 self.mainWindow.set_title('ListBoxViewer1');
 self.listBox = Gtk.TreeView(model=self.listStore)
 self.listBox.append_column(self.listColumn)
 self.mainWindow.add(self.listBox)
 self.mainWindow.connect('delete_event', self.destroyCallback)
 self.mainWindow.show_all()

if __name__ == "__main__":
 lbv1 = ListBoxViewer1()
 Gtk.main()

This example covers the theory of creating listboxes with additional routines necessary to run minimal gtk+ program. Additional method is added to provide termination of this example when its window has been closed.

All list-related routines are explained below:

self.listStore = Gtk.ListStore(str)
self.listStore.append(["String 1"])
self.listStore.append(["String 2"])
self.listStore.append(["String 3"])
self.listStore.append(["String 4"])
self.listStore.append(["String 5"])

The model is created: it can hold one string value per a row. Then it is populated by 5 rows.

self.textRenderer = Gtk.CellRendererText()

Text renderer is created.

self.listColumn = Gtk.TreeViewColumn("Sample column")
self.listColumn.pack_start(self.textRenderer, True)
self.listColumn.set_attributes(self.textRenderer, text = 0)

A column is created. Then the renderer is packed into the column, and the column is informed which column and what type of data from the store will be used.

self.listBox = Gtk.TreeView(self.listStore)
self.listBox.append_column(self.listColumn)

Main widget is created. The column is appended to the list.

It looks like the following:

Explanation of the next examples contains only the routines related to list control; other routines did not change if not mentioned.

Two values per row

 self.listStore = Gtk.ListStore(str, int)
 self.listStore.append(["String 1", 18000])
 self.listStore.append(["String 2", 1500])
 self.listStore.append(["String 3", 900])
 self.listStore.append(["String 4", 60])
 self.listStore.append(["String 5", 3])

Now the store holds a string an integer pair per a row.

self.listColumn = Gtk.TreeViewColumn("Sample column")
self.textRenderer = Gtk.CellRendererText()
self.numRenderer = Gtk.CellRendererText()
self.numRenderer.set_property('xalign', 1.0)

A column and two cell renderers are created. The set_property routine with xalign property to be set tells the renderer to align right the values in the row. Value of 0.0 means left alignment, 0.5 centers the text and 1.0 means right alignment.

self.listColumn.pack_start(self.textRenderer, True)
self.listColumn.pack_start(self.numRenderer, False)
self.listColumn.set_attributes(self.textRenderer, text = 0)
self.listColumn.set_attributes(self.numRenderer, text = 1)

The two renderers are packed into the column. The string value renderer will expand the cell if possible. Proper renderers are assigned to proper data columns from the store.

self.listBox = Gtk.TreeView(store=self.listStore)
self.listBox.append_column(self.listColumn)

The control is created and the column is appended to the control.

The following picture shows the result of this example:

Two columns in the control

self.listColumn1 = Gtk.TreeViewColumn("Ascii text")
self.listColumn2 = Gtk.TreeViewColumn("Numeric value")
self.textRenderer = Gtk.CellRendererText()
self.numRenderer = Gtk.CellRendererText()
self.numRenderer.set_property('xalign', 1.0)
self.listColumn1.pack_start(self.textRenderer, True)
self.listColumn2.pack_start(self.numRenderer, False)
self.listColumn1.set_attributes(self.textRenderer, text = 0)
self.listColumn2.set_attributes(self.numRenderer, text = 1)

Every column packs one of the renderes. It looks like the following:

Adding pixmaps to the list

Now, creating the store is like below:

self.sheetIcon = Gtk.gdk.pixbuf_new_from_file("sheet.xpm");
self.listStore = Gtk.ListStore(str, int, Gtk.gdk.Pixbuf)
self.listStore.append(["String 1", 18000, self.sheetIcon])
self.listStore.append(["String 2", 1500, self.sheetIcon])
self.listStore.append(["String 3", 900, self.sheetIcon])
self.listStore.append(["String 4", 60, self.sheetIcon])
self.listStore.append(["String 5", 3, self.sheetIcon])

The pixbuf is added in every row. Of course, it may be different in every row. This is only the example.

self.iconRenderer = Gtk.CellRendererPixbuf()

The icon requires a special kind of cell renderer.

self.listColumn1.pack_start(self.iconRenderer, False)
self.listColumn1.set_attributes(self.iconRenderer, pixbuf = 2)

Pixbuf cell renderer is now packed into the first column together with the text renderer.

It looks like the following:

Display the same values twice or more times

Displaying more values per row is achieved by multiplicating the renderes:

self.listColumn1 = Gtk.TreeViewColumn("Ascii text")
self.listColumn2 = Gtk.TreeViewColumn("Numeric value")
self.textRenderer = Gtk.CellRendererText()
self.textRenderer2 = Gtk.CellRendererText()
self.numRenderer = Gtk.CellRendererText()
self.numRenderer2 = Gtk.CellRendererText()
self.numRenderer3 = Gtk.CellRendererText()
self.iconRenderer = Gtk.CellRendererPixbuf()
self.iconRenderer2 = Gtk.CellRendererPixbuf()
self.numRenderer.set_property('xalign', 1.0)
self.numRenderer2.set_property('xalign', 0.0)
self.numRenderer2.set_property('xalign', 0.5)
self.textRenderer2.set_property('xalign', 1.0)
self.listColumn1.pack_start(self.iconRenderer, False)
self.listColumn1.pack_start(self.textRenderer, True)
self.listColumn2.pack_start(self.numRenderer, False)
self.listColumn2.pack_start(self.numRenderer2, False)
self.listColumn2.pack_start(self.iconRenderer2, False)
self.listColumn2.pack_start(self.numRenderer3, False)
self.listColumn2.pack_start(self.textRenderer2, True)
self.listColumn1.set_attributes(self.iconRenderer, pixbuf = 2)
self.listColumn1.set_attributes(self.textRenderer, text = 0)
self.listColumn2.set_attributes(self.numRenderer, text = 1)
self.listColumn2.set_attributes(self.numRenderer2, text = 1)
self.listColumn2.set_attributes(self.numRenderer3, text = 1)
self.listColumn2.set_attributes(self.textRenderer2, text = 0)
self.listColumn2.set_attributes(self.iconRenderer2, pixbuf = 2)

Also, the left, right and center alignment of text is shown.

It looks like the following:

2026-06-22

Mon, 22 Jun 2026 20:05:00 +0200

The original version of this article was written in 2006.

Back then:

Python 2 was still alive,

distutils existed,

XEmacs was technically not dead,

and people still owned VHS tapes.

Let’s see how much of this still works in 2026.

Modules, Lies, and VHS Tapes

Sometimes you need to write Python bindings for a strange third-party library. It happens.

Sometimes you need to write the library itself. That happens too.

And sometimes you have to do all of that on Windows using GNU tools.

This article serves both as a professional tutorial and as a public service announcement suggesting that you abandon everything and move to a remote mountain cabin. Mostly because I can never remember the correct order of the steps involved.

Prerequisites on Windows

The easiest approach is to use MSYS2 and GCC.

You should have the following tools available somewhere in your PATH:

GCC
Python
dlltool

Nothing particularly exotic.

A Sample Library

Our example library is intentionally simple. It contains only two functions: one that adds two integers and one that multiplies them.

int mul2x(int x, int y)
{
 return x * y;
}

int add2x(int x, int y)
{
 return x + y;
}

Since the library is simple, let’s call it SimpLib.

Assume the source code is stored in a file called simplib.c.

Building the Library

As always, source files should first be compiled into object files.

To produce a shared library, GCC requires the -shared option.

Following Unix naming conventions, shared libraries usually have a lib prefix and a .so extension. Linking with -lname assumes the presence of a library named libname.so somewhere on the library search path. Many GNU projects ported to Windows continue to use this naming convention internally, even though the final artifact is a .dll.

Linux

gcc -o simplib.o -c simplib.c
gcc -o libsimp.so simplib.o -shared

Of course, for a single source file you could simply write:

gcc -o libsimp.so simplib.c -shared

However, once a project grows beyond a trivial example, compiling each source file separately and linking everything at the end is usually a much better idea.

Congratulations. The library has been built and is ready for use.

Cue triumphant fanfare.

Windows

Although we’re using exactly the same compiler, Windows requires one additional step.

We need to create an import library (sometimes called an interface library) that other applications can link against. This is where dlltool enters the picture.

Creating the Import Library

gcc -o simplib.o -c simplib.c
dlltool -l libsimp.lib simplib.o
gcc -o libsimp.dll simplib.o -shared

The DLL is now ready.

The import library is also ready.

Cue Windows-themed fanfare.

Header File

Providing a header file is generally considered a polite thing to do.

Other developers will appreciate not having to reverse-engineer your function declarations, and they will be less inclined to say unpleasant things about you.

#ifndef __SIMPLIB_H__
#define __SIMPLIB_H__

int mul2x(int x, int y);
int add2x(int x, int y);

#endif

Assume this file is called simplib.h.

A Sample C Program

The best way to test a library is to write a small program that uses it.

There are not many activities one can perform while fully clothed that are more enjoyable than programming, although surprisingly few people seem aware of this fact.

#include <stdio.h>
#include "simplib.h"

int main(int argc, char *argv[])
{
 printf("Adding 5 to 10: %d\n", add2x(5, 10));
 printf("Multiplying 5 by 10: %d\n", mul2x(5, 10));

 return 0;
}

Assume this program is stored as simprg.c.

Building the Sample Program

Linux

gcc -o simprg.o -c simprg.c
gcc -o simprg simprg.o -lsimp

Windows

Remember the import library:

gcc -o simprg.o -c simprg.c
gcc -o simprg simprg.o libsimp.lib -lsimp

A Brief Note About Flags

If the library is not located on the system library search path, remember to use the -L option.

Windows searches the current directory by default.

Linux does not.

For example:

gcc -o simprg simprg.o -L. -lsimp

Writing a Python Extension Module

Historical note

The code below targets Python 2.x and reflects the state of the CPython API around 2006. Modern Python 3 extension modules use a different initialization mechanism based on PyModuleDef and PyModule_Create.

The following code demonstrates Python bindings for SimpLib:

#include <Python.h>
#include "simplib.h"

static PyObject *simp_mul2x(PyObject *self, PyObject *args)
{
 int x, y, result;
 PyObject *pyresult;
 if (!PyArg_ParseTuple(args, "ii", &x;, &y;))
 {
 return NULL;
 }
 result = mul2x(x, y);
 pyresult = Py_BuildValue("i", result);
 return pyresult;
}

static PyObject *simp_add2x(PyObject *self, PyObject *args)
{
 int x, y, result;
 PyObject *pyresult;
 if (!PyArg_ParseTuple(args, "ii", &x;, &y;))
 {
 return NULL;
 }
 result = add2x(x, y);
 pyresult = Py_BuildValue("i", result);
 return pyresult;
}

static PyMethodDef SimpMethods[] = {
 {"mul2x", simp_mul2x, METH_VARARGS, "Multiply two integer values"},
 {"add2x", simp_add2x, METH_VARARGS, "Add two integer values"},
 {NULL, NULL, 0, NULL}
};
 
PyMODINIT_FUNC initsimp(void)
{
 (void) Py_InitModule("simp", SimpMethods);
}

Assume the file is called simpmodule.c.

What Is Happening Here?

Every extension module requires an initialization function.

Historically, for Python 2.x, this function was named init followed by the module name, hence:

initsimp()

The initialization function creates the module object itself.

Every function listed in the module’s method table becomes a method of that module.

In our case:

static PyMethodDef SimpMethods[]

contains:

the names visible from Python,
the addresses of the corresponding C functions,
additional flags describing how arguments are passed.

The METH_VARARGS flag indicates that Python will pass arguments as a tuple.

The binding functions themselves follow a simple pattern:

Validate input arguments.
Perform the actual computation.
Convert the result into a Python object.

Argument validation is handled by:

PyArg_ParseTuple(args, "ii", &x, &y)

The format string "ii" means:

I expect two arguments, and both of them must be integers.

If validation fails, the function should simply return NULL.

Building the return value is similarly straightforward:

Py_BuildValue("i", result);

which constructs a Python integer object.

The Python documentation traditionally recommends declaring all binding functions as static.

Building the Module

One way to build the extension is to use distutils.

Example setup.py

#!/usr/bin/env python3

from distutils.core import setup, Extension

simpmodule = Extension(
 'simp',
 sources=['simpmodule.c'],
 libraries=['simp'],
 library_dirs=['.']
)

setup(
 name='SimpLib',
 version='1.0',
 description='This is SimpLib bindings package',
 ext_modules=[simpmodule]
)

The Extension object describes:

source files,
required libraries,
library search paths.

The setup() function handles the rest.

Linux

python setup.py build

Windows

Unfortunately, Python traditionally expects Visual C++ when building extension modules.

If that doesn’t bother you, feel free to use it.

That would, however, make this article considerably shorter.

To force MinGW:

python setup.py build --compiler=mingw32

Installing the Module

Linux

python setup.py install

The extension and all required files will be installed into the appropriate Python directories.

Windows

The generated simp.pyd file should be copied into either:

Lib\site-packages

%APPDATA%\Roaming\Python\site-packages

Make sure you know which Python installation you’re targeting before copying files around.

If you happen to own Visual C++, and if the sight of it does not cause emotional distress, installation works exactly like it does on Linux.

A Short Test Program

Naturally, the best way to test the module is to use it.

from simp import *

print("Adding 212 to 384:", add2x(212, 384))
print("Multiplying 212 by 384:", mul2x(212, 384))

You should also verify that incorrect input is handled properly.

For example:

print(mul2x(212, "A tester walks into a bar"))

or:

print(mul2x(212, 384, 25))

Both cases should result in Python exceptions being raised by the argument validation code.

Final Thoughts

Keep your spirits up.

Rome wasn’t built in a day.

Neither are C libraries, Python bindings, build systems, or debugging skills.

Compilation errors, broken builds, failed tests, and nights spent chasing mysterious bugs are simply part of the profession.

The important thing is to remember that every experienced developer has been through exactly the same process.

Some of them are still going through it.