Description

Gnome::Gtk4::DrawingArea is a widget that allows drawing with cairo.

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

• The realize defined in Widget signal to take any necessary actions when the widget is instantiated on a particular display. (Create GDK resources in response to this signal.)

• The resize signal to take any necessary actions when the widget changes size.

• Call .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.

Simple GtkDrawingArea usage

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 .queue-draw() in class Gnome::Gtk4::Widget. This will cause the drawing area to call the draw function again.

The available routines for drawing are documented in the [Cairo documentation](https://www.cairographics.org/manual/); GDK offers additional API to integrate with Cairo, like .cairo-set-source-rgba() in package Gnome::Gdk or .cairo-set-source-pixbuf() in package Gnome::Gdk.

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 Gnome::Gtk4::Widget subclass.

Class initialization

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

new-drawingarea

Creates a new drawing area.

method new-drawingarea ( --> Gnome::Gtk4::DrawingArea \)

Methods

get-content-height

Retrieves the content height of the Gnome::Gtk4::DrawingArea.

method get-content-height (--> Int )

Return value; The height requested for content of the drawing area.

get-content-width

Retrieves the content width of the Gnome::Gtk4::DrawingArea.

method get-content-width (--> Int )

Return value; The width requested for content of the drawing area.

set-content-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 .set-valign() in class Gnome::Gtk4::Widget to avoid that.

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

method set-content-height ( Int() $height )

• $height; the height of contents.

set-content-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 .set-halign() in class Gnome::Gtk4::Widget to avoid that.

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

method set-content-width ( Int() $width )

• $width; the width of contents.

set-draw-func This function is not yet available

Setting a draw function is the main thing you want to do when using a drawing area.

The draw function 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 .queue-draw() in class Gnome::Gtk4::Widget on the drawing area. This will cause a redraw and will call $draw-func again.

method set-draw-func ( &draw-func, gpointer $user-data, … )

• &draw-func; callback that lets you draw the drawing area's contents. Tthe function must be specified with following signature; :( N-Object $drawing-area, N-Object $cr, gint $width, gint $height, gpointer $user-data ).

• $user-data; user data passed to $draw-func.

• destroy; destroy notifier for $user-data. Note that each argument must be specified as a type followed by its value!

Signals

resize

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.

method handler (
  gint $width,
  gint $height,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::DrawingArea :$_widget,
  *C<user>-options
)

• $width; the width of the viewport.

• $height; the height of the viewport.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::DrawingArea object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.