gtkfaq.sgml 65.2 KB
Newer Older
1
2
3
4
5
6
7
<!doctype linuxdoc system>

<article>

<!-- Title information -->

<title>GTK+ FAQ
Tony Gale's avatar
Tony Gale committed
8
9

<!-- NOTE: Use only one author tag, otherwise sgml2txt barfs - TRG --> 
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
10
<author>Nathan Froyd, Tony Gale, Shawn T. Amundson, Emmanuel Deloget
BST 1998  Tony Gale's avatar
BST 1998 Tony Gale committed
11

BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
12
<date>July 14th 1999
BST 1998  Tony Gale's avatar
BST 1998 Tony Gale committed
13

BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
14
15
16
<abstract> This document is intended to answer questions that are likely to be 
frequently asked by programmers using GTK+ or people who are just looking at 
using GTK+. 
17
18
19
20
21
22
23
24
25
26
</abstract>

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

<!-- Begin the document -->

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

BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
<!-- ----------------------------------------------------------------- -->
<sect1>Before anything else: the greetings
<p>
The FAQ authors want to thank:
<itemize>
<item>Havoc Pennington
<item>Eric Mouw
<item>Owen Taylor
<item>Tim Janik
<item>Thomas Mailund Jensen
<item>Joe Pfeiffer
<item>Andy Kahn
<item>Federico Mena Quintero
<item>Damon Chaplin
<item>and all the members of the GTK+ lists
</itemize>
If we forgot you, please email us !
Thanks again (I know, it's really short :)

46
<!-- ----------------------------------------------------------------- -->
Shawn Amundson's avatar
Shawn Amundson committed
47
<sect1>Authors
48
49
50
<p>
The authors of GTK+ are:

Shawn Amundson's avatar
Shawn Amundson committed
51
52
53
54
55
56
<itemize>
<item>Peter Mattis    (petm@xcf.berkeley.edu)
<item>Spencer Kimball (spencer@xcf.berkeley.edu)
<item>Josh MacDonald  (jmacd@xcf.berkeley.edu)
</itemize>
GTK+ is distributed under the GNU Library General Public License
57
58

<!-- ----------------------------------------------------------------- -->
Shawn Amundson's avatar
Shawn Amundson committed
59
<sect1>What is GTK+?
60
<p>
Shawn Amundson's avatar
Shawn Amundson committed
61
GTK+ is a small and efficient widget set designed with the general look 
62
63
64
65
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.

Shawn Amundson's avatar
Shawn Amundson committed
66
67
68
69
70
71
72
73
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. 

74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
<!-- ----------------------------------------------------------------- -->
<sect1>What is the + in GTK+?
<P>
Peter Mattis informed the gtk mailing list that:
<quote>
"I originally wrote gtk which included the three libraries, libglib,
libgdk and libgtk. It featured a flat widget hierarchy. That is, you
couldn't derive a new widget from an existing one. And it contained
a more standard callback mechanism instead of the signal mechanism now
present in gtk+. The + was added to distinguish between the original
version of gtk and the new version. You can think of it as being an
enhancement to the original gtk that adds object oriented features."
</quote>

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

Shawn Amundson's avatar
Shawn Amundson committed
98
99
100
101
<!-- ----------------------------------------------------------------- -->
<sect1>Where is the documentation for GTK+?
<p>
In the GTK+ distribution's doc/ directory you will find the
102
103
reference material for both GTK and GDK, this FAQ and the
GTK Tutorial.
Shawn Amundson's avatar
Shawn Amundson committed
104

105
106
In addition, you can find links to HTML versions of these documents 
by going to 
107
108
<htmlurl url="http://www.gtk.org/" 
name="http://www.gtk.org/">.
Shawn Amundson's avatar
Shawn Amundson committed
109
110
111
112
113


<!-- ----------------------------------------------------------------- -->
<sect1>Is there a mailing list (or mailing list archive) for GTK+?
<p>
Tony Gale's avatar
Tony Gale committed
114
115
116
117
118
119
120
121
122
123
There are two mailing lists:
<itemize>
<item>A mailing list for discussion of development of GTK based applications
is hosted at gtk-app-devel-list@redhat.com. To subscribe send an
email message to <htmlurl url="mailto:gtk-app-devel-list-request@redhat.com"
name="gtk-app-devel-list-request@redhat.com">
with <em>subscribe</em> in the <bf>subject</bf>.
<p>
<item>A mailing list for discussion of development of GTK is hosted 
at gtk-list@redhat.com. To subscribe send an
Shawn Amundson's avatar
Shawn Amundson committed
124
125
126
email message to <htmlurl url="mailto:gtk-list-request@redhat.com" 
name="gtk-list-request@redhat.com">
with <em>subscribe</em> in the <bf>subject</bf>.
Tony Gale's avatar
Tony Gale committed
127
<p>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
128
129
130
A searchable archive of the mailing list can be found at 
<htmlurl url="http://archive.redhat.com/gtk-list" 
name="http://archive.redhat.com/gtk-list">
Tony Gale's avatar
Tony Gale committed
131
</itemize>
Shawn Amundson's avatar
Shawn Amundson committed
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
<!-- ----------------------------------------------------------------- -->
<sect1>The gtk-list hasn't had any traffic for days, is it dead?
<p>
No, everyone's just busy coding.

<!-- ----------------------------------------------------------------- -->
<sect1>How to get help with GTK+
<p>
First, make sure your question isn't answered in the documentation, this
FAQ or the tutorial. Done that? You're sure you've done that, right? In
that case, the best place to post questions is to the GTK+ mailing list.

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

BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
149
150
151
152
153
154
155
156
157
<!-- ----------------------------------------------------------------- -->
<sect1>Is there a Windows version of GTK+?
<p>
There is an on going port of GTK+ to the Windows platform which is
making impressive progress.

See <htmlurl url="http://www.iki.fi/tml/gimp/win32"
name="http://www.iki.fi/tml/gimp/win32"> for more information.

158
159
160
<!-- ----------------------------------------------------------------- -->
<sect1>What applications have been written with GTK+?
<p>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
161
162
163
164
165
A list of some GTK+ based application can be found on the GTK+ web
server at <htmlurl url="http://www.gtk.org/apps/" 
name="http://www.gtk.org/apps/"> and contains more than 350 applications.

Some of these are:
166
<itemize>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
167
168
169
170
171
172
<item>GIMP (<htmlurl url="http://www.gimp.org/" 
                  name="http://www.gimp.org/">), 
        an image manipulation program
<item>AbiWord (<htmlurl url="http://www.abisource.com/" 
        name="http://www.abisource.com/">),
        a professional word processor
Tony Gale's avatar
Tony Gale committed
173
174
<item>GUBI (<htmlurl url="http://www.SoftHome.net/pub/users/timj/gubi/index.htm"
            name="http://www.SoftHome.net/pub/users/timj/gubi/index.htm">),
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
        a user interface builder
<item>Gzilla (<htmlurl url="http://www.levien.com/gzilla/" 
        name="http://www.levien.com/gzilla/">),
        a web browser
<item>SANE (<htmlurl url="http://www.azstarnet.com/~axplinux/sane/" 
        name="http://www.azstarnet.com/~axplinux/sane/"> ),
        a universal scanner interface
<item>XQF (<htmlurl url="http://www.botik.ru/~roma/quake/" 
        name="http://www.botik.ru/~roma/quake/">),
        a QuakeWorld/Quake2 server browser and launcher
<item>ElectricEyes (<htmlurl url="http://www.labs.redhat.com/ee.shtml" 
        name="http://www.labs.redhat.com/ee.shtml">),
        an image viewer that aims to be a free replacement for xv
<item>GPK - the General Proxy Kit (<htmlurl url="http://www.humanfactor.com/gpk/" 
        name="http://www.humanfactor.com/gpk/">),
        an add-on library to permit thread-safe access to GTK+
<item>GCK - the General Convenience Kit (<htmlurl url="http://www.ii.uib.no/~tomb/gck.html" 
        name="http://www.ii.uib.no/~tomb/gck.html">),
        miscellaneous functions intended to ease color handling, UI construction,
        vector operations, and math functions
<item>GDK Imlib (<htmlurl url="http://www.labs.redhat.com/imlib/" 
        name="http://www.labs.redhat.com/imlib/">),
        a fast image loading and manipulation library for GDK
<item>Glade (<htmlurl url="http://glade.pn.org/"
        name="http://glade.pn.org/">),
        a GTK+ based RAD tool which produces GTK+ applications
201
</itemize>
Tony Gale's avatar
Tony Gale committed
202
203
204
205
206
<p>
In addition to the above, the GNOME project (<htmlurl url="http://www.gnome.org"
name="http://www.gnome.org">)
is using GTK+ to build a free desktop for Linux. Many more programs can be found
there.
207

Owen Taylor's avatar
Owen Taylor committed
208
<!-- ----------------------------------------------------------------- -->
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
209
<sect1>I'm looking for an application to write in GTK+. How about an IRC client? 
Owen Taylor's avatar
Owen Taylor committed
210
211
<p> 

BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
212
213
214
215
Ask on gtk-list for suggestions. There are at least three IRC
clients already under development (probably more in fact. The server at
<htmlurl url="http://www.forcix.cx/irc-clients.html"
name="http://www.forcix.cx/irc-clients.html"> list a bunch of them).
Owen Taylor's avatar
Owen Taylor committed
216
217
218
219
220

<itemize>
<item>girc. (Included with GNOME)
<item>Bezerk (<htmlurl url="http://www.gtk.org/~trog/"
                       name="http://www.gtk.org/~trog/">)
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
221
<item>gsirc. (In the gnome CVS tree)
Owen Taylor's avatar
Owen Taylor committed
222
223
</itemize>

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

<!-- ***************************************************************** -->
228
229

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

235
<!-- ----------------------------------------------------------------- -->
236
237
238
239
<sect1>Where can I get GTK+?
<p>
The canonical site is:
<verb>
240
ftp://ftp.gtk.org/pub/gtk
241
</verb>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
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
<htmlurl url="ftp://ftp.gtk.org/etc/mirrors"
name="ftp://ftp.gtk.org/etc/mirrors">

Here's a few mirror sites to get you started:
<itemize>
<item>Africa - ftp://ftp.is.co.za/applications/gimp/
<item>Australia - ftp://ftp.au.gimp.org/pub/gimp/
<item>Finland - ftp://ftp.funet.fi/pub/sci/graphics/packages/gimp
<item>Germany - ftp://infosoc.uni-koeln.de/pub/ftp.gimp.org/
<item>Japan - ftp://SunSITE.sut.ac.jp/pub/archives/packages/gimp/
<item>UK - ftp://ftp.flirble.org/pub/X/gimp/
<item>US - ftp://ftp.insync.net/pub/mirrors/ftp.gimp.org/
</itemize>
257
258
259
260
261
262
263
264
265
266

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

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

<!-- ----------------------------------------------------------------- -->
 
Owen Taylor's avatar
Owen Taylor committed
277
<sect1>I've compiled and installed GTK+, but I can't get any programs to link with it!
278
<p>
Shawn Amundson's avatar
Shawn Amundson committed
279
280
281
282
283
This problem is most often encountered when the GTK+ libraries can't be 
found or are the wrong version. Generally, the compiler will complain about an
'unresolved symbol'.  There are two things you need to check:
<itemize>
<item>Make sure that the libraries can be found. You want to edit 
284
/etc/ld.so.conf to include the directories which contain the GTK libraries,
Shawn Amundson's avatar
Shawn Amundson committed
285
 so it looks something like:
286
287
288
289
<verb>
/usr/X11R6/lib
/usr/local/lib
</verb>
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
Then you need to run /sbin/ldconfig as root. You can find what directory
GTK is in using
<verb>
gtk-config --libs
</verb>

If your system doesn't use ld.so to find libraries (such as Solaris), then
you will have to use the LD_LIBRARY_PATH environment variable (or compile
the path into your program, which I'm not going to cover here). So, with a
Bourne type shell you can do (if your GTK libraries are in /usr/local/lib):
<verb>
export LD_LIBRARY_PATH=/usr/local/lib
</verb>
and in a csh, you can do:
<verb>
setenv LD_LIBRARY_PATH /usr/local/lib
</verb>

Shawn Amundson's avatar
Shawn Amundson committed
308
309
310
<item>Make sure the linker is finding the correct set of libraries. If you
have a Linux distribution that installs GTK+ (e.g. RedHat 5.0) then this 
older version may be used. Now (assuming you have a RedHat
311
312
313
314
315
316
317
318
system), issue the command
<verb>
rpm -e gtk gtk-devel
</verb>
You may also want to remove the packages that depend on gtk (rpm will tell you
which ones they are).  If you don't have a RedHat Linux system, check to make sure
that neither <verb>/usr/lib</verb> or <verb>/usr/local/lib</verb> contain any of
the libraries libgtk, libgdk, libglib, or libgck.  If they do exist, remove them
Shawn Amundson's avatar
Shawn Amundson committed
319
(and any gtk include files, such as /usr/include/gtk and /usr/include/gdk) 
320
and reinstall gtk+.
Shawn Amundson's avatar
Shawn Amundson committed
321
</itemize>
322

Owen Taylor's avatar
Owen Taylor committed
323
324
<!-- ----------------------------------------------------------------- -->
<sect1>When compiling programs with GTK+, I get compiler error messages about not being able to find <tt/"glibconfig.h"/.
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
325
326
<p>
The header file "glibconfig.h" was moved to the directory
Owen Taylor's avatar
Owen Taylor committed
327
328
329
330
331
332
$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/.

333
This was done because "glibconfig.h" includes architecture
Owen Taylor's avatar
Owen Taylor committed
334
335
336
337
dependent information, and the rest of the include files
are put in $prefix/include, which can be shared between different
architectures. 

338
GTK+ includes a shell script, <tt/gtk-config/, that
Owen Taylor's avatar
Owen Taylor committed
339
340
341
342
343
344
makes it easy to find out the correct include paths.
The GTK+ tutorial includes an example of using <tt/gtk-config/
for simple compilation from the command line. For information
about more complicated configuration, see the file
docs/gtk-config.txt in the GTK+ distribution.

345
If you are trying to compile an old program, you may
Owen Taylor's avatar
Owen Taylor committed
346
347
348
349
be able to work around the problem by configuring it
with a command line like: 

<tscreen><verb>
350
CPPFLAGS="-I/usr/local/include/glib/include" ./configure
Owen Taylor's avatar
Owen Taylor committed
351
352
353
354
355
</verb></tscreen>

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

<tscreen><verb>
356
setenv CPPFLAGS "-I/usr/local/include/glib/include" 
Owen Taylor's avatar
Owen Taylor committed
357
358
359
360
361
./configure
</verb></tscreen>

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

362
<!-- ----------------------------------------------------------------- -->
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
363
<sect1>When installing a GTK+ application, configure reports that it can't find GTK.
364
<p>
365
There are several common reasons for this:
366
367
<itemize>
<item>You have an old version of GTK installed somewhere. RedHat 5.0, for 
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
368
369
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
370
371
372
373
374
375
376
of RedHat 5.0 this will break the <tt/control-panel/ applications.
<P>
<item><tt/gtk-config/ (or another component of GTK) isn't in your path, or
there is an old version on your system. Type:
<verb>
gtk-config --version
</verb>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
377
378
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.
379
380
381
382
<P>
<item>The ./configure script can't find the GTK libraries. As ./configure
compiles various test programs, it needs to be able to find the GTK
libraries. See the question above for help on this.
383
</itemize>
384
385
386
387
388
389
<p>
If none of the above help, then have a look in config.log, which is
generated by ./configure as it runs. At the bottom will be the last
action it took before failing. If it is a section of source code, copy
the source code to a file and compile it with the line just above it in
config.log. If the compilation is successful, try executing it.
390

391
392
<!-- ***************************************************************** -->
<sect>Development of GTK+
Shawn Amundson's avatar
Shawn Amundson committed
393
<!-- ***************************************************************** -->
394

395
396
397
<!-- ----------------------------------------------------------------- -->
<sect1>Whats this CVS thing that everyone keeps talking about, and how do I access it?
<p>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
398
CVS is the Concurent Version System and is a very popular means of 
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
version control for software projects. It is designed to allow multiple 
authors to be able to simultanously operate on the same source tree. 
This source tree is centrally maintained, but each developer has a
local mirror of this repository that they make there changes to.

The GTK+ developers use a CVS repository to store the master copy of
the current development version of GTK+. As such, people wishing to
contribute patches to GTK+ should generate them against the CVS version.
Normal people should use the packaged releases.

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

Anyone can download the latest CVS version of GTK+ by using anonymous access
using the following steps:
<itemize>
<item> In a bourne shell descendant (e.g. bash) type:
<verb>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
419
420
CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'
export CVSROOT
421
422
423
424
425
426
427
428
</verb>
<item>Next, the first time the source tree is checked out, a cvs login 
is needed. 
<verb>
cvs login
</verb>
This will ask you for a password. There is no password for cvs.gimp.org, 
so just enter a carriage return. 
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
429
430
<item>To get the tree and place it in a subdir of your current working
directory, issue the command: 
431
<verb>
BST 1998  Tony Gale's avatar
BST 1998 Tony Gale committed
432
433
434
435
436
437
438
439
cvs -z3 get gtk+
</verb>

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:
<verb>
cvs -z3 get glib
440
</verb>
BST 1998  Tony Gale's avatar
BST 1998 Tony Gale committed
441

442
</itemize>
Shawn Amundson's avatar
Shawn Amundson committed
443
<!-- ----------------------------------------------------------------- -->
444
445
<sect1>How can I contribute to GTK+?
<p>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
446
447
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
448
449
450
451
true bug or missing feature, track it down in the GTK+ source, change it, 
and then generate a patch in the form of a 'context diff'. This can be done
using a command such as <tt/diff -ru &lt;oldfile&gt; &lt;newfile&gt;/. 
Then upload the patchfile to:
452
<verb>
453
ftp://ftp.gtk.org/incoming
454
</verb>
Shawn Amundson's avatar
Shawn Amundson committed
455
along with a README file.  Make sure you follow the naming conventions or your
456
patch will just be deleted! The filenames should be of this form:
Shawn Amundson's avatar
Shawn Amundson committed
457
458
459
460
461
462
463
464
465
466
467
468
469
<verb>
gtk-<username>-<date yymmdd-n>.patch.gz
gtk-<username>-<date yymmdd-n>.patch.README
</verb>
The "n" in the date indicates a unique number (starting from 0)
of patches you uploaded that day.  It should be 0, unless you
upload more than one patch in the same day.

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

472
473
474
<!-- ----------------------------------------------------------------- -->
<sect1>How do I know if my patch got applied, and if not, why not?
<p>
475
Uploaded patches will be moved to <tt>ftp://ftp.gtk.org/pub/gtk/patches</tt>
476
477
478
479
480
481
482
483
484
485
where one of the GTK+ development team will pick them up. If applied, they
will be moved to <tt>/pub/gtk/patches/old</tt>.

Patches that aren't applied, for whatever reason, are moved to 
<tt>/pub/gtk/patches/unapplied</tt> or <tt>/pub/gtk/patches/outdated</tt>.
At this point you can ask on the <tt/gtk-list/ mailing list why your patch
wasn't applied. There are many possible reasons why patches may not be
applied, ranging from it doesn't apply cleanly, to it isn't right. Don't
be put off if your patch didn't make it first time round.

Shawn Amundson's avatar
Shawn Amundson committed
486
<!-- ----------------------------------------------------------------- -->
487
488
489
<sect1>What is the policy on incorporating new widgets into the library?
<p>
This is up to the authors, so you will have to ask them once you
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
490
are done with your widget. As a general guideline, widgets that are 
491
492
generally useful, work, and are not a disgrace to the widget set will 
gladly be included.
493

494
<!-- ----------------------------------------------------------------- -->
Shawn Amundson's avatar
Shawn Amundson committed
495
<sect1>Is anyone working on bindings for languages other than C?
496
<p>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
497
498
499
The GTK+ home page (<htmlurl url="http://www.gtk.org/" 
name="http://www.gtk.org/">) presents a list of GTK+ bindings.

Shawn Amundson's avatar
Shawn Amundson committed
500
<itemize>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
<item>There are several C++ wrappers for GTK+.
  <itemize>
  
  <item>the gtk-- package, which is a very small wrapper for GTK+.
  You can find the home page at:
  <htmlurl url="http://www.cs.tut.fi/~p150650/gtk/gtk--.html"
  name="http://www.cs.tut.fi/~p150650/gtk/gtk--.html">. 
  The FTP site is 
  <htmlurl url="ftp://ftp.gtk.org/pub/gtk/gtk--"
  name="ftp://ftp.gtk.org/pub/gtk/gtk--">.
  
  <item>the VDK package, which was built as the base package of a GTK+
  application Borland-like builder. The home page can be found at
  <htmlurl url="www.guest.net/homepages/mmotta/VDKHome" 
  name="www.guest.net/homepages/mmotta/VDKHome">.

  <item>The wxWindows/Gtk package, a free C++ library for cross-platform 
  GUI development. The home page of this package is
  <htmlurl url="http://www.freiburg.linux.de/~wxxt/"
  name="http://www.freiburg.linux.de/~wxxt/">.

  </itemize> 
523
<p>
Shawn Amundson's avatar
Shawn Amundson committed
524

BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
525
<item>There are three known Objective-c bindings currently in development:
526

BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
527
  <itemize>
528

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

BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
534
535
536
537
538
539
540
541
542
543
544
  <item>If you are more inclined towards the 
  <htmlurl url="http://www.gnustep.org/" name="GNUstep project">,
  you may want to check out GTKKit by 
  <htmlurl url="mailto:helge@mdlink.de" name="Helge He&szlig;">.
  The intention is to setup a GTK+ binding using the FoundationKit. 
  GTKKit includes nicities like writing a XML-type template file to 
  construct a GTK+ interface.

  <item>The GToolKit package, which can be found at
  <htmlurl url="ftp://ftp.gtk.org/pub/gtk/objc-gtoolkit/" 
  name="ftp://ftp.gtk.org/pub/gtk/objc-gtoolkit/">.
545
546
547

 </itemize> 
<p>               
548
<item>Perl bindings
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
549
550
  <htmlurl url="ftp://ftp.gtk.org/pub/gtk/perl"
  name="ftp://ftp.gtk.org/pub/gtk/perl">
551
552
<P>
<item>Guile bindings. The home page is at
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
553
554
555
556
  <htmlurl url="http://www.ping.de/sites/zagadka/guile-gtk"
  name="http://www.ping.de/sites/zagadka/guile-gtk">.
  By the way, Guile is the GNU Project's implemention of R4RS Scheme (the
  standard). If you like Scheme, you may want to take a look at this.
Shawn Amundson's avatar
Shawn Amundson committed
557
<p>
558

Shawn Amundson's avatar
Shawn Amundson committed
559
<item>David Monniaux reports:
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
560
561
  <quote>I've started a gtk-O'Caml binding system.
  The basics of the system, including callbacks, work fine.
Shawn Amundson's avatar
Shawn Amundson committed
562

BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
563
564
565
566
  The current development is in
  <htmlurl url="http://www.ens-lyon.fr/~dmonniau/arcs"
  name="http://www.ens-lyon.fr/~dmonniau/arcs">
  </quote>
Tony Gale's avatar
Tony Gale committed
567

BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
568
<item> Several python bindings have been done:
569
<p>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
  <itemize>
  <item>pygtk is at 
  <htmlurl url="http://www.daa.com.au/~james/pygtk" 
  name="http://www.daa.com.au/~james/pygtk"> and 
  <htmlurl url="ftp://ftp.gtk.org/pub/gtk/python"
  name="ftp://ftp.gtk.org/pub/gtk/python">

  <item>python-gtk is at
  <htmlurl url="http://www.ucalgary.ca/~nascheme/python-gtk" 
  name="http://www.ucalgary.ca/~nascheme/python-gtk">
  </itemize>
<p>
<item>There's are a couple of OpenGL/Mesa widgets available for
GTK+. I suggest you start at
  <htmlurl url="http://www.student.oulu.fi/~jlof/gtkglarea/index.html" 
  name="http://www.student.oulu.fi/~jlof/gtkglarea/index.html">
586
<p>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
587
588
<item>Last, there are a lot of other language bindings for languages such as 
  Eiffel, TOM, Pascal, Pike, etc.
Tony Gale's avatar
Tony Gale committed
589

Shawn Amundson's avatar
Shawn Amundson committed
590
</itemize>
Tony Gale's avatar
Tony Gale committed
591

592
<!-- ***************************************************************** -->
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
593
<sect>Development with GTK+: the begining
Tony Gale's avatar
Tony Gale committed
594
595
596
597
598
599
<!-- ***************************************************************** -->
<!-- ----------------------------------------------------------------- -->
<sect1>How do I get started?
<p>
So, after you have installed GTK+ there are a couple of things that can
ease you into developing applications with it. There is the
600
601
GTK+ Tutorial <htmlurl url="http://www.gtk.org/tutorial/" 
name="&lt;http://www.gtk.org/tutorial/&gt;">, which is undergoing 
602
development. This will introduce you to writing applications using C.
Tony Gale's avatar
Tony Gale committed
603
604
605
606
607
608
609

The Tutorial doesn't (yet) contain information on all of the widgets
that are in GTK+. For example code on how to use the basics of all the
GTK+ widgets you should look at the file gtk/testgtk.c (and associated
source files) within the GTK+ distribution. Looking at these exmaples will
give you a good grounding on what the widgets can do.

BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
<!-- ----------------------------------------------------------------- -->
<sect1>I tried to compile a small <tt/Hello World/ of mine, but it failed. Any clue?
<p>
Since you are good at coding, we will not deal with compile time error here :).

