gtk/docs/gdk.sgml

<!doctype linuxdoc system>

<article>

<!-- Title information -->

<title>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.

<!-- Table of contents -->
<toc>

<!-- Begin the document -->

<!-- ***************************************************************** -->
<sect>Introduction

<p>
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
<p>
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 (&amp;argc, &amp;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+ 
<p>
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 (&amp;argc, &amp;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 
<p>
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
<p>
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
<P>
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
<p>
Copyright (c) 1996 Peter Mattis
<p>
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>