gtk.texi

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

\input texinfo @c -*-texinfo-*-
@c Copyright (C) 1996 by Peter Mattis. All rights reserved.
@c Portions Copyright (C) 1998 Marius Vollmer
@c
@c %**start of header
@setfilename gtk.info
@settitle GTK
@setchapternewpage odd
@include macros.texi
@c %**end of header

@set edition 1.0
@set update-date 23 August 1998
@set update-month August 1998

@ifinfo
This file documents GTK, the GIMP Toolkit

Copyright (C) 1996 Peter Mattis
Copyright (C) 1997 Peter Mattis

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

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission notice
identical to this one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
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.
@end ifinfo

@titlepage
@title The GIMP Toolkit
@subtitle Version @value{edition}
@subtitle @value{update-month}
@author by Peter Mattis and the GTK+ team

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1996 Peter Mattis
@vskip 0pt plus 1fill
Copyright @copyright{} 1997 Peter Mattis

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.
@end titlepage

@dircategory User Interface Toolkit
@direntry
* GTK: (gtk).		The GIMP Toolkit
@end direntry

@node Top, Copying, (dir), (dir)
@top The GIMP Toolkit
@ifinfo
This is edition @value{edition} of the GTK documentation,
@w{@value{update-date}}.
@end ifinfo
@c FIXME: Do a introduction to the GTK?

@menu
* Copying::                     Your rights.
* Overview::                    What is GTK?
* Types::                       
* Objects::                     
* Signals::                     Signals overview.
* Widgets::                     Widget overview.
* Other Objects::               Utility objects.
* Miscellaneous::               Initialization, exit and other features.
* Examples::                    Using GTK.
* Object Implementation::       Object internals.
* Signal Implementation::       Signal internals.
* Widget Implementation::       Widget internals.
* Function Index::              Index of functions.
* Concept Index::               Index of concepts.
@end menu

@node Copying, Overview, Top, Top
@comment node-name, next, previous, up
@chapter Copying
@cindex Copying

GTK is @dfn{free}; this means that everyone is free to use it and free
to redistribute it on a free basis. GTK is not in the public domain; it
is copyrighted and there are restrictions on its distribution, but
these restrictions are designed to permit everything that a good
cooperating citizen would want to do. What is not allowed is to try to
prevent others from further sharing any version of GTK that they might
get from you.

Specifically, we want to make sure that you have the right to give away
copies of GTK, that you receive source code or else can get it if you
want it, that you can change GTK or use pieces of it in new free
programs, and that you know you can do these things.

To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights. For example, if you distribute
copies of GTK, you must give the recipients all the rights that you
have. You must make sure that they, too, receive or can get the source
code. And you must tell them their rights.

Also, for our own protection, we must make certain that everyone finds
out that there is no warranty for GTK. If GTK is modified by someone
else and passed on, we want their recipients to know that what they have
is not what we distributed, so that any problems introduced by others
will no reflect on our reputation.

The precise conditions of the licenses for GTK are found in the General
Public Licenses that accompany it.


@node Overview, Types, Copying, Top
@comment node-name, next, previous, up
@chapter What is GTK?
@cindex Overview

GTK is a library for creating graphical user interfaces similar to the
Motif ``look and feel''. It is designed to be small and efficient, but
still flexible enough to allow the programmer freedom in the interfaces
created. GTK allows the programmer to use a variety of standard user
interface widgets (@pxref{Widgets}) such as push, radio and check
buttons, menus, lists and frames. It also provides several ``container''
widgets which can be used to control the layout of the user interface
elements.

GTK provides some unique features. (At least, I know of no other widget
library which provides them). For example, a button does not contain a
label, it contains a child widget, which in most instances will be a
label. However, the child widget can also be a pixmap, image or any
combination possible the programmer desires. This flexibility is adhered
to throughout the library.

@c I think the next paragraph takes unproportionally much space for
@c the thing it wants to say (compared to the rest of this overview).
@c So Somebody please extend this overview with more generally interesting
@c stuff. - mvo

To make life easier for you, GTK presents this flexibility in a uniform
framework.  Specifically, it implements its own support for object
oriented programming that is well adapted to the purposes of a user
interface toolkit and it aims at providing a reasonable sane and
disciplined programming interface.  This uniformity and discipline is
intended to make it easy and reliable to access GTK from languages other
than C.  Especially more dynamic languages like Perl, Python or Scheme
will find amble support, and in fact, bindings to these languages
already exist.

@node Types, Objects, Overview, Top
@comment node-name, next, previous, up
@chapter Types
@cindex type
@cindex type system
@cindex class

@flushright
Other kid's games are all such a bore!
They've gotta have rules and they gotta keep score!
@*
-- Calvin about CalvinBall(tm)
@end flushright

GTK implements a semi-simple type system with an associated class
mechanism for widgets and several other useful objects.  This type
system is intended to be general enough to allow both a smooth binding
of dynamically typed languages to Gtk, as well as to serve for a
rigorous and formalistic definition of the larger part of the Gtk API.

