gtk.drawing_area

[gtk.drawing_area.DrawingArea] is a widget that allows drawing with cairo.

!An example GtkDrawingArea

It’s essentially a blank widget; you can draw on it. After creating a drawing area, the application may want to connect to:

• The [gtk.widget.Widget.realize] signal to take any necessary actions

when the widget is instantiated on a particular display. (Create GDK resources in response to this signal.)

• The [gtk.drawing_area.DrawingArea.resize] signal to take any necessary

actions when the widget changes size.

• Call [gtk.drawing_area.DrawingArea.setDrawFunc] to handle redrawing the

contents of the widget.

The following code portion demonstrates using a drawing area to display a circle in the normal widget foreground color.

Simple GtkDrawingArea usage

static void
draw_function (GtkDrawingArea *area,
              cairo_t        *cr,
              int             width,
              int             height,
              gpointer        data)
{
 GdkRGBA color;

 cairo_arc (cr,
            width / 2.0, height / 2.0,
            MIN (width, height) / 2.0,
            0, 2 * G_PI);

 gtk_widget_get_color (GTK_WIDGET (area),
                       &color);
 gdk_cairo_set_source_rgba (cr, &color);

 cairo_fill (cr);
}

int
main (int argc, char **argv)
{
 gtk_init ();

 GtkWidget *area = gtk_drawing_area_new ();
 gtk_drawing_area_set_content_width (GTK_DRAWING_AREA (area), 100);
 gtk_drawing_area_set_content_height (GTK_DRAWING_AREA (area), 100);
 gtk_drawing_area_set_draw_func (GTK_DRAWING_AREA (area),
                                 draw_function,
                                 NULL, NULL);
 return 0;
}

The draw function is normally called when a drawing area first comes onscreen, or when it’s covered by another window and then uncovered. You can also force a redraw by adding to the “damage region” of the drawing area’s window using [gtk.widget.Widget.queueDraw]. This will cause the drawing area to call the draw function again.

The available routines for drawing are documented in the

offers additional API to integrate with Cairo, like func@Gdk.cairo_set_source_rgba or func@Gdk.cairo_set_source_pixbuf.

To receive mouse events on a drawing area, you will need to use event controllers. To receive keyboard events, you will need to set the “can-focus” property on the drawing area, and you should probably draw some user-visible indication that the drawing area is focused.

If you need more complex control over your widget, you should consider creating your own [gtk.widget.Widget] subclass.

Fluent builder for [gtk.drawing_area.DrawingArea]