![]() |
![]() |
![]() |
![]() |
GTK+ is a widget toolkit. Each user interface created by GTK+ consists of widgets. This is implemented in C using GObject, an object-oriented framework for C. Widgets are organized in a hierachy. The window widget is the main container. The user interface is then built by adding buttons, drop-down menus, input fields, and other widgets to the window. If you are creating complex user interfaces it is recommended to use GtkBuilder and its GTK-specific markup description language, instead of assembling the interface manually. You can also use a visual user interface editor, like Glade.
GTK+ is event-driven. The toolkit listens for events such as a click on a button, and passes the event to your application.
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.
To begin our introduction to GTK, we'll start with a simple signal-based Gtk application. 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> static void activate (GtkApplication* app, gpointer user_data) { GtkWidget *window; window = gtk_application_window_new (app); gtk_window_set_title (GTK_WINDOW (window), "Window"); gtk_window_set_default_size (GTK_WINDOW (window), 200, 200); gtk_widget_show_all (window); } int main (int argc, char **argv) { GtkApplication *app; int status; app = gtk_application_new ("org.gtk.example", G_APPLICATION_FLAGS_NONE); g_signal_connect (app, "activate", G_CALLBACK (activate), NULL); status = g_application_run (G_APPLICATION (app), argc, argv); g_object_unref (app); return status; }
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.
In a GTK+ application, the purpose of the main()
function is to
create a GtkApplication object and run it. In this example a
GtkApplication pointer named app
is called and then
initialized using gtk_application_new()
.
When creating a GtkApplication
you need to pick an application identifier (a name)
and input to gtk_application_new()
as parameter.
For this example org.gtk.example
is used
but for choosing an identifier for your application see
this guide.
Lastly gtk_application_new()
takes a GApplicationFlags as input for your
application, if your application would have special needs.
Next the
activate signal
is connected to the activate()
function above the main()
functions.
The activate
signal will be sent
when your application is launched with
g_application_run()
on the line below.
The gtk_application_run()
also 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.
Within g_application_run the activate()
signal is sent and
we then proceed into the activate
() function of the
application. Inside the activate()
function we want to construct
our GTK window, so that a window is shown when the application
is launched. The call to gtk_application_window_new()
will
createa a new GtkWindow and store it inside the
window
pointer. The window will have a frame,
a title bar, and window controls depending on the platform.
A window title is set using gtk_window_set_title()
. This function
takes a GtkWindow* pointer and a string as input. As our
window
pointer is a GtkWidget pointer, we need to cast it
to GtkWindow*.
But instead of casting window
via
(GtkWindow*)
,
window
can be cast using the macro
.
GTK_WINDOW()
will check if the
pointer is an instance of the GtkWindow class, before casting, and emit a
warning if the check fails. More information about this convention
can be found
here.GTK_WINDOW()
Finally the window size is set using gtk_window_set_default_size and
the window is then shown by GTK via gtk_widget_show_all()
.
When you exit the window, by for example pressing the X,
the g_application_run()
in the main loop returns with a number
which is saved inside an integer named "status". Afterwards, the
GtkApplication object is freed from memory with g_object_unref()
.
Finally the status integer is returned and the GTK application exits.
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`