Blame docs/faq/gtk-faq.sgml

Packit Service fb6fa5
Packit Service fb6fa5
<book>
Packit Service fb6fa5
Packit Service fb6fa5
<bookinfo>
Packit Service fb6fa5
  <date>January 14th 2004</date>
Packit Service fb6fa5
  <title>GTK+ FAQ</title>
Packit Service fb6fa5
  <authorgroup>
Packit Service fb6fa5
    <author>
Packit Service fb6fa5
<firstname>Tony</firstname>
Packit Service fb6fa5
<surname>Gale</surname>
Packit Service fb6fa5
    </author>
Packit Service fb6fa5
    <author>
Packit Service fb6fa5
<firstname>Shawn</firstname>
Packit Service fb6fa5
<surname>Amundson</surname>
Packit Service fb6fa5
    </author>
Packit Service fb6fa5
    <author>
Packit Service fb6fa5
<firstname>Emmanuel</firstname>
Packit Service fb6fa5
<surname>Deloget</surname>
Packit Service fb6fa5
    </author>
Packit Service fb6fa5
  </authorgroup>
Packit Service fb6fa5
  <abstract>
Packit Service fb6fa5
    <para> This document is intended to answer questions that are
Packit Service fb6fa5
    likely to be frequently asked by programmers using GTK+ or
Packit Service fb6fa5
    people who are just looking at using GTK+. </para>
Packit Service fb6fa5
    <para><emphasis>Note: </emphasis> This FAQ mainly covers GTK+ 1.2. 
Packit Service fb6fa5
	Where the text covers GTK+ 2.x this will be indicated</para>
Packit Service fb6fa5
  </abstract>