The classic command line to compile a GTK+ based program is

<verb>
gcc -o myprg [c files list] `gtk-config --cflags --libs`
</verb>

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 'gtk-config --cflags --libs'. The text in
backquotes is an instruction to your shell to substitute the output of
executing this text into the command line.

The command line above ensure that:
<itemize>

  <item>the correct C compiler flags will be used to compile the program
        (including the complete C header directory list)

  <item>your program will be linked with the needed libraries.

</itemize>

<sect1>What about using the <tt/make/ utility?
<p>
This is a sample makefile which compile a GTK+ based program:

<tscreen><verb>
# basic GTK+ app makefile
SOURCES = myprg.c foo.c bar.c
OBJS    = ${SOURCES:.c=.o}
CFLAGS  = `gtk-config --cflags`
LDADD   = `gtk-config --libs`
CC      = gcc
PACKAGE = myprg

all : ${OBJS}
        ${CC} -o ${PACKAGE} ${OBJS} ${LDADD}

.c.o:
        ${CC} ${CFLAGS} -c $<

# end of file
</verb></tscreen>

For more information about the <tt/make/ utility, you should read either the
related man page or the relevant info file.

<sect1>I use the backquote stuff in my makefiles, but my make process failed.
<p>
The backquote construction seems to not be accepted by some old <tt/make/
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
<htmlurl url="ftp://ftp.gnu.org/" name="ftp://ftp.gnu.org/">).

