PyGObject GTK+ 3 - Documentation?

Question

PyGObject appears to have no real documentation. This tutorial is as close as it gets. I've been struggling all morning simply trying to find a description of the arguments accepted by the Gtk.Window constructor. It seems I can't do much reflection in Python because everything in PyGObject is dynamically generated.

All I want is to know what arguments I can pass to this constructor! There doesn't appear to be an equivalent of this object in the GTK+ 3 documentation, and reading the source code to figure out the bindings has proven to be an extremely daunting task. Any ideas??

Answer 1

I agree that this is a huge shortcoming of the PyGObject in it's current state. For those of us who have been using GTK+ for a while it's no problem, but, for new users it can be confusing.

Folks are working on a system to automatically generate the docs for languages other than C which is known as GObject Introspection Doctools. Since that's not quite ready yet, your best bet to use the C API documentation and learn how it translates to Python. It's not as hard as it sounds.

Remember, the Python calls are dynamically wrapped to the underlying C library. All you need to do is learn how a few things are typically translated to Python and understand how GTK+ "properties" work. It's basically a naming convention in C and the patterns are easy to learn. The PyGObject/Introspection Porting page is a good start.

A constructor in Python is generally wrapped to the *_new() function in C. PyGObject also allows you to pass in any GTK+ property belonging to that widget as keyword arguments in the constructor. Thus, you have a lot of options when constructing widgets in Python.

You had mentioned the GtkWindow. If you look at the GtkWindow Documentation, the gtk_window_new() function takes a window type as an argument in C. This would be a positional argument to the constructor in Python. PyGObject "overrides" the constructor so that the type is optional and defaults to a top-level window. There are a bunch of GtkWindow properties that could also be passed to the constructor as keyword arguments.

Here are 3 examples of constructing a Gtk.Window in Python which are functionally equivelent:

# this is very close to how it's done in C using get_*/set_* accessors. window = Gtk.Window(Gtk.WindowType.TOPLEVEL) window.set_title("Hello")  # setting properties as keyword arguments to the constructor window = Gtk.Window(type=Gtk.WindowType.TOPLEVEL, title="Hello")  # set_properties() can be used to set properties after construction window = Gtk.Window() window.set_properties(title="Hello") 

The Python interactive console can be a great way to experiment with widgets and properties.