![]() |
![]() |
![]() |
GTK+ 3 Reference Manual | ![]() |
---|
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.
To begin our introduction to GTK, we'll start with the simplest program possible. This program will create an empty 200x200 pixel window:
FIXME: MISSING XINCLUDE CONTENT
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`
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.
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:
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.
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
FIXME: MISSING XINCLUDE CONTENTThe builder.ui file looks like this:
FIXME: MISSING XINCLUDE CONTENT
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.