1 <!doctype linuxdoc system>
5 <!-- Title information -->
9 <!-- NOTE: Use only one author tag, otherwise sgml2txt barfs - TRG -->
10 <author>Nathan Froyd, Tony Gale, Shawn T. Amundson, Emmanuel Deloget
14 <abstract> This document is intended to answer questions that are likely to be
15 frequently asked by programmers using GTK+ or people who are just looking at
19 <!-- Table of contents -->
22 <!-- Begin the document -->
24 <!-- ***************************************************************** -->
25 <sect>General Information
27 <!-- ----------------------------------------------------------------- -->
28 <sect1>Before anything else: the greetings
30 The FAQ authors want to thank:
32 <item>Havoc Pennington
36 <item>Thomas Mailund Jensen
39 <item>Federico Mena Quintero
41 <item>and all the members of the GTK+ lists
43 If we forgot you, please email us !
44 Thanks again (I know, it's really short :)
46 <!-- ----------------------------------------------------------------- -->
49 The authors of GTK+ are:
52 <item>Peter Mattis (petm@xcf.berkeley.edu)
53 <item>Spencer Kimball (spencer@xcf.berkeley.edu)
54 <item>Josh MacDonald (jmacd@xcf.berkeley.edu)
56 GTK+ is distributed under the GNU Library General Public License
58 <!-- ----------------------------------------------------------------- -->
61 GTK+ is a small and efficient widget set designed with the general look
62 and feel of Motif. In reality, it looks much better than Motif. It
63 contains common widgets and some more complex widgets such as a file
64 selection, and color selection widgets.
66 GTK+ provides some unique features. (At least, I know of no other widget
67 library which provides them). For
68 example, a button does not contain a label, it contains a child widget,
69 which in most instances will be a label.
70 However, the child widget can also be a pixmap, image or any combination
71 possible the programmer desires.
72 This flexibility is adhered to throughout the library.
74 <!-- ----------------------------------------------------------------- -->
75 <sect1>What is the + in GTK+?
77 Peter Mattis informed the gtk mailing list that:
79 "I originally wrote gtk which included the three libraries, libglib,
80 libgdk and libgtk. It featured a flat widget hierarchy. That is, you
81 couldn't derive a new widget from an existing one. And it contained
82 a more standard callback mechanism instead of the signal mechanism now
83 present in gtk+. The + was added to distinguish between the original
84 version of gtk and the new version. You can think of it as being an
85 enhancement to the original gtk that adds object oriented features."
88 <!-- ----------------------------------------------------------------- -->
89 <sect1>Does the G in GTK+ stand for General, Gimp, or GNU?
91 Peter Mattis informed the gtk mailing list that:
93 "I think the last time Spencer and I talked about it we decided on
94 GTK = Gimp ToolKit. But I don't know for sure. Its definately not
98 <!-- ----------------------------------------------------------------- -->
99 <sect1>Where is the documentation for GTK+?
101 In the GTK+ distribution's doc/ directory you will find the
102 reference material for both GTK and GDK, this FAQ and the
105 In addition, you can find links to HTML versions of these documents
107 <htmlurl url="http://www.gtk.org/"
108 name="http://www.gtk.org/">.
111 <!-- ----------------------------------------------------------------- -->
112 <sect1>Is there a mailing list (or mailing list archive) for GTK+?
114 There are two mailing lists:
116 <item>A mailing list for discussion of development of GTK based applications
117 is hosted at gtk-app-devel-list@redhat.com. To subscribe send an
118 email message to <htmlurl url="mailto:gtk-app-devel-list-request@redhat.com"
119 name="gtk-app-devel-list-request@redhat.com">
120 with <em>subscribe</em> in the <bf>subject</bf>.
122 <item>A mailing list for discussion of development of GTK is hosted
123 at gtk-list@redhat.com. To subscribe send an
124 email message to <htmlurl url="mailto:gtk-list-request@redhat.com"
125 name="gtk-list-request@redhat.com">
126 with <em>subscribe</em> in the <bf>subject</bf>.
128 A searchable archive of the mailing list can be found at
129 <htmlurl url="http://archive.redhat.com/gtk-list"
130 name="http://archive.redhat.com/gtk-list">
132 <!-- ----------------------------------------------------------------- -->
133 <sect1>The gtk-list hasn't had any traffic for days, is it dead?
135 No, everyone's just busy coding.
137 <!-- ----------------------------------------------------------------- -->
138 <sect1>How to get help with GTK+
140 First, make sure your question isn't answered in the documentation, this
141 FAQ or the tutorial. Done that? You're sure you've done that, right? In
142 that case, the best place to post questions is to the GTK+ mailing list.
144 <!-- ----------------------------------------------------------------- -->
145 <sect1>How to report bugs in GTK+
147 Bug reports should be sent to the GTK+ mailing list.
149 <!-- ----------------------------------------------------------------- -->
150 <sect1>Is there a Windows version of GTK+?
152 There is an on going port of GTK+ to the Windows platform which is
153 making impressive progress.
155 See <htmlurl url="http://www.iki.fi/tml/gimp/win32"
156 name="http://www.iki.fi/tml/gimp/win32"> for more information.
158 <!-- ----------------------------------------------------------------- -->
159 <sect1>What applications have been written with GTK+?
161 A list of some GTK+ based application can be found on the GTK+ web
162 server at <htmlurl url="http://www.gtk.org/apps/"
163 name="http://www.gtk.org/apps/"> and contains more than 350 applications.
167 <item>GIMP (<htmlurl url="http://www.gimp.org/"
168 name="http://www.gimp.org/">),
169 an image manipulation program
170 <item>AbiWord (<htmlurl url="http://www.abisource.com/"
171 name="http://www.abisource.com/">),
172 a professional word processor
173 <item>GUBI (<htmlurl url="http://www.SoftHome.net/pub/users/timj/gubi/index.htm"
174 name="http://www.SoftHome.net/pub/users/timj/gubi/index.htm">),
175 a user interface builder
176 <item>Gzilla (<htmlurl url="http://www.levien.com/gzilla/"
177 name="http://www.levien.com/gzilla/">),
179 <item>SANE (<htmlurl url="http://www.azstarnet.com/~axplinux/sane/"
180 name="http://www.azstarnet.com/~axplinux/sane/"> ),
181 a universal scanner interface
182 <item>XQF (<htmlurl url="http://www.botik.ru/~roma/quake/"
183 name="http://www.botik.ru/~roma/quake/">),
184 a QuakeWorld/Quake2 server browser and launcher
185 <item>ElectricEyes (<htmlurl url="http://www.labs.redhat.com/ee.shtml"
186 name="http://www.labs.redhat.com/ee.shtml">),
187 an image viewer that aims to be a free replacement for xv
188 <item>GPK - the General Proxy Kit (<htmlurl url="http://www.humanfactor.com/gpk/"
189 name="http://www.humanfactor.com/gpk/">),
190 an add-on library to permit thread-safe access to GTK+
191 <item>GCK - the General Convenience Kit (<htmlurl url="http://www.ii.uib.no/~tomb/gck.html"
192 name="http://www.ii.uib.no/~tomb/gck.html">),
193 miscellaneous functions intended to ease color handling, UI construction,
194 vector operations, and math functions
195 <item>GDK Imlib (<htmlurl url="http://www.labs.redhat.com/imlib/"
196 name="http://www.labs.redhat.com/imlib/">),
197 a fast image loading and manipulation library for GDK
198 <item>Glade (<htmlurl url="http://glade.pn.org/"
199 name="http://glade.pn.org/">),
200 a GTK+ based RAD tool which produces GTK+ applications
203 In addition to the above, the GNOME project (<htmlurl url="http://www.gnome.org"
204 name="http://www.gnome.org">)
205 is using GTK+ to build a free desktop for Linux. Many more programs can be found
208 <!-- ----------------------------------------------------------------- -->
209 <sect1>I'm looking for an application to write in GTK+. How about an IRC client?
212 Ask on gtk-list for suggestions. There are at least three IRC
213 clients already under development (probably more in fact. The server at
214 <htmlurl url="http://www.forcix.cx/irc-clients.html"
215 name="http://www.forcix.cx/irc-clients.html"> list a bunch of them).
218 <item>girc. (Included with GNOME)
219 <item>Bezerk (<htmlurl url="http://www.gtk.org/~trog/"
220 name="http://www.gtk.org/~trog/">)
221 <item>gsirc. (In the gnome CVS tree)
224 <!-- ***************************************************************** -->
225 <sect>How to find, configure, install, and troubleshoot GTK+
227 <!-- ***************************************************************** -->
229 <!-- ----------------------------------------------------------------- -->
230 <sect1>What do I need to run GTK+?
232 To compile GTK+, all you need is a C compiler (gcc) and the X Window System
233 and associated libraries on your system.
235 <!-- ----------------------------------------------------------------- -->
236 <sect1>Where can I get GTK+?
238 The canonical site is:
240 ftp://ftp.gtk.org/pub/gtk
242 This site tends to get busy around the time of a new GTK+ release
243 so try and use one of the mirror sites that are listed in
244 <htmlurl url="ftp://ftp.gtk.org/etc/mirrors"
245 name="ftp://ftp.gtk.org/etc/mirrors">
247 Here's a few mirror sites to get you started:
249 <item>Africa - ftp://ftp.is.co.za/applications/gimp/
250 <item>Australia - ftp://ftp.au.gimp.org/pub/gimp/
251 <item>Finland - ftp://ftp.funet.fi/pub/sci/graphics/packages/gimp
252 <item>Germany - ftp://infosoc.uni-koeln.de/pub/ftp.gimp.org/
253 <item>Japan - ftp://SunSITE.sut.ac.jp/pub/archives/packages/gimp/
254 <item>UK - ftp://ftp.flirble.org/pub/X/gimp/
255 <item>US - ftp://ftp.insync.net/pub/mirrors/ftp.gimp.org/
258 <sect1>How do I configure/compile GTK+?
260 Generally, all you will need to do is issue the commands:
265 in the gtk+-version/ directory.
267 <!-- ----------------------------------------------------------------- -->
268 <sect1>When compiling GTK+ I get an error like:
269 <tt/make: file `Makefile' line 456: Syntax error/
271 Make sure that you are using GNU make (use <tt/make -v/ to check). There are
272 many weird and wonderful versions of make out there, and not all of them
273 handle the automatically generated Makefiles.
275 <!-- ----------------------------------------------------------------- -->
277 <sect1>I've compiled and installed GTK+, but I can't get any programs to link with it!
279 This problem is most often encountered when the GTK+ libraries can't be
280 found or are the wrong version. Generally, the compiler will complain about an
281 'unresolved symbol'. There are two things you need to check:
283 <item>Make sure that the libraries can be found. You want to edit
284 /etc/ld.so.conf to include the directories which contain the GTK libraries,
285 so it looks something like:
290 Then you need to run /sbin/ldconfig as root. You can find what directory
296 If your system doesn't use ld.so to find libraries (such as Solaris), then
297 you will have to use the LD_LIBRARY_PATH environment variable (or compile
298 the path into your program, which I'm not going to cover here). So, with a
299 Bourne type shell you can do (if your GTK libraries are in /usr/local/lib):
301 export LD_LIBRARY_PATH=/usr/local/lib
303 and in a csh, you can do:
305 setenv LD_LIBRARY_PATH /usr/local/lib
308 <item>Make sure the linker is finding the correct set of libraries. If you
309 have a Linux distribution that installs GTK+ (e.g. RedHat 5.0) then this
310 older version may be used. Now (assuming you have a RedHat
311 system), issue the command
315 You may also want to remove the packages that depend on gtk (rpm will tell you
316 which ones they are). If you don't have a RedHat Linux system, check to make sure
317 that neither <verb>/usr/lib</verb> or <verb>/usr/local/lib</verb> contain any of
318 the libraries libgtk, libgdk, libglib, or libgck. If they do exist, remove them
319 (and any gtk include files, such as /usr/include/gtk and /usr/include/gdk)
323 <!-- ----------------------------------------------------------------- -->
324 <sect1>When compiling programs with GTK+, I get compiler error messages about not being able to find <tt/"glibconfig.h"/.
326 The header file "glibconfig.h" was moved to the directory
327 $exec_prefix/lib/glib/include/. $exec_prefix is the
328 directory that was specified by giving the --exec-prefix
329 flags to ./configure when compiling GTK+. It defaults to
330 $prefix, (specified with --prefix), which in turn defaults
333 This was done because "glibconfig.h" includes architecture
334 dependent information, and the rest of the include files
335 are put in $prefix/include, which can be shared between different
338 GTK+ includes a shell script, <tt/gtk-config/, that
339 makes it easy to find out the correct include paths.
340 The GTK+ tutorial includes an example of using <tt/gtk-config/
341 for simple compilation from the command line. For information
342 about more complicated configuration, see the file
343 docs/gtk-config.txt in the GTK+ distribution.
345 If you are trying to compile an old program, you may
346 be able to work around the problem by configuring it
347 with a command line like:
350 CPPFLAGS="-I/usr/local/include/glib/include" ./configure
353 for Bourne-compatible shells like bash, or for csh variants:
356 setenv CPPFLAGS "-I/usr/local/include/glib/include"
360 (Substitute the appropriate value of $exec_prefix for /usr/local.)
362 <!-- ----------------------------------------------------------------- -->
363 <sect1>When installing a GTK+ application, configure reports that it can't find GTK.
365 There are several common reasons for this:
367 <item>You have an old version of GTK installed somewhere. RedHat 5.0, for
368 example, installs an older copy of GTK that may not work with the latest
369 applications. You should remove this old copy, but note that in the case
370 of RedHat 5.0 this will break the <tt/control-panel/ applications.
372 <item><tt/gtk-config/ (or another component of GTK) isn't in your path, or
373 there is an old version on your system. Type:
377 to check for both of these. If it returns a value different from what
378 you expect, then you have an old version of GTK on your system.
380 <item>The ./configure script can't find the GTK libraries. As ./configure
381 compiles various test programs, it needs to be able to find the GTK
382 libraries. See the question above for help on this.
385 If none of the above help, then have a look in config.log, which is
386 generated by ./configure as it runs. At the bottom will be the last
387 action it took before failing. If it is a section of source code, copy
388 the source code to a file and compile it with the line just above it in
389 config.log. If the compilation is successful, try executing it.
391 <!-- ***************************************************************** -->
392 <sect>Development of GTK+
393 <!-- ***************************************************************** -->
395 <!-- ----------------------------------------------------------------- -->
396 <sect1>Whats this CVS thing that everyone keeps talking about, and how do I access it?
398 CVS is the Concurent Version System and is a very popular means of
399 version control for software projects. It is designed to allow multiple
400 authors to be able to simultanously operate on the same source tree.
401 This source tree is centrally maintained, but each developer has a
402 local mirror of this repository that they make there changes to.
404 The GTK+ developers use a CVS repository to store the master copy of
405 the current development version of GTK+. As such, people wishing to
406 contribute patches to GTK+ should generate them against the CVS version.
407 Normal people should use the packaged releases.
409 The CVS toolset is available as RPM packages from the usual RedHat sites.
410 The latest version is available at
411 <htmlurl url="http://download.cyclic.com/pub/"
412 name="<http://download.cyclic.com/pub/>">
414 Anyone can download the latest CVS version of GTK+ by using anonymous access
415 using the following steps:
417 <item> In a bourne shell descendant (e.g. bash) type:
419 CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'
422 <item>Next, the first time the source tree is checked out, a cvs login
427 This will ask you for a password. There is no password for cvs.gimp.org,
428 so just enter a carriage return.
429 <item>To get the tree and place it in a subdir of your current working
430 directory, issue the command:
435 Note that with the GTK+ 1.1 tree, glib has been moved to a separate CVS
436 module, so if you don't have glib installed you will need to get that
443 <!-- ----------------------------------------------------------------- -->
444 <sect1>How can I contribute to GTK+?
446 It's simple. If something doesn't work like you think it should in a program,
447 check the documentation to make sure you're not missing something. If it is a
448 true bug or missing feature, track it down in the GTK+ source, change it,
449 and then generate a patch in the form of a 'context diff'. This can be done
450 using a command such as <tt/diff -ru <oldfile> <newfile>/.
451 Then upload the patchfile to:
453 ftp://ftp.gtk.org/incoming
455 along with a README file. Make sure you follow the naming conventions or your
456 patch will just be deleted! The filenames should be of this form:
458 gtk-<username>-<date yymmdd-n>.patch.gz
459 gtk-<username>-<date yymmdd-n>.patch.README
461 The "n" in the date indicates a unique number (starting from 0)
462 of patches you uploaded that day. It should be 0, unless you
463 upload more than one patch in the same day.
467 gtk-gale-982701-0.patch.gz
468 gtk-gale-982701-0.patch.README
470 Once you upload <em>anything</em>, send the README to ftp-admin@gtk.org
472 <!-- ----------------------------------------------------------------- -->
473 <sect1>How do I know if my patch got applied, and if not, why not?
475 Uploaded patches will be moved to <tt>ftp://ftp.gtk.org/pub/gtk/patches</tt>
476 where one of the GTK+ development team will pick them up. If applied, they
477 will be moved to <tt>/pub/gtk/patches/old</tt>.
479 Patches that aren't applied, for whatever reason, are moved to
480 <tt>/pub/gtk/patches/unapplied</tt> or <tt>/pub/gtk/patches/outdated</tt>.
481 At this point you can ask on the <tt/gtk-list/ mailing list why your patch
482 wasn't applied. There are many possible reasons why patches may not be
483 applied, ranging from it doesn't apply cleanly, to it isn't right. Don't
484 be put off if your patch didn't make it first time round.
486 <!-- ----------------------------------------------------------------- -->
487 <sect1>What is the policy on incorporating new widgets into the library?
489 This is up to the authors, so you will have to ask them once you
490 are done with your widget. As a general guideline, widgets that are
491 generally useful, work, and are not a disgrace to the widget set will
494 <!-- ----------------------------------------------------------------- -->
495 <sect1>Is anyone working on bindings for languages other than C?
497 The GTK+ home page (<htmlurl url="http://www.gtk.org/"
498 name="http://www.gtk.org/">) presents a list of GTK+ bindings.
501 <item>There are several C++ wrappers for GTK+.
504 <item>the gtk-- package, which is a very small wrapper for GTK+.
505 You can find the home page at:
506 <htmlurl url="http://www.cs.tut.fi/~p150650/gtk/gtk--.html"
507 name="http://www.cs.tut.fi/~p150650/gtk/gtk--.html">.
509 <htmlurl url="ftp://ftp.gtk.org/pub/gtk/gtk--"
510 name="ftp://ftp.gtk.org/pub/gtk/gtk--">.
512 <item>the VDK package, which was built as the base package of a GTK+
513 application Borland-like builder. The home page can be found at
514 <htmlurl url="www.guest.net/homepages/mmotta/VDKHome"
515 name="www.guest.net/homepages/mmotta/VDKHome">.
517 <item>The wxWindows/Gtk package, a free C++ library for cross-platform
518 GUI development. The home page of this package is
519 <htmlurl url="http://www.freiburg.linux.de/~wxxt/"
520 name="http://www.freiburg.linux.de/~wxxt/">.
525 <item>There are three known Objective-c bindings currently in development:
529 <item>The <htmlurl url="http://www.gnome.org/" name="GNOME project's"> package
530 of choice is objgtk. Objgtk is based on the Object class and is maintained by
531 <htmlurl url="mailto:sopwith@cuc.edu" name="Elliot Lee">. Apparently, objgtk
532 is being accepted as the `standard' Objective-C binding for GTK+.
534 <item>If you are more inclined towards the
535 <htmlurl url="http://www.gnustep.org/" name="GNUstep project">,
536 you may want to check out GTKKit by
537 <htmlurl url="mailto:helge@mdlink.de" name="Helge Heß">.
538 The intention is to setup a GTK+ binding using the FoundationKit.
539 GTKKit includes nicities like writing a XML-type template file to
540 construct a GTK+ interface.
542 <item>The GToolKit package, which can be found at
543 <htmlurl url="ftp://ftp.gtk.org/pub/gtk/objc-gtoolkit/"
544 name="ftp://ftp.gtk.org/pub/gtk/objc-gtoolkit/">.
549 <htmlurl url="ftp://ftp.gtk.org/pub/gtk/perl"
550 name="ftp://ftp.gtk.org/pub/gtk/perl">
552 <item>Guile bindings. The home page is at
553 <htmlurl url="http://www.ping.de/sites/zagadka/guile-gtk"
554 name="http://www.ping.de/sites/zagadka/guile-gtk">.
555 By the way, Guile is the GNU Project's implemention of R4RS Scheme (the
556 standard). If you like Scheme, you may want to take a look at this.
559 <item>David Monniaux reports:
560 <quote>I've started a gtk-O'Caml binding system.
561 The basics of the system, including callbacks, work fine.
563 The current development is in
564 <htmlurl url="http://www.ens-lyon.fr/~dmonniau/arcs"
565 name="http://www.ens-lyon.fr/~dmonniau/arcs">
568 <item> Several python bindings have been done:
572 <htmlurl url="http://www.daa.com.au/~james/pygtk"
573 name="http://www.daa.com.au/~james/pygtk"> and
574 <htmlurl url="ftp://ftp.gtk.org/pub/gtk/python"
575 name="ftp://ftp.gtk.org/pub/gtk/python">
577 <item>python-gtk is at
578 <htmlurl url="http://www.ucalgary.ca/~nascheme/python-gtk"
579 name="http://www.ucalgary.ca/~nascheme/python-gtk">
582 <item>There's are a couple of OpenGL/Mesa widgets available for
583 GTK+. I suggest you start at
584 <htmlurl url="http://www.student.oulu.fi/~jlof/gtkglarea/index.html"
585 name="http://www.student.oulu.fi/~jlof/gtkglarea/index.html">
587 <item>Last, there are a lot of other language bindings for languages such as
588 Eiffel, TOM, Pascal, Pike, etc.
592 <!-- ***************************************************************** -->
593 <sect>Development with GTK+: the begining
594 <!-- ***************************************************************** -->
595 <!-- ----------------------------------------------------------------- -->
596 <sect1>How do I get started?
598 So, after you have installed GTK+ there are a couple of things that can
599 ease you into developing applications with it. There is the
600 GTK+ Tutorial <htmlurl url="http://www.gtk.org/tutorial/"
601 name="<http://www.gtk.org/tutorial/>">, which is undergoing
602 development. This will introduce you to writing applications using C.
604 The Tutorial doesn't (yet) contain information on all of the widgets
605 that are in GTK+. For example code on how to use the basics of all the
606 GTK+ widgets you should look at the file gtk/testgtk.c (and associated
607 source files) within the GTK+ distribution. Looking at these exmaples will
608 give you a good grounding on what the widgets can do.
610 <!-- ----------------------------------------------------------------- -->
611 <sect1>I tried to compile a small <tt/Hello World/ of mine, but it failed. Any clue?
613 Since you are good at coding, we will not deal with compile time error here :).
615 The classic command line to compile a GTK+ based program is
618 gcc -o myprg [c files list] `gtk-config --cflags --libs`
621 You should notice the backquote character which is used in this command line.
622 A common mistake when you start a GTK+ based development is to use quote
623 instead of backquotes. If you do so, the compiler will complain about an
624 unknown file called 'gtk-config --cflags --libs'. The text in
625 backquotes is an instruction to your shell to substitute the output of
626 executing this text into the command line.
628 The command line above ensure that:
631 <item>the correct C compiler flags will be used to compile the program
632 (including the complete C header directory list)
634 <item>your program will be linked with the needed libraries.
638 <sect1>What about using the <tt/make/ utility?
640 This is a sample makefile which compile a GTK+ based program:
643 # basic GTK+ app makefile
644 SOURCES = myprg.c foo.c bar.c
645 OBJS = ${SOURCES:.c=.o}
646 CFLAGS = `gtk-config --cflags`
647 LDADD = `gtk-config --libs`
652 ${CC} -o ${PACKAGE} ${OBJS} ${LDADD}
655 ${CC} ${CFLAGS} -c $<
660 For more information about the <tt/make/ utility, you should read either the
661 related man page or the relevant info file.
663 <sect1>I use the backquote stuff in my makefiles, but my make process failed.
665 The backquote construction seems to not be accepted by some old <tt/make/
666 utilities. If you use one of these, the make process will probably fail.
667 In order to have the backquote syntax working again, you should use the
668 GNU make utility (get it on the GNU ftp server at
669 <htmlurl url="ftp://ftp.gnu.org/" name="ftp://ftp.gnu.org/">).
671 <!-- ----------------------------------------------------------------- -->
672 <sect1>I want to add some configure stuff, how could I do this?
674 To use autoconf/automake, you must first install the relevant packages. These
678 <item>the m4 preprocessor v1.4 or better
679 <item>autoconf v2.13 or better
680 <item>automake v1.4 or better
683 You'll find these packages on the GNU main ftp server (<htmlurl
684 url="ftp://ftp.gnu.org/" name="ftp://ftp.gnu.org/">) or on any GNU mirror.
686 In order to use the powerfull autoconf/automake scheme, you must create
687 a configure.in which may look like:
690 dnl Process this file with autoconf to produce a configure script.
691 dnl configure.in for a GTK+ based program
694 AM_INIT_AUTOMAKE(mypkbname,0.0.1)dnl
695 AM_CONFIG_HEADER(config.h)dnl
697 dnl Checks for programs.
698 AC_PROG_CC dnl check for the c compiler
699 dnl you should add CFLAGS="" here, 'cos it is set to -g by PROG_CC
701 dnl Checks for libraries.
702 AM_PATH_GTK(1.2.0,,AC_MSG_ERROR(mypkgname 0.1 needs GTK))dnl
709 You must add a Makefile.am file:
713 myprg_SOURCES = myprg.c foo.c bar.c
714 INCLUDES = @GTK_CFLAGS@
717 DISTCLEANFILES = .deps/*.P
720 then, to use these, simply type the following commands:
726 automake --add-missing --include-deps --foreign
729 For further informations, you should look at the autoconf and the automake
730 documentation (the shipped info files are really easy to understand, and there
731 are plenty of web resources that deal with autoconf and/or automake).
733 <!-- ----------------------------------------------------------------- -->
734 <sect1>I try to debug my GTK+ application with gdb, but it hangs my X server when I hit some breakpoint. Any Idea ?
736 From Federico Mena Quintero:
738 X is not locked up. It is likely that you are hitting a breakpoint
739 inside a callback that is called from a place in Gtk that has a mouse
742 Run your program with the "--sync" option; it will make it easier to
743 debug. Also, you may want to use the console for running the
744 debugger, and just let the program run in another console with the X
748 Eric Mouw had another solution:
750 An old terminal connected to an otherwise unused serial port is also great
751 for debugging X programs. Old vt100/vt220 terminals are dirt cheap but a
752 bit hard to get (here in The Netherlands, YMMV).
755 <!-- ***************************************************************** -->
756 <sect>Development with GTK+: the programming part
757 <!-- ***************************************************************** -->
758 <!-- ----------------------------------------------------------------- -->
759 <sect1>What widgets are in GTK?
761 The GTK+ Tutorial lists the following widgets:
774 | | | `GtkAspectFrame
779 | | | | `GtkCheckMenuItem
780 | | | | `GtkRadioMenuItem
784 | | +GtkColorSelectionDialog
786 | | | `GtkInputDialog
787 | | `GtkFileSelection
796 | | +GtkColorSelection
847 <!-- ----------------------------------------------------------------- -->
848 <sect1>Is GTK+ thread safe? How do I write multi-threaded GTK+ applications?
850 The GLib library can be used in a thread-safe mode by calling
851 g_thread_init() before making any other GLib calls. In this mode GLib
852 automatically locks all internal data structures as needed. This
853 does not mean that two threads can simultaneously access, for
854 example, a single hash table, but they can access two different hash
855 tables simultaneously. If two different threads need to access the
856 same hash table, the application is responsible for locking
859 When GLib is intialized to be thread-safe, GTK+ is
860 <em>thread aware</em>. There is a single global lock
861 that you must acquire with gdk_threads_enter() before
862 making any GDK calls, and release with gdk_threads_leave()
865 A minimal main program for a threaded GTK+ application
870 main (int argc, char *argv[])
875 gtk_init(&argc, &argv);
877 window = create_window();
878 gtk_widget_show(window);
888 Callbacks require a bit of attention. Callbacks from GTK+
889 (signals) are made within the GTK+ lock. However callbacks
890 from GLib (timeouts, IO callbacks, and idle functions)
891 are made outside of the GTK+ lock. So, within a signal
892 handler you do not need to call gdk_threads_enter(), but
893 within the other types of callbacks, you do.
895 <!-- This is the old answer - TRG
898 Although GTK+, like many X toolkits, isn't thread safe, this does
899 not prohibit the development of multi-threaded applications with
902 Rob Browning (rlb@cs.utexas.edu) describes threading techniques for
903 use with GTK+ (slightly edited):
905 There are basically two main approaches, the first is simple, and the
906 second complicated. In the first, you just make sure that all GTK+ (or
907 X) interactions are handled by one, and
908 only one, thread. Any other thread that wants to draw something has
909 to somehow notify the "GTK+" thread, and let it handle the
912 The second approach allows you to call GTK+ (or X) functions from any
913 thread, but it requires some careful synchronization. The
914 basic idea is that you create an X protection mutex, and no one may
915 make any X calls without first acquiring this mutex.
917 Note that this is a little effort, but it allows you to be
918 potentially more efficient than a completely thread safe GTK+. You
919 get to decide the granularity of the thread locking. You also have to
920 make sure that the thread that calls <tt/gtk_main()/ is holding the lock when
921 it calls <tt/gtk_main()/.
923 The next thing to worry about is that since you were holding the
924 global mutex when you entered <tt/gtk_main()/, all callbacks will also be
925 holding it. This means that the callback must release it if it's
926 going to call any other code that might reacquire it. Otherwise
927 you'll get deadlock. Also, you must be holding the mutex when you
928 finally return from the callback.
930 In order to allow threads other than the one calling <tt/gtk_main/ to
931 get access to the mutex, we also need to register a work function
932 with GTK that allows us to release the mutex periodically.
934 Why can't GTK+ be thread safe by default?
936 Complexity, overhead, and manpower. The proportion of threaded
937 programs is still reasonably small, and getting thread safety right is
938 both quite difficult and takes valuable time away from the main work
939 of getting a good graphics library finished. It would be nice to have
940 GTK+ thread safe "out of the box", but that's not practical right now,
941 and it also might make GTK+ substantially less efficient if not handled
944 Regardless, it's especially not a priority since relatively good
945 workarounds exist. -->
947 <!-- ----------------------------------------------------------------- -->
948 <sect1>How do I find out about the selection of a GtkList?
951 Get the selection something like this:
954 sel = GTK_LIST(list)->selection;
957 This is how GList is defined (quoting glist.h):
959 typedef struct _GList GList;
969 A GList structure is just a simple structure for doubly linked lists.
970 there exist several g_list_*() functions to modify a linked list in
971 glib.h. However the GTK_LIST(MyGtkList)->selection is maintained
972 by the gtk_list_*() functions and should not be modified.
974 The selection_mode of the GtkList determines the selection
975 facilities of a GtkList and therefore the contents
976 of GTK_LIST(AnyGtkList)->selection:
979 selection_mode GTK_LIST()->selection contents
980 ------------------------------------------------------
982 GTK_SELECTION_SINGLE) selection is either NULL
983 or contains a GList* pointer
984 for a single selected item.
986 GTK_SELECTION_BROWSE) selection is NULL if the list
987 contains no widgets, otherwise
988 it contains a GList* pointer
989 for one GList structure.
990 GTK_SELECTION_MULTIPLE) selection is NULL if no listitems
991 are selected or a a GList* pointer
992 for the first selected item. that
993 in turn points to a GList structure
994 for the second selected item and so
997 GTK_SELECTION_EXTENDED) selection is NULL.
1000 The data field of the GList structure GTK_LIST(MyGtkList)->selection points
1001 to the first GtkListItem that is selected. So if you would like to determine
1002 which listitems are selected you should go like this:
1004 Upon Initialization:
1007 gchar *list_items[]={
1013 guint nlist_items=sizeof(list_items)/sizeof(list_items[0]);
1014 GtkWidget *list_item;
1017 list=gtk_list_new();
1018 gtk_list_set_selection_mode(GTK_LIST(list), GTK_SELECTION_MULTIPLE);
1019 gtk_container_add(GTK_CONTAINER(AnyGtkContainer), list);
1020 gtk_widget_show (list);
1022 for (i = 0; i < nlist_items; i++)
1024 list_item=gtk_list_item_new_with_label(list_items[i]);
1025 gtk_object_set_user_data(GTK_OBJECT(list_item), (gpointer)i);
1026 gtk_container_add(GTK_CONTAINER(list), list_item);
1027 gtk_widget_show(list_item);
1032 To get known about the selection:
1037 items=GTK_LIST(list)->selection;
1039 printf("Selected Items: ");
1041 if (GTK_IS_LIST_ITEM(items->data))
1042 printf("%d ", (guint)
1043 gtk_object_get_user_data(items->data));
1050 <!-- ----------------------------------------------------------------- -->
1051 <sect1>How can I prevent redrawing and resizing while I change multiple widgets?
1053 Old versions of GTK+ used to provide the <tt/gtk_container_enable_resize()/ and
1054 <tt/gtk_container_disable_resize()/ functions to enable or disable the resize while
1057 In the current version of GTK+, there is no more need for these functions,
1058 since GTK+ will only resize widget during idle.
1060 <!-- XXX should we get rid of this one ? -->
1062 <!-- ----------------------------------------------------------------- -->
1063 <sect1>How do I catch a double click event (in a list widget, for example)?
1065 Tim Janik wrote to gtk-list (slightly modified):
1067 Define a signal handler:
1071 signal_handler_event(GtkWiget *widget, GdkEvenButton *event, gpointer func_data)
1073 if (GTK_IS_LIST_ITEM(widget) &&
1074 (event->type==GDK_2BUTTON_PRESS ||
1075 event->type==GDK_3BUTTON_PRESS) ) {
1076 printf("I feel %s clicked on button %d\",
1077 event->type==GDK_2BUTTON_PRESS ? "double" : "triple",
1085 And connect the handler to your object:
1089 /* list, list item init stuff */
1091 gtk_signal_connect(GTK_OBJECT(list_item),
1092 "button_press_event",
1093 GTK_SIGNAL_FUNC(signal_handler_event),
1098 gtk_signal_connect(GTK_OBJECT(list_item),
1099 "button_release_event",
1100 GTK_SIGNAL_FUNC(signal_handler_event),
1103 /* something else */
1107 and, Owen Taylor wrote:
1109 Note that a single button press will be received beforehand, and
1110 if you are doing this for a button, you will therefore also get a
1111 "clicked" signal for the button. (This is going to be true for
1112 any toolkit, since computers aren't good at reading one's
1115 <!-- ----------------------------------------------------------------- -->
1116 <sect1>By the way, what are the differences between signals and events?
1118 First of all, Havoc Pennington gives a rather complete description of the
1119 differences between events and signals in his free book (two chapters can
1120 be found at <htmlurl url="http://www106.pair.com/rhp/sample_chapters.html"
1121 name="http://www106.pair.com/rhp/sample_chapters.html">).
1123 Moreover, Havoc posted this to the <tt/gtk-list/
1125 Events are a stream of messages received from the X server. They drive the
1126 Gtk main loop; which more or less amounts to "wait for events, process
1127 them" (not exactly, it is really more general than that and can wait on
1128 many different input streams at once). Events are a Gdk/Xlib concept.
1130 Signals are a feature of GtkObject and its subclasses. They have nothing
1131 to do with any input stream; really a signal is just a way to keep a list
1132 of callbacks around and invoke them ("emit" the signal). There are lots of
1133 details and extra features of course. Signals are emitted by object
1134 instances, and are entirely unrelated to the Gtk main loop.
1135 Conventionally, signals are emitted "when something changes" about the
1136 object emitting the signal.
1138 Signals and events only come together because GtkWidget happens to emit
1139 signals when it gets events. This is purely a convenience, so you can
1140 connect callbacks to be invoked when a particular widget receives a
1141 particular event. There is nothing about this that makes signals and
1142 events inherently related concepts, any more than emitting a signal when
1143 you click a button makes button clicking and signals related concepts.
1146 <!-- ----------------------------------------------------------------- -->
1147 <sect1>I have my signal connected to the the (whatever) event, but it seems I don't catch it. What's wrong?
1149 There is some special initialisation to do in order to catch some
1150 particular events. In fact, you must set the correct event mask bit of your
1151 widget before getting some particular events.
1156 gtk_widget_add_events(window, GDK_KEY_RELEASE_MASK);
1159 lets you catch the key release events. If you want to catch every events,
1160 simply us the GDK_ALL_EVENTS_MASK event mask.
1162 All the event masks are defined in the <tt/gdktypes.h/ file.
1164 <!-- ----------------------------------------------------------------- -->
1165 <sect1>Is it possible to get some text displayed which is truncated to fit inside its allocation?
1167 GTK's behavior (no clipping) is a consequence of its attempts to
1168 conserve X resources. Label widgets (among others) don't get their own
1169 X window - they just draw their contents on their parent's window.
1170 While it might be possible to have clipping occur by setting the clip
1171 mask before drawing the text, this would probably cause a substantial
1172 performance penalty.
1174 Its possible that, in the long term, the best solution to such
1175 problems might be just to change gtk to give labels X windows.
1176 A short term workaround is to put the label widget inside another
1177 widget that does get it's own window - one possible candidate would
1178 be the viewport widget.
1181 viewport = gtk_viewport (NULL, NULL);
1182 gtk_widget_set_usize (viewport, 50, 25);
1183 gtk_viewport_set_shadow_type (GTK_VIEWPORT(viewport), GTK_SHADOW_NONE);
1184 gtk_widget_show(viewport);
1186 label = gtk_label ("a really long label that won't fit");
1187 gtk_container_add (GTK_CONTAINER(viewport), label);
1188 gtk_widget_show (label);
1191 If you were doing this for a bunch of widgets, you might want to
1192 copy gtkviewport.c and strip out the adjustment and shadow
1193 functionality (perhaps you could call it GtkClipper).
1195 <!-- ----------------------------------------------------------------- -->
1196 <sect1>How can I define a separation line in a menu?
1198 See the <htmlurl url="http://www.gtk.org/tutorial/"
1199 name="Tutorial"> for information on how to create menus.
1200 However, to create a separation line in a menu, just insert an
1204 menuitem = gtk_menu_item_new();
1205 gtk_menu_append(GTK_MENU(menu), menuitem);
1206 gtk_widget_show(menuitem);
1209 <!-- ----------------------------------------------------------------- -->
1210 <sect1>How can I right justify a menu, such as Help?
1212 Depending on if you use the MenuFactory or not, there are two ways to proceed.
1213 With the MenuFactory, use something like the following:
1216 menu_path = gtk_menu_factory_find (factory, "<MyApp>/Help");
1217 gtk_menu_item_right_justify(menu_path->widget);
1220 If you do not use the MenuFactory, you should simply use:
1223 gtk_menu_item_right_justify(my_menu_item);
1226 <!-- ----------------------------------------------------------------- -->
1227 <sect1>How do I add some underlined accelerators to menu items?
1229 Damon Chaplin, the technical force behind the Glade project, provided the
1230 following code sample (this code is an output from Glade). It creates a
1231 small <tt/File/ menu item with only one child (<tt/New/). The F in <tt/File/
1232 and the N in <tt/New/ are underlined, and the relevant accelerators are
1236 menubar1 = gtk_menu_bar_new ();
1237 gtk_object_set_data (GTK_OBJECT (window1), "menubar1", menubar1);
1238 gtk_widget_show (menubar1);
1239 gtk_box_pack_start (GTK_BOX (vbox1), menubar1, FALSE, FALSE, 0);
1241 file1 = gtk_menu_item_new_with_label ("");
1242 tmp_key = gtk_label_parse_uline (GTK_LABEL (GTK_BIN (file1)->child),
1244 gtk_widget_add_accelerator (file1, "activate_item", accel_group,
1245 tmp_key, GDK_MOD1_MASK, 0);
1246 gtk_object_set_data (GTK_OBJECT (window1), "file1", file1);
1247 gtk_widget_show (file1);
1248 gtk_container_add (GTK_CONTAINER (menubar1), file1);
1250 file1_menu = gtk_menu_new ();
1251 file1_menu_accels = gtk_menu_ensure_uline_accel_group (GTK_MENU (file1_menu));
1252 gtk_object_set_data (GTK_OBJECT (window1), "file1_menu", file1_menu);
1253 gtk_menu_item_set_submenu (GTK_MENU_ITEM (file1), file1_menu);
1255 new1 = gtk_menu_item_new_with_label ("");
1256 tmp_key = gtk_label_parse_uline (GTK_LABEL (GTK_BIN (new1)->child),
1258 gtk_widget_add_accelerator (new1, "activate_item", file1_menu_accels,
1260 gtk_object_set_data (GTK_OBJECT (window1), "new1", new1);
1261 gtk_widget_show (new1);
1262 gtk_container_add (GTK_CONTAINER (file1_menu), new1);
1265 <!-- ----------------------------------------------------------------- -->
1266 <sect1>How do I make my window modal? / How do I make a single window active?
1268 After you create your window, do <tt/gtk_grab_add(my_window)/. And after
1269 closing the window do <tt/gtk_grab_remove(my_window)/.
1271 <!-- ----------------------------------------------------------------- -->
1272 <sect1>Why doesn't my widget (e.g. progressbar) update?
1275 You are probably doing all the changes within a function
1276 without returning control to <tt/gtk_main()/. This may be the case if you do some
1277 lengthy calculation in your code. Most drawing updates are only
1278 placed on a queue, which is processed within <tt/gtk_main()/. You can
1279 force the drawing queue to be processed using something like:
1282 while (gtk_events_pending())
1283 gtk_main_iteration();
1286 inside you're function that changes the widget.
1288 What the above snippet does is run all pending events and high priority
1289 idle functions, then return immediately (the drawing is done in a
1290 high priority idle function).
1292 <!-- ----------------------------------------------------------------- -->
1293 <sect1>How do I attach data to some GTK+ object/widget?
1295 First of all, the attached data is stored in the object_data field of a
1296 GtkObject. The type of this field is GData, which is defined in glib.h.
1297 So you should read the gdataset.c file in your glib source directory very
1300 There are two (easy) ways to attach some data to a gtk object.
1301 Using <tt/gtk_object_set_data()/ and <tt/gtk_object_get_data()/ seems to be the
1302 most common way to do this, as it provides a powerfull interface
1303 to connect objects and data.
1306 void gtk_object_set_data(GtkObject *object, const gchar *key, gpointer data);
1307 gpointer gtk_object_get_data(GtkObject *object, const gchar *key);
1310 Since a short example is better than any lengthy speech:
1313 struct my_struct p1,p2,*result;
1316 gtk_object_set_data(GTK_OBJECT(w),"p1 data",(gpointer)&p1);
1317 gtk_object_set_data(GTK_OBJECT(w),"p2 data",(gpointer)&p2);
1319 result = gtk_object_get_data(GTK_OBJECT(w),"p1 data");
1322 The <tt/gtk_object_set_user_data()/ and <tt/gtk_object_get_user_data()/
1323 functions does exactly the same thing
1324 as the functions above, but does not let you specify the "key" parameter.
1325 Instead, it uses a standard "user_data" key. Note that the use of these
1326 functions is deprecated in 1.2. They only provide a compatibility mode
1327 with some old gtk packages.
1329 <!-- ----------------------------------------------------------------- -->
1330 <sect1>How do I remove the data I have attached to an object?
1332 When attaching the data to the object, you can use the
1333 <tt/gtk_object_set_data_full()/
1334 function. The three first arguments of the function are the same as in
1335 <tt/gtk_object_set_data()/. The fourth one is a pointer to a callback function
1336 which is called when the data is destroyed. The data is destroyed when
1340 <item> destroy the object
1341 <item> replace the data with a new one (with the same key)
1342 <item> replace the data with NULL (with the same key)
1345 <!-- ----------------------------------------------------------------- -->
1346 <sect1>How do I right (or otherwise) justify a label?
1348 Are you sure you want to <em>justify</em> the labels? The label class contains
1349 the <tt/gtk_label_set_justify()/ function that is used to control the
1350 justification of a multi-line label.
1352 What you probably want is to set the <em>alignment</em> of the label, ie right
1353 align it, center it or left align it. If you want to do this, you
1357 void gtk_misc_set_alignment (GtkMisc *misc,
1362 where the <tt/xalign/ and <tt/yalign/ values are floats in [0.00;1.00].
1367 /* horizontal : left align, vertical : top */
1368 gtk_misc_set_alignment(GTK_MISK(label), 0.0f, 0.0f);
1370 /* horizontal : centered, vertical : centered */
1371 gtk_misc_set_alignment(GTK_MISK(label), 0.5f, 0.5f);
1373 /* horizontal : right align, vertical : bottom */
1374 gtk_misc_set_alignment(GTK_MISK(label), 1.0f, 1.0f);
1377 <!-- ----------------------------------------------------------------- -->
1378 <sect1>How could I get any widget position?
1380 As Tim Janik pointed out, there are different cases, and each case requires
1381 a different solution.
1384 <item> If you want the position of a widget relative to its parent, you should
1385 use <tt/widget->allocate.x/ and <tt/widget->allocate.y/.
1386 <item> If you want the position of a window relative to the X root window,
1387 you should use <tt/gdk_window_get_geometry()/ or
1388 <tt/gdk_window_get_origin()/.
1389 <item> Last but not least, if you want to get a Window Manager frame position,
1390 you should use <tt/gdk_window_get_deskrelative_origin()/.
1393 <!-- ----------------------------------------------------------------- -->
1394 <sect1>How do I set the position/size of a widget/window?
1396 The <tt/gtk_widget_set_uposition()/ function is used to set the
1397 position of any widget.
1399 The <tt/gtk_widget_set_usize()/ function is used to set the
1400 size of a widget. In order to use all the features that are provided by
1401 this function when it acts on a window, you may want to use the
1402 <tt/gtk_window_set_policy/ function. The definition of this function
1406 void gtk_window_set_policy (GtkWindow *window,
1412 <tt/Auto_shrink/ will automatically shrink the window when the
1413 requested size of the child widgets goes below the current size of the
1414 window. <tt/Allow_shrink/ will give the user the authorisation to
1415 make the window smaller that it should normally be. <tt/Allow_grow/
1416 will give the user will have the ability to make the window
1417 bigger. The default values for these parameters are:
1420 allow_shrink = FALSE
1425 <!-- ----------------------------------------------------------------- -->
1426 <sect1>How do I add a popup menu to my GTK+ application?
1428 The <tt/menu/ example in the examples/menu directory of the GTK+ distribution
1429 implements a popup menu with this technique :
1432 static gint button_press (GtkWidget *widget, GdkEvent *event)
1435 if (event->type == GDK_BUTTON_PRESS) {
1436 GdkEventButton *bevent = (GdkEventButton *) event;
1437 gtk_menu_popup (GTK_MENU(widget), NULL, NULL, NULL, NULL,
1438 bevent->button, bevent->time);
1439 /* Tell calling code that we have handled this event; the buck
1444 /* Tell calling code that we have not handled this event; pass it on. */
1449 <!-- ----------------------------------------------------------------- -->
1450 <sect1>How do I disable or enable a widget, such as a button?
1452 To disable (or to enable) a widget, use the <tt/gtk_widget_set_sensitive()/
1453 function. The first parameter is you widget pointer. The second parameter
1454 is a boolean value: when this value is TRUE, the widget is enabled.
1456 <!-- ----------------------------------------------------------------- -->
1457 <sect1>How do I set the cursor position in a GtkText object?
1459 Notice that the response is valid for any object that inherits from the
1462 Are you sure that you want to move the cursor position? Most of the time,
1463 while the cursor position is good, the insertion point does not match the
1464 cursor position. If this apply to what you really want, then you should use
1465 the <tt/gtk_text_set_point()/ function. If you want to set the insertion point
1466 at the current cursor position, use the following:
1469 gtk_text_set_point(GTK_TEXT(text),
1470 gtk_editable_get_position(GTK_EDITABLE(text)));
1473 If you want the insertion point to follow the cursor at all time, you
1474 should probably catch the button press event, and then move the
1475 insertion point. Be careful : you'll have to catch it after the widget
1476 has changed the cursor position though. Thomas Mailund Jensen proposed the
1481 insert_bar (GtkWidget *text)
1483 /* jump to cursor mark */
1484 gtk_text_set_point (GTK_TEXT (text),
1485 gtk_editable_get_position (GTK_EDITABLE (text)));
1487 gtk_text_insert (GTK_TEXT (text), NULL, NULL, NULL,
1488 "bar", strlen ("bar"));
1492 main (int argc, char *argv[])
1494 GtkWidget *window, *text;
1496 gtk_init (&argc, &argv);
1498 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
1499 text = gtk_text_new (NULL, NULL);
1500 gtk_text_set_editable (GTK_TEXT (text), TRUE);
1501 gtk_container_add (GTK_CONTAINER (window), text);
1503 /* connect after everything else */
1504 gtk_signal_connect_after (GTK_OBJECT(text), "button_press_event",
1505 GTK_SIGNAL_FUNC (insert_bar), NULL);
1507 gtk_widget_show_all(window);
1514 Now, if you really want to change the cursor position, you should use the
1515 <tt/gtk_editable_set_position()/ function.
1517 <!-- ***************************************************************** -->
1518 <sect>Development with GTK+: misc questions
1519 <!-- ***************************************************************** -->
1520 <!-- ----------------------------------------------------------------- -->
1521 <sect1>Why do this strange 'x io error' occur when I <tt/fork()/ in my GTK+ app?
1523 This is not really a GTK+ problem, and the problem is not related to <tt/fork()/
1524 too. If the 'x io error' occurs then you probably use the <tt/exit()/ function
1525 in order to exit from the child process.
1527 When GDK opens an X display, it creates a socket file descriptor. When you use
1528 the <tt/exit()/ function, you implicitly close all the open file descriptors,
1529 and the underlying X library really doesn't like this.
1531 The right function to use here is <tt/_exit()/.
1533 Eric Mouw gave the following piece of code about the fork()/exit() problem
1544 else if(pid==0) /* child */
1546 retval=system("a command"); /* can use exec* functions here */
1547 _exit(retval); /* notice _exit() instead of exit() */
1553 if(waitpid(pid, &status, WNOHANG) == pid)
1555 waitpid(pid, &status, WUNTRACED); /* anti zombie code */
1560 return(WEXITSTATUS(status));
1564 <!-- ----------------------------------------------------------------- -->
1565 <sect1>I can't add more than (something like) 2000 chars in a GtkEntry. What's wrong?
1567 There is now a known problem in the GtkEntry widget. In the
1568 <tt/gtk_entry_insert_text()/ function, the following lines limit
1569 the number of chars in the entry to 2047.
1572 /* The algorithms here will work as long as, the text size (a
1573 * multiple of 2), fits into a guint16 but we specify a shorter
1574 * maximum length so that if the user pastes a very long text, there
1575 * is not a long hang from the slow X_LOCALE functions. */
1577 if (entry->text_max_length == 0)
1580 max_length = MIN (2047, entry->text_max_length);
1583 <!-- ----------------------------------------------------------------- -->
1584 <sect1>Why don't the contents of a button move when the button is pressed? Here's a patch to make it work that way...
1589 The reason buttons don't move their child down and to the right when
1590 they are depressed is because I don't think that's what is happening
1591 visually. My view of buttons is that you are looking at them straight
1592 on. That is, the user interface lies in a plane and you're above it
1593 looking straight at it. When a button gets pressed it moves directly
1594 away from you. To be absolutely correct I guess the child should
1595 actually shrink a tiny amount. But I don't see why the child should
1596 shift down and to the left. Remember, the child is supposed to be
1597 attached to the buttons surface. Its not good for it to appear like
1598 the child is slipping on the surface of the button.
1600 On a more practical note, I did implement this at one point and
1601 determined it didn't look good and removed it.
1604 <!-- ***************************************************************** -->
1606 <!-- ***************************************************************** -->
1608 <!-- ----------------------------------------------------------------- -->
1611 GDK is basically a wrapper around the standard Xlib function calls. If you are
1612 at all familiar with Xlib, a lot of the functions in GDK will require little
1613 or no getting used to. All functions are written to provide an way
1614 to access Xlib functions in an easier and slightly more intuitive manner.
1615 In addition, since GDK uses GLib (see below), it will be more portable
1616 and safer to use on multiple platforms.
1618 <!-- Examples, anybody? I've been mulling some over. NF -->
1620 <sect1>How do I use color allocation?
1622 One of the nice things about GDK is that it's based on top of Xlib; this is
1623 also a problem, especially in the area of color management. If you want
1624 to use color in your program (drawing a rectangle or such, your code
1625 should look something like this:
1636 /* first, create a GC to draw on */
1637 gc = gdk_gc_new(widget->window);
1639 /* find proper dimensions for rectangle */
1640 gdk_window_get_size(widget->window, &width, &height);
1642 /* the color we want to use */
1643 color = (GdkColor *)malloc(sizeof(GdkColor));
1645 /* red, green, and blue are passed values, indicating the RGB triple
1646 * of the color we want to draw. Note that the values of the RGB components
1647 * within the GdkColor are taken from 0 to 65535, not 0 to 255.
1649 color->red = red * (65535/255);
1650 color->green = green * (65535/255);
1651 color->blue = blue * (65535/255);
1653 /* the pixel value indicates the index in the colormap of the color.
1654 * it is simply a combination of the RGB values we set earlier
1656 color->pixel = (gulong)(red*65536 + green*256 + blue);
1658 /* However, the pixel valule is only truly valid on 24-bit (TrueColor)
1659 * displays. Therefore, this call is required so that GDK and X can
1660 * give us the closest color available in the colormap
1662 gdk_color_alloc(gtk_widget_get_colormap(widget), color);
1664 /* set the foreground to our color */
1665 gdk_gc_set_foreground(gc, color);
1667 /* draw the rectangle */
1668 gdk_draw_rectangle(widget->window, gc, 1, 0, 0, width, height);
1675 <!-- ***************************************************************** -->
1677 <!-- ***************************************************************** -->
1679 <!-- ----------------------------------------------------------------- -->
1680 <sect1>What is GLib?
1682 GLib is a library of useful functions and definitions available for use
1683 when creating GDK and GTK applications. It provides replacements for some
1684 standard libc functions, such as malloc, which are buggy on some systems.
1686 It also provides routines for handling:
1688 <item>Doubly Linked Lists
1689 <item>Singly Linked Lists
1691 <item>String Handling
1692 <item>A Lexical Scanner
1693 <item>Error Functions
1696 <!-- ----------------------------------------------------------------- -->
1697 <sect1>How can I use the doubly linked lists?
1699 The GList object is defined as:
1702 typedef struct _GList GList;
1712 To use the GList objects, simply :
1717 gint array[] = { 1, 2, 3, 4, 5, 6 };
1721 /* add data to the list */
1722 for (pos=0;pos < sizeof array; pos++) {
1723 list = g_list_append(list, (gpointer)&array[pos]);
1726 /* run through the list */
1727 listrunner = g_list_first(list);
1728 while (listrunner) {
1729 value = (gint *)listrunner->data;
1730 printf("%d\n", *value);
1731 listrunner = g_list_next(listrunner);
1734 /* removing datas from the list */
1735 listrunner = g_list_first(list);
1736 list = g_list_remove_link(list, listrunner);
1737 list = g_list_remove(list, &array[4]);
1740 The same code is usable with singly linked lists (GSList objects) by replacing
1741 g_list_* functions with the relevant g_slist_* ones (g_slist_append,
1742 g_slist_remove, ...). Just remember that since you can't go backward in a singly
1743 linked list, there is no g_slist_first function - you'll need to keep a
1744 reference on the first node of the list.
1746 <!-- Some Examples might be useful here! NF -->
1747 <!-- I believe it should be better :) ED -->
1748 <!-- Linked lists are pretty standard data structures - don't want to
1749 over do it - TRG -->
1750 <!-- ----------------------------------------------------------------- -->
1751 <sect1>Why use g_print, g_malloc, g_strdup and fellow glib functions?
1753 Thanks to Tim Janik who wrote to gtk-list: (slightly modified)
1755 Regarding g_malloc(), g_free() and siblings, these functions are much safer
1756 than their libc equivalents. For example, g_free() just returns if called
1757 with NULL. Also, if USE_DMALLOC is defined, the definition for these
1758 functions changes (in glib.h) to use MALLOC(), FREE() etc... If MEM_PROFILE
1759 or MEM_CHECK are defined, there are even small statistics made counting
1760 the used block sizes (shown by g_mem_profile() / g_mem_check()).
1762 Considering the fact that glib provides an interface for memory chunks
1763 to save space if you have lots of blocks that are always the same size
1764 and to mark them ALLOC_ONLY if needed, it is just straight forward to
1765 create a small saver (debug able) wrapper around the normal malloc/free
1766 stuff as well - just like gdk covers Xlib. ;)
1768 Using g_error() and g_warning() inside of applications like the GIMP
1769 that fully rely on gtk even gives the opportunity to pop up a window
1770 showing the messages inside of a gtk window with your own handler
1771 (by using g_set_error_handler()) along the lines of <tt/gtk_print()/
1772 (inside of gtkmain.c).
1775 <!-- ***************************************************************** -->
1776 <sect>GTK+ FAQ Contributions, Maintainers and Copyright
1778 If you would like to make a contribution to the FAQ, send either one of us
1779 an e-mail message with the exact text you think should be included (question and
1780 answer). With your help, this document can grow and become more useful!
1782 This document is maintained by Nathan Froyd
1783 <htmlurl url="mailto:maestrox@geocities.com"
1784 name="<maestrox@geocities.com>">,
1785 Tony Gale <htmlurl url="mailto:gale@gimp.org"
1786 name="<gale@gimp.org>"> and
1787 Emmanuel Deloget <htmlurl url="mailto:pixel@epita.fr"
1788 name="<pixel@epita.fr>">.
1789 This FAQ was created by Shawn T. Amundson
1790 <htmlurl url="mailto:amundson@gimp.org"
1791 name="<amundson@gimp.org>"> who continues to provide support.
1793 The GTK+ FAQ is Copyright (C) 1997,1998, 1999 by Shawn T. Amundson,
1794 Nathan Froyd and Tony Gale, Emmanuel Deloget.
1796 Permission is granted to make and distribute verbatim copies of
1797 this manual provided the copyright notice and this permission notice
1798 are preserved on all copies.
1800 Permission is granted to copy and distribute modified versions of
1801 this document under the conditions for verbatim copying, provided
1802 that this copyright notice is included exactly as in the original,
1803 and that the entire resulting derived work is distributed under
1804 the terms of a permission notice identical to this one.
1806 Permission is granted to copy and distribute translations of
1807 this document into another language, under the above conditions
1808 for modified versions.
1810 If you are intending to incorporate this document into a published work,
1811 please contact one of the maintainers, and we will make an effort to ensure
1812 that you have the most up to date information available.
1814 There is no guarentee that this document lives up to its intended
1815 purpose. This is simply provided as a free resource. As such,
1816 the authors and maintainers of the information provided within can
1817 not make any guarentee that the information is even accurate.