public static interface Widget.Draw

The signal emitted when a portion or all of the Widget has been exposed and needs [re]drawing. This can happen when a Widget is first realized to the screen or when part of it has come back from being obscured (by another Window or because it was offscreen).

GNOME uses the excellent Cairo 2D graphics library to draw its user interfaces, which we make available in java-gnome in package org.freedesktop.cairo.

Code that does drawing needs to be written a little differently than code which just builds Widgets up into user interfaces. While we are accustomed to doing setting up various Widgets and packing them into Windows in our constructors, the one thing you cannot easily do there is graphics drawing. In order to be able to construct the Context used for drawing operations, Cairo needs the details of the [org.gnome.gdk] Display, Screen and Window it will be drawing to, and these are not available until the Widget has been realized and mapped. The Widget.Draw signal is emitted exactly at this point, and so that's when we have the environment we need to do our drawing.

To do drawing with Cairo you need a Context, and GTK 3 conveniently provides you with one all ready to go:

 foo.connect(new Widget.Draw() {
     public boolean onDraw(Widget source, Context cr) {
        // start drawing
     }
 }
 

GTK makes calls to Context's save() and restore() around the Widget.Draw signal so you don't worry about having to reset the Context to its initial state.