path: root/docs/faq/gtk-faq.sgml

<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []>
<book>

  <bookinfo>
    <date>June 28th 2000</date>
    <title>GTK+ FAQ</title>
    <authorgroup>
      <author>
	<firstname>Tony</firstname>
	<surname>Gale</surname>
      </author>
      <author>
	<firstname>Shawn</firstname>
	<surname>Amundson</surname>
      </author>
      <author>
	<firstname>Emmanuel</firstname>
	<surname>Deloget</surname>
      </author>
    </authorgroup>
    <abstract>
      <para> This document is intended to answer questions that are
      likely to be frequently asked by programmers using GTK+ or
      people who are just looking at using GTK+. </para>
    </abstract>
  </bookinfo>

  <toc></toc>

  <!-- ***************************************************************** -->
  <chapter>
    <title>General Information</title>
    <para>Here's a paragraph of text because it is stylistically poor
    to start a section right after the chapter title.</para>
    <sect1>
      <title></title>

      <!-- ----------------------------------------------------------------- -->

      <sect2>
	<title>Before anything else: the greetings</title>
	<para>The FAQ authors want to thank:</para>
	<itemizedlist spacing=Compact>
	  <listitem>
	    <simpara>Havoc Pennington</simpara>
	  </listitem>
	  <listitem>
	    <simpara>Erik Mouw</simpara>
	  </listitem>
	  <listitem>
	    <simpara>Owen Taylor</simpara>
	  </listitem>
	  <listitem>
	    <simpara>Tim Janik</simpara>
	  </listitem>
	  <listitem>
	    <simpara>Thomas Mailund Jensen</simpara>
	  </listitem>
	  <listitem>
	    <simpara>Joe Pfeiffer</simpara>
	  </listitem>
	  <listitem>
	    <simpara>Andy Kahn</simpara>
	  </listitem>
	  <listitem>
	    <simpara>Federico Mena Quntero</simpara>
	  </listitem>
	  <listitem>
	    <simpara>Damon Chaplin</simpara>
	  </listitem>
	  <listitem>
	    <simpara>and all the members of the GTK+ lists</simpara>
	  </listitem></itemizedlist>
	<para> If we forgot you, please email us! Thanks again (I know,
	  it's really short :) </para>
      </sect2>
      
      <!-- ----------------------------------------------------------------- -->
      
      <sect2>
	<title>Authors</title>
	<para>The original authors of GTK+ were:</para>
	<itemizedlist spacing=Compact>
	  <listitem>
	    <simpara>Peter Mattis</simpara>
	  </listitem>
	  <listitem>
	    <simpara>Spencer Kimball</simpara>
	  </listitem>
	  <listitem>
	    <simpara>Josh MacDonald</simpara>
	  </listitem>
	</itemizedlist>
	<para>Since then, much has been added by others. Please see the
              AUTHORS file in the distribution for the GTK+ Team.</para>
      </sect2>

      <!-- ----------------------------------------------------------------- -->

      <sect2>
	<title>What is GTK+?</title>
	<para>GTK+ is a small and efficient widget set designed with
	the general look and feel of Motif.  In reality, it looks much
	better than Motif.  It contains common widgets and some more
	complex widgets such as a file selection, and color selection
	widgets.</para>
	<para>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.</para>
      </sect2>

      <!-- ----------------------------------------------------------------- -->

      <sect2>
	<title>What is the + in GTK+?</title>
	<para>Peter Mattis informed the gtk mailing list that:</para>
	<para><quote>I originally wrote gtk which included the three
	libraries, libglib, libgdk and libgtk. It featured a flat
	widget hierarchy. That is, you couldn't derive a new widget
	from an existing one. And it contained a more standard
	callback mechanism instead of the signal mechanism now present
	in gtk+. The + was added to distinguish between the original
	version of gtk and the new version. You can think of it as
	being an enhancement to the original gtk that adds object
	oriented features.</quote></para>
      </sect2>

      <!-- ----------------------------------------------------------------- -->

      <sect2>
	<title>Does the G in GTK+, GDK and GLib stand for?</title>
	<para>GTK+ == Gimp Toolkit</para>
	<para>GDK == GTK+ Drawing Kit</para>
	<para>GLib == G Libray</para>
      </sect2>

      <!-- ----------------------------------------------------------------- -->

      <sect2>
	<title>Where is the documentation for GTK+?</title>
	<para>In the GTK+ distribution's doc/ directory you will find
	the reference material for both GTK and GDK, this FAQ and the
	GTK Tutorial.</para>
	<para>In addition, you can find links to HTML versions of
	these documents  by going to <ulink url="http://www.gtk.org/">
	http://www.gtk.org/</ulink>. A
	packaged version of the GTK Tutorial, with SGML, HTML,
	Postscript, DVI and text versions can be found in <ulink
	url="ftp://ftp.gtk.org/pub/gtk/tutorial">ftp://ftp.gtk.org/pub/gtk/tutorial
	</ulink></para>
	<para>There are now a couple of books available that deal with
	programming GTK+, GDK and GNOME:</para>
	<itemizedlist>
	  <listitem><simpara>Eric Harlows book entitled "Developing
	  Linux Applications with GTK+ and GDK". The ISBN is 0-7357-0021-4</simpara>
	  </listitem>
	  <listitem><simpara>The example code from Eric's book is
	  available on-line at <ulink
	  url="http://www.bcpl.net/~eharlow/book">
	  http://www.bcpl.net/~eharlow/book</ulink></simpara>
	  </listitem>
	  <listitem><simpara>Havoc Pennington has released a book called
	  "GTK+/GNOME Application Development". The ISBN is 0-7357-0078-8</simpara>
	    <simpara>The free version of the book lives here: <ulink
	  url="http://developer.gnome.org/doc/GGAD/">http://developer.gnome.org/doc/GGAD/
	  </ulink></simpara>
	    <simpara>And Havoc maintains information about it and
	  errata here: <ulink
	  url="http://pobox.com/~hp/gnome-app-devel.html">http://pobox.com/~hp/gnome-app-devel.html
	  </ulink></simpara>
	  </listitem>
	</itemizedlist>
      </sect2>

      <!-- ----------------------------------------------------------------- -->

      <sect2>
	<title>Is there a mailing list (or mailing list archive) for
	GTK+?</title>
	<para>Information on mailing lists relating to GTK+ can be
	found at: <ulink
	url="http://www.gtk.org/mailinglists.html">http://www.gtk.org/mailinglists.html
	</ulink></para>
      </sect2>

      <!-- ----------------------------------------------------------------- -->

      <sect2>
	<title>How to get help with GTK+</title>
	<para>First, make sure your question isn't answered in the
	documentation, this FAQ or the tutorial. Done that? You're
	sure you've done that, right? In that case, the best place to
	post questions is to the GTK+ mailing list.</para>
      </sect2>

      <!-- ----------------------------------------------------------------- -->

      <sect2>
	<title>How to report bugs in GTK+</title>
	<para>Bugs should be reported to the GNOME bug tracking system
	(<ulink
	url="http://bugs.gnome.org">http://bugs.gnome.org</ulink>). To
	report a problem about GTK+, send mail to submit@bugs.gnome.org.</para>
	<para>The subject of the mail should describe your problem. In
	the body of the mail, you should first include a
	"pseudo-header" that gives the package and version
	number. This should be separated by a blank line from the
	actual headers.</para>

	<para><literallayout><literal>Package: gtk+</literal>
	<literal>Version: 1.2.0</literal></literallayout></para>

	<para>Substitute 1.2.0 with the version of GTK+ that you have installed.</para>
	<para>Then describe the bug. Include:</para>
	
	<itemizedlist>
	  <listitem><simpara> Information about your system. For instance:</simpara>
	    <itemizedlist spacing=compact>
	      <listitem><simpara> What operating system and version</simpara>
	      </listitem>
	      <listitem><simpara> What version of X</simpara>
	      </listitem>
	      <listitem><simpara> For Linux, what version of the C library</simpara>
	      </listitem>
	    </itemizedlist>
	    <para>And anything else you think is relevant.</para>
	  </listitem>
	  <listitem><simpara> How to reproduce the bug.</simpara>
	    <simpara>If you can reproduce it with the testgtk program
	    that is built in the gtk/ subdirectory, that will be most
	    convenient. Otherwise, please include a short test program
	    that exhibits the behavior. As a last resort, you can also
	    provide a pointer to a larger piece of software that can
	    be downloaded.</simpara>
	    <simpara>(Bugs that can be reproduced within the GIMP are
	    almost as good as bugs that can be reproduced in
	    testgtk. If you are reporting a bug found with the GIMP,
	    please include the version number of the GIMP you are
	    using)</simpara>
	  </listitem>
	  <listitem><simpara> If the bug was a crash, the exact text that was
	  printed out when the crash occured.</simpara>
	  </listitem>
	  <listitem><simpara> Further information such as stack traces
  may be useful, but are not necessary. If you do send a stack trace,
  and the error is an X error, it will be more useful if the stacktrace is produced running
  the test program with the <literal>--sync</literal> command line option.</simpara>
	  </listitem>
	</itemizedlist>
      </sect2>

      <!-- ----------------------------------------------------------------- -->

      <sect2>
	<title>Is there a Windows version of GTK+?</title>
	<para>There is an on going port of GTK+ to the Windows
	platform which is making impressive progress.</para>
	<para>See <ulink
	url="http://www.iki.fi/tml/gimp/win32">http://www.iki.fi/tml/gimp/win32</ulink>
	for more information.</para>
      </sect2>

      <!-- ----------------------------------------------------------------- -->

      <sect2>
	<title>What applications have been written with GTK+?</title>
	<para>A list of some GTK+ based application can be found on
	the GTK+ web server at <ulink
	url="http://www.gtk.org/apps/">http://www.gtk.org/apps/</ulink>
	and contains more than 350 applications.</para>
	<para>Failing that, look for a project to work on for the
	GNOME project, <ulink
	url="http://www.gnome.org/">http://www.gnome.org/</ulink>
	Write a game. Write something that is useful.</para>
	<para>Some of these are:</para>

	<itemizedlist>
	  <listitem><simpara> GIMP (<ulink
	  url="http://www.gimp.org/">http://www.gimp.org/</ulink>), an
	  image manipulation program</simpara>
	  </listitem>
	  <listitem><simpara> AbiWord (<ulink
	  url="http://www.abisource.com/">http://www.abisource.com/</ulink>),
	  a professional word processor</simpara>
	  </listitem>
	  <listitem><simpara> Gzilla (<ulink
	  url="http://www.levien.com/gzilla/">http://www.levien.com/gzilla/</ulink>),
	  a web browser</simpara>
	  </listitem>
	  <listitem><simpara> XQF (<ulink
	  url="http://www.botik.ru/~roma/quake/">http://www.botik.ru/~roma/quake/</ulink>),
	  a QuakeWorld/Quake2 server browser and launcher</simpara>
	  </listitem>
	  <listitem><simpara> GDK Imlib (<ulink
	  url="http://www.rasterman.com/imlib.html">http://www.rasterman.com/imlib.html</ulink>),
	  a fast image loading and manipulation library for GDK</simpara>
	  </listitem>
	  <listitem><simpara> Glade (<ulink
	  url="http://glade.pn.org/">http://glade.pn.org/</ulink>), a
	  GTK+ based RAD tool which produces GTK+ applications</simpara>
	  </listitem>
	</itemizedlist>
       </sect2>

      <!-- ----------------------------------------------------------------- -->

      <sect2>
	<title>I'm looking for an application to write in GTK+. How
	about an IRC client?</title>
	<para>Ask on gtk-list for suggestions. There are at least
	three IRC clients already under development (probably more in fact. The server at
        <ulink url="http://www.forcix.cx/irc-clients.html">
	http://www.forcix.cx/irc-clients.html</ulink> list a bunch of them).</para>

	<itemizedlist spacing=compact>
	  <listitem><simpara> X-Chat.</simpara>
	  </listitem>
	  <listitem><simpara> girc. (Included with GNOME)</simpara>
	  </listitem>
	  <listitem><simpara> gsirc. (In the gnome CVS tree)</simpara>
	  </listitem>
	</itemizedlist>
      </sect2>
    </sect1>
  </chapter>

  <!-- ***************************************************************** -->
  <chapter>
    <title>How to find, configure, install, and troubleshoot GTK+</title>
    <sect1>
      <title></title>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>What do I need to run GTK+?</title>
	<para>To compile GTK+, all you need is a C compiler (gcc) and
	the X Window System and associated libraries on your system.</para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>Where can I get GTK+?</title>
	<para>The canonical site is <ulink
	url="ftp://ftp.gtk.org/pub/gtk">ftp://ftp.gtk.org/pub/gtk</ulink>.</para>
	<para>This site tends to get busy around the time of a new
	GTK+ release so try and use one of the mirror sites that are
	listed in <ulink
	url="ftp://ftp.gtk.org/etc/mirrors">ftp://ftp.gtk.org/etc/mirrors</ulink></para>
	<para>Here's a few mirror sites to get you started:</para>

	<itemizedlist spacing=compact>
	  <listitem><simpara> Africa - ftp://ftp.is.co.za/applications/gimp/</simpara>
	  </listitem>
	  <listitem><simpara> Australia - ftp://ftp.au.gimp.org/pub/gimp/</simpara>
	  </listitem>
	  <listitem><simpara> Finland - ftp://ftp.funet.fi/pub/sci/graphics/packages/gimp</simpara>
	  </listitem>
	  <listitem><simpara> Germany - ftp://infosoc.uni-koeln.de/pub/ftp.gimp.org/</simpara>
	  </listitem>
	  <listitem><simpara> Japan - ftp://SunSITE.sut.ac.jp/pub/archives/packages/gimp/</simpara>
	  </listitem>
	  <listitem><simpara> UK - ftp://ftp.flirble.org/pub/X/gimp/</simpara>
	  </listitem>
	  <listitem><simpara> US - ftp://ftp.insync.net/pub/mirrors/ftp.gimp.org/</simpara>
	  </listitem>
	</itemizedlist>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I configure/compile GTK+?</title>
	<para>Generally, all you will need to do is issue the commands:</para>

	<para><literallayout><literal>./configure</literal>
	<literal>make</literal></literallayout></para>

	<para>in the gtk+-version/ directory.</para>
      </sect2>

      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>When compiling GTK+ I get an error like: <literal>make:
	file `Makefile' line 456: Syntax error</literal></title>
	<para>Make sure that you are using GNU make (use <literal>make
	-v</literal>
	to check). There are many weird and wonderful versions of make
	out there, and not all of them handle the automatically
	generated Makefiles.</para>
      </sect2>

      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>I've compiled and installed GTK+, but I can't get any
	programs to link with it!</title>
	<para>This problem is most often encountered when the GTK+
	libraries can't be  found or are the wrong version. Generally,
	the compiler will complain about an 'unresolved symbol'.
	There are two things you need to check:</para>

	<itemizedlist>
	  <listitem><simpara>Make sure that the libraries can be
 found. You want to edit <filename>/etc/ld.so.conf</filename> to
 include the directories which contain the GTK libraries,
 so it looks something like:</simpara>
 	<para><literallayout><literal>/usr/X11R6/lib</literal>
	<literal>/usr/local/lib</literal></literallayout></para>

	    <para>Then you need to run /sbin/ldconfig as root. You can
	    find what directory GTK is in using</para>

 	<para><literallayout><literal>gtk-config --libs</literal>
	</literallayout></para>

	    <para>If your system doesn't use ld.so to find libraries
(such as Solaris), then you will have to use the LD_LIBRARY_PATH
environment variable (or compile the path into your program, which I'm
not going to cover here). So, with a Bourne type shell you can do (if
your GTK libraries are in /usr/local/lib):</para>

	    <para><literallayout><literal>export LD_LIBRARY_PATH=/usr/local/lib</literal></literallayout></para>

	    <para>and in a csh, you can do:</para>

	    <para><literallayout><literal>setenv LD_LIBRARY_PATH /usr/local/lib</literal></literallayout></para>

	  </listitem>
	  <listitem><simpara>Make sure the linker is finding the
correct set of libraries. If you have a Linux distribution that
installs GTK+ (e.g. RedHat 5.0) then this  older version may be
used. Now (assuming you have a RedHat system), issue the
command</simpara>

	    <para><literallayout><literal>rpm -e gtk gtk-devel</literal></literallayout></para>
	 
	    <para>You may also want to remove the packages that depend
on gtk (rpm will tell you which ones they are).  If you don't have a RedHat Linux system, check to make sure
that neither <filename>/usr/lib</filename> or <filename>/usr/local/lib</filename> contain any of
the libraries libgtk, libgdk, libglib, or libgck.  If they do exist, remove them
(and any gtk include files, such as <filename>/usr/include/gtk</filename> and <filename>/usr/include/gdk</filename>) 
and reinstall gtk+.</para>
	  </listitem>
	    
	</itemizedlist>
      </sect2>

      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>When compiling programs with GTK+, I get compiler error
	messages about not being able to find
	<literal>glibconfig.h</literal>.</title>
	<para>The header file "glibconfig.h" was moved to the
	directory $exec_prefix/lib/glib/include/. $exec_prefix is the
	directory that was specified by giving the --exec-prefix flags
	to ./configure when compiling GTK+. It defaults to  $prefix,
	(specified with --prefix), which in turn defaults to /usr/local/.</para>

	<para>This was done because "glibconfig.h" includes
	architecture dependent information, and the rest of the
	include files are put in $prefix/include, which can be shared
	between different architectures.</para>

	<para>GTK+ includes a shell script, <literal>/gtk-config/</literal>, that makes it
	easy to find out the correct include paths. The GTK+ Tutorial
	includes an example of using <literal>/gtk-config/</literal> for simple
	compilation from the command line. For information about more
	complicated configuration, see the file docs/gtk-config.txt in
	the GTK+ distribution.</para>

	<para>If you are trying to compile an old program, you may be
	able to work around the problem by configuring it with a
	command line like:</para>

	<para><literallayout><literal>setenv CPPFLAGS "-I/usr/local/include/glib/include"</literal>
<literal>./configure</literal></literallayout></para>

	<para>(Substitute the appropriate value of $exec_prefix for
	/usr/local.)</para>
      </sect2>

      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>When installing a GTK+ application, configure reports
	that it can't find GTK.</title>
	<para>There are several common reasons for this:</para>
	<itemizedlist>
	  <listitem><simpara>You have an old version of GTK installed
          somewhere. RedHat 5.0, for example, installs an older copy of GTK that
          may not work with the latest applications. You should remove this old
          copy, but note that in the case of RedHat 5.0 this will
          break the <literal>control-panel</literal> applications.</simpara>
	  </listitem>
	  <listitem><simpara><literal>gtk-config</literal> (or another
	component of GTK) isn't in your path, or there is an old
	version on your system. Type:</simpara>
	<para><literallayout><literal>gtk-config --version</literal></literallayout></para>

	    <para>to check for both of these. If it returns a value
	    different from what you expect, then you have an old
	    version of GTK on your system.</para>
	  </listitem>
	  <listitem><simpara>The ./configure script can't find the GTK
          libraries. As ./configure compiles various test programs, it needs to
          be able to find the GTK libraries. See the question above
          for help on this. </simpara></listitem>
	</itemizedlist>

	<para>If none of the above help, then have a look in
        config.log, which is generated by ./configure as it runs. At the
        bottom will be the last action it took before failing. If it is a
        section of source code, copy the source code to a file and compile it
        with the line just above it in config.log. If the compilation is
        successful, try executing it.</para>
      </sect2>

    </sect1>
  </chapter>

  <!-- ***************************************************************** -->
  <chapter>
    <title>Development of GTK+</title>
    <sect1>
      <title></title>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>Whats this CVS thing that everyone keeps talking about,
	and how do I access it?</title>
	<para>CVS is the Concurent Version System and is a very
	popular means of version control for software projects. It is
	designed to allow multiple  authors to be able to
	simultanously operate on the same source tree.  This source
	tree is centrally maintained, but each developer has a local
	mirror of this repository that they make there changes to.</para>
	<para>The GTK+ developers use a CVS repository to store the
	master copy of the current development version of GTK+. As
	such, people wishing to contribute patches to GTK+ should
	generate them against the CVS version. Normal people should
	use the packaged releases.</para>
	<para>The CVS toolset is available as RPM packages from the
	usual RedHat sites. The latest version is available at <ulink
	url="http://download.cyclic.com/pub/">http://download.cyclic.com/pub/
	</ulink></para>
	<para>Anyone can download the latest CVS version of GTK+ by
	using anonymous access using the following steps:</para>
	<itemizedlist>
	  <listitem><simpara> In a bourne shell descendant (e.g. bash) type:</simpara>
	<para><literallayout><literal>CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'</literal>
<literal>export CVSROOT</literal></literallayout></para>
	  </listitem>
	  <listitem><simpara>Next, the first time the source tree is
	  checked out, a cvs login is needed. </simpara>
	<para><literallayout><literal>cvs login</literal></literallayout></para>
	    <para>This will ask you for a password. There is no
	  password for cvs.gimp.org, so just enter a carriage return.</para>
	  </listitem>
	  <listitem><simpara>To get the tree and place it in a subdir of your
	  current working directory, issue the command:</simpara>
	<para><literallayout><literal>cvs -z3 get gtk+</literal></literallayout></para>
	<para>Note that with the GTK+ 1.1 tree, glib has been moved to
        a separate CVS module, so if you don't have glib installed you will
        need to get that as well:</para>
	<para><literallayout><literal>cvs -z3 get glib</literal></literallayout></para>
	  </listitem>
	</itemizedlist>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How can I contribute to GTK+?</title>
	<para>It's simple. If something doesn't work like you think it
	should in a program, check the documentation to make sure
	you're not missing something. If it is a true bug or missing
	feature, track it down in the GTK+ source, change it,  and
	then generate a patch in the form of a 'context diff'. This
	can be done using a command such as <literal>diff -ru
	&lt;oldfile&gt; &lt;newfile&gt;.</literal>  Then upload the patchfile to:</para>
	<para><literallayout><literal>ftp://ftp.gtk.org/incoming</literal></literallayout></para>
	<para>along with a README file. Make sure you follow the
	naming conventions or your patch will just be deleted! The
	filenames should be of this form:</para>
	<para><literallayout><literal>gtk&lt;username&gt;-&lt;date yymmdd-n&gt;.patch.gz</literal>
<literal>gtk-&lt;username&gt;-&lt;date yymmdd-n&gt;.patch.README</literal></literallayout></para>
	<para>The "n" in the date indicates a unique number (starting
	from 0) of patches you uploaded that day.  It should be 0,
	unless you upload more than one patch in the same day.</para>

	<para>Example:</para>
	<para><literallayout><literal>gtk-gale-982701-0.patch.gz</literal>
<literal>gtk-gale-982701-0.patch.README</literal></literallayout></para>
	<para>Once you upload <emphasis>anything</emphasis>, send the README to ftp-admin@gtk.org</para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I know if my patch got applied, and if not, why
	not?</title>
	<para>Uploaded patches will be moved to
	<filename>ftp://ftp.gtk.org/pub/gtk/patches</filename> where one of the
	GTK+ development team will pick them up. If applied, they will
	be moved to <filename>/pub/gtk/patches/old</filename>.</para>
	<para>Patches that aren't applied, for whatever reason, are
	moved to <filename>/pub/gtk/patches/unapplied</filename> or
	<filename>/pub/gtk/patches/outdated</filename>. At this point you can ask
	on the <literal>gtk-list</literal> mailing list why your patch wasn't
	applied. There are many possible reasons why patches may not
	be applied, ranging from it doesn't apply cleanly, to it isn't
	right. Don't be put off if your patch didn't make it first
	time round.</para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>What is the policy on incorporating new widgets into
	the library?</title>
	<para>This is up to the authors, so you will have to ask them
	once you are done with your widget. As a general guideline,
	widgets that are  generally useful, work, and are not a
	disgrace to the widget set will gladly be included.</para>
      </sect2>

      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>Is anyone working on bindings for languages other than
	C?</title>
	<para>The GTK+ home page (<ulink
	url="http://www.gtk.org/">http://www.gtk.org/</ulink>)
	presents a list of GTK+ bindings.</para>
	<itemizedlist>
	  <listitem><simpara>There are several C++ wrappers for GTK+.</simpara>
	    <itemizedlist> 
	      <listitem><simpara>the gtk-- package, which is a very small wrapper for GTK+.
              You can find the home page at <ulink
              url="http://www.cs.tut.fi/~p150650/gtk/gtk--.html">
              http://www.cs.tut.fi/~p150650/gtk/gtk--.html</ulink>. The FTP site is 
              <ulink url="ftp://ftp.gtk.org/pub/gtk/gtk--">
              ftp://ftp.gtk.org/pub/gtk/gtk--</ulink>.</simpara>
	      </listitem>
	      <listitem><simpara>the VDK package, which was built as
              the base package of a GTK+ application Borland-like
              builder. The home page can be found at <ulink
              url="http://www.guest.net/homepages/mmotta/VDKHome">
              http://www.guest.net/homepages/mmotta/VDKHome</ulink>.</simpara>
	      </listitem>

	      <listitem><simpara>The wxWindows/Gtk package, a free C++ library for cross-platform 
              GUI development. The home page of this package is
              <ulink url="http://www.freiburg.linux.de/~wxxt/">
              http://www.freiburg.linux.de/~wxxt/</ulink>.</simpara>
	      </listitem>
	    </itemizedlist>
	  </listitem>
	  <listitem><simpara>There are three known Objective-c
	  bindings currently in development:</simpara>
	    <itemizedlist> 
	      <listitem><simpara>The <ulink
	  url="http://www.gnome.org/">http://www.gnome.org/</ulink>
	  package of choice is objgtk. Objgtk is based on the Object class and is maintained by
          <ulink url="mailto:sopwith@cuc.edu">Elliot Lee</ulink>. Apparently,
	  objgtk is being accepted as the `standard' Objective-C binding for GTK+.</simpara>
	      </listitem>

	      <listitem><simpara>If you are more inclined towards the 
              <ulink url="http://www.gnustep.org/">GNUstep project</ulink>,
              you may want to check out GTKKit by 
              <ulink url="mailto:helge@mdlink.de">Helge He&szlig;</ulink>.
              The intention is to setup a GTK+ binding using the FoundationKit. 
              GTKKit includes nicities like writing a XML-type template file to 
              construct a GTK+ interface.</simpara>
	      </listitem>

	      <listitem><simpara>The GToolKit package, which can be found at
  <ulink url="ftp://ftp.gtk.org/pub/gtk/objc-gtoolkit/">
  ftp://ftp.gtk.org/pub/gtk/objc-gtoolkit/</ulink>.</simpara>
	      </listitem>
	    </itemizedlist>
	  </listitem>
	  <listitem><simpara>Perl bindings <ulink
	  url="ftp://ftp.gtk.org/pub/gtk/perl">ftp://ftp.gtk.org/pub/gtk/perl</ulink></simpara>
	  </listitem>
	  <listitem><simpara>Guile bindings. The home page is at
  <ulink url="http://www.ping.de/sites/zagadka/guile-gtk">http://www.ping.de/sites/zagadka/guile-gtk</ulink>.
  By the way, Guile is the GNU Project's implemention of R4RS Scheme (the
  standard). If you like Scheme, you may want to take a look at this.</simpara>
	  </listitem>
	  <listitem><simpara>David Monniaux reports:
  <quote>I've started a gtk-O'Caml binding system.
  The basics of the system, including callbacks, work fine.

  The current development is in
  <ulink url="http://www.ens-lyon.fr/~dmonniau/arcs">http://www.ens-lyon.fr/~dmonniau/arcs</ulink>
  </quote></simpara>
	  </listitem>
	  <listitem><simpara>Several python bindings have been done:</simpara>
	    <itemizedlist>
	      <listitem><simpara>pygtk is at 
  <ulink url="http://www.daa.com.au/~james/pygtk">http://www.daa.com.au/~james/pygtk</ulink> and 
  <ulink url="ftp://ftp.gtk.org/pub/gtk/python">ftp://ftp.gtk.org/pub/gtk/python</ulink></simpara>
	      </listitem>

	      <listitem><simpara>python-gtk is at
  <ulink url="http://www.ucalgary.ca/~nascheme/python-gtk">http://www.ucalgary.ca/~nascheme/python-gtk</ulink></simpara>
	      </listitem>
	    </itemizedlist>
	  </listitem>
	  <listitem><simpara>There's are a couple of OpenGL/Mesa
	  widgets available for GTK+. I suggest you start at
  <ulink url="http://www.student.oulu.fi/~jlof/gtkglarea/index.html">http://www.student.oulu.fi/~jlof/gtkglarea/index.html</ulink></simpara>
	  </listitem>
	  <listitem><simpara>Last, there are a lot of other language
	  bindings for languages such as Eiffel, TOM, Pascal, Pike, etc.</simpara>
	  </listitem>
	</itemizedlist>
      </sect2>

    </sect1>
  </chapter>

  <!-- ***************************************************************** -->
  <chapter>
    <title>Development with GTK+: the begining</title>
    <sect1>
      <title></title>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I get started?</title>
	<para>So, after you have installed GTK+ there are a couple of
	things that can ease you into developing applications with
	it. There is the GTK+ Tutorial <ulink
	url="http://www.gtk.org/tutorial/">
	http://www.gtk.org/tutorial/</ulink>, which is undergoing
	development. This will introduce you to writing applications
	using C.</para>

	<para>The Tutorial doesn't (yet) contain information on all of
	the widgets that are in GTK+. For example code on how to use
	the basics of all the GTK+ widgets you should look at the file
	gtk/testgtk.c (and associated source files) within the GTK+
	distribution. Looking at these examples will give you a good
	grounding on what the widgets can do.</para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>I tried to compile a small <command>Hello World</command> of mine,
	but it failed. Any clue?</title>
	<para>Since you are good at coding, we will not deal with
	compile time error here :)</para>

	<para>The classic command line to compile a GTK+ based program is</para>
	<para><literallayout><literal>gcc -o myprog [c files list] `gtk-config --cflags --libs`</literal></literallayout></para>

	<para>You should notice the backquote character which is used
        in this command line. A common mistake when you start a GTK+
        based development is to use quote instead of backquotes. If
        you do so, the compiler will complain about an unknown file
        called <filename>gtk-config --cflags --libs</filename>. The
        text in backquotes is an instruction to your shell to
        substitute the output of executing this text into the
        commandline.</para>

	<para>The command line above ensure that:</para>
	<itemizedlist>

	  <listitem><simpara>the correct C compiler flags will be used
           to compile the program (including the complete C header
           directory list)</simpara>
	  </listitem>

	  <listitem><simpara>your program will be linked with the
	  needed libraries.</simpara>
	  </listitem>
	</itemizedlist>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>What about using the <command>make</command>
	utility?</title>

	<para>This is a sample makefile which compile a GTK+ based
	program:</para>
<programlisting role="C">
# basic GTK+ app makefile
SOURCES = myprg.c foo.c bar.c
OBJS    = ${SOURCES:.c=.o}
CFLAGS  = `gtk-config --cflags`
LDADD   = `gtk-config --libs`
CC      = gcc
PACKAGE = myprg

all : ${OBJS}
        ${CC} -o ${PACKAGE} ${OBJS} ${LDADD}

.c.o:
        ${CC} ${CFLAGS} -c $<

# end of file
</programlisting>

	<para>For more information about the <command>make</command> utility, you
	should read either the related man page or the relevant info file.</para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>I use the backquote stuff in my makefiles, but my make
	process failed.</title>

	<para>The backquote construction seems to not be accepted by
        some old <command>make</command> utilities. If you use one of these, the
        make process will probably fail. In order to have the
        backquote syntax working again, you should use the GNU make
        utility (get it on the GNU ftp server at <ulink
        url="ftp://ftp.gnu.org/">ftp://ftp.gnu.org/"</ulink>).</para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>I want to add some configure stuff, how could I do
	this?</title>

	<para>To use autoconf/automake, you must first install the
	relevant packages. These are:</para>

	<itemizedlist spacing=Compact>
	  <listitem><simpara>the m4 preprocessor v1.4 or better</simpara>
	  </listitem>
	  <listitem><simpara>autoconf v2.13 or better</simpara>
	  </listitem>
	  <listitem><simpara>automake v1.4 or better</simpara>
	  </listitem>
	</itemizedlist>

	<para>You'll find these packages on the GNU main ftp server
	(<ulink url="ftp://ftp.gnu.org/">ftp://ftp.gnu.org/</ulink>)
	or on any GNU mirror.</para>

	<para>In order to use the powerful autoconf/automake scheme,
	you must create a configure.in which may look like:</para>

<programlisting role="C">
dnl Process this file with autoconf to produce a configure script.
dnl configure.in for a GTK+ based program

AC_INIT(myprg.c)dnl
AM_INIT_AUTOMAKE(mypkgname,0.0.1)dnl
AM_CONFIG_HEADER(config.h)dnl

dnl Checks for programs.
AC_PROG_CC dnl check for the c compiler
dnl you should add CFLAGS="" here, 'cos it is set to -g by PROG_CC

dnl Checks for libraries.
AM_PATH_GTK(1.2.0,,AC_MSG_ERROR(mypkgname 0.1 needs GTK))dnl

AC_OUTPUT(
	Makefile
)dnl
</programlisting>

	<para>You must add a Makefile.am file:</para>

<programlisting role="C">
bin_PROGRAMS    = myprg
myprg_SOURCES   = myprg.c foo.c bar.c
INCLUDES        = @GTK_CFLAGS@
LDADD           = @GTK_LIBS@
CLEANFILES      = *~
DISTCLEANFILES  = .deps/*.P
</programlisting>

	<para>If your project contains more than one subdirectory,
        you'll have to create one Makefile.am in each directory plus a
        master Makefile.am which will look like:</para>

<programlisting role="C">
SUBDIRS         = mydir1 mydir2 mydir3
</programlisting>

	<para>then, to use these, simply type the following
	commands:</para>

<programlisting role="C">
aclocal
autoheader
autoconf
automake --add-missing --include-deps --foreign 
</programlisting>

	<para>For further information, you should look at the autoconf
        and the automake documentation (the shipped info files are
        really easy to understand, and there are plenty of web
        resources that deal with autoconf and automake).</para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>I try to debug my GTK+ application with gdb, but it
	hangs my X server when I hit some breakpoint. Any
	Idea?</title>

	<para>From Federico Mena Quintero:
        <quote>X is not locked up.  It is likely that you are hitting a breakpoint
        inside a callback that is called from a place in Gtk that has a mouse grab.

	Run your program with the <literal>--sync</literal>
        option; it will make it easier to debug. Also, you may want to
        use the console for running the debugger, and just let the
        program run in another console with the X server.</quote></para>

	<para>Eric Mouw had another solution:
        <quote>An old terminal connected to an otherwise unused serial
        port is also great for debugging X programs. Old vt100/vt220
        terminals are dirt cheap but a bit hard to get (here in The
        Netherlands, YMMV).</quote></para>
      </sect2>
    </sect1>
  </chapter>

  <!-- ***************************************************************** -->
  <chapter>
    <title>Development with GTK+: general questions</title>
    <sect1>
      <title></title>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>What widgets are in GTK?</title>

	<para>The GTK+ Tutorial lists the following widgets:</para>
<programlisting role="C">
  GtkObject
   +GtkData
   | +GtkAdjustment
   | `GtkTooltips
   `GtkWidget
     +GtkContainer
     | +GtkBin
     | | +GtkAlignment
     | | +GtkEventBox
     | | +GtkFrame
     | | | `GtkAspectFrame
     | | +GtkHandleBox
     | | +GtkItem
     | | | +GtkListItem
     | | | +GtkMenuItem
     | | | | `GtkCheckMenuItem
     | | | |   `GtkRadioMenuItem
     | | | `GtkTreeItem
     | | +GtkViewport
     | | `GtkWindow
     | |   +GtkColorSelectionDialog
     | |   +GtkDialog
     | |   | `GtkInputDialog
     | |   `GtkFileSelection
     | +GtkBox
     | | +GtkButtonBox
     | | | +GtkHButtonBox
     | | | `GtkVButtonBox
     | | +GtkHBox
     | | | +GtkCombo
     | | | `GtkStatusbar
     | | `GtkVBox
     | |   +GtkColorSelection
     | |   `GtkGammaCurve
     | +GtkButton
     | | +GtkOptionMenu
     | | `GtkToggleButton
     | |   `GtkCheckButton
     | |     `GtkRadioButton
     | +GtkCList
     |   `GtkCTree
     | +GtkFixed
     | +GtkList
     | +GtkMenuShell
     | | +GtkMenuBar
     | | `GtkMenu
     | +GtkNotebook
     | +GtkPaned
     | | +GtkHPaned
     | | `GtkVPaned
     | +GtkScrolledWindow
     | +GtkTable
     | +GtkToolbar
     | `GtkTree
     +GtkDrawingArea
     | `GtkCurve
     +GtkEditable
     | +GtkEntry
     | | `GtkSpinButton
     | `GtkText
     +GtkMisc
     | +GtkArrow
     | +GtkImage
     | +GtkLabel
     | | `GtkTipsQuery
     | `GtkPixmap
     +GtkPreview
     +GtkProgressBar
     +GtkRange
     | +GtkScale
     | | +GtkHScale
     | | `GtkVScale
     | `GtkScrollbar
     |   +GtkHScrollbar
     |   `GtkVScrollbar
     +GtkRuler
     | +GtkHRuler
     | `GtkVRuler
     `GtkSeparator
       +GtkHSeparator
       `GtkVSeparator
</programlisting>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>Is GTK+ thread safe? How do I write multi-threaded GTK+
	applications?</title>

	<para>The GLib library can be used in a thread-safe mode by
         calling g_thread_init() before making any other GLib
         calls. In this mode GLib automatically locks all internal
         data structures as needed.  This does not mean that two
         threads can simultaneously access, for example, a single hash
         table, but they can access two different hash tables
         simultaneously. If two different threads need to access the
         same hash table, the application is responsible for locking
         itself.</para>

	<para>When GLib is intialized to be thread-safe, GTK+ is
         <emphasis>thread aware</emphasis>. There is a single global
         lock that you must acquire with gdk_threads_enter() before
         making any GDK calls, and release with gdk_threads_leave()
         afterwards.</para>

	<para>A minimal main program for a threaded GTK+ application
         looks like:</para>

<programlisting role="C">
int
main (int argc, char *argv[])
{
  GtkWidget *window;

  g_thread_init(NULL);
  gtk_init(&amp;argc, &amp;argv);

  window = create_window();
  gtk_widget_show(window);

  gdk_threads_enter();
  gtk_main();
  gdk_threads_leave();

  return(0);
}
</programlisting>

	<para>Callbacks require a bit of attention. Callbacks from
         GTK+ (signals) are made within the GTK+ lock. However
         callbacks from GLib (timeouts, IO callbacks, and idle
         functions) are made outside of the GTK+ lock. So, within a
         signal handler you do not need to call gdk_threads_enter(),
         but within the other types of callbacks, you do.</para>

	<para>Erik Mouw contributed the following code example to
	 illustrate how to use threads within GTK+ programs.</para>

<programlisting role="C">
/*-------------------------------------------------------------------------
 * Filename:      gtk-thread.c
 * Version:       0.99.1
 * Copyright:     Copyright (C) 1999, Erik Mouw
 * Author:        Erik Mouw &lt;J.A.K.Mouw@its.tudelft.nl&gt;
 * Description:   GTK threads example. 
 * Created at:    Sun Oct 17 21:27:09 1999
 * Modified by:   Erik Mouw &lt;J.A.K.Mouw@its.tudelft.nl&gt;
 * Modified at:   Sun Oct 24 17:21:41 1999
 *-----------------------------------------------------------------------*/
/*
 * Compile with:
 *
 * cc -o gtk-thread gtk-thread.c `gtk-config --cflags --libs gthread`
 *
 * Thanks to Sebastian Wilhelmi and Owen Taylor for pointing out some
 * bugs.
 *
 */

#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;unistd.h&gt;
#include &lt;time.h&gt;
#include &lt;gtk/gtk.h&gt;
#include &lt;glib.h&gt;
#include &lt;pthread.h&gt;

#define YES_IT_IS    (1)
#define NO_IT_IS_NOT (0)

typedef struct 
{
  GtkWidget *label;
  int what;
} yes_or_no_args;

G_LOCK_DEFINE_STATIC (yes_or_no);
static volatile int yes_or_no = YES_IT_IS;

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

void *argument_thread(void *args)
{
  yes_or_no_args *data = (yes_or_no_args *)args;
  gboolean say_something;

  for(;;)
    {
      /* sleep a while */
      sleep(rand() / (RAND_MAX / 3) + 1);

      /* lock the yes_or_no_variable */
      G_LOCK(yes_or_no);

      /* do we have to say something? */
      say_something = (yes_or_no != data->what);

      if(say_something)
	{
	  /* set the variable */
	  yes_or_no = data->what;
	}

      /* Unlock the yes_or_no variable */
      G_UNLOCK(yes_or_no);

      if(say_something)
	{
	  /* get GTK thread lock */
	  gdk_threads_enter();

	  /* set label text */
	  if(data->what == YES_IT_IS)
	    gtk_label_set_text(GTK_LABEL(data->label), "O yes, it is!");
	  else
	    gtk_label_set_text(GTK_LABEL(data->label), "O no, it isn't!");

	  /* release GTK thread lock */
	  gdk_threads_leave();
	}
    }

  return(NULL);
}

int main(int argc, char *argv[])
{
  GtkWidget *window;
  GtkWidget *label;
  yes_or_no_args yes_args, no_args;
  pthread_t no_tid, yes_tid;

  /* init threads */
  g_thread_init(NULL);

  /* init gtk */
  gtk_init(&amp;argc, &amp;argv);

  /* init random number generator */
  srand((unsigned int)time(NULL));

  /* create a window */
  window = gtk_window_new(GTK_WINDOW_TOPLEVEL);

  gtk_signal_connect(GTK_OBJECT (window), "destroy",
		     GTK_SIGNAL_FUNC(destroy), NULL);

  gtk_container_set_border_width(GTK_CONTAINER (window), 10);

  /* create a label */
  label = gtk_label_new("And now for something completely different ...");
  gtk_container_add(GTK_CONTAINER(window), label);
  
  /* show everything */
  gtk_widget_show(label);
  gtk_widget_show (window);

  /* create the threads */
  yes_args.label = label;
  yes_args.what = YES_IT_IS;
  pthread_create(&amp;yes_tid, NULL, argument_thread, &amp;yes_args);

  no_args.label = label;
  no_args.what = NO_IT_IS_NOT;
  pthread_create(&amp;no_tid, NULL, argument_thread, &amp;no_args);

  /* enter the GTK main loop */
  gdk_threads_enter();
  gtk_main();
  gdk_threads_leave();

  return(0);
}
</programlisting>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>Why does this strange 'x io error' occur when I
	<literal>fork()</literal> in my GTK+ app?</title>

	<para>This is not really a GTK+ problem, and the problem is
         not related to <literal>fork()</literal> either. If the 'x io
         error' occurs then you probably use the <literal>exit()</literal> function
         in order to exit from the child process.</para>

	<para>When GDK opens an X display, it creates a socket file
         descriptor. When you use the <literal>exit()</literal>
         function, you implicitly close all the open file descriptors,
         and the underlying X library really doesn't like this.</para>

	<para>The right function to use here is
	<literal>_exit()</literal>.</para> 

	<para>Erik Mouw contributed the following code example to
	 illustrate handling fork() and exit().</para>

<programlisting role="C">
/*-------------------------------------------------------------------------
 * Filename:      gtk-fork.c
 * Version:       0.99.1
 * Copyright:     Copyright (C) 1999, Erik Mouw
 * Author:        Erik Mouw &lt;J.A.K.Mouw@its.tudelft.nl&gt;
 * Description:   GTK+ fork example
 * Created at:    Thu Sep 23 21:37:55 1999
 * Modified by:   Erik Mouw &lt;J.A.K.Mouw@its.tudelft.nl&gt;
 * Modified at:   Thu Sep 23 22:39:39 1999
 *-----------------------------------------------------------------------*/
/*
 * Compile with:
 *
 * cc -o gtk-fork gtk-fork.c `gtk-config --cflags --libs`
 *
 */

#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;signal.h&gt;
#include &lt;sys/types.h&gt;
#include &lt;sys/wait.h&gt;
#include &lt;unistd.h&gt;
#include &lt;gtk/gtk.h&gt;

void sigchld_handler(int num)
{
  sigset_t set, oldset;
  pid_t pid;
  int status, exitstatus;

  /* block other incoming SIGCHLD signals */
  sigemptyset(&amp;set);
  sigaddset(&amp;set, SIGCHLD);
  sigprocmask(SIG_BLOCK, &amp;set, &amp;oldset);

  /* wait for child */
  while((pid = waitpid((pid_t)-1, &amp;status, WNOHANG)) > 0)
    {
      if(WIFEXITED(status))
	{
	  exitstatus = WEXITSTATUS(status);

	  fprintf(stderr, 
		  "Parent: child exited, pid = %d, exit status = %d\n", 
		  (int)pid, exitstatus);
	}
      else if(WIFSIGNALED(status))
	{
	  exitstatus = WTERMSIG(status);

	  fprintf(stderr,
		  "Parent: child terminated by signal %d, pid = %d\n",
		  exitstatus, (int)pid);
	}
      else if(WIFSTOPPED(status))
	{
	  exitstatus = WSTOPSIG(status);

	  fprintf(stderr,
		  "Parent: child stopped by signal %d, pid = %d\n",
		  exitstatus, (int)pid);
	}
      else
	{
	  fprintf(stderr,
		  "Parent: child exited magically, pid = %d\n",
		  (int)pid);
	}
    }

  /* re-install the signal handler (some systems need this) */
  signal(SIGCHLD, sigchld_handler);
  
  /* and unblock it */
  sigemptyset(&amp;set);
  sigaddset(&amp;set, SIGCHLD);
  sigprocmask(SIG_UNBLOCK, &amp;set, &amp;oldset);
}

gint delete_event(GtkWidget *widget, GdkEvent *event, gpointer data)
{
  return(FALSE);
}

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

void fork_me(GtkWidget *widget, gpointer data)
{
  pid_t pid;

  pid = fork();

  if(pid == -1)
    {
      /* ouch, fork() failed */
      perror("fork");
      exit(-1);
    }
  else if(pid == 0)
    {
      /* child */
      fprintf(stderr, "Child: pid = %d\n", (int)getpid());

      execlp("ls", "ls", "-CF", "/", NULL);
      
      /* if exec() returns, there is something wrong */
      perror("execlp");

      /* exit child. note the use of _exit() instead of exit() */
      _exit(-1);
    }
  else
    {
      /* parent */
      fprintf(stderr, "Parent: forked a child with pid = %d\n", (int)pid);
    }
}

int main(int argc, char *argv[])
{
  GtkWidget *window;
  GtkWidget *button;

  gtk_init(&amp;argc, &amp;argv);

  /* the basic stuff: make a window and set callbacks for destroy and
   * delete events 
   */
  window = gtk_window_new(GTK_WINDOW_TOPLEVEL);

  gtk_signal_connect(GTK_OBJECT (window), "delete_event",
		     GTK_SIGNAL_FUNC(delete_event), NULL);
          
  gtk_signal_connect(GTK_OBJECT (window), "destroy",
		     GTK_SIGNAL_FUNC(destroy), NULL);

#if (GTK_MAJOR_VERSION == 1) && (GTK_MINOR_VERSION == 0)
  gtk_container_border_width(GTK_CONTAINER (window), 10);
#else  
  gtk_container_set_border_width(GTK_CONTAINER (window), 10);
#endif

  /* add a button to do something usefull */
  button = gtk_button_new_with_label("Fork me!");
          
  gtk_signal_connect(GTK_OBJECT (button), "clicked",
		     GTK_SIGNAL_FUNC(fork_me), NULL);

  gtk_container_add(GTK_CONTAINER(window), button);
          
  /* show everything */
  gtk_widget_show (button);
  gtk_widget_show (window);


  /* install a signal handler for SIGCHLD signals */
  signal(SIGCHLD, sigchld_handler);

  
  /* main loop */
  gtk_main ();

  exit(0);         
}
</programlisting>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>Why don't the contents of a button move when the button
	is pressed? Here's a patch to make it work that way...</title>

	<para>From: Peter Mattis
         <quote>The reason buttons don't move their child down and to
          the right when they are depressed is because I don't think
          that's what is happening visually. My view of buttons is
          that you are looking at them straight on. That is, the user
          interface lies in a plane and you're above it looking
          straight at it. When a button gets pressed it moves directly
          away from you. To be absolutely correct I guess the child
          should actually shrink a tiny amount. But I don't see why
          the child should shift down and to the left. Remember, the
          child is supposed to be attached to the buttons surface. Its
          not good for it to appear like the child is slipping on the
          surface of the button.

          On a more practical note, I did implement this at one point
          and determined it didn't look good and removed
          it.</quote></para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How to I identifiy a widgets top level window or other
	ancestor?</title>

	<para>There are a couple of ways to find the top level parent
         of a widget. The easier way is to call the
         <literal>gtk_widget_top_level()</literal> function that
         returns pointer to a GtkWidget that is the top level
         window.</para>

	<para>A more complicated way to do this (but less limited, as
         it allows the user to get the closest ancestor of a known type) is to use
         <literal>gtk_widget_get_ancestor()</literal> as in:</para>

<programlisting role="C">
      GtkWidget       *widget;
      widget = gtk_widget_get_ancestor(w, GTK_TYPE_WINDOW);
</programlisting>

	<para>Since virtually all the GTK_TYPEs can be used as the
         second parameter of this function, you can get any parent
         widget of a particular widget. Suppose you have an hbox which
         contains a vbox, which in turn contains some other atomic
         widget (entry, label, etc. To find the master hbox using the
         <literal>entry</literal> widget simply use:</para>

<programlisting role="C">
      GtkWidget       *hbox;
      hbox = gtk_widget_get_ancestor(w, GTK_TYPE_HBOX);
</programlisting>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I get the Window ID of a GtkWindow?</title>

	<para>The actual Gdk/X window will be created when the widget
	 gets realized. You can get the Window ID with:</para>

<programlisting role="C">
#include &lt;gdk/gdkx.h&gt;

Window xwin = GDK_WINDOW_XWINDOW (GTK_WIDGET (my_window)->window);
</programlisting>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I catch a double click event (in a list widget,
	for example)?</title>

	<para>Tim Janik wrote to gtk-list (slightly modified):</para>

	<para>Define a signal handler:</para>

<programlisting role="C">
gint
signal_handler_event(GtkWiget *widget, GdkEvenButton *event, gpointer func_data)
{
  if (GTK_IS_LIST_ITEM(widget) &&
       (event->type==GDK_2BUTTON_PRESS ||
        event->type==GDK_3BUTTON_PRESS) ) {
    printf("I feel %s clicked on button %d\",
           event->type==GDK_2BUTTON_PRESS ? "double" : "triple",
           event->button);
  }

  return FALSE;
}</programlisting>

	<para>And connect the handler to your object:</para>

<programlisting role="C">
{
  /* list, list item init stuff */     

  gtk_signal_connect(GTK_OBJECT(list_item),
                     "button_press_event",
                     GTK_SIGNAL_FUNC(signal_handler_event),
                     NULL);

  /* and/or */

  gtk_signal_connect(GTK_OBJECT(list_item),
                     "button_release_event",
                     GTK_SIGNAL_FUNC(signal_handler_event),
                     NULL);

  /* something else */
}
</programlisting>

	<para>and, Owen Taylor wrote:
         <quote>Note that a single button press will be received
         beforehand, and if you are doing this for a button, you will
         therefore also get a "clicked" signal for the button. (This
         is going to be true for any toolkit, since computers aren't
         good at reading one's mind.)</quote></para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>By the way, what are the differences between signals
	and events?</title>

	<para>First of all, Havoc Pennington gives a rather complete
         description of the differences between events and signals in
         his free book (two chapters can be found at <ulink
         url="http://www106.pair.com/rhp/sample_chapters.html">
         http://www106.pair.com/rhp/sample_chapters.html</ulink>).</para>

	<para>Moreover, Havoc posted this to the <literal>gtk-list</literal>
         <quote>Events are a stream of messages received from the X
         server. They drive the Gtk main loop; which more or less
         amounts to "wait for events, process them" (not exactly, it
         is really more general than that and can wait on many
         different input streams at once). Events are a Gdk/Xlib
         concept.</quote></para>

  <para><quote>Signals are a feature of GtkObject and its subclasses. They have
  nothing to do with any input stream; really a signal is just a way
  to keep a list of callbacks around and invoke them ("emit" the
  signal). There are lots of details and extra features of
  course. Signals are emitted by object instances, and are entirely
  unrelated to the Gtk main loop.  Conventionally, signals are emitted
  "when something changes" about the object emitting the signal.</quote></para>

  <para><quote>Signals and events only come together because GtkWidget happens to
  emit signals when it gets events. This is purely a convenience, so
  you can connect callbacks to be invoked when a particular widget
  receives a particular event. There is nothing about this that makes
  signals and events inherently related concepts, any more than
  emitting a signal when you click a button makes button clicking and
  signals related concepts.</quote></para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>Data I pass to the <literal>delete_event</literal> (or other event)
	handler gets corrupted.</title>

	<para>All event handlers take an additional argument which
         contains information about the event that triggered the
         handler. So, a <literal>delete_event</literal> handler must
         be declared as:</para>


<programlisting role="C">
gint delete_event_handler (GtkWidget   *widget,
                           GdkEventAny *event,
                           gpointer     data);
</programlisting>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>I have my signal connected to the the (whatever) event,
	but it seems I don't catch it. What's wrong?</title>

	<para>There is some special initialisation to do in order to
         catch some particular events. In fact, you must set the
         correct event mask bit of your widget before getting some
         particular events.</para>

	<para>For example,</para>

<programlisting role="C">
  gtk_widget_add_events(window, GDK_KEY_RELEASE_MASK);
</programlisting>

	<para>lets you catch the key release events. If you want to
	catch every events, simply us the GDK_ALL_EVENTS_MASK event
	mask.</para>

	<para>All the event masks are defined in the
	<filename>gdktypes.h</filename> file.</para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>I need to add a new signal to a GTK+ widget. Any
	idea?</title>

	<para>If the signal you want to add may be beneficial for
         other GTK+ users, you may want to submit a patch that
         presents your changes. Check the tutorial for more
         information about adding signals to a widget class.</para>

	<para>If you don't think it is the case or if your patch is
         not applied you'll have to use the
         <literal>gtk_object_class_user_signal_new</literal>
         function. <literal>gtk_object_class_user_signal_new</literal> allows you to
         add a new signal to a predefined GTK+ widget without any
         modification of the GTK+ source code. The new signal can be
         emited with <literal>gtk_signal_emit</literal> and can be
         handled in the same way as other signals.</para>

	<para>Tim Janik posted this code snippet:</para>

<programlisting role="C">
static guint signal_user_action = 0;

signal_user_action =
  gtk_object_class_user_signal_new (gtk_type_class (GTK_TYPE_WIDGET),
                    "user_action",
                    GTK_RUN_LAST | GTK_RUN_ACTION,
                    gtk_marshal_NONE__POINTER,
                    GTK_TYPE_NONE, 1,
                    GTK_TYPE_POINTER);

void
gtk_widget_user_action (GtkWidget *widget,
                        gpointer   act_data)
{
  g_return_if_fail (GTK_IS_WIDGET (widget));

  gtk_signal_emit (GTK_OBJECT (widget), signal_user_action, act_data);
}
</programlisting>

	<para>If you want your new signal to have more than the
	classical gpointer parameter, you'll have to play with GTK+
	marshallers.</para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>Is it possible to get some text displayed which is
	truncated to fit inside its allocation?</title>

	<para>GTK's behavior (no clipping) is a consequence of its
         attempts to conserve X resources. Label widgets (among
         others) don't get their own X window - they just draw their
         contents on their parent's window. While it might be possible
         to have clipping occur by setting the clip mask before
         drawing the text, this would probably cause a substantial
         performance penalty.</para>

	<para>Its possible that, in the long term, the best solution
         to such problems might be just to change gtk to give labels X
         windows. A short term workaround is to put the label widget
         inside another widget that does get its own window - one
         possible candidate would be the viewport widget.</para>

<programlisting role="C">
viewport = gtk_viewport (NULL, NULL);
gtk_widget_set_usize (viewport, 50, 25);
gtk_viewport_set_shadow_type (GTK_VIEWPORT(viewport), GTK_SHADOW_NONE);
gtk_widget_show(viewport);

label = gtk_label ("a really long label that won't fit");
gtk_container_add (GTK_CONTAINER(viewport), label);
gtk_widget_show (label);
</programlisting>

	<para>If you were doing this for a bunch of widgets, you might
         want to copy gtkviewport.c and strip out the adjustment and
         shadow functionality (perhaps you could call it
         GtkClipper).</para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I make my window modal? / How do I make a single
	window active?</title>

	<para>After you create your window, do
	<literal>gtk_grab_add(my_window)</literal>. And after  closing
	the window do
	<literal>gtk_grab_remove(my_window)</literal>.</para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>Why doesn't my widget (e.g. progressbar)
	update?</title>

	<para>You are probably doing all the changes within a function without
         returning control to <literal>gtk_main()</literal>. This may
         be the case if you do some lengthy calculation in your
         code. Most drawing updates are only placed on a queue, which
         is processed within <literal>gtk_main()</literal>. You can force the
         drawing queue to be processed using something like:</para>


<programlisting role="C">
while (gtk_main_iteration());
</programlisting>

	<para>inside you're function that changes the widget.</para>

	<para>What the above snippet does is run all pending events
         and high priority idle functions, then return immediately
         (the drawing is done in a high priority idle function).</para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I attach data to some GTK+ object/widget?</title>

	<para>First of all, the attached data is stored in the
        object_data field of a GtkObject. The type of this field is
        GData, which is defined in glib.h.  So you should read the
        gdataset.c file in your glib source directory very
        carefully.</para>

	<para>There are two (easy) ways to attach some data to a gtk
        object.  Using <literal>gtk_object_set_data()</literal> and
        <literal>gtk_object_get_data()</literal> seems to be the most
        common way to do this, as it provides a powerful interface to
        connect objects and data.</para>

<programlisting role="C">
void gtk_object_set_data(GtkObject *object, const gchar *key, gpointer data);

gpointer gtk_object_get_data(GtkObject *object, const gchar *key);
</programlisting>

	<para>Since a short example is better than any lengthy speech:</para>

<programlisting role="C">
struct my_struct	p1,p2,*result;
GtkWidget		*w;

gtk_object_set_data(GTK_OBJECT(w),"p1 data",(gpointer)&amp;p1);
gtk_object_set_data(GTK_OBJECT(w),"p2 data",(gpointer)&amp;p2);

result = gtk_object_get_data(GTK_OBJECT(w),"p1 data");
</programlisting>

	<para>The <literal>gtk_object_set_user_data()</literal> and
	<literal>gtk_object_get_user_data()</literal> functions does
	exactly the same thing as the functions above, but does not
	let you specify the "key" parameter.Instead, it uses a
	standard "user_data" key. Note that the use of these functions
	is deprecated in 1.2. They only provide a compatibility mode
	with some old gtk packages.</para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I remove the data I have attached to an
	object?</title>

	<para>When attaching the data to the object, you can use the
        <literal>gtk_object_set_data_full()</literal> function. The three
        first arguments of the function are the same as in
        <literal>gtk_object_set_data()</literal>. The fourth one is a
        pointer to a callback function which is called when the data
        is destroyed. The data is destroyed when you:</para>

	<itemizedlist>
	  <listitem><simpara> destroy the object</simpara>
	  </listitem>
	  <listitem><simpara> replace the data with a new one (with
	  the same key)</simpara>
	  </listitem>
	  <listitem><simpara> replace the data with NULL (with the
	  same key)</simpara>
	  </listitem>
	</itemizedlist>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I reparent a widget?</title>

	<para>The normal way to reparent (ie change the owner) of a
	widget should be to use the function:</para>

<programlisting role="C">
void gtk_widget_reparent (GtkWidget *widget, 
                          GtkWidget *new_parent)
</programlisting>

	<para>But this is only a "should be" since this function does
        not correctly do its job on some specific widgets. The main
        goal of gtk_widget_reparent() is to avoid unrealizing widget
        if both widget and new_parent are realized (in this case,
        widget->window is successfully reparented). The problem here
        is that some widgets in the GTK+ hierarchy have multiple
        attached X subwindows and this is notably the case for the
        GtkSpinButton widget. For those, gtk_widget_reparent() will
        fail by leaving an unrealized child window where it should
        not.</para>

	<para>To avoid this problem, simply use the following code
	snippet:</para>

<programlisting role="C">
     gtk_widget_ref(widget);
     gtk_container_remove(GTK_CONTAINER(old_parent), widget);
     gtk_container_add(GTK_CONTAINER(new_parent), widget);
     gtk_widget_unref(widget);
</programlisting>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How could I get any widgets position?</title>

	<para>As Tim Janik pointed out, there are different cases, and
	each case requires a different solution.</para>

	<itemizedlist>
	  <listitem><simpara> If you want the position of a widget
        relative to its parent, you should use
        <literal>widget->allocation.x</literal> and
        <literal>widget->allocation.y</literal>.</simpara>
	  </listitem>
	  <listitem><simpara> If you want the position of a window
        relative to the X root window, you should use <literal>gdk_window_get_geometry()</literal>
        <literal>gdk_window_get_position()</literal> or
        <literal>gdk_window_get_origin()</literal>.</simpara>
	  </listitem>
	  <listitem><simpara> If you want to get the position of the
        window (including the WM decorations), you should use
        <literal>gdk_window_get_root_origin()</literal>.</simpara>
	  </listitem>
	  <listitem><simpara> Last but not least, if you want to get a Window Manager frame
        position, you should use
        <literal>gdk_window_get_deskrelative_origin()</literal>.</simpara>
	  </listitem>
</itemizedlist>

	<para>Your choice of Window Manager will have an effect of the
        results of the above functions. You should keep this in mind
        when writing your application. This is dependant upon how the
        Window Managers manage the decorations that they add around
        windows.</para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I set the size of a widget/window? How do I
	prevent the user resizing my window?</title>

	<para>The <literal>gtk_widget_set_uposition()</literal>
	function is used to set the position of any widget.</para>

	<para>The <literal>gtk_widget_set_usize()</literal> function
        is used to set the size of a widget. In order to use all the
        features that are provided by this function when it acts on a
        window, you may want to use the
        <literal>gtk_window_set_policy</literal> function. The
        definition of these functions are:</para>

<programlisting role="C">
void gtk_widget_set_usize (GtkWidget *widget,
                           gint width,
                           gint height);

void gtk_window_set_policy (GtkWindow *window,
                            gint allow_shrink,
                            gint allow_grow,
                            gint auto_shrink);
</programlisting>

	<para><literal>Auto_shrink</literal> will automatically shrink
        the window when the requested size of the child widgets goes
        below the current size of the
        window. <literal>Allow_shrink</literal> will give the user the
        authorisation to make the window smaller that it should
        normally be. <literal>Allow_grow</literal> will give the user
        will have the ability to make the window bigger. The default
        values for these parameters are:</para>

<programlisting role="C">
allow_shrink = FALSE
allow_grow   = TRUE
auto_shrink  = FALSE
</programlisting>

	<para>The <literal>gtk_widget_set_usize()</literal> functions
        is not the easiest way to set a window size since you cannot
        decrease this window size with another call to this function
        unless you call it twice, as in:</para>

<programlisting role="C">
     gtk_widget_set_usize(your_widget, -1, -1);
     gtk_widget_set_usize(your_widget, new_x_size, new_y_size);
</programlisting>

	<para>Another way to set the size of and/or move a window is to use
        the <literal>gdk_window_move_resize()</literal> function which
        uses to work fine both to grow or to shrink the window:</para>

<programlisting role="C">
     gdk_window_move_resize(window->window, 
                            x_pos, y_pos, 
                            x_size, y_size);
</programlisting>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I add a popup menu to my GTK+
	application?</title>

	<para>The <literal>menu</literal> example in the examples/menu
	directory of the GTK+ distribution implements a popup menu
	with this technique:</para>


<programlisting role="C">
static gint button_press (GtkWidget *widget, GdkEvent *event)
{

    if (event->type == GDK_BUTTON_PRESS) {
        GdkEventButton *bevent = (GdkEventButton *) event; 
        gtk_menu_popup (GTK_MENU(widget), NULL, NULL, NULL, NULL,
                        bevent->button, bevent->time);
        /* Tell calling code that we have handled this event; the buck
         * stops here. */
        return TRUE;
    }

    /* Tell calling code that we have not handled this event; pass it on. */
    return FALSE;
}
</programlisting>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I disable or enable a widget, such as a
	button?</title>

	<para>To disable (or to enable) a widget, use the
        <literal>gtk_widget_set_sensitive()</literal> function. The
        first parameter is you widget pointer. The second parameter is
        a boolean value: when this value is TRUE, the widget is
        enabled.</para>
      </sect2>

      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>Shouldn't the text argument in the gtk_clist_*
	functions be declared const?</title>

	<para>For example:</para>

<programlisting role="C">
gint gtk_clist_prepend (GtkCList *clist,
                        gchar    *text[]);
</programlisting>

	<para>Answer: No, while a type "gchar*" (pointer to char) can
        automatically be cast into "const gchar*" (pointer to const
        char), this does not apply for "gchar *[]" (array of an
        unspecified number of pointers to char) into "const gchar *[]"
        (array of an unspecified number of pointers to const char).</para>

	<para>The type qualifier "const" may be subject to automatic
        casting, but in the array case, it is not the array itself
        that needs the (const) qualified cast, but its members, thus
        changing the whole type.</para>
      </sect2>

     <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I render pixels (image data) to the
	screen?</title>

	<para>There are several ways to approach this. The simplest
        way is to use GdkRGB, see gdk/gdkrgb.h. You create an RGB
        buffer, render to your RGB buffer, then use GdkRGB routines to
        copy your RGB buffer to a drawing area or custom widget. The
        book "GTK+/Gnome Application Development" gives some details;
        GdkRGB is also documented in the GTK+ reference
        documentation.</para>

	<para>If you're writing a game or other graphics-intensive
        application, you might consider a more elaborate
        solution. OpenGL is the graphics standard that will let you
        access hardware accelaration in future versions of XFree86; so
        for maximum speed, you probably want to use OpenGL. A
        GtkGLArea widget is available for using OpenGL with GTK+ (but
        GtkGLArea does not come with GTK+ itself). There are also
        several open source game libraries, such as ClanLib and Loki's
        Simple DirectMedia Layer library (SDL).</para>

	<para>You do NOT want to use
	<literal>gdk_draw_point()</literal>, that will be extremely
	slow.</para>
      </sect2>

     <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I create a pixmap without having my window being
	realized/shown?</title>

	<para>Functions such as
        <literal>gdk_pixmap_create_from_xpm()</literal> require a
        valid window as a parameter. During the initialisation phase
        of an application, a valid window may not be available without
        showing a window, which may be inappropriate. In order to
        avoid this, a function such as
        <literal>gdk_pixmap_colormap_create_from_xpm</literal> can be
        used, as in:</para>

<programlisting role="C">
  char *pixfile = "foo.xpm";
  GtkWidget *top, *box, *pixw;
  GdkPixmap *pixmap, *pixmap_mask;

  top = gtk_window_new (GKT_WINDOW_TOPLEVEL);
  box = gtk_hbox_new (FALSE, 4);
  gtk_conainer_add (GTK_CONTAINER(top), box);
 
  pixmap = gdk_pixmap_colormap_create_from_xpm (
               NULL, gtk_widget_get_colormap(top),
               &amp;pixmap_mask, NULL, pixfile);
  pixw = gtk_pixmap_new (pixmap, pixmap_mask);
  gdk_pixmap_unref (pixmap);
  gdk_pixmap_unref (pixmap_mask);
</programlisting>
      </sect2>
    </sect1>
  </chapter>

  <!-- ***************************************************************** -->
  <chapter>
    <title>Development with GTK+: widget specific questions</title>
    <sect1>
      <title></title>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I find out about the selection of a GtkList?</title>

	<para>Get the selection something like this:</para>

<programlisting role="C">
GList *sel;
sel = GTK_LIST(list)->selection;
</programlisting>

	<para>This is how GList is defined (quoting glist.h):</para>

<programlisting role="C">
typedef struct _GList GList;

struct _GList
{
  gpointer data;
  GList *next;
  GList *prev;
};
</programlisting>

	<para>A GList structure is just a simple structure for doubly
        linked lists. there exist several g_list_*() functions to
        modify a linked list in glib.h.  However the
        GTK_LIST(MyGtkList)->selection is maintained by the
        gtk_list_*() functions and should not be modified.</para>


	<para>The selection_mode of the GtkList determines the
        selection facilities of a GtkList and therefore the contents
        of GTK_LIST(AnyGtkList)->selection:</para>
	<informaltable frame="all">
	  <tgroup cols="2">
	    <thead>
	      <row>
	      <entry><literal>selection_mode</literal></entry>
		<entry><literal> GTK_LIST()->selection</literal>
	      contents</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry><literal>GTK_SELECTION_SINGLE</literal></entry>
		<entry>selection is either NULL or contains a GList*
	                pointer for a single selected item.</entry>
	      </row>
	      <row>
		<entry><literal>GTK_SELECTION_BROWSE</literal></entry>
		<entry>selection is NULL if the list contains no
                        widgets, otherwise it contains a GList*
                        pointer for one GList structure.</entry>
	      </row>
	      <row>
		<entry><literal>GTK_SELECTION_MULTIPLE</literal></entry>
		<entry>selection is NULL if no listitems are selected
                        or a a GList* pointer for the first selected
                        item. that in turn points to a GList structure
                        for the second selected item and so
		        on.</entry>
	      </row>
	      <row>
		<entry><literal>GTK_SELECTION_EXTENDED</literal></entry>
		<entry>selection is NULL.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>

	<para>The data field of the GList structure
             GTK_LIST(MyGtkList)->selection points to the first
             GtkListItem that is selected.  So if you would like to
             determine which listitems are selected you should go like
             this:</para>

<programlisting role="C">
{
        gchar           *list_items[]={
                                "Item0",
                                "Item1",
                                "foo",
                                "last Item",
                        };
        guint           nlist_items=sizeof(list_items)/sizeof(list_items[0]);
        GtkWidget       *list_item;
        guint           i;

        list=gtk_list_new();
        gtk_list_set_selection_mode(GTK_LIST(list), GTK_SELECTION_MULTIPLE);
        gtk_container_add(GTK_CONTAINER(AnyGtkContainer), list);
        gtk_widget_show (list);

        for (i = 0; i < nlist_items; i++)
        {
                list_item=gtk_list_item_new_with_label(list_items[i]);
                gtk_object_set_user_data(GTK_OBJECT(list_item), (gpointer)i);
                gtk_container_add(GTK_CONTAINER(list), list_item);
                gtk_widget_show(list_item);
        }
}
</programlisting>

	<para>To get known about the selection:</para>

<programlisting role="C">
{
        GList   *items;

        items=GTK_LIST(list)->selection;

        printf("Selected Items: ");
        while (items) {
                if (GTK_IS_LIST_ITEM(items->data))
                        printf("%d ", (guint) 
                gtk_object_get_user_data(items->data));
                items=items->next;
        }
        printf("\n");
}
</programlisting>

      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I stop the column headings of a GtkCList
	disappearing when the list is scrolled?</title>

	<para>This happens when a GtkCList is packed into a
        GtkScrolledWindow using the function
        <literal>gtk_scroll_window_add_with_viewport()</literal>. The prefered
        method of adding a CList to a scrolled window is to use the
        function <literal>gtk_container_add</literal>, as in:</para>

<programlisting role="C">
    GtkWidget *scrolled, *clist;
    char *titles[] = { "Title1" , "Title2" };

    scrolled = gtk_scrolled_window_new(NULL, NULL);

    clist = gtk_clist_new_with_titles(2, titles);
    gtk_container_add(GTK_CONTAINER(scrolled), clist);
</programlisting>

      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>I don't want the user of my applications to enter text
	into a GtkCombo. Any idea?</title>

	<para>A GtkCombo has an associated entry which can be accessed
	using the following expression:</para>

<programlisting role="C">
      GTK_COMBO(combo_widget)->entry
</programlisting>

	<para>If you don't want the user to be able to modify the
	content of this entry, you can use the
	gtk_entry_set_editable() function:</para>


<programlisting role="C">
      void gtk_entry_set_editable(GtkEntry *entry, 
                                  gboolean editable);
</programlisting>

	<para>Set the editable parameter to FALSE to disable typing
	into the entry.</para>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I catch a combo box change?</title>

	<para>The entry which is associated to your GtkCombo send a
	"changed" signal when:</para>

	<itemizedlist>
	  <listitem><simpara>some text is typed in</simpara>
	  </listitem>
	  <listitem><simpara>the selection of the combo box is changed</simpara>
	  </listitem>
	</itemizedlist>

	<para>To catch any combo box change, simply connect your
	signal handler with</para>

<programlisting role="C">
      gtk_signal_connect(GTK_COMBO(cb)->entry,
                         "changed",
                         GTK_SIGNAL_FUNC(my_cb_change_handler),
                         NULL);
</programlisting>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How can I define a separation line in a menu?</title>

	<para>See the <ulink
	url="http://www.gtk.org/tutorial/">Tutorial</ulink> for
	information on how to create menus. However, to create a
	separation line in a menu, just insert an empty menu item:</para>

<programlisting role="C">
menuitem = gtk_menu_item_new();
gtk_menu_append(GTK_MENU(menu), menuitem);
gtk_widget_show(menuitem);
</programlisting>

      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How can I right justify a menu, such as Help?</title>

	<para>Depending on if you use the MenuFactory or not, there
	are two ways to proceed. With the MenuFactory, use something
	like the following:</para>

<programlisting role="C">
menu_path = gtk_menu_factory_find (factory,  "&lt;MyApp&gt;/Help");
gtk_menu_item_right_justify(menu_path->widget);
</programlisting>

	<para>If you do not use the MenuFactory, you should simply
	use:</para>


<programlisting role="C">
gtk_menu_item_right_justify(my_menu_item);
</programlisting>

      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I add some underlined accelerators to menu
	items?</title>

	<para>Damon Chaplin, the technical force behind the Glade
        project, provided the following code sample (this code is an
        output from Glade). It creates a small <GUIMenu>File</guimenu> menu item
        with only one child (<guimenu>New</guimenu>). The F in <guimenu>File</guimenu> and the N
        in <guimenu>New</guimenu> are underlined, and the relevant accelerators are
        created.</para>

<programlisting role="C">
  menubar1 = gtk_menu_bar_new ();
  gtk_object_set_data (GTK_OBJECT (window1), "menubar1", menubar1);
  gtk_widget_show (menubar1);
  gtk_box_pack_start (GTK_BOX (vbox1), menubar1, FALSE, FALSE, 0);

  file1 = gtk_menu_item_new_with_label ("");
  tmp_key = gtk_label_parse_uline (GTK_LABEL (GTK_BIN (file1)->child),
                                   _("_File"));
  gtk_widget_add_accelerator (file1, "activate_item", accel_group,
                              tmp_key, GDK_MOD1_MASK, 0);
  gtk_object_set_data (GTK_OBJECT (window1), "file1", file1);
  gtk_widget_show (file1);
  gtk_container_add (GTK_CONTAINER (menubar1), file1);

  file1_menu = gtk_menu_new ();
  file1_menu_accels = gtk_menu_ensure_uline_accel_group (GTK_MENU (file1_menu));
  gtk_object_set_data (GTK_OBJECT (window1), "file1_menu", file1_menu);
  gtk_menu_item_set_submenu (GTK_MENU_ITEM (file1), file1_menu);

  new1 = gtk_menu_item_new_with_label ("");
  tmp_key = gtk_label_parse_uline (GTK_LABEL (GTK_BIN (new1)->child),
                                   _("_New"));
  gtk_widget_add_accelerator (new1, "activate_item", file1_menu_accels,
                              tmp_key, 0, 0);
  gtk_object_set_data (GTK_OBJECT (window1), "new1", new1);
  gtk_widget_show (new1);
  gtk_container_add (GTK_CONTAINER (file1_menu), new1);
</programlisting>

      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How can I retrieve the text from a GtkMenuItem?</title>

	<para>You can usually retrieve the label of a specific
	GtkMenuItem with:</para>

<programlisting role="C">
    if (GTK_BIN (menu_item)->child)
    {
      GtkWidget *child = GTK_BIN (menu_item)->child;
  
      /* do stuff with child */
      if (GTK_IS_LABEL (child))
      {
        gchar *text;
    
        gtk_label_get (GTK_LABEL (child), &amp;text);
        g_print ("menu item text: %s\n", text);
      }
    }
</programlisting>

	<para>To get the active menu item from a GtkOptionMenu you can
	do:</para>

<programlisting role="C">
if (GTK_OPTION_MENU (option_menu)->menu_item)
{
  GtkWidget *menu_item = GTK_OPTION_MENU (option_menu)->menu_item;
}
</programlisting>

	<para>But, there's a catch. For this specific case, you can
        <emphasis>not</emphasis> get the label widget from
        <literal>menu_item</literal> with the above code, because the
        option menu reparents the menu_item's child temporarily to
        display the currently active contents. So to retrive the child
        of the currently active menu_item of an option menu, you'll
        have to do:</para>


<programlisting role="C">
    if (GTK_BIN (option_menu)->child)
    {
      GtkWidget *child = GTK_BIN (option_menu)->child;

      /* do stuff with child */
    }
</programlisting>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I right (or otherwise) justify a
	GtkLabel?</title>

	<para>Are you sure you want to <emphasis>justify</emphasis>
        the labels? The label class contains the
        <literal>gtk_label_set_justify()</literal> function that is
        used to control the justification of a multi-line
        label.</para>

	<para>What you probably want is to set the <emphasis>alignment</emphasis>
        of the label, ie right align it, center it or left align
        it. If you want to do this, you should use:</para>

<programlisting role="C">
void gtk_misc_set_alignment (GtkMisc *misc,
                             gfloat xalign,
                             gfloat yalign);
</programlisting>

	<para>where the <literal>xalign</literal> and
	<literal>yalign</literal> values are floats in
	[0.00;1.00].</para>


<programlisting role="C">
GtkWidget       *label;

/* horizontal : left align, vertical : top */
gtk_misc_set_alignment(GTK_MISK(label), 0.0f, 0.0f);

/* horizontal : centered, vertical : centered */
gtk_misc_set_alignment(GTK_MISK(label), 0.5f, 0.5f);

/* horizontal : right align, vertical : bottom */
gtk_misc_set_alignment(GTK_MISK(label), 1.0f, 1.0f);
</programlisting>
      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I set the background color of a GtkLabel
	widget?</title>

	<para>The Gtklabel widget is one of a few GTK+ widgets that
        don't create their own window to render themselves
        into. Instead, they draw themselves directly onto their
        parents window.</para>

	<para>This means that in order to set the background color for
        a GtkLabel widget, you need to change the background color of
        its parent, i.e. the object that you pack it into.</para>
      </sect2> 
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I set the color and font of a GtkLabel using a
	Resource File?</title>

	<para>The widget name path constructed for a Label consists of
	the widget names of its object hierarchy as well, e.g.</para>

	<para><literallayout>
        <literal>window (name: humphrey)</literal>
	<literal>  hbox</literal>
        <literal>     label (name: mylabel)</literal>
        </literallayout></para>

	<para>The widget path your pattern needs to match would be:
        <literal>humphrey.GtkHBox.mylabel</literal></para>

	<para>The resource file may look something like:</para>

<programlisting role="C">
style "title"
{
      fg[NORMAL] = {1.0, 0.0, 0.0}
      font = "-adobe-helvetica-bold-r-normal--*-140-*-*-*-*-*-*"
}
widget "*mylabel" style "title"
</programlisting>

	<para>In your program, you would also need to give a name to
	the Label widget, which can be done using:</para>

<programlisting role="C">
  label = gtk_label_new("Some Label Text");
  gtk_widget_set_name(label, "mylabel");
  gtk_widget_show(label);
</programlisting>

      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I configure Tooltips in a Resource File?</title>

	<para>The tooltip's window is named "gtk-tooltips",
        GtkTooltips in itself is not a GtkWidget (though a GtkObject)
        and as such is not attempted to match any widget styles.</para>

	<para>So, you resource file should look something like:</para>

<programlisting role="C">
style "postie"
{
      bg[NORMAL] = {1.0, 1.0, 0.0}
}
widget "gtk-tooltips*" style "postie"
</programlisting>

      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>I can't add more than (something like) 2000 chars in a
	GtkEntry. What's wrong?</title>

	<para>There is now a known problem in the GtkEntry widget. In
        the <literal>gtk_entry_insert_text()</literal> function, the
        following lines limit the number of chars in the entry to
        2047.</para>

<programlisting role="C">
  /* The algorithms here will work as long as, the text size (a
   * multiple of 2), fits into a guint16 but we specify a shorter
   * maximum length so that if the user pastes a very long text, there
   * is not a long hang from the slow X_LOCALE functions.  */

  if (entry->text_max_length == 0)
    max_length = 2047;
  else
    max_length = MIN (2047, entry->text_max_length);
</programlisting>

      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I make a GtkEntry widget activate on pressing
	the Return key?</title>

	<para>The Entry widget emits an 'activate' signal when you
        press return in it. Just attach to the activate signal on the
        entry and do whatever you want to do. Typical code would
        be:</para>

<programlisting role="C">
  entry = gtk_entry_new();
  gtk_signal_connect (GTK_OBJECT(entry), "activate",
                      GTK_SIGNAL_FUNC(entry_callback),
                      NULL);
</programlisting>

      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I validate/limit/filter the input to a
	GtkEntry?</title>

	<para>If you want to validate the text that a user enters into
        a GtkEntry widget you can attach to the "insert_text" signal
        of the entry, and modify the text within the callback
        function. The example below forces all characters to
        uppercase, and limits the range of characters to A-Z. Note
        that the entry is cast to an object of type GtkEditable, from
        which GtkEntry is derived.</para>

<programlisting role="C">
#include &lt;ctype.h&gt;
#include &lt;gtk/gtk.h&gt;

void insert_text_handler (GtkEntry    *entry,
                          const gchar *text,
                          gint         length,
                          gint        *position,
                          gpointer     data)
{
  GtkEditable *editable = GTK_EDITABLE(entry);
  int i, count=0;
  gchar *result = g_new (gchar, length);

  for (i=0; i < length; i++) {
    if (!isalpha(text[i]))
      continue;
    result[count++] = islower(text[i]) ? toupper(text[i]) : text[i];
  }
  
  if (count > 0) {
    gtk_signal_handler_block_by_func (GTK_OBJECT (editable),
				      GTK_SIGNAL_FUNC (insert_text_handler),
				      data);
    gtk_editable_insert_text (editable, result, count, position);
    gtk_signal_handler_unblock_by_func (GTK_OBJECT (editable),
					GTK_SIGNAL_FUNC (insert_text_handler),
					data);
  }
  gtk_signal_emit_stop_by_name (GTK_OBJECT (editable), "insert_text");
  
  g_free (result);
}

int main (int   argc,
          char *argv[])
{
  GtkWidget *window;
  GtkWidget *entry;
  
  gtk_init (&amp;argc, &amp;argv);
  
  /* create a new window */
  window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
  gtk_window_set_title(GTK_WINDOW (window), "GTK Entry");
  gtk_signal_connect(GTK_OBJECT (window), "delete_event",
		     (GtkSignalFunc) gtk_exit, NULL);
  
  entry = gtk_entry_new();
  gtk_signal_connect(GTK_OBJECT(entry), "insert_text",
		     GTK_SIGNAL_FUNC(insert_text_handler),
		     NULL);
  gtk_container_add(GTK_CONTAINER (window), entry);
  gtk_widget_show(entry);
  
  gtk_widget_show(window);
  
  gtk_main();
  return(0);
}
</programlisting>

      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I use horizontal scrollbars with a GtkText
	widget?</title>

	<para>The short answer is that you can't. The current version
        of the GtkText widget does not support horizontal
        scrolling. There is an intention to completely rewrite the
        GtkText widget, at which time this limitation will be
        removed.</para>

      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I change the font of a GtkText widget?</title>

	<para>There are a couple of ways of doing this. As GTK+ allows
        the appearance of applications to be changed at run time using
        resources you can use something like the following in the
        appropriate file:</para>

<programlisting role="C">
style "text"
{
  font = "-adobe-helvetica-medium-r-normal--*-100-*-*-*-*-*-*"
}
</programlisting>

	<para>Another way to do this is to load a font within your
        program, and then use this in the functions for adding text to
        the text widget. You can load a font using, for example:</para>

<programlisting role="C">
  GdkFont *font;
  font = gdk_font_load("-adobe-helvetica-medium-r-normal--*-140-*-*-*-*-*-*");
</programlisting>

      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I set the cursor position in a GtkText
	object?</title>

	<para>Notice that the response is valid for any object that
	inherits from the GtkEditable class.</para>

	<para>Are you sure that you want to move the cursor position?
        Most of the time, while the cursor position is good, the
        insertion point does not match the cursor position. If this
        apply to what you really want, then you should use the
        <literal>gtk_text_set_point()</literal> function. If you want
        to set the insertion point at the current cursor position, use
        the following:</para>

<programlisting role="C">
  gtk_text_set_point(GTK_TEXT(text),
  gtk_editable_get_position(GTK_EDITABLE(text)));
</programlisting>

	<para>If you want the insertion point to follow the cursor at
        all time, you should probably catch the button press event,
        and then move the insertion point. Be careful : you'll have to
        catch it after the widget has changed the cursor position
        though. Thomas Mailund Jensen proposed the following
        code:</para>

<programlisting role="C">
static void
insert_bar (GtkWidget *text)
{
  /* jump to cursor mark */
  gtk_text_set_point (GTK_TEXT (text),
  gtk_editable_get_position (GTK_EDITABLE  (text)));

  gtk_text_insert (GTK_TEXT (text), NULL, NULL, NULL,
     "bar", strlen ("bar"));
}

int
main (int argc, char *argv[])
{
  GtkWidget *window, *text;

  gtk_init (&amp;argc, &amp;argv);

  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  text = gtk_text_new (NULL, NULL);
  gtk_text_set_editable (GTK_TEXT (text), TRUE);
  gtk_container_add (GTK_CONTAINER (window), text);

  /* connect after everything else */
  gtk_signal_connect_after (GTK_OBJECT(text), "button_press_event",
    GTK_SIGNAL_FUNC (insert_bar), NULL);

  gtk_widget_show_all(window);
  gtk_main();

  return 0;
}
</programlisting>

	<para>Now, if you really want to change the cursor position,
	you should use the
	<literal>gtk_editable_set_position()</literal>
	function.</para>

      </sect2>

    </sect1>
  </chapter>

  <!-- ***************************************************************** -->
  <chapter>
    <title>About GDK</title>
    <sect1>
      <title></title>
 
      <!-- ----------------------------------------------------------------- -->

      <sect2>
	<title>What is GDK?</title>

	<para>GDK is basically a wrapper around the standard Xlib
        function calls. If you are at all familiar with Xlib, a lot of
        the functions in GDK will require little or no getting used
        to. All functions are written to provide an way to access Xlib
        functions in an easier and slightly more intuitive manner. In
        addition, since GDK uses GLib (see below), it will be more
        portable and safer to use on multiple platforms.</para>

        <!-- Examples, anybody? I've been mulling some over. NF -->

      </sect2>
 
      <!-- ----------------------------------------------------------------- -->

     <sect2>
	<title>How do I use color allocation?</title>

	<para>One of the nice things about GDK is that it's based on
        top of Xlib; this is also a problem, especially in the area of
        color management. If you want  to use color in your program
        (drawing a rectangle or such, your code  should look something
        like this:</para>

<programlisting role="C">
{
  GdkColor *color;
  int width, height;
  GtkWidget *widget;
  GdkGC *gc;

  ...
  
  /* first, create a GC to draw on */
  gc = gdk_gc_new(widget->window);

  /* find proper dimensions for rectangle */
  gdk_window_get_size(widget->window, &amp;width, &amp;height);

  /* the color we want to use */
  color = (GdkColor *)malloc(sizeof(GdkColor));
  
  /* red, green, and blue are passed values, indicating the RGB triple
   * of the color we want to draw. Note that the values of the RGB components
   * within the GdkColor are taken from 0 to 65535, not 0 to 255.
   */
  color->red = red * (65535/255);
  color->green = green * (65535/255);
  color->blue = blue * (65535/255);
  
  /* the pixel value indicates the index in the colormap of the color.
   * it is simply a combination of the RGB values we set earlier
   */
  color->pixel = (gulong)(red*65536 + green*256 + blue);

  /* However, the pixel valule is only truly valid on 24-bit (TrueColor)
   * displays. Therefore, this call is required so that GDK and X can
   * give us the closest color available in the colormap
   */
  gdk_color_alloc(gtk_widget_get_colormap(widget), color);

  /* set the foreground to our color */
  gdk_gc_set_foreground(gc, color);
  
  /* draw the rectangle */
  gdk_draw_rectangle(widget->window, gc, 1, 0, 0, width, height);

  ...
}
</programlisting>

      </sect2>
    </sect1>
  </chapter>

  <!-- ----------------------------------------------------------------- -->

</book>