gtk_tut.sgml

gtk是linux一款强大的夸平台的图形化开发工具

<!doctype linuxdoc system>

<!-- This is the tutorial marked up in SGML
     (just to show how to write a comment)
-->

<article>
<title>GTK v1.2 Tutorial
<author>
Tony Gale <tt><htmlurl url="mailto:[e-mail]"
			      name="&lt;[e-mail]&gt;"></tt>
Ian Main <tt><htmlurl url="mailto:[e-mail]"
			      name="&lt;[e-mail]&gt;"></tt>,
<date>February 21st, 1999
<abstract>
This is a tutorial on how to use GTK (the GIMP Toolkit) through its C
interface.
</abstract>

<!-- Table of contents -->
<!-- Older versions of this tutorial did not have a table of contents,
     but the tutorial is now so large that having one is very useful. -->
<toc>
 

<!-- ***************************************************************** -->
<sect>Introduction
<!-- ***************************************************************** -->
<p>
GTK (GIMP Toolkit) is a library for creating graphical user
interfaces. It is licensed using the LGPL license, so you can develop
open software, free software, or even commercial non-free software
using GTK without having to spend anything for licenses or royalties.

It's called the GIMP toolkit because it was originally written for
developing the General Image Manipulation Program (GIMP), but GTK has
now been used in a large number of software projects, including the
GNU Network Object Model Environment (GNOME) project. GTK is built on
top of GDK (GIMP Drawing Kit) which is basically a wrapper around the
low-level functions for accessing the underlying windowing functions
(Xlib in the case of X windows). The primary authors of GTK are:

<itemize>
<item> Peter Mattis   <tt><htmlurl url="mailto:[e-mail]"
			   name="[e-mail]"></tt>
<item> Spencer Kimball <tt><htmlurl url="mailto:[e-mail]"
			   name="[e-mail]"></tt>
<item> Josh MacDonald <tt><htmlurl url="mailto:[e-mail]"
			   name="[e-mail]"></tt>
</itemize>

GTK is essentially an object oriented application programmers
interface (API). Although written completely in C, it is implemented
using the idea of classes and callback functions (pointers to
functions).

There is also a third component called glib which contains a few
replacements for some standard calls, as well as some additional
functions for handling linked lists etc. The replacement functions are
used to increase GTK's portability, as some of the functions
implemented here are not available or are nonstandard on other unixes
such as g_strerror(). Some also contain enhancements to the libc
versions, such as g_malloc that has enhanced debugging utilities.

This tutorial describes the C interface to GTK. There are GTK
bindings for many other languages including C++, Guile, Perl, Python,
TOM, Ada95, Objective C, Free Pascal, and Eiffel. If you intend to
use another language's bindings to GTK, look at that binding's
documentation first. In some cases that documentation may describe
some important conventions (which you should know first) and then
refer you back to this tutorial. There are also some cross-platform
APIs (such as wxWindows and V) which use GTK as one of their target
platforms; again, consult their documentation first.

If you're developing your GTK application in C++, a few extra notes
are in order. There's a C++ binding to GTK called GTK--, which
provides a more C++-like interface to GTK; you should probably look
into this instead. If you don't like that approach for whatever
reason, there are two alternatives for using GTK. First, you can use
only the C subset of C++ when interfacing with GTK and then use the C
interface as described in this tutorial. Second, you can use GTK and
C++ together by declaring all callbacks as static functions in C++
classes, and again calling GTK using its C interface. If you choose
this last approach, you can include as the callback's data value a
pointer to the object to be manipulated (the so-called "this" value).
Selecting between these options is simply a matter of preference,
since in all three approaches you get C++ and GTK. None of these
approaches requires the use of a specialized preprocessor, so no
matter what you choose you can use standard C++ with GTK.

This tutorial is an attempt to document as much as possible of GTK,
but it is by no means complete. This tutorial assumes a good
understanding of C, and how to create C programs. It would be a great
benefit for the reader to have previous X programming experience, but
it shouldn't be necessary. If you are learning GTK as your first
widget set, please comment on how you found this tutorial, and what
you had trouble with. Note that there is also a C++ API for GTK
(GTK--) in the works, so if you prefer to use C++, you should look
into this instead. There are also Objective C, ADA, Guile and other
language bindings available, but I don't follow these.

