Class drawing-area - cl-cffi-gtk4 API documentation

Package: gtk

Class gtk:drawing-area

Superclasses

gtk:widget, gobject:initially-unowned, gtk:accessible, gtk:buildable, gtk:constraint-target, gobject:object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

None

Direct Slots

content-height

The content-height property of type :int (Read / Write)
The content height.
Allowed values: >= 0
Default value: 0

content-width

The content-width property of type :int (Read / Write)
The content width.
Allowed values: >= 0
Default value: 0

Details

The gtk:drawing-area widget is a widget that allows drawing with Cairo. It is essentially a blank widget. You can draw on it.

Figure: GtkDrawingArea

After creating a drawing area, the application may want to connect to:

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 "resize" signal to take any necessary actions when the widget changes size.
Call the gtk:drawing-area-set-draw-func function to handle redrawing the contents of the widget.

The draw function is normally called when a drawing area first comes onscreen, or when it is 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 the gtk:widget-queue-draw function. This will cause the drawing area to call the draw function again.

The available routines for drawing are documented in the Cairo documentation. GDK offers additional API to integrate with Cairo, like the gdk:cairo-set-source-rgba or gdk:cairo-set-source-pixbuf functions.

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.

Examples

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

(defun do-drawing-area (&optional application)
  (let* ((area (make-instance 'gtk:drawing-area))
         (window (make-instance 'gtk:window
                                :application application
                                :child area
                                :title "Drawing Area"
                                :default-width 400
                                :default-height 300)))
    ;; Set a drawing function
    (gtk:drawing-area-set-draw-func area
        (lambda (widget cr width height)
          (let ((color (gtk:widget-color widget)))
            (gdk:cairo-set-source-rgba cr color)
            ;; Draw and fill a circle on the drawing area
            (cairo:arc cr
                       (/ width 2.0)
                       (/ height 2.0)
                       (- (/ (min width height) 2.0) 12)
                       0.0
                       (* 2.0 pi))
            (cairo:fill cr))))
    ;; Show the window
    (setf (gtk:widget-visible window) t)))

Signal Details

The "resize" signal

lambda (area width height)    :run-last

area: The gtk:drawing-area widget that emitted the signal.
width: The integer for the width of the viewport.
height: The integer for the height of the viewport.

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

Returned by

gtk:drawing-area-new

Slot Access Functions

gtk:drawing-area-content-height

gtk:drawing-area-content-width

Inherited Slot Access Functions

2025-07-24