<!-- ----------------------------------------------------------------- -->
<sect1>I want to add some configure stuff, how could I do this?
<p>
To use autoconf/automake, you must first install the relevant packages. These
are:

<itemize>
  <item>the m4 preprocessor v1.4 or better
  <item>autoconf v2.13 or better
  <item>automake v1.4 or better
</itemize>

You'll find these packages on the GNU main ftp server (<htmlurl 
url="ftp://ftp.gnu.org/" name="ftp://ftp.gnu.org/">) or on any GNU mirror.

In order to use the powerfull autoconf/automake scheme, you must create
a configure.in which may look like:

<tscreen><verb>
dnl Process this file with autoconf to produce a configure script.
dnl configure.in for a GTK+ based program

AC_INIT(myprg.c)dnl
AM_INIT_AUTOMAKE(mypkbname,0.0.1)dnl
AM_CONFIG_HEADER(config.h)dnl

dnl Checks for programs.
AC_PROG_CC dnl check for the c compiler
dnl you should add CFLAGS="" here, 'cos it is set to -g by PROG_CC

dnl Checks for libraries.
AM_PATH_GTK(1.2.0,,AC_MSG_ERROR(mypkgname 0.1 needs GTK))dnl

AC_OUTPUT(
	Makefile
)dnl
</verb></tscreen>

