documentation and non-C languages

[Paolo Molaro <lupus lettere unipd it>]

Hi.
I'd like to write a tutorial for using Perl/Gtk.
The standard C-based tutorial is fine; besides I'm not so good
at writing english:-), so what about this setup?
We embed in the tutorial sections that are rendered from
sgml only when they are enabled: this means I only have to
rewrite in perl the code snippets:-) and the tutorial for
perl is kept almost automagically in sync with the tutorial for C.
This will allow other languages as well.
The only drawback is that this increases the size of the shipping 
gtk+ tarball, but we may want to have a separate tarball for the
documentation/tutorial anyway.
In the attachment you will find a modified gdk.sgml that shows
how it can be done.
To format it for different programming languages use:

sgml2{txt,html,...} --include c-code gdk.sgml
or
sgml2{txt,html,...} --include perl-code gdk.sgml

Comments welcome.

lupus

-- 
-----------------------------------------------------------------
lupus@debian.org                                     debian/rules
<!doctype linuxdoc system [
<!entity % perl-code "IGNORE">
<!entity % c-code "IGNORE">
]>

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

<![ %c-code [
<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>
]]>

<![ %perl-code [
<tscreen><verb>
use Gtk;

init Gtk::Gdk;
</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.

<![ %c-code [
<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>
]]>

<![ %perl-code [
<tscreen><verb>
use Gtk;

# The expose callback does the drawing of the line 
sub
expose_callback # (GtkWidget *widget, GdkEventExpose *event, gpointer data)
{
     my ($widget, $event, $data) = @_;
     my $gc;

    print "expose...\n";


    # The GC is the Graphics Context.  Here it is borrowed from the widget 
    $gc = $widget->style->fg_gc('normal');

    $widget->window->draw_line (    # GDK Window of GtkDrawingArea widget 
                   $gc,             # Graphics Context 
                   0,               # x1, left 
                   0,               # y1, top 
                   200,             # x2, right 
                   200);            # y2, bottom 
}

# This quits GTK+ 
sub destroy #(GtkWidget *widget, gpointer data)
{
    Gtk->main_quit ();
}

main: # (int argc, char *argv[])
{
    my $window;
    my $darea;
    my $events;

    # This initializes both GTK+ and GDK 
    init Gtk;

    # Create a window 
    $window = new Gtk::Window ('toplevel');
    $window->signal_connect ("destroy",\&amp;destroy));

    # 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 = new Gtk::DrawingArea;
    $window->add ($darea);

    # Set the width and height (arguments are in that order) 
    $darea->size (200, 200);

    # Drawing in the expose event is important to keep the 
    #   draw line always on the GDK window 
    $darea->signal_connect ("expose_event",\&amp;expose_callback);

    # 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 = $darea->get_events;
    push(@{$events}, 'button_press_mask');
    $darea->set_events ($events);

    # If we click on the darea, the application will exit 
    $darea->signal_connect_object ( "button_press_event", sub {shift->destroy;});

    $darea->show;
    $window->show;

    # The GTK+ main idle loop 
    Gtk->main;

    # Cleanup of GDK is done automatically when the program exits. 
    exit(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>