The GTK+ Drawing Kit Programming Manual <author>Shawn T. Amundson, Peter Mattis <date>July 26, 1998 <abstract> This document aims at teaching user how to effectively program in GDK, the GTK+ Drawing Kit, and to serve as a reference guide to more experienced GTK+ programmers. It is a work in progress.  <toc>   <sect>Introduction GDK is designed as a wrapper library that lies on top of Xlib. It performs many common and desired operations for a programmer instead of the programmer having to explicitly ask for such functionality from Xlib directly. For example, GDK provides a common interface to both regular and shared memory XImage types. By doing so, an application can nearly transparently use the fastest image type available. GDK also provides routines for determining the best available color depth and the best available visual which is not always the default visual for a screen. GDK is distributed and developed with GTK+, and is licensed under the GNU Library General Public Licence (LGPL). <sect>Getting Started <sect1>Initialization Initialization of GDK is easy. Simply call gdk_init() passing in the argc and argv parameters. <tscreen><verb> int main (int argc, char *argv[]) { /* Initialize GDK. */ gdk_init (&argc, &argv); /* Cleanup of GDK is done automatically when the program exits. */ return 0; } </verb></tscreen> Generally, GDK initialization is done by gtk_init() in GTK+. This means that when using GTK+, you do not need to directly call gdk_init(). <sect1>An Example using GDK with GTK+ This example demonstrates drawing a line using the foreground color of the GtkDrawArea widget it is drawn inside. The example will end when you click inside the window, which is filled by the GtkDrawingArea widget. The line is drawn during the expose event so that when the window drawing is done whenever it is needed. <tscreen><verb> #include <gtk/gtk.h> /* The expose callback does the drawing of the line */ int expose_callback (GtkWidget *widget, GdkEventExpose *event, gpointer data) { GdkGC *gc; printf("expose...\n"); /* The GC is the Graphics Context. Here it is borrowed from the widget */ gc = widget->style->fg_gc[GTK_STATE_NORMAL]; gdk_draw_line (widget->window, /* GDK Window of GtkDrawingArea widget */ gc, /* Graphics Context */ 0, /* x1, left */ 0, /* y1, top */ 200, /* x2, right */ 200); /* y2, bottom */ } /* This quits GTK+ */ void destroy (GtkWidget *widget, gpointer data) { gtk_main_quit (); } int main (int argc, char *argv[]) { GtkWidget *window; GtkWidget *darea; int events; /* This initializes both GTK+ and GDK */ gtk_init (&argc, &argv); /* Create a window */ window = gtk_window_new (GTK_WINDOW_TOPLEVEL); gtk_signal_connect (GTK_OBJECT (window), "destroy", GTK_SIGNAL_FUNC (destroy), NULL); /* Create a drawing area widget. This widget actually is just a simple widget which provides us an GDK window to draw on and takes care of all the toolkit integration, like providing the ability to add it to the window with gtk_contianer_add() */ darea = gtk_drawing_area_new (); gtk_container_add (GTK_CONTAINER (window), darea); /* Set the width and height (arguments are in that order) */ gtk_drawing_area_size (GTK_DRAWING_AREA (darea), 200, 200); /* Drawing in the expose event is important to keep the draw line always on the GDK window */ gtk_signal_connect (GTK_OBJECT (darea), "expose_event", GTK_SIGNAL_FUNC (expose_callback), NULL); /* We get the events, then add in button press. If we did not do this, we would not be notified of button press events in the GtkDrawingArea widget */ events = gtk_widget_get_events (darea); gtk_widget_set_events (darea, events | GDK_BUTTON_PRESS_MASK); /* If we click on the darea, the application will exit */ gtk_signal_connect_object (GTK_OBJECT (darea), "button_press_event", GTK_SIGNAL_FUNC (gtk_widget_destroy), GTK_OBJECT (window)); gtk_widget_show (darea); gtk_widget_show (window); /* The GTK+ main idle loop */ gtk_main(); /* Cleanup of GDK is done automatically when the program exits. */ return 0; } </verb></tscreen> <sect>The Graphics Context The Graphics Context, or GC, defines how things should be drawn, including color, font, fill, tile, stipple, clipping mask, line width, line style, and join style. <sect1>Color Changing color is done by changing the forground or background color of the GC. <sect>Drawing Commands <sect>Event Handling <sect>Understanding and Using Visuals <sect>Creating and Using New Windows <sect>Pixmaps <sect>Images <sect>Fonts <sect> <sect>About this Document <sect1>History This document was originially written by Peter Mattis and entitled "The General Drawing Kit". It was meant as a reference guide. This version of the document has been renamed and is meant as a general programming guide. <sect1>Copying Copyright (c) 1996 Peter Mattis Copyright (c) 1998 Shawn T. Amundson Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by Peter Mattis. </article>