You must add a Makefile.am file:

<tscreen><verb>
bin_PROGRAMS    = myprg
myprg_SOURCES   = myprg.c foo.c bar.c
INCLUDES        = @GTK_CFLAGS@
LDADD           = @GTK_LIBS@
CLEANFILES      = *~
DISTCLEANFILES  = .deps/*.P
</verb></tscreen>

then, to use these, simply type the following commands:

<verb>
aclocal
autoheader
autoconf
automake --add-missing --include-deps --foreign 
</verb>

For further informations, 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/or automake).

<!-- ----------------------------------------------------------------- -->
<sect1>I try to debug my GTK+ application with gdb, but it hangs my X server when I hit some breakpoint. Any Idea ?
<p>
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.
<P>
Run your program with the "--sync" 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>

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>

<!-- ***************************************************************** -->
<sect>Development with GTK+: the programming part
<!-- ***************************************************************** -->
<!-- ----------------------------------------------------------------- -->
Tony Gale's avatar
Tony Gale committed
759
760
761
<sect1>What widgets are in GTK?
<p>
The GTK+ Tutorial lists the following widgets:
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
762

Tony Gale's avatar
Tony Gale committed
763
<verb>
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
  GtkObject
   +GtkData
   | +GtkAdjustment
   | `GtkTooltips
   `GtkWidget
     +GtkContainer
     | +GtkBin
     | | +GtkAlignment
     | | +GtkEventBox
     | | +GtkFrame
     | | | `GtkAspectFrame
     | | +GtkHandleBox
     | | +GtkItem
     | | | +GtkListItem
     | | | +GtkMenuItem
     | | | | `GtkCheckMenuItem
     | | | |   `GtkRadioMenuItem
     | | | `GtkTreeItem
     | | +GtkViewport
     | | `GtkWindow
     | |   +GtkColorSelectionDialog
     | |   +GtkDialog
     | |   | `GtkInputDialog
     | |   `GtkFileSelection
     | +GtkBox
     | | +GtkButtonBox
     | | | +GtkHButtonBox
     | | | `GtkVButtonBox
     | | +GtkHBox
     | | | +GtkCombo
     | | | `GtkStatusbar
     | | `GtkVBox
     | |   +GtkColorSelection
     | |   `GtkGammaCurve
     | +GtkButton
     | | +GtkOptionMenu
     | | `GtkToggleButton
     | |   `GtkCheckButton
     | |     `GtkRadioButton
     | +GtkCList
804
     |   `GtkCTree
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
     | +GtkFixed
     | +GtkList
     | +GtkMenuShell
     | | +GtkMenuBar
     | | `GtkMenu
     | +GtkNotebook
     | +GtkPaned
     | | +GtkHPaned
     | | `GtkVPaned
     | +GtkScrolledWindow
     | +GtkTable
     | +GtkToolbar
     | `GtkTree
     +GtkDrawingArea
     | `GtkCurve
     +GtkEditable
     | +GtkEntry
     | | `GtkSpinButton
     | `GtkText
     +GtkMisc
     | +GtkArrow
     | +GtkImage
     | +GtkLabel
     | | `GtkTipsQuery
     | `GtkPixmap
     +GtkPreview
     +GtkProgressBar
     +GtkRange
     | +GtkScale
     | | +GtkHScale
     | | `GtkVScale
     | `GtkScrollbar
     |   +GtkHScrollbar
     |   `GtkVScrollbar
     +GtkRuler
     | +GtkHRuler
     | `GtkVRuler
     `GtkSeparator
       +GtkHSeparator
       `GtkVSeparator
Tony Gale's avatar
Tony Gale committed
845
</verb>
846

847
848
849
<!-- ----------------------------------------------------------------- -->
<sect1>Is GTK+ thread safe? How do I write multi-threaded GTK+ applications?
<p>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
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.

When GLib is intialized to be thread-safe, GTK+ is
<em>thread aware</em>. 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.

A minimal main program for a threaded GTK+ application
looks like:

<verb>
int
main (int argc, char *argv[])
{
  GtkWidget *window;

  g_thread_init(NULL);
  gtk_init(&amp;argc, &amp;argv);

  window = create_window();
  gtk_widget_show(window);

  gdk_threads_enter();
  gtk_main();
  gdk_threads_leave();

  return(0);
}
</verb>

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.

<!-- This is the old answer - TRG


898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
Although GTK+, like many X toolkits, isn't thread safe, this does
not prohibit the development of multi-threaded applications with
GTK+. 

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

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

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

Note that this is a little effort, but it allows you to be
potentially more efficient than a completely thread safe GTK+. You
get to decide the granularity of the thread locking. You also have to
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
920
921
make sure that the thread that calls <tt/gtk_main()/ is holding the lock when
it calls <tt/gtk_main()/.
922
923

The next thing to worry about is that since you were holding the
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
924
global mutex when you entered <tt/gtk_main()/, all callbacks will also be
925
926
927
928
929
holding it. This means that the callback must release it if it's
going to call any other code that might reacquire it. Otherwise
you'll get deadlock. Also, you must be holding the mutex when you
finally return from the callback. 

BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
930
In order to allow threads other than the one calling <tt/gtk_main/ to
931
932
933
934
935
936
937
938
939
940
941
942
943
944
get access to the mutex, we also need to register a work function
with GTK that allows us to release the mutex periodically.

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

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

Regardless, it's especially not a priority since relatively good
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
945
workarounds exist. -->
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048

<!-- ----------------------------------------------------------------- -->
<sect1>How do I find out about the selection of a GtkList?
<p>

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

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

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

A GList structure is just a simple structure for doubly linked lists.
there exist several g_list_*() functions to modify a linked list in
glib.h.  However the GTK_LIST(MyGtkList)->selection is maintained
by the gtk_list_*() functions and should not be modified.

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

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

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

GTK_SELECTION_BROWSE)   selection is NULL if the list
                        contains no widgets, otherwise
                        it contains a GList* pointer
                        for one GList structure.
GTK_SELECTION_MULTIPLE) selection is NULL if no listitems
                        are selected or a a GList* pointer
                        for the first selected item. that
                        in turn points to a GList structure
                        for the second selected item and so
                        on

GTK_SELECTION_EXTENDED) selection is NULL.
</verb>

The data field of the GList structure GTK_LIST(MyGtkList)->selection points
to the first GtkListItem that is selected.  So if you would like to determine 
which listitems are selected you should go like this:

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

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

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

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

        items=GTK_LIST(list)->selection;

        printf("Selected Items: ");
        while (items) {
                if (GTK_IS_LIST_ITEM(items->data))
                        printf("%d ", (guint) 
                gtk_object_get_user_data(items->data));
                items=items->next;
        }
        printf("\n");
}
</verb></tscreen>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163

<!-- ----------------------------------------------------------------- -->
<sect1>How can I prevent redrawing and resizing while I change multiple widgets?
<p>
Old versions of GTK+ used to provide the <tt/gtk_container_enable_resize()/ and
<tt/gtk_container_disable_resize()/ functions to enable or disable the resize while
modifying widgets.

In the current version of GTK+, there is no more need for these functions, 
since GTK+ will only resize widget during idle.

<!-- XXX should we get rid of this one ? -->

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

Define a signal handler:

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

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

And connect the handler to your object:

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

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

  /* and/or */

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

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

