Container secrets

I recently spent some time tracking down a problem with GTK+ containers and drawing. Here is what I found out.

CSS drawing

In GTK+ 3.22, most, if not all, containers support the full CSS drawing model with multiple layers of backgrounds and borders. This is how, for example, GtkFrame draws its frame nowadays. But also containers that normally only arrange their children, such as GtkBox, can draw backgrounds and borders. The possibilities are endless!

For example, we can use a GtkBox to put a frame around a list box and a label, to make the label visually appear as part of the list. You can even make it colorful and fun, using some CSS like:

box.frame {
 border: 5px solid magenta;

Allocation and resizing

Traditionally, most containers in GTK+ are not doing any drawing of their own and just arrange their children, and thus there is no real need for them to do a full redraw when their size changes – it is enough to redraw the children. This is what gtk_container_set_reallocate_redraws() is about. And it defaults to FALSE in GTK+ 3, since we did not want to risk adding excessive redraws  whenever allocations change.

You can see where this is going: If I use the delete button to remove Butter and Salt from the list of ingredients, the allocation of the list, and thus of the box around it, will shrink, and we get a redraw problem.

The solution

If you plan to make plain layout containers draw backgrounds or borders, make sure to set reallocate-redraws to TRUE for the right widgets (in this case, the parent of the fun box).

gtk_container_reallocate_redraws (GTK_CONTAINER (parent), TRUE);

Note that gtk_container_reallocate_redraws() is deprecated in GTK+ 3.22, since we will get rid of it in GTK+ 4 and do the right thing automatically. But that shouldn’t stop you from using it to fix this issue.

Another (and maybe better) alternative is to use a container that is meant to draw a border, such as GtkFrame.

Logging and more

A while ago, GLib gained a new facility for ‘structured logging’. At the same time, it also gained support for writing logs to the systemd journal. Clearly, logging in GLib got a bit more complicated, and it can be a bit confusing.

This article is an attempt to clarify things.

Structured or not

The traditional GLib logging facilities are the g_message(), g_debug(), etc macros, which eventually call the g_log() function, which then uses the log handler that has been set with g_log_set_handler() to do the actual writing. You can put any information you like into your logs, but it has to all be formatted as a single string, the message.

g_debug ("You have %d eggs", 12 + 2);

g_log (G_LOG_DOMAIN,
       "You have %d eggs", 12 + 2);

With the new structured logging facilities, you call g_log_structured(), which then uses a log writer function to do the writing. So far, this is very similar to the older logging facility. The advantage of structured logs is that you can put multiple fields into the log without resorting to formatting it all into a string. Instead, you pass an array of log fields, which are key-value pairs.

g_log_structured (G_LOG_DOMAIN,
                  "CODE_FILE", "mysource.c",
                  "CODE_LINE", 312,
                  "MESSSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e",
                  "MESSAGE", "You have %d eggs", 12 + 2);

CODE_FILE, CODE_LINE and MESSAGE_ID here are just examples for “standard” fields. You can also invent your own fields. Note that you can still use printf-style formatting for the MESSAGE field.

So GLib has two separate logging facilities now. To make matters a bit more interesting, we allow you to redirect the g_message(), g_debug(), etc wrapper macros to use g_log_structured() instead of g_log() under the covers. To do so, define the G_LOG_USE_STRUCTURED macro before including glib.h.

Why is this useful? For one thing, it saves you the trouble of replacing all your g_debug() and still lets you take some advantage of the structured logging – when used in this fashion, the traditional macros use separate fields for the log domain, the code file and line and some other fields, which can be helpful for filtering and searching in the resulting logs, in particular with the systemd journal.

Another advantage is that you can use a single backend, the log writer function, to control where both old and new logging calls end up.

Where have all my logs gone ?

Structured logging is frequently associated with the systemd journal. So, it is not surprising that people expect the g_log_structured() output to go the journal. And that is a really useful thing for services, or when you are launching an application e.g. from a desktop icon. But if you run it from the terminal, you probably expect to see its output right there.

To satisfy these competing demands, the GLib default log writer function tries to be smart. If it detects that stderr is redirected to the journald socket, then it writes its structured output to the journal. Otherwise, it formats a message and writes it to stderr.

Both GNOME Shell and DBus arrange for stderr to be redirected to the journal when they start apps or services. A way to explicitly redirect stderr to the journal is to run your application under systemd-cat:

systemd-cat my-app-that-logs

If you are sure that you want your logs to always go to the journal, you can tell GLib to use a log writer that does that:

g_log_set_writer_func (g_log_writer_journald, NULL, NULL)

Beyond the default

Even though the log writer functions that GLib provides by default should serve many needs, you might need to write your own. In that case, GLib has a number of useful functions that can help you, such as g_log_writer_format_fields(), g_log_writer_is_journald() or g_log_writer_supports_color().

Happy logging!


First steps with GSettings

We sometimes get questions about GSettings in #gtk+, and whether it is a good idea to use this API for ‘simple’ cases. The answer is a very clear Yes, in my opinion, and this article is trying to explain why.


One of the nice things about GSettings is that it is a high-level API with backends for various native configuration systems. So, if you ever get around to porting your application to OS X or Windows, your application will automatically use the expected platform API to store its settings (the registry on Windows, and plists on OS X).

And even if your application will never be ported to those platforms, the dconf backend that is used on Linux has powerful features such as profiles and locks that let system administrators configure your application without you having to worry about it.

The documentation for GSettings unfortunately makes it appear more complicated than it is, since it doesn’t really try to hide the powerful features that are available to you (profiles, vendor overrides, translated defaults, complex types, bindings, etc).

So, here is a guide to first steps with GSettings, in a simple case.

Getting started

Lets get started with the simplest possible setting: a boolean.

The biggest hurdle to overcome is that GSettings insists on having a schema, which defines the datatype and default value for each key.

  <schema path="/org/gnome/recipes/"       
    <key type="b" name="use-metric">
      <summary>Prefer metric units</summary>
        This key determines whether values
        such as temperatures or weights will
        be displayed in metric units.

Schemas need to be installed (the advantage of this is that tools such as dconf-editor can use the schema information). If you are using autotools, this is supported with macros. Just add


to your, and

gsettings_SCHEMAS = org.gnome.Recipes.gschema.xml

to The setup with meson is similar.

Now that we’ve defined our key, we can obtain its value like this:

s = g_settings_new ("org.gnome.Recipes");
if (g_settings_get_boolean (s, "use-metric"))
  g_print ("Using metric units");

and we can set it like this:

s = g_settings_new ("org.gnome.Recipes");g_settings_set_boolean (s, "use-metric", TRUE);

Using GSettings for other basic types such as integers, floating point numbers, strings, etc. is very similar. Just use the appropriate getters and setters.

You may be wondering about the settings objects that we are creating here. It is fine to just create these whenever you need them. You can also create a global singleton if you prefer, but there is not real need to do so unless you want to monitor the setting for changes.

Next Steps: complex types

Beyond basic types, you have the full power of the GVariant type system available to store complex types. For example, if you need to store information about a circle in the plane, you could store it as a triple of type (ddd) storing the x, y coordinates of the center and the radius.

To handle settings with complex types in your code, use g_settings_get() and g_settings_set(), which return and accept the value in the form of a GVariant.

Next Steps: relocatable schemas

If your application uses accounts, you may want to look at relocatable schemas. A relocatable schema is what you need when you need multiple instances of the same configuration, stored separately. A typical example for this is accounts: your application allows to create more than one, and each of them has the same kind of configuration information associated with it.

GSettings handles this by omitting the path in the schema:

  <schema id="org.gnome.Recipes.User">
    <key type="b" name="use-metric">

Instead, we need to specify a path when we create the GSettings object:

s = g_settings_new_with_path ("org.gnome.Recipes.User",
if (g_settings_get_boolean (s, "use-metric"))
  g_print ("User mclasen is using metric units");

It is up to you to come up with a schema to map your accounts to unique paths.

Stumbling blocks

There are a few things to be aware of when using GSettings. One is that GLib needs to be able to find the compiled schema at runtime. This can be an issue when running your application out of the build directory without installing it. To handle this situation, you can set the GSETTINGS_SCHEMA_DIR environment variable to tell GLib where to find the compiled schema:

GSETTINGS_SCHEMA_DIR=build/data ./build/src/gnome-recipes

Another stumbling block is that GSettings reads the default values in the XML in the form of a serialized GVariant. This can be a bit surprising for the common case of a string, since it means that we need to put quotes around the string:


But these are minor issues, and easily avoided once you know about them.

Drag-and-drop in lists

I’ve recently had an occasion to implement reordering of a GtkListBox via drag-and-drop (DND). It was not that complicated. Since I haven’t seen drag-and-drop used much with list boxes, here is a quick summary of what is needed to get the basics working.

Setting up the drag source

There are two ways to make a GTK+ widget a drag source (i.e. a place where clicking and dragging will initiate a DND operation). You can decide dynamically to initiate a drag by calling gtk_drag_begin(). But we go for the simpler approach here: we just declare statically that our list rows should be drag sources, and let GTK+ handle all the details:

handle = gtk_event_box_new ();
gtk_container_add (GTK_CONTAINER (handle),
        gtk_image_new_from_icon_name ("open-menu-symbolic", 1));
gtk_drag_source_set (handle,
        GDK_BUTTON1_MASK, entries, 1, GDK_ACTION_MOVE);

Note that I choose to create a visible drag handle here instead of allowing drags to start anywhere on the row. It looks like this:

The entries tell GTK+ what data we want to offer via drags from this source. In our case, we will not offer a standard mime type like text/plain, but instead make up our own, private type, and also hint GTK+ that we don’t want to support drags to other applications:

static GtkTargetEntry entries[] = {

A little gotcha here is that the widget you set up as drag source must have a GdkWindow. A GtkButton or a GtkEventBox (as in this example) will work. GTK4 will offer a different API to create drag sources that avoids the need for a window.

With this code in place, you can already drag your rows, but so far, there’s nowhere to drop them. Lets fix that.

Accepting drops

In contrast to drags, where we created a visible drag handle to give users a hint that drag-and-drop is supported, we want to just accept drops anywhere in the list. The easiest way to do that is to just make each row a drop target (i.e. a place that will potentially accept drops).

gtk_drag_dest_set (row,

The entries are the same that we discussed above. GTK_DEST_DEFAULT_ALL tells GTK+ to handle all aspects of the DND operation for us, so we can keep this example simple.

Now we can start a drag on the handle, and we can drop it on some other row. But nothing happens after that. We need to do a little bit of extra work to make the reordering happen. Lets do that next.

Transferring the data

Drag-and-drop is often used to transfer data between applications. GTK+ uses a data holder object called GtkSelectionData for this. To send and receive data, we need to connect to signals on both the source and the target side:

g_signal_connect (handle, "drag-data-get",
        G_CALLBACK (drag_data_get), NULL);
g_signal_connect (row, "drag-data-received",
        G_CALLBACK (drag_data_received), NULL);

On the source side, the drag-data-get signal is emitted when GTK+ needs the data to send it to the drop target. In our case, the function will just put a pointer to the source widget in the selection data:

gtk_selection_data_set (selection_data,
        gdk_atom_intern_static_string ("GTK_LIST_BOX_ROW"),
        (const guchar *)&widget,
        sizeof (gpointer));

On the target side, drag-data-received is emitted on the drop target when GTK+ passes the data it received on to the application. In our case, we will pull the pointer out of the selection data, and reorder the row.

handle = *(gpointer*)gtk_selection_data_get_data (selection_data);
source = gtk_widget_get_ancestor (handle, GTK_TYPE_LIST_BOX_ROW);

if (source == target)

source_list = gtk_widget_get_parent (source);
target_list = gtk_widget_get_parent (target);
position = gtk_list_box_row_get_index (GTK_LIST_BOX_ROW (target));

g_object_ref (source);
gtk_container_remove (GTK_CONTAINER (source_list), source);
gtk_list_box_insert (GTK_LIST_BOX (target_list), source, position);
g_object_unref (source);

The only trick here is that we need to take a reference on the widget before removing it from its parent container, to prevent it from getting finalized.

And with this, we have reorderable rows. Yay!

As a final step, lets make it look good.

A nice drag icon

So far, during the drag, you just see just the cursor, which is not very helpful and not very pretty. The expected behavior is to drag a visual representation of the row.

To make that happen, we connect to the drag-begin signal on the drag source:

g_signal_connect (handle, "drag-begin",
        G_CALLBACK (drag_begin), NULL);

…and do some extra work to create a nice ‘drag icon’:

row = gtk_widget_get_ancestor (widget, GTK_TYPE_LIST_BOX_ROW);
gtk_widget_get_allocation (row, &alloc);
surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
                                      alloc.width, alloc.height);
cr = cairo_create (surface);
gtk_widget_draw (row, cr);

gtk_drag_set_icon_surface (context, surface);

cairo_destroy (cr);
cairo_surface_destroy (surface);

This looks more complicated than it is – we are creating a cairo surface of the right size, render the row widget to it (the signal is emitted on the handle, so we have to find the row as an ancestor).

Unfortunately, this does not yet yield a perfect result, since list box rows generally don’t render a background or frame. To work around that, we can temporarily add a custom style class to the row’s style context, and use some custom CSS to ensure we get a background and frame:

context = gtk_widget_get_style_context (row);
gtk_style_context_add_class (context, "drag-icon");
gtk_widget_draw (row, cr);
gtk_style_context_remove_class (context, "drag-icon")

As an extra refinement, we can set an offset on the surface, to prevent a visual ‘jump’ at the beginning of the drag, by placing this code before the gtk_drag_set_icon_surface() call:

gtk_widget_translate_coordinates (widget, row, 0, 0, &x, &y);
cairo_surface_set_device_offset (surface, -x, -y);


Next steps

This article just shows the simplest possible setup for row reordering by drag-and-drop. Many refinements are possible, some easy and some not so easy.

An obvious enhancement is to allow dragging between different lists in the same application. This is just a matter of being careful about the handling of the list widgets in the drag_data_received() call, and the code I have shown here should already work for this.

Another refinement would be to drop the row before or after the target row, depending on which edge is closer. Together with this, you probably want to modify the drop target highlighing to indicate the edge where the drop will happen. This could be done in different ways, but all of them will require listening to drag-motion events and juggling event coordinates, which is not something I wanted to get into here.

Finally, scrolling the list during the drag. This is important for long lists, if you want to drag a row from the top to bottom – if the list doesn’t scroll, you have to do this in page increments, which is just too cumbersome. Implementing this may be easiest by moving the drag target to be the list widget itself, instead of the individual rows.


This week in GTK+ – 23

In this last week, the master branch of GTK+ has seen 146 commits, with 10020 lines added and 16435 lines removed.

Planning and status
  • Benjamin Otte worked on clarifying the relationship between various coordinate systems used in GTK+ and in gsk.
  • Benjamin is also making changes throughout the tree in preparation for making all widgets window-less.
  • Emmanule Bassi is working on finer-grained gsk render nodes for CSS rendering.
  • The GTK+ road map is available on the wiki.
Notable changes
  • Benjamin Otte added a frame recorder to the GTK+ inspector. See this post for more information.
  • Timm Bäder and Benjamin converted more widgets to use indirect rendering with gsk render nodes.
  • Matthias Clasen made the GtkTextAttributes structure private, thereby enabling further cleanups and the removal of the deprecated GdkColor type.
  • Benjamin removed visuals.
Bugs fixed
  • 773885 pop down GtkPopover on pressing escape
  • 773299Ensure GTK+-4.x builds and works on Windows
  • 773274[Wayland] Crash under gdk_wayland_window_attach_image()
  • 768081Enable HiDPI support for GDK-Win32
  • 773857 – X11: Add support for gdk_window_fullscreen_on_monitor
  • 773799GtkLevelBar doesn’t update blocks on discrete mode
  • 773954gtkstylecontext: Clarify memory allocation behaviour of getters
  • 773903gtk.h and gtktextiter.h include private gtktextattributes.h
Getting involved

Interested in working on GTK+? Look at the list of bugs for newcomers and join the IRC channel #gtk+ on

This Week in GTK+ – 8

In this last week, the master branch of GTK+ has seen 23 commits, with 1154 lines added and 121 lines removed.

Planning and Status
  • Matthias continued to work on the portal branches of GLib and GTK+.
  • Emmanuele continued to make gsk render widgets on the gsk-renderer branch.
  • Philip Withnall is working on a patch series to make GLib support structured logging to the systemd journal here.
Notable Changes
  • Carlos Garnacho improved compatibility of Wayland clipboard handling with legacy X clients.
  • Matthias made it possible to hide the preview button in print dialogs.
  • Eric Koegel added support for the Xfce session manager to GtkApplication
  • Georges Basile Stavracas Neto added support for background-blend-mode to the GTK+ CSS machinery.
  • Over in GLib, Matthias added a new gio utility that combines the functionality of the various gvfs commandline tools into one.
Bugs fixed
  • Bug 767965Improve heuristics to detect remote filesystems
  • Bug 768184headerbar: don’t throw a warning if title widget is hidden
  • Bug 768082 – Copying from Wayland to NEdit doesn’t work
  • Bug 768177 CLIPBOARD target request after PRIMARY request times out
  • Bug 768142 Incorrect order of $(LIBS) and $(OBJS) in Makefile.example caused “undefined reference”
  • Bug 693203GtkApplication does not support Xfce session manager
  • Bug 768305Gtk+ should support background-blend-mode
Get Involved

Interested in working on GTK+? Look at the list of bugs for newcomers and join the IRC channel #gtk+ on

This Week in GTK+ – 7

In this last week, the master branch of GTK+ has seen 29 commits, with 4744 lines added and 4340 lines removed.

Planning and Status
  • GTK+ 3.21.3 was released
  • Matthias continued to work on the portal branches of GLib and GTK+.
  • William Hua is reworking the menu positioning API from bug 756579 following the hackfest discussion.
  • Emmanuele pushed a new revision of the gsk branch.
  • Carlos Soriano is working on a new pathbar implementation for the file chooser and nautilus.
Notable changes
  • Emmanuele fixed some fallout in firefox from the GdkDrawingContext introduction.
  • Ray Strode cleaned up some headerbar code and added support for expanding children
  • Matthias fixed a crash in GtkColorChooser and another one in GtkInspector
Bugs fixed
  • Bug 767851 – popover arrows broken in some orientations
  • Bug 767849 – crash in focus handling
  • Bug 724332 – GtkHeaderBar need to support an expand property
  • Bug 768025 – entry.warning & entry.error broken
Get Involved

Interested in working on GTK+? Look at the list of bugs for newcomers and join the IRC channel #gtk+ on

Cursors in GTK+


Cursors have traditionally been a big mess in Linux.

The X11 cursor font has been passed down to us from times immemorial, and given us gems such as gumby () or trek (). Unfortunately for us, this state of affairs was frozen into the GDK api with the GdkCursorType enumeration and the gdk_cursor_new() function.

Later on, the Xcursor library came around. It invented its own image format for storing cursors and brought us cursor themes, but didn’t do anything to answer the question “What cursors should my cursor theme provide ?”

Since there is no official list of recommended cursor names, cursor themes frequently provide all the variants of cursor names that have been spotted in the wild. As an example, here is the list of cursors included in the oxygen cursor theme. If you are wondering, the hex strings in this list are a clever trick of Xcursor to retrofit themed cursors underneath core X11 applications that use cursors from the cursor font mentioned above.

CSS to the rescue

About a year ago, we decided to finally improve the GTK+ cursor story. Thankfully, the CSS3 spec contains a decent list of cursor names that can be reasonably expected to be available across platforms.

Standard cursorsSince the GdkCursorType enumeration contains too much nonsense and is not easily extensible, we decided to make gdk_cursor_new_from_name() the recommended API for obtaining cursors. The documentation for this function now lists the CSS cursor names (follow the link above to see it), and the cursor handling code in the various GDK backends tries hard to give you meaningful cursors for all of these names.

On some platforms (such as X11 with a random cursor theme), we may have to fall back to the default arrow cursor if a certain cursor is not present in the theme. As part of this general overhaul of the cursor code, the Windows backend grew support for cursor themes.

GTK+ itself is now using gdk_cursor_new_from_name() exclusively, with the standard cursor names. And gtk3-demo includes a demo that shows all the standard cursors and lets you try them out. The screenshot above shows it.

The changes described here went into GTK+ 3.18, which was released about 9 months ago.

What you should do in your application

Most likely, you don’t have to do anything! GTK+ widgets use suitable cursors all by themselves, and you can benefit from that without any extra work.

If your application is creating its own cursors for whatever reason, you should check carefully if one of the standard cursors shown above is suitable for you. Using a standard cursor ensures that you will get a suitable cursor regardless of the platform your application is running on and regardless of the cursor theme the user has chosen.

Please use gdk_cursor_new_from_name() to generate your themed cursor, since this is now the preferred API for this task.