Packit Service fb6fa5
</bookinfo>
Packit Service fb6fa5
Packit Service fb6fa5
<toc></toc>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<chapter>
Packit Service fb6fa5
<title>General Information</title>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Note: This FAQ is undergoing conversion to GTK+ 2.x</title>
Packit Service fb6fa5
<para>This FAQ is undergoing conversion to GTK+ 2.x.
Packit Service fb6fa5
Where the text covers GTK+ 2.x this will be indicated by prefixing the
Packit Service fb6fa5
text with: <emphasis>[GTK+ 2.x]</emphasis>. Where this is not
Packit Service fb6fa5
indicated, the text has not yet been updated from GTK+ 1.2 and may
Packit Service fb6fa5
not be totally correct.
Packit Service fb6fa5
</para>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Before anything else: the greetings <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
<para>The FAQ authors want to thank:</para>
Packit Service fb6fa5
<itemizedlist spacing=Compact>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Havoc Pennington</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Erik Mouw</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Owen Taylor</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Tim Janik</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Thomas Mailund Jensen</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Joe Pfeiffer</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Andy Kahn</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Federico Mena Quntero</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Damon Chaplin</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>and all the members of the GTK+ lists</simpara>
Packit Service fb6fa5
</listitem></itemizedlist>
Packit Service fb6fa5
<para> If we forgot you, please email us! Thanks again (I know,
Packit Service fb6fa5
it's really short :) </para>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Authors <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The original authors of GTK+ were:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<itemizedlist spacing=Compact>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Peter Mattis</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Spencer Kimball</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Josh MacDonald</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
</itemizedlist>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Since then, much has been added by others. Please see the
Packit Service fb6fa5
AUTHORS file in the distribution for the GTK+ Team. The people currently
Packit Service fb6fa5
contributing the most code to GTK+ are (in no particular order):</para>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<itemizedlist spacing=Compact>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Owen Taylor</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Matthias Clasen</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Federico Mena Quintero</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Soeren Sandmann</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Padraig O'Briain</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Manish Singh</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Kristian Rietveld</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem>
Packit Service fb6fa5
<simpara>Tor Lillqvist</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
</itemizedlist>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>What is GTK+? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>GTK+ is a multi-platform toolkit for creating graphical user
Packit Service fb6fa5
interfaces, originally designed with
Packit Service fb6fa5
the general look and feel of Motif.  In reality, it looks much
Packit Service fb6fa5
better than Motif.  It contains common and complex widgets, such as
Packit Service fb6fa5
file selection, and color selection widgets.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>GTK+ was initially developed as a widget set for the GIMP (GNU Image
Packit Service fb6fa5
Manipulation Program). It has grown extensively since then, and is today
Packit Service fb6fa5
used by a large number of applications, and is the toolkit used by the
Packit Service fb6fa5
<ulink url="http://www.gnome.org/">GNOME</ulink> desktop project.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>GTK+ is free software and part of the GNU Project. However, the
Packit Service fb6fa5
licensing terms for GTK+, the GNU LGPL, allow it to be used by all developers,
Packit Service fb6fa5
including those developing proprietary software, without any license fees
Packit Service fb6fa5
or royalties.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>GTK+ has been designed from the ground up to support a range of
Packit Service fb6fa5
<ulink url="http://www.gtk.org/bindings.html">
Packit Service fb6fa5
language bindings</ulink>, not only C/C++. Using GTK+ from languages
Packit Service fb6fa5
such as Perl and Python (especially in combination with the Glade GUI
Packit Service fb6fa5
builder) provides an effective method of rapid application
Packit Service fb6fa5
development..</para>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>What is the + in GTK+? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Peter Mattis informed the gtk mailing list that:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para><quote>I originally wrote gtk which included the three
Packit Service fb6fa5
libraries, libglib, libgdk and libgtk. It featured a flat
Packit Service fb6fa5
widget hierarchy. That is, you couldn't derive a new widget
Packit Service fb6fa5
from an existing one. And it contained a more standard
Packit Service fb6fa5
callback mechanism instead of the signal mechanism now present
Packit Service fb6fa5
in gtk+. The + was added to distinguish between the original
Packit Service fb6fa5
version of gtk and the new version. You can think of it as
Packit Service fb6fa5
being an enhancement to the original gtk that adds object
Packit Service fb6fa5
oriented features.</quote></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Although much has changed with GTK+, and Peter, Spencer and Josh
Packit Service fb6fa5
don't have any direct involvement these days, the name is kept to keep
Packit Service fb6fa5
a link with the heritage of GTK+.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>GTK+ is now additionally based upon the Pango and ATK
Packit Service fb6fa5
libraries, that provide text layout and rendering and accessibility
Packit Service fb6fa5
interfaces.</para>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Does the G in GTK+, GDK and GLib stand for? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>GTK+ == The GIMP Toolkit</para>
Packit Service fb6fa5
<para>GDK == GTK+ Drawing Kit</para>
Packit Service fb6fa5
<para>GLib == G Library</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Where is the documentation for GTK+? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>In the GTK+ distribution's doc/ directory you will find
Packit Service fb6fa5
the API Reference for both GTK and GDK, this FAQ and the
Packit Service fb6fa5
GTK Tutorial.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>In addition, you can find links to HTML versions of
Packit Service fb6fa5
these documents by going to <ulink url="http://www.gtk.org/">
Packit Service fb6fa5
http://www.gtk.org/</ulink>. A
Packit Service fb6fa5
packaged version of the GTK Tutorial, with SGML, HTML,
Packit Service fb6fa5
Postscript, DVI and text versions can be found in 
Packit Service fb6fa5
url="ftp://ftp.gtk.org/pub/gtk/tutorial">
Packit Service fb6fa5
ftp://ftp.gtk.org/pub/gtk/tutorial
Packit Service fb6fa5
</ulink></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>There are now a few books available that deal with
Packit Service fb6fa5
programming GTK+, GDK and GNOME. Unfortunately, they
Packit Service fb6fa5
currently are all based upon GTK+ 1.x:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<itemizedlist>
Packit Service fb6fa5
<listitem><simpara>Eric Harlows book entitled "Developing
Packit Service fb6fa5
Linux Applications with GTK+ and GDK". The ISBN is
Packit Service fb6fa5
0-7357-0021-4</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem><simpara>The example code from Eric's book is
Packit Service fb6fa5
available on-line at 
Packit Service fb6fa5
url="http://www.bcpl.net/~eharlow/book">
Packit Service fb6fa5
http://www.bcpl.net/~eharlow/book</ulink></simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem><simpara>Havoc Pennington has released a book called
Packit Service fb6fa5
"GTK+/GNOME Application Development". The ISBN is
Packit Service fb6fa5
0-7357-0078-8</simpara>
Packit Service fb6fa5
<simpara>The free version of the book lives here: 
Packit Service fb6fa5
url="http://developer.gnome.org/doc/GGAD/">
Packit Service fb6fa5
http://developer.gnome.org/doc/GGAD/
Packit Service fb6fa5
</ulink></simpara>
Packit Service fb6fa5
<simpara>And Havoc maintains information about it and
Packit Service fb6fa5
errata here: 
Packit Service fb6fa5
url="http://pobox.com/~hp/gnome-app-devel.html">
Packit Service fb6fa5
http://pobox.com/~hp/gnome-app-devel.html
Packit Service fb6fa5
</ulink></simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem><simpara>"GTK+ Programming in C" by
Packit Service fb6fa5
Syd Logan. ISBN: 0-1301-4264-6</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem><simpara>"Linux GNOME/GTK+ Programming Bible" by
Packit Service fb6fa5
Arthur Griffith. ISBN: 0-7645-4640-6</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem><simpara>"Beginning GTK+/GNOME Programming" by
Packit Service fb6fa5
Peter Wright. ISBN: 1-8610-0381-1</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem><simpara>"Sams Teach Yourself GTK+ Programming
Packit Service fb6fa5
in 21 Days" by Donna Martin
Packit Service fb6fa5
. ISBN: 0-6723-1829-6</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
</itemizedlist>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1 id="faq-MailLists">
Packit Service fb6fa5
<title>Is there a mailing list (or mailing list archive) for
Packit Service fb6fa5
GTK+? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Information on mailing lists relating to GTK+ can be
Packit Service fb6fa5
found at: 
Packit Service fb6fa5
url="http://www.gtk.org/mailinglists.html">
Packit Service fb6fa5
http://www.gtk.org/mailinglists.html
Packit Service fb6fa5
</ulink></para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How to get help with GTK+ <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>First, make sure your question isn't answered in the
Packit Service fb6fa5
documentation, this FAQ or the tutorial. Done that? You're
Packit Service fb6fa5
sure you've done that, right? In that case, the best place to
Packit Service fb6fa5
post questions is to the GTK+ mailing list.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How to report bugs in GTK+ <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Bugs should be reported to the GNOME bug tracking system
Packit Service fb6fa5
(<ulink url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>).
Packit Service fb6fa5
You will need to enter your email address and receive a password before
Packit Service fb6fa5
you can use the system to register a new bug report.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>There are a number of options to select and boxes to fill in when
Packit Service fb6fa5
submitting a bug report. Please remember that the more information you
Packit Service fb6fa5
give, the easier it will be to track the problem down. Extra information
Packit Service fb6fa5
that may prove useful includes:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<itemizedlist>
Packit Service fb6fa5
<listitem><simpara> How to reproduce the bug.</simpara>
Packit Service fb6fa5
<simpara>If you can reproduce it with the testgtk program
Packit Service fb6fa5
that is built in the gtk/ subdirectory, that will be most
Packit Service fb6fa5
convenient. Otherwise, please include a complete, short test
Packit Service fb6fa5
program that exhibits the behavior. As a last resort, you can also
Packit Service fb6fa5
provide a pointer to a larger piece of software that can
Packit Service fb6fa5
be downloaded.</simpara>
Packit Service fb6fa5
Packit Service fb6fa5
<simpara>(Bugs that can be reproduced within the GIMP are
Packit Service fb6fa5
almost as good as bugs that can be reproduced in
Packit Service fb6fa5
testgtk. If you are reporting a bug found with the GIMP,
Packit Service fb6fa5
please include the version number of the GIMP you are
Packit Service fb6fa5
using)</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> If the bug was a crash, the exact text that was
Packit Service fb6fa5
printed out when the crash occurred. If you can easily reproduce this
Packit Service fb6fa5
crash then running the program under a debugger (e.g. gdb) and getting
Packit Service fb6fa5
a backtrace when the crash occurs is very useful.</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> Further information such as stack traces
Packit Service fb6fa5
may be useful. If you do send a stack trace,
Packit Service fb6fa5
and the error is an X error, it will be more useful if the stacktrace is
Packit Service fb6fa5
produced running the test program with the <literal>--sync</literal>
Packit Service fb6fa5
command line option.</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
</itemizedlist>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Is there a Windows version of GTK+? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The Win32 port of GTK+ is maintained concurrently with the Xwindows
Packit Service fb6fa5
version in Git. As such it is a supported architecture.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The Win32 port has been predominately done by Tor Lillqvist. Tor
Packit Service fb6fa5
maintains some information on the
Packit Service fb6fa5
  Windows <ulink url="http://www.gtk.org/download.html">download
Packit Service fb6fa5
    page</ulink> (32bit and 64bit).</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>There is a pre-compiled, easy-to-install version of GTK+ for
Packit Service fb6fa5
windows on the <ulink url="http://www.dropline.net/gtk/">
Packit Service fb6fa5
Dropline GTK+</ulink> site.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>What applications have been written with GTK+? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The GNOME software map contains a catalogue of software that is
Packit Service fb6fa5
built using GNOME and GTK+. The catalogue is searchable and browsable, so
Packit Service fb6fa5
provides easy access.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Some of the best known projects utilising GTK+ are:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<itemizedlist>
Packit Service fb6fa5
<listitem><simpara> GIMP (
Packit Service fb6fa5
url="http://www.gimp.org/">http://www.gimp.org/</ulink>), an
Packit Service fb6fa5
image manipulation program</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem><simpara> AbiWord (
Packit Service fb6fa5
url="http://www.abiword.org/">http://www.abiword.com/</ulink>),
Packit Service fb6fa5
a professional word processor</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem><simpara> Dia (
Packit Service fb6fa5
url="http://www.lysator.liu.se/~alla/dia/dia.html">
Packit Service fb6fa5
http://www.lysator.liu.se/~alla/dia/dia.html</ulink>),
Packit Service fb6fa5
a diagram creation program</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem><simpara> GnuCash (
Packit Service fb6fa5
url="http://www.gnucash.org/">
Packit Service fb6fa5
http://www.gnucash.org/</ulink>),
Packit Service fb6fa5
a personal finance manager</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem><simpara> Gnumeric (
Packit Service fb6fa5
url="http://www.gnome.org/projects/gnumeric/">
Packit Service fb6fa5
http://www.gnome.org/projects/gnumeric/</ulink>),
Packit Service fb6fa5
the GNOME spreadsheet application</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem><simpara> Glade (
Packit Service fb6fa5
url="http://glade.gnome.org/">http://glade.gnome.org/</ulink>), a
Packit Service fb6fa5
GTK+ based RAD tool which produces GTK+ and GNOME applications</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
<listitem><simpara> Anjuta (
Packit Service fb6fa5
url="http://anjuta.sourceforge.net/">http://anjuta.sourceforge.net/</ulink>),
Packit Service fb6fa5
a versatile Integrated Development Environment (IDE) using C and C++ for GTK+
Packit Service fb6fa5
and GIMP.</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
</itemizedlist>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
</chapter>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<chapter>
Packit Service fb6fa5
<title>How to find, configure, install, and troubleshoot GTK+</title>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1 id="faq-Compile">
Packit Service fb6fa5
<title>What do I need to compile GTK+? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>GTK+ is a large package that is dependent on a number of other
Packit Service fb6fa5
tools and libraries. It is recommended that you use precompiled
Packit Service fb6fa5
binary packages for your system if possible</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>To compile GTK+ from source you need a C compiler (gcc) and
Packit Service fb6fa5
the X Window System and associated development libraries and packages
Packit Service fb6fa5
on your system.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>You will also need to have installed the tools
Packit Service fb6fa5
and libraries that GTK+ depends upon. These are listed below in the order
Packit Service fb6fa5
in which they need to be installed:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<itemizedlist spacing=compact>
Packit Service fb6fa5
<listitem><simpara> pkg-config
Packit Service fb6fa5
(<ulink url="http://pkg-config.freedesktop.org/wiki">
Packit Service fb6fa5
pkg-config Site</ulink>)</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> GNU make
Packit Service fb6fa5
(<ulink url="http://www.gnu.org/software/make/">
Packit Service fb6fa5
GNU make Site</ulink>)</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> JPEG, PNG and TIFF image libraries
Packit Service fb6fa5
(<ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/dependencies/">
Packit Service fb6fa5
GTK+ Site</ulink>)</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> FreeType
Packit Service fb6fa5
(<ulink url="http://www.freetype.org/">
Packit Service fb6fa5
FreeType Site</ulink>)</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> fontconfig
Packit Service fb6fa5
(<ulink url="http://www.fontconfig.org/">
Packit Service fb6fa5
fontconfig Site</ulink>)</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> GNU libiconv library (if your system doesn't have iconv())
Packit Service fb6fa5
(<ulink url="http://www.gnu.org/software/libiconv/">
Packit Service fb6fa5
GNU libiconv Site</ulink>)</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> GNU gettext (if your system doesn't have gettext())
Packit Service fb6fa5
(<ulink url="http://www.gnu.org/software/gettext/">
Packit Service fb6fa5
GTK+ Site</ulink>)</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> GLib
Packit Service fb6fa5
(<ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">
Packit Service fb6fa5
GTK+ Site</ulink>)</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> Pango
Packit Service fb6fa5
(<ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">
Packit Service fb6fa5
GTK+ Site</ulink>)</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> ATK
Packit Service fb6fa5
(<ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">
Packit Service fb6fa5
GTK+ Site</ulink>)</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> GTK+
Packit Service fb6fa5
(<ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">
Packit Service fb6fa5
GTK+ Site</ulink>)</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
</itemizedlist>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Where can I get GTK+? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The canonical site is 
Packit Service fb6fa5
url="ftp://ftp.gtk.org/pub/gtk">ftp://ftp.gtk.org/pub/gtk</ulink>.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>This site tends to get busy around the time of a new
Packit Service fb6fa5
GTK+ release so try and use one of the mirror sites that are
Packit Service fb6fa5
listed in 
Packit Service fb6fa5
url="ftp://ftp.gtk.org/etc/mirrors">ftp://ftp.gtk.org/etc/mirrors
Packit Service fb6fa5
</ulink></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Here's a few mirror sites to get you started:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<itemizedlist spacing=compact>
Packit Service fb6fa5
<listitem><simpara> Africa -
Packit Service fb6fa5
<ulink url="ftp://ftp.is.co.za/applications/gimp">
Packit Service fb6fa5
ftp://ftp.is.co.za/applications/gimp</ulink></simpara> 
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> Australia -
Packit Service fb6fa5
Packit Service fb6fa5
url="ftp://ftp.planetmirror.com/pub/gimp/gtk">
Packit Service fb6fa5
ftp://ftp.planetmirror.com/pub/gimp/gtk</ulink></simpara> 
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> Finland -
Packit Service fb6fa5
<ulink url="ftp://ftp.funet.fi/pub/sci/graphics/packages/gimp/gtk">
Packit Service fb6fa5
ftp://ftp.funet.fi/pub/sci/graphics/packages/gimp/gtk</ulink></simpara> 
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> Germany -
Packit Service fb6fa5
<ulink url="ftp://ftp.gwdg.de/pub/misc/grafik/gimp/gtk">
Packit Service fb6fa5
ftp://ftp.gwdg.de/pub/misc/grafik/gimp/gtk</ulink></simpara> 
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> Japan -
Packit Service fb6fa5
<ulink url="ftp://sunsite.sut.ac.jp/pub/archives/packages/gimp/gtk">
Packit Service fb6fa5
ftp://sunsite.sut.ac.jp/pub/archives/packages/gimp/gtk</ulink></simpara> 
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> UK - 
Packit Service fb6fa5
<ulink url="http://www.mirror.ac.uk/sites/ftp.gimp.org/pub/gtk/">
Packit Service fb6fa5
http://www.mirror.ac.uk/sites/ftp.gimp.org/pub/gtk/</ulink></simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
</itemizedlist>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I configure/compile GTK+? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Generally, the minimum you need to do is issue the commands:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para><literallayout><literal>./configure</literal>
Packit Service fb6fa5
<literal>make</literal>
Packit Service fb6fa5
<literal>make install</literal></literallayout></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>in the GTK+ source directory.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>This generally also holds true for each of the packages that GTK+
Packit Service fb6fa5
depends upon, listed <link linkend="faq-Compile">above</link>.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>There are various options that you can pass to the configure script
Packit Service fb6fa5
in order to change its default settings. The one that you are most likely
Packit Service fb6fa5
to want to use is the <literal>--prefix</literal>
Packit Service fb6fa5
argument, which defines where the package is to be install, e.g.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>
Packit Service fb6fa5
<literallayout><literal>./configure --prefix=/usr</literal></literallayout>
Packit Service fb6fa5
</para>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>When compiling GTK+ I get an error like: <literal>make:
Packit Service fb6fa5
file `Makefile' line 456: Syntax error</literal> <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Make sure that you are using GNU make
Packit Service fb6fa5
(use <literal>make -v</literal>
Packit Service fb6fa5
to check). There are many weird and wonderful versions of make
Packit Service fb6fa5
out there, and not all of them handle the automatically
Packit Service fb6fa5
generated Makefiles.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>I've compiled and installed GTK+, but I can't get any
Packit Service fb6fa5
programs to link with it! <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>This problem is most often encountered when the GTK+
Packit Service fb6fa5
libraries can't be  found or are the wrong version. Generally,
Packit Service fb6fa5
the compiler will complain about an 'unresolved symbol'.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Make sure that the libraries can be
Packit Service fb6fa5
found. You want to edit <filename>/etc/ld.so.conf</filename> to
Packit Service fb6fa5
include the directories which contain the GTK libraries,
Packit Service fb6fa5
so it looks something like:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para><literallayout><literal>/usr/X11R6/lib</literal>
Packit Service fb6fa5
<literal>/usr/local/lib</literal></literallayout></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Then you need to run /sbin/ldconfig as root. You can
Packit Service fb6fa5
find what libraries GTK requires using</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para><literallayout><literal>pkg-config gtk+-2.0 --libs</literal>
Packit Service fb6fa5
</literallayout></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>If your system doesn't use ld.so to find libraries
Packit Service fb6fa5
(such as Solaris), then you will have to use the LD_LIBRARY_PATH
Packit Service fb6fa5
environment variable (or compile the path into your program, which I'm
Packit Service fb6fa5
not going to cover here). So, with a Bourne type shell you can do (if
Packit Service fb6fa5
your GTK libraries are in /usr/local/lib):</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para><literallayout>
Packit Service fb6fa5
<literal>export LD_LIBRARY_PATH=/usr/local/lib</literal>
Packit Service fb6fa5
</literallayout></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>and in a csh, you can do:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para><literallayout>
Packit Service fb6fa5
<literal>setenv LD_LIBRARY_PATH /usr/local/lib</literal>
Packit Service fb6fa5
</literallayout></para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>When installing a GTK+ application, configure reports
Packit Service fb6fa5
that it can't find GTK. <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>There are several common reasons for this:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<itemizedlist>
Packit Service fb6fa5
<listitem><simpara>You have an old version of GTK installed
Packit Service fb6fa5
somewhere. You should remove this old copy, but note that
Packit Service fb6fa5
this may break applications that have been compiled against
Packit Service fb6fa5
the old version.</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara><literal>pkg-config</literal> (or another
Packit Service fb6fa5
component of GTK) isn't in your path, or there is an old
Packit Service fb6fa5
version on your system. Type:</simpara>
Packit Service fb6fa5
Packit Service fb6fa5
<para><literallayout>
Packit Service fb6fa5
<literal>pkg-config gtk+-2.0 --modversion</literal>
Packit Service fb6fa5
</literallayout></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>to check for both of these. If it returns a value
Packit Service fb6fa5
different from what you expect, then you have an old
Packit Service fb6fa5
version of GTK on your system.</para>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara>The ./configure script can't find the GTK
Packit Service fb6fa5
libraries. As ./configure compiles various test programs, it needs to be
Packit Service fb6fa5
able to find the GTK libraries. See the question above
Packit Service fb6fa5
for help on this. </simpara></listitem>
Packit Service fb6fa5
</itemizedlist>
Packit Service fb6fa5
Packit Service fb6fa5
<para>If none of the above help, then have a look in
Packit Service fb6fa5
config.log, which is generated by ./configure as it runs. At the
Packit Service fb6fa5
bottom will be the last action it took before failing. If it is a
Packit Service fb6fa5
section of source code, copy the source code to a file and compile it
Packit Service fb6fa5
with the line just above it in config.log. If the compilation is
Packit Service fb6fa5
successful, try executing it.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
</chapter>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<chapter>
Packit Service fb6fa5
<title>Development of GTK+</title>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>What's this Git thing that everyone keeps talking about,
Packit Service fb6fa5
and how do I access it? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Git is a version control system and it is a very
Packit Service fb6fa5
popular means of version control for software projects. It is
Packit Service fb6fa5
designed to allow multiple authors to simultanously operate on the same
Packit Service fb6fa5
source tree.  This source tree is centrally maintained, but each
Packit Service fb6fa5
developer has a local mirror of this repository that they make
Packit Service fb6fa5
their changes to.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The GTK+ developers use a Git repository to store the
Packit Service fb6fa5
master copy of the current development version of GTK+. As
Packit Service fb6fa5
such, people wishing to contribute patches to GTK+ should
Packit Service fb6fa5
generate them against the Git version. Normal people should
Packit Service fb6fa5
use the packaged releases.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The Git toolset is available as a package on most distributions
Packit Service fb6fa5
  and the released tarballs are available
Packit Service fb6fa5
  from <ulink url="http://git-scm.com/">http://git-scm.com/</ulink>.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Anyone can download the latest Git version of GTK+ by
Packit Service fb6fa5
using anonymous access using the following steps:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<itemizedlist>
Packit Service fb6fa5
<listitem><simpara>In a bourne shell descendant (e.g. bash) type:</simpara>
Packit Service fb6fa5
<para><literallayout>
Packit Service fb6fa5
<literal>git clone git://git.gnome.org/gtk+</literal>
Packit Service fb6fa5
</literallayout></para>
Packit Service fb6fa5
<para>Note that with the GTK+ 1.1 tree, glib has been moved to
Packit Service fb6fa5
a separate Git module, so if you don't have glib installed you will
Packit Service fb6fa5
need to get that as well:<literallayout>
Packit Service fb6fa5
<literal>git clone git://git.gnome.org/glib</literal>
Packit Service fb6fa5
</literallayout></para>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
</itemizedlist>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The Git archive stores both the current development version of
Packit Service fb6fa5
GTK+ (the Git master branch) and all current and past stable versions.
Packit Service fb6fa5
If you want to retrieve a specific version of GTK+ you have to specify
Packit Service fb6fa5
the Git tag corresponding to the version you want to checkout. If you
Packit Service fb6fa5
want to checkout the current GTK+ 2.2 stable source code, you would need
Packit Service fb6fa5
to use the following command:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para><literallayout>
Packit Service fb6fa5
<literal>git checkout --track -b gtk-2-24 origin/gtk-2-24</literal>
Packit Service fb6fa5
</literallayout></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>You can switch between branches once set up more easily using:</para>
Packit Service fb6fa5
<para><literallayout>
Packit Service fb6fa5
<literal>git checkout master</literal>
Packit Service fb6fa5
</literallayout></para>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1 id="faq-Patches">
Packit Service fb6fa5
<title>How can I contribute to GTK+? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>It's simple. If something doesn't work like you think it
Packit Service fb6fa5
should in a program, check the documentation to make sure
Packit Service fb6fa5
you're not missing something. If it is a true bug or missing
Packit Service fb6fa5
feature, track it down in the GTK+ source, change it,  and
Packit Service fb6fa5
then generate a patch in the form of a 'context diff'. This
Packit Service fb6fa5
can be done using a command such as <literal>diff -ru
Packit Service fb6fa5
<oldfile> <newfile></literal>.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The patch should then be attached to a bug report in
Packit Service fb6fa5
the GNOME bug tracking system, which can also be used to store
Packit Service fb6fa5
general patches
Packit Service fb6fa5
(<ulink url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>).
Packit Service fb6fa5
</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>This method ensures that the patch will not be lost.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I know if my patch got applied, and if not, why
Packit Service fb6fa5
not? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>If you have used the GNOME bug tracking system (as stated
Packit Service fb6fa5
<link linkend="faq-Patches">above</link>) then the status
Packit Service fb6fa5
of your patch should be reflected in the bug report.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The GTK+ developers will generally add comments to the bug
Packit Service fb6fa5
report stating what needs to be done to get the patch applied,
Packit Service fb6fa5
or why the patch is not appropriate.</para>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>What is the policy on incorporating new widgets into
Packit Service fb6fa5
the library? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>This is up to the authors, so you will have to ask them
Packit Service fb6fa5
once you are done with your widget. As a general guideline,
Packit Service fb6fa5
widgets that are generally useful, work, and are not a
Packit Service fb6fa5
disgrace to the widget set will gladly be included.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The new widgets that get added to GTK+ are generally either
Packit Service fb6fa5
replacements for existing widgets that are no longer
Packit Service fb6fa5
deemed to be adequate, or have been developed externally to GTK+ but
Packit Service fb6fa5
have been widely tested.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Before you spend months of your valuable time implementing your
Packit Service fb6fa5
revolutionary widget, it is highly recommended that you get some
Packit Service fb6fa5
feedback on your idea via the appropriate 
Packit Service fb6fa5
<link linkend="faq-MailLists">mailing list</link>.</para>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Is anyone working on bindings for languages other than
Packit Service fb6fa5
C? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>There is a list of <ulink url="http://www.gtk.org/bindings.html">
Packit Service fb6fa5
language bindings</ulink> on the GTK+ website.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The 'official' language bindings are C++, Ada and Python.
Packit Service fb6fa5
However, bindings for many other languages are available.</para>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
</chapter>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<chapter>
Packit Service fb6fa5
<title>Development with GTK+: the begining</title>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I get started? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>So, after you have installed GTK+ there are a couple of
Packit Service fb6fa5
things that can ease you into developing applications with
Packit Service fb6fa5
it. There is the GTK+ Tutorial 
Packit Service fb6fa5
url="http://library.gnome.org/devel/gtk-tutorial/stable/">
Packit Service fb6fa5
http://library.gnome.org/devel/gtk-tutorial/stable/</ulink>, which is undergoing
Packit Service fb6fa5
development. This will introduce you to writing applications
Packit Service fb6fa5
using C.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The GTK+ Tutorial doesn't contain information on all of
Packit Service fb6fa5
the widgets that are in GTK+. For example code on how to use
Packit Service fb6fa5
the basics of all the GTK+ widgets you should look in the
Packit Service fb6fa5
directory 'tests' (and associated source files) within the GTK+
Packit Service fb6fa5
distribution. Looking at these examples will give you a good
Packit Service fb6fa5
grounding on what the widgets can do.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I use the Glade GUI builder with GTK+? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>There are two ways to use Glade. The first way is to use
Packit Service fb6fa5
Glade's facilities for generating code; the second
Packit Service fb6fa5
way is to use the libglade library which directly loads
Packit Service fb6fa5
the XML user interface description files that Glade
Packit Service fb6fa5
generates into a running program.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Experienced GTK+ programmers generally strongly recommend
Packit Service fb6fa5
using libglade; you don't have to worry about the interaction
Packit Service fb6fa5
between Glade generating the source and you editing it,
Packit Service fb6fa5
and its been shown to be a method that works better
Packit Service fb6fa5
for large projects, so there is a lot of example code
Packit Service fb6fa5
out there you can look at.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>An introduction to using libglade can be found in the 
Packit Service fb6fa5
libglade API docs
Packit Service fb6fa5
(<ulink url="http://developer.gnome.org/doc/API/2.0/libglade/libglade-notes.html#libglade-basics">
Packit Service fb6fa5
http://developer.gnome.org/doc/API/2.0/libglade/libglade-notes.html#libglade-basics</ulink>)
Packit Service fb6fa5
.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I write security sensitive/SUID/SGID programs with GTK+?
Packit Service fb6fa5
Is GTK+ secure? What's this GTK_MODULES security hole I heard about?
Packit Service fb6fa5
<emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The short answer to this question is: you can't, so don't write SUID/SGID
Packit Service fb6fa5
programs with GTK+</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>GTK+ will refuse to run with elevated privileges, as it is not designed
Packit Service fb6fa5
to be used in this manner. The only correct way to write a setuid program with
Packit Service fb6fa5
a graphical user interface is to have a setuid backend that communicates with
Packit Service fb6fa5
the non-setuid graphical user interface via a mechanism such as a pipe and that
Packit Service fb6fa5
considers the input it receives to be untrusted.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>For a more thorough explanation of the GTK+ Developers position on
Packit Service fb6fa5
this issue see 
Packit Service fb6fa5
url="http://www.gtk.org/setuid.html">http://www.gtk.org/setuid.html</ulink>.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>I tried to compile a small <command>Hello World</command> of mine,
Packit Service fb6fa5
but it failed. Any clue? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Since you are good at coding, we will not deal with
Packit Service fb6fa5
compile time errors here :)</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The classic command line to compile a GTK+ based program is</para>
Packit Service fb6fa5
<para><literallayout>
Packit Service fb6fa5
<literal>gcc -o myprog [c files] `pkg-config gtk+-2.0 --cflags --libs`</literal>
Packit Service fb6fa5
</literallayout></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>You should notice the backquote character which is used
Packit Service fb6fa5
in this command line. A common mistake when you start a GTK+
Packit Service fb6fa5
based development is to use quotes instead of backquotes. If
Packit Service fb6fa5
you do so, the compiler will complain about an unknown file
Packit Service fb6fa5
called <filename>pkg-config gtk+-2.0 --cflags --libs</filename>. The
Packit Service fb6fa5
text in backquotes is an instruction to your shell to
Packit Service fb6fa5
substitute the output of executing this command into the
Packit Service fb6fa5
commandline.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The command line above ensures that:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<itemizedlist>
Packit Service fb6fa5
<listitem><simpara>the correct C compiler flags will be used
Packit Service fb6fa5
to compile the program (including the complete C header
Packit Service fb6fa5
directory list)</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara>your program will be linked with the
Packit Service fb6fa5
needed libraries.</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
</itemizedlist>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>What about using the <command>make</command>
Packit Service fb6fa5
utility? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>This is a sample makefile which compiles a GTK+ based
Packit Service fb6fa5
program:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
# basic GTK+ app makefile
Packit Service fb6fa5
SOURCES = myprg.c foo.c bar.c
Packit Service fb6fa5
OBJS    = ${SOURCES:.c=.o}
Packit Service fb6fa5
CFLAGS  = `pkg-config gtk+-2.0 --cflags`
Packit Service fb6fa5
LDADD   = `pkg-config gtk+-2.0 --libs`
Packit Service fb6fa5
CC      = gcc
Packit Service fb6fa5
PACKAGE = myprg
Packit Service fb6fa5
Packit Service fb6fa5
all : ${OBJS}
Packit Service fb6fa5
  ${CC} -o ${PACKAGE} ${OBJS} ${LDADD}
Packit Service fb6fa5
Packit Service fb6fa5
.c.o:
Packit Service fb6fa5
  ${CC} ${CFLAGS} -c $<
Packit Service fb6fa5
Packit Service fb6fa5
# end of file
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>For more information about the <command>make</command> utility, you
Packit Service fb6fa5
should read either the related man page or the relevant info file.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>I use the backquote stuff in my makefiles, but my make
Packit Service fb6fa5
process failed. <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The backquote construction seems to not be accepted by
Packit Service fb6fa5
some old <command>make</command> utilities. If you use one of these, the
Packit Service fb6fa5
make process will probably fail. In order to have the
Packit Service fb6fa5
backquote syntax working again, you should use the GNU make
Packit Service fb6fa5
utility (get it on the GNU ftp server at 
Packit Service fb6fa5
url="ftp://ftp.gnu.org/gnu/make/">ftp://ftp.gnu.org/gnu/make/</ulink>).</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>I want to add some configure stuff, how could I do
Packit Service fb6fa5
this? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>To use autoconf/automake, you must first install the
Packit Service fb6fa5
relevant packages. These are:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<itemizedlist spacing=Compact>
Packit Service fb6fa5
<listitem><simpara>the m4 preprocessor v1.4 or better</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara>autoconf v2.54 or better</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara>automake v1.7 or better suggested</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
</itemizedlist>
Packit Service fb6fa5
Packit Service fb6fa5
<para>You'll find these packages on the main GNU ftp server
Packit Service fb6fa5
(<ulink url="ftp://ftp.gnu.org/">ftp://ftp.gnu.org/</ulink>)
Packit Service fb6fa5
or on any GNU mirror.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>In order to use the powerful autoconf/automake scheme,
Packit Service fb6fa5
you must create a configure.in which may look like:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
dnl Process this file with autoconf to produce a configure script.
Packit Service fb6fa5
dnl configure.in for a GTK+ based program
Packit Service fb6fa5
Packit Service fb6fa5
AC_INIT(myprg.c)
Packit Service fb6fa5
AM_INIT_AUTOMAKE(mypkgname, 0.0.1)
Packit Service fb6fa5
AM_CONFIG_HEADER(config.h)
Packit Service fb6fa5
Packit Service fb6fa5
dnl Checks for programs.
Packit Service fb6fa5
AC_PROG_CC dnl check for the c compiler
Packit Service fb6fa5
dnl you should add CFLAGS="" here, 'cos it is set to -g by PROG_CC
Packit Service fb6fa5
Packit Service fb6fa5
dnl Checks for libraries.
Packit Service fb6fa5
AM_PATH_GTK_2_0(2.2.0,,AC_MSG_ERROR(mypkgname 0.1 needs GTK+ 2.2.0))
Packit Service fb6fa5
Packit Service fb6fa5
AC_OUTPUT(
Packit Service fb6fa5
	Makefile
Packit Service fb6fa5
)
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>You must add a Makefile.am file:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
bin_PROGRAMS    = myprg
Packit Service fb6fa5
myprg_SOURCES   = myprg.c foo.c bar.c
Packit Service fb6fa5
INCLUDES        = @GTK_CFLAGS@
Packit Service fb6fa5
LDADD           = @GTK_LIBS@
Packit Service fb6fa5
CLEANFILES      = *~
Packit Service fb6fa5
DISTCLEANFILES  = .deps/*.P
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>If your project contains more than one subdirectory,
Packit Service fb6fa5
you'll have to create one Makefile.am in each directory plus a
Packit Service fb6fa5
master Makefile.am which will look like:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
SUBDIRS         = mydir1 mydir2 mydir3
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>then, to use these, simply type the following
Packit Service fb6fa5
commands:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
aclocal
Packit Service fb6fa5
autoheader
Packit Service fb6fa5
autoconf
Packit Service fb6fa5
automake --add-missing --include-deps --foreign 
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>For further information, you should look at the autoconf
Packit Service fb6fa5
and the automake documentation (the shipped info files are
Packit Service fb6fa5
really easy to understand, and there are plenty of web
Packit Service fb6fa5
resources that deal with autoconf and automake).</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>I try to debug my GTK+ application with gdb, but it
Packit Service fb6fa5
hangs my X server when I hit some breakpoint. Any
Packit Service fb6fa5
Idea? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>From Federico Mena Quintero:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para><quote>X is not locked up.  It is likely that you are hitting a
Packit Service fb6fa5
breakpoint inside a callback that is called from a place in Gtk that has
Packit Service fb6fa5
a mouse grab.</quote></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para><quote>Run your program with the <literal>--sync</literal>
Packit Service fb6fa5
option; it will make it easier to debug. Also, you may want to
Packit Service fb6fa5
use the console for running the debugger, and just let the
Packit Service fb6fa5
program run in another console with the X server.</quote></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Eric Mouw had another solution:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para><quote>An old terminal connected to an otherwise unused serial
Packit Service fb6fa5
port is also great for debugging X programs. Old vt100/vt220
Packit Service fb6fa5
terminals are dirt cheap but a bit hard to get (here in The
Packit Service fb6fa5
Netherlands, YMMV).</quote></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>
Packit Service fb6fa5
Another option is to run your application on Xnest. Xnest is an X server
Packit Service fb6fa5
which displays its root window in a regular window of another X server.  
Packit Service fb6fa5
A pointer grab on the Xnest display will not affect the GUI of your debugger
Packit Service fb6fa5
running on your regular X server.
Packit Service fb6fa5
<programlisting>
Packit Service fb6fa5
Xnest :1
Packit Service fb6fa5
twm -display :1
Packit Service fb6fa5
myapp --display=:1
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
</para>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
</chapter>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<chapter>
Packit Service fb6fa5
<title>Development with GTK+: general questions</title>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>What widgets are in GTK?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The GTK+ Tutorial lists the following widgets:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
  GtkObject
Packit Service fb6fa5
   +GtkData
Packit Service fb6fa5
   | +GtkAdjustment
Packit Service fb6fa5
   | `GtkTooltips
Packit Service fb6fa5
   `GtkWidget
Packit Service fb6fa5
     +GtkContainer
Packit Service fb6fa5
     | +GtkBin
Packit Service fb6fa5
     | | +GtkAlignment
Packit Service fb6fa5
     | | +GtkEventBox
Packit Service fb6fa5
     | | +GtkFrame
Packit Service fb6fa5
     | | | `GtkAspectFrame
Packit Service fb6fa5
     | | +GtkHandleBox
Packit Service fb6fa5
     | | +GtkItem
Packit Service fb6fa5
     | | | +GtkListItem
Packit Service fb6fa5
     | | | +GtkMenuItem
Packit Service fb6fa5
     | | | | `GtkCheckMenuItem
Packit Service fb6fa5
     | | | |   `GtkRadioMenuItem
Packit Service fb6fa5
     | | | `GtkTreeItem
Packit Service fb6fa5
     | | +GtkViewport
Packit Service fb6fa5
     | | `GtkWindow
Packit Service fb6fa5
     | |   +GtkColorSelectionDialog
Packit Service fb6fa5
     | |   +GtkDialog
Packit Service fb6fa5
     | |   | `GtkInputDialog
Packit Service fb6fa5
     | |   `GtkFileSelection
Packit Service fb6fa5
     | +GtkBox
Packit Service fb6fa5
     | | +GtkButtonBox
Packit Service fb6fa5
     | | | +GtkHButtonBox
Packit Service fb6fa5
     | | | `GtkVButtonBox
Packit Service fb6fa5
     | | +GtkHBox
Packit Service fb6fa5
     | | | +GtkCombo
Packit Service fb6fa5
     | | | `GtkStatusbar
Packit Service fb6fa5
     | | `GtkVBox
Packit Service fb6fa5
     | |   +GtkColorSelection
Packit Service fb6fa5
     | |   `GtkGammaCurve
Packit Service fb6fa5
     | +GtkButton
Packit Service fb6fa5
     | | +GtkOptionMenu
Packit Service fb6fa5
     | | `GtkToggleButton
Packit Service fb6fa5
     | |   `GtkCheckButton
Packit Service fb6fa5
     | |     `GtkRadioButton
Packit Service fb6fa5
     | +GtkCList
Packit Service fb6fa5
     |   `GtkCTree
Packit Service fb6fa5
     | +GtkFixed
Packit Service fb6fa5
     | +GtkList
Packit Service fb6fa5
     | +GtkMenuShell
Packit Service fb6fa5
     | | +GtkMenuBar
Packit Service fb6fa5
     | | `GtkMenu
Packit Service fb6fa5
     | +GtkNotebook
Packit Service fb6fa5
     | +GtkPaned
Packit Service fb6fa5
     | | +GtkHPaned
Packit Service fb6fa5
     | | `GtkVPaned
Packit Service fb6fa5
     | +GtkScrolledWindow
Packit Service fb6fa5
     | +GtkTable
Packit Service fb6fa5
     | +GtkToolbar
Packit Service fb6fa5
     | `GtkTree
Packit Service fb6fa5
     +GtkDrawingArea
Packit Service fb6fa5
     | `GtkCurve
Packit Service fb6fa5
     +GtkEditable
Packit Service fb6fa5
     | +GtkEntry
Packit Service fb6fa5
     | | `GtkSpinButton
Packit Service fb6fa5
     | `GtkText
Packit Service fb6fa5
     +GtkMisc
Packit Service fb6fa5
     | +GtkArrow
Packit Service fb6fa5
     | +GtkImage
Packit Service fb6fa5
     | +GtkLabel
Packit Service fb6fa5
     | | `GtkTipsQuery
Packit Service fb6fa5
     | `GtkPixmap
Packit Service fb6fa5
     +GtkPreview
Packit Service fb6fa5
     +GtkProgressBar
Packit Service fb6fa5
     +GtkRange
Packit Service fb6fa5
     | +GtkScale
Packit Service fb6fa5
     | | +GtkHScale
Packit Service fb6fa5
     | | `GtkVScale
Packit Service fb6fa5
     | `GtkScrollbar
Packit Service fb6fa5
     |   +GtkHScrollbar
Packit Service fb6fa5
     |   `GtkVScrollbar
Packit Service fb6fa5
     +GtkRuler
Packit Service fb6fa5
     | +GtkHRuler
Packit Service fb6fa5
     | `GtkVRuler
Packit Service fb6fa5
     `GtkSeparator
Packit Service fb6fa5
       +GtkHSeparator
Packit Service fb6fa5
       `GtkVSeparator
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Is GTK+ thread safe? How do I write multi-threaded GTK+
Packit Service fb6fa5
applications? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The GLib library can be used in a thread-safe mode by
Packit Service fb6fa5
calling g_thread_init() before making any other GLib
Packit Service fb6fa5
calls. In this mode GLib automatically locks all internal
Packit Service fb6fa5
data structures as needed.  This does not mean that two
Packit Service fb6fa5
threads can simultaneously access, for example, a single hash
Packit Service fb6fa5
table, but they can access two different hash tables
Packit Service fb6fa5
simultaneously. If two different threads need to access the
Packit Service fb6fa5
same hash table, the application is responsible for locking
Packit Service fb6fa5
itself.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>In order to make GDK thread aware, you also need to
Packit Service fb6fa5
call gdk_threads_init() in conjunction with the above call.
Packit Service fb6fa5
There is a single global
Packit Service fb6fa5
lock that you must acquire with gdk_threads_enter() before
Packit Service fb6fa5
making any GDK calls, and release with gdk_threads_leave()
Packit Service fb6fa5
afterwards throughout your code.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>A minimal main program for a threaded GTK+ application
Packit Service fb6fa5
looks like:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
int
Packit Service fb6fa5
main (int argc, char *argv[])
Packit Service fb6fa5
{
Packit Service fb6fa5
  GtkWidget *window;
Packit Service fb6fa5
Packit Service fb6fa5
  /* init threads */	
Packit Service fb6fa5
  g_thread_init(NULL);
Packit Service fb6fa5
  gdk_threads_init();
Packit Service fb6fa5
  
Packit Service fb6fa5
  /* init gtk */
Packit Service fb6fa5
  gtk_init(&argc, &argv);
Packit Service fb6fa5
Packit Service fb6fa5
  window = create_window();
Packit Service fb6fa5
  gtk_widget_show(window);
Packit Service fb6fa5
Packit Service fb6fa5
  gdk_threads_enter();
Packit Service fb6fa5
  gtk_main();
Packit Service fb6fa5
  gdk_threads_leave();
Packit Service fb6fa5
Packit Service fb6fa5
  return 0;
Packit Service fb6fa5
}
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Callbacks require a bit of attention. Callbacks from
Packit Service fb6fa5
GTK+ (signals) are made within the GTK+ lock. However
Packit Service fb6fa5
callbacks from GLib (timeouts, IO callbacks, and idle
Packit Service fb6fa5
functions) are made outside of the GTK+ lock. So, within a
Packit Service fb6fa5
signal handler you do not need to call gdk_threads_enter(),
Packit Service fb6fa5
but within the other types of callbacks, you do.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Erik Mouw contributed the following code example to
Packit Service fb6fa5
illustrate how to use threads within GTK+ programs.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
/*-------------------------------------------------------------------------
Packit Service fb6fa5
 * Filename:      gtk-thread.c
Packit Service fb6fa5
 * Version:       1.99.1
Packit Service fb6fa5
 * Copyright:     Copyright (C) 1999, Erik Mouw
Packit Service fb6fa5
 * Author:        Erik Mouw <J.A.K.Mouw@its.tudelft.nl>
Packit Service fb6fa5
 * Description:   GTK threads example.
Packit Service fb6fa5
 * Created at:    Sun Oct 17 21:27:09 1999
Packit Service fb6fa5
 * Modified by:   Owen Taylor <otaylor@gtk.org>
Packit Service fb6fa5
 * Modified at:   Wed May 28 10:43:00 2003
Packit Service fb6fa5
 *-----------------------------------------------------------------------*/
Packit Service fb6fa5
/*
Packit Service fb6fa5
 * Compile with:
Packit Service fb6fa5
 *
Packit Service fb6fa5
 * cc -o gtk-thread gtk-thread.c `pkg-config --cflags --libs gtk+-2.0 gthread-2.0`
Packit Service fb6fa5
 *
Packit Service fb6fa5
 * Thanks to Sebastian Wilhelmi for pointing out some bugs in earlier versions.
Packit Service fb6fa5
 *
Packit Service fb6fa5
 */
Packit Service fb6fa5
Packit Service fb6fa5
#include <unistd.h>
Packit Service fb6fa5
#include <gtk/gtk.h>
Packit Service fb6fa5
Packit Service fb6fa5
#define YES_IT_IS    (1)
Packit Service fb6fa5
#define NO_IT_IS_NOT (0)
Packit Service fb6fa5
Packit Service fb6fa5
typedef struct
Packit Service fb6fa5
{
Packit Service fb6fa5
  GtkWidget *label;
Packit Service fb6fa5
  int what;
Packit Service fb6fa5
} yes_or_no_args;
Packit Service fb6fa5
Packit Service fb6fa5
G_LOCK_DEFINE_STATIC (yes_or_no);
Packit Service fb6fa5
static volatile int yes_or_no = YES_IT_IS;
Packit Service fb6fa5
Packit Service fb6fa5
void destroy(GtkWidget *widget, gpointer data)
Packit Service fb6fa5
{
Packit Service fb6fa5
  gtk_main_quit();
Packit Service fb6fa5
}
Packit Service fb6fa5
Packit Service fb6fa5
void *argument_thread(void *args)
Packit Service fb6fa5
{
Packit Service fb6fa5
  yes_or_no_args *data = (yes_or_no_args *)args;
Packit Service fb6fa5
  gboolean say_something;
Packit Service fb6fa5
Packit Service fb6fa5
  for(;;)
Packit Service fb6fa5
    {
Packit Service fb6fa5
      /* sleep a while */
Packit Service fb6fa5
      sleep(g_random_int_range (1, 4));
Packit Service fb6fa5
Packit Service fb6fa5
      /* lock the yes_or_no_variable */
Packit Service fb6fa5
      G_LOCK(yes_or_no);
Packit Service fb6fa5
Packit Service fb6fa5
      /* do we have to say something? */
Packit Service fb6fa5
      say_something = (yes_or_no != data->what);
Packit Service fb6fa5
Packit Service fb6fa5
      if(say_something)
Packit Service fb6fa5
	{
Packit Service fb6fa5
	  /* set the variable */
Packit Service fb6fa5
	  yes_or_no = data->what;
Packit Service fb6fa5
	}
Packit Service fb6fa5
Packit Service fb6fa5
      /* Unlock the yes_or_no variable */
Packit Service fb6fa5
      G_UNLOCK(yes_or_no);
Packit Service fb6fa5
Packit Service fb6fa5
      if(say_something)
Packit Service fb6fa5
	{
Packit Service fb6fa5
	  /* get GTK thread lock */
Packit Service fb6fa5
	  gdk_threads_enter();
Packit Service fb6fa5
Packit Service fb6fa5
	  /* set label text */
Packit Service fb6fa5
	  if(data->what == YES_IT_IS)
Packit Service fb6fa5
	    gtk_label_set_text(GTK_LABEL(data->label), "O yes, it is!");
Packit Service fb6fa5
	  else
Packit Service fb6fa5
	    gtk_label_set_text(GTK_LABEL(data->label), "O no, it isn't!");
Packit Service fb6fa5
Packit Service fb6fa5
	  /* Make sure all X commands are sent to the X server; not strictly
Packit Service fb6fa5
	   * necessary here, but always a good idea when you do anything
Packit Service fb6fa5
	   * from a thread other than the one where the main loop is running.
Packit Service fb6fa5
	   */
Packit Service fb6fa5
	  gdk_flush ();
Packit Service fb6fa5
Packit Service fb6fa5
	  /* release GTK thread lock */
Packit Service fb6fa5
	  gdk_threads_leave();
Packit Service fb6fa5
	}
Packit Service fb6fa5
    }
Packit Service fb6fa5
Packit Service fb6fa5
  return NULL;
Packit Service fb6fa5
}
Packit Service fb6fa5
Packit Service fb6fa5
int main(int argc, char *argv[])
Packit Service fb6fa5
{
Packit Service fb6fa5
  GtkWidget *window;
Packit Service fb6fa5
  GtkWidget *label;
Packit Service fb6fa5
  GError *error = NULL;
Packit Service fb6fa5
  yes_or_no_args yes_args, no_args;
Packit Service fb6fa5
Packit Service fb6fa5
  /* init threads */
Packit Service fb6fa5
  g_thread_init(NULL);
Packit Service fb6fa5
  gdk_threads_init();
Packit Service fb6fa5
Packit Service fb6fa5
  /* init gtk */
Packit Service fb6fa5
  gtk_init(&argc, &argv);
Packit Service fb6fa5
Packit Service fb6fa5
  /* create a window */
Packit Service fb6fa5
  window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
Packit Service fb6fa5
Packit Service fb6fa5
  g_signal_connect(window, "destroy",
Packit Service fb6fa5
		   G_CALLBACK(destroy), NULL);
Packit Service fb6fa5
Packit Service fb6fa5
  gtk_container_set_border_width(GTK_CONTAINER (window), 10);
Packit Service fb6fa5
Packit Service fb6fa5
  /* create a label */
Packit Service fb6fa5
  label = gtk_label_new("And now for something completely different ...");
Packit Service fb6fa5
  gtk_container_add(GTK_CONTAINER(window), label);
Packit Service fb6fa5
Packit Service fb6fa5
  /* show everything */
Packit Service fb6fa5
  gtk_widget_show(label);
Packit Service fb6fa5
  gtk_widget_show (window);
Packit Service fb6fa5
Packit Service fb6fa5
  /* create the threads */
Packit Service fb6fa5
  yes_args.label = label;
Packit Service fb6fa5
  yes_args.what = YES_IT_IS;
Packit Service fb6fa5
  if (!g_thread_create(argument_thread, &yes_args, FALSE, &error))
Packit Service fb6fa5
    {
Packit Service fb6fa5
      g_printerr ("Failed to create YES thread: %s\n", error->message);
Packit Service fb6fa5
      return 1;
Packit Service fb6fa5
    }
Packit Service fb6fa5
Packit Service fb6fa5
  no_args.label = label;
Packit Service fb6fa5
  no_args.what = NO_IT_IS_NOT;
Packit Service fb6fa5
  if (!g_thread_create(argument_thread, &no_args, FALSE, &error))
Packit Service fb6fa5
    {
Packit Service fb6fa5
      g_printerr ("Failed to create NO thread: %s\n", error->message);
Packit Service fb6fa5
      return 1;
Packit Service fb6fa5
    }
Packit Service fb6fa5
Packit Service fb6fa5
  /* enter the GTK main loop */
Packit Service fb6fa5
  gdk_threads_enter();
Packit Service fb6fa5
  gtk_main();
Packit Service fb6fa5
  gdk_threads_leave();
Packit Service fb6fa5
Packit Service fb6fa5
  return 0;
Packit Service fb6fa5
}
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>I'm doing some stuff with GTK+ in a separate thread, and
Packit Service fb6fa5
properly locking with gdk_threads_enter/gdk_threads_leave()
Packit Service fb6fa5
but the display doesn't update properly. <emphasis>[GTK 2.x]</emphasis>
Packit Service fb6fa5
</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>For efficiency, the X window system batches up commands
Packit Service fb6fa5
and sends them to the X server in batches instead of sending
Packit Service fb6fa5
out immediately.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>In a non-multithreaded program, you don't have to worry about
Packit Service fb6fa5
this, since the first thing that happens when control returns
Packit Service fb6fa5
to the main loop is that any outstanding X requests are 
Packit Service fb6fa5
sent to the X server.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>However, if you are making GTK+ calls from a thread other
Packit Service fb6fa5
than the main loop, then GTK+ doesn't know when to send batched
Packit Service fb6fa5
commands out. For that reason, after making GTK+ calls 
Packit Service fb6fa5
in a separate thread, it is usually a good idea to call
Packit Service fb6fa5
gdk_flush() before gdk_thread_leave().</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Actually, gdk_flush() is more expensive than is necessary here,
Packit Service fb6fa5
since it waits for the X server to finish outstanding commands
Packit Service fb6fa5
as well; if performance is an issue, you may want to call
Packit Service fb6fa5
XFlush() directly:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
Packit Service fb6fa5
#include <gdk/gdkx.h>
Packit Service fb6fa5
Packit Service fb6fa5
void my_flush_commands (void)
Packit Service fb6fa5
{
Packit Service fb6fa5
  GdkDisplay *display = gdk_display_get_default ();
Packit Service fb6fa5
  XFlush (GDK_DISPLAY_XDISPLAY (display);
Packit Service fb6fa5
}
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>What's an easy way to run a function in the thread with
Packit Service fb6fa5
the main loop? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Sometimes the simplest way to set up a threaded program
Packit Service fb6fa5
is to make all the GTK+ calls in a single thread. In such
Packit Service fb6fa5
a program, you should still call g_threads_init(), but
Packit Service fb6fa5
don't need to call gdk_threads_init(), gkd_threads_enter(),
Packit Service fb6fa5
and gdk_threads_leave().</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>If you set your program up this way, how then do you get
Packit Service fb6fa5
the thread making GTK+ calls and running the main loop
Packit Service fb6fa5
to do something in response to another thread?</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>An easy way to do it is to take advantage of the fact that
Packit Service fb6fa5
the GLib main loop functions are all thread safe, and can
Packit Service fb6fa5
be called from any thread by adding an idle function
Packit Service fb6fa5
with g_idle_add(). The function provided will be called
Packit Service fb6fa5
at the next opportunity by the main thread. If you want
Packit Service fb6fa5
your function to take priority over event handling and
Packit Service fb6fa5
drawing, you can instead use g_idle_add_full() and pass
Packit Service fb6fa5
in a priority of G_PRIORITY_HIGH.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Why does this strange 'x io error' occur when I
Packit Service fb6fa5
<literal>fork()</literal> in my GTK+ app? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>This is not really a GTK+ problem, and the problem is
Packit Service fb6fa5
not related to <literal>fork()</literal> either. If the 'x io
Packit Service fb6fa5
error' occurs then you probably use the <literal>exit()</literal> function
Packit Service fb6fa5
in order to exit from the child process.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>When GDK opens an X display, it creates a socket file
Packit Service fb6fa5
descriptor. When you use the <literal>exit()</literal>
Packit Service fb6fa5
function, you implicitly close all the open file descriptors,
Packit Service fb6fa5
and the underlying X library really doesn't like this.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The right function to use here is
Packit Service fb6fa5
<literal>_exit()</literal>.</para> 
Packit Service fb6fa5
Packit Service fb6fa5
<para>Erik Mouw contributed the following code example to
Packit Service fb6fa5
illustrate handling fork() and exit().</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
/*-------------------------------------------------------------------------
Packit Service fb6fa5
 * Filename:      gtk-fork.c
Packit Service fb6fa5
 * Version:       0.99.2
Packit Service fb6fa5
 * Copyright:     Copyright (C) 1999, Erik Mouw
Packit Service fb6fa5
 * Author:        Erik Mouw <J.A.K.Mouw@its.tudelft.nl>
Packit Service fb6fa5
 * Description:   GTK+ fork example
Packit Service fb6fa5
 * Created at:    Thu Sep 23 21:37:55 1999
Packit Service fb6fa5
 * Modified by:   Erik Mouw <J.A.K.Mouw@its.tudelft.nl>
Packit Service fb6fa5
 * Modified at:   Thu Sep 23 22:39:39 1999
Packit Service fb6fa5
 * Modified by:   Tony Gale <gale@gtk.org>
Packit Service fb6fa5
 * Modified at:   Wed Jan 14 12:38:00 2004
Packit Service fb6fa5
 *-----------------------------------------------------------------------*/
Packit Service fb6fa5
/*
Packit Service fb6fa5
 * Compile with:
Packit Service fb6fa5
 *
Packit Service fb6fa5
 * cc -o gtk-fork gtk-fork.c `pkg-config gtk+-2.0 --cflags --libs`
Packit Service fb6fa5
 *
Packit Service fb6fa5
 */
Packit Service fb6fa5
Packit Service fb6fa5
#include <stdio.h>
Packit Service fb6fa5
#include <stdlib.h>
Packit Service fb6fa5
#include <signal.h>
Packit Service fb6fa5
#include <sys/types.h>
Packit Service fb6fa5
#include <sys/wait.h>
Packit Service fb6fa5
#include <unistd.h>
Packit Service fb6fa5
#include <gtk/gtk.h>
Packit Service fb6fa5
Packit Service fb6fa5
void sigchld_handler(int num)
Packit Service fb6fa5
{
Packit Service fb6fa5
  sigset_t set, oldset;
Packit Service fb6fa5
  pid_t pid;
Packit Service fb6fa5
  int status, exitstatus;
Packit Service fb6fa5
Packit Service fb6fa5
  /* block other incoming SIGCHLD signals */
Packit Service fb6fa5
  sigemptyset(&set);
Packit Service fb6fa5
  sigaddset(&set, SIGCHLD);
Packit Service fb6fa5
  sigprocmask(SIG_BLOCK, &set, &oldset);
Packit Service fb6fa5
Packit Service fb6fa5
  /* wait for child */
Packit Service fb6fa5
  while((pid = waitpid((pid_t)-1, &status, WNOHANG)) > 0)
Packit Service fb6fa5
    {
Packit Service fb6fa5
      if(WIFEXITED(status))
Packit Service fb6fa5
	{
Packit Service fb6fa5
	  exitstatus = WEXITSTATUS(status);
Packit Service fb6fa5
Packit Service fb6fa5
	  fprintf(stderr, 
Packit Service fb6fa5
		  "Parent: child exited, pid = %d, exit status = %d\n", 
Packit Service fb6fa5
		  (int)pid, exitstatus);
Packit Service fb6fa5
	}
Packit Service fb6fa5
      else if(WIFSIGNALED(status))
Packit Service fb6fa5
	{
Packit Service fb6fa5
	  exitstatus = WTERMSIG(status);
Packit Service fb6fa5
Packit Service fb6fa5
	  fprintf(stderr,
Packit Service fb6fa5
		  "Parent: child terminated by signal %d, pid = %d\n",
Packit Service fb6fa5
		  exitstatus, (int)pid);
Packit Service fb6fa5
	}
Packit Service fb6fa5
      else if(WIFSTOPPED(status))
Packit Service fb6fa5
	{
Packit Service fb6fa5
	  exitstatus = WSTOPSIG(status);
Packit Service fb6fa5
Packit Service fb6fa5
	  fprintf(stderr,
Packit Service fb6fa5
		  "Parent: child stopped by signal %d, pid = %d\n",
Packit Service fb6fa5
		  exitstatus, (int)pid);
Packit Service fb6fa5
	}
Packit Service fb6fa5
      else
Packit Service fb6fa5
	{
Packit Service fb6fa5
	  fprintf(stderr,
Packit Service fb6fa5
		  "Parent: child exited magically, pid = %d\n",
Packit Service fb6fa5
		  (int)pid);
Packit Service fb6fa5
	}
Packit Service fb6fa5
    }
Packit Service fb6fa5
Packit Service fb6fa5
  /* re-install the signal handler (some systems need this) */
Packit Service fb6fa5
  signal(SIGCHLD, sigchld_handler);
Packit Service fb6fa5
  
Packit Service fb6fa5
  /* and unblock it */
Packit Service fb6fa5
  sigemptyset(&set);
Packit Service fb6fa5
  sigaddset(&set, SIGCHLD);
Packit Service fb6fa5
  sigprocmask(SIG_UNBLOCK, &set, &oldset);
Packit Service fb6fa5
}
Packit Service fb6fa5
Packit Service fb6fa5
gint delete_event(GtkWidget *widget, GdkEvent *event, gpointer data)
Packit Service fb6fa5
{
Packit Service fb6fa5
  return(FALSE);
Packit Service fb6fa5
}
Packit Service fb6fa5
Packit Service fb6fa5
void destroy(GtkWidget *widget, gpointer data)
Packit Service fb6fa5
{
Packit Service fb6fa5
  gtk_main_quit();
Packit Service fb6fa5
}
Packit Service fb6fa5
Packit Service fb6fa5
void fork_me(GtkWidget *widget, gpointer data)
Packit Service fb6fa5
{
Packit Service fb6fa5
  pid_t pid;
Packit Service fb6fa5
Packit Service fb6fa5
  pid = fork();
Packit Service fb6fa5
Packit Service fb6fa5
  if(pid == -1)
Packit Service fb6fa5
    {
Packit Service fb6fa5
      /* ouch, fork() failed */
Packit Service fb6fa5
      perror("fork");
Packit Service fb6fa5
      exit(-1);
Packit Service fb6fa5
    }
Packit Service fb6fa5
  else if(pid == 0)
Packit Service fb6fa5
    {
Packit Service fb6fa5
      /* child */
Packit Service fb6fa5
      fprintf(stderr, "Child: pid = %d\n", (int)getpid());
Packit Service fb6fa5
Packit Service fb6fa5
      execlp("ls", "ls", "-CF", "/", NULL);
Packit Service fb6fa5
      
Packit Service fb6fa5
      /* if exec() returns, there is something wrong */
Packit Service fb6fa5
      perror("execlp");
Packit Service fb6fa5
Packit Service fb6fa5
      /* exit child. note the use of _exit() instead of exit() */
Packit Service fb6fa5
      _exit(-1);
Packit Service fb6fa5
    }
Packit Service fb6fa5
  else
Packit Service fb6fa5
    {
Packit Service fb6fa5
      /* parent */
Packit Service fb6fa5
      fprintf(stderr, "Parent: forked a child with pid = %d\n", (int)pid);
Packit Service fb6fa5
    }
Packit Service fb6fa5
}
Packit Service fb6fa5
Packit Service fb6fa5
int main(int argc, char *argv[])
Packit Service fb6fa5
{
Packit Service fb6fa5
  GtkWidget *window;
Packit Service fb6fa5
  GtkWidget *button;
Packit Service fb6fa5
Packit Service fb6fa5
  gtk_init(&argc, &argv);
Packit Service fb6fa5
Packit Service fb6fa5
  /* the basic stuff: make a window and set callbacks for destroy and
Packit Service fb6fa5
   * delete events 
Packit Service fb6fa5
   */
Packit Service fb6fa5
  window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
Packit Service fb6fa5
Packit Service fb6fa5
  g_signal_connect(G_OBJECT (window), "delete_event",
Packit Service fb6fa5
		     G_CALLBACK(delete_event), NULL);
Packit Service fb6fa5
          
Packit Service fb6fa5
  g_signal_connect(G_OBJECT (window), "destroy",
Packit Service fb6fa5
		     G_CALLBACK(destroy), NULL);
Packit Service fb6fa5
Packit Service fb6fa5
#if (GTK_MAJOR_VERSION == 1) && (GTK_MINOR_VERSION == 0)
Packit Service fb6fa5
  gtk_container_border_width(GTK_CONTAINER (window), 10);
Packit Service fb6fa5
#else  
Packit Service fb6fa5
  gtk_container_set_border_width(GTK_CONTAINER (window), 10);
Packit Service fb6fa5
#endif
Packit Service fb6fa5
Packit Service fb6fa5
  /* add a button to do something useful */
Packit Service fb6fa5
  button = gtk_button_new_with_label("Fork me!");
Packit Service fb6fa5
          
Packit Service fb6fa5
  g_signal_connect(G_OBJECT (button), "clicked",
Packit Service fb6fa5
		     G_CALLBACK(fork_me), NULL);
Packit Service fb6fa5
Packit Service fb6fa5
  gtk_container_add(GTK_CONTAINER(window), button);
Packit Service fb6fa5
          
Packit Service fb6fa5
  /* show everything */
Packit Service fb6fa5
  gtk_widget_show (button);
Packit Service fb6fa5
  gtk_widget_show (window);
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
  /* install a signal handler for SIGCHLD signals */
Packit Service fb6fa5
  signal(SIGCHLD, sigchld_handler);
Packit Service fb6fa5
Packit Service fb6fa5
  
Packit Service fb6fa5
  /* main loop */
Packit Service fb6fa5
  gtk_main ();
Packit Service fb6fa5
Packit Service fb6fa5
  exit(0);         
Packit Service fb6fa5
}
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Why don't the contents of a button move when the button
Packit Service fb6fa5
is pressed? Here's a patch to make it work that way... <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>From: Peter Mattis</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para><quote>The reason buttons don't move their child down and to
Packit Service fb6fa5
the right when they are depressed is because I don't think
Packit Service fb6fa5
that's what is happening visually. My view of buttons is
Packit Service fb6fa5
that you are looking at them straight on. That is, the user
Packit Service fb6fa5
interface lies in a plane and you're above it looking
Packit Service fb6fa5
straight at it. When a button gets pressed it moves directly
Packit Service fb6fa5
away from you. To be absolutely correct I guess the child
Packit Service fb6fa5
should actually shrink a tiny amount. But I don't see why
Packit Service fb6fa5
the child should shift down and to the left. Remember, the
Packit Service fb6fa5
child is supposed to be attached to the buttons surface. Its
Packit Service fb6fa5
not good for it to appear like the child is slipping on the
Packit Service fb6fa5
surface of the button.</quote></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para><quote>On a more practical note, I did implement this at one point
Packit Service fb6fa5
and determined it didn't look good and removed it.</quote></para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I identifiy a widgets top level window or other
Packit Service fb6fa5
ancestor? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>There are a couple of ways to find the top level parent
Packit Service fb6fa5
of a widget. The easiest way is to call the
Packit Service fb6fa5
<literal>gtk_widget_get_toplevel()</literal> function that
Packit Service fb6fa5
returns a pointer to a GtkWidget that is the top level
Packit Service fb6fa5
window.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>A more complicated way to do this (but less limited, as
Packit Service fb6fa5
it allows the user to get the closest ancestor of a known type) is to use
Packit Service fb6fa5
<literal>gtk_widget_get_ancestor()</literal> as in:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
      GtkWidget       *widget;
Packit Service fb6fa5
      widget = gtk_widget_get_ancestor(w, GTK_TYPE_WINDOW);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Since virtually all the GTK_TYPEs can be used as the
Packit Service fb6fa5
second parameter of this function, you can get any parent
Packit Service fb6fa5
widget of a particular widget. Suppose you have an hbox which
Packit Service fb6fa5
contains a vbox, which in turn contains some other atomic
Packit Service fb6fa5
widget (entry, label, etc. To find the master hbox using the
Packit Service fb6fa5
<literal>entry</literal> widget simply use:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
      GtkWidget       *hbox;
Packit Service fb6fa5
      hbox = gtk_widget_get_ancestor(w, GTK_TYPE_HBOX);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>You can also follow the a widgets ancestry by using the function
Packit Service fb6fa5
<literal>gtk_widget_get_parent()</literal> that returns a pointer
Packit Service fb6fa5
to a widgets parent widget.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I get the Window ID of a GtkWindow? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The actual Gdk/X window will be created when the widget
Packit Service fb6fa5
gets realized. You can get the Window ID with:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
#include <gdk/gdkx.h>
Packit Service fb6fa5
Packit Service fb6fa5
Window xwin = GDK_WINDOW_XWINDOW (GTK_WIDGET (my_window)->window);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I catch a double click event? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Tim Janik wrote to gtk-list (slightly modified):</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Define a signal handler:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
gint
Packit Service fb6fa5
signal_handler_event(GtkWidget *widget, GdkEventButton *event, gpointer func_data)
Packit Service fb6fa5
{
Packit Service fb6fa5
  if (GTK_IS_BUTTON(widget) &&
Packit Service fb6fa5
       (event->type==GDK_2BUTTON_PRESS ||
Packit Service fb6fa5
        event->type==GDK_3BUTTON_PRESS) ) {
Packit Service fb6fa5
    printf("I feel %s clicked with button %d\n",
Packit Service fb6fa5
           event->type==GDK_2BUTTON_PRESS ? "double" : "triple",
Packit Service fb6fa5
           event->button);
Packit Service fb6fa5
  }
Packit Service fb6fa5
Packit Service fb6fa5
  return FALSE;
Packit Service fb6fa5
}</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>And connect the handler to your object:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
{
Packit Service fb6fa5
  /* button init stuff */     
Packit Service fb6fa5
Packit Service fb6fa5
  g_signal_connect(G_OBJECT(button),
Packit Service fb6fa5
                     "button_press_event",
Packit Service fb6fa5
                     G_CALLBACK(signal_handler_event),
Packit Service fb6fa5
                     NULL);
Packit Service fb6fa5
Packit Service fb6fa5
  /* and/or */
Packit Service fb6fa5
Packit Service fb6fa5
  g_signal_connect(G_OBJECT(button),
Packit Service fb6fa5
                     "button_release_event",
Packit Service fb6fa5
                     G_CALLBACK(signal_handler_event),
Packit Service fb6fa5
                     NULL);
Packit Service fb6fa5
Packit Service fb6fa5
  /* something else */
Packit Service fb6fa5
}
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>and, Owen Taylor wrote:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para><quote>Note that a single button press will be received
Packit Service fb6fa5
beforehand, and if you are doing this for a button, you will
Packit Service fb6fa5
therefore also get a "clicked" signal for the button. (This
Packit Service fb6fa5
is going to be true for any toolkit, since computers aren't
Packit Service fb6fa5
good at reading one's mind.)</quote></para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>By the way, what are the differences between signals
Packit Service fb6fa5
and events?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>First of all, Havoc Pennington gives a rather complete
Packit Service fb6fa5
description of the differences between events and signals in
Packit Service fb6fa5
his free book (two chapters can be found at 
Packit Service fb6fa5
url="http://www106.pair.com/rhp/sample_chapters.html">
Packit Service fb6fa5
http://www106.pair.com/rhp/sample_chapters.html</ulink>).</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Moreover, Havoc posted this to the <literal>gtk-list</literal>
Packit Service fb6fa5
<quote>Events are a stream of messages received from the X
Packit Service fb6fa5
server. They drive the Gtk main loop; which more or less
Packit Service fb6fa5
amounts to "wait for events, process them" (not exactly, it
Packit Service fb6fa5
is really more general than that and can wait on many
Packit Service fb6fa5
different input streams at once). Events are a Gdk/Xlib
Packit Service fb6fa5
concept.</quote></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para><quote>Signals are a feature of GtkObject and its subclasses. They
Packit Service fb6fa5
have nothing to do with any input stream; really a signal is just a way
Packit Service fb6fa5
to keep a list of callbacks around and invoke them ("emit" the
Packit Service fb6fa5
signal). There are lots of details and extra features of
Packit Service fb6fa5
course. Signals are emitted by object instances, and are entirely
Packit Service fb6fa5
unrelated to the Gtk main loop.  Conventionally, signals are emitted
Packit Service fb6fa5
"when something changes" about the object emitting the
Packit Service fb6fa5
signal.</quote></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para><quote>Signals and events only come together because GtkWidget
Packit Service fb6fa5
happens to emit signals when it gets events. This is purely a
Packit Service fb6fa5
convenience, so you can connect callbacks to be invoked when a
Packit Service fb6fa5
particular widget receives a particular event. There is nothing about
Packit Service fb6fa5
this that makes signals and events inherently related concepts, any more
Packit Service fb6fa5
than emitting a signal when you click a button makes button clicking and
Packit Service fb6fa5
signals related concepts.</quote></para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Data I pass to the <literal>delete_event</literal> (or other event)
Packit Service fb6fa5
handler gets corrupted.</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>All event handlers take an additional argument which
Packit Service fb6fa5
contains information about the event that triggered the
Packit Service fb6fa5
handler. So, a <literal>delete_event</literal> handler must
Packit Service fb6fa5
be declared as:</para>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
gint delete_event_handler (GtkWidget   *widget,
Packit Service fb6fa5
                           GdkEventAny *event,
Packit Service fb6fa5
                           gpointer     data);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>I have my signal connected to the the (whatever) event,
Packit Service fb6fa5
but it seems I don't catch it. What's wrong?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>There is some special initialisation to do in order to
Packit Service fb6fa5
catch some particular events. In fact, you must set the
Packit Service fb6fa5
correct event mask bit of your widget before getting some
Packit Service fb6fa5
particular events.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>For example,</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
  gtk_widget_add_events(window, GDK_KEY_RELEASE_MASK);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>lets you catch the key release events. If you want to
Packit Service fb6fa5
catch every events, simply us the GDK_ALL_EVENTS_MASK event
Packit Service fb6fa5
mask.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>All the event masks are defined in the
Packit Service fb6fa5
<filename>gdktypes.h</filename> file.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>I need to add a new signal to a GTK+ widget. Any
Packit Service fb6fa5
idea?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>If the signal you want to add may be beneficial for
Packit Service fb6fa5
other GTK+ users, you may want to submit a patch that
Packit Service fb6fa5
presents your changes. Check the tutorial for more
Packit Service fb6fa5
information about adding signals to a widget class.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>If you don't think it is the case or if your patch is
Packit Service fb6fa5
not applied you'll have to use the
Packit Service fb6fa5
<literal>gtk_object_class_user_signal_new</literal>
Packit Service fb6fa5
function. <literal>gtk_object_class_user_signal_new</literal> allows you
Packit Service fb6fa5
to add a new signal to a predefined GTK+ widget without any
Packit Service fb6fa5
modification of the GTK+ source code. The new signal can be
Packit Service fb6fa5
emited with <literal>gtk_signal_emit</literal> and can be
Packit Service fb6fa5
handled in the same way as other signals.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Tim Janik posted this code snippet:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
static guint signal_user_action = 0;
Packit Service fb6fa5
Packit Service fb6fa5
signal_user_action =
Packit Service fb6fa5
  gtk_object_class_user_signal_new (gtk_type_class (GTK_TYPE_WIDGET),
Packit Service fb6fa5
                    "user_action",
Packit Service fb6fa5
                    GTK_RUN_LAST | GTK_RUN_ACTION,
Packit Service fb6fa5
                    gtk_marshal_NONE__POINTER,
Packit Service fb6fa5
                    GTK_TYPE_NONE, 1,
Packit Service fb6fa5
                    GTK_TYPE_POINTER);
Packit Service fb6fa5
Packit Service fb6fa5
void
Packit Service fb6fa5
gtk_widget_user_action (GtkWidget *widget,
Packit Service fb6fa5
                        gpointer   act_data)
Packit Service fb6fa5
{
Packit Service fb6fa5
  g_return_if_fail (GTK_IS_WIDGET (widget));
Packit Service fb6fa5
Packit Service fb6fa5
  gtk_signal_emit (GTK_OBJECT (widget), signal_user_action, act_data);
Packit Service fb6fa5
}
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>If you want your new signal to have more than the
Packit Service fb6fa5
classical gpointer parameter, you'll have to play with GTK+
Packit Service fb6fa5
marshallers.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Is it possible to get some text displayed which is
Packit Service fb6fa5
truncated to fit inside its allocation?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>GTK's behavior (no clipping) is a consequence of its
Packit Service fb6fa5
attempts to conserve X resources. Label widgets (among
Packit Service fb6fa5
others) don't get their own X window - they just draw their
Packit Service fb6fa5
contents on their parent's window. While it might be possible
Packit Service fb6fa5
to have clipping occur by setting the clip mask before
Packit Service fb6fa5
drawing the text, this would probably cause a substantial
Packit Service fb6fa5
performance penalty.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Its possible that, in the long term, the best solution
Packit Service fb6fa5
to such problems might be just to change gtk to give labels X
Packit Service fb6fa5
windows. A short term workaround is to put the label widget
Packit Service fb6fa5
inside another widget that does get its own window - one
Packit Service fb6fa5
possible candidate would be the viewport widget.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
viewport = gtk_viewport (NULL, NULL);
Packit Service fb6fa5
gtk_widget_set_usize (viewport, 50, 25);
Packit Service fb6fa5
gtk_viewport_set_shadow_type (GTK_VIEWPORT(viewport), GTK_SHADOW_NONE);
Packit Service fb6fa5
gtk_widget_show(viewport);
Packit Service fb6fa5
Packit Service fb6fa5
label = gtk_label ("a really long label that won't fit");
Packit Service fb6fa5
gtk_container_add (GTK_CONTAINER(viewport), label);
Packit Service fb6fa5
gtk_widget_show (label);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>If you were doing this for a bunch of widgets, you might
Packit Service fb6fa5
want to copy gtkviewport.c and strip out the adjustment and
Packit Service fb6fa5
shadow functionality (perhaps you could call it
Packit Service fb6fa5
GtkClipper).</para>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I make my window modal? / How do I make a single
Packit Service fb6fa5
window active?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>After you create your window, do
Packit Service fb6fa5
<literal>gtk_grab_add(my_window)</literal>. And after closing the window
Packit Service fb6fa5
do <literal>gtk_grab_remove(my_window)</literal>.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Why doesn't my widget (e.g. progressbar)
Packit Service fb6fa5
update? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>You are probably doing all the changes within a function without
Packit Service fb6fa5
returning control to <literal>gtk_main()</literal>. This may
Packit Service fb6fa5
be the case if you do some lengthy calculation in your
Packit Service fb6fa5
code. Most drawing updates are only placed on a queue, which
Packit Service fb6fa5
is processed within <literal>gtk_main()</literal>. You can force the
Packit Service fb6fa5
drawing queue to be processed using something like:</para>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
while (g_main_context_iteration(NULL, FALSE));
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>inside you're function that changes the widget.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>What the above snippet does is run all pending events
Packit Service fb6fa5
and high priority idle functions, then return immediately
Packit Service fb6fa5
(the drawing is done in a high priority idle function).</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I attach data to some GTK+ object/widget?
Packit Service fb6fa5
<emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>First of all, the attached data is stored in the
Packit Service fb6fa5
object_data field of a GtkObject. The type of this field is
Packit Service fb6fa5
GData, which is defined in glib.h.  So you should read the
Packit Service fb6fa5
gdataset.c file in your glib source directory very
Packit Service fb6fa5
carefully.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>There are two (easy) ways to attach some data to a gtk
Packit Service fb6fa5
object.  Using <literal>g_object_set_data()</literal> and
Packit Service fb6fa5
<literal>g_object_get_data()</literal> seems to be the most
Packit Service fb6fa5
common way to do this, as it provides a powerful interface to
Packit Service fb6fa5
connect objects and data.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
void g_object_set_data(GObject *object, const gchar *key, gpointer data);
Packit Service fb6fa5
Packit Service fb6fa5
gpointer g_object_get_data(GObject *object, const gchar *key);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Since a short example is better than any lengthy speech:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
struct my_struct	p1,p2,*result;
Packit Service fb6fa5
GtkWidget		*w;
Packit Service fb6fa5
Packit Service fb6fa5
g_object_set_data(G_OBJECT(w),"p1 data",(gpointer)&p1);
Packit Service fb6fa5
g_object_set_data(G_OBJECT(w),"p2 data",(gpointer)&p2);
Packit Service fb6fa5
Packit Service fb6fa5
result = g_object_get_data(G_OBJECT(w),"p1 data");
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The <literal>gtk_object_set_user_data()</literal> and
Packit Service fb6fa5
<literal>gtk_object_get_user_data()</literal> functions does
Packit Service fb6fa5
exactly the same thing as the functions above, but does not
Packit Service fb6fa5
let you specify the "key" parameter.Instead, it uses a
Packit Service fb6fa5
standard "user_data" key. Note that the use of these functions
Packit Service fb6fa5
is deprecated in 1.2. They only provide a compatibility mode
Packit Service fb6fa5
with some old gtk packages.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I remove the data I have attached to an
Packit Service fb6fa5
object?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>When attaching the data to the object, you can use the
Packit Service fb6fa5
<literal>gtk_object_set_data_full()</literal> function. The three
Packit Service fb6fa5
first arguments of the function are the same as in
Packit Service fb6fa5
<literal>gtk_object_set_data()</literal>. The fourth one is a
Packit Service fb6fa5
pointer to a callback function which is called when the data
Packit Service fb6fa5
is destroyed. The data is destroyed when you:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<itemizedlist>
Packit Service fb6fa5
<listitem><simpara> destroy the object</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> replace the data with a new one (with
Packit Service fb6fa5
the same key)</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> replace the data with NULL (with the
Packit Service fb6fa5
same key)</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
</itemizedlist>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I reparent a widget?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The normal way to reparent (ie change the owner) of a
Packit Service fb6fa5
widget should be to use the function:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
void gtk_widget_reparent (GtkWidget *widget, 
Packit Service fb6fa5
                          GtkWidget *new_parent)
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>But this is only a "should be" since this function does
Packit Service fb6fa5
not correctly do its job on some specific widgets. The main
Packit Service fb6fa5
goal of gtk_widget_reparent() is to avoid unrealizing widget
Packit Service fb6fa5
if both widget and new_parent are realized (in this case,
Packit Service fb6fa5
widget->window is successfully reparented). The problem here
Packit Service fb6fa5
is that some widgets in the GTK+ hierarchy have multiple
Packit Service fb6fa5
attached X subwindows and this is notably the case for the
Packit Service fb6fa5
GtkSpinButton widget. For those, gtk_widget_reparent() will
Packit Service fb6fa5
fail by leaving an unrealized child window where it should
Packit Service fb6fa5
not.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>To avoid this problem, simply use the following code
Packit Service fb6fa5
snippet:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
     g_object_ref(widget);
Packit Service fb6fa5
     gtk_container_remove(GTK_CONTAINER(old_parent), widget);
Packit Service fb6fa5
     gtk_container_add(GTK_CONTAINER(new_parent), widget);
Packit Service fb6fa5
     g_object_unref(widget);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How could I get any widgets position?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>As Tim Janik pointed out, there are different cases, and
Packit Service fb6fa5
each case requires a different solution.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<itemizedlist>
Packit Service fb6fa5
<listitem><simpara> If you want the position of a widget
Packit Service fb6fa5
relative to its parent, you should use
Packit Service fb6fa5
<literal>widget->allocation.x</literal> and
Packit Service fb6fa5
<literal>widget->allocation.y</literal>.</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> If you want the position of a window
Packit Service fb6fa5
relative to the X root window, you should use
Packit Service fb6fa5
<literal>gdk_window_get_geometry()</literal>
Packit Service fb6fa5
<literal>gdk_window_get_position()</literal> or
Packit Service fb6fa5
<literal>gdk_window_get_origin()</literal>.</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> If you want to get the position of the
Packit Service fb6fa5
window (including the WM decorations), you should use
Packit Service fb6fa5
<literal>gdk_window_get_root_origin()</literal>.</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara> Last but not least, if you want to get a Window
Packit Service fb6fa5
Manager frame position, you should use
Packit Service fb6fa5
<literal>gdk_window_get_deskrelative_origin()</literal>.</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
</itemizedlist>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Your choice of Window Manager will have an effect of the
Packit Service fb6fa5
results of the above functions. You should keep this in mind
Packit Service fb6fa5
when writing your application. This is dependant upon how the
Packit Service fb6fa5
Window Managers manage the decorations that they add around
Packit Service fb6fa5
windows.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I set the size of a widget/window? How do I
Packit Service fb6fa5
prevent the user resizing my window? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The <literal>gtk_widget_set_size_request()</literal> function
Packit Service fb6fa5
is used to set the size of a widget to a specific size.
Packit Service fb6fa5
Packit Service fb6fa5
The function
Packit Service fb6fa5
<literal>gtk_window_set_resizable()</literal> function sets whether
Packit Service fb6fa5
the user can resize a window, which they can by default. The
Packit Service fb6fa5
definition of these functions are:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
void gtk_widget_set_size_request (GtkWidget *widget,
Packit Service fb6fa5
                                  gint       width,
Packit Service fb6fa5
                                  gint       height);
Packit Service fb6fa5
Packit Service fb6fa5
void gtk_window_set_resizable (GtkWindow *window,
Packit Service fb6fa5
                               gboolean   resizable);
Packit Service fb6fa5
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I add a popup menu to my GTK+ application?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The <literal>menu</literal> example in the examples/menu
Packit Service fb6fa5
directory of the GTK+ distribution implements a popup menu
Packit Service fb6fa5
with this technique:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
static gint button_press (GtkWidget *widget, GdkEvent *event)
Packit Service fb6fa5
{
Packit Service fb6fa5
Packit Service fb6fa5
    if (event->type == GDK_BUTTON_PRESS) {
Packit Service fb6fa5
        GdkEventButton *bevent = (GdkEventButton *) event; 
Packit Service fb6fa5
        gtk_menu_popup (GTK_MENU(widget), NULL, NULL, NULL, NULL,
Packit Service fb6fa5
                        bevent->button, bevent->time);
Packit Service fb6fa5
        /* Tell calling code that we have handled this event; the buck
Packit Service fb6fa5
         * stops here. */
Packit Service fb6fa5
        return TRUE;
Packit Service fb6fa5
    }
Packit Service fb6fa5
Packit Service fb6fa5
    /* Tell calling code that we have not handled this event; pass it on. */
Packit Service fb6fa5
    return FALSE;
Packit Service fb6fa5
}
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I disable or enable a widget, such as a
Packit Service fb6fa5
button?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>To disable (or to enable) a widget, use the
Packit Service fb6fa5
<literal>gtk_widget_set_sensitive()</literal> function. The
Packit Service fb6fa5
first parameter is you widget pointer. The second parameter is
Packit Service fb6fa5
a boolean value: when this value is TRUE, the widget is
Packit Service fb6fa5
enabled.</para>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Shouldn't the text argument in the gtk_clist_*
Packit Service fb6fa5
functions be declared const?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>For example:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
gint gtk_clist_prepend (GtkCList *clist,
Packit Service fb6fa5
                        gchar    *text[]);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Answer: No, while a type "gchar*" (pointer to char) can
Packit Service fb6fa5
automatically be cast into "const gchar*" (pointer to const
Packit Service fb6fa5
char), this does not apply for "gchar *[]" (array of an
Packit Service fb6fa5
unspecified number of pointers to char) into "const gchar *[]"
Packit Service fb6fa5
(array of an unspecified number of pointers to const char).</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The type qualifier "const" may be subject to automatic
Packit Service fb6fa5
casting, but in the array case, it is not the array itself
Packit Service fb6fa5
that needs the (const) qualified cast, but its members, thus
Packit Service fb6fa5
changing the whole type.</para>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I render pixels (image data) to the
Packit Service fb6fa5
screen?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>There are several ways to approach this. The simplest
Packit Service fb6fa5
way is to use GdkRGB, see gdk/gdkrgb.h. You create an RGB
Packit Service fb6fa5
buffer, render to your RGB buffer, then use GdkRGB routines to
Packit Service fb6fa5
copy your RGB buffer to a drawing area or custom widget. The
Packit Service fb6fa5
book "GTK+/Gnome Application Development" gives some details;
Packit Service fb6fa5
GdkRGB is also documented in the GTK+ reference
Packit Service fb6fa5
documentation.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>If you're writing a game or other graphics-intensive
Packit Service fb6fa5
application, you might consider a more elaborate
Packit Service fb6fa5
solution. OpenGL is the graphics standard that will let you
Packit Service fb6fa5
access hardware accelaration in future versions of XFree86; so
Packit Service fb6fa5
for maximum speed, you probably want to use OpenGL. A
Packit Service fb6fa5
GtkGLArea widget is available for using OpenGL with GTK+ (but
Packit Service fb6fa5
GtkGLArea does not come with GTK+ itself). There are also
Packit Service fb6fa5
several open source game libraries, such as ClanLib and Loki's
Packit Service fb6fa5
Simple DirectMedia Layer library (SDL).</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>You do NOT want to use
Packit Service fb6fa5
<literal>gdk_draw_point()</literal>, that will be extremely
Packit Service fb6fa5
slow.</para>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I create a pixmap without having my window being
Packit Service fb6fa5
realized/shown?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Functions such as
Packit Service fb6fa5
<literal>gdk_pixmap_create_from_xpm()</literal> require a
Packit Service fb6fa5
valid window as a parameter. During the initialisation phase
Packit Service fb6fa5
of an application, a valid window may not be available without
Packit Service fb6fa5
showing a window, which may be inappropriate. In order to
Packit Service fb6fa5
avoid this, a function such as
Packit Service fb6fa5
<literal>gdk_pixmap_colormap_create_from_xpm</literal> can be
Packit Service fb6fa5
used, as in:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
  char *pixfile = "foo.xpm";
Packit Service fb6fa5
  GtkWidget *top, *box, *pixw;
Packit Service fb6fa5
  GdkPixmap *pixmap, *pixmap_mask;
Packit Service fb6fa5
Packit Service fb6fa5
  top = gtk_window_new (GKT_WINDOW_TOPLEVEL);
Packit Service fb6fa5
  box = gtk_hbox_new (FALSE, 4);
Packit Service fb6fa5
  gtk_conainer_add (GTK_CONTAINER(top), box);
Packit Service fb6fa5
 
Packit Service fb6fa5
  pixmap = gdk_pixmap_colormap_create_from_xpm (
Packit Service fb6fa5
               NULL, gtk_widget_get_colormap(top),
Packit Service fb6fa5
               &pixmap_mask, NULL, pixfile);
Packit Service fb6fa5
  pixw = gtk_pixmap_new (pixmap, pixmap_mask);
Packit Service fb6fa5
  g_object_unref (pixmap);
Packit Service fb6fa5
  g_object_unref (pixmap_mask);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I do drag-and-drop?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>GTK+ has a high level set of functions for doing inter-process
Packit Service fb6fa5
communication via the drag-and-drop system. GTK+ can perform
Packit Service fb6fa5
drag-and-drop on top of the low level Xdnd and Motif drag-and-drop
Packit Service fb6fa5
protocols.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The documentation on GTK+ drag-and-drop isn't complete, but there
Packit Service fb6fa5
is some information in the 
Packit Service fb6fa5
url="http://www.gtk.org/tutorial/">Tutorial</ulink>. You should also
Packit Service fb6fa5
look at the drag-and-drop example code that is part of the GTK+ source
Packit Service fb6fa5
distribution, in the file <filename>gtk/testdnd.c</filename>.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Why does GTK+/GLib leak memory?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>It doesn't. Both GLib and the C library (malloc implementation)
Packit Service fb6fa5
will cache allocated memory on occasion, even if you free it with
Packit Service fb6fa5
free().</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>So you can't generally use tools such as top to see if you are
Packit Service fb6fa5
using free() properly (aside from the very roughest of estimations, i.e.
Packit Service fb6fa5
if you are really, really screwing up top will show that, but you can't
Packit Service fb6fa5
distinguish small mistakes from the GLib/malloc caches).</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>In order to find memory leaks, use proper memory profiling
Packit Service fb6fa5
tools.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
</chapter>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<chapter>
Packit Service fb6fa5
<title>Development with GTK+: widget specific questions</title>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I find out about the selection of a GtkList?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Get the selection something like this:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
GList *sel;
Packit Service fb6fa5
sel = GTK_LIST(list)->selection;
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>This is how GList is defined (quoting glist.h):</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
typedef struct _GList GList;
Packit Service fb6fa5
Packit Service fb6fa5
struct _GList
Packit Service fb6fa5
{
Packit Service fb6fa5
  gpointer data;
Packit Service fb6fa5
  GList *next;
Packit Service fb6fa5
  GList *prev;
Packit Service fb6fa5
};
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>A GList structure is just a simple structure for doubly
Packit Service fb6fa5
linked lists. There exist several g_list_*() functions to
Packit Service fb6fa5
modify a linked list in glib.h.  However the
Packit Service fb6fa5
GTK_LIST(MyGtkList)->selection is maintained by the
Packit Service fb6fa5
gtk_list_*() functions and should not be modified.</para>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<para>The selection_mode of the GtkList determines the
Packit Service fb6fa5
selection facilities of a GtkList and therefore the contents
Packit Service fb6fa5
of GTK_LIST(AnyGtkList)->selection:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<informaltable frame="all">
Packit Service fb6fa5
<tgroup cols="2">
Packit Service fb6fa5
Packit Service fb6fa5
<row>
Packit Service fb6fa5
<entry><literal>selection_mode</literal></entry>
Packit Service fb6fa5
<entry><literal> GTK_LIST()->selection</literal>
Packit Service fb6fa5
contents</entry>
Packit Service fb6fa5
</row>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<row>
Packit Service fb6fa5
<entry><literal>GTK_SELECTION_SINGLE</literal></entry>
Packit Service fb6fa5
<entry>selection is either NULL or contains a GList*
Packit Service fb6fa5
pointer for a single selected item.</entry>
Packit Service fb6fa5
</row>
Packit Service fb6fa5
Packit Service fb6fa5
<row>
Packit Service fb6fa5
<entry><literal>GTK_SELECTION_BROWSE</literal></entry>
Packit Service fb6fa5
<entry>selection is NULL if the list contains no
Packit Service fb6fa5
widgets, otherwise it contains a GList*
Packit Service fb6fa5
pointer for one GList structure.</entry>
Packit Service fb6fa5
</row>
Packit Service fb6fa5
Packit Service fb6fa5
<row>
Packit Service fb6fa5
<entry><literal>GTK_SELECTION_MULTIPLE</literal></entry>
Packit Service fb6fa5
<entry>selection is NULL if no listitems are selected
Packit Service fb6fa5
or a a GList* pointer for the first selected
Packit Service fb6fa5
item. that in turn points to a GList structure
Packit Service fb6fa5
for the second selected item and so
Packit Service fb6fa5
on.</entry>
Packit Service fb6fa5
</row>
Packit Service fb6fa5
Packit Service fb6fa5
<row>
Packit Service fb6fa5
<entry><literal>GTK_SELECTION_EXTENDED</literal></entry>
Packit Service fb6fa5
<entry>selection is NULL.</entry>
Packit Service fb6fa5
</row>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
</tgroup>
Packit Service fb6fa5
</informaltable>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The data field of the GList structure
Packit Service fb6fa5
GTK_LIST(MyGtkList)->selection points to the first
Packit Service fb6fa5
GtkListItem that is selected.  So if you would like to
Packit Service fb6fa5
determine which listitems are selected you should go like
Packit Service fb6fa5
this:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
{
Packit Service fb6fa5
        gchar           *list_items[]={
Packit Service fb6fa5
                                "Item0",
Packit Service fb6fa5
                                "Item1",
Packit Service fb6fa5
                                "foo",
Packit Service fb6fa5
                                "last Item",
Packit Service fb6fa5
                        };
Packit Service fb6fa5
        guint           nlist_items=sizeof(list_items)/sizeof(list_items[0]);
Packit Service fb6fa5
        GtkWidget       *list_item;
Packit Service fb6fa5
        guint           i;
Packit Service fb6fa5
Packit Service fb6fa5
        list=gtk_list_new();
Packit Service fb6fa5
        gtk_list_set_selection_mode(GTK_LIST(list), GTK_SELECTION_MULTIPLE);
Packit Service fb6fa5
        gtk_container_add(GTK_CONTAINER(AnyGtkContainer), list);
Packit Service fb6fa5
        gtk_widget_show (list);
Packit Service fb6fa5
Packit Service fb6fa5
        for (i = 0; i < nlist_items; i++)
Packit Service fb6fa5
        {
Packit Service fb6fa5
                list_item=gtk_list_item_new_with_label(list_items[i]);
Packit Service fb6fa5
                gtk_object_set_user_data(GTK_OBJECT(list_item), (gpointer)i);
Packit Service fb6fa5
                gtk_container_add(GTK_CONTAINER(list), list_item);
Packit Service fb6fa5
                gtk_widget_show(list_item);
Packit Service fb6fa5
        }
Packit Service fb6fa5
}
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>To get known about the selection:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
{
Packit Service fb6fa5
        GList   *items;
Packit Service fb6fa5
Packit Service fb6fa5
        items=GTK_LIST(list)->selection;
Packit Service fb6fa5
Packit Service fb6fa5
        printf("Selected Items: ");
Packit Service fb6fa5
        while (items) {
Packit Service fb6fa5
                if (GTK_IS_LIST_ITEM(items->data))
Packit Service fb6fa5
                        printf("%d ", (guint) 
Packit Service fb6fa5
                gtk_object_get_user_data(items->data));
Packit Service fb6fa5
                items=items->next;
Packit Service fb6fa5
        }
Packit Service fb6fa5
        printf("\n");
Packit Service fb6fa5
}
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I stop the column headings of a GtkCList
Packit Service fb6fa5
disappearing when the list is scrolled?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>This happens when a GtkCList is packed into a
Packit Service fb6fa5
GtkScrolledWindow using the function
Packit Service fb6fa5
<literal>gtk_scroll_window_add_with_viewport()</literal>. The prefered
Packit Service fb6fa5
method of adding a CList to a scrolled window is to use the
Packit Service fb6fa5
function <literal>gtk_container_add</literal>, as in:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
    GtkWidget *scrolled, *clist;
Packit Service fb6fa5
    char *titles[] = { "Title1" , "Title2" };
Packit Service fb6fa5
Packit Service fb6fa5
    scrolled = gtk_scrolled_window_new(NULL, NULL);
Packit Service fb6fa5
Packit Service fb6fa5
    clist = gtk_clist_new_with_titles(2, titles);
Packit Service fb6fa5
    gtk_container_add(GTK_CONTAINER(scrolled), clist);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>I don't want the user of my applications to enter text
Packit Service fb6fa5
into a GtkCombo. Any idea?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>A GtkCombo has an associated entry which can be accessed
Packit Service fb6fa5
using the following expression:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
      GTK_COMBO(combo_widget)->entry
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>If you don't want the user to be able to modify the
Packit Service fb6fa5
content of this entry, you can use the
Packit Service fb6fa5
gtk_entry_set_editable() function:</para>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
      void gtk_entry_set_editable(GtkEntry *entry, 
Packit Service fb6fa5
                                  gboolean editable);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Set the editable parameter to FALSE to disable typing
Packit Service fb6fa5
into the entry.</para>
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I catch a combo box change?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The entry which is associated to your GtkCombo send a
Packit Service fb6fa5
"changed" signal when:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<itemizedlist>
Packit Service fb6fa5
<listitem><simpara>some text is typed in</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara>the selection of the combo box is changed</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
</itemizedlist>
Packit Service fb6fa5
Packit Service fb6fa5
<para>To catch any combo box change, simply connect your
Packit Service fb6fa5
signal handler with</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
      gtk_signal_connect(GTK_COMBO(cb)->entry,
Packit Service fb6fa5
                         "changed",
Packit Service fb6fa5
                         GTK_SIGNAL_FUNC(my_cb_change_handler),
Packit Service fb6fa5
                         NULL);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How can I define a separation line in a menu?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>See the 
Packit Service fb6fa5
url="http://www.gtk.org/tutorial/">Tutorial</ulink> for
Packit Service fb6fa5
information on how to create menus. However, to create a
Packit Service fb6fa5
separation line in a menu, just insert an empty menu item:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
menuitem = gtk_menu_item_new();
Packit Service fb6fa5
gtk_menu_shell_append(GTK_MENU_SHELL(menu), menuitem);
Packit Service fb6fa5
gtk_widget_show(menuitem);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How can I right justify a menu, such as Help?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Depending on if you use the MenuFactory or not, there
Packit Service fb6fa5
are two ways to proceed. With the MenuFactory, use something
Packit Service fb6fa5
like the following:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
menu_path = gtk_menu_factory_find (factory,  "<MyApp>/Help");
Packit Service fb6fa5
gtk_menu_item_right_justify(menu_path->widget);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>If you do not use the MenuFactory, you should simply
Packit Service fb6fa5
use:</para>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
gtk_menu_item_right_justify(my_menu_item);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I add some underlined accelerators to menu
Packit Service fb6fa5
items?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Damon Chaplin, the technical force behind the Glade
Packit Service fb6fa5
project, provided the following code sample (this code is an
Packit Service fb6fa5
output from Glade). It creates a small <GUIMenu>File</guimenu> menu item
Packit Service fb6fa5
with only one child (<guimenu>New</guimenu>). The F in
Packit Service fb6fa5
<guimenu>File</guimenu> and the N in <guimenu>New</guimenu> are
Packit Service fb6fa5
underlined, and the relevant accelerators are created.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
  menubar1 = gtk_menu_bar_new ();
Packit Service fb6fa5
  gtk_object_set_data (GTK_OBJECT (window1), "menubar1", menubar1);
Packit Service fb6fa5
  gtk_widget_show (menubar1);
Packit Service fb6fa5
  gtk_box_pack_start (GTK_BOX (vbox1), menubar1, FALSE, FALSE, 0);
Packit Service fb6fa5
Packit Service fb6fa5
  file1 = gtk_menu_item_new_with_label ("");
Packit Service fb6fa5
  tmp_key = gtk_label_parse_uline (GTK_LABEL (GTK_BIN (file1)->child),
Packit Service fb6fa5
                                   _("_File"));
Packit Service fb6fa5
  gtk_widget_add_accelerator (file1, "activate_item", accel_group,
Packit Service fb6fa5
                              tmp_key, GDK_MOD1_MASK, 0);
Packit Service fb6fa5
  gtk_object_set_data (GTK_OBJECT (window1), "file1", file1);
Packit Service fb6fa5
  gtk_widget_show (file1);
Packit Service fb6fa5
  gtk_container_add (GTK_CONTAINER (menubar1), file1);
Packit Service fb6fa5
Packit Service fb6fa5
  file1_menu = gtk_menu_new ();
Packit Service fb6fa5
  file1_menu_accels = gtk_menu_ensure_uline_accel_group (GTK_MENU (file1_menu));
Packit Service fb6fa5
  gtk_object_set_data (GTK_OBJECT (window1), "file1_menu", file1_menu);
Packit Service fb6fa5
  gtk_menu_item_set_submenu (GTK_MENU_ITEM (file1), file1_menu);
Packit Service fb6fa5
Packit Service fb6fa5
  new1 = gtk_menu_item_new_with_label ("");
Packit Service fb6fa5
  tmp_key = gtk_label_parse_uline (GTK_LABEL (GTK_BIN (new1)->child),
Packit Service fb6fa5
                                   _("_New"));
Packit Service fb6fa5
  gtk_widget_add_accelerator (new1, "activate_item", file1_menu_accels,
Packit Service fb6fa5
                              tmp_key, 0, 0);
Packit Service fb6fa5
  gtk_object_set_data (GTK_OBJECT (window1), "new1", new1);
Packit Service fb6fa5
  gtk_widget_show (new1);
Packit Service fb6fa5
  gtk_container_add (GTK_CONTAINER (file1_menu), new1);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How can I retrieve the text from a GtkMenuItem?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>You can usually retrieve the label of a specific
Packit Service fb6fa5
GtkMenuItem with:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
    if (GTK_BIN (menu_item)->child)
Packit Service fb6fa5
    {
Packit Service fb6fa5
      GtkWidget *child = GTK_BIN (menu_item)->child;
Packit Service fb6fa5
  
Packit Service fb6fa5
      /* do stuff with child */
Packit Service fb6fa5
      if (GTK_IS_LABEL (child))
Packit Service fb6fa5
      {
Packit Service fb6fa5
        gchar *text;
Packit Service fb6fa5
    
Packit Service fb6fa5
        gtk_label_get (GTK_LABEL (child), &text);
Packit Service fb6fa5
        g_print ("menu item text: %s\n", text);
Packit Service fb6fa5
      }
Packit Service fb6fa5
    }
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>To get the active menu item from a GtkOptionMenu you can
Packit Service fb6fa5
do:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
if (GTK_OPTION_MENU (option_menu)->menu_item)
Packit Service fb6fa5
{
Packit Service fb6fa5
  GtkWidget *menu_item = GTK_OPTION_MENU (option_menu)->menu_item;
Packit Service fb6fa5
}
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>But, there's a catch. For this specific case, you can
Packit Service fb6fa5
<emphasis>not</emphasis> get the label widget from
Packit Service fb6fa5
<literal>menu_item</literal> with the above code, because the
Packit Service fb6fa5
option menu reparents the menu_item's child temporarily to
Packit Service fb6fa5
display the currently active contents. So to retrive the child
Packit Service fb6fa5
of the currently active menu_item of an option menu, you'll
Packit Service fb6fa5
have to do:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
    if (GTK_BIN (option_menu)->child)
Packit Service fb6fa5
    {
Packit Service fb6fa5
      GtkWidget *child = GTK_BIN (option_menu)->child;
Packit Service fb6fa5
Packit Service fb6fa5
      /* do stuff with child */
Packit Service fb6fa5
    }
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I right (or otherwise) justify a
Packit Service fb6fa5
GtkLabel?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Are you sure you want to <emphasis>justify</emphasis>
Packit Service fb6fa5
the labels? The label class contains the
Packit Service fb6fa5
<literal>gtk_label_set_justify()</literal> function that is
Packit Service fb6fa5
used to control the justification of a multi-line
Packit Service fb6fa5
label.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>What you probably want is to set the <emphasis>alignment</emphasis>
Packit Service fb6fa5
of the label, ie right align it, center it or left align
Packit Service fb6fa5
it. If you want to do this, you should use:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
void gtk_misc_set_alignment (GtkMisc *misc,
Packit Service fb6fa5
                             gfloat xalign,
Packit Service fb6fa5
                             gfloat yalign);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>where the <literal>xalign</literal> and
Packit Service fb6fa5
<literal>yalign</literal> values are floats in
Packit Service fb6fa5
[0.00;1.00].</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
GtkWidget       *label;
Packit Service fb6fa5
Packit Service fb6fa5
/* horizontal : left align, vertical : top */
Packit Service fb6fa5
gtk_misc_set_alignment(GTK_MISC(label), 0.0f, 0.0f);
Packit Service fb6fa5
Packit Service fb6fa5
/* horizontal : centered, vertical : centered */
Packit Service fb6fa5
gtk_misc_set_alignment(GTK_MISC(label), 0.5f, 0.5f);
Packit Service fb6fa5
Packit Service fb6fa5
/* horizontal : right align, vertical : bottom */
Packit Service fb6fa5
gtk_misc_set_alignment(GTK_MISC(label), 1.0f, 1.0f);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I set the background color of a GtkLabel
Packit Service fb6fa5
widget?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The GtkLabel widget is one of a few GTK+ widgets that
Packit Service fb6fa5
don't create their own window to render themselves
Packit Service fb6fa5
into. Instead, they draw themselves directly onto their
Packit Service fb6fa5
parents window.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>This means that in order to set the background color for
Packit Service fb6fa5
a GtkLabel widget, you need to change the background color of
Packit Service fb6fa5
its parent, i.e. the object that you pack it into.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1> 
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I set the color and font of a GtkLabel using a
Packit Service fb6fa5
Resource File?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The widget name path constructed for a Label consists of
Packit Service fb6fa5
the widget names of its object hierarchy as well, e.g.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para><literallayout>
Packit Service fb6fa5
<literal>window (name: humphrey)</literal>
Packit Service fb6fa5
<literal>  hbox</literal>
Packit Service fb6fa5
<literal>     label (name: mylabel)</literal>
Packit Service fb6fa5
</literallayout></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The widget path your pattern needs to match would be:
Packit Service fb6fa5
<literal>humphrey.GtkHBox.mylabel</literal></para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The resource file may look something like:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
style "title"
Packit Service fb6fa5
{
Packit Service fb6fa5
      fg[NORMAL] = {1.0, 0.0, 0.0}
Packit Service fb6fa5
      font = "-adobe-helvetica-bold-r-normal--*-140-*-*-*-*-*-*"
Packit Service fb6fa5
}
Packit Service fb6fa5
widget "*mylabel" style "title"
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>In your program, you would also need to give a name to
Packit Service fb6fa5
the Label widget, which can be done using:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
  label = gtk_label_new("Some Label Text");
Packit Service fb6fa5
  gtk_widget_set_name(label, "mylabel");
Packit Service fb6fa5
  gtk_widget_show(label);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I configure Tooltips in a Resource File?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The tooltip's window is named "gtk-tooltips",
Packit Service fb6fa5
GtkTooltips in itself is not a GtkWidget (though a GtkObject)
Packit Service fb6fa5
and as such is not attempted to match any widget styles.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>So, your resource file should look something like:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
style "postie"
Packit Service fb6fa5
{
Packit Service fb6fa5
      bg[NORMAL] = {1.0, 1.0, 0.0}
Packit Service fb6fa5
}
Packit Service fb6fa5
widget "gtk-tooltips*" style "postie"
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>I can't add more than (something like) 2000 chars in a
Packit Service fb6fa5
GtkEntry. What's wrong?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>There is now a known problem in the GtkEntry widget. In
Packit Service fb6fa5
the <literal>gtk_entry_insert_text()</literal> function, the
Packit Service fb6fa5
following lines limit the number of chars in the entry to
Packit Service fb6fa5
2047.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
  /* The algorithms here will work as long as, the text size (a
Packit Service fb6fa5
   * multiple of 2), fits into a guint16 but we specify a shorter
Packit Service fb6fa5
   * maximum length so that if the user pastes a very long text, there
Packit Service fb6fa5
   * is not a long hang from the slow X_LOCALE functions.  */
Packit Service fb6fa5
Packit Service fb6fa5
  if (entry->text_max_length == 0)
Packit Service fb6fa5
    max_length = 2047;
Packit Service fb6fa5
  else
Packit Service fb6fa5
    max_length = MIN (2047, entry->text_max_length);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I make a GtkEntry widget activate on pressing
Packit Service fb6fa5
the Return key?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The Entry widget emits an 'activate' signal when you
Packit Service fb6fa5
press return in it. Just attach to the activate signal on the
Packit Service fb6fa5
entry and do whatever you want to do. Typical code would
Packit Service fb6fa5
be:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
  entry = gtk_entry_new();
Packit Service fb6fa5
  gtk_signal_connect (GTK_OBJECT(entry), "activate",
Packit Service fb6fa5
                      GTK_SIGNAL_FUNC(entry_callback),
Packit Service fb6fa5
                      NULL);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I validate/limit/filter the input to a GtkEntry? <emphasis>[GTK 2.x]</emphasis></title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>If you want to validate the text that a user enters into
Packit Service fb6fa5
a GtkEntry widget you can attach to the "insert_text" signal
Packit Service fb6fa5
of the entry, and modify the text within the callback
Packit Service fb6fa5
function. The example below forces all characters to
Packit Service fb6fa5
uppercase, and limits the range of characters to A-Z. Note
Packit Service fb6fa5
that the entry is cast to an object of type GtkEditable, from
Packit Service fb6fa5
which GtkEntry is derived.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
#include <ctype.h>
Packit Service fb6fa5
#include <gtk/gtk.h>
Packit Service fb6fa5
Packit Service fb6fa5
void insert_text_handler (GtkEntry    *entry,
Packit Service fb6fa5
                          const gchar *text,
Packit Service fb6fa5
                          gint         length,
Packit Service fb6fa5
                          gint        *position,
Packit Service fb6fa5
                          gpointer     data)
Packit Service fb6fa5
{
Packit Service fb6fa5
  GtkEditable *editable = GTK_EDITABLE(entry);
Packit Service fb6fa5
  int i, count=0;
Packit Service fb6fa5
  gchar *result = g_new (gchar, length);
Packit Service fb6fa5
Packit Service fb6fa5
  for (i=0; i < length; i++) {
Packit Service fb6fa5
    if (!isalpha(text[i]))
Packit Service fb6fa5
      continue;
Packit Service fb6fa5
    result[count++] = islower(text[i]) ? toupper(text[i]) : text[i];
Packit Service fb6fa5
  }
Packit Service fb6fa5
  
Packit Service fb6fa5
  if (count > 0) {
Packit Service fb6fa5
    g_signal_handlers_block_by_func (G_OBJECT (editable),
Packit Service fb6fa5
                                     G_CALLBACK (insert_text_handler),
Packit Service fb6fa5
                                     data);
Packit Service fb6fa5
    gtk_editable_insert_text (editable, result, count, position);
Packit Service fb6fa5
    g_signal_handlers_unblock_by_func (G_OBJECT (editable),
Packit Service fb6fa5
                                       G_CALLBACK (insert_text_handler),
Packit Service fb6fa5
                                       data);
Packit Service fb6fa5
  }
Packit Service fb6fa5
  g_signal_stop_emission_by_name (G_OBJECT (editable), "insert_text");
Packit Service fb6fa5
Packit Service fb6fa5
  g_free (result);
Packit Service fb6fa5
}
Packit Service fb6fa5
Packit Service fb6fa5
int main (int   argc,
Packit Service fb6fa5
          char *argv[])
Packit Service fb6fa5
{
Packit Service fb6fa5
  GtkWidget *window;
Packit Service fb6fa5
  GtkWidget *entry;
Packit Service fb6fa5
  
Packit Service fb6fa5
  gtk_init (&argc, &argv);
Packit Service fb6fa5
  
Packit Service fb6fa5
  /* create a new window */
Packit Service fb6fa5
  window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
Packit Service fb6fa5
  gtk_window_set_title(GTK_WINDOW (window), "GTK Entry");
Packit Service fb6fa5
  g_signal_connect (G_OBJECT (window), "destroy",
Packit Service fb6fa5
                    G_CALLBACK (gtk_main_quit),
Packit Service fb6fa5
                    NULL);
Packit Service fb6fa5
Packit Service fb6fa5
  entry = gtk_entry_new();
Packit Service fb6fa5
  g_signal_connect(G_OBJECT(entry), "insert_text",
Packit Service fb6fa5
		     G_CALLBACK(insert_text_handler),
Packit Service fb6fa5
		     NULL);
Packit Service fb6fa5
  gtk_container_add(GTK_CONTAINER (window), entry);
Packit Service fb6fa5
  gtk_widget_show(entry);
Packit Service fb6fa5
  
Packit Service fb6fa5
  gtk_widget_show(window);
Packit Service fb6fa5
  
Packit Service fb6fa5
  gtk_main();
Packit Service fb6fa5
  return(0);
Packit Service fb6fa5
}
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I use horizontal scrollbars with a GtkText widget?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The short answer is that you can't. The current version
Packit Service fb6fa5
of the GtkText widget does not support horizontal
Packit Service fb6fa5
scrolling. There is an intention to completely rewrite the
Packit Service fb6fa5
GtkText widget, at which time this limitation will be
Packit Service fb6fa5
removed.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I change the font of a GtkText widget?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>There are a couple of ways of doing this. As GTK+ allows
Packit Service fb6fa5
the appearance of applications to be changed at run time using
Packit Service fb6fa5
resources you can use something like the following in the
Packit Service fb6fa5
appropriate file:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
style "text"
Packit Service fb6fa5
{
Packit Service fb6fa5
  font = "-adobe-helvetica-medium-r-normal--*-100-*-*-*-*-*-*"
Packit Service fb6fa5
}
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Another way to do this is to load a font within your
Packit Service fb6fa5
program, and then use this in the functions for adding text to
Packit Service fb6fa5
the text widget. You can load a font using, for example:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
  GdkFont *font;
Packit Service fb6fa5
  font = gdk_font_load("-adobe-helvetica-medium-r-normal--*-140-*-*-*-*-*-*");
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I set the cursor position in a GtkText
Packit Service fb6fa5
object?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Notice that the response is valid for any object that
Packit Service fb6fa5
inherits from the GtkEditable class.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Are you sure that you want to move the cursor position?
Packit Service fb6fa5
Most of the time, while the cursor position is good, the
Packit Service fb6fa5
insertion point does not match the cursor position. If this
Packit Service fb6fa5
apply to what you really want, then you should use the
Packit Service fb6fa5
<literal>gtk_text_set_point()</literal> function. If you want
Packit Service fb6fa5
to set the insertion point at the current cursor position, use
Packit Service fb6fa5
the following:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
  gtk_text_set_point(GTK_TEXT(text),
Packit Service fb6fa5
  gtk_editable_get_position(GTK_EDITABLE(text)));
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>If you want the insertion point to follow the cursor at
Packit Service fb6fa5
all time, you should probably catch the button press event,
Packit Service fb6fa5
and then move the insertion point. Be careful : you'll have to
Packit Service fb6fa5
catch it after the widget has changed the cursor position
Packit Service fb6fa5
though. Thomas Mailund Jensen proposed the following
Packit Service fb6fa5
code:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
static void
Packit Service fb6fa5
insert_bar (GtkWidget *text)
Packit Service fb6fa5
{
Packit Service fb6fa5
  /* jump to cursor mark */
Packit Service fb6fa5
  gtk_text_set_point (GTK_TEXT (text),
Packit Service fb6fa5
  gtk_editable_get_position (GTK_EDITABLE  (text)));
Packit Service fb6fa5
Packit Service fb6fa5
  gtk_text_insert (GTK_TEXT (text), NULL, NULL, NULL,
Packit Service fb6fa5
     "bar", strlen ("bar"));
Packit Service fb6fa5
}
Packit Service fb6fa5
Packit Service fb6fa5
int
Packit Service fb6fa5
main (int argc, char *argv[])
Packit Service fb6fa5
{
Packit Service fb6fa5
  GtkWidget *window, *text;
Packit Service fb6fa5
Packit Service fb6fa5
  gtk_init (&argc, &argv);
Packit Service fb6fa5
Packit Service fb6fa5
  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
Packit Service fb6fa5
  text = gtk_text_new (NULL, NULL);
Packit Service fb6fa5
  gtk_text_set_editable (GTK_TEXT (text), TRUE);
Packit Service fb6fa5
  gtk_container_add (GTK_CONTAINER (window), text);
Packit Service fb6fa5
Packit Service fb6fa5
  /* connect after everything else */
Packit Service fb6fa5
  gtk_signal_connect_after (GTK_OBJECT(text), "button_press_event",
Packit Service fb6fa5
    GTK_SIGNAL_FUNC (insert_bar), NULL);
Packit Service fb6fa5
Packit Service fb6fa5
  gtk_widget_show_all(window);
Packit Service fb6fa5
  gtk_main();
Packit Service fb6fa5
Packit Service fb6fa5
  return 0;
Packit Service fb6fa5
}
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>Now, if you really want to change the cursor position,
Packit Service fb6fa5
you should use the
Packit Service fb6fa5
<literal>gtk_editable_set_position()</literal>
Packit Service fb6fa5
function.</para>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
</chapter>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<chapter>
Packit Service fb6fa5
<title>About GDK</title>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>What is GDK?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>GDK is basically a wrapper around the standard Xlib
Packit Service fb6fa5
function calls. If you are at all familiar with Xlib, a lot of
Packit Service fb6fa5
the functions in GDK will require little or no getting used
Packit Service fb6fa5
to. All functions are written to provide an way to access Xlib
Packit Service fb6fa5
functions in an easier and slightly more intuitive manner. In
Packit Service fb6fa5
addition, since GDK uses GLib (see below), it will be more
Packit Service fb6fa5
portable and safer to use on multiple platforms.</para>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How do I use color allocation?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>One of the nice things about GDK is that it's based on
Packit Service fb6fa5
top of Xlib; this is also a problem, especially in the area of
Packit Service fb6fa5
color management. If you want  to use color in your program
Packit Service fb6fa5
(drawing a rectangle or such, your code  should look something
Packit Service fb6fa5
like this:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
{
Packit Service fb6fa5
  GdkColor *color;
Packit Service fb6fa5
  int width, height;
Packit Service fb6fa5
  GtkWidget *widget;
Packit Service fb6fa5
  GdkGC *gc;
Packit Service fb6fa5
Packit Service fb6fa5
  ...
Packit Service fb6fa5
  
Packit Service fb6fa5
  /* first, create a GC to draw on */
Packit Service fb6fa5
  gc = gdk_gc_new(widget->window);
Packit Service fb6fa5
Packit Service fb6fa5
  /* find proper dimensions for rectangle */
Packit Service fb6fa5
  gdk_window_get_size(widget->window, &width, &height);
Packit Service fb6fa5
Packit Service fb6fa5
  /* the color we want to use */
Packit Service fb6fa5
  color = (GdkColor *)malloc(sizeof(GdkColor));
Packit Service fb6fa5
  
Packit Service fb6fa5
  /* red, green, and blue are passed values, indicating the RGB triple
Packit Service fb6fa5
   * of the color we want to draw. Note that the values of the RGB components
Packit Service fb6fa5
   * within the GdkColor are taken from 0 to 65535, not 0 to 255.
Packit Service fb6fa5
   */
Packit Service fb6fa5
  color->red = red * (65535/255);
Packit Service fb6fa5
  color->green = green * (65535/255);
Packit Service fb6fa5
  color->blue = blue * (65535/255);
Packit Service fb6fa5
  
Packit Service fb6fa5
  /* the pixel value indicates the index in the colormap of the color.
Packit Service fb6fa5
   * it is simply a combination of the RGB values we set earlier
Packit Service fb6fa5
   */
Packit Service fb6fa5
  color->pixel = (gulong)(red*65536 + green*256 + blue);
Packit Service fb6fa5
Packit Service fb6fa5
  /* However, the pixel valule is only truly valid on 24-bit (TrueColor)
Packit Service fb6fa5
   * displays. Therefore, this call is required so that GDK and X can
Packit Service fb6fa5
   * give us the closest color available in the colormap
Packit Service fb6fa5
   */
Packit Service fb6fa5
  gdk_color_alloc(gtk_widget_get_colormap(widget), color);
Packit Service fb6fa5
Packit Service fb6fa5
  /* set the foreground to our color */
Packit Service fb6fa5
  gdk_gc_set_foreground(gc, color);
Packit Service fb6fa5
  
Packit Service fb6fa5
  /* draw the rectangle */
Packit Service fb6fa5
  gdk_draw_rectangle(widget->window, gc, 1, 0, 0, width, height);
Packit Service fb6fa5
Packit Service fb6fa5
  ...
Packit Service fb6fa5
}
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
</chapter>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<chapter>
Packit Service fb6fa5
<title>About GLib</title>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>What is GLib?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>GLib is a library of useful functions and definitions
Packit Service fb6fa5
available for use  when creating GDK and GTK applications. It
Packit Service fb6fa5
provides replacements for some standard libc functions, such
Packit Service fb6fa5
as malloc, which are buggy on some systems.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>It also provides routines for handling:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<itemizedlist spacing=compact>
Packit Service fb6fa5
<listitem><simpara>Doubly Linked Lists</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara>Singly Linked Lists</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara>Timers</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara>String Handling</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara>A Lexical Scanner</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
Packit Service fb6fa5
<listitem><simpara>Error Functions</simpara>
Packit Service fb6fa5
</listitem>
Packit Service fb6fa5
</itemizedlist>
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>How can I use the doubly linked lists?</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The GList object is defined as:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
typedef struct _GList GList;
Packit Service fb6fa5
Packit Service fb6fa5
struct _GList
Packit Service fb6fa5
{
Packit Service fb6fa5
  gpointer data;
Packit Service fb6fa5
  GList *next;
Packit Service fb6fa5
  GList *prev;
Packit Service fb6fa5
};
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>To use the GList objects, simply:</para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
GList   *list = NULL;
Packit Service fb6fa5
GList   *listrunner;
Packit Service fb6fa5
gint    array[] = { 1, 2, 3, 4, 5, 6 };
Packit Service fb6fa5
gint    pos;
Packit Service fb6fa5
gint    *value;
Packit Service fb6fa5
Packit Service fb6fa5
/* add data to the list */
Packit Service fb6fa5
for (pos=0;pos < sizeof array; pos++) {
Packit Service fb6fa5
  list = g_list_append(list, (gpointer)&array[pos]);
Packit Service fb6fa5
}
Packit Service fb6fa5
Packit Service fb6fa5
/* run through the list */
Packit Service fb6fa5
listrunner = g_list_first(list);
Packit Service fb6fa5
while (listrunner) {
Packit Service fb6fa5
  value = (gint *)listrunner->data;
Packit Service fb6fa5
  printf("%d\n", *value);
Packit Service fb6fa5
  listrunner = g_list_next(listrunner);
Packit Service fb6fa5
}
Packit Service fb6fa5
Packit Service fb6fa5
/* removing datas from the list */
Packit Service fb6fa5
listrunner = g_list_first(list);
Packit Service fb6fa5
list = g_list_remove_link(list, listrunner);
Packit Service fb6fa5
list = g_list_remove(list, &array[4]);
Packit Service fb6fa5
</programlisting>
Packit Service fb6fa5
Packit Service fb6fa5
<para>The same code is usable with singly linked lists (GSList
Packit Service fb6fa5
objects) by replacing g_list_* functions with the relevant
Packit Service fb6fa5
g_slist_* ones (g_slist_append,  g_slist_remove, ...). Just
Packit Service fb6fa5
remember that since you can't go backward in a singly linked
Packit Service fb6fa5
list, there is no g_slist_first function - you'll need to keep
Packit Service fb6fa5
a  reference on the first node of the list.</para>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
over do it - TRG -->
Packit Service fb6fa5
Packit Service fb6fa5
</sect1>
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
Packit Service fb6fa5
<sect1>
Packit Service fb6fa5
<title>Memory does not seem to be released when I free the
Packit Service fb6fa5
list nodes I've allocated</title>
Packit Service fb6fa5
Packit Service fb6fa5
<para>GLib tries to be "intelligent" on this special issue: it
Packit Service fb6fa5
assumes that you are likely to reuse the objects, so caches
Packit Service fb6fa5
the allocated memory. If you do not want to use this behavior,
Packit Service fb6fa5
you'll probably want to set up a special allocator.</para>
Packit Service fb6fa5
Packit Service fb6fa5
<para>To quote Tim Janik:</para>
Packit Service fb6fa5
<para><quote>If you have a certain portion of code that uses *lots*
Packit Service fb6fa5
of GLists or GNodes, and you know you'd better want to release
Packit Service fb6fa5
all of them after a short while, you'd want to use a
Packit Service fb6fa5
GAllocator. Pushing an allocator into g_list will make all
Packit Service fb6fa5
subsequent glist operations private to that allocator's memory
Packit Service fb6fa5
pool (and thus you have to take care to pop the allocator
Packit Service fb6fa5
again, before making any external calls): </quote></para>
Packit Service fb6fa5
Packit Service fb6fa5
<programlisting role="C">
Packit Service fb6fa5
GAllocator *allocator;
Packit Service fb6fa5
GList *list = NULL;
Packit Service fb6fa5
guint i;
Packit Service fb6fa5
Packit Service fb6fa5
/* set a new allocation pool for GList nodes */
Packit Service fb6fa5
allocator = g_allocator_new ("list heap", 1024);
Packit Service fb6fa5
g_list_push_allocator (allocator);
Packit Service fb6fa5
Packit Service fb6fa5
/* do some list operations */
Packit Service fb6fa5
for (i = 0; i < 4096; i++)
Packit Service fb6fa5
  list = g_list_prepend (list, NULL);
Packit Service fb6fa5
list = g_list_reverse (list);
Packit Service fb6fa5
Packit Service fb6fa5
/* beware to pop allocator befor calling external functions */
Packit Service fb6fa5
g_list_pop_allocator ();
Packit Service fb6fa5
gtk_label_set_text (GTK_LABEL (some_label), "some text");
Packit Service fb6fa5
Packit Service fb6fa5
/* and set our private glist pool again */
Packit Service fb6fa5
g_list_push_allocator (allocator);
Packit Service fb6fa5
Packit Service