and, Owen Taylor wrote:

Note that a single button press will be received beforehand, and
if you are doing this for a button, you will therefore also get a
"clicked" signal for the button. (This is going to be true for
any toolkit, since computers aren't good at reading one's
mind.)
                                       
<!-- ----------------------------------------------------------------- -->
<sect1>By the way, what are the differences between signals and events?
<p>
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 <htmlurl url="http://www106.pair.com/rhp/sample_chapters.html"
name="http://www106.pair.com/rhp/sample_chapters.html">).

Moreover, Havoc posted this to the <tt/gtk-list/
<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.
<P>
  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.
<P>
  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>

<!-- ----------------------------------------------------------------- -->
<sect1>I have my signal connected to the the (whatever) event, but it seems I don't catch it. What's wrong?
<p>
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.

For example, 

<tscreen><verb>
  gtk_widget_add_events(window, GDK_KEY_RELEASE_MASK);
</verb></tscreen>

lets you catch the key release events. If you want to catch every events,
simply us the GDK_ALL_EVENTS_MASK event mask.

All the event masks are defined in the <tt/gdktypes.h/ file.

1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
<!-- ----------------------------------------------------------------- -->
<sect1>Is it possible to get some text displayed which is truncated to fit inside its allocation? 
<p>
GTK's behavior (no clipping) is a consequence of its attempts to
conserve X resources. Label widgets (among others) don't get their own
X window - they just draw their contents on their parent's window.
While it might be possible to have clipping occur by setting the clip
mask before drawing the text, this would probably cause a substantial
performance penalty.