This document is a 'work in progress'. Please look for updates on
http://www.gtk.org/ <htmlurl url="http://www.gtk.org/"
name="http://www.gtk.org/">.

I would very much like to hear of any problems you have learning GTK
from this document, and would appreciate input as to how it may be
improved. Please see the section on <ref id="sec_Contributing"
name="Contributing"> for further information.

<!-- ***************************************************************** -->
<sect>Getting Started
<!-- ***************************************************************** -->

<p>
The first thing to do of course, is download the GTK source and
install it. You can always get the latest version from ftp.gtk.org in
/pub/gtk. You can also view other sources of GTK information on
http://www.gtk.org/ <htmlurl url="http://www.gtk.org/"
name="http://www.gtk.org/">. GTK uses GNU autoconf for configuration.
Once untar'd, type ./configure --help to see a list of options.

Th GTK source distribution also contains the complete source to all of
the examples used in this tutorial, along with Makefiles to aid
compilation.

To begin our introduction to GTK, we'll start with the simplest
program possible. This program will create a 200x200 pixel window and
has no way of exiting except to be killed using the shell.

<tscreen><verb>
/* example-start base base.c */

#include <gtk/gtk.h>

int main( int   argc,
          char *argv[] )
{
    GtkWidget *window;
    
    gtk_init (&amp;argc, &amp;argv);
    
    window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
    gtk_widget_show  (window);
    
    gtk_main ();
    
    return(0);
}
/* example-end */
</verb></tscreen>

You can compile the above program with gcc using:
<tscreen><verb>
gcc base.c -o base `gtk-config --cflags --libs`
</verb></tscreen>

The meaning of the unusual compilation options is explained below.

All programs will of course include gtk/gtk.h which declares the
variables, functions, structures etc. that will be used in your GTK
application.

The next line:

<tscreen><verb>
gtk_init (&amp;argc, &amp;argv);
</verb></tscreen>

calls the function gtk_init(gint *argc, gchar ***argv) which will be
called in all GTK applications. This sets up a few things for us such
as the default visual and color map and then proceeds to call
gdk_init(gint *argc, gchar ***argv). This function initializes the
library for use, sets up default signal handlers, and checks the
arguments passed to your application on the command line, looking for
one of the following:

<itemize>
<item> <tt/--gtk-module/
<item> <tt/--g-fatal-warnings/
<item> <tt/--gtk-debug/
<item> <tt/--gtk-no-debug/
<item> <tt/--gdk-debug/
<item> <tt/--gdk-no-debug/
<item> <tt/--display/
<item> <tt/--sync/
<item> <tt/--no-xshm/
<item> <tt/--name/
<item> <tt/--class/
</itemize>

It removes these from the argument list, leaving anything it does not
recognize for your application to parse or ignore. This creates a set
of standard arguments accepted by all GTK applications.

The next two lines of code create and display a window.

<tscreen><verb>
  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  gtk_widget_show (window);
</verb></tscreen>

The GTK_WINDOW_TOPLEVEL argument specifies that we want the window to
undergo window manager decoration and placement. Rather than create a
window of 0x0 size, a window without children is set to 200x200 by
default so you can still manipulate it.

The gtk_widget_show() function lets GTK know that we are done setting
the attributes of this widget, and that it can display it.

The last line enters the GTK main processing loop.

<tscreen><verb>
  gtk_main ();
</verb></tscreen>

gtk_main() is another call you will see in every GTK application.
When control reaches this point, GTK will sleep waiting for X events
(such as button or key presses), timeouts, or file IO notifications to
occur. In our simple example however, events are ignored.

<!-- ----------------------------------------------------------------- -->
<sect1>Hello World in GTK
<p>
Now for a program with a widget (a button).  It's the classic
hello world a la GTK.

<tscreen><verb>
/* example-start helloworld helloworld.c */

#include <gtk/gtk.h>

/* This is a callback function. The data arguments are ignored
 * in this example. More on callbacks below. */
void hello( GtkWidget *widget,
            gpointer   data )
{
    g_print ("Hello World\n");
}

gint delete_event( GtkWidget *widget,
                   GdkEvent  *event,
		   gpointer   data )
{
    /* If you return FALSE in the "delete_event" signal handler,
     * GTK will emit the "destroy" signal. Returning TRUE means
     * you don't want the window to be destroyed.
     * This is useful for popping up 'are you sure you want to quit?'
     * type dialogs. */

    g_print ("delete event occurred\n");

    /* Change TRUE to FALSE and the main window will be destroyed with
     * a "delete_event". */

    return(TRUE);
}

