PyGObject GTK+ 3 - Documentation?
gobject, gtk, gtk3, pygobject, python
Solution
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.
Problem
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??