Its possible that, in the long term, the best solution to such
problems might be just to change gtk to give labels X windows.
A short term workaround is to put the label widget inside another
widget that does get it's own window - one possible candidate would
be the viewport widget.

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

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

If you were doing this for a bunch of widgets, you might want to
copy gtkviewport.c and strip out the adjustment and shadow
functionality (perhaps you could call it GtkClipper).

<!-- ----------------------------------------------------------------- -->
<sect1>How can I define a separation line in a menu? 
<p>
1198
See the <htmlurl url="http://www.gtk.org/tutorial/"
1199
1200
1201
name="Tutorial"> for information on how to create menus.
However, to create a separation line in a menu, just insert an
empty menu item:
1202
1203
1204
1205
1206
1207
1208

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

1209
<!-- ----------------------------------------------------------------- -->
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1210
<sect1>How can I right justify a menu, such as Help? 
1211
<p>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1212
1213
Depending on if you use the MenuFactory or not, there are two ways to proceed.
With the MenuFactory, use something like the following:
1214
1215
1216
1217
1218

<tscreen><verb>
menu_path = gtk_menu_factory_find (factory,  "<MyApp>/Help");
gtk_menu_item_right_justify(menu_path->widget);
</verb></tscreen>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264

If you do not use the MenuFactory, you should simply use:

<tscreen><verb>
gtk_menu_item_right_justify(my_menu_item);
</verb></tscreen>

<!-- ----------------------------------------------------------------- -->
<sect1>How do I add some underlined accelerators to menu items?
<p>
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 <tt/File/ menu item with only one child (<tt/New/). The F in <tt/File/ 
and the N in <tt/New/ are underlined, and the relevant accelerators are 
created.

<tscreen><verb>
  menubar1 = gtk_menu_bar_new ();
  gtk_object_set_data (GTK_OBJECT (window1), "menubar1", menubar1);
  gtk_widget_show (menubar1);
  gtk_box_pack_start (GTK_BOX (vbox1), menubar1, FALSE, FALSE, 0);

  file1 = gtk_menu_item_new_with_label ("");
  tmp_key = gtk_label_parse_uline (GTK_LABEL (GTK_BIN (file1)->child),
                                   _("_File"));
  gtk_widget_add_accelerator (file1, "activate_item", accel_group,
                              tmp_key, GDK_MOD1_MASK, 0);
  gtk_object_set_data (GTK_OBJECT (window1), "file1", file1);
  gtk_widget_show (file1);
  gtk_container_add (GTK_CONTAINER (menubar1), file1);

  file1_menu = gtk_menu_new ();
  file1_menu_accels = gtk_menu_ensure_uline_accel_group (GTK_MENU (file1_menu));
  gtk_object_set_data (GTK_OBJECT (window1), "file1_menu", file1_menu);
  gtk_menu_item_set_submenu (GTK_MENU_ITEM (file1), file1_menu);

  new1 = gtk_menu_item_new_with_label ("");
  tmp_key = gtk_label_parse_uline (GTK_LABEL (GTK_BIN (new1)->child),
                                   _("_New"));
  gtk_widget_add_accelerator (new1, "activate_item", file1_menu_accels,
                              tmp_key, 0, 0);
  gtk_object_set_data (GTK_OBJECT (window1), "new1", new1);
  gtk_widget_show (new1);
  gtk_container_add (GTK_CONTAINER (file1_menu), new1);
</verb></tscreen>

1265
1266
1267
<!-- ----------------------------------------------------------------- -->
<sect1>How do I make my window modal? / How do I make a single window active?
<p>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1268
1269
After you create your window, do <tt/gtk_grab_add(my_window)/. And after 
closing the window do <tt/gtk_grab_remove(my_window)/.
1270
1271

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

1275
You are probably doing all the changes within a function 
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1276
1277
1278
without returning control to <tt/gtk_main()/. 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 <tt/gtk_main()/. You can
1279
1280
1281
1282
1283
1284
1285
force the drawing queue to be processed using something like:

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

1286
inside you're function that changes the widget.
1287
1288
1289
1290

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

BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
<!-- ----------------------------------------------------------------- -->
<sect1>How do I attach data to some GTK+ object/widget?
<p>
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.

There are two (easy) ways to attach some data to a gtk object. 
Using <tt/gtk_object_set_data()/ and <tt/gtk_object_get_data()/ seems to be the 
most common way to do this, as it provides a powerfull interface 
to connect objects and data.

<tscreen><verb>
void gtk_object_set_data(GtkObject *object, const gchar *key, gpointer data);
gpointer gtk_object_get_data(GtkObject *object, const gchar *key);
</verb></tscreen>

Since a short example is better than any lengthy speech:

<tscreen><verb>
struct my_struct	p1,p2,*result;
GtkWidget		*w;

