![]() |
![]() |
![]() |
![]() |
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 hierarchy. 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 very simple 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 (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 gtk4` -o example-0 example-0.c `pkg-config --libs gtk4`
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 declared
and then initialized using gtk_application_new().
When creating a GtkApplication, you need to pick an application
identifier (a name) and pass it to gtk_application_new() as parameter.
For this example org.gtk.example
is used. For
choosing an identifier for your application, see
this guide.
Lastly gtk_application_new() takes 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() function.
The activate
signal will be emitted when your application
is launched with g_application_run() on the line below. The g_application_run()
call also takes as arguments the command line arguments (the
argc
count and the argv
string array).
Your application can override the command line handling, e.g. to open
files passed on the commandline.
Within g_application_run() the activate signal is sent and we then
proceed into the activate() function of the application. This is where we
construct our GTK window, so that a window is shown when the application
is launched. The call to gtk_application_window_new() will create 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()
. 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.
Finally the window size is set using gtk_window_set_default_size() and the window is then shown by GTK via gtk_widget_show().
When you close the window, by for example pressing the X, the
g_application_run() call returns with a number which is saved inside
an integer variable named status
. Afterwards, the
GtkApplication object is freed from memory with g_object_unref().
Finally the status integer is returned and the 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.