📄 gtk.html
字号:
<HTML><HEAD><!-- This HTML file has been created by texi2html 1.54 from gtk.texi on 24 March 1999 --><TITLE>GTK</TITLE></HEAD><BODY><H1>The GIMP Toolkit</H1><H2>Version 1.0</H2><H2>August 1998</H2><ADDRESS>by Peter Mattis and the GTK+ team</ADDRESS><P><P><HR><P><H1><A NAME="SEC1" HREF="gtk_toc.html#TOC1">Copying</A></H1><P><A NAME="IDX4"></A></P><P>GTK is <STRONG>free</STRONG>; this means that everyone is free to use it and freeto redistribute it on a free basis. GTK is not in the public domain; itis copyrighted and there are restrictions on its distribution, butthese restrictions are designed to permit everything that a goodcooperating citizen would want to do. What is not allowed is to try toprevent others from further sharing any version of GTK that they mightget from you.</P><P>Specifically, we want to make sure that you have the right to give awaycopies of GTK, that you receive source code or else can get it if youwant it, that you can change GTK or use pieces of it in new freeprograms, and that you know you can do these things.</P><P>To make sure that everyone has such rights, we have to forbid you todeprive anyone else of these rights. For example, if you distributecopies of GTK, you must give the recipients all the rights that youhave. You must make sure that they, too, receive or can get the sourcecode. And you must tell them their rights.</P><P>Also, for our own protection, we must make certain that everyone findsout that there is no warranty for GTK. If GTK is modified by someoneelse and passed on, we want their recipients to know that what they haveis not what we distributed, so that any problems introduced by otherswill no reflect on our reputation.</P><P>The precise conditions of the licenses for GTK are found in the GeneralPublic Licenses that accompany it.</P><H1><A NAME="SEC2" HREF="gtk_toc.html#TOC2">What is GTK?</A></H1><P><A NAME="IDX5"></A></P><P>GTK is a library for creating graphical user interfaces similar to theMotif "look and feel". It is designed to be small and efficient, butstill flexible enough to allow the programmer freedom in the interfacescreated. GTK allows the programmer to use a variety of standard userinterface widgets (see section <A HREF="gtk.html#SEC15">Widget Overview</A>) such as push, radio and checkbuttons, menus, lists and frames. It also provides several "container"widgets which can be used to control the layout of the user interfaceelements.</P><P>GTK provides some unique features. (At least, I know of no other widgetlibrary which provides them). For example, a button does not contain alabel, it contains a child widget, which in most instances will be alabel. However, the child widget can also be a pixmap, image or anycombination possible the programmer desires. This flexibility is adheredto throughout the library.</P><P>To make life easier for you, GTK presents this flexibility in a uniformframework. Specifically, it implements its own support for objectoriented programming that is well adapted to the purposes of a userinterface toolkit and it aims at providing a reasonable sane anddisciplined programming interface. This uniformity and discipline isintended to make it easy and reliable to access GTK from languages otherthan C. Especially more dynamic languages like Perl, Python or Schemewill find amble support, and in fact, bindings to these languagesalready exist.</P><H1><A NAME="SEC3" HREF="gtk_toc.html#TOC3">Types</A></H1><P><A NAME="IDX6"></A><A NAME="IDX7"></A><A NAME="IDX8"></A></P><PRE>Other kid's games are all such a bore!They've gotta have rules and they gotta keep score!<BR>-- Calvin about CalvinBall(tm)</PRE><P>GTK implements a semi-simple type system with an associated classmechanism for widgets and several other useful objects. This typesystem is intended to be general enough to allow both a smooth bindingof dynamically typed languages to Gtk, as well as to serve for arigorous and formalistic definition of the larger part of the Gtk API.</P><P>The classes for the individual widgets are by far the most importantpart of this type system, but before we get to them, we describe thebasics of the type system itself. This is mostly of interest for widgetwriters and language binders, so you might want to skip ahead to thenext chapter, which talks about the object oriented stuff.</P><H2><A NAME="SEC4" HREF="gtk_toc.html#TOC4">Introduction to the Type System</A></H2><P>Gtk defines its own system of types, much like a computer languagedefines what types it supports. Of course, the Gtk type system is buildon top of the types that C provides, so it includes members like<SAMP>`int'</SAMP>, <SAMP>`long'</SAMP> and <SAMP>`float'</SAMP>. But, compared to C, it allowsonly few carefully selected types and specifies a lot of restrictions onthe way you can use values of these types. For example, there is nogeneral facility for specifying <EM>pointer to X</EM>. Instead, we take amore higher level approach and define such things as <SAMP>`string'</SAMP>,which is just like a <CODE>char*</CODE> but with additional rules about how tomanage the memory that it points to.</P><P>The type system has two purposes: to define a formal system with whichto describe the various exported features of Gtk; and to implement thissystem at run-time so that we get sound and flexible <STRONG>dynamic</STRONG> typesfor the dynamic languages that want to interface with Gtk.</P><P>Let me restate this with different words, because I think it isimportant to understand this idea. We will see in a moment that thetype system is indeed well defined and all this detail is implementedwith functions and data structures in Gtk. For example, every type (andthere can be any number of them) can be represented with a uniqueinteger and Gtk has support for the necessary bookkeeping for this.Every type also has a name and there are functions for convertingbetween 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 avalue of any representable type, together with its precise type.</P><P>This is the run-time or dynamic side of the type system. Mostly, you donot need to use it when you don't want to. The compile-time or staticside of the type system can is used to statically define the programminginterface of Gtk. For example, suppose there is function <CODE>gtk_foo</CODE>in the Gtk API that has a prototype</P><PRE>char *gtk_foo (char *);</PRE><P>This looks like it does something with strings. But what does it dowith the memory of the string that has been passed in, and what are wesupposed or allowed to do with the memory that the returned pointerpoints to? The more restricted type <SAMP>`string'</SAMP> from the Gtk typesystem can be used to be more precise. In fact, the definition of<SAMP>`string'</SAMP> below includes the rule that when a <SAMP>`string'</SAMP> ispassed to a function, that function is not allowed to retain a pointerinto the string beyond the life time of that function call. So we aresafe to deallocate it or override it when the function has returned.Likewise, the definition specifies that the memory of a <SAMP>`string'</SAMP>that is returned from a function becomes the sole property of thecalling function. The calling function is responsible for deallocatingit eventually and it can be sure that nobody else scribbles in it. When<SAMP>`gtk_foo'</SAMP> really obeys these rules, we can say that it takes oneargument, which is a <SAMP>`string'</SAMP>, and it returns a <SAMP>`string'</SAMP>.</P><P>Now we can understand why it makes sense to have a more restrictive typesystem than that of C. With it, it is possible to be more precise andwe actually have a framework where we can be sure that as long as westay inside this framework we are not gratuitously causing trouble forlanguages that are more disciplined than C. Of course, you are notrestricted to making all your interfaces expressible within theframework. There are valid reasons for breaking it, for performance orsimply for convenience. But please try to provide all the functionalityof your module in such a way that it can be described with this typesystem and treat the non-conforming functions as additional goodies thatare nice to have but not essential. The reward is an instantaccessibility of your code from a huge number of scripting and extensionlanguages such as Perl, Python, and Guile.</P><P>These formal specifications of the Gtk interface are contained inspecial declarations in the header files of Gtk. They are ignored bythe C compiler, but can be used by other language processors. For extraconvenience, these declarations are also available in a more condensedform that is easier to parse. Tools for generating bindings of Gtk toother languages can read these declarations and--because all theimportant details are defined--automatically generate the bulk of theneeded glue code. It is also possible to feed these declarations into arunning application (a interface builder, say) and thus make it aware ofnew widgets and functions without recompiling anything.</P><P>The run-time side of the type system is also somewhat introspective.This means that you can query Gtk about all the members of anenumeration for example. Gtk provides tools that help you provide thisintrospection for your definitions also.</P><P>Types are not enough to completely specify an interface, so GTK also has<STRONG>modes</STRONG>. A mode specifies what happens to a value when it crosses amodule boundary; it can be <SAMP>`in'</SAMP>, <SAMP>`out'</SAMP>, or <SAMP>`inout'</SAMP>. Mostfundamental types (and their derived types) support only mode <SAMP>`in'</SAMP>.The modes <SAMP>`out'</SAMP> and <SAMP>`inout'</SAMP> can only be used with thecomposite types: lists and vectors. When argument of these types aremarked as <SAMP>`out'</SAMP> or <SAMP>`inout'</SAMP> it means that the called module isallowed to change the contents of the composite value and that thesechanges need to be propagated back to the originator of the value. Mode<SAMP>`out'</SAMP> means that the argument has no meaningful value at thebeginning and should not be read. Mode <SAMP>`in'</SAMP> specifies that thecalled module is not allowed to change the value in any way.</P><P>The type system allows for an unbounded number of types. Every widgetis a type for example and you can add new widget types at any timewithout confusing the run-time implementation of the type system.Nevertheless, all types are derived from a certain <STRONG>fundamental</STRONG>type, and there are only a small and finite number of fundamental types.We only specify rules for the fundamental types and all other typesinherit these rules from their fundamental type. For example,<SAMP>`int'</SAMP> is a fundamental type, as is <SAMP>`GtkObject'</SAMP>. All widgetsderive from <SAMP>`GtkObject'</SAMP> and so the rules for <SAMP>`GtkObject'</SAMP> applyto all widgets as well.</P><P>This derivation defines a type hierachy, but this hierachy is notcompletely general. You can't derive from <SAMP>`int'</SAMP> for example, andyou can only have one level of derivation from <SAMP>`enum'</SAMP>. Thefundamental type <SAMP>`GtkObject'</SAMP>, however, is the basis for the largeand deep hierarchy of widget types.</P><P>The individual fundamental types are defined and explained in thefollowing sections. Here is a complete list of them:</P><DL COMPACT><DT><SAMP>`none'</SAMP><DD>The not-a-value type, similar to <SAMP>`void'</SAMP>.<DT><SAMP>`char'</SAMP><DD>A character. Internationalization issues are still undecided.<DT><SAMP>`bool'</SAMP><DD>True or false.<DT><SAMP>`byte, ubyte, int, uint, long, ulong, float, double'</SAMP><DD>The usual assortment of scalar types.<DT><SAMP>`string'</SAMP><DD>A string. Internationalization issues are still undecided.<DT><SAMP>`enum, flags'</SAMP><DD>Enumerations with a fixed set of literals. Either used to express asingle choice from this set or to individually turn on and off severalflags.<DT><SAMP>`boxed'</SAMP><DD>A pointer to an opaque structure that can be copied and destroyed.<DT><SAMP>`callback'</SAMP><DD>A pointer to a function with enough extra information so that it canalso be used for functions written in languages completely differentfrom C.<DT><SAMP>`GtkObject'</SAMP><DD>A pointer to a GtkObject or derived type. The fun starts here.<DT><SAMP>`args, slist, dlist, cvec, tvec'</SAMP><DD>An assortment of composite types like linked lists and counted orzero-terminated arrays.<DT><SAMP>`pointer, signal, c_callback'</SAMP><DD>Obsolete types.</DL><H2><A NAME="SEC5" HREF="gtk_toc.html#TOC5">Basic Concepts</A></H2><P>The basis for the type system are the fundamental types. At run-time,they are represented by members of the <CODE>GtkFundamentalType</CODE>enumeration. For the static declarations, they are identified with aunique name.</P><P><DL><DT><U>Enumeration:</U> <B>GtkFundamentalType</B><DD><A NAME="IDX9"></A>This enumeration contains a member for each defined fundamental type.Most members are listed along with the description of their semantics,but one is listed here:</P><DL COMPACT><DT><CODE>GTK_TYPE_INVALID</CODE><DD>No valid type is derived from this. Use <CODE>GTK_TYPE_INVALID</CODE> toexpress exceptional situations. This member does not really correspondto a fundamental type and thus there is no name for it.</DL></DL><P><DL><DT><U>Data type:</U> <B>GtkType</B><DD><A NAME="IDX10"></A>The type <CODE>GtkType</CODE> holds the run-time representation of a type. Itis a integer of a certain size. The follwing macros are defined toaccess the basic properties of a <CODE>GtkType</CODE>:</P><P><DL><DT><U>Macro:</U> unsigned int <B>GTK_TYPE_SEQNO</B> <I>(GtkType type)</I><DD><A NAME="IDX11"></A>Returns the sequence number of <VAR>type</VAR>. The sequence numbers areguaranteed to be dense, i.e., you can use them to index a table and thetable need not be much larger than the number of different GtkTypes thatyou might encounter.</DL></P><P>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -