Pileus Git - ~andy/gtk/blob - docs/gdk.sgml

   1 <!doctype linuxdoc system>
   2
   3 <article>
   4
   5 <!-- Title information -->
   6
   7 <title>The GTK+ Drawing Kit Programming Manual
   8 <author>Shawn T. Amundson, Peter Mattis
   9 <date>July 26, 1998
  10
  11 <abstract>
  12 This document aims at teaching user how to effectively program in
  13 GDK, the GTK+ Drawing Kit, and to serve as a reference guide to
  14 more experienced GTK+ programmers.  It is a work in progress.
  15
  16 <!-- Table of contents -->
  17 <toc>
  18
  19 <!-- Begin the document -->
  20
  21 <!-- ***************************************************************** -->
  22 <sect>Introduction
  23
  24 <p>
  25 GDK is designed as a wrapper library that lies on top of Xlib. It
  26 performs many common and desired operations for a programmer instead
  27 of the programmer having to explicitly ask for such functionality from
  28 Xlib directly. For example, GDK provides a common interface to both
  29 regular and shared memory XImage types. By doing so, an application
  30 can nearly transparently use the fastest image type available. GDK
  31 also provides routines for determining the best available color depth
  32 and the best available visual which is not always the default visual
  33 for a screen.
  34
  35 GDK is distributed and developed with GTK+, and is licensed under the
  36 GNU Library General Public Licence (LGPL).
  37
  38 <sect>Getting Started
  39
  40 <sect1>Initialization
  41 <p>
  42 Initialization of GDK is easy.  Simply call gdk_init() passing
  43 in the argc and argv parameters.
  44
  45 <tscreen><verb>
  46 int main (int argc, char *argv[])
  47 {
  48     /* Initialize GDK. */
  49     gdk_init (&amp;argc, &amp;argv);
  50
  51     /* Cleanup of GDK is done automatically when the program exits. */
  52     return 0;
  53 }
  54 </verb></tscreen>
  55
  56 Generally, GDK initialization is done by gtk_init() in GTK+.  This means
  57 that when using GTK+, you do not need to directly call gdk_init().
  58
  59 <sect1>An Example using GDK with GTK+
  60 <p>
  61 This example demonstrates drawing a line using the foreground
  62 color of the GtkDrawArea widget it is drawn inside.  The example
  63 will end when you click inside the window, which is filled by the
  64 GtkDrawingArea widget.
  65
  66 The line is drawn during the expose event so that when the window
  67 drawing is done whenever it is needed.
  68
  69 <tscreen><verb>
  70 #include <gtk/gtk.h>
  71
  72 /* The expose callback does the drawing of the line */
  73 int
  74 expose_callback (GtkWidget *widget, GdkEventExpose *event, gpointer data)
  75 {
  76     GdkGC *gc;
  77
  78     printf("expose...\n");
  79
  80
  81     /* The GC is the Graphics Context.  Here it is borrowed from the widget */
  82     gc = widget->style->fg_gc[GTK_STATE_NORMAL];
  83
  84     gdk_draw_line (widget->window,  /* GDK Window of GtkDrawingArea widget */
  85                    gc,              /* Graphics Context */
  86                    0,               /* x1, left */
  87                    0,               /* y1, top */
  88                    200,             /* x2, right */
  89                    200);            /* y2, bottom */
  90 }
  91
  92 /* This quits GTK+ */
  93 void destroy (GtkWidget *widget, gpointer data)
  94 {
  95     gtk_main_quit ();
  96 }
  97
  98 int main (int argc, char *argv[])
  99 {
 100     GtkWidget *window;
 101     GtkWidget *darea;
 102     int events;
 103
 104     /* This initializes both GTK+ and GDK */
 105     gtk_init (&amp;argc, &amp;argv);
 106
 107     /* Create a window */
 108     window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
 109     gtk_signal_connect (GTK_OBJECT (window), "destroy",
 110                         GTK_SIGNAL_FUNC (destroy), NULL);
 111
 112     /* Create a drawing area widget. This widget actually is just a
 113        simple widget which provides us an GDK window to draw on and
 114        takes care of all the toolkit integration, like providing the
 115        ability to add it to the window with gtk_contianer_add() */
 116     darea = gtk_drawing_area_new ();
 117     gtk_container_add (GTK_CONTAINER (window), darea);
 118
 119     /* Set the width and height (arguments are in that order) */
 120     gtk_drawing_area_size (GTK_DRAWING_AREA (darea), 200, 200);
 121
 122     /* Drawing in the expose event is important to keep the
 123        draw line always on the GDK window */
 124     gtk_signal_connect (GTK_OBJECT (darea), "expose_event",
 125                         GTK_SIGNAL_FUNC (expose_callback), NULL);
 126
 127     /* We get the events, then add in button press.  If we did not
 128        do this, we would not be notified of button press events in
 129        the GtkDrawingArea widget */
 130     events = gtk_widget_get_events (darea);
 131     gtk_widget_set_events (darea, events | GDK_BUTTON_PRESS_MASK);
 132
 133     /* If we click on the darea, the application will exit */
 134     gtk_signal_connect_object (GTK_OBJECT (darea), "button_press_event",
 135                                GTK_SIGNAL_FUNC (gtk_widget_destroy),
 136                                GTK_OBJECT (window));
 137
 138     gtk_widget_show (darea);
 139     gtk_widget_show (window);
 140
 141     /* The GTK+ main idle loop */
 142     gtk_main();
 143
 144     /* Cleanup of GDK is done automatically when the program exits. */
 145     return 0;
 146 }
 147 </verb></tscreen>
 148
 149 <sect>The Graphics Context
 150 <p>
 151 The Graphics Context, or GC, defines how things should be drawn,
 152 including color, font, fill, tile, stipple, clipping mask, line
 153 width, line style, and join style.
 154
 155 <sect1>Color
 156 <p>
 157 Changing color is done by changing the forground or background color
 158 of the GC.
 159
 160 <sect>Drawing Commands
 161 <sect>Event Handling
 162 <sect>Understanding and Using Visuals
 163 <sect>Creating and Using New Windows
 164 <sect>Pixmaps
 165 <sect>Images
 166 <sect>Fonts
 167 <sect>
 168
 169 <sect>About this Document
 170 <sect1>History
 171 <P>
 172 This document was originially written by Peter Mattis and entitled
 173 "The General Drawing Kit".  It was meant as a reference guide.
 174
 175 This version of the document has been renamed and is meant as a general
 176 programming guide.
 177
 178 <sect1>Copying
 179 <p>
 180 Copyright (c) 1996 Peter Mattis
 181 <p>
 182 Copyright (c) 1998 Shawn T. Amundson
 183
 184 Permission is granted to make and distribute verbatim copies of this
 185 manual provided the copyright notice and this permission notice are
 186 preserved on all copies.
 187
 188 Permission is granted to copy and distribute modified versions of this
 189 manual under the conditions for verbatim copying, provided that the
 190 entire resulting derived work is distributed under the terms of a
 191 permission notice identical to this one.
 192
 193 Permission is granted to copy and distribute translations of this manual
 194 into another language, under the above conditions for modified versions,
 195 except that this permission notice may be stated in a translation
 196 approved by Peter Mattis.
 197
 198 </article>