diff options
| author | BST 2000 Tony Gale <gale@gtk.org> | 2000-07-11 12:13:53 +0000 |
|---|---|---|
| committer | Tony Gale <gale@src.gnome.org> | 2000-07-11 12:13:53 +0000 |
| commit | 30973dd7a2f7bd8354d9f7ba2cd25c41f115e3ec (patch) | |
| tree | 100963b02f4255c43bd79a6433913e306cc74d5f /docs | |
| parent | fc5ee9256d7b16abf0ec49319daeca59752d1cb2 (diff) | |
| download | gtk+-30973dd7a2f7bd8354d9f7ba2cd25c41f115e3ec.tar.gz | |
Cleanup indenting and various small changes.
Tue Jul 11 13:10:57 BST 2000 Tony Gale <gale@gtk.org>
* docs/faq/gtk-faq.sgml: Cleanup indenting and various
small changes.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/faq/gtk-faq.sgml | 3811 |
1 files changed, 2015 insertions, 1796 deletions
diff --git a/docs/faq/gtk-faq.sgml b/docs/faq/gtk-faq.sgml index 580541bb12..ab8e05b8d1 100644 --- a/docs/faq/gtk-faq.sgml +++ b/docs/faq/gtk-faq.sgml @@ -1,793 +1,959 @@ <!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []> <book> - <bookinfo> - <date>June 28th 2000</date> - <title>GTK+ FAQ</title> - <authorgroup> - <author> - <firstname>Tony</firstname> - <surname>Gale</surname> - </author> - <author> - <firstname>Shawn</firstname> - <surname>Amundson</surname> - </author> - <author> - <firstname>Emmanuel</firstname> - <surname>Deloget</surname> - </author> - </authorgroup> - <abstract> - <para> This document is intended to answer questions that are - likely to be frequently asked by programmers using GTK+ or - people who are just looking at using GTK+. </para> - </abstract> - </bookinfo> - - <toc></toc> - - <!-- ***************************************************************** --> - <chapter> - <title>GTK+ FAQ</title> - <sect1> - <title>General Information</title> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>Before anything else: the greetings</title> - <para>The FAQ authors want to thank:</para> - <itemizedlist spacing=Compact> - <listitem> - <simpara>Havoc Pennington</simpara> - </listitem> - <listitem> - <simpara>Erik Mouw</simpara> - </listitem> - <listitem> - <simpara>Owen Taylor</simpara> - </listitem> - <listitem> - <simpara>Tim Janik</simpara> - </listitem> - <listitem> - <simpara>Thomas Mailund Jensen</simpara> - </listitem> - <listitem> - <simpara>Joe Pfeiffer</simpara> - </listitem> - <listitem> - <simpara>Andy Kahn</simpara> - </listitem> - <listitem> - <simpara>Federico Mena Quntero</simpara> - </listitem> - <listitem> - <simpara>Damon Chaplin</simpara> - </listitem> - <listitem> - <simpara>and all the members of the GTK+ lists</simpara> - </listitem></itemizedlist> - <para> If we forgot you, please email us! Thanks again (I know, - it's really short :) </para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>Authors</title> - <para>The original authors of GTK+ were:</para> - <itemizedlist spacing=Compact> - <listitem> - <simpara>Peter Mattis</simpara> - </listitem> - <listitem> - <simpara>Spencer Kimball</simpara> - </listitem> - <listitem> - <simpara>Josh MacDonald</simpara> - </listitem> - </itemizedlist> - <para>Since then, much has been added by others. Please see the - AUTHORS file in the distribution for the GTK+ Team.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>What is GTK+?</title> - <para>GTK+ is a small and efficient widget set designed with - the general look and feel of Motif. In reality, it looks much - better than Motif. It contains common widgets and some more - complex widgets such as a file selection, and color selection - widgets.</para> - <para>GTK+ provides some unique features. (At least, I know of - no other widget library which provides them). For example, a - button does not contain a label, it contains a child widget, - which in most instances will be a label. However, the child - widget can also be a pixmap, image or any combination possible - the programmer desires. This flexibility is adhered to - throughout the library.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>What is the + in GTK+?</title> - <para>Peter Mattis informed the gtk mailing list that:</para> - <para><quote>I originally wrote gtk which included the three - libraries, libglib, libgdk and libgtk. It featured a flat - widget hierarchy. That is, you couldn't derive a new widget - from an existing one. And it contained a more standard - callback mechanism instead of the signal mechanism now present - in gtk+. The + was added to distinguish between the original - version of gtk and the new version. You can think of it as - being an enhancement to the original gtk that adds object - oriented features.</quote></para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>Does the G in GTK+, GDK and GLib stand for?</title> - <para>GTK+ == Gimp Toolkit</para> - <para>GDK == GTK+ Drawing Kit</para> - <para>GLib == G Libray</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>Where is the documentation for GTK+?</title> - <para>In the GTK+ distribution's doc/ directory you will find - the reference material for both GTK and GDK, this FAQ and the - GTK Tutorial.</para> - <para>In addition, you can find links to HTML versions of - these documents by going to <ulink url="http://www.gtk.org/"> - http://www.gtk.org/</ulink>. A - packaged version of the GTK Tutorial, with SGML, HTML, - Postscript, DVI and text versions can be found in <ulink - url="ftp://ftp.gtk.org/pub/gtk/tutorial">ftp://ftp.gtk.org/pub/gtk/tutorial - </ulink></para> - <para>There are now a couple of books available that deal with - programming GTK+, GDK and GNOME:</para> - <itemizedlist> - <listitem><simpara>Eric Harlows book entitled "Developing - Linux Applications with GTK+ and GDK". The ISBN is 0-7357-0021-4</simpara> - </listitem> - <listitem><simpara>The example code from Eric's book is - available on-line at <ulink - url="http://www.bcpl.net/~eharlow/book"> - http://www.bcpl.net/~eharlow/book</ulink></simpara> - </listitem> - <listitem><simpara>Havoc Pennington has released a book called - "GTK+/GNOME Application Development". The ISBN is 0-7357-0078-8</simpara> - <simpara>The free version of the book lives here: <ulink - url="http://developer.gnome.org/doc/GGAD/">http://developer.gnome.org/doc/GGAD/ - </ulink></simpara> - <simpara>And Havoc maintains information about it and - errata here: <ulink - url="http://pobox.com/~hp/gnome-app-devel.html">http://pobox.com/~hp/gnome-app-devel.html - </ulink></simpara> - </listitem> - </itemizedlist> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>Is there a mailing list (or mailing list archive) for - GTK+?</title> - <para>Information on mailing lists relating to GTK+ can be - found at: <ulink - url="http://www.gtk.org/mailinglists.html">http://www.gtk.org/mailinglists.html - </ulink></para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>How to get help with GTK+</title> - <para>First, make sure your question isn't answered in the - documentation, this FAQ or the tutorial. Done that? You're - sure you've done that, right? In that case, the best place to - post questions is to the GTK+ mailing list.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>How to report bugs in GTK+</title> - <para>Bugs should be reported to the GNOME bug tracking system - (<ulink - url="http://bugs.gnome.org">http://bugs.gnome.org</ulink>). To - report a problem about GTK+, send mail to submit@bugs.gnome.org.</para> - <para>The subject of the mail should describe your problem. In - the body of the mail, you should first include a - "pseudo-header" that gives the package and version - number. This should be separated by a blank line from the - actual headers.</para> - - <para><literallayout><literal>Package: gtk+</literal> - <literal>Version: 1.2.0</literal></literallayout></para> - - <para>Substitute 1.2.0 with the version of GTK+ that you have installed.</para> - <para>Then describe the bug. Include:</para> - - <itemizedlist> - <listitem><simpara> Information about your system. For instance:</simpara> - <itemizedlist spacing=compact> - <listitem><simpara> What operating system and version</simpara> - </listitem> - <listitem><simpara> What version of X</simpara> - </listitem> - <listitem><simpara> For Linux, what version of the C library</simpara> - </listitem> - </itemizedlist> - <para>And anything else you think is relevant.</para> - </listitem> - <listitem><simpara> How to reproduce the bug.</simpara> - <simpara>If you can reproduce it with the testgtk program - that is built in the gtk/ subdirectory, that will be most - convenient. Otherwise, please include a short test program - that exhibits the behavior. As a last resort, you can also - provide a pointer to a larger piece of software that can - be downloaded.</simpara> - <simpara>(Bugs that can be reproduced within the GIMP are - almost as good as bugs that can be reproduced in - testgtk. If you are reporting a bug found with the GIMP, - please include the version number of the GIMP you are - using)</simpara> - </listitem> - <listitem><simpara> If the bug was a crash, the exact text that was - printed out when the crash occured.</simpara> - </listitem> - <listitem><simpara> Further information such as stack traces - may be useful, but are not necessary. If you do send a stack trace, - and the error is an X error, it will be more useful if the stacktrace is produced running - the test program with the <literal>--sync</literal> command line option.</simpara> - </listitem> - </itemizedlist> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>Is there a Windows version of GTK+?</title> - <para>There is an on going port of GTK+ to the Windows - platform which is making impressive progress.</para> - <para>See <ulink - url="http://www.iki.fi/tml/gimp/win32">http://www.iki.fi/tml/gimp/win32</ulink> - for more information.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>What applications have been written with GTK+?</title> - <para>A list of some GTK+ based application can be found on - the GTK+ web server at <ulink - url="http://www.gtk.org/apps/">http://www.gtk.org/apps/</ulink> - and contains more than 350 applications.</para> - <para>Failing that, look for a project to work on for the - GNOME project, <ulink - url="http://www.gnome.org/">http://www.gnome.org/</ulink> - Write a game. Write something that is useful.</para> - <para>Some of these are:</para> - - <itemizedlist> - <listitem><simpara> GIMP (<ulink - url="http://www.gimp.org/">http://www.gimp.org/</ulink>), an - image manipulation program</simpara> - </listitem> - <listitem><simpara> AbiWord (<ulink - url="http://www.abisource.com/">http://www.abisource.com/</ulink>), - a professional word processor</simpara> - </listitem> - <listitem><simpara> Gzilla (<ulink - url="http://www.levien.com/gzilla/">http://www.levien.com/gzilla/</ulink>), - a web browser</simpara> - </listitem> - <listitem><simpara> XQF (<ulink - url="http://www.botik.ru/~roma/quake/">http://www.botik.ru/~roma/quake/</ulink>), - a QuakeWorld/Quake2 server browser and launcher</simpara> - </listitem> - <listitem><simpara> GDK Imlib (<ulink - url="http://www.rasterman.com/imlib.html">http://www.rasterman.com/imlib.html</ulink>), - a fast image loading and manipulation library for GDK</simpara> - </listitem> - <listitem><simpara> Glade (<ulink - url="http://glade.pn.org/">http://glade.pn.org/</ulink>), a - GTK+ based RAD tool which produces GTK+ applications</simpara> - </listitem> - </itemizedlist> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>I'm looking for an application to write in GTK+. How - about an IRC client?</title> - <para>Ask on gtk-list for suggestions. There are at least - three IRC clients already under development (probably more in fact. The server at - <ulink url="http://www.forcix.cx/irc-clients.html"> - http://www.forcix.cx/irc-clients.html</ulink> list a bunch of them).</para> - - <itemizedlist spacing=compact> - <listitem><simpara> X-Chat.</simpara> - </listitem> - <listitem><simpara> girc. (Included with GNOME)</simpara> - </listitem> - <listitem><simpara> gsirc. (In the gnome CVS tree)</simpara> - </listitem> - </itemizedlist> - </sect2> - </sect1> - - <!-- ***************************************************************** --> - <sect1> - <title>How to find, configure, install, and troubleshoot GTK+</title> - - <!-- ----------------------------------------------------------------- --> +<bookinfo> + <date>June 28th 2000</date> + <title>GTK+ FAQ</title> + <authorgroup> + <author> +<firstname>Tony</firstname> +<surname>Gale</surname> + </author> + <author> +<firstname>Shawn</firstname> +<surname>Amundson</surname> + </author> + <author> +<firstname>Emmanuel</firstname> +<surname>Deloget</surname> + </author> + </authorgroup> + <abstract> + <para> This document is intended to answer questions that are + likely to be frequently asked by programmers using GTK+ or + people who are just looking at using GTK+. </para> + </abstract> +</bookinfo> + +<toc></toc> + +<!-- ***************************************************************** --> +<chapter> +<title>GTK+ FAQ</title> + +<!-- ----------------------------------------------------------------- --> + +<sect1> +<title>General Information</title> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>Before anything else: the greetings</title> +<para>The FAQ authors want to thank:</para> +<itemizedlist spacing=Compact> +<listitem> +<simpara>Havoc Pennington</simpara> +</listitem> +<listitem> +<simpara>Erik Mouw</simpara> +</listitem> +<listitem> +<simpara>Owen Taylor</simpara> +</listitem> +<listitem> +<simpara>Tim Janik</simpara> +</listitem> +<listitem> +<simpara>Thomas Mailund Jensen</simpara> +</listitem> +<listitem> +<simpara>Joe Pfeiffer</simpara> +</listitem> +<listitem> +<simpara>Andy Kahn</simpara> +</listitem> +<listitem> +<simpara>Federico Mena Quntero</simpara> +</listitem> +<listitem> +<simpara>Damon Chaplin</simpara> +</listitem> +<listitem> +<simpara>and all the members of the GTK+ lists</simpara> +</listitem></itemizedlist> +<para> If we forgot you, please email us! Thanks again (I know, +it's really short :) </para> +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>Authors</title> + +<para>The original authors of GTK+ were:</para> + +<itemizedlist spacing=Compact> +<listitem> +<simpara>Peter Mattis</simpara> +</listitem> +<listitem> +<simpara>Spencer Kimball</simpara> +</listitem> +<listitem> +<simpara>Josh MacDonald</simpara> +</listitem> +</itemizedlist> - <sect2> - <title>What do I need to run GTK+?</title> - <para>To compile GTK+, all you need is a C compiler (gcc) and - the X Window System and associated libraries on your system.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>Where can I get GTK+?</title> - <para>The canonical site is <ulink - url="ftp://ftp.gtk.org/pub/gtk">ftp://ftp.gtk.org/pub/gtk</ulink>.</para> - <para>This site tends to get busy around the time of a new - GTK+ release so try and use one of the mirror sites that are - listed in <ulink - url="ftp://ftp.gtk.org/etc/mirrors">ftp://ftp.gtk.org/etc/mirrors</ulink></para> - <para>Here's a few mirror sites to get you started:</para> - - <itemizedlist spacing=compact> - <listitem><simpara> Africa - ftp://ftp.is.co.za/applications/gimp/</simpara> - </listitem> - <listitem><simpara> Australia - ftp://ftp.au.gimp.org/pub/gimp/</simpara> - </listitem> - <listitem><simpara> Finland - ftp://ftp.funet.fi/pub/sci/graphics/packages/gimp</simpara> - </listitem> - <listitem><simpara> Germany - ftp://infosoc.uni-koeln.de/pub/ftp.gimp.org/</simpara> - </listitem> - <listitem><simpara> Japan - ftp://SunSITE.sut.ac.jp/pub/archives/packages/gimp/</simpara> - </listitem> - <listitem><simpara> UK - ftp://ftp.flirble.org/pub/X/gimp/</simpara> - </listitem> - <listitem><simpara> US - ftp://ftp.insync.net/pub/mirrors/ftp.gimp.org/</simpara> - </listitem> - </itemizedlist> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>How do I configure/compile GTK+?</title> - <para>Generally, all you will need to do is issue the commands:</para> - - <para><literallayout><literal>./configure</literal> - <literal>make</literal></literallayout></para> - - <para>in the gtk+-version/ directory.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>When compiling GTK+ I get an error like: <literal>make: - file `Makefile' line 456: Syntax error</literal></title> - <para>Make sure that you are using GNU make (use <literal>make - -v</literal> - to check). There are many weird and wonderful versions of make - out there, and not all of them handle the automatically - generated Makefiles.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>I've compiled and installed GTK+, but I can't get any - programs to link with it!</title> - <para>This problem is most often encountered when the GTK+ - libraries can't be found or are the wrong version. Generally, - the compiler will complain about an 'unresolved symbol'. - There are two things you need to check:</para> - - <itemizedlist> - <listitem><simpara>Make sure that the libraries can be - found. You want to edit <filename>/etc/ld.so.conf</filename> to - include the directories which contain the GTK libraries, - so it looks something like:</simpara> - <para><literallayout><literal>/usr/X11R6/lib</literal> - <literal>/usr/local/lib</literal></literallayout></para> - - <para>Then you need to run /sbin/ldconfig as root. You can - find what directory GTK is in using</para> - - <para><literallayout><literal>gtk-config --libs</literal> - </literallayout></para> - - <para>If your system doesn't use ld.so to find libraries +<para>Since then, much has been added by others. Please see the +AUTHORS file in the distribution for the GTK+ Team.</para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>What is GTK+?</title> + +<para>GTK+ is a small and efficient widget set designed with +the general look and feel of Motif. In reality, it looks much +better than Motif. It contains common widgets and some more +complex widgets such as a file selection, and color selection +widgets.</para> + +<para>GTK+ provides some unique features. (At least, I know of +no other widget library which provides them). For example, a +button does not contain a label, it contains a child widget, +which in most instances will be a label. However, the child +widget can also be a pixmap, image or any combination possible +the programmer desires. This flexibility is adhered to +throughout the library.</para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>What is the + in GTK+?</title> + +<para>Peter Mattis informed the gtk mailing list that:</para> + +<para><quote>I originally wrote gtk which included the three +libraries, libglib, libgdk and libgtk. It featured a flat +widget hierarchy. That is, you couldn't derive a new widget +from an existing one. And it contained a more standard +callback mechanism instead of the signal mechanism now present +in gtk+. The + was added to distinguish between the original +version of gtk and the new version. You can think of it as +being an enhancement to the original gtk that adds object +oriented features.</quote></para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>Does the G in GTK+, GDK and GLib stand for?</title> + +<para>GTK+ == Gimp Toolkit</para> +<para>GDK == GTK+ Drawing Kit</para> +<para>GLib == G Libray</para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>Where is the documentation for GTK+?</title> + +<para>In the GTK+ distribution's doc/ directory you will find +the reference material for both GTK and GDK, this FAQ and the +GTK Tutorial.</para> + +<para>In addition, you can find links to HTML versions of +these documents by going to <ulink url="http://www.gtk.org/"> +http://www.gtk.org/</ulink>. A +packaged version of the GTK Tutorial, with SGML, HTML, +Postscript, DVI and text versions can be found in <ulink +url="ftp://ftp.gtk.org/pub/gtk/tutorial"> +ftp://ftp.gtk.org/pub/gtk/tutorial +</ulink></para> + +<para>There are now a couple of books available that deal with +programming GTK+, GDK and GNOME:</para> + +<itemizedlist> +<listitem><simpara>Eric Harlows book entitled "Developing +Linux Applications with GTK+ and GDK". The ISBN is +0-7357-0021-4</simpara> +</listitem> +<listitem><simpara>The example code from Eric's book is +available on-line at <ulink +url="http://www.bcpl.net/~eharlow/book"> +http://www.bcpl.net/~eharlow/book</ulink></simpara> +</listitem> +<listitem><simpara>Havoc Pennington has released a book called +"GTK+/GNOME Application Development". The ISBN is +0-7357-0078-8</simpara> +<simpara>The free version of the book lives here: <ulink +url="http://developer.gnome.org/doc/GGAD/"> +http://developer.gnome.org/doc/GGAD/ +</ulink></simpara> +<simpara>And Havoc maintains information about it and +errata here: <ulink +url="http://pobox.com/~hp/gnome-app-devel.html"> +http://pobox.com/~hp/gnome-app-devel.html +</ulink></simpara> +</listitem> +</itemizedlist> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>Is there a mailing list (or mailing list archive) for +GTK+?</title> + +<para>Information on mailing lists relating to GTK+ can be +found at: <ulink +url="http://www.gtk.org/mailinglists.html"> +http://www.gtk.org/mailinglists.html +</ulink></para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>How to get help with GTK+</title> + +<para>First, make sure your question isn't answered in the +documentation, this FAQ or the tutorial. Done that? You're +sure you've done that, right? In that case, the best place to +post questions is to the GTK+ mailing list.</para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>How to report bugs in GTK+</title> + +<para>Bugs should be reported to the GNOME bug tracking system +(<ulink +url="http://bugs.gnome.org">http://bugs.gnome.org</ulink>). To +report a problem about GTK+, send mail to submit@bugs.gnome.org.</para> + +<para>The subject of the mail should describe your problem. In +the body of the mail, you should first include a +"pseudo-header" that gives the package and version +number. This should be separated by a blank line from the +actual headers.</para> + +<para><literallayout> +<literal>Package: gtk+</literal> +<literal>Version: 1.2.0</literal> +</literallayout></para> + +<para>Substitute 1.2.0 with the version of GTK+ that you have +installed.</para> + +<para>Then describe the bug. Include:</para> + +<itemizedlist> +<listitem><simpara> Information about your system. For +instance:</simpara> +<itemizedlist spacing=compact> +<listitem><simpara> What operating system and version</simpara> +</listitem> +<listitem><simpara> What version of X</simpara> +</listitem> +<listitem><simpara> For Linux, what version of the C library</simpara> +</listitem> +</itemizedlist> +<para>And anything else you think is relevant.</para> +</listitem> +<listitem><simpara> How to reproduce the bug.</simpara> +<simpara>If you can reproduce it with the testgtk program +that is built in the gtk/ subdirectory, that will be most +convenient. Otherwise, please include a short test program +that exhibits the behavior. As a last resort, you can also +provide a pointer to a larger piece of software that can +be downloaded.</simpara> +<simpara>(Bugs that can be reproduced within the GIMP are +almost as good as bugs that can be reproduced in +testgtk. If you are reporting a bug found with the GIMP, +please include the version number of the GIMP you are +using)</simpara> +</listitem> +<listitem><simpara> If the bug was a crash, the exact text that was +printed out when the crash occured.</simpara> +</listitem> +<listitem><simpara> Further information such as stack traces +may be useful, but are not necessary. If you do send a stack trace, +and the error is an X error, it will be more useful if the stacktrace is +produced running the test program with the <literal>--sync</literal> +command line option.</simpara> +</listitem> +</itemizedlist> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>Is there a Windows version of GTK+?</title> + +<para>There is an on going port of GTK+ to the Windows +platform which is making impressive progress.</para> + +<para>See <ulink +url="http://www.iki.fi/tml/gimp/win32"> +http://www.iki.fi/tml/gimp/win32</ulink> +for more information.</para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>What applications have been written with GTK+?</title> + +<para>A list of some GTK+ based application can be found on +the GTK+ web server at <ulink +url="http://www.gtk.org/apps/">http://www.gtk.org/apps/</ulink> +and contains more than 350 applications.</para> + +<para>Failing that, look for a project to work on for the +GNOME project, <ulink +url="http://www.gnome.org/">http://www.gnome.org/</ulink> +Write a game. Write something that is useful.</para> +<para>Some of these are:</para> + +<itemizedlist> +<listitem><simpara> GIMP (<ulink +url="http://www.gimp.org/">http://www.gimp.org/</ulink>), an +image manipulation program</simpara> +</listitem> +<listitem><simpara> AbiWord (<ulink +url="http://www.abisource.com/">http://www.abisource.com/</ulink>), +a professional word processor</simpara> +</listitem> +<listitem><simpara> Gzilla (<ulink +url="http://www.levien.com/gzilla/">http://www.levien.com/gzilla/</ulink>), +a web browser</simpara> +</listitem> +<listitem><simpara> XQF (<ulink +url="http://www.botik.ru/~roma/quake/"> +http://www.botik.ru/~roma/quake/</ulink>), +a QuakeWorld/Quake2 server browser and launcher</simpara> +</listitem> +<listitem><simpara> GDK Imlib (<ulink +url="http://www.rasterman.com/imlib.html"> +http://www.rasterman.com/imlib.html</ulink>), +a fast image loading and manipulation library for GDK</simpara> +</listitem> +<listitem><simpara> Glade (<ulink +url="http://glade.pn.org/">http://glade.pn.org/</ulink>), a +GTK+ based RAD tool which produces GTK+ applications</simpara> +</listitem> +</itemizedlist> +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>I'm looking for an application to write in GTK+. How +about an IRC client?</title> + +<para>Ask on gtk-list for suggestions. There are at least +three IRC clients already under development (probably more in fact. The +server at <ulink url="http://www.forcix.cx/irc-clients.html"> +http://www.forcix.cx/irc-clients.html</ulink> list a bunch of +them).</para> + +<itemizedlist spacing=compact> +<listitem><simpara> X-Chat.</simpara> +</listitem> +<listitem><simpara> girc. (Included with GNOME)</simpara> +</listitem> +<listitem><simpara> gsirc. (In the gnome CVS tree)</simpara> +</listitem> +</itemizedlist> + +</sect2> + +</sect1> + +<!-- ***************************************************************** --> +<sect1> +<title>How to find, configure, install, and troubleshoot GTK+</title> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>What do I need to run GTK+?</title> + +<para>To compile GTK+, all you need is a C compiler (gcc) and +the X Window System and associated libraries on your system.</para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>Where can I get GTK+?</title> + +<para>The canonical site is <ulink +url="ftp://ftp.gtk.org/pub/gtk">ftp://ftp.gtk.org/pub/gtk</ulink>.</para> + +<para>This site tends to get busy around the time of a new +GTK+ release so try and use one of the mirror sites that are +listed in <ulink +url="ftp://ftp.gtk.org/etc/mirrors">ftp://ftp.gtk.org/etc/mirrors +</ulink></para> + +<para>Here's a few mirror sites to get you started:</para> + +<itemizedlist spacing=compact> +<listitem><simpara> Africa - +<ulink url="ftp://ftp.is.co.za/applications/gimp"> +ftp://ftp.is.co.za/applications/gimp</ulink></simpara> +</listitem> +<listitem><simpara> Australia - +<ulink +url="ftp://ftp.au.gimp.org/pub/gimp"> +ftp://ftp.au.gimp.org/pub/gimp</ulink></simpara> +</listitem> +<listitem><simpara> Finland - +<ulink url="ftp://ftp.funet.fi/pub/sci/graphics/packages/gimp"> +ftp://ftp.funet.fi/pub/sci/graphics/packages/gimp</ulink></simpara> +</listitem> +<listitem><simpara> Germany - +<ulink url="ftp://infosoc.uni-koeln.de/pub/ftp.gimp.org"> +ftp://infosoc.uni-koeln.de/pub/ftp.gimp.org"</ulink></simpara> +</listitem> +<listitem><simpara> Japan - +<ulink url="ftp://SunSITE.sut.ac.jp/pub/archives/packages/gimp"> +ftp://SunSITE.sut.ac.jp/pub/archives/packages/gimp</ulink></simpara> +</listitem> +<listitem><simpara> UK - +<ulink url="ftp://ftp.flirble.org/pub/X/gimp"> +ftp://ftp.flirble.org/pub/X/gimp</ulink></simpara> +</listitem> +<listitem><simpara> US - +<ulink url="ftp://ftp.insync.net/pub/mirrors/ftp.gimp.org"> +ftp://ftp.insync.net/pub/mirrors/ftp.gimp.org</ulink></simpara> +</listitem> +</itemizedlist> +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>How do I configure/compile GTK+?</title> + +<para>Generally, all you will need to do is issue the commands:</para> + +<para><literallayout><literal>./configure</literal> +<literal>make</literal></literallayout></para> + +<para>in the gtk+-version/ directory.</para> +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>When compiling GTK+ I get an error like: <literal>make: +file `Makefile' line 456: Syntax error</literal></title> + +<para>Make sure that you are using GNU make +(use <literal>make -v</literal> +to check). There are many weird and wonderful versions of make +out there, and not all of them handle the automatically +generated Makefiles.</para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>I've compiled and installed GTK+, but I can't get any +programs to link with it!</title> + +<para>This problem is most often encountered when the GTK+ +libraries can't be found or are the wrong version. Generally, +the compiler will complain about an 'unresolved symbol'. +There are two things you need to check:</para> + +<itemizedlist> +<listitem><simpara>Make sure that the libraries can be +found. You want to edit <filename>/etc/ld.so.conf</filename> to +include the directories which contain the GTK libraries, +so it looks something like:</simpara> + +<para><literallayout><literal>/usr/X11R6/lib</literal> +<literal>/usr/local/lib</literal></literallayout></para> + +<para>Then you need to run /sbin/ldconfig as root. You can +find what directory GTK is in using</para> + +<para><literallayout><literal>gtk-config --libs</literal> +</literallayout></para> + +<para>If your system doesn't use ld.so to find libraries (such as Solaris), then you will have to use the LD_LIBRARY_PATH environment variable (or compile the path into your program, which I'm not going to cover here). So, with a Bourne type shell you can do (if your GTK libraries are in /usr/local/lib):</para> - <para><literallayout><literal>export LD_LIBRARY_PATH=/usr/local/lib</literal></literallayout></para> +<para><literallayout> +<literal>export LD_LIBRARY_PATH=/usr/local/lib</literal> +</literallayout></para> - <para>and in a csh, you can do:</para> +<para>and in a csh, you can do:</para> - <para><literallayout><literal>setenv LD_LIBRARY_PATH /usr/local/lib</literal></literallayout></para> +<para><literallayout> +<literal>setenv LD_LIBRARY_PATH /usr/local/lib</literal> +</literallayout></para> - </listitem> - <listitem><simpara>Make sure the linker is finding the +</listitem> +<listitem><simpara>Make sure the linker is finding the correct set of libraries. If you have a Linux distribution that installs GTK+ (e.g. RedHat 5.0) then this older version may be used. Now (assuming you have a RedHat system), issue the command</simpara> - <para><literallayout><literal>rpm -e gtk gtk-devel</literal></literallayout></para> - - <para>You may also want to remove the packages that depend -on gtk (rpm will tell you which ones they are). If you don't have a RedHat Linux system, check to make sure -that neither <filename>/usr/lib</filename> or <filename>/usr/local/lib</filename> contain any of -the libraries libgtk, libgdk, libglib, or libgck. If they do exist, remove them -(and any gtk include files, such as <filename>/usr/include/gtk</filename> and <filename>/usr/include/gdk</filename>) -and reinstall gtk+.</para> - </listitem> - - </itemizedlist> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>When compiling programs with GTK+, I get compiler error - messages about not being able to find - <literal>glibconfig.h</literal>.</title> - <para>The header file "glibconfig.h" was moved to the - directory $exec_prefix/lib/glib/include/. $exec_prefix is the - directory that was specified by giving the --exec-prefix flags - to ./configure when compiling GTK+. It defaults to $prefix, - (specified with --prefix), which in turn defaults to /usr/local/.</para> - - <para>This was done because "glibconfig.h" includes - architecture dependent information, and the rest of the - include files are put in $prefix/include, which can be shared - between different architectures.</para> - - <para>GTK+ includes a shell script, <literal>/gtk-config/</literal>, that makes it - easy to find out the correct include paths. The GTK+ Tutorial - includes an example of using <literal>/gtk-config/</literal> for simple - compilation from the command line. For information about more - complicated configuration, see the file docs/gtk-config.txt in - the GTK+ distribution.</para> - - <para>If you are trying to compile an old program, you may be - able to work around the problem by configuring it with a - command line like:</para> - - <para><literallayout><literal>setenv CPPFLAGS "-I/usr/local/include/glib/include"</literal> -<literal>./configure</literal></literallayout></para> - - <para>(Substitute the appropriate value of $exec_prefix for - /usr/local.)</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>When installing a GTK+ application, configure reports - that it can't find GTK.</title> - <para>There are several common reasons for this:</para> - <itemizedlist> - <listitem><simpara>You have an old version of GTK installed - somewhere. RedHat 5.0, for example, installs an older copy of GTK that - may not work with the latest applications. You should remove this old - copy, but note that in the case of RedHat 5.0 this will - break the <literal>control-panel</literal> applications.</simpara> - </listitem> - <listitem><simpara><literal>gtk-config</literal> (or another - component of GTK) isn't in your path, or there is an old - version on your system. Type:</simpara> - <para><literallayout><literal>gtk-config --version</literal></literallayout></para> - - <para>to check for both of these. If it returns a value - different from what you expect, then you have an old - version of GTK on your system.</para> - </listitem> - <listitem><simpara>The ./configure script can't find the GTK - libraries. As ./configure compiles various test programs, it needs to - be able to find the GTK libraries. See the question above - for help on this. </simpara></listitem> - </itemizedlist> - - <para>If none of the above help, then have a look in - config.log, which is generated by ./configure as it runs. At the - bottom will be the last action it took before failing. If it is a - section of source code, copy the source code to a file and compile it - with the line just above it in config.log. If the compilation is - successful, try executing it.</para> - </sect2> - - </sect1> - - <!-- ***************************************************************** --> - <sect1> - <title>Development of GTK+</title> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>Whats this CVS thing that everyone keeps talking about, - and how do I access it?</title> - <para>CVS is the Concurent Version System and is a very - popular means of version control for software projects. It is - designed to allow multiple authors to be able to - simultanously operate on the same source tree. This source - tree is centrally maintained, but each developer has a local - mirror of this repository that they make there changes to.</para> - <para>The GTK+ developers use a CVS repository to store the - master copy of the current development version of GTK+. As - such, people wishing to contribute patches to GTK+ should - generate them against the CVS version. Normal people should - use the packaged releases.</para> - <para>The CVS toolset is available as RPM packages from the - usual RedHat sites. The latest version is available at <ulink - url="http://download.cyclic.com/pub/">http://download.cyclic.com/pub/ - </ulink></para> - <para>Anyone can download the latest CVS version of GTK+ by - using anonymous access using the following steps:</para> - <itemizedlist> - <listitem><simpara> In a bourne shell descendant (e.g. bash) type:</simpara> - <para><literallayout><literal>CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'</literal> -<literal>export CVSROOT</literal></literallayout></para> - </listitem> - <listitem><simpara>Next, the first time the source tree is - checked out, a cvs login is needed. </simpara> - <para><literallayout><literal>cvs login</literal></literallayout></para> - <para>This will ask you for a password. There is no - password for cvs.gimp.org, so just enter a carriage return.</para> - </listitem> - <listitem><simpara>To get the tree and place it in a subdir of your - current working directory, issue the command:</simpara> - <para><literallayout><literal>cvs -z3 get gtk+</literal></literallayout></para> - <para>Note that with the GTK+ 1.1 tree, glib has been moved to - a separate CVS module, so if you don't have glib installed you will - need to get that as well:</para> - <para><literallayout><literal>cvs -z3 get glib</literal></literallayout></para> - </listitem> - </itemizedlist> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>How can I contribute to GTK+?</title> - <para>It's simple. If something doesn't work like you think it - should in a program, check the documentation to make sure - you're not missing something. If it is a true bug or missing - feature, track it down in the GTK+ source, change it, and - then generate a patch in the form of a 'context diff'. This - can be done using a command such as <literal>diff -ru - <oldfile> <newfile>.</literal> Then upload the patchfile to:</para> - <para><literallayout><literal>ftp://ftp.gtk.org/incoming</literal></literallayout></para> - <para>along with a README file. Make sure you follow the - naming conventions or your patch will just be deleted! The - filenames should be of this form:</para> - <para><literallayout><literal>gtk<username>-<date yymmdd-n>.patch.gz</literal> -<literal>gtk-<username>-<date yymmdd-n>.patch.README</literal></literallayout></para> - <para>The "n" in the date indicates a unique number (starting - from 0) of patches you uploaded that day. It should be 0, - unless you upload more than one patch in the same day.</para> - - <para>Example:</para> - <para><literallayout><literal>gtk-gale-982701-0.patch.gz</literal> -<literal>gtk-gale-982701-0.patch.README</literal></literallayout></para> - <para>Once you upload <emphasis>anything</emphasis>, send the README to ftp-admin@gtk.org</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>How do I know if my patch got applied, and if not, why - not?</title> - <para>Uploaded patches will be moved to - <filename>ftp://ftp.gtk.org/pub/gtk/patches</filename> where one of the - GTK+ development team will pick them up. If applied, they will - be moved to <filename>/pub/gtk/patches/old</filename>.</para> - <para>Patches that aren't applied, for whatever reason, are - moved to <filename>/pub/gtk/patches/unapplied</filename> or - <filename>/pub/gtk/patches/outdated</filename>. At this point you can ask - on the <literal>gtk-list</literal> mailing list why your patch wasn't - applied. There are many possible reasons why patches may not - be applied, ranging from it doesn't apply cleanly, to it isn't - right. Don't be put off if your patch didn't make it first - time round.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>What is the policy on incorporating new widgets into - the library?</title> - <para>This is up to the authors, so you will have to ask them - once you are done with your widget. As a general guideline, - widgets that are generally useful, work, and are not a - disgrace to the widget set will gladly be included.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>Is anyone working on bindings for languages other than - C?</title> - <para>The GTK+ home page (<ulink - url="http://www.gtk.org/">http://www.gtk.org/</ulink>) - presents a list of GTK+ bindings.</para> - <itemizedlist> - <listitem><simpara>There are several C++ wrappers for GTK+.</simpara> - <itemizedlist> - <listitem><simpara>the gtk-- package, which is a very small wrapper for GTK+. - You can find the home page at <ulink - url="http://www.cs.tut.fi/~p150650/gtk/gtk--.html"> - http://www.cs.tut.fi/~p150650/gtk/gtk--.html</ulink>. The FTP site is - <ulink url="ftp://ftp.gtk.org/pub/gtk/gtk--"> - ftp://ftp.gtk.org/pub/gtk/gtk--</ulink>.</simpara> - </listitem> - <listitem><simpara>the VDK package, which was built as - the base package of a GTK+ application Borland-like - builder. The home page can be found at <ulink - url="http://www.guest.net/homepages/mmotta/VDKHome"> - http://www.guest.net/homepages/mmotta/VDKHome</ulink>.</simpara> - </listitem> - - <listitem><simpara>The wxWindows/Gtk package, a free C++ library for cross-platform - GUI development. The home page of this package is - <ulink url="http://www.freiburg.linux.de/~wxxt/"> - http://www.freiburg.linux.de/~wxxt/</ulink>.</simpara> - </listitem> - </itemizedlist> - </listitem> - <listitem><simpara>There are three known Objective-c - bindings currently in development:</simpara> - <itemizedlist> - <listitem><simpara>The <ulink - url="http://www.gnome.org/">http://www.gnome.org/</ulink> - package of choice is objgtk. Objgtk is based on the Object class and is maintained by - <ulink url="mailto:sopwith@cuc.edu">Elliot Lee</ulink>. Apparently, - objgtk is being accepted as the `standard' Objective-C binding for GTK+.</simpara> - </listitem> - - <listitem><simpara>If you are more inclined towards the - <ulink url="http://www.gnustep.org/">GNUstep project</ulink>, - you may want to check out GTKKit by - <ulink url="mailto:helge@mdlink.de">Helge Heß</ulink>. - The intention is to setup a GTK+ binding using the FoundationKit. - GTKKit includes nicities like writing a XML-type template file to - construct a GTK+ interface.</simpara> - </listitem> - - <listitem><simpara>The GToolKit package, which can be found at +<para><literallayout> +<literal>rpm -e gtk gtk-devel</literal> +</literallayout></para> + +<para>You may also want to remove the packages that depend +on gtk (rpm will tell you which ones they are). If you don't have a +RedHat Linux system, check to make sure that neither +<filename>/usr/lib</filename> or <filename>/usr/local/lib</filename> +contain any of the libraries libgtk, libgdk, libglib, or libgck. If +they do exist, remove them (and any gtk include files, such as +<filename>/usr/include/gtk</filename> and +<filename>/usr/include/gdk</filename>) and reinstall gtk+.</para> +</listitem> +</itemizedlist> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>When compiling programs with GTK+, I get compiler error +messages about not being able to find +<literal>glibconfig.h</literal>.</title> + +<para>The header file "glibconfig.h" was moved to the +directory $exec_prefix/lib/glib/include/. $exec_prefix is the +directory that was specified by giving the --exec-prefix flags +to ./configure when compiling GTK+. It defaults to $prefix, +(specified with --prefix), which in turn defaults to /usr/local/.</para> + +<para>This was done because "glibconfig.h" includes +architecture dependent information, and the rest of the +include files are put in $prefix/include, which can be shared +between different architectures.</para> + +<para>GTK+ includes a shell script, <literal>/gtk-config/</literal>, +that makes it easy to find out the correct include paths. The GTK+ +Tutorial includes an example of using <literal>/gtk-config/</literal> +for simple compilation from the command line. For information about more +complicated configuration, see the file docs/gtk-config.txt in the GTK+ +distribution.</para> + +<para>If you are trying to compile an old program, you may be +able to work around the problem by configuring it with a +command line like:</para> + +<para><literallayout> +<literal>setenv CPPFLAGS "-I/usr/local/include/glib/include"</literal> +<literal>./configure</literal> +</literallayout></para> + +<para>(Substitute the appropriate value of $exec_prefix for +/usr/local.)</para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>When installing a GTK+ application, configure reports +that it can't find GTK.</title> + +<para>There are several common reasons for this:</para> + +<itemizedlist> +<listitem><simpara>You have an old version of GTK installed +somewhere. RedHat 5.0, for example, installs an older copy of GTK that +may not work with the latest applications. You should remove this old +copy, but note that in the case of RedHat 5.0 this will +break the <literal>control-panel</literal> applications.</simpara> +</listitem> + +<listitem><simpara><literal>gtk-config</literal> (or another +component of GTK) isn't in your path, or there is an old +version on your system. Type:</simpara> + +<para><literallayout> +<literal>gtk-config --version</literal> +</literallayout></para> + +<para>to check for both of these. If it returns a value +different from what you expect, then you have an old +version of GTK on your system.</para> +</listitem> + +<listitem><simpara>The ./configure script can't find the GTK +libraries. As ./configure compiles various test programs, it needs to be +able to find the GTK libraries. See the question above +for help on this. </simpara></listitem> +</itemizedlist> + +<para>If none of the above help, then have a look in +config.log, which is generated by ./configure as it runs. At the +bottom will be the last action it took before failing. If it is a +section of source code, copy the source code to a file and compile it +with the line just above it in config.log. If the compilation is +successful, try executing it.</para> + +</sect2> + +</sect1> + +<!-- ***************************************************************** --> +<sect1> +<title>Development of GTK+</title> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>Whats this CVS thing that everyone keeps talking about, +and how do I access it?</title> + +<para>CVS is the Concurent Version System and is a very +popular means of version control for software projects. It is +designed to allow multiple authors to be able to +simultanously operate on the same source tree. This source +tree is centrally maintained, but each developer has a local +mirror of this repository that they make there changes to.</para> + +<para>The GTK+ developers use a CVS repository to store the +master copy of the current development version of GTK+. As +such, people wishing to contribute patches to GTK+ should +generate them against the CVS version. Normal people should +use the packaged releases.</para> + +<para>The CVS toolset is available as RPM packages from the +usual RedHat sites. The latest version is available at <ulink +url="http://download.cyclic.com/pub/">http://download.cyclic.com/pub/ +</ulink></para> + +<para>Anyone can download the latest CVS version of GTK+ by +using anonymous access using the following steps:</para> + +<itemizedlist> +<listitem><simpara> In a bourne shell descendant (e.g. bash) type:</simpara> +<para><literallayout> +<literal>CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'</literal> +<literal>export CVSROOT</literal> +</literallayout></para> +</listitem> + +<listitem><simpara>Next, the first time the source tree is +checked out, a cvs login is needed. </simpara> +<para><literallayout> +<literal>cvs login</literal> +</literallayout></para> +<para>This will ask you for a password. There is no +password for cvs.gimp.org, so just enter a carriage return.</para> +</listitem> + +<listitem><simpara>To get the tree and place it in a subdir of your +current working directory, issue the command:</simpara> +<para><literallayout> +<literal>cvs -z3 get gtk+</literal> +</literallayout></para> +<para>Note that with the GTK+ 1.1 tree, glib has been moved to +a separate CVS module, so if you don't have glib installed you will +need to get that as well:</para> +<para><literallayout> +<literal>cvs -z3 get glib</literal> +</literallayout></para> +</listitem> +</itemizedlist> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>How can I contribute to GTK+?</title> + +<para>It's simple. If something doesn't work like you think it +should in a program, check the documentation to make sure +you're not missing something. If it is a true bug or missing +feature, track it down in the GTK+ source, change it, and +then generate a patch in the form of a 'context diff'. This +can be done using a command such as <literal>diff -ru +<oldfile> <newfile></literal>. Then upload the patchfile +to:</para> + +<para><literallayout> +<literal>ftp://ftp.gtk.org/incoming</literal> +</literallayout></para> + +<para>along with a README file. Make sure you follow the +naming conventions or your patch will just be deleted! The +filenames should be of this form:</para> + +<para><literallayout> +<literal>gtk<username>-<date yymmdd-n>.patch.gz</literal> +<literal>gtk-<username>-<date yymmdd-n>.patch.README</literal> +</literallayout></para> + +<para>The "n" in the date indicates a unique number (starting +from 0) of patches you uploaded that day. It should be 0, +unless you upload more than one patch in the same day.</para> + +<para>Example:</para> + +<para><literallayout> +<literal>gtk-gale-982701-0.patch.gz</literal> +<literal>gtk-gale-982701-0.patch.README</literal> +</literallayout></para> + +<para>Once you upload <emphasis>anything</emphasis>, send the README to +ftp-admin@gtk.org</para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>How do I know if my patch got applied, and if not, why +not?</title> + +<para>Uploaded patches will be moved to +<filename>ftp://ftp.gtk.org/pub/gtk/patches</filename> where one of the +GTK+ development team will pick them up. If applied, they will be moved +to <filename>/pub/gtk/patches/old</filename>.</para> + +<para>Patches that aren't applied, for whatever reason, are +moved to <filename>/pub/gtk/patches/unapplied</filename> or +<filename>/pub/gtk/patches/outdated</filename>. At this point you can ask +on the <literal>gtk-list</literal> mailing list why your patch wasn't +applied. There are many possible reasons why patches may not +be applied, ranging from it doesn't apply cleanly, to it isn't +right. Don't be put off if your patch didn't make it first +time round.</para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>What is the policy on incorporating new widgets into +the library?</title> + +<para>This is up to the authors, so you will have to ask them +once you are done with your widget. As a general guideline, +widgets that are generally useful, work, and are not a +disgrace to the widget set will gladly be included.</para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>Is anyone working on bindings for languages other than +C?</title> + +<para>The GTK+ home page (<ulink +url="http://www.gtk.org/">http://www.gtk.org/</ulink>) +presents a list of GTK+ bindings.</para> + +<itemizedlist> +<listitem><simpara>There are several C++ wrappers for GTK+.</simpara> + + <itemizedlist> + <listitem><simpara>the gtk-- package, which is a very small wrapper for + GTK+. You can find the home page at <ulink + url="http://www.cs.tut.fi/~p150650/gtk/gtk--.html"> + http://www.cs.tut.fi/~p150650/gtk/gtk--.html</ulink>. The FTP site is + <ulink url="ftp://ftp.gtk.org/pub/gtk/gtk--"> + ftp://ftp.gtk.org/pub/gtk/gtk--</ulink>.</simpara> + </listitem> + + <listitem><simpara>the VDK package, which was built as + the base package of a GTK+ application Borland-like + builder. The home page can be found at <ulink + url="http://www.guest.net/homepages/mmotta/VDKHome"> + http://www.guest.net/homepages/mmotta/VDKHome</ulink>.</simpara> + </listitem> + + <listitem><simpara>The wxWindows/Gtk package, a free C++ library for + cross-platform GUI development. The home page of this package is + <ulink url="http://www.freiburg.linux.de/~wxxt/"> + http://www.freiburg.linux.de/~wxxt/</ulink>.</simpara> + </listitem> + + </itemizedlist> +</listitem> + +<listitem><simpara>There are three known Objective-c +bindings currently in development:</simpara> + + <itemizedlist> + <listitem><simpara>The <ulink + url="http://www.gnome.org/">http://www.gnome.org/</ulink> + package of choice is objgtk. Objgtk is based on the Object class and + is maintained by <ulink url="mailto:sopwith@cuc.edu">Elliot + Lee</ulink>. Apparently, objgtk is being accepted as the `standard' + Objective-C binding for GTK+.</simpara> + </listitem> + + <listitem><simpara>If you are more inclined towards the + <ulink url="http://www.gnustep.org/">GNUstep project</ulink>, + you may want to check out GTKKit by + <ulink url="mailto:helge@mdlink.de">Helge Heß</ulink>. + The intention is to setup a GTK+ binding using the FoundationKit. + GTKKit includes nicities like writing a XML-type template file to + construct a GTK+ interface.</simpara> + </listitem> + + <listitem><simpara>The GToolKit package, which can be found at <ulink url="ftp://ftp.gtk.org/pub/gtk/objc-gtoolkit/"> ftp://ftp.gtk.org/pub/gtk/objc-gtoolkit/</ulink>.</simpara> - </listitem> - </itemizedlist> - </listitem> - <listitem><simpara>Perl bindings <ulink - url="ftp://ftp.gtk.org/pub/gtk/perl">ftp://ftp.gtk.org/pub/gtk/perl</ulink></simpara> - </listitem> - <listitem><simpara>Guile bindings. The home page is at - <ulink url="http://www.ping.de/sites/zagadka/guile-gtk">http://www.ping.de/sites/zagadka/guile-gtk</ulink>. - By the way, Guile is the GNU Project's implemention of R4RS Scheme (the - standard). If you like Scheme, you may want to take a look at this.</simpara> - </listitem> - <listitem><simpara>David Monniaux reports: - <quote>I've started a gtk-O'Caml binding system. - The basics of the system, including callbacks, work fine. - - The current development is in - <ulink url="http://www.ens-lyon.fr/~dmonniau/arcs">http://www.ens-lyon.fr/~dmonniau/arcs</ulink> - </quote></simpara> - </listitem> - <listitem><simpara>Several python bindings have been done:</simpara> - <itemizedlist> - <listitem><simpara>pygtk is at - <ulink url="http://www.daa.com.au/~james/pygtk">http://www.daa.com.au/~james/pygtk</ulink> and - <ulink url="ftp://ftp.gtk.org/pub/gtk/python">ftp://ftp.gtk.org/pub/gtk/python</ulink></simpara> - </listitem> - - <listitem><simpara>python-gtk is at - <ulink url="http://www.ucalgary.ca/~nascheme/python-gtk">http://www.ucalgary.ca/~nascheme/python-gtk</ulink></simpara> - </listitem> - </itemizedlist> - </listitem> - <listitem><simpara>There's are a couple of OpenGL/Mesa - widgets available for GTK+. I suggest you start at - <ulink url="http://www.student.oulu.fi/~jlof/gtkglarea/index.html">http://www.student.oulu.fi/~jlof/gtkglarea/index.html</ulink></simpara> - </listitem> - <listitem><simpara>Last, there are a lot of other language - bindings for languages such as Eiffel, TOM, Pascal, Pike, etc.</simpara> - </listitem> - </itemizedlist> - </sect2> - - </sect1> - - <!-- ***************************************************************** --> - <sect1> - <title>Development with GTK+: the begining</title> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>How do I get started?</title> - <para>So, after you have installed GTK+ there are a couple of - things that can ease you into developing applications with - it. There is the GTK+ Tutorial <ulink - url="http://www.gtk.org/tutorial/"> - http://www.gtk.org/tutorial/</ulink>, which is undergoing - development. This will introduce you to writing applications - using C.</para> - - <para>The Tutorial doesn't (yet) contain information on all of - the widgets that are in GTK+. For example code on how to use - the basics of all the GTK+ widgets you should look at the file - gtk/testgtk.c (and associated source files) within the GTK+ - distribution. Looking at these examples will give you a good - grounding on what the widgets can do.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>I tried to compile a small <command>Hello World</command> of mine, - but it failed. Any clue?</title> - <para>Since you are good at coding, we will not deal with - compile time error here :)</para> - - <para>The classic command line to compile a GTK+ based program is</para> - <para><literallayout><literal>gcc -o myprog [c files list] `gtk-config --cflags --libs`</literal></literallayout></para> - - <para>You should notice the backquote character which is used - in this command line. A common mistake when you start a GTK+ - based development is to use quote instead of backquotes. If - you do so, the compiler will complain about an unknown file - called <filename>gtk-config --cflags --libs</filename>. The - text in backquotes is an instruction to your shell to - substitute the output of executing this text into the - commandline.</para> - - <para>The command line above ensure that:</para> - <itemizedlist> - - <listitem><simpara>the correct C compiler flags will be used - to compile the program (including the complete C header - directory list)</simpara> - </listitem> - - <listitem><simpara>your program will be linked with the - needed libraries.</simpara> - </listitem> - </itemizedlist> - </sect2> - - <!-- ----------------------------------------------------------------- --> + </listitem> + + </itemizedlist> +</listitem> + +<listitem><simpara>Perl bindings <ulink +url="ftp://ftp.gtk.org/pub/gtk/perl"> +ftp://ftp.gtk.org/pub/gtk/perl</ulink></simpara> +</listitem> + +<listitem><simpara>Guile bindings. The home page is at +<ulink url="http://www.ping.de/sites/zagadka/guile-gtk"> +http://www.ping.de/sites/zagadka/guile-gtk</ulink>. +By the way, Guile is the GNU Project's implemention of R4RS Scheme (the +standard). If you like Scheme, you may want to take a look at +this.</simpara> +</listitem> + +<listitem><simpara>David Monniaux reports: +<quote>I've started a gtk-O'Caml binding system. +The basics of the system, including callbacks, work fine. + +The current development is in +<ulink url="http://www.ens-lyon.fr/~dmonniau/arcs"> +http://www.ens-lyon.fr/~dmonniau/arcs</ulink> +</quote></simpara> +</listitem> + +<listitem><simpara>Several python bindings have been done:</simpara> + + <itemizedlist> + <listitem><simpara>pygtk is at + <ulink url="http://www.daa.com.au/~james/pygtk"> + http://www.daa.com.au/~james/pygtk</ulink> and + <ulink url="ftp://ftp.gtk.org/pub/gtk/python"> + ftp://ftp.gtk.org/pub/gtk/python</ulink></simpara> + </listitem> + + <listitem><simpara>python-gtk is at + <ulink url="http://www.ucalgary.ca/~nascheme/python-gtk"> + http://www.ucalgary.ca/~nascheme/python-gtk</ulink></simpara> + </listitem> + + </itemizedlist> +</listitem> + +<listitem><simpara>There's are a couple of OpenGL/Mesa +widgets available for GTK+. I suggest you start at +<ulink url="http://www.student.oulu.fi/~jlof/gtkglarea/index.html"> +http://www.student.oulu.fi/~jlof/gtkglarea/index.html</ulink></simpara> +</listitem> +<listitem><simpara>Last, there are a lot of other language +bindings for languages such as Eiffel, TOM, Pascal, Pike, etc.</simpara> +</listitem> - <sect2> - <title>What about using the <command>make</command> - utility?</title> +</itemizedlist> +</sect2> + +</sect1> + +<!-- ***************************************************************** --> +<sect1> +<title>Development with GTK+: the begining</title> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>How do I get started?</title> + +<para>So, after you have installed GTK+ there are a couple of +things that can ease you into developing applications with +it. There is the GTK+ Tutorial <ulink +url="http://www.gtk.org/tutorial/"> +http://www.gtk.org/tutorial/</ulink>, which is undergoing +development. This will introduce you to writing applications +using C.</para> + +<para>The Tutorial doesn't (yet) contain information on all of +the widgets that are in GTK+. For example code on how to use +the basics of all the GTK+ widgets you should look at the file +gtk/testgtk.c (and associated source files) within the GTK+ +distribution. Looking at these examples will give you a good +grounding on what the widgets can do.</para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>I tried to compile a small <command>Hello World</command> of mine, +but it failed. Any clue?</title> + +<para>Since you are good at coding, we will not deal with +compile time error here :)</para> + +<para>The classic command line to compile a GTK+ based program is</para> +<para><literallayout> +<literal>gcc -o myprog [c files] `gtk-config --cflags --libs`</literal> +</literallayout></para> + +<para>You should notice the backquote character which is used +in this command line. A common mistake when you start a GTK+ +based development is to use quote instead of backquotes. If +you do so, the compiler will complain about an unknown file +called <filename>gtk-config --cflags --libs</filename>. The +text in backquotes is an instruction to your shell to +substitute the output of executing this text into the +commandline.</para> + +<para>The command line above ensure that:</para> + +<itemizedlist> +<listitem><simpara>the correct C compiler flags will be used +to compile the program (including the complete C header +directory list)</simpara> +</listitem> + +<listitem><simpara>your program will be linked with the +needed libraries.</simpara> +</listitem> +</itemizedlist> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>What about using the <command>make</command> +utility?</title> + +<para>This is a sample makefile which compile a GTK+ based +program:</para> - <para>This is a sample makefile which compile a GTK+ based - program:</para> <programlisting role="C"> # basic GTK+ app makefile SOURCES = myprg.c foo.c bar.c @@ -798,56 +964,60 @@ CC = gcc PACKAGE = myprg all : ${OBJS} - ${CC} -o ${PACKAGE} ${OBJS} ${LDADD} + ${CC} -o ${PACKAGE} ${OBJS} ${LDADD} .c.o: - ${CC} ${CFLAGS} -c $< + ${CC} ${CFLAGS} -c $< # end of file </programlisting> - <para>For more information about the <command>make</command> utility, you - should read either the related man page or the relevant info file.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>I use the backquote stuff in my makefiles, but my make - process failed.</title> - - <para>The backquote construction seems to not be accepted by - some old <command>make</command> utilities. If you use one of these, the - make process will probably fail. In order to have the - backquote syntax working again, you should use the GNU make - utility (get it on the GNU ftp server at <ulink - url="ftp://ftp.gnu.org/">ftp://ftp.gnu.org/"</ulink>).</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> +<para>For more information about the <command>make</command> utility, you +should read either the related man page or the relevant info file.</para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>I use the backquote stuff in my makefiles, but my make +process failed.</title> - <sect2> - <title>I want to add some configure stuff, how could I do - this?</title> +<para>The backquote construction seems to not be accepted by +some old <command>make</command> utilities. If you use one of these, the +make process will probably fail. In order to have the +backquote syntax working again, you should use the GNU make +utility (get it on the GNU ftp server at <ulink +url="ftp://ftp.gnu.org/">ftp://ftp.gnu.org/</ulink>).</para> - <para>To use autoconf/automake, you must first install the - relevant packages. These are:</para> +</sect2> - <itemizedlist spacing=Compact> - <listitem><simpara>the m4 preprocessor v1.4 or better</simpara> - </listitem> - <listitem><simpara>autoconf v2.13 or better</simpara> - </listitem> - <listitem><simpara>automake v1.4 or better</simpara> - </listitem> - </itemizedlist> +<!-- ----------------------------------------------------------------- --> - <para>You'll find these packages on the GNU main ftp server - (<ulink url="ftp://ftp.gnu.org/">ftp://ftp.gnu.org/</ulink>) - or on any GNU mirror.</para> +<sect2> +<title>I want to add some configure stuff, how could I do +this?</title> - <para>In order to use the powerful autoconf/automake scheme, - you must create a configure.in which may look like:</para> +<para>To use autoconf/automake, you must first install the +relevant packages. These are:</para> + +<itemizedlist spacing=Compact> +<listitem><simpara>the m4 preprocessor v1.4 or better</simpara> +</listitem> + +<listitem><simpara>autoconf v2.13 or better</simpara> +</listitem> + +<listitem><simpara>automake v1.4 or better</simpara> +</listitem> +</itemizedlist> + +<para>You'll find these packages on the GNU main ftp server +(<ulink url="ftp://ftp.gnu.org/">ftp://ftp.gnu.org/</ulink>) +or on any GNU mirror.</para> + +<para>In order to use the powerful autoconf/automake scheme, +you must create a configure.in which may look like:</para> <programlisting role="C"> dnl Process this file with autoconf to produce a configure script. @@ -869,7 +1039,7 @@ AC_OUTPUT( )dnl </programlisting> - <para>You must add a Makefile.am file:</para> +<para>You must add a Makefile.am file:</para> <programlisting role="C"> bin_PROGRAMS = myprg @@ -880,16 +1050,16 @@ CLEANFILES = *~ DISTCLEANFILES = .deps/*.P </programlisting> - <para>If your project contains more than one subdirectory, - you'll have to create one Makefile.am in each directory plus a - master Makefile.am which will look like:</para> +<para>If your project contains more than one subdirectory, +you'll have to create one Makefile.am in each directory plus a +master Makefile.am which will look like:</para> <programlisting role="C"> SUBDIRS = mydir1 mydir2 mydir3 </programlisting> - <para>then, to use these, simply type the following - commands:</para> +<para>then, to use these, simply type the following +commands:</para> <programlisting role="C"> aclocal @@ -898,46 +1068,52 @@ autoconf automake --add-missing --include-deps --foreign </programlisting> - <para>For further information, you should look at the autoconf - and the automake documentation (the shipped info files are - really easy to understand, and there are plenty of web - resources that deal with autoconf and automake).</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>I try to debug my GTK+ application with gdb, but it - hangs my X server when I hit some breakpoint. Any - Idea?</title> - - <para>From Federico Mena Quintero: - <quote>X is not locked up. It is likely that you are hitting a breakpoint - inside a callback that is called from a place in Gtk that has a mouse grab. - - Run your program with the <literal>--sync</literal> - option; it will make it easier to debug. Also, you may want to - use the console for running the debugger, and just let the - program run in another console with the X server.</quote></para> - - <para>Eric Mouw had another solution: - <quote>An old terminal connected to an otherwise unused serial - port is also great for debugging X programs. Old vt100/vt220 - terminals are dirt cheap but a bit hard to get (here in The - Netherlands, YMMV).</quote></para> - </sect2> - </sect1> - - <!-- ***************************************************************** --> - <sect1> - <title>Development with GTK+: general questions</title> - - <!-- ----------------------------------------------------------------- --> +<para>For further information, you should look at the autoconf +and the automake documentation (the shipped info files are +really easy to understand, and there are plenty of web +resources that deal with autoconf and automake).</para> - <sect2> - <title>What widgets are in GTK?</title> +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>I try to debug my GTK+ application with gdb, but it +hangs my X server when I hit some breakpoint. Any +Idea?</title> + +<para>From Federico Mena Quintero:</para> + +<para><quote>X is not locked up. It is likely that you are hitting a +breakpoint inside a callback that is called from a place in Gtk that has +a mouse grab.</quote></para> + +<para><quote>Run your program with the <literal>--sync</literal> +option; it will make it easier to debug. Also, you may want to +use the console for running the debugger, and just let the +program run in another console with the X server.</quote></para> + +<para>Eric Mouw had another solution:</para> + +<para><quote>An old terminal connected to an otherwise unused serial +port is also great for debugging X programs. Old vt100/vt220 +terminals are dirt cheap but a bit hard to get (here in The +Netherlands, YMMV).</quote></para> + +</sect2> +</sect1> + +<!-- ***************************************************************** --> +<sect1> +<title>Development with GTK+: general questions</title> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>What widgets are in GTK?</title> + +<para>The GTK+ Tutorial lists the following widgets:</para> - <para>The GTK+ Tutorial lists the following widgets:</para> <programlisting role="C"> GtkObject +GtkData @@ -1021,32 +1197,32 @@ automake --add-missing --include-deps --foreign +GtkHSeparator `GtkVSeparator </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> - <sect2> - <title>Is GTK+ thread safe? How do I write multi-threaded GTK+ - applications?</title> +<!-- ----------------------------------------------------------------- --> - <para>The GLib library can be used in a thread-safe mode by - calling g_thread_init() before making any other GLib - calls. In this mode GLib automatically locks all internal - data structures as needed. This does not mean that two - threads can simultaneously access, for example, a single hash - table, but they can access two different hash tables - simultaneously. If two different threads need to access the - same hash table, the application is responsible for locking - itself.</para> +<sect2> +<title>Is GTK+ thread safe? How do I write multi-threaded GTK+ +applications?</title> - <para>When GLib is intialized to be thread-safe, GTK+ is - <emphasis>thread aware</emphasis>. There is a single global - lock that you must acquire with gdk_threads_enter() before - making any GDK calls, and release with gdk_threads_leave() - afterwards.</para> +<para>The GLib library can be used in a thread-safe mode by +calling g_thread_init() before making any other GLib +calls. In this mode GLib automatically locks all internal +data structures as needed. This does not mean that two +threads can simultaneously access, for example, a single hash +table, but they can access two different hash tables +simultaneously. If two different threads need to access the +same hash table, the application is responsible for locking +itself.</para> - <para>A minimal main program for a threaded GTK+ application - looks like:</para> +<para>When GLib is intialized to be thread-safe, GTK+ is +<emphasis>thread aware</emphasis>. There is a single global +lock that you must acquire with gdk_threads_enter() before +making any GDK calls, and release with gdk_threads_leave() +afterwards.</para> + +<para>A minimal main program for a threaded GTK+ application +looks like:</para> <programlisting role="C"> int @@ -1068,15 +1244,15 @@ main (int argc, char *argv[]) } </programlisting> - <para>Callbacks require a bit of attention. Callbacks from - GTK+ (signals) are made within the GTK+ lock. However - callbacks from GLib (timeouts, IO callbacks, and idle - functions) are made outside of the GTK+ lock. So, within a - signal handler you do not need to call gdk_threads_enter(), - but within the other types of callbacks, you do.</para> +<para>Callbacks require a bit of attention. Callbacks from +GTK+ (signals) are made within the GTK+ lock. However +callbacks from GLib (timeouts, IO callbacks, and idle +functions) are made outside of the GTK+ lock. So, within a +signal handler you do not need to call gdk_threads_enter(), +but within the other types of callbacks, you do.</para> - <para>Erik Mouw contributed the following code example to - illustrate how to use threads within GTK+ programs.</para> +<para>Erik Mouw contributed the following code example to +illustrate how to use threads within GTK+ programs.</para> <programlisting role="C"> /*------------------------------------------------------------------------- @@ -1217,29 +1393,29 @@ int main(int argc, char *argv[]) return(0); } </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> - <sect2> - <title>Why does this strange 'x io error' occur when I - <literal>fork()</literal> in my GTK+ app?</title> +<!-- ----------------------------------------------------------------- --> - <para>This is not really a GTK+ problem, and the problem is - not related to <literal>fork()</literal> either. If the 'x io - error' occurs then you probably use the <literal>exit()</literal> function - in order to exit from the child process.</para> +<sect2> +<title>Why does this strange 'x io error' occur when I +<literal>fork()</literal> in my GTK+ app?</title> - <para>When GDK opens an X display, it creates a socket file - descriptor. When you use the <literal>exit()</literal> - function, you implicitly close all the open file descriptors, - and the underlying X library really doesn't like this.</para> +<para>This is not really a GTK+ problem, and the problem is +not related to <literal>fork()</literal> either. If the 'x io +error' occurs then you probably use the <literal>exit()</literal> function +in order to exit from the child process.</para> - <para>The right function to use here is - <literal>_exit()</literal>.</para> +<para>When GDK opens an X display, it creates a socket file +descriptor. When you use the <literal>exit()</literal> +function, you implicitly close all the open file descriptors, +and the underlying X library really doesn't like this.</para> - <para>Erik Mouw contributed the following code example to - illustrate handling fork() and exit().</para> +<para>The right function to use here is +<literal>_exit()</literal>.</para> + +<para>Erik Mouw contributed the following code example to +illustrate handling fork() and exit().</para> <programlisting role="C"> /*------------------------------------------------------------------------- @@ -1411,91 +1587,93 @@ int main(int argc, char *argv[]) exit(0); } </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>Why don't the contents of a button move when the button - is pressed? Here's a patch to make it work that way...</title> - - <para>From: Peter Mattis - <quote>The reason buttons don't move their child down and to - the right when they are depressed is because I don't think - that's what is happening visually. My view of buttons is - that you are looking at them straight on. That is, the user - interface lies in a plane and you're above it looking - straight at it. When a button gets pressed it moves directly - away from you. To be absolutely correct I guess the child - should actually shrink a tiny amount. But I don't see why - the child should shift down and to the left. Remember, the - child is supposed to be attached to the buttons surface. Its - not good for it to appear like the child is slipping on the - surface of the button. - - On a more practical note, I did implement this at one point - and determined it didn't look good and removed - it.</quote></para> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>Why don't the contents of a button move when the button +is pressed? Here's a patch to make it work that way...</title> + +<para>From: Peter Mattis</para> + +<para><quote>The reason buttons don't move their child down and to +the right when they are depressed is because I don't think +that's what is happening visually. My view of buttons is +that you are looking at them straight on. That is, the user +interface lies in a plane and you're above it looking +straight at it. When a button gets pressed it moves directly +away from you. To be absolutely correct I guess the child +should actually shrink a tiny amount. But I don't see why +the child should shift down and to the left. Remember, the +child is supposed to be attached to the buttons surface. Its +not good for it to appear like the child is slipping on the +surface of the button.</quote></para> - <sect2> - <title>How do I identifiy a widgets top level window or other - ancestor?</title> +<para><quote>On a more practical note, I did implement this at one point +and determined it didn't look good and removed it.</quote></para> - <para>There are a couple of ways to find the top level parent - of a widget. The easier way is to call the - <literal>gtk_widget_top_level()</literal> function that - returns pointer to a GtkWidget that is the top level - window.</para> +</sect2> - <para>A more complicated way to do this (but less limited, as - it allows the user to get the closest ancestor of a known type) is to use - <literal>gtk_widget_get_ancestor()</literal> as in:</para> +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>How do I identifiy a widgets top level window or other +ancestor?</title> + +<para>There are a couple of ways to find the top level parent +of a widget. The easier way is to call the +<literal>gtk_widget_top_level()</literal> function that +returns pointer to a GtkWidget that is the top level +window.</para> + +<para>A more complicated way to do this (but less limited, as +it allows the user to get the closest ancestor of a known type) is to use +<literal>gtk_widget_get_ancestor()</literal> as in:</para> <programlisting role="C"> GtkWidget *widget; widget = gtk_widget_get_ancestor(w, GTK_TYPE_WINDOW); </programlisting> - <para>Since virtually all the GTK_TYPEs can be used as the - second parameter of this function, you can get any parent - widget of a particular widget. Suppose you have an hbox which - contains a vbox, which in turn contains some other atomic - widget (entry, label, etc. To find the master hbox using the - <literal>entry</literal> widget simply use:</para> +<para>Since virtually all the GTK_TYPEs can be used as the +second parameter of this function, you can get any parent +widget of a particular widget. Suppose you have an hbox which +contains a vbox, which in turn contains some other atomic +widget (entry, label, etc. To find the master hbox using the +<literal>entry</literal> widget simply use:</para> <programlisting role="C"> GtkWidget *hbox; hbox = gtk_widget_get_ancestor(w, GTK_TYPE_HBOX); </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> - <sect2> - <title>How do I get the Window ID of a GtkWindow?</title> +</sect2> - <para>The actual Gdk/X window will be created when the widget - gets realized. You can get the Window ID with:</para> +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>How do I get the Window ID of a GtkWindow?</title> + +<para>The actual Gdk/X window will be created when the widget +gets realized. You can get the Window ID with:</para> <programlisting role="C"> #include <gdk/gdkx.h> Window xwin = GDK_WINDOW_XWINDOW (GTK_WIDGET (my_window)->window); </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> + +<!-- ----------------------------------------------------------------- --> - <sect2> - <title>How do I catch a double click event (in a list widget, - for example)?</title> +<sect2> +<title>How do I catch a double click event (in a list widget, +for example)?</title> - <para>Tim Janik wrote to gtk-list (slightly modified):</para> +<para>Tim Janik wrote to gtk-list (slightly modified):</para> - <para>Define a signal handler:</para> +<para>Define a signal handler:</para> <programlisting role="C"> gint @@ -1512,7 +1690,7 @@ signal_handler_event(GtkWiget *widget, GdkEvenButton *event, gpointer func_data) return FALSE; }</programlisting> - <para>And connect the handler to your object:</para> +<para>And connect the handler to your object:</para> <programlisting role="C"> { @@ -1534,61 +1712,65 @@ signal_handler_event(GtkWiget *widget, GdkEvenButton *event, gpointer func_data) } </programlisting> - <para>and, Owen Taylor wrote: - <quote>Note that a single button press will be received - beforehand, and if you are doing this for a button, you will - therefore also get a "clicked" signal for the button. (This - is going to be true for any toolkit, since computers aren't - good at reading one's mind.)</quote></para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>By the way, what are the differences between signals - and events?</title> - - <para>First of all, Havoc Pennington gives a rather complete - description of the differences between events and signals in - his free book (two chapters can be found at <ulink - url="http://www106.pair.com/rhp/sample_chapters.html"> - http://www106.pair.com/rhp/sample_chapters.html</ulink>).</para> - - <para>Moreover, Havoc posted this to the <literal>gtk-list</literal> - <quote>Events are a stream of messages received from the X - server. They drive the Gtk main loop; which more or less - amounts to "wait for events, process them" (not exactly, it - is really more general than that and can wait on many - different input streams at once). Events are a Gdk/Xlib - concept.</quote></para> - - <para><quote>Signals are a feature of GtkObject and its subclasses. They have - nothing to do with any input stream; really a signal is just a way - to keep a list of callbacks around and invoke them ("emit" the - signal). There are lots of details and extra features of - course. Signals are emitted by object instances, and are entirely - unrelated to the Gtk main loop. Conventionally, signals are emitted - "when something changes" about the object emitting the signal.</quote></para> - - <para><quote>Signals and events only come together because GtkWidget happens to - emit signals when it gets events. This is purely a convenience, so - you can connect callbacks to be invoked when a particular widget - receives a particular event. There is nothing about this that makes - signals and events inherently related concepts, any more than - emitting a signal when you click a button makes button clicking and - signals related concepts.</quote></para> - </sect2> - - <!-- ----------------------------------------------------------------- --> +<para>and, Owen Taylor wrote:</para> + +<para><quote>Note that a single button press will be received +beforehand, and if you are doing this for a button, you will +therefore also get a "clicked" signal for the button. (This +is going to be true for any toolkit, since computers aren't +good at reading one's mind.)</quote></para> + +</sect2> - <sect2> - <title>Data I pass to the <literal>delete_event</literal> (or other event) - handler gets corrupted.</title> +<!-- ----------------------------------------------------------------- --> - <para>All event handlers take an additional argument which - contains information about the event that triggered the - handler. So, a <literal>delete_event</literal> handler must - be declared as:</para> +<sect2> +<title>By the way, what are the differences between signals +and events?</title> + +<para>First of all, Havoc Pennington gives a rather complete +description of the differences between events and signals in +his free book (two chapters can be found at <ulink +url="http://www106.pair.com/rhp/sample_chapters.html"> +http://www106.pair.com/rhp/sample_chapters.html</ulink>).</para> + +<para>Moreover, Havoc posted this to the <literal>gtk-list</literal> +<quote>Events are a stream of messages received from the X +server. They drive the Gtk main loop; which more or less +amounts to "wait for events, process them" (not exactly, it +is really more general than that and can wait on many +different input streams at once). Events are a Gdk/Xlib +concept.</quote></para> + +<para><quote>Signals are a feature of GtkObject and its subclasses. They +have nothing to do with any input stream; really a signal is just a way +to keep a list of callbacks around and invoke them ("emit" the +signal). There are lots of details and extra features of +course. Signals are emitted by object instances, and are entirely +unrelated to the Gtk main loop. Conventionally, signals are emitted +"when something changes" about the object emitting the +signal.</quote></para> + +<para><quote>Signals and events only come together because GtkWidget +happens to emit signals when it gets events. This is purely a +convenience, so you can connect callbacks to be invoked when a +particular widget receives a particular event. There is nothing about +this that makes signals and events inherently related concepts, any more +than emitting a signal when you click a button makes button clicking and +signals related concepts.</quote></para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>Data I pass to the <literal>delete_event</literal> (or other event) +handler gets corrupted.</title> + +<para>All event handlers take an additional argument which +contains information about the event that triggered the +handler. So, a <literal>delete_event</literal> handler must +be declared as:</para> <programlisting role="C"> @@ -1596,54 +1778,56 @@ gint delete_event_handler (GtkWidget *widget, GdkEventAny *event, gpointer data); </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> - <sect2> - <title>I have my signal connected to the the (whatever) event, - but it seems I don't catch it. What's wrong?</title> +</sect2> - <para>There is some special initialisation to do in order to - catch some particular events. In fact, you must set the - correct event mask bit of your widget before getting some - particular events.</para> +<!-- ----------------------------------------------------------------- --> - <para>For example,</para> +<sect2> +<title>I have my signal connected to the the (whatever) event, +but it seems I don't catch it. What's wrong?</title> + +<para>There is some special initialisation to do in order to +catch some particular events. In fact, you must set the +correct event mask bit of your widget before getting some +particular events.</para> + +<para>For example,</para> <programlisting role="C"> gtk_widget_add_events(window, GDK_KEY_RELEASE_MASK); </programlisting> - <para>lets you catch the key release events. If you want to - catch every events, simply us the GDK_ALL_EVENTS_MASK event - mask.</para> +<para>lets you catch the key release events. If you want to +catch every events, simply us the GDK_ALL_EVENTS_MASK event +mask.</para> - <para>All the event masks are defined in the - <filename>gdktypes.h</filename> file.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> +<para>All the event masks are defined in the +<filename>gdktypes.h</filename> file.</para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> - <sect2> - <title>I need to add a new signal to a GTK+ widget. Any - idea?</title> +<sect2> +<title>I need to add a new signal to a GTK+ widget. Any +idea?</title> - <para>If the signal you want to add may be beneficial for - other GTK+ users, you may want to submit a patch that - presents your changes. Check the tutorial for more - information about adding signals to a widget class.</para> +<para>If the signal you want to add may be beneficial for +other GTK+ users, you may want to submit a patch that +presents your changes. Check the tutorial for more +information about adding signals to a widget class.</para> - <para>If you don't think it is the case or if your patch is - not applied you'll have to use the - <literal>gtk_object_class_user_signal_new</literal> - function. <literal>gtk_object_class_user_signal_new</literal> allows you to - add a new signal to a predefined GTK+ widget without any - modification of the GTK+ source code. The new signal can be - emited with <literal>gtk_signal_emit</literal> and can be - handled in the same way as other signals.</para> +<para>If you don't think it is the case or if your patch is +not applied you'll have to use the +<literal>gtk_object_class_user_signal_new</literal> +function. <literal>gtk_object_class_user_signal_new</literal> allows you +to add a new signal to a predefined GTK+ widget without any +modification of the GTK+ source code. The new signal can be +emited with <literal>gtk_signal_emit</literal> and can be +handled in the same way as other signals.</para> - <para>Tim Janik posted this code snippet:</para> +<para>Tim Janik posted this code snippet:</para> <programlisting role="C"> static guint signal_user_action = 0; @@ -1666,30 +1850,31 @@ gtk_widget_user_action (GtkWidget *widget, } </programlisting> - <para>If you want your new signal to have more than the - classical gpointer parameter, you'll have to play with GTK+ - marshallers.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> +<para>If you want your new signal to have more than the +classical gpointer parameter, you'll have to play with GTK+ +marshallers.</para> + +</sect2> - <sect2> - <title>Is it possible to get some text displayed which is - truncated to fit inside its allocation?</title> +<!-- ----------------------------------------------------------------- --> - <para>GTK's behavior (no clipping) is a consequence of its - attempts to conserve X resources. Label widgets (among - others) don't get their own X window - they just draw their - contents on their parent's window. While it might be possible - to have clipping occur by setting the clip mask before - drawing the text, this would probably cause a substantial - performance penalty.</para> +<sect2> +<title>Is it possible to get some text displayed which is +truncated to fit inside its allocation?</title> - <para>Its possible that, in the long term, the best solution - to such problems might be just to change gtk to give labels X - windows. A short term workaround is to put the label widget - inside another widget that does get its own window - one - possible candidate would be the viewport widget.</para> +<para>GTK's behavior (no clipping) is a consequence of its +attempts to conserve X resources. Label widgets (among +others) don't get their own X window - they just draw their +contents on their parent's window. While it might be possible +to have clipping occur by setting the clip mask before +drawing the text, this would probably cause a substantial +performance penalty.</para> + +<para>Its possible that, in the long term, the best solution +to such problems might be just to change gtk to give labels X +windows. A short term workaround is to put the label widget +inside another widget that does get its own window - one +possible candidate would be the viewport widget.</para> <programlisting role="C"> viewport = gtk_viewport (NULL, NULL); @@ -1702,65 +1887,66 @@ gtk_container_add (GTK_CONTAINER(viewport), label); gtk_widget_show (label); </programlisting> - <para>If you were doing this for a bunch of widgets, you might - want to copy gtkviewport.c and strip out the adjustment and - shadow functionality (perhaps you could call it - GtkClipper).</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> +<para>If you were doing this for a bunch of widgets, you might +want to copy gtkviewport.c and strip out the adjustment and +shadow functionality (perhaps you could call it +GtkClipper).</para> +</sect2> - <sect2> - <title>How do I make my window modal? / How do I make a single - window active?</title> +<!-- ----------------------------------------------------------------- --> - <para>After you create your window, do - <literal>gtk_grab_add(my_window)</literal>. And after closing - the window do - <literal>gtk_grab_remove(my_window)</literal>.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> +<sect2> +<title>How do I make my window modal? / How do I make a single +window active?</title> + +<para>After you create your window, do +<literal>gtk_grab_add(my_window)</literal>. And after closing the window +do <literal>gtk_grab_remove(my_window)</literal>.</para> + +</sect2> - <sect2> - <title>Why doesn't my widget (e.g. progressbar) - update?</title> +<!-- ----------------------------------------------------------------- --> - <para>You are probably doing all the changes within a function without - returning control to <literal>gtk_main()</literal>. This may - be the case if you do some lengthy calculation in your - code. Most drawing updates are only placed on a queue, which - is processed within <literal>gtk_main()</literal>. You can force the - drawing queue to be processed using something like:</para> +<sect2> +<title>Why doesn't my widget (e.g. progressbar) +update?</title> + +<para>You are probably doing all the changes within a function without +returning control to <literal>gtk_main()</literal>. This may +be the case if you do some lengthy calculation in your +code. Most drawing updates are only placed on a queue, which +is processed within <literal>gtk_main()</literal>. You can force the +drawing queue to be processed using something like:</para> <programlisting role="C"> while (gtk_main_iteration()); </programlisting> - <para>inside you're function that changes the widget.</para> +<para>inside you're function that changes the widget.</para> - <para>What the above snippet does is run all pending events - and high priority idle functions, then return immediately - (the drawing is done in a high priority idle function).</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> +<para>What the above snippet does is run all pending events +and high priority idle functions, then return immediately +(the drawing is done in a high priority idle function).</para> - <sect2> - <title>How do I attach data to some GTK+ object/widget?</title> +</sect2> - <para>First of all, the attached data is stored in the - object_data field of a GtkObject. The type of this field is - GData, which is defined in glib.h. So you should read the - gdataset.c file in your glib source directory very - carefully.</para> +<!-- ----------------------------------------------------------------- --> - <para>There are two (easy) ways to attach some data to a gtk - object. Using <literal>gtk_object_set_data()</literal> and - <literal>gtk_object_get_data()</literal> seems to be the most - common way to do this, as it provides a powerful interface to - connect objects and data.</para> +<sect2> +<title>How do I attach data to some GTK+ object/widget?</title> + +<para>First of all, the attached data is stored in the +object_data field of a GtkObject. The type of this field is +GData, which is defined in glib.h. So you should read the +gdataset.c file in your glib source directory very +carefully.</para> + +<para>There are two (easy) ways to attach some data to a gtk +object. Using <literal>gtk_object_set_data()</literal> and +<literal>gtk_object_get_data()</literal> seems to be the most +common way to do this, as it provides a powerful interface to +connect objects and data.</para> <programlisting role="C"> void gtk_object_set_data(GtkObject *object, const gchar *key, gpointer data); @@ -1768,7 +1954,7 @@ void gtk_object_set_data(GtkObject *object, const gchar *key, gpointer data); gpointer gtk_object_get_data(GtkObject *object, const gchar *key); </programlisting> - <para>Since a short example is better than any lengthy speech:</para> +<para>Since a short example is better than any lengthy speech:</para> <programlisting role="C"> struct my_struct p1,p2,*result; @@ -1780,66 +1966,71 @@ gtk_object_set_data(GTK_OBJECT(w),"p2 data",(gpointer)&p2); result = gtk_object_get_data(GTK_OBJECT(w),"p1 data"); </programlisting> - <para>The <literal>gtk_object_set_user_data()</literal> and - <literal>gtk_object_get_user_data()</literal> functions does - exactly the same thing as the functions above, but does not - let you specify the "key" parameter.Instead, it uses a - standard "user_data" key. Note that the use of these functions - is deprecated in 1.2. They only provide a compatibility mode - with some old gtk packages.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>How do I remove the data I have attached to an - object?</title> - - <para>When attaching the data to the object, you can use the - <literal>gtk_object_set_data_full()</literal> function. The three - first arguments of the function are the same as in - <literal>gtk_object_set_data()</literal>. The fourth one is a - pointer to a callback function which is called when the data - is destroyed. The data is destroyed when you:</para> - - <itemizedlist> - <listitem><simpara> destroy the object</simpara> - </listitem> - <listitem><simpara> replace the data with a new one (with - the same key)</simpara> - </listitem> - <listitem><simpara> replace the data with NULL (with the - same key)</simpara> - </listitem> - </itemizedlist> - </sect2> - - <!-- ----------------------------------------------------------------- --> +<para>The <literal>gtk_object_set_user_data()</literal> and +<literal>gtk_object_get_user_data()</literal> functions does +exactly the same thing as the functions above, but does not +let you specify the "key" parameter.Instead, it uses a +standard "user_data" key. Note that the use of these functions +is deprecated in 1.2. They only provide a compatibility mode +with some old gtk packages.</para> - <sect2> - <title>How do I reparent a widget?</title> +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>How do I remove the data I have attached to an +object?</title> + +<para>When attaching the data to the object, you can use the +<literal>gtk_object_set_data_full()</literal> function. The three +first arguments of the function are the same as in +<literal>gtk_object_set_data()</literal>. The fourth one is a +pointer to a callback function which is called when the data +is destroyed. The data is destroyed when you:</para> + +<itemizedlist> +<listitem><simpara> destroy the object</simpara> +</listitem> + +<listitem><simpara> replace the data with a new one (with +the same key)</simpara> +</listitem> + +<listitem><simpara> replace the data with NULL (with the +same key)</simpara> +</listitem> + +</itemizedlist> - <para>The normal way to reparent (ie change the owner) of a - widget should be to use the function:</para> +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>How do I reparent a widget?</title> + +<para>The normal way to reparent (ie change the owner) of a +widget should be to use the function:</para> <programlisting role="C"> void gtk_widget_reparent (GtkWidget *widget, GtkWidget *new_parent) </programlisting> - <para>But this is only a "should be" since this function does - not correctly do its job on some specific widgets. The main - goal of gtk_widget_reparent() is to avoid unrealizing widget - if both widget and new_parent are realized (in this case, - widget->window is successfully reparented). The problem here - is that some widgets in the GTK+ hierarchy have multiple - attached X subwindows and this is notably the case for the - GtkSpinButton widget. For those, gtk_widget_reparent() will - fail by leaving an unrealized child window where it should - not.</para> +<para>But this is only a "should be" since this function does +not correctly do its job on some specific widgets. The main +goal of gtk_widget_reparent() is to avoid unrealizing widget +if both widget and new_parent are realized (in this case, +widget->window is successfully reparented). The problem here +is that some widgets in the GTK+ hierarchy have multiple +attached X subwindows and this is notably the case for the +GtkSpinButton widget. For those, gtk_widget_reparent() will +fail by leaving an unrealized child window where it should +not.</para> - <para>To avoid this problem, simply use the following code - snippet:</para> +<para>To avoid this problem, simply use the following code +snippet:</para> <programlisting role="C"> gtk_widget_ref(widget); @@ -1847,59 +2038,65 @@ void gtk_widget_reparent (GtkWidget *widget, gtk_container_add(GTK_CONTAINER(new_parent), widget); gtk_widget_unref(widget); </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>How could I get any widgets position?</title> - - <para>As Tim Janik pointed out, there are different cases, and - each case requires a different solution.</para> - - <itemizedlist> - <listitem><simpara> If you want the position of a widget - relative to its parent, you should use - <literal>widget->allocation.x</literal> and - <literal>widget->allocation.y</literal>.</simpara> - </listitem> - <listitem><simpara> If you want the position of a window - relative to the X root window, you should use <literal>gdk_window_get_geometry()</literal> - <literal>gdk_window_get_position()</literal> or - <literal>gdk_window_get_origin()</literal>.</simpara> - </listitem> - <listitem><simpara> If you want to get the position of the - window (including the WM decorations), you should use - <literal>gdk_window_get_root_origin()</literal>.</simpara> - </listitem> - <listitem><simpara> Last but not least, if you want to get a Window Manager frame - position, you should use - <literal>gdk_window_get_deskrelative_origin()</literal>.</simpara> - </listitem> + +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>How could I get any widgets position?</title> + +<para>As Tim Janik pointed out, there are different cases, and +each case requires a different solution.</para> + +<itemizedlist> +<listitem><simpara> If you want the position of a widget +relative to its parent, you should use +<literal>widget->allocation.x</literal> and +<literal>widget->allocation.y</literal>.</simpara> +</listitem> + +<listitem><simpara> If you want the position of a window +relative to the X root window, you should use +<literal>gdk_window_get_geometry()</literal> +<literal>gdk_window_get_position()</literal> or +<literal>gdk_window_get_origin()</literal>.</simpara> +</listitem> + +<listitem><simpara> If you want to get the position of the +window (including the WM decorations), you should use +<literal>gdk_window_get_root_origin()</literal>.</simpara> +</listitem> + +<listitem><simpara> Last but not least, if you want to get a Window +Manager frame position, you should use +<literal>gdk_window_get_deskrelative_origin()</literal>.</simpara> +</listitem> </itemizedlist> - <para>Your choice of Window Manager will have an effect of the - results of the above functions. You should keep this in mind - when writing your application. This is dependant upon how the - Window Managers manage the decorations that they add around - windows.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> +<para>Your choice of Window Manager will have an effect of the +results of the above functions. You should keep this in mind +when writing your application. This is dependant upon how the +Window Managers manage the decorations that they add around +windows.</para> - <sect2> - <title>How do I set the size of a widget/window? How do I - prevent the user resizing my window?</title> +</sect2> - <para>The <literal>gtk_widget_set_uposition()</literal> - function is used to set the position of any widget.</para> +<!-- ----------------------------------------------------------------- --> - <para>The <literal>gtk_widget_set_usize()</literal> function - is used to set the size of a widget. In order to use all the - features that are provided by this function when it acts on a - window, you may want to use the - <literal>gtk_window_set_policy</literal> function. The - definition of these functions are:</para> +<sect2> +<title>How do I set the size of a widget/window? How do I +prevent the user resizing my window?</title> + +<para>The <literal>gtk_widget_set_uposition()</literal> +function is used to set the position of any widget.</para> + +<para>The <literal>gtk_widget_set_usize()</literal> function +is used to set the size of a widget. In order to use all the +features that are provided by this function when it acts on a +window, you may want to use the +<literal>gtk_window_set_policy</literal> function. The +definition of these functions are:</para> <programlisting role="C"> void gtk_widget_set_usize (GtkWidget *widget, @@ -1912,14 +2109,14 @@ void gtk_window_set_policy (GtkWindow *window, gint auto_shrink); </programlisting> - <para><literal>Auto_shrink</literal> will automatically shrink - the window when the requested size of the child widgets goes - below the current size of the - window. <literal>Allow_shrink</literal> will give the user the - authorisation to make the window smaller that it should - normally be. <literal>Allow_grow</literal> will give the user - will have the ability to make the window bigger. The default - values for these parameters are:</para> +<para><literal>Auto_shrink</literal> will automatically shrink +the window when the requested size of the child widgets goes +below the current size of the +window. <literal>Allow_shrink</literal> will give the user the +authorisation to make the window smaller that it should +normally be. <literal>Allow_grow</literal> will give the user +will have the ability to make the window bigger. The default +values for these parameters are:</para> <programlisting role="C"> allow_shrink = FALSE @@ -1927,37 +2124,36 @@ allow_grow = TRUE auto_shrink = FALSE </programlisting> - <para>The <literal>gtk_widget_set_usize()</literal> functions - is not the easiest way to set a window size since you cannot - decrease this window size with another call to this function - unless you call it twice, as in:</para> +<para>The <literal>gtk_widget_set_usize()</literal> functions +is not the easiest way to set a window size since you cannot +decrease this window size with another call to this function +unless you call it twice, as in:</para> <programlisting role="C"> gtk_widget_set_usize(your_widget, -1, -1); gtk_widget_set_usize(your_widget, new_x_size, new_y_size); </programlisting> - <para>Another way to set the size of and/or move a window is to use - the <literal>gdk_window_move_resize()</literal> function which - uses to work fine both to grow or to shrink the window:</para> +<para>Another way to set the size of and/or move a window is to use +the <literal>gdk_window_move_resize()</literal> function which +uses to work fine both to grow or to shrink the window:</para> <programlisting role="C"> gdk_window_move_resize(window->window, x_pos, y_pos, x_size, y_size); </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> - <sect2> - <title>How do I add a popup menu to my GTK+ - application?</title> +</sect2> + +<!-- ----------------------------------------------------------------- --> - <para>The <literal>menu</literal> example in the examples/menu - directory of the GTK+ distribution implements a popup menu - with this technique:</para> +<sect2> +<title>How do I add a popup menu to my GTK+ application?</title> +<para>The <literal>menu</literal> example in the examples/menu +directory of the GTK+ distribution implements a popup menu +with this technique:</para> <programlisting role="C"> static gint button_press (GtkWidget *widget, GdkEvent *event) @@ -1976,89 +2172,90 @@ static gint button_press (GtkWidget *widget, GdkEvent *event) return FALSE; } </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> - <sect2> - <title>How do I disable or enable a widget, such as a - button?</title> +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>How do I disable or enable a widget, such as a +button?</title> - <para>To disable (or to enable) a widget, use the - <literal>gtk_widget_set_sensitive()</literal> function. The - first parameter is you widget pointer. The second parameter is - a boolean value: when this value is TRUE, the widget is - enabled.</para> - </sect2> +<para>To disable (or to enable) a widget, use the +<literal>gtk_widget_set_sensitive()</literal> function. The +first parameter is you widget pointer. The second parameter is +a boolean value: when this value is TRUE, the widget is +enabled.</para> +</sect2> - <!-- ----------------------------------------------------------------- --> +<!-- ----------------------------------------------------------------- --> - <sect2> - <title>Shouldn't the text argument in the gtk_clist_* - functions be declared const?</title> +<sect2> +<title>Shouldn't the text argument in the gtk_clist_* +functions be declared const?</title> - <para>For example:</para> +<para>For example:</para> <programlisting role="C"> gint gtk_clist_prepend (GtkCList *clist, gchar *text[]); </programlisting> - <para>Answer: No, while a type "gchar*" (pointer to char) can - automatically be cast into "const gchar*" (pointer to const - char), this does not apply for "gchar *[]" (array of an - unspecified number of pointers to char) into "const gchar *[]" - (array of an unspecified number of pointers to const char).</para> - - <para>The type qualifier "const" may be subject to automatic - casting, but in the array case, it is not the array itself - that needs the (const) qualified cast, but its members, thus - changing the whole type.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>How do I render pixels (image data) to the - screen?</title> - - <para>There are several ways to approach this. The simplest - way is to use GdkRGB, see gdk/gdkrgb.h. You create an RGB - buffer, render to your RGB buffer, then use GdkRGB routines to - copy your RGB buffer to a drawing area or custom widget. The - book "GTK+/Gnome Application Development" gives some details; - GdkRGB is also documented in the GTK+ reference - documentation.</para> - - <para>If you're writing a game or other graphics-intensive - application, you might consider a more elaborate - solution. OpenGL is the graphics standard that will let you - access hardware accelaration in future versions of XFree86; so - for maximum speed, you probably want to use OpenGL. A - GtkGLArea widget is available for using OpenGL with GTK+ (but - GtkGLArea does not come with GTK+ itself). There are also - several open source game libraries, such as ClanLib and Loki's - Simple DirectMedia Layer library (SDL).</para> - - <para>You do NOT want to use - <literal>gdk_draw_point()</literal>, that will be extremely - slow.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>How do I create a pixmap without having my window being - realized/shown?</title> - - <para>Functions such as - <literal>gdk_pixmap_create_from_xpm()</literal> require a - valid window as a parameter. During the initialisation phase - of an application, a valid window may not be available without - showing a window, which may be inappropriate. In order to - avoid this, a function such as - <literal>gdk_pixmap_colormap_create_from_xpm</literal> can be - used, as in:</para> +<para>Answer: No, while a type "gchar*" (pointer to char) can +automatically be cast into "const gchar*" (pointer to const +char), this does not apply for "gchar *[]" (array of an +unspecified number of pointers to char) into "const gchar *[]" +(array of an unspecified number of pointers to const char).</para> + +<para>The type qualifier "const" may be subject to automatic +casting, but in the array case, it is not the array itself +that needs the (const) qualified cast, but its members, thus +changing the whole type.</para> +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>How do I render pixels (image data) to the +screen?</title> + +<para>There are several ways to approach this. The simplest +way is to use GdkRGB, see gdk/gdkrgb.h. You create an RGB +buffer, render to your RGB buffer, then use GdkRGB routines to +copy your RGB buffer to a drawing area or custom widget. The +book "GTK+/Gnome Application Development" gives some details; +GdkRGB is also documented in the GTK+ reference +documentation.</para> + +<para>If you're writing a game or other graphics-intensive +application, you might consider a more elaborate +solution. OpenGL is the graphics standard that will let you +access hardware accelaration in future versions of XFree86; so +for maximum speed, you probably want to use OpenGL. A +GtkGLArea widget is available for using OpenGL with GTK+ (but +GtkGLArea does not come with GTK+ itself). There are also +several open source game libraries, such as ClanLib and Loki's +Simple DirectMedia Layer library (SDL).</para> + +<para>You do NOT want to use +<literal>gdk_draw_point()</literal>, that will be extremely +slow.</para> +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>How do I create a pixmap without having my window being +realized/shown?</title> + +<para>Functions such as +<literal>gdk_pixmap_create_from_xpm()</literal> require a +valid window as a parameter. During the initialisation phase +of an application, a valid window may not be available without +showing a window, which may be inappropriate. In order to +avoid this, a function such as +<literal>gdk_pixmap_colormap_create_from_xpm</literal> can be +used, as in:</para> <programlisting role="C"> char *pixfile = "foo.xpm"; @@ -2076,26 +2273,28 @@ gint gtk_clist_prepend (GtkCList *clist, gdk_pixmap_unref (pixmap); gdk_pixmap_unref (pixmap_mask); </programlisting> - </sect2> - </sect1> - <!-- ***************************************************************** --> - <sect1> - <title>Development with GTK+: widget specific questions</title> - - <!-- ----------------------------------------------------------------- --> +</sect2> + +</sect1> - <sect2> - <title>How do I find out about the selection of a GtkList?</title> +<!-- ***************************************************************** --> +<sect1> +<title>Development with GTK+: widget specific questions</title> - <para>Get the selection something like this:</para> +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>How do I find out about the selection of a GtkList?</title> + +<para>Get the selection something like this:</para> <programlisting role="C"> GList *sel; sel = GTK_LIST(list)->selection; </programlisting> - <para>This is how GList is defined (quoting glist.h):</para> +<para>This is how GList is defined (quoting glist.h):</para> <programlisting role="C"> typedef struct _GList GList; @@ -2108,58 +2307,64 @@ struct _GList }; </programlisting> - <para>A GList structure is just a simple structure for doubly - linked lists. there exist several g_list_*() functions to - modify a linked list in glib.h. However the - GTK_LIST(MyGtkList)->selection is maintained by the - gtk_list_*() functions and should not be modified.</para> - - - <para>The selection_mode of the GtkList determines the - selection facilities of a GtkList and therefore the contents - of GTK_LIST(AnyGtkList)->selection:</para> - <informaltable frame="all"> - <tgroup cols="2"> - <thead> - <row> - <entry><literal>selection_mode</literal></entry> - <entry><literal> GTK_LIST()->selection</literal> - contents</entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>GTK_SELECTION_SINGLE</literal></entry> - <entry>selection is either NULL or contains a GList* - pointer for a single selected item.</entry> - </row> - <row> - <entry><literal>GTK_SELECTION_BROWSE</literal></entry> - <entry>selection is NULL if the list contains no - widgets, otherwise it contains a GList* - pointer for one GList structure.</entry> - </row> - <row> - <entry><literal>GTK_SELECTION_MULTIPLE</literal></entry> - <entry>selection is NULL if no listitems are selected - or a a GList* pointer for the first selected - item. that in turn points to a GList structure - for the second selected item and so - on.</entry> - </row> - <row> - <entry><literal>GTK_SELECTION_EXTENDED</literal></entry> - <entry>selection is NULL.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>The data field of the GList structure - GTK_LIST(MyGtkList)->selection points to the first - GtkListItem that is selected. So if you would like to - determine which listitems are selected you should go like - this:</para> +<para>A GList structure is just a simple structure for doubly +linked lists. there exist several g_list_*() functions to +modify a linked list in glib.h. However the +GTK_LIST(MyGtkList)->selection is maintained by the +gtk_list_*() functions and should not be modified.</para> + + +<para>The selection_mode of the GtkList determines the +selection facilities of a GtkList and therefore the contents +of GTK_LIST(AnyGtkList)->selection:</para> + +<informaltable frame="all"> +<tgroup cols="2"> +<thead> +<row> +<entry><literal>selection_mode</literal></entry> +<entry><literal> GTK_LIST()->selection</literal> +contents</entry> +</row> +</thead> + +<tbody> +<row> +<entry><literal>GTK_SELECTION_SINGLE</literal></entry> +<entry>selection is either NULL or contains a GList* +pointer for a single selected item.</entry> +</row> + +<row> +<entry><literal>GTK_SELECTION_BROWSE</literal></entry> +<entry>selection is NULL if the list contains no +widgets, otherwise it contains a GList* +pointer for one GList structure.</entry> +</row> + +<row> +<entry><literal>GTK_SELECTION_MULTIPLE</literal></entry> +<entry>selection is NULL if no listitems are selected +or a a GList* pointer for the first selected +item. that in turn points to a GList structure +for the second selected item and so +on.</entry> +</row> + +<row> +<entry><literal>GTK_SELECTION_EXTENDED</literal></entry> +<entry>selection is NULL.</entry> +</row> + +</tbody> +</tgroup> +</informaltable> + +<para>The data field of the GList structure +GTK_LIST(MyGtkList)->selection points to the first +GtkListItem that is selected. So if you would like to +determine which listitems are selected you should go like +this:</para> <programlisting role="C"> { @@ -2188,7 +2393,7 @@ struct _GList } </programlisting> - <para>To get known about the selection:</para> +<para>To get known about the selection:</para> <programlisting role="C"> { @@ -2207,19 +2412,19 @@ struct _GList } </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> + +<!-- ----------------------------------------------------------------- --> - <sect2> - <title>How do I stop the column headings of a GtkCList - disappearing when the list is scrolled?</title> +<sect2> +<title>How do I stop the column headings of a GtkCList +disappearing when the list is scrolled?</title> - <para>This happens when a GtkCList is packed into a - GtkScrolledWindow using the function - <literal>gtk_scroll_window_add_with_viewport()</literal>. The prefered - method of adding a CList to a scrolled window is to use the - function <literal>gtk_container_add</literal>, as in:</para> +<para>This happens when a GtkCList is packed into a +GtkScrolledWindow using the function +<literal>gtk_scroll_window_add_with_viewport()</literal>. The prefered +method of adding a CList to a scrolled window is to use the +function <literal>gtk_container_add</literal>, as in:</para> <programlisting role="C"> GtkWidget *scrolled, *clist; @@ -2231,24 +2436,24 @@ struct _GList gtk_container_add(GTK_CONTAINER(scrolled), clist); </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> + +<!-- ----------------------------------------------------------------- --> - <sect2> - <title>I don't want the user of my applications to enter text - into a GtkCombo. Any idea?</title> +<sect2> +<title>I don't want the user of my applications to enter text +into a GtkCombo. Any idea?</title> - <para>A GtkCombo has an associated entry which can be accessed - using the following expression:</para> +<para>A GtkCombo has an associated entry which can be accessed +using the following expression:</para> <programlisting role="C"> GTK_COMBO(combo_widget)->entry </programlisting> - <para>If you don't want the user to be able to modify the - content of this entry, you can use the - gtk_entry_set_editable() function:</para> +<para>If you don't want the user to be able to modify the +content of this entry, you can use the +gtk_entry_set_editable() function:</para> <programlisting role="C"> @@ -2256,27 +2461,28 @@ struct _GList gboolean editable); </programlisting> - <para>Set the editable parameter to FALSE to disable typing - into the entry.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> +<para>Set the editable parameter to FALSE to disable typing +into the entry.</para> +</sect2> + +<!-- ----------------------------------------------------------------- --> - <sect2> - <title>How do I catch a combo box change?</title> +<sect2> +<title>How do I catch a combo box change?</title> - <para>The entry which is associated to your GtkCombo send a - "changed" signal when:</para> +<para>The entry which is associated to your GtkCombo send a +"changed" signal when:</para> - <itemizedlist> - <listitem><simpara>some text is typed in</simpara> - </listitem> - <listitem><simpara>the selection of the combo box is changed</simpara> - </listitem> - </itemizedlist> +<itemizedlist> +<listitem><simpara>some text is typed in</simpara> +</listitem> - <para>To catch any combo box change, simply connect your - signal handler with</para> +<listitem><simpara>the selection of the combo box is changed</simpara> +</listitem> +</itemizedlist> + +<para>To catch any combo box change, simply connect your +signal handler with</para> <programlisting role="C"> gtk_signal_connect(GTK_COMBO(cb)->entry, @@ -2284,17 +2490,18 @@ struct _GList GTK_SIGNAL_FUNC(my_cb_change_handler), NULL); </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> - <sect2> - <title>How can I define a separation line in a menu?</title> +</sect2> + +<!-- ----------------------------------------------------------------- --> - <para>See the <ulink - url="http://www.gtk.org/tutorial/">Tutorial</ulink> for - information on how to create menus. However, to create a - separation line in a menu, just insert an empty menu item:</para> +<sect2> +<title>How can I define a separation line in a menu?</title> + +<para>See the <ulink +url="http://www.gtk.org/tutorial/">Tutorial</ulink> for +information on how to create menus. However, to create a +separation line in a menu, just insert an empty menu item:</para> <programlisting role="C"> menuitem = gtk_menu_item_new(); @@ -2302,44 +2509,44 @@ gtk_menu_append(GTK_MENU(menu), menuitem); gtk_widget_show(menuitem); </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> + +<!-- ----------------------------------------------------------------- --> - <sect2> - <title>How can I right justify a menu, such as Help?</title> +<sect2> +<title>How can I right justify a menu, such as Help?</title> - <para>Depending on if you use the MenuFactory or not, there - are two ways to proceed. With the MenuFactory, use something - like the following:</para> +<para>Depending on if you use the MenuFactory or not, there +are two ways to proceed. With the MenuFactory, use something +like the following:</para> <programlisting role="C"> menu_path = gtk_menu_factory_find (factory, "<MyApp>/Help"); gtk_menu_item_right_justify(menu_path->widget); </programlisting> - <para>If you do not use the MenuFactory, you should simply - use:</para> +<para>If you do not use the MenuFactory, you should simply +use:</para> <programlisting role="C"> gtk_menu_item_right_justify(my_menu_item); </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> + +<!-- ----------------------------------------------------------------- --> - <sect2> - <title>How do I add some underlined accelerators to menu - items?</title> +<sect2> +<title>How do I add some underlined accelerators to menu +items?</title> - <para>Damon Chaplin, the technical force behind the Glade - project, provided the following code sample (this code is an - output from Glade). It creates a small <GUIMenu>File</guimenu> menu item - with only one child (<guimenu>New</guimenu>). The F in <guimenu>File</guimenu> and the N - in <guimenu>New</guimenu> are underlined, and the relevant accelerators are - created.</para> +<para>Damon Chaplin, the technical force behind the Glade +project, provided the following code sample (this code is an +output from Glade). It creates a small <GUIMenu>File</guimenu> menu item +with only one child (<guimenu>New</guimenu>). The F in +<guimenu>File</guimenu> and the N in <guimenu>New</guimenu> are +underlined, and the relevant accelerators are created.</para> <programlisting role="C"> menubar1 = gtk_menu_bar_new (); @@ -2371,15 +2578,15 @@ gtk_menu_item_right_justify(my_menu_item); gtk_container_add (GTK_CONTAINER (file1_menu), new1); </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> + +<!-- ----------------------------------------------------------------- --> - <sect2> - <title>How can I retrieve the text from a GtkMenuItem?</title> +<sect2> +<title>How can I retrieve the text from a GtkMenuItem?</title> - <para>You can usually retrieve the label of a specific - GtkMenuItem with:</para> +<para>You can usually retrieve the label of a specific +GtkMenuItem with:</para> <programlisting role="C"> if (GTK_BIN (menu_item)->child) @@ -2397,8 +2604,8 @@ gtk_menu_item_right_justify(my_menu_item); } </programlisting> - <para>To get the active menu item from a GtkOptionMenu you can - do:</para> +<para>To get the active menu item from a GtkOptionMenu you can +do:</para> <programlisting role="C"> if (GTK_OPTION_MENU (option_menu)->menu_item) @@ -2407,14 +2614,13 @@ if (GTK_OPTION_MENU (option_menu)->menu_item) } </programlisting> - <para>But, there's a catch. For this specific case, you can - <emphasis>not</emphasis> get the label widget from - <literal>menu_item</literal> with the above code, because the - option menu reparents the menu_item's child temporarily to - display the currently active contents. So to retrive the child - of the currently active menu_item of an option menu, you'll - have to do:</para> - +<para>But, there's a catch. For this specific case, you can +<emphasis>not</emphasis> get the label widget from +<literal>menu_item</literal> with the above code, because the +option menu reparents the menu_item's child temporarily to +display the currently active contents. So to retrive the child +of the currently active menu_item of an option menu, you'll +have to do:</para> <programlisting role="C"> if (GTK_BIN (option_menu)->child) @@ -2424,23 +2630,24 @@ if (GTK_OPTION_MENU (option_menu)->menu_item) /* do stuff with child */ } </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> - <sect2> - <title>How do I right (or otherwise) justify a - GtkLabel?</title> +</sect2> - <para>Are you sure you want to <emphasis>justify</emphasis> - the labels? The label class contains the - <literal>gtk_label_set_justify()</literal> function that is - used to control the justification of a multi-line - label.</para> +<!-- ----------------------------------------------------------------- --> - <para>What you probably want is to set the <emphasis>alignment</emphasis> - of the label, ie right align it, center it or left align - it. If you want to do this, you should use:</para> +<sect2> +<title>How do I right (or otherwise) justify a +GtkLabel?</title> + +<para>Are you sure you want to <emphasis>justify</emphasis> +the labels? The label class contains the +<literal>gtk_label_set_justify()</literal> function that is +used to control the justification of a multi-line +label.</para> + +<para>What you probably want is to set the <emphasis>alignment</emphasis> +of the label, ie right align it, center it or left align +it. If you want to do this, you should use:</para> <programlisting role="C"> void gtk_misc_set_alignment (GtkMisc *misc, @@ -2448,10 +2655,9 @@ void gtk_misc_set_alignment (GtkMisc *misc, gfloat yalign); </programlisting> - <para>where the <literal>xalign</literal> and - <literal>yalign</literal> values are floats in - [0.00;1.00].</para> - +<para>where the <literal>xalign</literal> and +<literal>yalign</literal> values are floats in +[0.00;1.00].</para> <programlisting role="C"> GtkWidget *label; @@ -2465,43 +2671,45 @@ gtk_misc_set_alignment(GTK_MISK(label), 0.5f, 0.5f); /* horizontal : right align, vertical : bottom */ gtk_misc_set_alignment(GTK_MISK(label), 1.0f, 1.0f); </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> - <sect2> - <title>How do I set the background color of a GtkLabel - widget?</title> +</sect2> - <para>The Gtklabel widget is one of a few GTK+ widgets that - don't create their own window to render themselves - into. Instead, they draw themselves directly onto their - parents window.</para> +<!-- ----------------------------------------------------------------- --> - <para>This means that in order to set the background color for - a GtkLabel widget, you need to change the background color of - its parent, i.e. the object that you pack it into.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> +<sect2> +<title>How do I set the background color of a GtkLabel +widget?</title> + +<para>The Gtklabel widget is one of a few GTK+ widgets that +don't create their own window to render themselves +into. Instead, they draw themselves directly onto their +parents window.</para> + +<para>This means that in order to set the background color for +a GtkLabel widget, you need to change the background color of +its parent, i.e. the object that you pack it into.</para> + +</sect2> + +<!-- ----------------------------------------------------------------- --> - <sect2> - <title>How do I set the color and font of a GtkLabel using a - Resource File?</title> +<sect2> +<title>How do I set the color and font of a GtkLabel using a +Resource File?</title> - <para>The widget name path constructed for a Label consists of - the widget names of its object hierarchy as well, e.g.</para> +<para>The widget name path constructed for a Label consists of +the widget names of its object hierarchy as well, e.g.</para> - <para><literallayout> - <literal>window (name: humphrey)</literal> - <literal> hbox</literal> - <literal> label (name: mylabel)</literal> - </literallayout></para> +<para><literallayout> +<literal>window (name: humphrey)</literal> +<literal> hbox</literal> +<literal> label (name: mylabel)</literal> +</literallayout></para> - <para>The widget path your pattern needs to match would be: - <literal>humphrey.GtkHBox.mylabel</literal></para> +<para>The widget path your pattern needs to match would be: +<literal>humphrey.GtkHBox.mylabel</literal></para> - <para>The resource file may look something like:</para> +<para>The resource file may look something like:</para> <programlisting role="C"> style "title" @@ -2512,8 +2720,8 @@ style "title" widget "*mylabel" style "title" </programlisting> - <para>In your program, you would also need to give a name to - the Label widget, which can be done using:</para> +<para>In your program, you would also need to give a name to +the Label widget, which can be done using:</para> <programlisting role="C"> label = gtk_label_new("Some Label Text"); @@ -2521,18 +2729,18 @@ widget "*mylabel" style "title" gtk_widget_show(label); </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> + +<!-- ----------------------------------------------------------------- --> - <sect2> - <title>How do I configure Tooltips in a Resource File?</title> +<sect2> +<title>How do I configure Tooltips in a Resource File?</title> - <para>The tooltip's window is named "gtk-tooltips", - GtkTooltips in itself is not a GtkWidget (though a GtkObject) - and as such is not attempted to match any widget styles.</para> +<para>The tooltip's window is named "gtk-tooltips", +GtkTooltips in itself is not a GtkWidget (though a GtkObject) +and as such is not attempted to match any widget styles.</para> - <para>So, you resource file should look something like:</para> +<para>So, you resource file should look something like:</para> <programlisting role="C"> style "postie" @@ -2542,18 +2750,18 @@ style "postie" widget "gtk-tooltips*" style "postie" </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> - <sect2> - <title>I can't add more than (something like) 2000 chars in a - GtkEntry. What's wrong?</title> +<!-- ----------------------------------------------------------------- --> - <para>There is now a known problem in the GtkEntry widget. In - the <literal>gtk_entry_insert_text()</literal> function, the - following lines limit the number of chars in the entry to - 2047.</para> +<sect2> +<title>I can't add more than (something like) 2000 chars in a +GtkEntry. What's wrong?</title> + +<para>There is now a known problem in the GtkEntry widget. In +the <literal>gtk_entry_insert_text()</literal> function, the +following lines limit the number of chars in the entry to +2047.</para> <programlisting role="C"> /* The algorithms here will work as long as, the text size (a @@ -2567,18 +2775,18 @@ widget "gtk-tooltips*" style "postie" max_length = MIN (2047, entry->text_max_length); </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> - <sect2> - <title>How do I make a GtkEntry widget activate on pressing - the Return key?</title> +<!-- ----------------------------------------------------------------- --> - <para>The Entry widget emits an 'activate' signal when you - press return in it. Just attach to the activate signal on the - entry and do whatever you want to do. Typical code would - be:</para> +<sect2> +<title>How do I make a GtkEntry widget activate on pressing +the Return key?</title> + +<para>The Entry widget emits an 'activate' signal when you +press return in it. Just attach to the activate signal on the +entry and do whatever you want to do. Typical code would +be:</para> <programlisting role="C"> entry = gtk_entry_new(); @@ -2587,21 +2795,20 @@ widget "gtk-tooltips*" style "postie" NULL); </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> - <sect2> - <title>How do I validate/limit/filter the input to a - GtkEntry?</title> +<!-- ----------------------------------------------------------------- --> - <para>If you want to validate the text that a user enters into - a GtkEntry widget you can attach to the "insert_text" signal - of the entry, and modify the text within the callback - function. The example below forces all characters to - uppercase, and limits the range of characters to A-Z. Note - that the entry is cast to an object of type GtkEditable, from - which GtkEntry is derived.</para> +<sect2> +<title>How do I validate/limit/filter the input to a GtkEntry?</title> + +<para>If you want to validate the text that a user enters into +a GtkEntry widget you can attach to the "insert_text" signal +of the entry, and modify the text within the callback +function. The example below forces all characters to +uppercase, and limits the range of characters to A-Z. Note +that the entry is cast to an object of type GtkEditable, from +which GtkEntry is derived.</para> <programlisting role="C"> #include <ctype.h> @@ -2665,31 +2872,30 @@ int main (int argc, } </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> - <sect2> - <title>How do I use horizontal scrollbars with a GtkText - widget?</title> +<!-- ----------------------------------------------------------------- --> - <para>The short answer is that you can't. The current version - of the GtkText widget does not support horizontal - scrolling. There is an intention to completely rewrite the - GtkText widget, at which time this limitation will be - removed.</para> +<sect2> +<title>How do I use horizontal scrollbars with a GtkText widget?</title> - </sect2> - - <!-- ----------------------------------------------------------------- --> +<para>The short answer is that you can't. The current version +of the GtkText widget does not support horizontal +scrolling. There is an intention to completely rewrite the +GtkText widget, at which time this limitation will be +removed.</para> + +</sect2> - <sect2> - <title>How do I change the font of a GtkText widget?</title> +<!-- ----------------------------------------------------------------- --> - <para>There are a couple of ways of doing this. As GTK+ allows - the appearance of applications to be changed at run time using - resources you can use something like the following in the - appropriate file:</para> +<sect2> +<title>How do I change the font of a GtkText widget?</title> + +<para>There are a couple of ways of doing this. As GTK+ allows +the appearance of applications to be changed at run time using +resources you can use something like the following in the +appropriate file:</para> <programlisting role="C"> style "text" @@ -2698,45 +2904,45 @@ style "text" } </programlisting> - <para>Another way to do this is to load a font within your - program, and then use this in the functions for adding text to - the text widget. You can load a font using, for example:</para> +<para>Another way to do this is to load a font within your +program, and then use this in the functions for adding text to +the text widget. You can load a font using, for example:</para> <programlisting role="C"> GdkFont *font; font = gdk_font_load("-adobe-helvetica-medium-r-normal--*-140-*-*-*-*-*-*"); </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> - <sect2> - <title>How do I set the cursor position in a GtkText - object?</title> +<!-- ----------------------------------------------------------------- --> - <para>Notice that the response is valid for any object that - inherits from the GtkEditable class.</para> +<sect2> +<title>How do I set the cursor position in a GtkText +object?</title> - <para>Are you sure that you want to move the cursor position? - Most of the time, while the cursor position is good, the - insertion point does not match the cursor position. If this - apply to what you really want, then you should use the - <literal>gtk_text_set_point()</literal> function. If you want - to set the insertion point at the current cursor position, use - the following:</para> +<para>Notice that the response is valid for any object that +inherits from the GtkEditable class.</para> + +<para>Are you sure that you want to move the cursor position? +Most of the time, while the cursor position is good, the +insertion point does not match the cursor position. If this +apply to what you really want, then you should use the +<literal>gtk_text_set_point()</literal> function. If you want +to set the insertion point at the current cursor position, use +the following:</para> <programlisting role="C"> gtk_text_set_point(GTK_TEXT(text), gtk_editable_get_position(GTK_EDITABLE(text))); </programlisting> - <para>If you want the insertion point to follow the cursor at - all time, you should probably catch the button press event, - and then move the insertion point. Be careful : you'll have to - catch it after the widget has changed the cursor position - though. Thomas Mailund Jensen proposed the following - code:</para> +<para>If you want the insertion point to follow the cursor at +all time, you should probably catch the button press event, +and then move the insertion point. Be careful : you'll have to +catch it after the widget has changed the cursor position +though. Thomas Mailund Jensen proposed the following +code:</para> <programlisting role="C"> static void @@ -2773,46 +2979,46 @@ main (int argc, char *argv[]) } </programlisting> - <para>Now, if you really want to change the cursor position, - you should use the - <literal>gtk_editable_set_position()</literal> - function.</para> +<para>Now, if you really want to change the cursor position, +you should use the +<literal>gtk_editable_set_position()</literal> +function.</para> - </sect2> +</sect2> - </sect1> +</sect1> - <!-- ***************************************************************** --> - <sect1> - <title>About GDK</title> - - <!-- ----------------------------------------------------------------- --> +<!-- ***************************************************************** --> +<sect1> +<title>About GDK</title> - <sect2> - <title>What is GDK?</title> +<!-- ----------------------------------------------------------------- --> - <para>GDK is basically a wrapper around the standard Xlib - function calls. If you are at all familiar with Xlib, a lot of - the functions in GDK will require little or no getting used - to. All functions are written to provide an way to access Xlib - functions in an easier and slightly more intuitive manner. In - addition, since GDK uses GLib (see below), it will be more - portable and safer to use on multiple platforms.</para> +<sect2> +<title>What is GDK?</title> - <!-- Examples, anybody? I've been mulling some over. NF --> +<para>GDK is basically a wrapper around the standard Xlib +function calls. If you are at all familiar with Xlib, a lot of +the functions in GDK will require little or no getting used +to. All functions are written to provide an way to access Xlib +functions in an easier and slightly more intuitive manner. In +addition, since GDK uses GLib (see below), it will be more +portable and safer to use on multiple platforms.</para> - </sect2> - - <!-- ----------------------------------------------------------------- --> +<!-- Examples, anybody? I've been mulling some over. NF --> + +</sect2> - <sect2> - <title>How do I use color allocation?</title> +<!-- ----------------------------------------------------------------- --> - <para>One of the nice things about GDK is that it's based on - top of Xlib; this is also a problem, especially in the area of - color management. If you want to use color in your program - (drawing a rectangle or such, your code should look something - like this:</para> +<sect2> +<title>How do I use color allocation?</title> + +<para>One of the nice things about GDK is that it's based on +top of Xlib; this is also a problem, especially in the area of +color management. If you want to use color in your program +(drawing a rectangle or such, your code should look something +like this:</para> <programlisting role="C"> { @@ -2861,46 +3067,54 @@ main (int argc, char *argv[]) } </programlisting> - </sect2> - </sect1> - <!-- ***************************************************************** --> - <sect1> - <title>About GLib</title> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>What is GLib?</title> - - <para>GLib is a library of useful functions and definitions - available for use when creating GDK and GTK applications. It - provides replacements for some standard libc functions, such - as malloc, which are buggy on some systems.</para> - - <para>It also provides routines for handling:</para> - - <itemizedlist> - <listitem><simpara>Doubly Linked Lists</simpara> - </listitem> - <listitem><simpara>Singly Linked Lists</simpara> - </listitem> - <listitem><simpara>Timers</simpara> - </listitem> - <listitem><simpara>String Handling</simpara> - </listitem> - <listitem><simpara>A Lexical Scanner</simpara> - </listitem> - <listitem><simpara>Error Functions</simpara> - </listitem> - </itemizedlist> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> + +</sect1> + +<!-- ***************************************************************** --> +<sect1> +<title>About GLib</title> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>What is GLib?</title> + +<para>GLib is a library of useful functions and definitions +available for use when creating GDK and GTK applications. It +provides replacements for some standard libc functions, such +as malloc, which are buggy on some systems.</para> + +<para>It also provides routines for handling:</para> + +<itemizedlist spacing=compact> +<listitem><simpara>Doubly Linked Lists</simpara> +</listitem> + +<listitem><simpara>Singly Linked Lists</simpara> +</listitem> + +<listitem><simpara>Timers</simpara> +</listitem> + +<listitem><simpara>String Handling</simpara> +</listitem> + +<listitem><simpara>A Lexical Scanner</simpara> +</listitem> + +<listitem><simpara>Error Functions</simpara> +</listitem> +</itemizedlist> + +</sect2> - <sect2> - <title>How can I use the doubly linked lists?</title> +<!-- ----------------------------------------------------------------- --> - <para>The GList object is defined as:</para> +<sect2> +<title>How can I use the doubly linked lists?</title> + +<para>The GList object is defined as:</para> <programlisting role="C"> typedef struct _GList GList; @@ -2913,7 +3127,7 @@ struct _GList }; </programlisting> - <para>To use the GList objects, simply:</para> +<para>To use the GList objects, simply:</para> <programlisting role="C"> GList *list = NULL; @@ -2941,39 +3155,39 @@ list = g_list_remove_link(list, listrunner); list = g_list_remove(list, &array[4]); </programlisting> - <para>The same code is usable with singly linked lists (GSList - objects) by replacing g_list_* functions with the relevant - g_slist_* ones (g_slist_append, g_slist_remove, ...). Just - remember that since you can't go backward in a singly linked - list, there is no g_slist_first function - you'll need to keep - a reference on the first node of the list.</para> +<para>The same code is usable with singly linked lists (GSList +objects) by replacing g_list_* functions with the relevant +g_slist_* ones (g_slist_append, g_slist_remove, ...). Just +remember that since you can't go backward in a singly linked +list, there is no g_slist_first function - you'll need to keep +a reference on the first node of the list.</para> - <!-- Some Examples might be useful here! NF --> - <!-- I believe it should be better :) ED --> - <!-- Linked lists are pretty standard data structures - don't want to - over do it - TRG --> +<!-- Some Examples might be useful here! NF --> +<!-- I believe it should be better :) ED --> +<!-- Linked lists are pretty standard data structures - don't want to +over do it - TRG --> - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> + +<!-- ----------------------------------------------------------------- --> - <sect2> - <title>Memory does not seem to be released when I free the - list nodes I've allocated</title> +<sect2> +<title>Memory does not seem to be released when I free the +list nodes I've allocated</title> - <para>GLib tries to be "intelligent" on this special issue: it - assumes that you are likely to reuse the objects, so caches - the allocated memory. If you do not want to use this behavior, - you'll probably want to set up a special allocator.</para> +<para>GLib tries to be "intelligent" on this special issue: it +assumes that you are likely to reuse the objects, so caches +the allocated memory. If you do not want to use this behavior, +you'll probably want to set up a special allocator.</para> - <para>To quote Tim Janik:</para> - <para><quote>If you have a certain portion of code that uses *lots* - of GLists or GNodes, and you know you'd better want to release - all of them after a short while, you'd want to use a - GAllocator. Pushing an allocator into g_list will make all - subsequent glist operations private to that allocator's memory - pool (and thus you have to take care to pop the allocator - again, before making any external calls): </quote></para> +<para>To quote Tim Janik:</para> +<para><quote>If you have a certain portion of code that uses *lots* +of GLists or GNodes, and you know you'd better want to release +all of them after a short while, you'd want to use a +GAllocator. Pushing an allocator into g_list will make all +subsequent glist operations private to that allocator's memory +pool (and thus you have to take care to pop the allocator +again, before making any external calls): </quote></para> <programlisting role="C"> GAllocator *allocator; @@ -3007,63 +3221,63 @@ g_list_pop_allocator (); g_allocator_free (allocator); </programlisting> - </sect2> - - <!-- ----------------------------------------------------------------- --> - - <sect2> - <title>Why use g_print, g_malloc, g_strdup and fellow glib - functions?</title> - - <para>Thanks to Tim Janik who wrote to gtk-list: (slightly - modified)</para> - - <para><quote>Regarding g_malloc(), g_free() and siblings, these - functions are much safer than their libc equivalents. For - example, g_free() just returns if called with NULL. Also, if - USE_DMALLOC is defined, the definition for these functions - changes (in glib.h) to use MALLOC(), FREE() etc... If - MEM_PROFILE or MEM_CHECK are defined, there are even small - statistics made counting the used block sizes (shown by - g_mem_profile() / g_mem_check()).</quote></para> - - <para><quote>Considering the fact that glib provides an interface for - memory chunks to save space if you have lots of blocks that - are always the same size and to mark them ALLOC_ONLY if - needed, it is just straight forward to create a small saver - (debug able) wrapper around the normal malloc/free stuff as - well - just like gdk covers Xlib. ;)</quote></para> - - <para><quote>Using g_error() and g_warning() inside of applications - like the GIMP that fully rely on gtk even gives the - opportunity to pop up a window showing the messages inside of - a gtk window with your own handler (by using - g_set_error_handler()) along the lines of - <literal>gtk_print()</literal> (inside of - gtkmain.c).</quote></para> - - </sect2> - - <!-- ----------------------------------------------------------------- --> +</sect2> + +<!-- ----------------------------------------------------------------- --> + +<sect2> +<title>Why use g_print, g_malloc, g_strdup and fellow glib +functions?</title> + +<para>Thanks to Tim Janik who wrote to gtk-list: (slightly +modified)</para> + +<para><quote>Regarding g_malloc(), g_free() and siblings, these +functions are much safer than their libc equivalents. For +example, g_free() just returns if called with NULL. Also, if +USE_DMALLOC is defined, the definition for these functions +changes (in glib.h) to use MALLOC(), FREE() etc... If +MEM_PROFILE or MEM_CHECK are defined, there are even small +statistics made counting the used block sizes (shown by +g_mem_profile() / g_mem_check()).</quote></para> - <sect2> - <title>What's a GScanner and how do I use one?</title> +<para><quote>Considering the fact that glib provides an interface for +memory chunks to save space if you have lots of blocks that +are always the same size and to mark them ALLOC_ONLY if +needed, it is just straight forward to create a small saver +(debug able) wrapper around the normal malloc/free stuff as +well - just like gdk covers Xlib. ;)</quote></para> - <para>A GScanner will tokenize your text, that is, it'll return - an integer for every word or number that appears in its input - stream, following certain (customizable) rules to perform this - translation. You still need to write the parsing functions on - your own though.</para> +<para><quote>Using g_error() and g_warning() inside of applications +like the GIMP that fully rely on gtk even gives the +opportunity to pop up a window showing the messages inside of +a gtk window with your own handler (by using +g_set_error_handler()) along the lines of +<literal>gtk_print()</literal> (inside of +gtkmain.c).</quote></para> - <para>Here's a little test program supplied by Tim Janik that - will parse</para> +</sect2> - <para><literallayout> - <literal><SYMBOL> = <OPTIONAL-MINUS> <NUMBER> ;</literal> - </literallayout></para> +<!-- ----------------------------------------------------------------- --> - <para>constructs, while skipping "#\n" and "/**/" style - comments.</para> +<sect2> +<title>What's a GScanner and how do I use one?</title> + +<para>A GScanner will tokenize your text, that is, it'll return +an integer for every word or number that appears in its input +stream, following certain (customizable) rules to perform this +translation. You still need to write the parsing functions on +your own though.</para> + +<para>Here's a little test program supplied by Tim Janik that +will parse</para> + +<para><literallayout> +<literal><SYMBOL> = <OPTIONAL-MINUS> <NUMBER> ;</literal> +</literallayout></para> + +<para>constructs, while skipping "#\n" and "/**/" style +comments.</para> <programlisting role="C"> #include <glib.h> @@ -3223,22 +3437,22 @@ main (int argc, char *argv[]) } </programlisting> - <para>You need to understand that the scanner will parse its - input and tokenize it, it is up to you to interpret these - tokens, not define their types before they get parsed, - e.g. watch gscanner parse a string:</para> +<para>You need to understand that the scanner will parse its +input and tokenize it, it is up to you to interpret these +tokens, not define their types before they get parsed, +e.g. watch gscanner parse a string:</para> - <para><literallayout> - <literal>"hi i am 17"</literal> - <literal> | | | |</literal> - <literal> | | | v</literal> - <literal> | | v TOKEN_INT, value: 17</literal> - <literal> | v TOKEN_IDENTIFIER, value: "am"</literal> - <literal> v TOKEN_CHAR, value: 'i'</literal> - <literal>TOKEN_IDENTIFIER, value: "hi"</literal> - </literallayout></para> +<para><literallayout> +<literal>"hi i am 17"</literal> +<literal> | | | |</literal> +<literal> | | | v</literal> +<literal> | | v TOKEN_INT, value: 17</literal> +<literal> | v TOKEN_IDENTIFIER, value: "am"</literal> +<literal> v TOKEN_CHAR, value: 'i'</literal> +<literal>TOKEN_IDENTIFIER, value: "hi"</literal> +</literallayout></para> - <para>If you configure the scanner with:</para> +<para>If you configure the scanner with:</para> <programlisting role="C"> scanner->config->int_2_float = TRUE; @@ -3246,30 +3460,30 @@ scanner->config->char_2_token = TRUE; scanner->config->scan_symbols = TRUE; </programlisting> - <para>and add "am" as a symbol with</para> +<para>and add "am" as a symbol with</para> <programlisting role="C"> g_scanner_add_symbol (scanner, "am", "symbol value"); </programlisting> - <para>GScanner will parse it as</para> +<para>GScanner will parse it as</para> - <para><literallayout> - <literal>"hi i am 17"</literal> - <literal> | | | |</literal> - <literal> | | | v</literal> - <literal> | | v TOKEN_FLOAT, value: 17.0 (automatic int->float conversion)</literal> - <literal> | | TOKEN_SYMBOL, value: "symbol value" (a successfull hash table lookup</literal> - <literal> | | turned a TOKEN_IDENTIFIER into a</literal> - <literal> | | TOKEN_SYMBOL and took over the</literal> - <literal> | v symbol's value)</literal> - <literal> v 'i' ('i' can be a valid token as well, as all chars >0 and <256)</literal> - <literal>TOKEN_IDENTIFIER, value: "hi"</literal> - </literallayout></para> +<para><literallayout> +<literal>"hi i am 17"</literal> +<literal> | | | |</literal> +<literal> | | | v</literal> +<literal> | | v TOKEN_FLOAT, value: 17.0 (automatic int->float conversion)</literal> +<literal> | | TOKEN_SYMBOL, value: "symbol value" (a successfull hash table lookup</literal> +<literal> | | turned a TOKEN_IDENTIFIER into a</literal> +<literal> | | TOKEN_SYMBOL and took over the</literal> +<literal> | v symbol's value)</literal> +<literal> v 'i' ('i' can be a valid token as well, as all chars >0 and <256)</literal> +<literal>TOKEN_IDENTIFIER, value: "hi"</literal> +</literallayout></para> - <para>You need to match the token sequence with your code, and - if you encounter something that you don't want, you error - out:</para> +<para>You need to match the token sequence with your code, and +if you encounter something that you don't want, you error +out:</para> <programlisting role="C"> /* expect an identifier ("hi") */ @@ -3290,31 +3504,36 @@ if (scanner->token != G_TOKEN_FLOAT) return G_TOKEN_FLOAT; </programlisting> - <para>If you got past here, you have parsed "hi i am 17" and - would have accepted "dooh i am 42" and "bah i am 0.75" as - well, but you would have not accepted "hi 7 am 17" or "hi i hi - 17".</para> +<para>If you got past here, you have parsed "hi i am 17" and +would have accepted "dooh i am 42" and "bah i am 0.75" as +well, but you would have not accepted "hi 7 am 17" or "hi i hi +17".</para> - </sect2> - </sect1> - <!-- ***************************************************************** --> - <sect1> - <title>GTK+ FAQ Contributions, Maintainers and Copyright</title> +</sect2> + +</sect1> + +<!-- ***************************************************************** --> + +<sect1> +<title>GTK+ FAQ Contributions, Maintainers and Copyright</title> <para>If you would like to make a contribution to the FAQ, send either one of us an e-mail message with the exact text you think should be included (question and answer). With your help, this document can grow and become more useful!</para> -<para>This document is maintained by -Tony Gale <ulink - url="mailto:gale@gtk.org"><gale@gtk.org></ulink> +<para>This document is maintained by +Tony Gale +<ulink url="mailto:gale@gtk.org"><gale@gtk.org></ulink> -Nathan Froyd <ulink url="mailto:maestrox@geocities.com"> +Nathan Froyd +<ulink url="mailto:maestrox@geocities.com"> <maestrox@geocities.com></ulink>, and -Emmanuel Deloget <ulink url="mailto:logout@free.fr"> -<logout@free.fr></ulink>. +Emmanuel Deloget +<ulink url="mailto:logout@free.fr"><logout@free.fr></ulink>. + This FAQ was created by Shawn T. Amundson <ulink url="mailto:amundson@gimp.org"> <amundson@gimp.org></ulink> who continues to provide support. @@ -3349,10 +3568,10 @@ purpose. This is simply provided as a free resource. As such, the authors and maintainers of the information provided within can not make any guarentee that the information is even accurate.</para> - </sect1> +</sect1> - </chapter> +</chapter> - <!-- ----------------------------------------------------------------- --> +<!-- ----------------------------------------------------------------- --> </book> |