GtkDrawingArea: GTK+ 4 Reference Manual

## GtkDrawingArea GtkDrawingArea — A simple widget for custom user interface elements |

## Functions

GtkWidget * | gtk_drawing_area_new ()
int | gtk_drawing_area_get_content_width ()
void | gtk_drawing_area_set_content_width ()
int | gtk_drawing_area_get_content_height ()
void | gtk_drawing_area_set_content_height ()
void | (*GtkDrawingAreaDrawFunc) ()
void | gtk_drawing_area_set_draw_func ()

## Types and Values

struct | GtkDrawingArea

## Includes

    #include <gtk/gtk.h>

## Description

The GtkDrawingArea widget is used for creating custom user interface elements. It’s essentially a blank widget; you can draw on it. After creating a drawing area, the application may want to connect to:

- Mouse and button press signals to respond to input from the user.

- The “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 “size-allocate” signal to take any necessary actions when the widget changes size.

- Call `gtk_drawing_area_set_draw_func()` 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.

Note that GDK automatically clears the exposed area before causing a redraw, and that drawing is implicitly clipped to the exposed area.

#### Simple GtkDrawingArea usage

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    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,
                                   gtk_style_context_get_state (context),
                                   &color);
      gdk_cairo_set_source_rgba (cr, &color);

      cairo_fill (cr);
    }
    [...]
      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);

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_region()`, `gtk_widget_queue_draw_area()` or `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 enable them with `gtk_widget_add_events()`. 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. Use `gtk_widget_has_focus()` in your expose event handler to decide whether to draw the focus indicator. See `gtk_render_focus()` for one way to draw focus.

If you need more complex control over your widget, you should consider creating your own GtkWidget subclass.

## Functions

### gtk_drawing_area_new ()

    GtkWidget *
    gtk_drawing_area_new (void);

Creates a new drawing area.

#### Returns

a new GtkDrawingArea

### 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()`.

#### Parameters

self | a GtkDrawingArea |

#### Returns

The width requested for content of the drawing area

Since: 3.90

### 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.

#### Parameters

self | a GtkDrawingArea |
width | the width of contents |

Since: 3.90

### 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()`.

#### Parameters

self | a GtkDrawingArea |

#### Returns

The height requested for content of the drawing area

Since: 3.90

### 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.

#### Parameters

self | a GtkDrawingArea |
height | the height of contents |

Since: 3.90

### 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.

#### Parameters

drawing_area | the GtkDrawingArea to redraw |
cr | the context to draw to |
width | the actual width of the contents. This value will be at least as wide as GtkDrawingArea:width. |
height | the actual height of the contents. This value will be at least as wide as GtkDrawingArea:height. |
user_data | user data. | [closure]

Since: 3.90

### 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 call a redraw and will call `draw_func` again.

#### Parameters

self | a GtkDrawingArea |
draw_func | callback that lets you draw the drawing area's contents. | [closure user_data][allow-none]
user_data | user data passed to `draw_func` |
destroy | destroy notifier for `user_data` |

Since: 3.90

## Types and Values

### struct GtkDrawingArea

    struct GtkDrawingArea {
      GtkWidget widget;
    };

## See Also

GtkImage