add question on multi-threading, minor URL cleanups.

[~andy/gtk] / docs / faq / gtkfaq.sgml

<!doctype linuxdoc system>

<article>

<!-- Title information -->

<title>GTK+ FAQ

<!-- NOTE: Use only one author tag, otherwise sgml2txt barfs - TRG --> 
<author>Nathan Froyd, Tony Gale, Shawn T. Amundson.
<date>May 11th 1998
<abstract>
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+.  
</abstract>

<!-- Table of contents -->
<toc>

<!-- Begin the document -->

<!-- ***************************************************************** -->
<sect>General Information

<!-- ----------------------------------------------------------------- -->
<sect1>Authors
<p>
The authors of GTK+ are:

<itemize>
<item>Peter Mattis    (petm@xcf.berkeley.edu)
<item>Spencer Kimball (spencer@xcf.berkeley.edu)
<item>Josh MacDonald  (jmacd@xcf.berkeley.edu)
</itemize>
GTK+ is distributed under the GNU Library General Public License

<!-- ----------------------------------------------------------------- -->
<sect1>What is GTK+?
<p>
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.

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. 

<!-- ----------------------------------------------------------------- -->
<sect1>What is the + in GTK+?
<P>
Peter Mattis informed the gtk mailing list that:
<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>

<!-- ----------------------------------------------------------------- -->
<sect1>Does the G in GTK+ stand for General, Gimp, or GNU?
<p>
Peter Mattis informed the gtk mailing list that:
<quote>
"I think the last time Spencer and I talked about it we decided on 
GTK = Gimp ToolKit. But I don't know for sure. Its definately not
GNU, though."
</quote>

<!-- ----------------------------------------------------------------- -->
<sect1>Where is the documentation for GTK+?
<p>
In the GTK+ distribution's doc/ directory you will find the
reference material for both GTK and GDK, this FAQ and the
GTK Tutorial.

In addition, you can find links to HTML versions of these documents 
by going to 
<htmlurl url="http://www.gtk.org/" 
name="http://www.gtk.org/">.

The Tutorial and FAQ can also be found at
<htmlurl url="http://www.geocities.com/ResearchTriangle/Lab/4299/"
name="http://www.geocities.com/ResearchTriangle/Lab/4299/">.

<!-- ----------------------------------------------------------------- -->
<sect1>Is there a mailing list (or mailing list archive) for GTK+?
<p>
There are two mailing lists:
<itemize>
<item>A mailing list for discussion of development of GTK based applications
is hosted at gtk-app-devel-list@redhat.com. To subscribe send an
email message to <htmlurl url="mailto:gtk-app-devel-list-request@redhat.com"
name="gtk-app-devel-list-request@redhat.com">
with <em>subscribe</em> in the <bf>subject</bf>.
<p>
<item>A mailing list for discussion of development of GTK is hosted 
at gtk-list@redhat.com. To subscribe send an
email message to <htmlurl url="mailto:gtk-list-request@redhat.com" 
name="gtk-list-request@redhat.com">
with <em>subscribe</em> in the <bf>subject</bf>.
<p>
A searchable archive of the mailing list can be found at <htmlurl url="http://archive.redhat.com/gtk-list" name="http://archive.redhat.com/gtk-list">
</itemize>
<!-- ----------------------------------------------------------------- -->
<sect1>The gtk-list hasn't had any traffic for days, is it dead?
<p>
No, everyone's just busy coding.

<!-- ----------------------------------------------------------------- -->
<sect1>How to get help with GTK+
<p>
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.

<!-- ----------------------------------------------------------------- -->
<sect1>How to report bugs in GTK+
<p>
Bug reports should be sent to the GTK+ mailing list.

<!-- ----------------------------------------------------------------- -->
<sect1>What applications have been written with GTK+?
<p>
Some applications which use GTK+ are:
<itemize>
<item>GIMP (<htmlurl url="http://www.XCF.Berkeley.EDU/~gimp/" 
                  name="http://www.XCF.Berkeley.EDU/~gimp/"> ), 
      an image manipulation program
<item>Gsumi (<htmlurl url="http://www.msc.cornell.edu/~otaylor/gsumi/gsumi.html" 
                  name="http://www.msc.cornell.edu/~otaylor/gsumi/gsumi.html">),
      a fun B+W doodling program with XInput support.
