GtkDrawingArea

Simple GtkDrawingArea usage

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

  context = gtk_widget_get_style_context (GTK_WIDGET (area));

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

  gtk_style_context_get_color (context,
                               &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_queue_draw(). This will cause the drawing area to call the draw function again.

The available routines for drawing are documented on the GDK Drawing Primitives page and the cairo documentation.

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 GtkWidget subclass.

gtk_drawing_area_new ()

GtkWidget *
gtk_drawing_area_new (void);

Creates a new drawing area.

gtk_drawing_area_get_content_width ()

int
gtk_drawing_area_get_content_width (GtkDrawingArea *self);

Retrieves the value previously set via gtk_drawing_area_set_content_width().

gtk_drawing_area_set_content_width ()

void
gtk_drawing_area_set_content_width (GtkDrawingArea *self,
                                    int width);

Sets the desired width of the contents of the drawing area. Note that because widgets may be allocated larger sizes than they requested, it is possible that the actual width passed to your draw function is larger than the width set here. You can use gtk_widget_set_halign() to avoid that.

If the width is set to 0 (the default), the drawing area may disappear.

gtk_drawing_area_get_content_height ()

int
gtk_drawing_area_get_content_height (GtkDrawingArea *self);

Retrieves the value previously set via gtk_drawing_area_set_content_height().

gtk_drawing_area_set_content_height ()

void
gtk_drawing_area_set_content_height (GtkDrawingArea *self,
                                     int height);

Sets the desired height of the contents of the drawing area. Note that because widgets may be allocated larger sizes than they requested, it is possible that the actual height passed to your draw function is larger than the height set here. You can use gtk_widget_set_valign() to avoid that.

If the height is set to 0 (the default), the drawing area may disappear.

GtkDrawingAreaDrawFunc ()

void
(*GtkDrawingAreaDrawFunc) (GtkDrawingArea *drawing_area,
                           cairo_t *cr,
                           int width,
                           int height,
                           gpointer user_data);

Whenever drawing_area needs to redraw, this function will be called.

This function should exclusively redraw the contents of the drawing area and must not call any widget functions that cause changes.

gtk_drawing_area_set_draw_func ()

void
gtk_drawing_area_set_draw_func (GtkDrawingArea *self,
                                GtkDrawingAreaDrawFunc draw_func,
                                gpointer user_data,
                                GDestroyNotify destroy);

Setting a draw function is the main thing you want to do when using a drawing area. It is called whenever GTK needs to draw the contents of the drawing area to the screen.

The draw function will be called during the drawing stage of GTK. In the drawing stage it is not allowed to change properties of any GTK widgets or call any functions that would cause any properties to be changed. You should restrict yourself exclusively to drawing your contents in the draw function.

If what you are drawing does change, call gtk_widget_queue_draw() on the drawing area. This will cause a redraw and will call draw_func again.

struct GtkDrawingArea

struct GtkDrawingArea;

The “content-height” property

  “content-height”           int

The content height. See gtk_drawing_area_set_content_height() for details.

Owner: GtkDrawingArea

Flags: Read / Write

Allowed values: >= 0

Default value: 0

The “content-width” property

  “content-width”            int

The content width. See gtk_drawing_area_set_content_width() for details.

Owner: GtkDrawingArea

Flags: Read / Write

Allowed values: >= 0

Default value: 0

The “resize” signal

void
user_function (GtkDrawingArea *area,
               int             width,
               int             height,
               gpointer        user_data)

The ::resize signal is emitted once when the widget is realized, and then each time the widget is changed while realized. This is useful in order to keep state up to date with the widget size, like for instance a backing surface.

Flags: Run Last