1 2@c %start of fragment 3 4@node GtkDrawingArea 5@chapter GtkDrawingArea 6A widget for custom user interface elements 7 8@section Overview 9The @code{<gtk-drawing-area>} widget is used for creating custom user interface 10elements. It's essentially a blank widget; you can draw on 11@samp{widget->window}. After creating a drawing area, the application may want 12to connect to: 13 14Mouse and button press signals to respond to input from the user. (Use 15@code{gtk-widget-add-events} to enable events you wish to receive.) 16 17The "realize" signal to take any necessary actions when the widget is 18instantiated on a particular display. (Create GDK resources in response to this 19signal.) 20 21The "configure_event" signal to take any necessary actions when the widget 22changes size. 23 24The "expose_event" signal to handle redrawing the contents of the widget. 25 26The following code portion demonstrates using a drawing area to display a circle 27in the normal widget foreground color. Note that GDK automatically clears the 28exposed area to the background color before sending the expose event, and that 29drawing is implicitly clipped to the exposed area. 30 31@example 32 33gboolean 34expose_event_callback (GtkWidget *widget, GdkEventExpose *event, gpointer data) 35@{ 36 gdk_draw_arc (widget->window, 37 widget->style->fg_gc[GTK_WIDGET_STATE (widget)], 38 TRUE, 39 0, 0, widget->allocation.width, widget->allocation.height, 40 0, 64 * 360); 41 42 return TRUE; 43@} 44[...] 45 GtkWidget *drawing_area = gtk_drawing_area_new (); 46 gtk_widget_set_size_request (drawing_area, 100, 100); 47 g_signal_connect (G_OBJECT (drawing_area), "expose_event", 48 G_CALLBACK (expose_event_callback), NULL); 49@end example 50 51Expose events are normally delivered when a drawing area first comes onscreen, 52or when it's covered by another window and then uncovered (exposed). You can 53also force an expose event by adding to the "damage region" of the drawing 54area's window; @code{gtk-widget-queue-draw-area} and 55@code{gdk-window-invalidate-rect} are equally good ways to do this. You'll then 56get an expose event for the invalid region. 57 58The available routines for drawing are documented on the GDK Drawing Primitives 59page. See also @code{gdk-pixbuf-render-to-drawable} for drawing a 60@code{<gdk-pixbuf>}. 61 62To receive mouse events on a drawing area, you will need to enable them with 63@code{gtk-widget-add-events}. To receive keyboard events, you will need to set 64the @code{<gtk-can-focus>} flag on the drawing area, and should probably draw 65some user-visible indication that the drawing area is focused. Use the 66@code{gtk-has-focus} macro in your expose event handler to decide whether to 67draw the focus indicator. See @code{gtk-paint-focus} for one way to draw focus. 68 69@section Usage 70@include defuns-gtkdrawingarea.xml.texi 71 72@c %end of fragment 73