GObject Brain Dump

OK, so here's how it is. All GTK widgets are descended from GObject. GObject provides 4 things:

Reference counting

This means you don't have to worry about how an object gets destroyed. It just goes away when the last reference is dropped. You can also add references to it to make sure it doesn't get destroyed while you're passing it around with g_object_ref().

For example, suppose you had a label (called "label") you wanted to move from one table (called "table1") to another (called "table2"):

g_object_ref(label);
gtk_container_remove(GTK_CONTAINER(table1), label);
gtk_table_attach(GTK_TABLE(table2), label, 0, 1, 0, 1, 0, 0, 0, 0);
g_object_unref(label);

Inheritance

You can create new types of widgets from existing types. This is a tutorial onto itself: ​http://www.gtk.org/tutorial/x2312.html

Properties

If you think of data structures, in C they contain individual members of various types. For, example, the mythical HumanBeing data structure:

typedef enum {
  HUMAN_FEMALE,
  HUMAN_MALE
} HumanGender;

typedef struct {
  char *first_name;
  char *last_name;
  double height;
  HumanGender gender;
} HumanBeing;

You would access this data structure like so: printf ("Human's first name is %s\n", ((HumanBeing *)some_human)->first_name);

GObject provides a way to formally identify such a structure member using a certain name which you can then use with g_object_new(), g_object_set(), and g_object_get(). So, if HumanBeing were a GObject, instead of using some_human->first_name, you could do

char *first_name = NULL;
g_object_get (G_OBJECT (some_human), "first-name", &first_name, NULL);
printf ("Human's first name is %s\n", first_name) ;
g_free (first_name) ;

This doesn't look too appealing, but consider: Each subclass of GObject adds new properties to the list of properties of its parent calss, so, by the time you get to, say, GtkWindow, you can do something really cool, like,

g_object_new (GTK_TYPE_WINDOW, "visible", TRUE, "title", "Demo App", "default-width", 320, "default-height", 240,
  "child", g_object_new (GTK_TYPE_ALIGNMENT, "visible", TRUE, "xalign", 0.5, "yalign", 0.5, "xscale", 0.0, "yscale", 0.0,
    "child", g_object_new (GTK_TYPE_BUTTON, "visible", TRUE, "label", GTK_STOCK_OK, "use-stock", TRUE, NULL),
    NULL),
  NULL);

g_object_new() allows you to create a new object of the type specified in its first argument, and set any number of the object's properties. You finish off the list of properties by giving it the NULL property at the end of the list. g_object_set() works the same way, but modifies the properties of an existing object. g_object_get() requires, for each property you specify, that you follow it up with a variable passed by reference, so that it may fill out the variable with the value. For example:

char *button_label;
gboolean button_sensitive;
g_object_get (G_OBJECT (the_button, "label", &button_label, "sensitive", &button_sensitive, NULL);

Unlike data structure members, properties can be defined more rigorously. Values of a property can be restricted to a certain range, and every property has a default value.

Signals

A signal is an object's means of informing those who are interested that something has happened to it. If you are interested in things that are happening to your object, you must pass a pointer to a function to g_signal_connect for each of the things you are interested in. All classes provide lists of such things - lets call them events. For example, when a button is clicked, all those interested will be informed. For a given button, say, the_button, you can express your interest in when it gets clicked, by connecting to its "clicked" signal:

g_signal_connect (G_OBJECT (the_button), "clicked", (GCallback)the_button_got_clicked, NULL);

You normally do this right after creating the button, so that you don't miss any clicks. Now, this is fine and dandy, but you gotta ask yourself: What does the_button_got_clicked look like? Well, that depends on the event you're interested in. The documentation for a given signal tells you what kind of a function to pass to g_signal_connect(). For example, ​http://developer.gnome.org/doc/API/2.0/gtk/GtkButton.html#GtkButton-clicked tells you that, in order to hook up to a button's "clicked" signal, you must create the_button_got_clicked to be of the form

static void the_button_got_clicked (GtkWidget *the_button, gpointer user_data);

In contrast, a "key-press-event" signal requires a different kind of function: ​http://developer.gnome.org/doc/API/2.0/gtk/GtkWidget.html#GtkWidget-key-press-event

One thing you will notice though is that all signals have gpointer user_data as the last parameter. This way, you can pass some stuff into the function when you hook up the signal. You do this by giving a pointer to this stuff to g_signal_connect(). You put it in the last parameter (the one that's NULL in the above example).

The bottom line is, you need to read the documentation for a given signal to know what kind of a function you need to write to properly receive it. If you write your function wrong, it will still work, but the arguments it receives will be gibberish - or segfault bait, if you prefer.

Every GTK widget has its signals documented. For example, if you go to ​http://developer.gnome.org/doc/API/2.0/gtk/GtkButton.html you will find all the signals a GtkButton can have under the heading 'Signals'.

Now, an interesting bit. Objects have properties, right? Well, it turns out that, for each property name an object has, there's a corresponding signal called "notify::<property-name>" and the function you hook up to it is always the same, no matter what <property-name> is:

static void property_name_has_changed (GObject *the_object, GParamSpec *pspec, gpointer user_data);

Pulling It All Together

So, to illustrate signals and properties, here's a program:

#include <gtk/gtk.h>

static void button_clicked(GtkWidget *button, gpointer user_data);
static void button_notify_sensitive(GObject *button, GParamSpec *pspec, gpointer user_data);

int main(int argc, char **argv)
{
  GtkWidget *btn1 = NULL, *btn2 = NULL, *vbox = NULL;

  gtk_init(&argc, &argv);

  g_signal_connect (
    G_OBJECT(g_object_new(GTK_TYPE_WINDOW, "title", "Demo", "visible", TRUE,
      "child", vbox = g_object_new(GTK_TYPE_VBOX, "visible", TRUE, NULL),
      NULL)), "delete-event", (GCallback)gtk_main_quit, NULL);

  gtk_container_add(GTK_CONTAINER(vbox),
    btn1 = g_object_new(GTK_TYPE_BUTTON, "visible", TRUE, "label", "Button 1", "sensitive", FALSE, NULL)) ;
  gtk_container_add(GTK_CONTAINER(vbox),
    btn2 = g_object_new(GTK_TYPE_BUTTON, "visible", TRUE, "label", "Button 2", NULL)) ;

  g_signal_connect(G_OBJECT(btn1), "clicked", (GCallback)button_clicked, NULL);
  g_signal_connect(G_OBJECT(btn2), "clicked", (GCallback)button_clicked, NULL);
  g_signal_connect(G_OBJECT(btn1), "notify::sensitive", (GCallback)button_notify_sensitive, btn2);
  g_signal_connect(G_OBJECT(btn2), "notify::sensitive", (GCallback)button_notify_sensitive, btn1);

  gtk_main();

  return 0;
}

static void button_clicked(GtkWidget *button, gpointer user_data)
{
  g_object_set(G_OBJECT(button), "sensitive", FALSE, NULL);
}

static void button_notify_sensitive(GObject *button, GParamSpec *pspec, gpointer user_data)
{
  gboolean i_am_sensitive;
  GObject *the_other_button = G_OBJECT(user_data);

  g_object_get(button, "sensitive", &i_am_sensitive, NULL);
  /* 
   * Here, we cannot simply always set the_other_button to !i_am_sensitive, because
   * that'll cause a loop, Remember, we're being told both when the button goes from
   * sensitive to insensitive /and/ when it goes from insensitive to sensitive.
   */
  if (!i_am_sensitive)
    g_object_set(the_other_button, "sensitive", TRUE, NULL);
}