## Getting Started with GTK+

This chapter contains some tutorial information to get you started with GTK+ programming. It assumes that you have GTK+, its dependencies and a C compiler installed and ready to use. If you need to build GTK+ itself first, refer to the Compiling the GTK+ libraries section in this reference.

## Basics

To begin our introduction to GTK, we'll start with the simplest program possible. This program will create an empty 200 × 200 pixel window.

Create a new file with the following content named example-0.c.

    #include <gtk/gtk.h>

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

      gtk_init (&argc, &argv);

      window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
      gtk_window_set_title (GTK_WINDOW (window), "Window");

      g_signal_connect (window, "destroy", G_CALLBACK (gtk_main_quit), NULL);

      gtk_widget_show (window);

      gtk_main ();

      return 0;
    }

You can compile the program above with GCC using:

`gcc `pkg-config --cflags gtk+-3.0` -o example-0 example-0.c `pkg-config --libs gtk+-3.0``

For more information on how to compile a GTK+ application, please refer to the Compiling GTK+ Applications section in this reference.

All GTK+ applications will, of course, include `gtk/gtk.h`, which declares functions, types and macros required by GTK+ applications.

Even if GTK+ installs multiple header files, only the top-level `gtk/gtk.h` header can be directly included by third party code. The compiler will abort with an error if any other header is directly included.

We then proceed into the `main`() function of the application, and we declare a `window` variable as a pointer of type GtkWidget.

The following line will call `gtk_init()`, which is the initialization function for GTK+; this function will set up GTK+, the type system, the connection to the windowing environment, etc. The `gtk_init()` takes as arguments the pointers to the command line arguments counter and string array; this allows GTK+ to parse specific command line arguments that control the behavior of GTK+ itself. The parsed arguments will be removed from the array, leaving the unrecognized ones for your application to parse.

For more information on which command line arguments GTK+ recognizes, please refer to the Running GTK+ Applications section in this reference.

The call to `gtk_window_new()` will create a new GtkWindow and store it inside the `window` variable. The type of the window is `GTK_WINDOW_TOPLEVEL`, which means that the GtkWindow will be managed by the windowing system: it will have a frame, a title bar and window controls, depending on the platform.

In order to terminate the application when the GtkWindow is destroyed, we connect the “destroy” signal to the `gtk_main_quit()` function. This function will terminate the GTK+ main loop started by calling `gtk_main()` later. The “destroy” signal is emitted when a widget is destroyed, either by explicitly calling `gtk_widget_destroy()` or when the widget is unparented. Top-level GtkWindows are also destroyed when the Close window control button is clicked.

GtkWidgets are hidden by default. By calling `gtk_widget_show()` on a GtkWidget we are asking GTK+ to set the visibility attribute so that it can be displayed. All this work is done after the main loop has been started.

The last line of interest is the call to `gtk_main()`. This function will start the GTK+ main loop and will block the control flow of the `main()` until the `gtk_main_quit()` function is called.

While the program is running, GTK+ is receiving events. These are typically input events caused by the user interacting with your program, but also things like messages from the window manager or other applications. GTK+ processes these and as a result, signals may be emitted on your widgets. Connecting handlers for these signals is how you normally make your program do something in response to user input.

The following example is slightly more complex, and tries to showcase some of the capabilities of GTK+.

In the long tradition of programming languages and libraries, it is called Hello, World.

Example 1. Hello World in GTK+

Create a new file with the following content named example-1.c.

    #include <gtk/gtk.h>

    /* This is a callback function. The data arguments are ignored
     * in this example. More on callbacks below.
     */
    static void
    print_hello (GtkWidget *widget,
                 gpointer   data)
    {
      g_print ("Hello World\n");
    }

    static gboolean
    on_delete_event (GtkWidget *widget,
                     GdkEvent  *event,
                     gpointer   data)
    {
      /* If you return FALSE in the "delete_event" signal handler,
       * GTK will emit the "destroy" signal. Returning TRUE means
       * you don't want the window to be destroyed.
       *
       * This is useful for popping up 'are you sure you want to quit?'
       * type dialogs.
       */

      g_print ("delete event occurred\n");

      return TRUE;
    }

    int
    main (int   argc,
          char *argv[])
    {
      /* GtkWidget is the storage type for widgets */
      GtkWidget *window;
      GtkWidget *button;

      /* This is called in all GTK applications. Arguments are parsed
       * from the command line and are returned to the application.
       */
      gtk_init (&argc, &argv);

      /* create a new window, and set its title */
      window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
      gtk_window_set_title (GTK_WINDOW (window), "Hello");

      /* When the window emits the "delete-event" signal (which is emitted
       * by GTK+ in response to an event coming from the window manager,
       * usually as a result of clicking the "close" window control), we
       * ask it to call the on_delete_event() function as defined above.
       *
       * The data passed to the callback function is NULL and is ignored
       * in the callback function.
       */
      g_signal_connect (window, "delete-event", G_CALLBACK (on_delete_event), NULL);

      /* Here we connect the "destroy" event to the gtk_main_quit() function.
       *
       * This signal is emitted when we call gtk_widget_destroy() on the window,
       * or if we return FALSE in the "delete_event" callback.
       */
      g_signal_connect (window, "destroy", G_CALLBACK (gtk_main_quit), NULL);

      /* Sets the border width of the window. */
      gtk_container_set_border_width (GTK_CONTAINER (window), 10);

      /* Creates a new button with the label "Hello World". */
      button = gtk_button_new_with_label ("Hello World");

      /* When the button receives the "clicked" signal, it will call the
       * function print_hello() passing it NULL as its argument.
       *
       * The print_hello() function is defined above.
       */
      g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL);

      /* The g_signal_connect_swapped() function will connect the "clicked" signal
       * of the button to the gtk_widget_destroy() function; instead of calling it
       * using the button as its argument, it will swap it with the user data
       * argument. This will cause the window to be destroyed by calling
       * gtk_widget_destroy() on the window.
       */
      g_signal_connect_swapped (button, "clicked", G_CALLBACK (gtk_widget_destroy), window);

      /* This packs the button into the window. A GtkWindow inherits from GtkBin,
       * which is a special container that can only have one child
       */
      gtk_container_add (GTK_CONTAINER (window), button);

      /* The final step is to display this newly created widget... */
      gtk_widget_show (button);

      /* ... and the window */
      gtk_widget_show (window);

      /* All GTK applications must have a gtk_main(). Control ends here
       * and waits for an event to occur (like a key press or a mouse event),
       * until gtk_main_quit() is called.
       */
      gtk_main ();

      return 0;
    }

You can compile the program above with GCC using:

`gcc `pkg-config --cflags gtk+-3.0` -o example-1 example-1.c `pkg-config --libs gtk+-3.0``