gtk_object_set_data(GTK_OBJECT(w),"p1 data",(gpointer)&amp;p1);
gtk_object_set_data(GTK_OBJECT(w),"p2 data",(gpointer)&amp;p2);

result = gtk_object_get_data(GTK_OBJECT(w),"p1 data");
</verb></tscreen>

The <tt/gtk_object_set_user_data()/ and <tt/gtk_object_get_user_data()/
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.

<!-- ----------------------------------------------------------------- -->
<sect1>How do I remove the data I have attached to an object?
<p>
When attaching the data to the object, you can use the 
<tt/gtk_object_set_data_full()/
function. The three first arguments of the function are the same as in
<tt/gtk_object_set_data()/. The fourth one is a pointer to a callback function
which is called when the data is destroyed. The data is destroyed when
you:

<itemize>
<item> destroy the object
<item> replace the data with a new one (with the same key)
<item> replace the data with NULL (with the same key)
</itemize>

<!-- ----------------------------------------------------------------- -->
<sect1>How do I right (or otherwise) justify a label?
<p>
Are you sure you want to <em>justify</em> the labels?  The label class contains 
the <tt/gtk_label_set_justify()/ function that is used to control the 
justification of a multi-line label.

What you probably want is to set the <em>alignment</em> of the label, ie right 
align it, center it or left align it. If you want to do this, you 
should use:

<tscreen><verb>
void gtk_misc_set_alignment     (GtkMisc *misc,
                                gfloat xalign,
                                gfloat yalign);
</verb></tscreen>

where the <tt/xalign/ and <tt/yalign/ values are floats in [0.00;1.00].

<tscreen><verb>
GtkWidget       *label;

/* horizontal : left align, vertical : top */
gtk_misc_set_alignment(GTK_MISK(label), 0.0f, 0.0f);

/* horizontal : centered, vertical : centered */
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);
</verb></tscreen>

<!-- ----------------------------------------------------------------- -->
<sect1>How could I get any widget position?
<p>
As Tim Janik pointed out, there are different cases, and each case requires
a different solution.

<itemize>
<item>  If you want the position of a widget relative to its parent, you should
        use <tt/widget->allocate.x/ and <tt/widget->allocate.y/.
<item>  If you want the position of a window relative to the X root window,
        you should use <tt/gdk_window_get_geometry()/ or 
        <tt/gdk_window_get_origin()/.
<item>  Last but not least, if you want to get a Window Manager frame position,
        you should use <tt/gdk_window_get_deskrelative_origin()/.
</itemize>

<!-- ----------------------------------------------------------------- -->
<sect1>How do I set the position/size of a widget/window?
<p>
The <tt/gtk_widget_set_uposition()/ function is used to set the
position of any widget.

The <tt/gtk_widget_set_usize()/ 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
<tt/gtk_window_set_policy/ function. The definition of this function
is the following:

<tscreen><verb>
void        gtk_window_set_policy           (GtkWindow *window,
                                             gint allow_shrink,
                                             gint allow_grow,
                                             gint auto_shrink);
</verb></tscreen>

<tt/Auto_shrink/ will automatically shrink the window when the
requested size of the child widgets goes below the current size of the
window. <tt/Allow_shrink/ will give the user the authorisation to
make the window smaller that it should normally be. <tt/Allow_grow/
will give the user will have the ability to make the window
bigger. The default values for these parameters are:

<tscreen><verb>
allow_shrink = FALSE
allow_grow   = TRUE
auto_shrink  = FALSE
</verb></tscreen>

<!-- ----------------------------------------------------------------- -->
<sect1>How do I add a popup menu to my GTK+ application?
<p>
The <tt/menu/ example in the examples/menu directory of the GTK+ distribution
implements a popup menu with this technique :

<tscreen><verb>
static gint button_press (GtkWidget *widget, GdkEvent *event)
{

    if (event->type == GDK_BUTTON_PRESS) {
        GdkEventButton *bevent = (GdkEventButton *) event; 
        gtk_menu_popup (GTK_MENU(widget), NULL, NULL, NULL, NULL,
                        bevent->button, bevent->time);
        /* Tell calling code that we have handled this event; the buck
         * stops here. */
        return TRUE;
    }

    /* Tell calling code that we have not handled this event; pass it on. */
    return FALSE;
}
</verb></tscreen>

<!-- ----------------------------------------------------------------- -->
<sect1>How do I disable or enable a widget, such as a button?
<p>
To disable (or to enable) a widget, use the <tt/gtk_widget_set_sensitive()/
function. The first parameter is you widget pointer. The second parameter
is a boolean value: when this value is TRUE, the widget is enabled.

<!-- ----------------------------------------------------------------- -->
<sect1>How do I set the cursor position in a GtkText object?
<p>
Notice that the response is valid for any object that inherits from the 
GtkEditable class.

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 <tt/gtk_text_set_point()/ function. If you want to set the insertion point
at the current cursor position, use the following:

<tscreen><verb>
  gtk_text_set_point(GTK_TEXT(text),
      gtk_editable_get_position(GTK_EDITABLE(text)));
</verb></tscreen>

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:

<tscreen><verb>
static void
insert_bar (GtkWidget *text)
{
  /* jump to cursor mark */
  gtk_text_set_point (GTK_TEXT (text),
      gtk_editable_get_position (GTK_EDITABLE  (text)));

  gtk_text_insert (GTK_TEXT (text), NULL, NULL, NULL,
     "bar", strlen ("bar"));
}

