<!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>GTK+ FAQ</title>
- <sect1>
- <title>General Information</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>
-
- <!-- ***************************************************************** -->
- <sect1>
- <title>How to find, configure, install, and troubleshoot GTK+</title>
-
- <!-- ----------------------------------------------------------------- -->
+<bookinfo>
+ <date>January 14th 2004</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>
+ <para><emphasis>Note: </emphasis> This FAQ mainly covers GTK+ 1.2.
+ Where the text covers GTK+ 2.x this will be indicated</para>
+ </abstract>
+</bookinfo>
+
+<toc></toc>
+
+<!-- ***************************************************************** -->
+<chapter>
+<title>General Information</title>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>Note: This FAQ is undergoing conversion to GTK+ 2.x</title>
+<para>This FAQ is undergoing conversion to GTK+ 2.x.
+Where the text covers GTK+ 2.x this will be indicated by prefixing the
+text with: <emphasis>[GTK+ 2.x]</emphasis>. Where this is not
+indicated, the text has not yet been updated from GTK+ 1.2 and may
+not be totally correct.
+</para>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>Before anything else: the greetings <emphasis>[GTK 2.x]</emphasis></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>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>Authors <emphasis>[GTK 2.x]</emphasis></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>
- <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
+<para>Since then, much has been added by others. Please see the
+AUTHORS file in the distribution for the GTK+ Team. The people currently
+contributing the most code to GTK+ are (in no particular order):</para>
+
+
+<itemizedlist spacing=Compact>
+<listitem>
+<simpara>Owen Taylor</simpara>
+</listitem>
+<listitem>
+<simpara>Matthias Clasen</simpara>
+</listitem>
+<listitem>
+<simpara>Federico Mena Quintero</simpara>
+</listitem>
+<listitem>
+<simpara>Soeren Sandmann</simpara>
+</listitem>
+<listitem>
+<simpara>Padraig O'Briain</simpara>
+</listitem>
+<listitem>
+<simpara>Manish Singh</simpara>
+</listitem>
+<listitem>
+<simpara>Kristian Rietveld</simpara>
+</listitem>
+<listitem>
+<simpara>Tor Lillqvist</simpara>
+</listitem>
+</itemizedlist>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>What is GTK+? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>GTK+ is a multi-platform toolkit for creating graphical user
+interfaces, originally designed with
+the general look and feel of Motif. In reality, it looks much
+better than Motif. It contains common and complex widgets, such as
+file selection, and color selection widgets.</para>
+
+<para>GTK+ was initially developed as a widget set for the GIMP (GNU Image
+Manipulation Program). It has grown extensively since then, and is today
+used by a large number of applications, and is the toolkit used by the
+<ulink url="http://www.gnome.org/">GNOME</ulink> desktop project.</para>
+
+<para>GTK+ is free software and part of the GNU Project. However, the
+licensing terms for GTK+, the GNU LGPL, allow it to be used by all developers,
+including those developing proprietary software, without any license fees
+or royalties.</para>
+
+<para>GTK+ has been designed from the ground up to support a range of
+<ulink url="http://www.gtk.org/bindings.html">
+language bindings</ulink>, not only C/C++. Using GTK+ from languages
+such as Perl and Python (especially in combination with the Glade GUI
+builder) provides an effective method of rapid application
+development..</para>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>What is the + in GTK+? <emphasis>[GTK 2.x]</emphasis></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>
+
+<para>Although much has changed with GTK+, and Peter, Spencer and Josh
+don't have any direct involvement these days, the name is kept to keep
+a link with the heritage of GTK+.</para>
+
+<para>GTK+ is now additionally based upon the Pango and ATK
+libraries, that provide text layout and rendering and accessibility
+interfaces.</para>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>Does the G in GTK+, GDK and GLib stand for? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>GTK+ == The GIMP Toolkit</para>
+<para>GDK == GTK+ Drawing Kit</para>
+<para>GLib == G Library</para>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>Where is the documentation for GTK+? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>In the GTK+ distribution's doc/ directory you will find
+the API Reference 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 few books available that deal with
+programming GTK+, GDK and GNOME. Unfortunately, they
+currently are all based upon GTK+ 1.x:</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>
+<listitem><simpara>"GTK+ Programming in C" by
+Syd Logan. ISBN: 0-1301-4264-6</simpara>
+</listitem>
+<listitem><simpara>"Linux GNOME/GTK+ Programming Bible" by
+Arthur Griffith. ISBN: 0-7645-4640-6</simpara>
+</listitem>
+<listitem><simpara>"Beginning GTK+/GNOME Programming" by
+Peter Wright. ISBN: 1-8610-0381-1</simpara>
+</listitem>
+<listitem><simpara>"Sams Teach Yourself GTK+ Programming
+in 21 Days" by Donna Martin
+. ISBN: 0-6723-1829-6</simpara>
+</listitem>
+</itemizedlist>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1 id="faq-MailLists">
+<title>Is there a mailing list (or mailing list archive) for
+GTK+? <emphasis>[GTK 2.x]</emphasis></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>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>How to get help with GTK+ <emphasis>[GTK 2.x]</emphasis></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>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>How to report bugs in GTK+ <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>Bugs should be reported to the GNOME bug tracking system
+(<ulink url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>).
+You will need to enter your email address and receive a password before
+you can use the system to register a new bug report.</para>
+
+<para>There are a number of options to select and boxes to fill in when
+submitting a bug report. Please remember that the more information you
+give, the easier it will be to track the problem down. Extra information
+that may prove useful includes:</para>
+
+<itemizedlist>
+<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 complete, 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 occurred. If you can easily reproduce this
+crash then running the program under a debugger (e.g. gdb) and getting
+a backtrace when the crash occurs is very useful.</simpara>
+</listitem>
+
+<listitem><simpara> Further information such as stack traces
+may be useful. 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>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>Is there a Windows version of GTK+? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>The Win32 port of GTK+ is maintained concurrently with the Xwindows
+version in CVS. As such it is a supported architecture.</para>
+
+<para>The Win32 port has been predominately done by Tor Lillqvist. Tor
+maintains some information on <ulink url="http://www.gimp.org/~tml/gimp/win32/">
+GTK+ and GIMP for Windows</ulink>.</para>
+
+<para>There is a pre-compiled, easy-to-install version of GTK+ for
+windows on the <ulink url="http://www.dropline.net/gtk/">
+Dropline GTK+</ulink> site.</para>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>What applications have been written with GTK+? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>The GNOME software map contains a catalogue of software that is
+built using GNOME and GTK+. The catalogue is searchable and browsable, so
+provides easy access.</para>
+
+<para>Some of the best known projects utilising GTK+ 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.abiword.org/">http://www.abiword.com/</ulink>),
+a professional word processor</simpara>
+</listitem>
+<listitem><simpara> Dia (<ulink
+url="http://www.lysator.liu.se/~alla/dia/dia.html">
+http://www.lysator.liu.se/~alla/dia/dia.html</ulink>),
+a diagram creation program</simpara>
+</listitem>
+<listitem><simpara> GnuCash (<ulink
+url="http://www.gnucash.org/">
+http://www.gnucash.org/</ulink>),
+a personal finance manager</simpara>
+</listitem>
+<listitem><simpara> Gnumeric (<ulink
+url="http://www.gnome.org/projects/gnumeric/">
+http://www.gnome.org/projects/gnumeric/</ulink>),
+the GNOME spreadsheet application</simpara>
+</listitem>
+<listitem><simpara> Glade (<ulink
+url="http://glade.gnome.org/">http://glade.gnome.org/</ulink>), a
+GTK+ based RAD tool which produces GTK+ and GNOME applications</simpara>
+</listitem>
+<listitem><simpara> Anjuta (<ulink
+url="http://anjuta.sourceforge.net/">http://anjuta.sourceforge.net/</ulink>),
+a versatile Integrated Development Environment (IDE) using C and C++ for GTK+
+and GIMP.</simpara>
+</listitem>
+</itemizedlist>
+</sect1>
+
+</chapter>
+
+<!-- ***************************************************************** -->
+<chapter>
+<title>How to find, configure, install, and troubleshoot GTK+</title>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1 id="faq-Compile">
+<title>What do I need to compile GTK+? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>GTK+ is a large package that is dependent on a number of other
+tools and libraries. It is recommended that you use precompiled
+binary packages for your system if possible</para>
+
+<para>To compile GTK+ from source you need a C compiler (gcc) and
+the X Window System and associated development libraries and packages
+on your system.</para>
+
+<para>You will also need to have installed the tools
+and libraries that GTK+ depends upon. These are listed below in the order
+in which they need to be installed:</para>
+
+<itemizedlist spacing=compact>
+<listitem><simpara> pkg-config
+(<ulink url="http://pkg-config.freedesktop.org/wiki">
+pkg-config Site</ulink>)</simpara>
+</listitem>
+
+<listitem><simpara> GNU make
+(<ulink url="http://www.gnu.org/software/make/">
+GNU make Site</ulink>)</simpara>
+</listitem>
+
+<listitem><simpara> JPEG, PNG and TIFF image libraries
+(<ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/dependencies/">
+GTK+ Site</ulink>)</simpara>
+</listitem>
+
+<listitem><simpara> FreeType
+(<ulink url="http://www.freetype.org/">
+FreeType Site</ulink>)</simpara>
+</listitem>
+
+<listitem><simpara> fontconfig
+(<ulink url="http://www.fontconfig.org/">
+fontconfig Site</ulink>)</simpara>
+</listitem>
+
+<listitem><simpara> GNU libiconv library (if your system doesn't have iconv())
+(<ulink url="http://www.gnu.org/software/libiconv/">
+GNU libiconv Site</ulink>)</simpara>
+</listitem>
+
+<listitem><simpara> GNU gettext (if your system doesn't have gettext())
+(<ulink url="http://www.gnu.org/software/gettext/">
+GTK+ Site</ulink>)</simpara>
+</listitem>
+
+<listitem><simpara> GLib
+(<ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">
+GTK+ Site</ulink>)</simpara>
+</listitem>
+
+<listitem><simpara> Pango
+(<ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">
+GTK+ Site</ulink>)</simpara>
+</listitem>
+
+<listitem><simpara> ATK
+(<ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">
+GTK+ Site</ulink>)</simpara>
+</listitem>
+
+<listitem><simpara> GTK+
+(<ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">
+GTK+ Site</ulink>)</simpara>
+</listitem>
+</itemizedlist>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>Where can I get GTK+? <emphasis>[GTK 2.x]</emphasis></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 -
+<ulink url="ftp://ftp.is.co.za/applications/gimp">
+ftp://ftp.is.co.za/applications/gimp</ulink></simpara>
+</listitem>
+
+<listitem><simpara> Australia -
+<ulink
+url="ftp://ftp.planetmirror.com/pub/gimp/gtk">
+ftp://ftp.planetmirror.com/pub/gimp/gtk</ulink></simpara>
+</listitem>
+
+<listitem><simpara> Finland -
+<ulink url="ftp://ftp.funet.fi/pub/sci/graphics/packages/gimp/gtk">
+ftp://ftp.funet.fi/pub/sci/graphics/packages/gimp/gtk</ulink></simpara>
+</listitem>
+
+<listitem><simpara> Germany -
+<ulink url="ftp://ftp.gwdg.de/pub/misc/grafik/gimp/gtk">
+ftp://ftp.gwdg.de/pub/misc/grafik/gimp/gtk</ulink></simpara>
+</listitem>
+
+<listitem><simpara> Japan -
+<ulink url="ftp://sunsite.sut.ac.jp/pub/archives/packages/gimp/gtk">
+ftp://sunsite.sut.ac.jp/pub/archives/packages/gimp/gtk</ulink></simpara>
+</listitem>
+
+<listitem><simpara> UK -
+<ulink url="http://www.mirror.ac.uk/sites/ftp.gimp.org/pub/gtk/">
+http://www.mirror.ac.uk/sites/ftp.gimp.org/pub/gtk/</ulink></simpara>
+</listitem>
+</itemizedlist>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>How do I configure/compile GTK+? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>Generally, the minimum you need to do is issue the commands:</para>
+
+<para><literallayout><literal>./configure</literal>
+<literal>make</literal>
+<literal>make install</literal></literallayout></para>
+
+<para>in the GTK+ source directory.</para>
+
+<para>This generally also holds true for each of the packages that GTK+
+depends upon, listed <link linkend="faq-Compile">above</link>.</para>
+
+<para>There are various options that you can pass to the configure script
+in order to change its default settings. The one that you are most likely
+to want to use is the <literal>--prefix</literal>
+argument, which defines where the package is to be install, e.g.</para>
+
+<para>
+<literallayout><literal>./configure --prefix=/usr</literal></literallayout>
+</para>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>When compiling GTK+ I get an error like: <literal>make:
+file `Makefile' line 456: Syntax error</literal> <emphasis>[GTK 2.x]</emphasis></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>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>I've compiled and installed GTK+, but I can't get any
+programs to link with it! <emphasis>[GTK 2.x]</emphasis></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'.</para>
+
+<para>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:</para>
+
+<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 libraries GTK requires using</para>
+
+<para><literallayout><literal>pkg-config gtk+-2.0 --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>
-
- <!-- ***************************************************************** -->
- <sect1>
- <title>Development of GTK+</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
- <oldfile> <newfile>.</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<username>-<date yymmdd-n>.patch.gz</literal>
-<literal>gtk-<username>-<date yymmdd-n>.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ß</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>
-
- <!-- ***************************************************************** -->
- <sect1>
- <title>Development with GTK+: the begining</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>
-
- <!-- ----------------------------------------------------------------- -->
+<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>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>When installing a GTK+ application, configure reports
+that it can't find GTK. <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>There are several common reasons for this:</para>
+
+<itemizedlist>
+<listitem><simpara>You have an old version of GTK installed
+somewhere. You should remove this old copy, but note that
+this may break applications that have been compiled against
+the old version.</simpara>
+</listitem>
+
+<listitem><simpara><literal>pkg-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>pkg-config gtk+-2.0 --modversion</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>
+
+</sect1>
+
+</chapter>
+
+<!-- ***************************************************************** -->
+<chapter>
+<title>Development of GTK+</title>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>Whats this CVS thing that everyone keeps talking about,
+and how do I access it? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>CVS is the Concurrent Version System and is a very
+popular means of version control for software projects. It is
+designed to allow multiple authors 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
+their 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>
+
+<para>The CVS archive stores both the current development version of
+GTK+ (the CVS HEAD branch) and all current and past stable versions.
+If you want to retrieve a specific version of GTK+ you have to specify
+the CVS tag corresponding to the version you want to checkout. If you
+want to checkout the current GTK+ 2.2 stable source code, you would need
+to use the following command:</para>
+
+<para><literallayout>
+<literal>cvs -z3 get -r gtk-2-2 gtk+</literal>
+</literallayout></para>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1 id="faq-Patches">
+<title>How can I contribute to GTK+? <emphasis>[GTK 2.x]</emphasis></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
+<oldfile> <newfile></literal>.</para>
+
+<para>The patch should then be attached to a bug report in
+the GNOME bug tracking system, which can also be used to store
+general patches
+(<ulink url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>).
+</para>
+
+<para>This method ensures that the patch will not be lost.</para>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>How do I know if my patch got applied, and if not, why
+not? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>If you have used the GNOME bug tracking system (as stated
+<link linkend="faq-Patches">above</link>) then the status
+of your patch should be reflected in the bug report.</para>
+
+<para>The GTK+ developers will generally add comments to the bug
+report stating what needs to be done to get the patch applied,
+or why the patch is not appropriate.</para>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>What is the policy on incorporating new widgets into
+the library? <emphasis>[GTK 2.x]</emphasis></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>
+
+<para>The new widgets that get added to GTK+ are generally either
+replacements for existing widgets that are no longer
+deemed to be adequate, or have been developed externally to GTK+ but
+have been widely tested.
+
+<para>Before you spend months of your valuable time implementing your
+revolutionary widget, it is highly recommended that you get some
+feedback on your idea via the appropriate
+<link linkend="faq-MailLists">mailing list</link>.</para>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>Is anyone working on bindings for languages other than
+C? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>There is a list of <ulink url="http://www.gtk.org/bindings.html">
+language bindings</ulink> on the GTK+ website.</para>
+
+<para>The 'official' language bindings are C++, Ada and Python.
+However, bindings for many other languages are available.</para>
+</sect1>
+
+</chapter>
+
+<!-- ***************************************************************** -->
+<chapter>
+<title>Development with GTK+: the begining</title>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>How do I get started? <emphasis>[GTK 2.x]</emphasis></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://library.gnome.org/devel/gtk-tutorial/stable/">
+http://library.gnome.org/devel/gtk-tutorial/stable/</ulink>, which is undergoing
+development. This will introduce you to writing applications
+using C.</para>
+
+<para>The GTK+ Tutorial doesn't 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 in the
+directory 'tests' (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>
- <title>What about using the <command>make</command>
- utility?</title>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>How do I use the Glade GUI builder with GTK+? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>There are two ways to use Glade. The first way is to use
+Glade's facilities for generating code; the second
+way is to use the libglade library which directly loads
+the XML user interface description files that Glade
+generates into a running program.</para>
+
+<para>Experienced GTK+ programmers generally strongly recommend
+using libglade; you don't have to worry about the interaction
+between Glade generating the source and you editing it,
+and its been shown to be a method that works better
+for large projects, so there is a lot of example code
+out there you can look at.</para>
+
+<para>An introduction to using libglade can be found in the
+libglade API docs
+(<ulink url="http://developer.gnome.org/doc/API/2.0/libglade/libglade-notes.html#libglade-basics">
+http://developer.gnome.org/doc/API/2.0/libglade/libglade-notes.html#libglade-basics</ulink>)
+.</para>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>How do I write security sensitive/SUID/SGID programs with GTK+?
+Is GTK+ secure? What's this GTK_MODULES security hole I heard about?
+<emphasis>[GTK 2.x]</emphasis></title>
+
+<para>The short answer to this question is: you can't, so don't write SUID/SGID
+programs with GTK+</para>
+
+<para>GTK+ will refuse to run with elevated privileges, as it is not designed
+to be used in this manner. The only correct way to write a setuid program with
+a graphical user interface is to have a setuid backend that communicates with
+the non-setuid graphical user interface via a mechanism such as a pipe and that
+considers the input it receives to be untrusted.</para>
+
+<para>For a more thorough explanation of the GTK+ Developers position on
+this issue see <ulink
+url="http://www.gtk.org/setuid.html">http://www.gtk.org/setuid.html</ulink>.</para>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>I tried to compile a small <command>Hello World</command> of mine,
+but it failed. Any clue? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>Since you are good at coding, we will not deal with
+compile time errors here :)</para>
+
+<para>The classic command line to compile a GTK+ based program is</para>
+<para><literallayout>
+<literal>gcc -o myprog [c files] `pkg-config gtk+-2.0 --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 quotes instead of backquotes. If
+you do so, the compiler will complain about an unknown file
+called <filename>pkg-config gtk+-2.0 --cflags --libs</filename>. The
+text in backquotes is an instruction to your shell to
+substitute the output of executing this command into the
+commandline.</para>
+
+<para>The command line above ensures 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>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>What about using the <command>make</command>
+utility? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>This is a sample makefile which compiles a GTK+ based
+program:</para>
- <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`
+CFLAGS = `pkg-config gtk+-2.0 --cflags`
+LDADD = `pkg-config gtk+-2.0 --libs`
CC = gcc
PACKAGE = myprg
all : ${OBJS}
- ${CC} -o ${PACKAGE} ${OBJS} ${LDADD}
+ ${CC} -o ${PACKAGE} ${OBJS} ${LDADD}
.c.o:
- ${CC} ${CFLAGS} -c $<
+ ${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>
-
- <!-- ----------------------------------------------------------------- -->
+<para>For more information about the <command>make</command> utility, you
+should read either the related man page or the relevant info file.</para>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>I use the backquote stuff in my makefiles, but my make
+process failed. <emphasis>[GTK 2.x]</emphasis></title>
- <sect2>
- <title>I want to add some configure stuff, how could I do
- this?</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/gnu/make/">ftp://ftp.gnu.org/gnu/make/</ulink>).</para>
- <para>To use autoconf/automake, you must first install the
- relevant packages. These are:</para>
+</sect1>
- <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>
+<sect1>
+<title>I want to add some configure stuff, how could I do
+this? <emphasis>[GTK 2.x]</emphasis></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.54 or better</simpara>
+</listitem>
+
+<listitem><simpara>automake v1.7 or better suggested</simpara>
+</listitem>
+</itemizedlist>
- <para>In order to use the powerful autoconf/automake scheme,
- you must create a configure.in which may look like:</para>
+<para>You'll find these packages on the main GNU 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.ac 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
+dnl configure.ac for a GTK+ based program
-AC_INIT(myprg.c)dnl
-AM_INIT_AUTOMAKE(mypkgname,0.0.1)dnl
-AM_CONFIG_HEADER(config.h)dnl
+AC_INIT(myprg.c)
+AM_INIT_AUTOMAKE(mypkgname, 0.0.1)
+AM_CONFIG_HEADER(config.h)
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
+AM_PATH_GTK_2_0(2.2.0,,AC_MSG_ERROR(mypkgname 0.1 needs GTK+ 2.2.0))
AC_OUTPUT(
Makefile
-)dnl
+)
</programlisting>
-
<para>You must add a Makefile.am file:</para>
+<para>You must add a Makefile.am file:</para>
<programlisting role="C">
bin_PROGRAMS = myprg
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>
+<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>
+<para>then, to use these, simply type the following
+commands:</para>
<programlisting role="C">
aclocal
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>
-
- <!-- ***************************************************************** -->
- <sect1>
- <title>Development with GTK+: general questions</title>
-
- <!-- ----------------------------------------------------------------- -->
+<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>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>I try to debug my GTK+ application with gdb, but it
+hangs my X server when I hit some breakpoint. Any
+Idea? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>From Federico Mena Quintero:</para>
+
+<para><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.</quote></para>
+
+<para><quote>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:</para>
+
+<para><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>
- <title>What widgets are in GTK?</title>
+<para>
+Another option is to run your application on Xnest. Xnest is an X server
+which displays its root window in a regular window of another X server.
+A pointer grab on the Xnest display will not affect the GUI of your debugger
+running on your regular X server.
+<programlisting>
+Xnest :1
+twm -display :1
+myapp --display=:1
+</programlisting>
+</para>
+</sect1>
+</chapter>
+
+<!-- ***************************************************************** -->
+<chapter>
+<title>Development with GTK+: general questions</title>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>What widgets are in GTK?</title>
+
+<para>The GTK+ Tutorial lists the following widgets:</para>
- <para>The GTK+ Tutorial lists the following widgets:</para>
<programlisting role="C">
GtkObject
+GtkData
| | | +GtkCombo
| | | `GtkStatusbar
| | `GtkVBox
- | | +GtkColorSelection
- | | `GtkGammaCurve
+ | | `GtkColorSelection
| +GtkButton
| | +GtkOptionMenu
| | `GtkToggleButton
| +GtkToolbar
| `GtkTree
+GtkDrawingArea
- | `GtkCurve
+GtkEditable
| +GtkEntry
| | `GtkSpinButton
+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>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>Is GTK+ thread safe? How do I write multi-threaded GTK+
+applications? <emphasis>[GTK 2.x]</emphasis></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>In order to make GDK thread aware, you also need to
+call gdk_threads_init() in conjunction with the above call.
+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 throughout your code.</para>
+
+<para>A minimal main program for a threaded GTK+ application
+looks like:</para>
<programlisting role="C">
int
{
GtkWidget *window;
+ /* init threads */
g_thread_init(NULL);
+ gdk_threads_init();
+
+ /* init gtk */
gtk_init(&argc, &argv);
window = create_window();
gtk_main();
gdk_threads_leave();
- return(0);
+ 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>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>
+<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
+ * Version: 1.99.1
* Copyright: Copyright (C) 1999, Erik Mouw
* Author: Erik Mouw <J.A.K.Mouw@its.tudelft.nl>
- * Description: GTK threads example.
+ * Description: GTK threads example.
* Created at: Sun Oct 17 21:27:09 1999
- * Modified by: Erik Mouw <J.A.K.Mouw@its.tudelft.nl>
- * Modified at: Sun Oct 24 17:21:41 1999
+ * Modified by: Owen Taylor <otaylor@gtk.org>
+ * Modified at: Wed May 28 10:43:00 2003
*-----------------------------------------------------------------------*/
/*
* Compile with:
*
- * cc -o gtk-thread gtk-thread.c `gtk-config --cflags --libs gthread`
+ * cc -o gtk-thread gtk-thread.c `pkg-config --cflags --libs gtk+-2.0 gthread-2.0`
*
- * Thanks to Sebastian Wilhelmi and Owen Taylor for pointing out some
- * bugs.
+ * Thanks to Sebastian Wilhelmi for pointing out some bugs in earlier versions.
*
*/
-#include <stdio.h>
-#include <stdlib.h>
#include <unistd.h>
-#include <time.h>
#include <gtk/gtk.h>
-#include <glib.h>
-#include <pthread.h>
#define YES_IT_IS (1)
#define NO_IT_IS_NOT (0)
-typedef struct
+typedef struct
{
GtkWidget *label;
int what;
for(;;)
{
/* sleep a while */
- sleep(rand() / (RAND_MAX / 3) + 1);
+ sleep(g_random_int_range (1, 4));
/* lock the yes_or_no_variable */
G_LOCK(yes_or_no);
else
gtk_label_set_text(GTK_LABEL(data->label), "O no, it isn't!");
+ /* Make sure all X commands are sent to the X server; not strictly
+ * necessary here, but always a good idea when you do anything
+ * from a thread other than the one where the main loop is running.
+ */
+ gdk_flush ();
+
/* release GTK thread lock */
gdk_threads_leave();
}
}
- return(NULL);
+ return NULL;
}
int main(int argc, char *argv[])
{
GtkWidget *window;
GtkWidget *label;
+ GError *error = NULL;
yes_or_no_args yes_args, no_args;
- pthread_t no_tid, yes_tid;
/* init threads */
g_thread_init(NULL);
+ gdk_threads_init();
/* init gtk */
gtk_init(&argc, &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);
+ g_signal_connect(window, "destroy",
+ G_CALLBACK(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(&yes_tid, NULL, argument_thread, &yes_args);
+ if (!g_thread_create(argument_thread, &yes_args, FALSE, &error))
+ {
+ g_printerr ("Failed to create YES thread: %s\n", error->message);
+ return 1;
+ }
no_args.label = label;
no_args.what = NO_IT_IS_NOT;
- pthread_create(&no_tid, NULL, argument_thread, &no_args);
+ if (!g_thread_create(argument_thread, &no_args, FALSE, &error))
+ {
+ g_printerr ("Failed to create NO thread: %s\n", error->message);
+ return 1;
+ }
/* enter the GTK main loop */
gdk_threads_enter();
gtk_main();
gdk_threads_leave();
- return(0);
+ return 0;
}
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>Why does this strange 'x io error' occur when I
- <literal>fork()</literal> in my GTK+ app?</title>
+<sect1>
+<title>I'm doing some stuff with GTK+ in a separate thread, and
+properly locking with gdk_threads_enter/gdk_threads_leave()
+but the display doesn't update properly. <emphasis>[GTK 2.x]</emphasis>
+</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>For efficiency, the X window system batches up commands
+and sends them to the X server in batches instead of sending
+out immediately.</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>In a non-multithreaded program, you don't have to worry about
+this, since the first thing that happens when control returns
+to the main loop is that any outstanding X requests are
+sent to the X server.</para>
- <para>The right function to use here is
- <literal>_exit()</literal>.</para>
+<para>However, if you are making GTK+ calls from a thread other
+than the main loop, then GTK+ doesn't know when to send batched
+commands out. For that reason, after making GTK+ calls
+in a separate thread, it is usually a good idea to call
+gdk_flush() before gdk_thread_leave().</para>
- <para>Erik Mouw contributed the following code example to
- illustrate handling fork() and exit().</para>
+<para>Actually, gdk_flush() is more expensive than is necessary here,
+since it waits for the X server to finish outstanding commands
+as well; if performance is an issue, you may want to call
+XFlush() directly:</para>
+
+<programlisting role="C">
+
+#include <gdk/gdkx.h>
+
+void my_flush_commands (void)
+{
+ GdkDisplay *display = gdk_display_get_default ();
+ XFlush (GDK_DISPLAY_XDISPLAY (display);
+}
+</programlisting>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>What's an easy way to run a function in the thread with
+the main loop? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>Sometimes the simplest way to set up a threaded program
+is to make all the GTK+ calls in a single thread. In such
+a program, you should still call g_threads_init(), but
+don't need to call gdk_threads_init(), gkd_threads_enter(),
+and gdk_threads_leave().</para>
+
+<para>If you set your program up this way, how then do you get
+the thread making GTK+ calls and running the main loop
+to do something in response to another thread?</para>
+
+<para>An easy way to do it is to take advantage of the fact that
+the GLib main loop functions are all thread safe, and can
+be called from any thread by adding an idle function
+with g_idle_add(). The function provided will be called
+at the next opportunity by the main thread. If you want
+your function to take priority over event handling and
+drawing, you can instead use g_idle_add_full() and pass
+in a priority of G_PRIORITY_HIGH.</para>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>Why does this strange 'x io error' occur when I
+<literal>fork()</literal> in my GTK+ app? <emphasis>[GTK 2.x]</emphasis></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
+ * Version: 0.99.2
* Copyright: Copyright (C) 1999, Erik Mouw
* Author: Erik Mouw <J.A.K.Mouw@its.tudelft.nl>
* Description: GTK+ fork example
* Created at: Thu Sep 23 21:37:55 1999
* Modified by: Erik Mouw <J.A.K.Mouw@its.tudelft.nl>
* Modified at: Thu Sep 23 22:39:39 1999
+ * Modified by: Tony Gale <gale@gtk.org>
+ * Modified at: Wed Jan 14 12:38:00 2004
*-----------------------------------------------------------------------*/
/*
* Compile with:
*
- * cc -o gtk-fork gtk-fork.c `gtk-config --cflags --libs`
+ * cc -o gtk-fork gtk-fork.c `pkg-config gtk+-2.0 --cflags --libs`
*
*/
sigprocmask(SIG_BLOCK, &set, &oldset);
/* wait for child */
- while((pid = waitpid((pid_t)-1, &status, WNOHANG)) > 0)
+ while((pid = waitpid((pid_t)-1, &status, WNOHANG)) > 0)
{
if(WIFEXITED(status))
{
*/
window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
- gtk_signal_connect(GTK_OBJECT (window), "delete_event",
- GTK_SIGNAL_FUNC(delete_event), NULL);
+ g_signal_connect(G_OBJECT (window), "delete_event",
+ G_CALLBACK(delete_event), NULL);
- gtk_signal_connect(GTK_OBJECT (window), "destroy",
- GTK_SIGNAL_FUNC(destroy), NULL);
+ g_signal_connect(G_OBJECT (window), "destroy",
+ G_CALLBACK(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 */
+ /* add a button to do something useful */
button = gtk_button_new_with_label("Fork me!");
- gtk_signal_connect(GTK_OBJECT (button), "clicked",
- GTK_SIGNAL_FUNC(fork_me), NULL);
+ g_signal_connect(G_OBJECT (button), "clicked",
+ G_CALLBACK(fork_me), NULL);
gtk_container_add(GTK_CONTAINER(window), button);
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>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<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... <emphasis>[GTK 2.x]</emphasis></title>
- <sect2>
- <title>How do I identifiy a widgets top level window or other
- ancestor?</title>
+<para>From: Peter Mattis</para>
- <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><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.</quote></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>
+<para><quote>On a more practical note, I did implement this at one point
+and determined it didn't look good and removed it.</quote></para>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>How do I identifiy a widgets top level window or other
+ancestor? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>There are a couple of ways to find the top level parent
+of a widget. The easiest way is to call the
+<literal>gtk_widget_get_toplevel()</literal> function that
+returns a 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>
+<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>You can also follow the a widgets ancestry by using the function
+<literal>gtk_widget_get_parent()</literal> that returns a pointer
+to a widgets parent widget.</para>
- <para>The actual Gdk/X window will be created when the widget
- gets realized. You can get the Window ID with:</para>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>How do I get the Window ID of a GtkWindow? <emphasis>[GTK 2.x]</emphasis></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 <gdk/gdkx.h>
Window xwin = GDK_WINDOW_XWINDOW (GTK_WIDGET (my_window)->window);
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>How do I catch a double click event (in a list widget,
- for example)?</title>
+<sect1>
+<title>How do I catch a double click event? <emphasis>[GTK 2.x]</emphasis></title>
-
<para>Tim Janik wrote to gtk-list (slightly modified):</para>
+<para>Tim Janik wrote to gtk-list (slightly modified):</para>
-
<para>Define a signal handler:</para>
+<para>Define a signal handler:</para>
<programlisting role="C">
gint
-signal_handler_event(GtkWiget *widget, GdkEvenButton *event, gpointer func_data)
+signal_handler_event(GtkWidget *widget, GdkEventButton *event, gpointer func_data)
{
- if (GTK_IS_LIST_ITEM(widget) &&
+ if (GTK_IS_BUTTON(widget) &&
(event->type==GDK_2BUTTON_PRESS ||
event->type==GDK_3BUTTON_PRESS) ) {
- printf("I feel %s clicked on button %d\",
+ printf("I feel %s clicked with button %d\n",
event->type==GDK_2BUTTON_PRESS ? "double" : "triple",
event->button);
}
return FALSE;
}</programlisting>
-
<para>And connect the handler to your object:</para>
+<para>And connect the handler to your object:</para>
<programlisting role="C">
{
- /* list, list item init stuff */
+ /* button init stuff */
- gtk_signal_connect(GTK_OBJECT(list_item),
+ g_signal_connect(G_OBJECT(button),
"button_press_event",
- GTK_SIGNAL_FUNC(signal_handler_event),
+ G_CALLBACK(signal_handler_event),
NULL);
/* and/or */
- gtk_signal_connect(GTK_OBJECT(list_item),
+ g_signal_connect(G_OBJECT(button),
"button_release_event",
- GTK_SIGNAL_FUNC(signal_handler_event),
+ G_CALLBACK(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>
-
- <!-- ----------------------------------------------------------------- -->
+<para>and, Owen Taylor wrote:</para>
+
+<para><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>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<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>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>Data I pass to the <literal>delete_event</literal> (or other event)
- handler gets corrupted.</title>
+<sect1>
+<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>
+<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">
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>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<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>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>
+<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>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>
-
- <!-- ----------------------------------------------------------------- -->
+<para>All the event masks are defined in the
+<filename>gdktypes.h</filename> file.</para>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>I need to add a new signal to a GTK+ widget. Any
- idea?</title>
+<sect1>
+<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 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>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>g_signal_emit</literal> and can be
+handled in the same way as other signals.</para>
-
<para>Tim Janik posted this code snippet:</para>
+<para>Tim Janik posted this code snippet:</para>
<programlisting role="C">
static guint signal_user_action = 0;
{
g_return_if_fail (GTK_IS_WIDGET (widget));
- gtk_signal_emit (GTK_OBJECT (widget), signal_user_action, act_data);
+ g_signal_emit (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>
+<para>If you want your new signal to have more than the
+classical gpointer parameter, you'll have to play with GTK+
+marshallers.</para>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<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_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>
-
- <!-- ----------------------------------------------------------------- -->
+<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>
+</sect1>
- <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>
-
- <!-- ----------------------------------------------------------------- -->
+<sect1>
+<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>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>Why doesn't my widget (e.g. progressbar)
- update?</title>
+<sect1>
+<title>Why doesn't my widget (e.g. progressbar)
+update? <emphasis>[GTK 2.x]</emphasis></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>
+<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());
+while (g_main_context_iteration(NULL, FALSE));
</programlisting>
-
<para>inside you're function that changes the widget.</para>
+<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>
-
- <!-- ----------------------------------------------------------------- -->
+<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>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>How do I attach data to some GTK+ object/widget?</title>
+<sect1>
+<title>How do I attach data to some GTK+ object/widget?
+<emphasis>[GTK 2.x]</emphasis></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>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>
+<para>There are two (easy) ways to attach some data to a gtk
+object. Using <literal>g_object_set_data()</literal> and
+<literal>g_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);
+void g_object_set_data(GObject *object, const gchar *key, gpointer data);
-gpointer gtk_object_get_data(GtkObject *object, const gchar *key);
+gpointer g_object_get_data(GObject *object, const gchar *key);
</programlisting>
-
<para>Since a short example is better than any lengthy speech:</para>
+<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)&p1);
-gtk_object_set_data(GTK_OBJECT(w),"p2 data",(gpointer)&p2);
+g_object_set_data(G_OBJECT(w),"p1 data",(gpointer)&p1);
+g_object_set_data(G_OBJECT(w),"p2 data",(gpointer)&p2);
-result = gtk_object_get_data(GTK_OBJECT(w),"p1 data");
+result = g_object_get_data(G_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>
-
- <!-- ----------------------------------------------------------------- -->
+<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>
- <title>How do I reparent a widget?</title>
+</sect1>
- <para>The normal way to reparent (ie change the owner) of a
- widget should be to use the function:</para>
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<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>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<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>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>
+<para>To avoid this problem, simply use the following code
+snippet:</para>
<programlisting role="C">
- gtk_widget_ref(widget);
+ g_object_ref(widget);
gtk_container_remove(GTK_CONTAINER(old_parent), widget);
gtk_container_add(GTK_CONTAINER(new_parent), widget);
- gtk_widget_unref(widget);
+ g_object_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>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
- <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>
+<sect1>
+<title>How could I get any widgets position?</title>
- <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>
+<para>As Tim Janik pointed out, there are different cases, and
+each case requires a different solution.</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>
+<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>
- <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>
+<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>
-<programlisting role="C">
-allow_shrink = FALSE
-allow_grow = TRUE
-auto_shrink = FALSE
-</programlisting>
+<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>
- <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>
+<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>
-<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>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>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
- <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>
+<sect1>
+<title>How do I set the size of a widget/window? How do I
+prevent the user resizing my window? <emphasis>[GTK 2.x]</emphasis></title>
+
+<para>The <literal>gtk_widget_set_size_request()</literal> function
+is used to set the size of a widget to a specific size.
+
+The function
+<literal>gtk_window_set_resizable()</literal> function sets whether
+the user can resize a window, which they can by default. The
+definition of these functions are:</para>
<programlisting role="C">
- gdk_window_move_resize(window->window,
- x_pos, y_pos,
- x_size, y_size);
+void gtk_widget_set_size_request (GtkWidget *widget,
+ gint width,
+ gint height);
+
+void gtk_window_set_resizable (GtkWindow *window,
+ gboolean resizable);
+
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>How do I add a popup menu to my GTK+
- application?</title>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
- <para>The <literal>menu</literal> example in the examples/menu
- directory of the GTK+ distribution implements a popup menu
- with this technique:</para>
+<sect1>
+<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)
return FALSE;
}
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>How do I disable or enable a widget, such as a
- button?</title>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<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>
+<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>
+</sect1>
- <!-- ----------------------------------------------------------------- -->
+<!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>Shouldn't the text argument in the gtk_clist_*
- functions be declared const?</title>
+<sect1>
+<title>Shouldn't the text argument in the gtk_clist_*
+functions be declared const?</title>
-
<para>For example:</para>
+<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>
+<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>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<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>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<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";
NULL, gtk_widget_get_colormap(top),
&pixmap_mask, NULL, pixfile);
pixw = gtk_pixmap_new (pixmap, pixmap_mask);
- gdk_pixmap_unref (pixmap);
- gdk_pixmap_unref (pixmap_mask);
+ g_object_unref (pixmap);
+ g_object_unref (pixmap_mask);
</programlisting>
- </sect2>
- </sect1>
- <!-- ***************************************************************** -->
- <sect1>
- <title>Development with GTK+: widget specific questions</title>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>How do I do drag-and-drop?</title>
+
+<para>GTK+ has a high level set of functions for doing inter-process
+communication via the drag-and-drop system. GTK+ can perform
+drag-and-drop on top of the low level Xdnd and Motif drag-and-drop
+protocols.</para>
+
+<para>The documentation on GTK+ drag-and-drop isn't complete, but there
+is some information in the <ulink
+url="http://www.gtk.org/tutorial/">Tutorial</ulink>. You should also
+look at the drag-and-drop example code that is part of the GTK+ source
+distribution, in the file <filename>gtk/testdnd.c</filename>.</para>
+
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>Why does GTK+/GLib leak memory?</title>
+
+<para>It doesn't. Both GLib and the C library (malloc implementation)
+will cache allocated memory on occasion, even if you free it with
+free().</para>
+
+<para>So you can't generally use tools such as top to see if you are
+using free() properly (aside from the very roughest of estimations, i.e.
+if you are really, really screwing up top will show that, but you can't
+distinguish small mistakes from the GLib/malloc caches).</para>
+
+<para>In order to find memory leaks, use proper memory profiling
+tools.</para>
+
+</sect1>
+
+</chapter>
- <sect2>
- <title>How do I find out about the selection of a GtkList?</title>
+<!-- ***************************************************************** -->
+<chapter>
+<title>Development with GTK+: widget specific questions</title>
- <para>Get the selection something like this:</para>
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<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>
+<para>This is how GList is defined (quoting glist.h):</para>
<programlisting role="C">
typedef struct _GList GList;
};
</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>
+<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">
{
}
</programlisting>
-
<para>To get known about the selection:</para>
+<para>To get known about the selection:</para>
<programlisting role="C">
{
}
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
- <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>
+<sect1>
+<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;
gtk_container_add(GTK_CONTAINER(scrolled), clist);
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>I don't want the user of my applications to enter text
- into a GtkCombo. Any idea?</title>
+<sect1>
+<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>
+<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>
+<para>If you don't want the user to be able to modify the
+content of this entry, you can use the
+gtk_editable_set_editable() function:</para>
<programlisting role="C">
- void gtk_entry_set_editable(GtkEntry *entry,
- gboolean editable);
+void gtk_editable_set_editable (GtkEditable *editable,
+ gboolean is_editable);
</programlisting>
- <para>Set the editable parameter to FALSE to disable typing
- into the entry.</para>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
+<para>Set the is_editable parameter to FALSE to disable typing
+into the entry.</para>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>How do I catch a combo box change?</title>
- <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>
- <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>
- <itemizedlist>
- <listitem><simpara>some text is typed in</simpara>
- </listitem>
- <listitem><simpara>the selection of the combo box is changed</simpara>
- </listitem>
- </itemizedlist>
+<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>
+<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);
+ g_signal_connect(GTK_COMBO(cb)->entry,
+ "changed",
+ G_CALLBACK(my_cb_change_handler),
+ NULL);
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>How can I define a separation line in a menu?</title>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
- <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>
+<sect1>
+<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_menu_shell_append(GTK_MENU_SHELL(menu), menuitem);
gtk_widget_show(menuitem);
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>How can I right justify a menu, such as Help?</title>
+<sect1>
+<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>
+<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, "<MyApp>/Help");
gtk_menu_item_right_justify(menu_path->widget);
</programlisting>
-
<para>If you do not use the MenuFactory, you should simply
- use:</para>
+<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>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>How do I add some underlined accelerators to menu
- items?</title>
+<sect1>
+<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>
+<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_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_label_set_use_underline (GTK_LABEL (gtk_bin_get_child (GTK_BIN (file1))),
+ TRUE);
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_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_label_set_use_underline (GTK_LABEL (gtk_bin_get_child (GTK_BIN (new1))),
+ TRUE);
gtk_widget_add_accelerator (new1, "activate_item", file1_menu_accels,
tmp_key, 0, 0);
gtk_object_set_data (GTK_OBJECT (window1), "new1", new1);
gtk_container_add (GTK_CONTAINER (file1_menu), new1);
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
- <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>
+<sect1>
+<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)
/* do stuff with child */
if (GTK_IS_LABEL (child))
{
- gchar *text;
+ const gchar *text;
- gtk_label_get (GTK_LABEL (child), &text);
+ text = gtk_label_get_text (GTK_LABEL (child));
g_print ("menu item text: %s\n", text);
}
}
</programlisting>
-
<para>To get the active menu item from a GtkOptionMenu you can
- do:</para>
+<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)
}
</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>
-
+<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)
/* do stuff with child */
}
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>How do I right (or otherwise) justify a
- GtkLabel?</title>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<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>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>
+<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 yalign);
</programlisting>
- <para>where the <literal>xalign</literal> and
- <literal>yalign</literal> values are floats in
- [0.00;1.00].</para>
-
+<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);
+gtk_misc_set_alignment(GTK_MISC(label), 0.0f, 0.0f);
/* horizontal : centered, vertical : centered */
-gtk_misc_set_alignment(GTK_MISK(label), 0.5f, 0.5f);
+gtk_misc_set_alignment(GTK_MISC(label), 0.5f, 0.5f);
/* horizontal : right align, vertical : bottom */
-gtk_misc_set_alignment(GTK_MISK(label), 1.0f, 1.0f);
+gtk_misc_set_alignment(GTK_MISC(label), 1.0f, 1.0f);
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>How do I set the background color of a GtkLabel
- widget?</title>
+</sect1>
- <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>
-
- <!-- ----------------------------------------------------------------- -->
+<sect1>
+<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>
+
+</sect1>
- <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>
+<sect1>
+<title>How do I set the color and font of a GtkLabel using a
+Resource File?</title>
- <para><literallayout>
- <literal>window (name: humphrey)</literal>
- <literal> hbox</literal>
- <literal> label (name: mylabel)</literal>
- </literallayout></para>
+<para>The widget name path constructed for a Label consists of
+the widget names of its object hierarchy as well, e.g.</para>
- <para>The widget path your pattern needs to match would be:
- <literal>humphrey.GtkHBox.mylabel</literal></para>
+<para><literallayout>
+<literal>window (name: humphrey)</literal>
+<literal> hbox</literal>
+<literal> label (name: mylabel)</literal>
+</literallayout></para>
- <para>The resource file may look something like:</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"
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>
+<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_show(label);
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>How do I configure Tooltips in a Resource File?</title>
+<sect1>
+<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>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>
+<para>So, your resource file should look something like:</para>
<programlisting role="C">
style "postie"
widget "gtk-tooltips*" style "postie"
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>I can't add more than (something like) 2000 chars in a
- GtkEntry. What's wrong?</title>
+<sect1>
+<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>
+<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
max_length = MIN (2047, entry->text_max_length);
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>How do I make a GtkEntry widget activate on pressing
- the Return key?</title>
+<sect1>
+<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>
+<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);
+ g_signal_connect (entry, "activate",
+ G_CALLBACK(entry_callback),
+ NULL);
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
- <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>
+<sect1>
+<title>How do I validate/limit/filter the input to a GtkEntry? <emphasis>[GTK 2.x]</emphasis></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 <ctype.h>
}
if (count > 0) {
- gtk_signal_handler_block_by_func (GTK_OBJECT (editable),
- GTK_SIGNAL_FUNC (insert_text_handler),
- data);
+ g_signal_handlers_block_by_func (G_OBJECT (editable),
+ G_CALLBACK (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);
+ g_signal_handlers_unblock_by_func (G_OBJECT (editable),
+ G_CALLBACK (insert_text_handler),
+ data);
}
- gtk_signal_emit_stop_by_name (GTK_OBJECT (editable), "insert_text");
-
+ g_signal_stop_emission_by_name (G_OBJECT (editable), "insert_text");
+
g_free (result);
}
/* 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);
-
+ g_signal_connect (G_OBJECT (window), "destroy",
+ G_CALLBACK (gtk_main_quit),
+ NULL);
+
entry = gtk_entry_new();
- gtk_signal_connect(GTK_OBJECT(entry), "insert_text",
- GTK_SIGNAL_FUNC(insert_text_handler),
+ g_signal_connect(G_OBJECT(entry), "insert_text",
+ G_CALLBACK(insert_text_handler),
NULL);
gtk_container_add(GTK_CONTAINER (window), entry);
gtk_widget_show(entry);
}
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
- <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>
+<sect1>
+<title>How do I use horizontal scrollbars with a GtkText widget?</title>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
+<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>
+
+</sect1>
- <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>
+<sect1>
+<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"
}
</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>
+<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>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
- <sect2>
- <title>How do I set the cursor position in a GtkText
- object?</title>
+<sect1>
+<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>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>
+<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>
+<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
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);
+ g_signal_connect_after (text, "button_press_event",
+ G_CALLBACK (insert_bar), NULL);
gtk_widget_show_all(window);
gtk_main();
}
</programlisting>
-
<para>Now, if you really want to change the cursor position,
- you should use the
- <literal>gtk_editable_set_position()</literal>
- function.</para>
+<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>
- </sect1>
+</chapter>
- <!-- ***************************************************************** -->
- <sect1>
- <title>About GDK</title>
-
- <!-- ----------------------------------------------------------------- -->
+<!-- ***************************************************************** -->
+<chapter>
+<title>About GDK</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>
+<sect1>
+<title>What is GDK?</title>
- <!-- Examples, anybody? I've been mulling some over. NF -->
+<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>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
+<!-- Examples, anybody? I've been mulling some over. NF -->
+
+</sect1>
- <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>
+<sect1>
+<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">
{
}
</programlisting>
- </sect2>
- </sect1>
- <!-- ***************************************************************** -->
- <sect1>
- <title>About GLib</title>
-
- <!-- ----------------------------------------------------------------- -->
-
- <sect2>
- <title>What is GLib?</title>
-
- <para>GLib is a library of useful functions and definitions
- available for use when creating GDK and GTK applications. It
- provides replacements for some standard libc functions, such
- as malloc, which are buggy on some systems.</para>
-
- <para>It also provides routines for handling:</para>
-
- <itemizedlist>
- <listitem><simpara>Doubly Linked Lists</simpara>
- </listitem>
- <listitem><simpara>Singly Linked Lists</simpara>
- </listitem>
- <listitem><simpara>Timers</simpara>
- </listitem>
- <listitem><simpara>String Handling</simpara>
- </listitem>
- <listitem><simpara>A Lexical Scanner</simpara>
- </listitem>
- <listitem><simpara>Error Functions</simpara>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
+
+</chapter>
+
+<!-- ***************************************************************** -->
+<chapter>
+<title>About GLib</title>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>What is GLib?</title>
+
+<para>GLib is a library of useful functions and definitions
+available for use when creating GDK and GTK applications. It
+provides replacements for some standard libc functions, such
+as malloc, which are buggy on some systems.</para>
+
+<para>It also provides routines for handling:</para>
+
+<itemizedlist spacing=compact>
+<listitem><simpara>Doubly Linked Lists</simpara>
+</listitem>
+
+<listitem><simpara>Singly Linked Lists</simpara>
+</listitem>
+
+<listitem><simpara>Timers</simpara>
+</listitem>
+
+<listitem><simpara>String Handling</simpara>
+</listitem>
+
+<listitem><simpara>A Lexical Scanner</simpara>
+</listitem>
+
+<listitem><simpara>Error Functions</simpara>
+</listitem>
+</itemizedlist>
+
+</sect1>
- <sect2>
- <title>How can I use the doubly linked lists?</title>
+<!-- ----------------------------------------------------------------- -->
- <para>The GList object is defined as:</para>
+<sect1>
+<title>How can I use the doubly linked lists?</title>
+
+<para>The GList object is defined as:</para>
<programlisting role="C">
typedef struct _GList GList;
};
</programlisting>
-
<para>To use the GList objects, simply:</para>
+<para>To use the GList objects, simply:</para>
<programlisting role="C">
GList *list = NULL;
list = g_list_remove(list, &array[4]);
</programlisting>
-
<para>The same code is usable with singly linked lists (GSList
- objects) by replacing g_list_* functions with the relevant
- g_slist_* ones (g_slist_append, g_slist_remove, ...). Just
- remember that since you can't go backward in a singly linked
- list, there is no g_slist_first function - you'll need to keep
- a reference on the first node of the list.</para>
+<para>The same code is usable with singly linked lists (GSList
+objects) by replacing g_list_* functions with the relevant
+g_slist_* ones (g_slist_append, g_slist_remove, ...). Just
+remember that since you can't go backward in a singly linked
+list, there is no g_slist_first function - you'll need to keep
+a reference on the first node of the list.</para>
- <!-- Some Examples might be useful here! NF -->
- <!-- I believe it should be better :) ED -->
- <!-- Linked lists are pretty standard data structures - don't want to
- over do it - TRG -->
+<!-- Some Examples might be useful here! NF -->
+<!-- I believe it should be better :) ED -->
+<!-- Linked lists are pretty standard data structures - don't want to
+over do it - TRG -->
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
-
- <sect2>
- <title>Memory does not seem to be released when I free the
- list nodes I've allocated</title>
-
-
<para>GLib tries to be "intelligent" on this special issue: it
- assumes that you are likely to reuse the objects, so caches
- the allocated memory. If you do not want to use this behavior,
- you'll probably want to set up a special allocator.</para>
-
-
<para>To quote Tim Janik:</para>
-
<para><quote>If you have a certain portion of code that uses *lots*
- of GLists or GNodes, and you know you'd better want to release
- all of them after a short while, you'd want to use a
- GAllocator. Pushing an allocator into g_list will make all
- subsequent glist operations private to that allocator's memory
- pool (and thus you have to take care to pop the allocator
- again, before making any external calls): </quote></para>
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>Memory does not seem to be released when I free the
+list nodes I've allocated</title>
+
+<para>GLib tries to be "intelligent" on this special issue: it
+assumes that you are likely to reuse the objects, so caches
+the allocated memory. If you do not want to use this behavior,
+you'll probably want to set up a special allocator.</para>
+
+<para>To quote Tim Janik:</para>
+<para><quote>If you have a certain portion of code that uses *lots*
+of GLists or GNodes, and you know you'd better want to release
+all of them after a short while, you'd want to use a
+GAllocator. Pushing an allocator into g_list will make all
+subsequent glist operations private to that allocator's memory
+pool (and thus you have to take care to pop the allocator
+again, before making any external calls): </quote></para>
<programlisting role="C">
GAllocator *allocator;
g_allocator_free (allocator);
</programlisting>
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
-
- <sect2>
- <title>Why use g_print, g_malloc, g_strdup and fellow glib
- functions?</title>
-
- <para>Thanks to Tim Janik who wrote to gtk-list: (slightly
- modified)</para>
-
- <para><quote>Regarding g_malloc(), g_free() and siblings, these
- functions are much safer than their libc equivalents. For
- example, g_free() just returns if called with NULL. Also, if
- USE_DMALLOC is defined, the definition for these functions
- changes (in glib.h) to use MALLOC(), FREE() etc... If
- MEM_PROFILE or MEM_CHECK are defined, there are even small
- statistics made counting the used block sizes (shown by
- g_mem_profile() / g_mem_check()).</quote></para>
-
- <para><quote>Considering the fact that glib provides an interface for
- memory chunks to save space if you have lots of blocks that
- are always the same size and to mark them ALLOC_ONLY if
- needed, it is just straight forward to create a small saver
- (debug able) wrapper around the normal malloc/free stuff as
- well - just like gdk covers Xlib. ;)</quote></para>
-
- <para><quote>Using g_error() and g_warning() inside of applications
- like the GIMP that fully rely on gtk even gives the
- opportunity to pop up a window showing the messages inside of
- a gtk window with your own handler (by using
- g_set_error_handler()) along the lines of
- <literal>gtk_print()</literal> (inside of
- gtkmain.c).</quote></para>
-
- </sect2>
-
- <!-- ----------------------------------------------------------------- -->
+</sect1>
+
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>Why use g_print, g_malloc, g_strdup and fellow glib
+functions?</title>
+
+<para>Thanks to Tim Janik who wrote to gtk-list: (slightly
+modified)</para>
- <sect2>
- <title>What's a GScanner and how do I use one?</title>
+<para><quote>Regarding g_malloc(), g_free() and siblings, these
+functions are much safer than their libc equivalents. For
+example, g_free() just returns if called with NULL. Also, if
+USE_DMALLOC is defined, the definition for these functions
+changes (in glib.h) to use MALLOC(), FREE() etc... If
+MEM_PROFILE or MEM_CHECK are defined, there are even small
+statistics made counting the used block sizes (shown by
+g_mem_profile() / g_mem_check()).</quote></para>
- <para>A GScanner will tokenize your text, that is, it'll return
- an integer for every word or number that appears in its input
- stream, following certain (customizable) rules to perform this
- translation. You still need to write the parsing functions on
- your own though.</para>
+<para><quote>Considering the fact that glib provides an interface for
+memory chunks to save space if you have lots of blocks that
+are always the same size and to mark them ALLOC_ONLY if
+needed, it is just straight forward to create a small saver
+(debug able) wrapper around the normal malloc/free stuff as
+well - just like gdk covers Xlib. ;)</quote></para>
- <para>Here's a little test program supplied by Tim Janik that
- will parse</para>
+<para><quote>Using g_error() and g_warning() inside of applications
+like the GIMP that fully rely on gtk even gives the
+opportunity to pop up a window showing the messages inside of
+a gtk window with your own handler (by using
+g_set_error_handler()) along the lines of
+<literal>gtk_print()</literal> (inside of
+gtkmain.c).</quote></para>
- <para><literallayout>
- <literal><SYMBOL> = <OPTIONAL-MINUS> <NUMBER> ;</literal>
- </literallayout></para>
+</sect1>
- <para>constructs, while skipping "#\n" and "/**/" style
- comments.</para>
+<!-- ----------------------------------------------------------------- -->
+
+<sect1>
+<title>What's a GScanner and how do I use one?</title>
+
+<para>A GScanner will tokenize your text, that is, it'll return
+an integer for every word or number that appears in its input
+stream, following certain (customizable) rules to perform this
+translation. You still need to write the parsing functions on
+your own though.</para>
+
+<para>Here's a little test program supplied by Tim Janik that
+will parse</para>
+
+<para><literallayout>
+<literal><SYMBOL> = <OPTIONAL-MINUS> <NUMBER> ;</literal>
+</literallayout></para>
+
+<para>constructs, while skipping "#\n" and "/**/" style
+comments.</para>
<programlisting role="C">
#include <glib.h>
}
</programlisting>
-
<para>You need to understand that the scanner will parse its
- input and tokenize it, it is up to you to interpret these
- tokens, not define their types before they get parsed,
- e.g. watch gscanner parse a string:</para>
+<para>You need to understand that the scanner will parse its
+input and tokenize it, it is up to you to interpret these
+tokens, not define their types before they get parsed,
+e.g. watch gscanner parse a string:</para>
- <literal>"hi i am 17"</literal>
- <literal> | | | |</literal>
- <literal> | | | v</literal>
- <literal> | | v TOKEN_INT, value: 17</literal>
- <literal> | v TOKEN_IDENTIFIER, value: "am"</literal>
- <literal> v TOKEN_CHAR, value: 'i'</literal>
- <literal>TOKEN_IDENTIFIER, value: "hi"</literal>
- </literallayout></para>
+<para><literallayout>
+<literal>"hi i am 17"</literal>
+<literal> | | | |</literal>
+<literal> | | | v</literal>
+<literal> | | v TOKEN_INT, value: 17</literal>
+<literal> | v TOKEN_IDENTIFIER, value: "am"</literal>
+<literal> v TOKEN_CHAR, value: 'i'</literal>
+<literal>TOKEN_IDENTIFIER, value: "hi"</literal>
+</literallayout></para>
-
<para>If you configure the scanner with:</para>
+<para>If you configure the scanner with:</para>
<programlisting role="C">
scanner->config->int_2_float = TRUE;
scanner->config->scan_symbols = TRUE;
</programlisting>
-
<para>and add "am" as a symbol with</para>
+<para>and add "am" as a symbol with</para>
<programlisting role="C">
g_scanner_add_symbol (scanner, "am", "symbol value");
</programlisting>
-
<para>GScanner will parse it as</para>
-
- <literal>"hi i am 17"</literal>
- <literal> | | | |</literal>
- <literal> | | | v</literal>
- <literal> | | v TOKEN_FLOAT, value: 17.0 (automatic int->float conversion)</literal>
- <literal> | | TOKEN_SYMBOL, value: "symbol value" (a successfull hash table lookup</literal>
- <literal> | | turned a TOKEN_IDENTIFIER into a</literal>
- <literal> | | TOKEN_SYMBOL and took over the</literal>
- <literal> | v symbol's value)</literal>
- <literal> v 'i' ('i' can be a valid token as well, as all chars >0 and <256)</literal>
- <literal>TOKEN_IDENTIFIER, value: "hi"</literal>
- </literallayout></para>
-
-
<para>You need to match the token sequence with your code, and
- if you encounter something that you don't want, you error
- out:</para>
+<para>GScanner will parse it as</para>
+
+<para><literallayout>
+<literal>"hi i am 17"</literal>
+<literal> | | | |</literal>
+<literal> | | | v</literal>
+<literal> | | v TOKEN_FLOAT, value: 17.0 (automatic int->float conversion)</literal>
+<literal> | | TOKEN_SYMBOL, value: "symbol value" (a successfull hash table lookup</literal>
+<literal> | | turned a TOKEN_IDENTIFIER into a</literal>
+<literal> | | TOKEN_SYMBOL and took over the</literal>
+<literal> | v symbol's value)</literal>
+<literal> v 'i' ('i' can be a valid token as well, as all chars >0 and <256)</literal>
+<literal>TOKEN_IDENTIFIER, value: "hi"</literal>
+</literallayout></para>
+
+<para>You need to match the token sequence with your code, and
+if you encounter something that you don't want, you error
+out:</para>
<programlisting role="C">
/* expect an identifier ("hi") */
return G_TOKEN_FLOAT;
</programlisting>
- <para>If you got past here, you have parsed "hi i am 17" and
- would have accepted "dooh i am 42" and "bah i am 0.75" as
- well, but you would have not accepted "hi 7 am 17" or "hi i hi
- 17".</para>
+<para>If you got past here, you have parsed "hi i am 17" and
+would have accepted "dooh i am 42" and "bah i am 0.75" as
+well, but you would have not accepted "hi 7 am 17" or "hi i hi
+17".</para>
+
+</sect1>
+
+</chapter>
- </sect2>
- </sect1>
- <!-- ***************************************************************** -->
- <sect1>
- <title>GTK+ FAQ Contributions, Maintainers and Copyright</title>
+<!-- ***************************************************************** -->
+
+<chapter>
+<title>GTK+ FAQ Contributions, Maintainers and Copyright</title>
<para>If you would like to make a contribution to the FAQ, send either one
of us an e-mail message with the exact text you think should be
included (question and answer). With your help, this document can grow
and become more useful!</para>
-<para>This document is maintained by
-Tony Gale <ulink
- url="mailto:gale@gtk.org"><gale@gtk.org></ulink>
+<para>This document is maintained by
+Tony Gale
+<ulink url="mailto:gale@gtk.org"><gale@gtk.org></ulink>
-Nathan Froyd <ulink url="mailto:maestrox@geocities.com">
-<maestrox@geocities.com></ulink>,
-and
-Emmanuel Deloget <ulink url="mailto:logout@free.fr">
-<logout@free.fr></ulink>.
This FAQ was created by Shawn T. Amundson
<ulink url="mailto:amundson@gimp.org">
-<amundson@gimp.org></ulink> who continues to provide support.
+<amundson@gimp.org></ulink>.
Contributions should be sent to Tony Gale <ulink
url="mailto:gale@gtk.org"><gale@gtk.org></ulink></para>
-<para>The GTK+ FAQ is Copyright (C) 1997-2000 by Shawn T. Amundson,
-Tony Gale, Emmanuel Deloget and Nathan Froyd.</para>
+<para>The GTK+ FAQ is Copyright (C) 1997-2003 by Shawn T. Amundson,
+Tony Gale.</para>
<para>Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
authors and maintainers of the information provided within can not
make any guarentee that the information is even accurate.</para>
- </sect1>
-
- </chapter>
+</chapter>
- <!-- ----------------------------------------------------------------- -->
+<!-- ----------------------------------------------------------------- -->
</book>
projects / ~andy / gtk / blobdiff