gtk/docs/faq/gtk-faq.sgm

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

  <bookinfo>
    <date>June 21st 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>

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

</book>