<item>GUBI (<htmlurl url="http://www.SoftHome.net/pub/users/timj/gubi/index.htm"
            name="http://www.SoftHome.net/pub/users/timj/gubi/index.htm">),
      a user interface builder
<item>Gzilla (<htmlurl url="http://www.levien.com/gzilla/" name="http://www.levien.com/gzilla/">),
      a web browser
<item>SANE (<htmlurl url="http://www.azstarnet.com/~axplinux/sane/" name="http://www.azstarnet.com/~axplinux/sane/"> ),
      a universal scanner interface
<item>XQF (<htmlurl url="http://www.botik.ru/~roma/quake/" name="http://www.botik.ru/~roma/quake/">),
      a QuakeWorld/Quake2 server browser and launcher
<item>ElectricEyes (<htmlurl url="http://www.labs.redhat.com/ee.shtml" name="http://www.labs.redhat.com/ee.shtml">),
      an image viewer that aims to be a free replacement for xv
<item>GPK - the General Proxy Kit (<htmlurl url="http://www.humanfactor.com/gpk/" name="http://www.humanfactor.com/gpk/">),
      an add-on library to permit thread-safe access to GTK+
<item>GCK - the General Convenience Kit (<htmlurl url="http://www.ii.uib.no/~tomb/gck.html" name="http://www.ii.uib.no/~tomb/gck.html">),
      miscellaneous functions intended to ease color handling, UI construction,
      vector operations, and math functions
<item>GDK Imlib (<htmlurl url="http://www.labs.redhat.com/imlib/" name="http://www.labs.redhat.com/imlib/">),
      a fast image loading and manipulation library for GDK      
</itemize>
<p>
In addition to the above, the GNOME project (<htmlurl url="http://www.gnome.org"
name="http://www.gnome.org">)
is using GTK+ to build a free desktop for Linux. Many more programs can be found
there.

<!-- ----------------------------------------------------------------- -->
<sect1>I'm looking for an application to write in GTK+. How about an IRC client?
<p> 

Ask on gtk-list for suggestions. There are at least four IRC
clients already under development.

<itemize>
<item>girc. (Included with GNOME)
<item>Bezerk (<htmlurl url="http://www.gtk.org/~trog/"
                       name="http://www.gtk.org/~trog/">)
<item>gsirc. (Location?)
<item>Gnirc. (<htmlurl url="http://www.imaginet.fr/~dramboz/gnirc"
                       name="http://www.imaginet.fr/~dramboz/gnirc">)
</itemize>


<!-- ***************************************************************** -->
<sect>How to find, configure, install, and troubleshoot GTK+

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

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

<!-- ----------------------------------------------------------------- -->
<sect1>Where can I get GTK+?
<p>
The canonical site is:
<verb>
ftp://ftp.gtk.org/pub/gtk
</verb>
Of course, any mirrors of ftp.gtk.org should have the latest version, too.

<sect1>How do I configure/compile GTK+?
<p>
Generally, all you will need to do is issue the commands:
<verb>
./configure
make
</verb>
in the gtk+-version/ directory.

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

<!-- ----------------------------------------------------------------- -->
 
<sect1>I've compiled and installed GTK+, but I can't get any programs to link with it!
<p>
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:
<itemize>
<item>Make sure that the libraries can be found. You want to edit 
/etc/ld.so.conf to include the directories which contain the GTK libraries,
 so it looks something like:
<verb>
/usr/X11R6/lib
/usr/local/lib
</verb>
Then you need to run /sbin/ldconfig as root. You can find what directory
GTK is in using
<verb>
gtk-config --libs
</verb>

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):
<verb>
export LD_LIBRARY_PATH=/usr/local/lib
</verb>
and in a csh, you can do:
<verb>
setenv LD_LIBRARY_PATH /usr/local/lib
</verb>

<item>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
<verb>
rpm -e gtk gtk-devel
</verb>
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 <verb>/usr/lib</verb> or <verb>/usr/local/lib</verb> contain any of
the libraries libgtk, libgdk, libglib, or libgck.  If they do exist, remove them
(and any gtk include files, such as /usr/include/gtk and /usr/include/gdk) 
and reinstall gtk+.
</itemize>