int
main (int argc, char *argv[])
{
  GtkWidget *window, *text;

  gtk_init (&amp;argc, &amp;argv);

  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  text = gtk_text_new (NULL, NULL);
  gtk_text_set_editable (GTK_TEXT (text), TRUE);
  gtk_container_add (GTK_CONTAINER (window), text);

  /* connect after everything else */
  gtk_signal_connect_after (GTK_OBJECT(text), "button_press_event",
    GTK_SIGNAL_FUNC (insert_bar), NULL);

  gtk_widget_show_all(window);
  gtk_main();

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

Now, if you really want to change the cursor position, you should use the
<tt/gtk_editable_set_position()/ function.

<!-- ***************************************************************** -->
<sect>Development with GTK+: misc questions
<!-- ***************************************************************** -->
<!-- ----------------------------------------------------------------- -->
<sect1>Why do this strange 'x io error' occur when I <tt/fork()/ in my GTK+ app?
<p>
This is not really a GTK+ problem, and the problem is not related to <tt/fork()/
too. If the 'x io error' occurs then you probably use the <tt/exit()/ function
in order to exit from the child process.

When GDK opens an X display, it creates a socket file descriptor. When you use
the <tt/exit()/ function, you implicitly close all the open file descriptors,
and the underlying X library really doesn't like this.

The right function to use here is <tt/_exit()/. 

Eric Mouw gave the following piece of code about the fork()/exit() problem
(slightly modified)

<tscreen><verb>
  int pid = fork();

  if(pid==-1)
    {
      perror("fork");
      exit(-1);
    }
  else if(pid==0) /* child */
    {
      retval=system("a command"); /* can use exec* functions here */
      _exit(retval);  /* notice _exit() instead of exit() */
    }
  else /* parent */
    {
      for(;;)
        {
          if(waitpid(pid, &amp;status, WNOHANG) == pid)
            {
              waitpid(pid, &amp;status, WUNTRACED); /* anti zombie code */
              break;
            }
        }

      return(WEXITSTATUS(status));
    }
</verb></tscreen>

<!-- ----------------------------------------------------------------- -->
<sect1>I can't add more than (something like) 2000 chars in a GtkEntry. What's wrong?
<p>
There is now a known problem in the GtkEntry widget. In the
<tt/gtk_entry_insert_text()/ function, the following lines limit
the number of chars in the entry to 2047.

<tscreen><verb>
  /* The algorithms here will work as long as, the text size (a
   * multiple of 2), fits into a guint16 but we specify a shorter
   * maximum length so that if the user pastes a very long text, there
   * is not a long hang from the slow X_LOCALE functions.  */

  if (entry->text_max_length == 0)
    max_length = 2047;
  else
    max_length = MIN (2047, entry->text_max_length);
</verb></tscreen>

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

<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.
<P>
On a more practical note, I did implement this at one point and
determined it didn't look good and removed it.
</quote>     

Tony Gale's avatar
Tony Gale committed
1604
1605
1606
1607
<!-- ***************************************************************** -->
<sect>About gdk
<!-- ***************************************************************** -->

Shawn Amundson's avatar
Shawn Amundson committed
1608
<!-- ----------------------------------------------------------------- -->
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1609
<sect1>What is GDK?
Tony Gale's avatar
Tony Gale committed
1610
<p>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1611
1612
1613
1614
1615
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 
1616
and safer to use on multiple platforms.
Tony Gale's avatar
Tony Gale committed
1617
1618
1619

<!-- Examples, anybody? I've been mulling some over. NF -->
   
1620
1621
<sect1>How do I use color allocation?
<p>
1622
1623
1624
1625
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:
1626
1627
1628
1629
1630
1631
<tscreen>
<verb>
{
  GdkColor *color;
  int width, height;
  GtkWidget *widget;
1632
  GdkGC *gc;
1633
1634
1635
1636
1637
1638
1639

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

  /* find proper dimensions for rectangle */
1640
  gdk_window_get_size(widget->window, &amp;width, &amp;height);
1641
1642
1643
1644
1645
1646

  /* the color we want to use */
  color = (GdkColor *)malloc(sizeof(GdkColor));
  
  /* red, green, and blue are passed values, indicating the RGB triple
   * of the color we want to draw. Note that the values of the RGB components
1647
   * within the GdkColor are taken from 0 to 65535, not 0 to 255.
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
   */
  color->red = red * (65535/255);
  color->green = green * (65535/255);
  color->blue = blue * (65535/255);
  
  /* the pixel value indicates the index in the colormap of the color.
   * it is simply a combination of the RGB values we set earlier
   */
  color->pixel = (gulong)(red*65536 + green*256 + blue);

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

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

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

Tony Gale's avatar
Tony Gale committed
1675
<!-- ***************************************************************** -->
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1676
<sect>About GLib
Tony Gale's avatar
Tony Gale committed
1677
<!-- ***************************************************************** -->
1678

Shawn Amundson's avatar
Shawn Amundson committed
1679
<!-- ----------------------------------------------------------------- -->
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1680
<sect1>What is GLib?
Shawn Amundson's avatar
Shawn Amundson committed
1681
<p>
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1682
GLib is a library of useful functions and definitions available for use 
Shawn Amundson's avatar
Shawn Amundson committed
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
when creating GDK and GTK applications. It provides replacements for some
standard libc functions, such as malloc, which are buggy on some systems.
<p>
It also provides routines for handling:
<itemize>
<item>Doubly Linked Lists
<item>Singly Linked Lists
<item>Timers
<item>String Handling
<item>A Lexical Scanner
<item>Error Functions
</itemize>
1695

BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
<!-- ----------------------------------------------------------------- -->
<sect1>How can I use the doubly linked lists?
<p>
The GList object is defined as:

<tscreen><verb>
typedef struct _GList GList;

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

To use the GList objects, simply :

<tscreen><verb>
GList   *list = NULL;
GList   *listrunner;
gint    array[] = { 1, 2, 3, 4, 5, 6 };
gint    pos;
gint    *value;

/* add data to the list */
for (pos=0;pos < sizeof array; pos++) {
  list = g_list_append(list, (gpointer)&amp;array[pos]);
}

/* run through the list */
listrunner = g_list_first(list);
while (listrunner) {
  value = (gint *)listrunner->data;
  printf("%d\n", *value);
  listrunner = g_list_next(listrunner);
}

/* removing datas from the list */
listrunner = g_list_first(list);
list = g_list_remove_link(list, listrunner);
list = g_list_remove(list, &amp;array[4]);
</verb></tscreen>

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.
Tony Gale's avatar
Tony Gale committed
1745

BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1746
1747
1748
1749
<!-- 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 -->
1750
<!-- ----------------------------------------------------------------- -->
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1751
<sect1>Why use g_print, g_malloc, g_strdup and fellow glib functions?  
Shawn Amundson's avatar
Shawn Amundson committed
1752
<p>
1753
1754
1755
Thanks to Tim Janik who wrote to gtk-list: (slightly modified)
<quote>
Regarding g_malloc(), g_free() and siblings, these functions are much safer
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1756
1757
than their libc equivalents. For example, g_free() just returns if called 
with NULL. Also, if USE_DMALLOC is defined, the definition for these 
1758
1759
1760
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()).
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1761
<P>
1762
1763
1764
1765
1766
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. ;)
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1767
<P>
1768
1769
1770
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
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1771
(by using g_set_error_handler()) along the lines of <tt/gtk_print()/
1772
1773
1774
(inside of gtkmain.c).
</quote>

1775
<!-- ***************************************************************** -->
Tony Gale's avatar
Tony Gale committed
1776
<sect>GTK+ FAQ Contributions, Maintainers and Copyright
1777
<p>
1778
1779
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
1780
1781
answer).  With your help, this document can grow and become more useful!

Tony Gale's avatar
Tony Gale committed
1782
This document is maintained by Nathan Froyd 
BST 1999 Tony Gale's avatar
BST 1999 Tony Gale committed
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
<htmlurl url="mailto:maestrox@geocities.com" 
name="&lt;maestrox@geocities.com&gt;">,
Tony Gale <htmlurl url="mailto:gale@gimp.org" 
name="&lt;gale@gimp.org&gt;"> and 
Emmanuel Deloget <htmlurl url="mailto:pixel@epita.fr"
name="&lt;pixel@epita.fr&gt;">.
This FAQ was created by Shawn T. Amundson 
<htmlurl url="mailto:amundson@gimp.org" 
name="&lt;amundson@gimp.org&gt;"> who continues to provide support.

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

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

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

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

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

There is no guarentee that this document lives up to its intended
purpose.  This is simply provided as a free resource.  As such,
Tony Gale's avatar
Tony Gale committed
1816
the authors and maintainers of the information provided within can 
1817
1818
1819
not make any guarentee that the information is even accurate.

</article>