GTK+ By Example/Beginning

In this chapter, we will look at some very simple GTK+ examples, starting off with the classic "Hello, world!".

1. You will find you learn more effectively by getting stuck in and writing code.
2. Make sure you understand what you are doing before you move on to the next chapter. Chapters in this book are designed to be completed as individual units but background knowledge of previous chapters is assumed.
3. You can copy and paste code to get quick results but typing out by hand will help you familiarise yourself with GTK+ coding style and is therefore recommended.
4. Take it slow and tell yourself how wonderful you are for getting each example working.
5. Make mistakes changing the code: get things wrong and have fun!

Compiling the examples

When you compile these example programs, you may need to pass additional information to the command line to enable the GTK+ windowing libraries.

On Linux, you will need to ensure that you have the program pkg-config.

gcc -Wall -g helloworld.c -o helloworld `pkg-config --cflags gtk+-2.0` `pkg-config --libs gtk+-2.0`

More information is available here: https://developer.gnome.org/gtk-tutorial/stable/x111.html

An empty window

In this example we create a single window, set its title and size and connect an event that allows the application to close.

#include <gtk/gtk.h>

int
main (int   argc,
      char *argv[])
{
  GtkWidget *window;

  /* Initialise GTK+ passing to it all command line arguments  */
  gtk_init (&argc, &argv);

  /* create a new window, set values */
  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  gtk_window_set_title (GTK_WINDOW (window), "Hello GTK+ World");
  /* set the size of the window */
  gtk_widget_set_size_request (GTK_WIDGET (window), 200, 200);
  /* connect the windows "destroy" event */
  g_signal_connect (G_OBJECT (window), "destroy",
                    G_CALLBACK (gtk_main_quit), NULL);  

  /* set the window as visible */
  gtk_widget_show (window);

  /* run the GTK+ main loop */
  gtk_main ();
  return 0;
}

Congratulations, you have created your first GTK+ window. You may not completely understand the code you have written yet. That's alright; by the end of this chapter creating windows will be easy. GTK+ is object oriented. As C is not designed as an object oriented language you must explicitly cast objects- this will occur most often with the paramater passed to a function. You first cast window from a GtkWidget to a GtkWindow when you wrote GTK_WINDOW (window). If you don't understand this example feel free to move on after you complete two small challenges. You can probably guess how to do them easily, but don't let yourself be tricked. The act of doing even small tasks will help you focus yourself on solving large problems.

challenge: Change the name of the window to your first name.

challenge: Change the window size to 400 * 400 pixels, currently it is 200 * 200 pixels.

We will have explained everything in this example by the end of the chapter, but for now let us focus on two lines of code.

gtk_init (&argc, &argv);

gtk_init () is called at the start of all GTK+ applications, it initialises gtk+ library. &argc and &argv are passed to gtk_init (), these are command line arguments that have been passed to the application gtk_init () takes these becase it has a set of command line arguments it can accept.

gtk_main ();

gtk_main () is called once your application has been set up, once this has been called you will have to wait until gtk_main_quit () is called before the application continues. We have already connected to that event and will explain it after further excercises.

Window with a button

This example is slightly different to the last example, we have added a button also notice we have not called gtk_widget_set_size_request ().

#include <gtk/gtk.h>

int
main (int   argc,
      char *argv[])
{
  GtkWidget *window;
  GtkWidget *button;

  /* Initialise GTK+ passing to it all command line arguments  */
  gtk_init (&argc, &argv);

  /* create a new window, set values */
  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  gtk_window_set_title (GTK_WINDOW (window), "Hello Button");
  /* connect the windows "destroy" event */
  g_signal_connect (G_OBJECT (window), "destroy",
                    G_CALLBACK (gtk_main_quit), NULL);  

  button = gtk_button_new_with_label ("Hello Window");
  gtk_container_add (GTK_CONTAINER (window), button);
  g_signal_connect (G_OBJECT (button), "clicked",
                    G_CALLBACK (gtk_main_quit), NULL);

  /* set the window as visible */
  gtk_widget_show_all (window);

  /* run the GTK+ main loop */
  gtk_main ();
  return 0;
}

Good work, another one bites the dust, don't move on just yet, same format as before my friend. When you click the button it closes the window, what kind of annoying application is this? One that is trying to get you to pay attention to how it is done that's what. Notice this time we did not call gtk_widget_set_size_request (), that is because GTK+ automatically sizes windows and widgets for you, for the most part you should not have to set the size of widgets or windows your self; the last example was different because we had nothing inside the window. As the name size_request suggest the size you ask for may not be the size allocated to the widget, this will be explained more further on in the book, for now understanding that it is a request should be enough.

challenge: make the button do nothing when you click it, that's right nothing.

challenge: remove the line starting with 'button =', and run your program from the command line and see what happens.

Once again we will not be explaining everything just yet, that would take the fun out of this for you. Anyhow, how did you go with the challenges? I bet you did well. Let's go through a two more lines of code:

window = gtk_window_new (GTK_WINDOW_TOPLEVEL);

gtk_window_new () creates a new window of one of two types, GTK_WINDOW_TOPLEVEL and GTK_WINDOW_POPUP. Don't let the name GTK_WINDOW_POPUP confuse you it is not for popup dialogs, popup dialogs and GTK_WINDOW_POPUP both will be explained in future chapters.

button = gtk_button_new_with_label ("Hello Window");

button_new_with_label () is a convenience function, in this case it means it creates a button and a label and inserts the label in the button for you. A button in GTK+ is a container that when clicked may cause a piece of code to be run. The button may hold anything you insert into it, but putting somethin in a button just for fun will really confuse people, so we suggest you insert labels or images, and if you are a great person you will learn to insert images and labels at the rate you are going you will rule the world soon.