<!-- ----------------------------------------------------------------- -->
<sect1>When compiling programs with GTK+, I get compiler error messages about not being able to find <tt/"glibconfig.h"/.

<p> 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/.

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. 

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

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: 

<tscreen><verb>
CPPFLAGS="-I/usr/local/include/glib/include" ./configure
</verb></tscreen>

for Bourne-compatible shells like bash, or for csh variants:

<tscreen><verb>
setenv CPPFLAGS "-I/usr/local/include/glib/include" 
./configure
</verb></tscreen>

(Substitute the appropriate value of $exec_prefix for /usr/local.)

<!-- ----------------------------------------------------------------- -->
<sect1>When installing The GIMP, configure reports that it can't find GTK.
<p>
There are several common reasons for this:
<itemize>
<item>You have an old version of GTK installed somewhere. RedHat 5.0, for 
example, installs an older copy of GTK that will not work with the latest 
versions of GIMP. You should remove this old copy, but note that in the case
of RedHat 5.0 this will break the <tt/control-panel/ applications.
<P>
<item><tt/gtk-config/ (or another component of GTK) isn't in your path, or
there is an old version on your system. Type:
<verb>
gtk-config --version
</verb>
to check for both of these. This should return a value of at least 0.99.8
for things to work properly with GIMP 0.99.23. If it returns a value
different from what you expect, then you have an old version of GTK on
your system.
<P>
<item>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.
</itemize>
<p>
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.

<!-- ***************************************************************** -->
<sect>Development of GTK+
<!-- ***************************************************************** -->

<!-- ----------------------------------------------------------------- -->
<sect1>Whats this CVS thing that everyone keeps talking about, and how do I access it?
<p>
CVS is the Concurent Version System and is a very popular mean 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.

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.

The CVS toolset is available as RPM packages from the usual RedHat sites.
The latest version is available at 
<htmlurl url="http://download.cyclic.com/pub/" 
name="&lt;http://download.cyclic.com/pub/&gt;">

Anyone can download the latest CVS version of GTK+ by using anonymous access
using the following steps:
<itemize>
<item> In a bourne shell descendant (e.g. bash) type:
<verb>
export CVSROOT=':pserver:anonymous@cvs.gimp.org:/debian/home/gnomecvs'
</verb>
<item>Next, the first time the source tree is checked out, a cvs login 
is needed. 
<verb>
cvs login
</verb>
This will ask you for a password. There is no password for cvs.gimp.org, 
so just enter a carriage return. 
<item>To get the tree and place it in a subdir of your current working directory, issue the command: 
<verb>
cvs -z9 get gtk+
</verb>
</itemize>
<!-- ----------------------------------------------------------------- -->
<sect1>How can I contribute to GTK+?
<p>
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 <tt/diff -ru &lt;oldfile&gt; &lt;newfile&gt;/. 
Then upload the patchfile to:
<verb>
ftp://ftp.gtk.org/incoming
</verb>
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:
<verb>
gtk-<username>-<date yymmdd-n>.patch.gz
gtk-<username>-<date yymmdd-n>.patch.README
</verb>
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.

Example:
<verb>
gtk-gale-982701-0.patch.gz
gtk-gale-982701-0.patch.README
</verb>
Once you upload <em>anything</em>, send the README to ftp-admin@gtk.org

<!-- ----------------------------------------------------------------- -->
<sect1>How do I know if my patch got applied, and if not, why not?
<p>
Uploaded patches will be moved to <tt>ftp://ftp.gtk.org/pub/gtk/patches</tt>
where one of the GTK+ development team will pick them up. If applied, they
will be moved to <tt>/pub/gtk/patches/old</tt>.

Patches that aren't applied, for whatever reason, are moved to 
<tt>/pub/gtk/patches/unapplied</tt> or <tt>/pub/gtk/patches/outdated</tt>.
At this point you can ask on the <tt/gtk-list/ 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.

<!-- ----------------------------------------------------------------- -->
<sect1>What is the policy on incorporating new widgets into the library?
<p>
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.

