| 2 | | |
| 3 | | = GObject Brain Dump = |
| 4 | | |
| 5 | | OK, so here's how it is. All GTK widgets are descended from GObject. GObject provides 4 things: |
| 6 | | |
| 7 | | == Reference counting == |
| 8 | | 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()}}}. |
| 9 | | |
| 10 | | For example, suppose you had a label (called "label") you wanted to move from one table (called "table1") to another (called "table2"): |
| 11 | | {{{ |
| 12 | | g_object_ref(label); |
| 13 | | gtk_container_remove(GTK_CONTAINER(table1), label); |
| 14 | | gtk_table_attach(GTK_TABLE(table2), label, 0, 1, 0, 1, 0, 0, 0, 0); |
| 15 | | g_object_unref(label); |
| 16 | | }}} |
| 17 | | |
| 18 | | == Inheritance == |
| 19 | | You can create new types of widgets from existing types. This is a tutorial onto itself: http://www.gtk.org/tutorial/x2312.html |
| 20 | | |
| 21 | | == Properties == |
| 22 | | If you think of data structures, in C they contain individual members of various types. For, example, the mythical {{{HumanBeing}}} data structure: |
| 23 | | {{{ |
| 24 | | typedef enum { |
| 25 | | HUMAN_FEMALE, |
| 26 | | HUMAN_MALE |
| 27 | | } HumanGender; |
| 28 | | |
| 29 | | typedef struct { |
| 30 | | char *first_name; |
| 31 | | char *last_name; |
| 32 | | double height; |
| 33 | | HumanGender gender; |
| 34 | | } HumanBeing; |
| 35 | | }}} |
| 36 | | You would access this data structure like so: {{{printf ("Human's first name is %s\n", ((HumanBeing *)some_human)->first_name);}}} |
| 37 | | |
| 38 | | 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 |
| 39 | | {{{ |
| 40 | | char *first_name = NULL; |
| 41 | | g_object_get (G_OBJECT (some_human), "first-name", &first_name, NULL); |
| 42 | | printf ("Human's first name is %s\n", first_name) ; |
| 43 | | g_free (first_name) ; |
| 44 | | }}} |
| 45 | | 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, |
| 46 | | {{{ |
| 47 | | g_object_new (GTK_TYPE_WINDOW, "visible", TRUE, "title", "Demo App", "default-width", 320, "default-height", 240, |
| 48 | | "child", g_object_new (GTK_TYPE_ALIGNMENT, "visible", TRUE, "xalign", 0.5, "yalign", 0.5, "xscale", 0.0, "yscale", 0.0, |
| 49 | | "child", g_object_new (GTK_TYPE_BUTTON, "visible", TRUE, "label", GTK_STOCK_OK, "use-stock", TRUE, NULL), |
| 50 | | NULL), |
| 51 | | NULL); |
| 52 | | }}} |
| 53 | | {{{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. |
| 54 | | {{{g_object_set()}}} works the same way, but modifies the properties of an existing object. |
| 55 | | {{{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: |
| 56 | | {{{ |
| 57 | | char *button_label; |
| 58 | | gboolean button_sensitive; |
| 59 | | g_object_get (G_OBJECT (the_button, "label", &button_label, "sensitive", &button_sensitive, NULL); |
| 60 | | }}} |
| 61 | | 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. |
| 62 | | |
| 63 | | == Signals == |
| 64 | | 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: |
| 65 | | {{{ |
| 66 | | g_signal_connect (G_OBJECT (the_button), "clicked", (GCallback)the_button_got_clicked, NULL); |
| 67 | | }}} |
| 68 | | 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 |
| 69 | | {{{ |
| 70 | | static void the_button_got_clicked (GtkWidget *the_button, gpointer user_data); |
| 71 | | }}} |
| 72 | | 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 |
| 73 | | |
| 74 | | 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). |
| 75 | | |
| 76 | | 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. |
| 77 | | |
| 78 | | 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'. |
| 79 | | |
| 80 | | 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: |
| 81 | | {{{ |
| 82 | | static void property_name_has_changed (GObject *the_object, GParamSpec *pspec, gpointer user_data); |
| 83 | | }}} |
| 84 | | |
| 85 | | = Pulling It All Together = |
| 86 | | |
| 87 | | So, to illustrate signals and properties, here's a program: |
| 88 | | {{{ |
| 89 | | #include <gtk/gtk.h> |
| 90 | | |
| 91 | | static void button_clicked(GtkWidget *button, gpointer user_data); |
| 92 | | static void button_notify_sensitive(GObject *button, GParamSpec *pspec, gpointer user_data); |
| 93 | | |
| 94 | | int main(int argc, char **argv) |
| 95 | | { |
| 96 | | GtkWidget *btn1 = NULL, *btn2 = NULL, *vbox = NULL; |
| 97 | | |
| 98 | | gtk_init(&argc, &argv); |
| 99 | | |
| 100 | | g_signal_connect ( |
| 101 | | G_OBJECT(g_object_new(GTK_TYPE_WINDOW, "title", "Demo", "visible", TRUE, |
| 102 | | "child", vbox = g_object_new(GTK_TYPE_VBOX, "visible", TRUE, NULL), |
| 103 | | NULL)), "delete-event", (GCallback)gtk_main_quit, NULL); |
| 104 | | |
| 105 | | gtk_container_add(GTK_CONTAINER(vbox), |
| 106 | | btn1 = g_object_new(GTK_TYPE_BUTTON, "visible", TRUE, "label", "Button 1", "sensitive", FALSE, NULL)) ; |
| 107 | | gtk_container_add(GTK_CONTAINER(vbox), |
| 108 | | btn2 = g_object_new(GTK_TYPE_BUTTON, "visible", TRUE, "label", "Button 2", NULL)) ; |
| 109 | | |
| 110 | | g_signal_connect(G_OBJECT(btn1), "clicked", (GCallback)button_clicked, NULL); |
| 111 | | g_signal_connect(G_OBJECT(btn2), "clicked", (GCallback)button_clicked, NULL); |
| 112 | | g_signal_connect(G_OBJECT(btn1), "notify::sensitive", (GCallback)button_notify_sensitive, btn2); |
| 113 | | g_signal_connect(G_OBJECT(btn2), "notify::sensitive", (GCallback)button_notify_sensitive, btn1); |
| 114 | | |
| 115 | | gtk_main(); |
| 116 | | |
| 117 | | return 0; |
| 118 | | } |
| 119 | | |
| 120 | | static void button_clicked(GtkWidget *button, gpointer user_data) |
| 121 | | { |
| 122 | | g_object_set(G_OBJECT(button), "sensitive", FALSE, NULL); |
| 123 | | } |
| 124 | | |
| 125 | | static void button_notify_sensitive(GObject *button, GParamSpec *pspec, gpointer user_data) |
| 126 | | { |
| 127 | | gboolean i_am_sensitive; |
| 128 | | GObject *the_other_button = G_OBJECT(user_data); |
| 129 | | |
| 130 | | g_object_get(button, "sensitive", &i_am_sensitive, NULL); |
| 131 | | /* |
| 132 | | * Here, we cannot simply always set the_other_button to !i_am_sensitive, because |
| 133 | | * that'll cause a loop, Remember, we're being told both when the button goes from |
| 134 | | * sensitive to insensitive /and/ when it goes from insensitive to sensitive. |
| 135 | | */ |
| 136 | | if (!i_am_sensitive) |
| 137 | | g_object_set(the_other_button, "sensitive", TRUE, NULL); |
| 138 | | } |
| 139 | | }}} |
