James Henstridge

james@daa.com.au

2000 James Henstridge GTK+ 2.0 is a versatile toolkit for creating graphical user interfaces, and is available for the X Window System, the Linux Framebuffer console and Microsoft Windows, among others. Unlike many other toolkits, GTK+ was designed so that it is fairly easy to write bindings to other languages. This document is designed to help language binding authors understand how to bind GTK+ 2.0 GTK+ 2.0 is an object oriented graphical toolkit. It's object model is based on top of the GObject library, which is part of glib. As the object system is implemented in C code, it is not constrained by what is provided by the language. One of the aims of the GObject system was to make it easy to use from a language binding. Some of the benefits are: Written in C. Most scripting languages are written in C, and have well defined interfaces for wrapping C code for use in the language. Many compiled languages also have the ability to call C functions as well, so this makes binding GTK easier Runtime introspection. The object model provides access to a lot of information about the type system at runtime. This is very useful for language bindings. more to come ... As you might expect, to write a good GTK language binding, a good understanding of GObject is necessary. There are a number of parts of GObject that you will need to look at: GType: the type registry. Every type used in GTK has (or should have) a type registered with the type system. From integers to enumerations to GObjects. This registry is used for runtime introspection at various parts of the binding. GValue: used for marshalling arbitrary data types to a function. A GValue is similar to a CORBA::Any (XXXX - is this true?). It consists of a GType typecode, and type specific data. The actual value can be read with type specific accessor functions. A language binding will probably need some code to marshal. GClosure: a data structure representing a function. It consists of a function and a marshaller that will marshal an array of GValues to a form that can be passed to the function. For a language binding, you will need to implement a new closure type and an appropriate marshaller that can call functions written in the scripting language. GClosures are used to implement signals for GObjects, and are used for various other callbacks in GTK+ (XXXX - at the moment, there aren't any other uses). GSignal: a notification mechanism. XXXX - put in description of signals here GObject: object and class system. These are the objects provided by the gobject library. A GObject class can be subclassed, can have a number of signals and may implement a number of interfaces. The programmer can store arbitrary data with a GObject instance, which can be accessed with a string key. All widgets in the GTK+ library are GObjects. From the point of view of a language binding author, understanding GObjects is vital to writing a good binding. GInterface: interfaces for GObjects. These are similar to C++ signatures (XXXX - well, that is what timj said). Each of these things will be explained in later sections. As a language binding author, mostly you will be querying the GType system for information, rather than registering new types. One exception would be creating new GObjects subclasses from the language the binding is for. Discussion of GObject subclassing will be covered in a later section. Another is if you wish to create an equivalent of the GTK+ 1.2 GTK_TYPE_FOREIGN type. GTK_TYPE_FOREIGN was removed in GTK 2.0, in favour of bindings registering their own type. You will probably want to use a boxed type for this purpose, as seen in the following example: static gpointer pyobject_copy(gpointer boxed) { PyObject *obj = (PyObject *)boxed; /* we use referencing as our copying semantics */ Py_INCREF(obj); return obj; } static void pyobject_free(gpointer boxed) { PyObject *obj = (PyObject *)boxed; Py_DECREF(obj); } ... /* in binding initialisation function */ g_boxed_type_register_static("PyObject", pyobject_copy, pyobject_free); A type such as this may be used in the definitions of new signals created for new GObjects created by your binding. For a language binding, you will need some way of converting between GValues and the native types in the language you are writing the binding for. You will probably need functions for converting to and from GValues. In pygtk, these are pyg_value_from_pyobject and pyg_value_as_pyobject: int pyg_value_from_pyobject GValue *value PyObject *obj PyObject * pyg_value_as_pyobject const GValue *value The first function pyg_value_from_pyobject takes a GValue that has had its type set and a PyObject which is the python object we wish to marshal into the value. If the PyObject has the wrong type, then an error is is returned. The second function pyg_value_as_pyobject takes a GValue, and returns the equivalent python object. In both of these functions, there is a big if statement calling the various G_VALUE_HOLDS_* macros to check the type of the value. In GTK 2.0, GClosures are used to represent callbacks supplied by the programmer. It will generally comprise a function of some kind and a marshaller used to call it. In the case of C programs, a closure usually just holds a pointer to a function and maybe a data argument. For a language binding, you will need to develop one or more closure types. When a GClosure is invoked, its marshal function will be called. As arguments, it will be passed a GValue that the return value should be written into, an array of GValues representing arguments to the function, a context dependent "invocation hint" and an extra data argument: void marshal GClosure *closure GValue *return_value guint n_param_values const GValue *param_values gpointer invocation_hint gpointer marshal_data Unlike in GTK 1.2, GClosures are extensible and can hold an arbitrary ammount of information, so you won't have to use tricks like passing a pointer to a structure as the user data for a callback. The most common closure type you will use is one that just wraps a function object from the language you are binding as a GClosure (for use as a signal handler, etc). In the case of interpreted languages, you will probably be able to write a generic closure marshal that will be able to construct arbitrary argument vector when invoking the closure. The closure marshal would most likely use the GVale -> native type routine written earlier to convert the param_values array into an argument vector suitable for calling the function wrapped by the closure. After calling the closure, the return value can then be converted back to a GValue and stored in return_value. It is trivial to create a new closure type. First of all you need to decide if you need to store more information in the closure than that provided by the GClosure structure. If so, define a structure to hold the extra data, with a GClosure as the first member. Something like this: typedef struct _MyClosure MyClosure; struct _MyClosure { GClosure closure; /* my extra data goes here */ }; Note that this structure does not need to be in any header files -- it is an implementation detail of your closure. Now to create a closure of this type, use the following statement: GClosure *closure; closure = g_closure_new_simple(sizeof(MyClosure), data); The second argument to g_closure_new_simple gets put in the data member of the GClosure structure. After creating the closure, you can set the extra data members in your custom closure any way you want. If those data members need to be finalised when the closure is freed, then you can add a finaliser to the closure: static void my_closure_finalize(gpointer notify_data, GClosure *closure) { MyClosure *myclosure = (MyClosure *)closure; /* free the extra data in myclosure */ } ... g_closure_add_finalize_notifier(closure, notify_data, my_closure_finalize); If you don't need to pass any extra data to the finaliser, notify_data can be NULL. You can associate a marshal function with the closure with the following command: g_closure_set_marshal(closure, my_closure_marshal); In the case where you don't need to store any extra data with the closure, you can simply pass the size of the GClosure structure to g_closure_new_simple and not add any finalize notifiers. For examples of some closure implementations, see the gobjectmodule.c file in recent pygtk snapshots. The new base class for the object system is now GObject (GtkObject is a subclass of GObject now). GObjects are one example of instantiable types in the GType type system. In practice, they are the only instantiable types you will use. It is important to make the wrapper for this type as good as possible -- it will be the most used wrapper in the binding. The better the GObject wrapper, the more natural the binding will feel. GObjects are reference counted, so your wrapper should hold a reference to the object, and release it when the wrapper is destroyed. Manipulation of the reference count is done with the following functions: gpointer g_object_ref gpointer object void g_object_unref gpointer object If you need to associate some data with a GObject, you can use the data APIs: gpointer g_object_get_data GObject *object const gchar *key void g_object_set_data GObject *object const gchar *key gpointer data void g_object_set_data_full GObject *object const gchar *key gpointer data GDestroyNotify destroy If you are writing a binding for an object oriented language, you will probably want to make a class heirachy of wrappers that correspond to the various GObject subclasses. The functions for each particular GObject type can be mapped to methods on the corresponding wrapper. At times, you may need to get the type of a particular GObject instance. This can be done with the G_OBJECT_TYPE macro, which effectively has the following prototype: GType G_OBJECT_TYPE gpointer object As well as creating the various GObject subclasses with their *_new constructors, there is also a generic constructor that can be used for any GObject type. It takes the GType of the object as the first argument, followed by (parameter name, value) pairs, and closed off with a NULL: gpointer g_object_new const gchar *first_property_name ... It's use might be something like this: GtkWidget *widget; widget = g_object_new(GTK_TYPE_WINDOW, "x", 42, "y", 20, "visible", TRUE, NULL); The use of g_object_new is the only way to set G_PARAM_CONSTRUCT_ONLY properties on an object. Unfortunately there doesn't seem to be a version of this function that doesn't use C varargs at the moment, which limits its usefulness to language bindings. In some cases, you may want to create new GObject subclasses from the language binding. For this, you will want to use the g_type_register_static function: GType g_type_register_static GType parent const gchar *type_name const GTypeInfo *info GTypeFlags flags The GTypeInfo structure passed has the following methods: typedef struct _GTypeInfo GTypeInfo; struct _GTypeInfo { /* interface types, classed types, instantiated types */ guint16 class_size; GBaseInitFunc base_init; GBaseFinalizeFunc base_finalize; /* classed types, instantiated types */ GClassInitFunc class_init; GClassFinalizeFunc class_finalize; gconstpointer class_data; /* instantiated types */ guint16 instance_size; guint16 n_preallocs; GInstanceInitFunc instance_init; /* value handling */ const GTypeValueTable *value_table; }; In most cases, you will just want to create a new GObject with the same size structure as the parent (or maybe with space for an additional pointer or two). The values to put in the class_size and instance_size members can be derived with the g_type_query function: void g_type_query GType type GTypeQuery *query Which returns its data in a GTypeQuery structure: typedef struct _GTypeQuery GTypeQuery; struct _GTypeQuery { GType type; const gchar *type_name; guint class_size; guint instance_size; }; The base_init and base_finalize members can be left NULL. The class_{init,finalize,data} members can be left NULL in most cases as well. For language bindings, it is probably easier to just initialise signals and properties after registering the type. What you use for the instance_init function depends on how new types will be instantiated. If the GObject will be created from a wrapper's constructor, then you probably don't want to do anything in the instance_init function, so can leave it as NULL. If you want the wrapper to be created from the GObject's constructor, then you can set instance_init to a function that will construct the wrapper for the object. The first case is what happens in the python bindings. Putting this all together, the code to derive a GType for a new subclass of GtkWidget might look something like this: GType typecode; GTypeInfo type_info = { 0, /* class_size */ (GBaseInitFunc) NULL, (GBaseFinalizeFunc) NULL, (GClassInitFunc) NULL, (GClassFinalizeFunc) NULL, NULL, /* class_data */ 0, /* instance_size */ 0, /* n_preallocs */ (GInstanceInitFunc) NULL }; GTypeQuery query; g_type_query(GTK_TYPE_WIDGET, &query); type_info.class_size = query.class_size; type_info.instance_size = query.instance_size; /* increase the size of the class or instance structs here if necessary */ typecode = g_type_register_static(GTK_TYPE_WIDGET, "NameOfNewWidget", &type_info, 0); It should now be possible to instantiate objects of the new type with g_object_new: GtkWidget *widget; widget = g_object_new(typecode, NULL); The replacement for GtkSignals in libgobject are GSignals. As with most things in this new library, GSignals are a lot more versatile than GtkSignals. Signals are a general purpose notification framework. A type may have one or more signals, each of which may have an argument list and return value. Handlers can then be connected to instances of the type. When the signal is emitted on an instance, each of the connected handlers will be called. Inside libgobject, signals are used for property change notification. In GTK+, signals are used for event notification and state change notification among other things. Unlike GTK+ 1.2, instead of directly connecting C functions as signal handlers, GClosures are used in glib 2.0 (there are convenience wrappers included for the benefit of C programmers). For a language binding, you will probably want to use either g_signal_connect_closure or g_signal_connect_closure_by_id: guint g_signal_connect_closure gpointer instance const gchar *detailed_signal GClosure *closure gboolean after guint g_signal_connect_closure_by_id gpointer instance guint signal_id GQuark detail GClosure *closure gboolean after Note that the only difference between the two functions is that g_signal_connect_closure converts its detailed_signal argument to signal_id and detail arguments using: gboolean g_signal_parse_name const gchar *detailed_signal GType itype guint *signal_id_p GQuark *detail_p gboolean force_detail_quark The detailed_signal or signal_id and detail arguments identify which signal to call on the instance. The closure argument says what function to call as a handler for the signal. The after argument says whether the handler should be called before or after the class closure of the signal (described in the next section). The closure will be passed all the arguments that should be passed to the function it wraps (unlike the GtkCallbackMarshal used in GTK+ 1.2, which didn't include the actual instance in the arg list). The invocation_hint argument passed to the closure's marshal function will be a pointer to a GSignalInvocationHint structure: typedef struct _GSignalInvocationHint GSignalInvocationHint; struct _GSignalInvocationHint { guint signal_id; GQuark detail; GSignalFlags run_type; }; For those who have used the GTK+ 1.2 signal system, the above functions would only seem to replace gtk_signal_connect and gtk_signal_connect_after -- not gtk_signal_connect_object and gtk_signal_connect_object_after. The behaviour of the second two functions is handled by the closure in the glib 2.0 model. To get the *_object behaviour, you will need to pass in a closure that swaps the first argument passed to the closure and the data argument. For example, there are two constructors for "C Closures" -- g_cclosure_new and g_cclosure_new_swap, which performs the argument swapping. If you want to provide the argument swapping behaviour in your language binding, your custom closure type must support it. To put it all together, the code to connect a function from the language you are binding to a signal of a particular object may look something like this pseudo C code: static guint connect_signal(ObjectWrapper *wrapper, const gchar *detailed_signal, Function *function, gboolean swap_data, gboolean after) { GObject *instance = get_object_from_wrapper(Wrapper); GClosure *closure = create_closure_for_function(function, swap_data); return g_signal_connect_closure(instance, detailed_signal, closure, after); } Once you have handlers connected to a signal, you need to wait for the signal to be emitted. For most of the signals in GTK+, the emission is handled by the library. In some cases though, you may want to emit signals from the language you are writing the binding for. In these cases, you will need a wrapper for g_signal_emitv: void g_signal_emitv const GValue *instance_and_params guint signal_id GQuark detail GValue *return_value The first argument to g_signal_emitv is the argument list for the signal emission. The first element in the array is a GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. The types of the arguments can be found with the g_signal_query function: void g_signal_query guint signal_id GSignalQuery *query This function will fill in a GSignalQuery structure passed in as the second argument. The structure has the following members: typedef struct _GSignalQuery GSignalQuery; struct _GSignalQuery { guint signal_id; const gchar *signal_name; GType itype; /* mangled with G_SIGNAL_TYPE_STATIC_SCOPE flag */ GSignalFlags signal_flags; GType return_type; /* mangled with G_SIGNAL_TYPE_STATIC_SCOPE flag */ guint n_params; const GType *param_types; }; Using the param types, you should be able to convert an argument vector in the native format of the language binding to a GValue array (using the functions for converting from native formats to GValues written earlier). The signal_id and detail arguments can be deduced with the g_signal_parse_name function. The return_value is a GValue to store the return value of the signal emission. It should be initialised before the g_signal_emitv with code something like this: GValue return_type = { 0, }; GSignalQuery query; g_signal_query(signal_id, &query); if (query.return_type != G_TYPE_NONE) g_value_init(&return_type, query.return_type); Signal emission is wrapped in the pygobject_emit function in pygtk. The interface provided to python is a GObject.emit method that takes a detailed signal argument as the first argument, followed by any arguments for the signal. The method returns the return value of the signal (using the function to convert from a GValue to native types). It is easy to add new signals to any instantiable type such as a GObject. This is done with the g_signal_newv function: guint g_signal_newv const gchar *signal_name GType itype GSignalFlags signal_flags GClosure *class_closure GSignalAccumulator accumulator gpointer accu_data GSignalCMarsahller c_marshaller GType return_type guint n_params GType *param_types The signal_name argument is the name of the signal being created. The itype argument is the GType of instances this signal should apply to. The signal_flags gives the flags for the signal (whether to run the class closure before or after handlers, etc). The accumulator related arguments can be ignored (pass NULL), and so can the c_marshaller argument (it is only needed if you intend to connect C handlers to the signal). The last three arguments give the GType's of the return value and parameters for the signal. The class_closure argument takes a closure that represents the `class handler' for the signal. That is, a handler that will always be called when the signal is emitted. Usually, this would be a different type of closure to that passed to g_signal_connect_closure. Instead of just wrapping a function, it will usually call a virtual function of the GObject wrapper (so that the class handler can be overidden in subclasses). The naming convention used for the class handler used in PyGTK and Inti is "do_" prepended to the signal name (XXXX - what do other bindings do?). It is recommended that other language bindings use something similar. In the case of bindings for languages with good introspective capabilities, you may be able to call a method if you know only its name. Since the name of the class handler is derived from the signal name (which can be derived from the signal id passed in the invocation hint for the marshaller), you can write a class closure marshal function that can handle all possible signals. This aproach is used in the python bindings where a single closure is used as the class closure for all signals created in python. See the pyg_signal_class_closure_get function in gobjectmodule.c file in pygtk for details.