Overview of the drawing model

Applications that use a windowing system generally create rectangular regions in the screen called surfaces (GTK is following the Wayland terminology, other windowing systems such as X11 may call these windows). Traditional windowing systems do not automatically save the graphical content of surfaces, and instead ask applications to provide new content whenever it is needed. For example, if a window that is stacked below other windows gets raised to the top, then the application has to repaint it, so the previously obscured area can be shown. When the windowing system asks an application to redraw a window, it sends a frame event (expose event in X11 terminology) for that window.

Each GTK toplevel window or dialog is associated with a windowing system surface. Child widgets such as buttons or entries don’t have their own surface; they use the surface of their toplevel.

Generally, the drawing cycle begins when GTK receives a frame event from the underlying windowing system: if the user drags a window over another one, the windowing system will tell the underlying surface that it needs to repaint itself. The drawing cycle can also be initiated when a widget itself decides that it needs to update its display. For example, when the user types a character in an entry widget, the entry asks GTK to queue a redraw operation for itself.

The windowing system generates frame events for surfaces. The GDK interface to the windowing system translates such events into emissions of the ::render signal on the affected surfaces. The GTK toplevel window connects to that signal, and reacts appropriately.

The following sections describe how GTK decides which widgets need to be repainted in response to such events, and how widgets work internally in terms of the resources they use from the windowing system.