/* Another callback */
void destroy( GtkWidget *widget,
              gpointer   data )
{
    gtk_main_quit();
}

int main( int   argc,
          char *argv[] )
{
    /* GtkWidget is the storage type for widgets */
    GtkWidget *window;
    GtkWidget *button;
    
    /* This is called in all GTK applications. Arguments are parsed
     * from the command line and are returned to the application. */
    gtk_init(&amp;argc, &amp;argv);
    
    /* create a new window */
    window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
    
    /* When the window is given the "delete_event" signal (this is given
     * by the window manager, usually by the 'close' option, or on the
     * titlebar), we ask it to call the delete_event () function
     * as defined above. The data passed to the callback
     * function is NULL and is ignored in the callback function. */
    gtk_signal_connect (GTK_OBJECT (window), "delete_event",
			GTK_SIGNAL_FUNC (delete_event), NULL);
    
    /* Here we connect the "destroy" event to a signal handler.  
     * This event occurs when we call gtk_widget_destroy() on the window,
     * or if we return 'FALSE' in the "delete_event" callback. */
    gtk_signal_connect (GTK_OBJECT (window), "destroy",
			GTK_SIGNAL_FUNC (destroy), NULL);
    
    /* Sets the border width of the window. */
    gtk_container_set_border_width (GTK_CONTAINER (window), 10);
    
    /* Creates a new button with the label "Hello World". */
    button = gtk_button_new_with_label ("Hello World");
    
    /* When the button receives the "clicked" signal, it will call the
     * function hello() passing it NULL as its argument.  The hello()
     * function is defined above. */
    gtk_signal_connect (GTK_OBJECT (button), "clicked",
			GTK_SIGNAL_FUNC (hello), NULL);
    
    /* This will cause the window to be destroyed by calling
     * gtk_widget_destroy(window) when "clicked".  Again, the destroy
     * signal could come from here, or the window manager. */
    gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
			       GTK_SIGNAL_FUNC (gtk_widget_destroy),
			       GTK_OBJECT (window));
    
    /* This packs the button into the window (a gtk container). */
    gtk_container_add (GTK_CONTAINER (window), button);
    
    /* The final step is to display this newly created widget. */
    gtk_widget_show (button);
    
    /* and the window */
    gtk_widget_show (window);
    
    /* All GTK applications must have a gtk_main(). Control ends here
     * and waits for an event to occur (like a key press or
     * mouse event). */
    gtk_main ();
    
    return(0);
}
/* example-end */
</verb></tscreen>

<!-- ----------------------------------------------------------------- -->
<sect1>Compiling Hello World
<p>
To compile use:

<tscreen><verb>
gcc -Wall -g helloworld.c -o helloworld `gtk-config --cflags` \
    `gtk-config --libs`
</verb></tscreen>

This uses the program <tt>gtk-config</>, which comes with gtk. This
program 'knows' what compiler switches are needed to compile programs
that use gtk. <tt>gtk-config --cflags</> will output a list of include
directories for the compiler to look in, and <tt>gtk-config --libs</>
will output the list of libraries for the compiler to link with and
the directories to find them in. In the aboce example they could have
been combined into a single instance, such as
`gtk-config --cflags --libs`.

Note that the type of single quote used in the compile command above
is significant.

The libraries that are usually linked in are:
<itemize>
<item>The GTK library (-lgtk), the widget library, based on top of GDK.
<item>The GDK library (-lgdk), the Xlib wrapper.
<item>The gmodule library (-lgmodule), which is used to load run time
extensions.
<item>The glib library (-lglib), containing miscellaneous functions, only
g_print() is used in this particular example. GTK is built on top
of glib so you will always require this library. See the section on 
<ref id="sec_glib" name="glib"> for details.
<item>The Xlib library (-lX11) which is used by GDK.
<item>The Xext library (-lXext). This contains code for shared memory
pixmaps and other X extensions.
<item>The math library (-lm). This is used by GTK for various purposes.
</itemize>

<!-- ----------------------------------------------------------------- -->
<sect1>Theory of Signals and Callbacks