<!-- ----------------------------------------------------------------- -->
<sect1>Is anyone working on bindings for languages other than C?
<p>
Yes. There is 
<itemize>
<item>a C++ wrapper for GTK+ called gtk--. You can find the home page at:
<htmlurl url="http://www.cs.tut.fi/~p150650/gtk/gtk--.html"
name="http://www.cs.tut.fi/~p150650/gtk/gtk--.html">. 
The FTP site is 
<htmlurl url="ftp://ftp.gtk.org/pub/gtk/gtk--"
name="ftp://ftp.gtk.org/pub/gtk/gtk--">.
<p>

<item>There are two Objective-c bindings currently in development:

 <itemize>

 <item>The <htmlurl url="http://www.gnome.org/" name="GNOME project's"> package
 of choice is obgtk. Objgtk is based on the Object class and is maintained by
 <htmlurl url="mailto:sopwith@cuc.edu" name="Elliot Lee">. Apparently, objgtk
 is being accepted as the `standard' Objective-C binding for GTK+.

 <item>If you are more inclined towards the 
 <htmlurl url="http://www.gnustep.org/" name="GNUstep project">,
 you may want to check out GTKKit by 
 <htmlurl url="mailto:helge@mdlink.de" name="Helge He&szlig;">.
 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.

 </itemize> 
<p>               
<item>Perl bindings
<htmlurl url="ftp://ftp.gtk.org/pub/gtk/perl"
name="ftp://ftp.gtk.org/pub/gtk/perl">
<P>
<item>Guile bindings. The home page is at
<htmlurl url="http://www.ping.de/sites/zagadka/guile-gtk"
name="http://www.ping.de/sites/zagadka/guile-gtk">.
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.
<p>

<item>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
<htmlurl url="http://www.ens-lyon.fr/~dmonniau/arcs"
name="http://www.ens-lyon.fr/~dmonniau/arcs">
</quote>

<item>
Several python bindings have been done:
<p>
<itemize>
<item>pygtk is at 
<htmlurl url="http://www.daa.com.au/~james/pygtk" 
name="http://www.daa.com.au/~james/pygtk"> and 
<htmlurl url="ftp://ftp.gtk.org/pub/gtk/python"
name="ftp://ftp.gtk.org/pub/gtk/python">
<item>python-gtk is at
<htmlurl url="http://www.ucalgary.ca/~nascheme/python-gtk" 
name="http://www.ucalgary.ca/~nascheme/python-gtk">
</itemize>
<p>
<item>
There's a OpenGL/Mesa widget available for GTK+. Grab it at
<htmlurl url="http://www.sakuranet.or.jp/~aozasa/shige/doc/comp/gtk/gtkGL/files-en.html" 
name="http://www.sakuranet.or.jp/~aozasa/shige/doc/comp/gtk/gtkGL/files-en.html">

</itemize>

<!-- ***************************************************************** -->
<sect>Development with GTK+
<!-- ***************************************************************** -->
<!-- ----------------------------------------------------------------- -->
<sect1>How do I get started?
<p>
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 <htmlurl url="http://www.gtk.org/tutorial/" 
name="&lt;http://www.gtk.org/tutorial/&gt;">, which is undergoing 
development. This will introduce you to writing applications using C.

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 exmaples will
give you a good grounding on what the widgets can do.

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

<!-- ----------------------------------------------------------------- -->
<sect1>Is GTK+ thread safe? How do I write multi-threaded GTK+ applications?
<p>
Although GTK+, like many X toolkits, isn't thread safe, this does
not prohibit the development of multi-threaded applications with
GTK+. 

Rob Browning (rlb@cs.utexas.edu) describes threading techniques for
use with GTK+ (slightly edited): 

There are basically two main approaches, the first is simple, and the
second complicated. In the first, you just make sure that all GTK+ (or
X) interactions are handled by one, and
only one, thread. Any other thread that wants to draw something has
to somehow notify the "GTK+" thread, and let it handle the
actual work. 

The second approach allows you to call GTK+ (or X) functions from any
thread, but it requires some careful synchronization. The
basic idea is that you create an X protection mutex, and no one may
make any X calls without first acquiring this mutex. 

Note that this is a little effort, but it allows you to be
potentially more efficient than a completely thread safe GTK+. You
get to decide the granularity of the thread locking. You also have to
make sure that the thread that calls gtk_main is holding the lock when
it calls gtk_main.

The next thing to worry about is that since you were holding the
global mutex when you entered gtk_main, all callbacks will also be
holding it. This means that the callback must release it if it's
going to call any other code that might reacquire it. Otherwise
you'll get deadlock. Also, you must be holding the mutex when you
finally return from the callback. 

In order to allow threads other than the one calling gtk_main to
get access to the mutex, we also need to register a work function
with GTK that allows us to release the mutex periodically.

Why can't GTK+ be thread safe by default?                           

Complexity, overhead, and manpower.  The proportion of threaded
programs is still reasonably small, and getting thread safety right is
both quite difficult and takes valuable time away from the main work
of getting a good graphics library finished.  It would be nice to have
GTK+ thread safe "out of the box", but that's not practical right now,
and it also might make GTK+ substantially less efficient if not handled
carefully.

Regardless, it's especially not a priority since relatively good
workarounds exist.

<!-- ----------------------------------------------------------------- -->
<sect1>How can I prevent redrawing and resizing while I change multiple widgets?
<p> 
Use gtk_container_disable_resize and gtk_container_enable_resize around the 
code where you are changing a lot of stuff. This will result in much faster 
speed since it will prevent resizing of the entire widget hierarchy. 

<!-- ----------------------------------------------------------------- -->
<sect1>How do I catch a double click event (in a list widget, for example)?
<p>
Tim Janik wrote to gtk-list (slightly modified):

Define a signal handler:

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

  return FALSE;
}
</verb></tscreen>

And connect the handler to your object:

<tscreen><verb>
{
  /* list, list item init stuff */     

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

  /* and/or */

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

  /* something else */
}
</verb></tscreen>

and, Owen Taylor wrote:

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.)
                                       
<!-- ----------------------------------------------------------------- -->
<sect1>How do I find out about the selection of a GtkList?
<p>

Get the selection something like this:
<tscreen><verb>
GList *sel;
sel = GTK_LIST(list)->selection;
</verb></tscreen>

This is how GList is defined (quoting glist.h):
<tscreen><verb>
typedef struct _GList GList;

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

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.

The selection_mode of the GtkList determines the selection
facilities of a GtkList and therefore the contents
of GTK_LIST(AnyGtkList)->selection:

<verb>
selection_mode          GTK_LIST()->selection contents
------------------------------------------------------

GTK_SELECTION_SINGLE)   selection is either NULL
                        or contains a GList* pointer
                        for a single selected item.

GTK_SELECTION_BROWSE)   selection is NULL if the list
                        contains no widgets, otherwise
                        it contains a GList* pointer
                        for one GList structure.
GTK_SELECTION_MULTIPLE) 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

GTK_SELECTION_EXTENDED) selection is NULL.
</verb>

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:

Upon Initialization:
<tscreen><verb>
{
        gchar           *list_items[]={
                                "Item0",
                                "Item1",
                                "foo",
                                "last Item",
                        };
        guint           nlist_items=sizeof(list_items)/sizeof(list_items[0]);
        GtkWidget       *list_item;
        guint           i;

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

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

To get known about the selection:
<tscreen><verb>
{
        GList   *items;

        items=GTK_LIST(list)->selection;

        printf("Selected Items: ");
        while (items) {
                if (GTK_IS_LIST_ITEM(items->data))
                        printf("%d ", (guint) 
                gtk_object_get_user_data(items->data));
                items=items->next;
        }
        printf("\n");
}
</verb></tscreen>
<!-- ----------------------------------------------------------------- -->
<sect1>Is it possible to get some text displayed which is truncated to fit inside its allocation? 
<p>
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.

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 it's own window - one possible candidate would
be the viewport widget.

<tscreen><verb>
viewport = gtk_viewport (NULL, NULL);
gtk_widget_set_usize (viewport, 50, 25);
gtk_viewport_set_shadow_type (GTK_VIEWPORT(viewport), GTK_SHADOW_NONE);
gtk_widget_show(viewport);

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

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).

<!-- ----------------------------------------------------------------- -->
<sect1>Why don't the contents of a button move when the button is pressed? Here's a patch to make it work that way...
<p>
From: Peter Mattis

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.
     
<!-- ----------------------------------------------------------------- -->
<sect1>How can I define a separation line in a menu? 
<p>
See the <htmlurl url="http://www.gtk.org/tutorial/"
name="Tutorial"> for information on how to create menus.
However, to create a separation line in a menu, just insert an
empty menu item:

<tscreen><verb>
menuitem = gtk_menu_item_new();
gtk_menu_append(GTK_MENU(menu), menuitem);
gtk_widget_show(menuitem);
</verb></tscreen>

<!-- ----------------------------------------------------------------- -->
<sect1>How can I right justify a menu, such as Help, when using the MenuFactory? 
<p>
Use something like the following:

<tscreen><verb>
menu_path = gtk_menu_factory_find (factory,  "<MyApp>/Help");
gtk_menu_item_right_justify(menu_path->widget);
</verb></tscreen>
<!-- ----------------------------------------------------------------- -->
<sect1>How do I make my window modal? / How do I make a single window active?
<p>
After you create your window, do gtk_grab_add(my_window). And after 
closing the window do gtk_grab_remove(my_window).

<!-- ----------------------------------------------------------------- -->
<sect1>Why doesn't my widget (e.g. progressbar) update?
<p>

You are probably doing all the changes within a function 
without returning control to gtk_main. Most drawing updates are only 
placed on a queue, which is processed within gtk_main. You can
force the drawing queue to be processed using something like:

<tscreen><verb>
while (gtk_events_pending())
        gtk_main_iteration();
</verb></tscreen>

inside you're function that changes the widget.

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).

<!-- ***************************************************************** -->
<sect>About gdk
<!-- ***************************************************************** -->

<!-- ----------------------------------------------------------------- -->
<sect1>What is gdk?
<p>
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 easy way 
to access Xlib functions in an easier an slightly more intuitive manner. 
In addition, since gdk uses glib (see below), it will be more portable 
and safer to use on multiple platforms.

<!-- Examples, anybody? I've been mulling some over. NF -->
   
<sect1>How do I use color allocation?
<p>
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:
<tscreen>
<verb>
{
  GdkColor *color;
  int width, height;
  GtkWidget *widget;
  GdkGC *gc;

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

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

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

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

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

  ...
}
</verb>
</tscreen>

<!-- ***************************************************************** -->
<sect>About glib
<!-- ***************************************************************** -->

<!-- ----------------------------------------------------------------- -->
<sect1>What is glib?
<p>
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.
<p>
It also provides routines for handling:
<itemize>
<item>Doubly Linked Lists
<item>Singly Linked Lists
<item>Timers
<item>String Handling
<item>A Lexical Scanner
<item>Error Functions
</itemize>

<!-- Some Examples might be useful here! NF -->         

<!-- ----------------------------------------------------------------- -->
<sect1>Why use g_print, g_malloc, g_strdup and fellow glib functions ?  
<p>
Thanks to Tim Janik who wrote to gtk-list: (slightly modified)
<quote>
Regarding g_malloc(), g_free() and siblings, these functions are much safer
than thier libc equivalences.  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()).
<p>
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. ;)
<p>
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 gtk_print()
(inside of gtkmain.c).
</quote>

<!-- ***************************************************************** -->
<sect>GTK+ FAQ Contributions, Maintainers and Copyright
<p>
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!

This document is maintained by Nathan Froyd 
<htmlurl url="mailto:maestrox@geocities.com" name="&lt;maestrox@geocities.com&gt;">
and Tony Gale <htmlurl url="mailto:gale@gimp.org" name="&lt;gale@gimp.org&gt;">. 
This FAQ was created by Shawn T. Amundson <htmlurl url="mailto:amundson@gimp.org" 
name="&lt;amundson@gimp.org&gt;">who continues to provide support.

The GTK+ FAQ is Copyright (C) 1997,1998 by Shawn T. Amundson, Nathan Froyd and Tony Gale.

Permission is granted to make and distribute verbatim copies of this manual provided the 
copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this document under the conditions 
for verbatim copying, provided that this copyright notice is included exactly as in the original, 
and that the entire resulting derived work is distributed under the terms of a permission 
notice identical to this one.

Permission is granted to copy and distribute translations of this document into another language, 
under the above conditions for modified versions.

If you are intending to incorporate this document into a published work, please contact one of
the maintainers, and we will make an effort to ensure that you have the most up to date 
information available.

There is no guarentee that this document lives up to its intended
purpose.  This is simply provided as a free resource.  As such,
the authors and maintainers of the information provided within can 
not make any guarentee that the information is even accurate.

</article>