@c  The GtkObject
@c  type is the root of the class hierarchy. It provides a few items needed
@c  by all classes, the foundation for the signal (@pxref{Signals})
@c  mechanism and the ``destroy'' method.

The classes for the individual widgets are by far the most important
part of this type system, but before we get to them, we describe the
basics of the type system itself.  This is mostly of interest for widget
writers and language binders, so you might want to skip ahead to the
next chapter, which talks about the object oriented stuff.

@menu
* Type introduction::           
* Basics::                      
* Simple types::                
* Enumerations and flags::      
* Strings::                     
* Boxed types::                 
* Callbacks::                   
* Composite types::             
@end menu

@node Type introduction, Basics, Types, Types
@section Introduction to the Type System

Gtk defines its own system of types, much like a computer language
defines what types it supports.  Of course, the Gtk type system is build
on top of the types that C provides, so it includes members like
@samp{int}, @samp{long} and @samp{float}.  But, compared to C, it allows
only few carefully selected types and specifies a lot of restrictions on
the way you can use values of these types.  For example, there is no
general facility for specifying @emph{pointer to X}.  Instead, we take a
more higher level approach and define such things as @samp{string},
which is just like a @code{char*} but with additional rules about how to
manage the memory that it points to.

The type system has two purposes: to define a formal system with which
to describe the various exported features of Gtk; and to implement this
system at run-time so that we get sound and flexible @dfn{dynamic} types
for the dynamic languages that want to interface with Gtk.

Let me restate this with different words, because I think it is
important to understand this idea.  We will see in a moment that the
type system is indeed well defined and all this detail is implemented
with functions and data structures in Gtk.  For example, every type (and
there can be any number of them) can be represented with a unique
integer and Gtk has support for the necessary bookkeeping for this.
Every type also has a name and there are functions for converting
between the name of a type and its unique number.  Maybe more useful,
there is a big discriminated union that can be used to pass around a
value of any representable type, together with its precise type.

This is the run-time or dynamic side of the type system.  Mostly, you do
not need to use it when you don't want to.  The compile-time or static
side of the type system can is used to statically define the programming
interface of Gtk.  For example, suppose there is function @code{gtk_foo}
in the Gtk API that has a prototype

@example
char *gtk_foo (char *);
@end example

This looks like it does something with strings.  But what does it do
with the memory of the string that has been passed in, and what are we
supposed or allowed to do with the memory that the returned pointer
points to?  The more restricted type @samp{string} from the Gtk type
system can be used to be more precise.  In fact, the definition of
@samp{string} below includes the rule that when a @samp{string} is
passed to a function, that function is not allowed to retain a pointer
into the string beyond the life time of that function call.  So we are
safe to deallocate it or override it when the function has returned.
Likewise, the definition specifies that the memory of a @samp{string}
that is returned from a function becomes the sole property of the
calling function.  The calling function is responsible for deallocating
it eventually and it can be sure that nobody else scribbles in it.  When
@samp{gtk_foo} really obeys these rules, we can say that it takes one
argument, which is a @samp{string}, and it returns a @samp{string}.

Now we can understand why it makes sense to have a more restrictive type
system than that of C.  With it, it is possible to be more precise and
we actually have a framework where we can be sure that as long as we
stay inside this framework we are not gratuitously causing trouble for
languages that are more disciplined than C.  Of course, you are not
restricted to making all your interfaces expressible within the
framework.  There are valid reasons for breaking it, for performance or
simply for convenience.  But please try to provide all the functionality
of your module in such a way that it can be described with this type
system and treat the non-conforming functions as additional goodies that
are nice to have but not essential.  The reward is an instant
accessibility of your code from a huge number of scripting and extension
languages such as Perl, Python, and Guile.

These formal specifications of the Gtk interface are contained in
special declarations in the header files of Gtk.  They are ignored by
the C compiler, but can be used by other language processors.  For extra
convenience, these declarations are also available in a more condensed
form that is easier to parse.  Tools for generating bindings of Gtk to
other languages can read these declarations and---because all the
important details are defined---automatically generate the bulk of the
needed glue code.  It is also possible to feed these declarations into a
running application (a interface builder, say) and thus make it aware of
new widgets and functions without recompiling anything.

The run-time side of the type system is also somewhat introspective.
This means that you can query Gtk about all the members of an
enumeration for example.  Gtk provides tools that help you provide this
introspection for your definitions also.

Types are not enough to completely specify an interface, so GTK also has
@dfn{modes}.  A mode specifies what happens to a value when it crosses a
module boundary; it can be @samp{in}, @samp{out}, or @samp{inout}.  Most
fundamental types (and their derived types) support only mode @samp{in}.
The modes @samp{out} and @samp{inout} can only be used with the
composite types: lists and vectors.  When argument of these types are