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

None

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 "GtkWidget::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 "GtkDrawingArea::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. 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)))    

The "resize" signal

lambda (area width height)    :run-last      

area

The gtk:drawing-area widget that emitted the signal.

width

An integer with the width of the viewport.

height

An integer with 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.