## Getting Started with GTK+

This chapter is 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 200x200 pixel window:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20

    #include <gtk/gtk.h>

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

      gtk_init (&argc, &argv);

      window = gtk_window_new (GTK_WINDOW_TOPLEVEL);

      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 window-default window-default.c `pkg-config --libs gtk+-3.0``

### Note

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.

### Warning

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.

### Note

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+

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104

    #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;
    }

## Packing

When creating an application, you'll want to put more than one widget inside a window. Our first helloworld example only used one widget so we could simply use a `gtk_container_add()` call to "pack" the widget into the window. But when you want to put more than one widget into a window, it it becomes important to control how each widget is positioned and sized. This is where packing comes in.

GTK+ comes with a large variety of layout containers whose purpose it is to control the layout of the child widgets that are added to them. See Layout Containers for an overview.

The following example shows how the GtkGrid container lets you arrange several buttons:

Example 2. Packing buttons

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73

    #include <gtk/gtk.h>

    static void
    print_hello (GtkWidget *widget,
         gpointer   data)
    {
      g_print ("Hello World\n");
    }

    int
    main (int   argc,
          char *argv[])
    {
      GtkWidget *window;
      GtkWidget *grid;
      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), "Grid");
      g_signal_connect (window, "destroy", G_CALLBACK (gtk_main_quit), NULL);
      gtk_container_set_border_width (GTK_CONTAINER (window), 10);

      /* Here we construct the container that is going pack our buttons */
      grid = gtk_grid_new ();

      /* Pack the container in the window */
      gtk_container_add (GTK_CONTAINER (window), grid);

      button = gtk_button_new_with_label ("Button 1");
      g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL);

      /* Place the first button in the grid cell (0, 0), and make it fill
       * just 1 cell horizontally and vertically (ie no spanning)
       */
      gtk_grid_attach (GTK_GRID (grid), button, 0, 0, 1, 1);

      button = gtk_button_new_with_label ("Button 2");
      g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL);

      /* Place the second button in the grid cell (1, 0), and make it fill
       * just 1 cell horizontally and vertically (ie no spanning)
       */
      gtk_grid_attach (GTK_GRID (grid), button, 1, 0, 1, 1);

      button = gtk_button_new_with_label ("Quit");
      g_signal_connect (button, "clicked", G_CALLBACK (gtk_main_quit), NULL);

      /* Place the Quit button in the grid cell (0, 1), and make it
       * span 2 columns.
       */
      gtk_grid_attach (GTK_GRID (grid), button, 0, 1, 2, 1);

      /* Now that we are done packing our widgets, we show them all
       * in one go, by calling gtk_widget_show_all() on the window.
       * This call recursively calls gtk_widget_show() on all widgets
       * that are contained in the window, directly or indirectly.
       */
      gtk_widget_show_all (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;
    }

## Drawing

Many widgets, like buttons, do all their drawing themselves. You just tell them the label you want to see, and they figure out what font to use, draw the button outline and focus rectangle, etc. Sometimes, it is necessary to do some custom drawing. In that case, a GtkDrawingArea might be the right widget to use. It offers a canvas on which you can draw by connecting to the "draw" signal.

The contents of a widget often need to be partially or fully redrawn, e.g. when another window is moved and uncovers part of the widget, or when tie window containing it is resized. It is also possible to explicitly cause part or all of the widget to be redrawn, by calling `gtk_widget_queue_draw()` or its variants. GTK+ takes care of most of the details by providing a ready-to-use cairo context to the ::draw signal handler.

The following example shows a ::draw signal handler. It is a bit more complicated than the previous examples, since it also demonstrates input event handling by means of ::button-press and ::motion-notify handlers.

Example 3. Drawing in response to input

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200

    #include <gtk/gtk.h>

    /* Surface to store current scribbles */
    static cairo_surface_t *surface = NULL;

    static void
    clear_surface (void)
    {
      cairo_t *cr;

      cr = cairo_create (surface);

      cairo_set_source_rgb (cr, 1, 1, 1);
      cairo_paint (cr);

      cairo_destroy (cr);
    }

    /* Create a new surface of the appropriate size to store our scribbles */
    static gboolean
    configure_event_cb (GtkWidget         *widget,
                GdkEventConfigure *event,
                gpointer           data)
    {
      if (surface)
        cairo_surface_destroy (surface);

      surface = gdk_window_create_similar_surface (gtk_widget_get_window (widget),
                                           CAIRO_CONTENT_COLOR,
                                           gtk_widget_get_allocated_width (widget),
                                           gtk_widget_get_allocated_height (widget));

      /* Initialize the surface to white */
      clear_surface ();

      /* We've handled the configure event, no need for further processing. */
      return TRUE;
    }

    /* Redraw the screen from the surface. Note that the ::draw
     * signal receives a ready-to-be-used cairo_t that is already
     * clipped to only draw the exposed areas of the widget
     */
    static gboolean
    draw_cb (GtkWidget *widget,
     cairo_t   *cr,
     gpointer   data)
    {
      cairo_set_source_surface (cr, surface, 0, 0);
      cairo_paint (cr);

      return FALSE;
    }

    /* Draw a rectangle on the surface at the given position */
    static void
    draw_brush (GtkWidget *widget,
        gdouble    x,
        gdouble    y)
    {
      cairo_t *cr;

      /* Paint to the surface, where we store our state */
      cr = cairo_create (surface);

      cairo_rectangle (cr, x - 3, y - 3, 6, 6);
      cairo_fill (cr);

      cairo_destroy (cr);

      /* Now invalidate the affected region of the drawing area. */
      gtk_widget_queue_draw_area (widget, x - 3, y - 3, 6, 6);
    }

    /* Handle button press events by either drawing a rectangle
     * or clearing the surface, depending on which button was pressed.
     * The ::button-press signal handler receives a GdkEventButton
     * struct which contains this information.
     */
    static gboolean
    button_press_event_cb (GtkWidget      *widget,
                   GdkEventButton *event,
                   gpointer        data)
    {
      /* paranoia check, in case we haven't gotten a configure event */
      if (surface == NULL)
        return FALSE;

      if (event->button == 1)
        {
          draw_brush (widget, event->x, event->y);
        }
      else if (event->button == 3)
        {
          clear_surface ();
          gtk_widget_queue_draw (widget);
        }

      /* We've handled the event, stop processing */
      return TRUE;
    }

    /* Handle motion events by continuing to draw if button 1 is
     * still held down. The ::motion-notify signal handler receives
     * a GdkEventMotion struct which contains this information.
     */
    static gboolean
    motion_notify_event_cb (GtkWidget      *widget,
                    GdkEventMotion *event,
                    gpointer        data)
    {
      int x, y;
      GdkModifierType state;

      /* paranoia check, in case we haven't gotten a configure event */
      if (surface == NULL)
        return FALSE;

      /* This call is very important; it requests the next motion event.
       * If you don't call gdk_window_get_pointer() you'll only get
       * a single motion event. The reason is that we specified
       * GDK_POINTER_MOTION_HINT_MASK to gtk_widget_set_events().
       * If we hadn't specified that, we could just use event->x, event->y
       * as the pointer location. But we'd also get deluged in events.
       * By requesting the next event as we handle the current one,
       * we avoid getting a huge number of events faster than we
       * can cope.
       */
      gdk_window_get_pointer (event->window, &x, &y, &state);

      if (state & GDK_BUTTON1_MASK)
        draw_brush (widget, x, y);

      /* We've handled it, stop processing */
      return TRUE;
    }

    static void
    close_window (void)
    {
      if (surface)
        cairo_surface_destroy (surface);

      gtk_main_quit ();
    }

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

      gtk_init (&argc, &argv);

      window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
      gtk_window_set_title (GTK_WINDOW (window), "Drawing Area");

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

      gtk_container_set_border_width (GTK_CONTAINER (window), 8);

      frame = gtk_frame_new (NULL);
      gtk_frame_set_shadow_type (GTK_FRAME (frame), GTK_SHADOW_IN);
      gtk_container_add (GTK_CONTAINER (window), frame);

      da = gtk_drawing_area_new ();
      /* set a minimum size */
      gtk_widget_set_size_request (da, 100, 100);

      gtk_container_add (GTK_CONTAINER (frame), da);

      /* Signals used to handle the backing surface */
      g_signal_connect (da, "draw",
                G_CALLBACK (draw_cb), NULL);
      g_signal_connect (da,"configure-event",
                G_CALLBACK (configure_event_cb), NULL);

      /* Event signals */
      g_signal_connect (da, "motion-notify-event",
                G_CALLBACK (motion_notify_event_cb), NULL);
      g_signal_connect (da, "button-press-event",
                G_CALLBACK (button_press_event_cb), NULL);

      /* Ask to receive events the drawing area doesn't normally
       * subscribe to. In particular, we need to ask for the
       * button press and motion notify events that want to handle.
       */
      gtk_widget_set_events (da, gtk_widget_get_events (da)
                         | GDK_BUTTON_PRESS_MASK
                         | GDK_POINTER_MOTION_MASK
                         | GDK_POINTER_MOTION_HINT_MASK);

      gtk_widget_show_all (window);

      gtk_main ();

      return 0;
    }

## Building interfaces

When construcing a more complicated user interface, with dozens or hundreds of widgets, doing all the setup work in C code is cumbersome, and making changes becomes next to impossible.

Thankfully, GTK+ supports the separation of user interface layout from your business logic, by using UI descriptions in an XML format that can be parsed by the GtkBuilder class.

Example 4. Packing buttons with GtkBuilder

            #include <gtk/gtk.h>

    static void
    print_hello (GtkWidget *widget,
                 gpointer   data)
    {
      g_print ("Hello World\n");
    }

    int
    main (int   argc,
          char *argv[])
    {
      GtkBuilder *builder;
      GObject *window;
      GObject *button;

      gtk_init (&argc, &argv);

      /* Construct a GtkBuilder instance and load our UI description */
      builder = gtk_builder_new ();
      gtk_builder_add_from_file (builder, "builder.ui", NULL);

      /* Connect signal handlers to the constructed widgets. */
      window = gtk_builder_get_object (builder, "window");
      g_signal_connect (window, "destroy", G_CALLBACK (gtk_main_quit), NULL);

      button = gtk_builder_get_object (builder, "button1");
      g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL);

      button = gtk_builder_get_object (builder, "button2");
      g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL);

      button = gtk_builder_get_object (builder, "quit");
      g_signal_connect (button, "clicked", G_CALLBACK (gtk_main_quit), NULL);

      gtk_main ();

      return 0;
    }

The builder.ui file looks like this:

            <interface>
      <object id="window" class="GtkWindow">
        <property name="visible">True</property>
        <property name="title">Grid</property>
        <property name="border-width">10</property>
        <child>
          <object id="grid" class="GtkGrid">
            <property name="visible">True</property>
            <child>
              <object id="button1" class="GtkButton">
                <property name="visible">True</property>
                <property name="label">Button 1</property>
              </object>
              <packing>
                <property name="left-attach">0</property>
                <property name="top-attach">0</property>
              </packing>
            </child>
            <child>
              <object id="button2" class="GtkButton">
                <property name="visible">True</property>
                <property name="label">Button 2</property>
              </object>
              <packing>
                <property name="left-attach">1</property>
                <property name="top-attach">0</property>
              </packing>
            </child>
            <child>
              <object id="quit" class="GtkButton">
                <property name="visible">True</property>
                <property name="label">Quit</property>
              </object>
              <packing>
                <property name="left-attach">0</property>
                <property name="top-attach">1</property>
                <property name="width">2</property>
              </packing>
            </child>
          </object>
          <packing>
          </packing>
        </child>
      </object>
    </interface>

Note that GtkBuilder can also be used to construct objects that are not widgets, such as tree models, adjustments, etc. That is the reason the method we use here is called `gtk_builder_get_object()` and returns a GObject* instead of a GtkWidget*.

Normally, you would pass a full path to `gtk_builder_add_from_file()` to make the execution of your program independent of the current directory. A common location to install UI descriptions and similar data is `/usr/share/`appname``.

It is also possible to embed the UI description in the source code as a string and use `gtk_builder_add_from_string()` to load it. But keeping the UI description in a separate file has several advantages: It is then possible to make minor adjustments to the UI without recompiling your program, and, more importantly, graphical UI editors such as glade can load the file and allow you to create and modify your UI by point-and-click.