forked from bratsche/gtk-
/
gtk-faq.sgml
3643 lines (2845 loc) · 111 KB
/
gtk-faq.sgml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
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
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
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
759
760
761
762
763
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
804
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
845
846
847
848
849
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
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
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
<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []>
<book>
<bookinfo>
<date>January 14th 2004</date>
<title>GTK+ FAQ</title>
<authorgroup>
<author>
<firstname>Tony</firstname>
<surname>Gale</surname>
</author>
<author>
<firstname>Shawn</firstname>
<surname>Amundson</surname>
</author>
<author>
<firstname>Emmanuel</firstname>
<surname>Deloget</surname>
</author>
</authorgroup>
<abstract>
<para> This document is intended to answer questions that are
likely to be frequently asked by programmers using GTK+ or
people who are just looking at using GTK+. </para>
<para><emphasis>Note: </emphasis> This FAQ mainly covers GTK+ 1.2.
Where the text covers GTK+ 2.x this will be indicated</para>
</abstract>
</bookinfo>
<toc></toc>
<!-- ***************************************************************** -->
<chapter>
<title>General Information</title>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>Note: This FAQ is undergoing conversion to GTK+ 2.x</title>
<para>This FAQ is undergoing conversion to GTK+ 2.x.
Where the text covers GTK+ 2.x this will be indicated by prefixing the
text with: <emphasis>[GTK+ 2.x]</emphasis>. Where this is not
indicated, the text has not yet been updated from GTK+ 1.2 and may
not be totally correct.
</para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>Before anything else: the greetings <emphasis>[GTK 2.x]</emphasis></title>
<para>The FAQ authors want to thank:</para>
<itemizedlist spacing=Compact>
<listitem>
<simpara>Havoc Pennington</simpara>
</listitem>
<listitem>
<simpara>Erik Mouw</simpara>
</listitem>
<listitem>
<simpara>Owen Taylor</simpara>
</listitem>
<listitem>
<simpara>Tim Janik</simpara>
</listitem>
<listitem>
<simpara>Thomas Mailund Jensen</simpara>
</listitem>
<listitem>
<simpara>Joe Pfeiffer</simpara>
</listitem>
<listitem>
<simpara>Andy Kahn</simpara>
</listitem>
<listitem>
<simpara>Federico Mena Quntero</simpara>
</listitem>
<listitem>
<simpara>Damon Chaplin</simpara>
</listitem>
<listitem>
<simpara>and all the members of the GTK+ lists</simpara>
</listitem></itemizedlist>
<para> If we forgot you, please email us! Thanks again (I know,
it's really short :) </para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>Authors <emphasis>[GTK 2.x]</emphasis></title>
<para>The original authors of GTK+ were:</para>
<itemizedlist spacing=Compact>
<listitem>
<simpara>Peter Mattis</simpara>
</listitem>
<listitem>
<simpara>Spencer Kimball</simpara>
</listitem>
<listitem>
<simpara>Josh MacDonald</simpara>
</listitem>
</itemizedlist>
<para>Since then, much has been added by others. Please see the
AUTHORS file in the distribution for the GTK+ Team. The people currently
contributing the most code to GTK+ are (in no particular order):</para>
<itemizedlist spacing=Compact>
<listitem>
<simpara>Owen Taylor</simpara>
</listitem>
<listitem>
<simpara>Matthias Clasen</simpara>
</listitem>
<listitem>
<simpara>Federico Mena Quintero</simpara>
</listitem>
<listitem>
<simpara>Soeren Sandmann</simpara>
</listitem>
<listitem>
<simpara>Padraig O'Briain</simpara>
</listitem>
<listitem>
<simpara>Manish Singh</simpara>
</listitem>
<listitem>
<simpara>Kristian Rietveld</simpara>
</listitem>
<listitem>
<simpara>Tor Lillqvist</simpara>
</listitem>
</itemizedlist>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>What is GTK+? <emphasis>[GTK 2.x]</emphasis></title>
<para>GTK+ is a multi-platform toolkit for creating graphical user
interfaces, originally designed with
the general look and feel of Motif. In reality, it looks much
better than Motif. It contains common and complex widgets, such as
file selection, and color selection widgets.</para>
<para>GTK+ was initially developed as a widget set for the GIMP (GNU Image
Manipulation Program). It has grown extensively since then, and is today
used by a large number of applications, and is the toolkit used by the
<ulink url="http://www.gnome.org/">GNOME</ulink> desktop project.</para>
<para>GTK+ is free software and part of the GNU Project. However, the
licensing terms for GTK+, the GNU LGPL, allow it to be used by all developers,
including those developing proprietary software, without any license fees
or royalties.</para>
<para>GTK+ has been designed from the ground up to support a range of
<ulink url="http://www.gtk.org/bindings.html">
language bindings</ulink>, not only C/C++. Using GTK+ from languages
such as Perl and Python (especially in combination with the Glade GUI
builder) provides an effective method of rapid application
development..</para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>What is the + in GTK+? <emphasis>[GTK 2.x]</emphasis></title>
<para>Peter Mattis informed the gtk mailing list that:</para>
<para><quote>I originally wrote gtk which included the three
libraries, libglib, libgdk and libgtk. It featured a flat
widget hierarchy. That is, you couldn't derive a new widget
from an existing one. And it contained a more standard
callback mechanism instead of the signal mechanism now present
in gtk+. The + was added to distinguish between the original
version of gtk and the new version. You can think of it as
being an enhancement to the original gtk that adds object
oriented features.</quote></para>
<para>Although much has changed with GTK+, and Peter, Spencer and Josh
don't have any direct involvement these days, the name is kept to keep
a link with the heritage of GTK+.</para>
<para>GTK+ is now additionally based upon the Pango and ATK
libraries, that provide text layout and rendering and accessibility
interfaces.</para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>Does the G in GTK+, GDK and GLib stand for? <emphasis>[GTK 2.x]</emphasis></title>
<para>GTK+ == The GIMP Toolkit</para>
<para>GDK == GTK+ Drawing Kit</para>
<para>GLib == G Library</para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>Where is the documentation for GTK+? <emphasis>[GTK 2.x]</emphasis></title>
<para>In the GTK+ distribution's doc/ directory you will find
the API Reference for both GTK and GDK, this FAQ and the
GTK Tutorial.</para>
<para>In addition, you can find links to HTML versions of
these documents by going to <ulink url="http://www.gtk.org/">
http://www.gtk.org/</ulink>. A
packaged version of the GTK Tutorial, with SGML, HTML,
Postscript, DVI and text versions can be found in <ulink
url="ftp://ftp.gtk.org/pub/gtk/tutorial">
ftp://ftp.gtk.org/pub/gtk/tutorial
</ulink></para>
<para>There are now a few books available that deal with
programming GTK+, GDK and GNOME. Unfortunately, they
currently are all based upon GTK+ 1.x:</para>
<itemizedlist>
<listitem><simpara>Eric Harlows book entitled "Developing
Linux Applications with GTK+ and GDK". The ISBN is
0-7357-0021-4</simpara>
</listitem>
<listitem><simpara>The example code from Eric's book is
available on-line at <ulink
url="http://www.bcpl.net/~eharlow/book">
http://www.bcpl.net/~eharlow/book</ulink></simpara>
</listitem>
<listitem><simpara>Havoc Pennington has released a book called
"GTK+/GNOME Application Development". The ISBN is
0-7357-0078-8</simpara>
<simpara>The free version of the book lives here: <ulink
url="http://developer.gnome.org/doc/GGAD/">
http://developer.gnome.org/doc/GGAD/
</ulink></simpara>
<simpara>And Havoc maintains information about it and
errata here: <ulink
url="http://pobox.com/~hp/gnome-app-devel.html">
http://pobox.com/~hp/gnome-app-devel.html
</ulink></simpara>
</listitem>
<listitem><simpara>"GTK+ Programming in C" by
Syd Logan. ISBN: 0-1301-4264-6</simpara>
</listitem>
<listitem><simpara>"Linux GNOME/GTK+ Programming Bible" by
Arthur Griffith. ISBN: 0-7645-4640-6</simpara>
</listitem>
<listitem><simpara>"Beginning GTK+/GNOME Programming" by
Peter Wright. ISBN: 1-8610-0381-1</simpara>
</listitem>
<listitem><simpara>"Sams Teach Yourself GTK+ Programming
in 21 Days" by Donna Martin
. ISBN: 0-6723-1829-6</simpara>
</listitem>
</itemizedlist>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1 id="faq-MailLists">
<title>Is there a mailing list (or mailing list archive) for
GTK+? <emphasis>[GTK 2.x]</emphasis></title>
<para>Information on mailing lists relating to GTK+ can be
found at: <ulink
url="http://www.gtk.org/mailinglists.html">
http://www.gtk.org/mailinglists.html
</ulink></para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>How to get help with GTK+ <emphasis>[GTK 2.x]</emphasis></title>
<para>First, make sure your question isn't answered in the
documentation, this FAQ or the tutorial. Done that? You're
sure you've done that, right? In that case, the best place to
post questions is to the GTK+ mailing list.</para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>How to report bugs in GTK+ <emphasis>[GTK 2.x]</emphasis></title>
<para>Bugs should be reported to the GNOME bug tracking system
(<ulink url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>).
You will need to enter your email address and receive a password before
you can use the system to register a new bug report.</para>
<para>There are a number of options to select and boxes to fill in when
submitting a bug report. Please remember that the more information you
give, the easier it will be to track the problem down. Extra information
that may prove useful includes:</para>
<itemizedlist>
<listitem><simpara> How to reproduce the bug.</simpara>
<simpara>If you can reproduce it with the testgtk program
that is built in the gtk/ subdirectory, that will be most
convenient. Otherwise, please include a complete, short test
program that exhibits the behavior. As a last resort, you can also
provide a pointer to a larger piece of software that can
be downloaded.</simpara>
<simpara>(Bugs that can be reproduced within the GIMP are
almost as good as bugs that can be reproduced in
testgtk. If you are reporting a bug found with the GIMP,
please include the version number of the GIMP you are
using)</simpara>
</listitem>
<listitem><simpara> If the bug was a crash, the exact text that was
printed out when the crash occurred. If you can easily reproduce this
crash then running the program under a debugger (e.g. gdb) and getting
a backtrace when the crash occurs is very useful.</simpara>
</listitem>
<listitem><simpara> Further information such as stack traces
may be useful. If you do send a stack trace,
and the error is an X error, it will be more useful if the stacktrace is
produced running the test program with the <literal>--sync</literal>
command line option.</simpara>
</listitem>
</itemizedlist>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>Is there a Windows version of GTK+? <emphasis>[GTK 2.x]</emphasis></title>
<para>The Win32 port of GTK+ is maintained concurrently with the Xwindows
version in CVS. As such it is a supported architecture.</para>
<para>The Win32 port has been predominately done by Tor Lillqvist. Tor
maintains some information on <ulink url="http://www.gimp.org/~tml/gimp/win32/">
GTK+ and GIMP for Windows</ulink>.</para>
<para>There is a pre-compiled, easy-to-install version of GTK+ for
windows on the <ulink url="http://www.dropline.net/gtk/">
Dropline GTK+</ulink> site.</para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>What applications have been written with GTK+? <emphasis>[GTK 2.x]</emphasis></title>
<para>The GNOME software map contains a catalogue of software that is
built using GNOME and GTK+. The catalogue is searchable and browsable, so
provides easy access.</para>
<para>Some of the best known projects utilising GTK+ are:</para>
<itemizedlist>
<listitem><simpara> GIMP (<ulink
url="http://www.gimp.org/">http://www.gimp.org/</ulink>), an
image manipulation program</simpara>
</listitem>
<listitem><simpara> AbiWord (<ulink
url="http://www.abiword.org/">http://www.abiword.com/</ulink>),
a professional word processor</simpara>
</listitem>
<listitem><simpara> Dia (<ulink
url="http://www.lysator.liu.se/~alla/dia/dia.html">
http://www.lysator.liu.se/~alla/dia/dia.html</ulink>),
a diagram creation program</simpara>
</listitem>
<listitem><simpara> GnuCash (<ulink
url="http://www.gnucash.org/">
http://www.gnucash.org/</ulink>),
a personal finance manager</simpara>
</listitem>
<listitem><simpara> Gnumeric (<ulink
url="http://www.gnome.org/projects/gnumeric/">
http://www.gnome.org/projects/gnumeric/</ulink>),
the GNOME spreadsheet application</simpara>
</listitem>
<listitem><simpara> Glade (<ulink
url="http://glade.gnome.org/">http://glade.gnome.org/</ulink>), a
GTK+ based RAD tool which produces GTK+ and GNOME applications</simpara>
</listitem>
<listitem><simpara> Anjuta (<ulink
url="http://anjuta.sourceforge.net/">http://anjuta.sourceforge.net/</ulink>),
a versatile Integrated Development Environment (IDE) using C and C++ for GTK+
and GIMP.</simpara>
</listitem>
</itemizedlist>
</sect1>
</chapter>
<!-- ***************************************************************** -->
<chapter>
<title>How to find, configure, install, and troubleshoot GTK+</title>
<!-- ----------------------------------------------------------------- -->
<sect1 id="faq-Compile">
<title>What do I need to compile GTK+? <emphasis>[GTK 2.x]</emphasis></title>
<para>GTK+ is a large package that is dependent on a number of other
tools and libraries. It is recommended that you use precompiled
binary packages for your system if possible</para>
<para>To compile GTK+ from source you need a C compiler (gcc) and
the X Window System and associated development libraries and packages
on your system.</para>
<para>You will also need to have installed the tools
and libraries that GTK+ depends upon. These are listed below in the order
in which they need to be installed:</para>
<itemizedlist spacing=compact>
<listitem><simpara> pkg-config
(<ulink url="http://pkg-config.freedesktop.org/wiki">
pkg-config Site</ulink>)</simpara>
</listitem>
<listitem><simpara> GNU make
(<ulink url="http://www.gnu.org/software/make/">
GNU make Site</ulink>)</simpara>
</listitem>
<listitem><simpara> JPEG, PNG and TIFF image libraries
(<ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/dependencies/">
GTK+ Site</ulink>)</simpara>
</listitem>
<listitem><simpara> FreeType
(<ulink url="http://www.freetype.org/">
FreeType Site</ulink>)</simpara>
</listitem>
<listitem><simpara> fontconfig
(<ulink url="http://www.fontconfig.org/">
fontconfig Site</ulink>)</simpara>
</listitem>
<listitem><simpara> GNU libiconv library (if your system doesn't have iconv())
(<ulink url="http://www.gnu.org/software/libiconv/">
GNU libiconv Site</ulink>)</simpara>
</listitem>
<listitem><simpara> GNU gettext (if your system doesn't have gettext())
(<ulink url="http://www.gnu.org/software/gettext/">
GTK+ Site</ulink>)</simpara>
</listitem>
<listitem><simpara> GLib
(<ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">
GTK+ Site</ulink>)</simpara>
</listitem>
<listitem><simpara> Pango
(<ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">
GTK+ Site</ulink>)</simpara>
</listitem>
<listitem><simpara> ATK
(<ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">
GTK+ Site</ulink>)</simpara>
</listitem>
<listitem><simpara> GTK+
(<ulink url="ftp://ftp.gtk.org/pub/gtk/v2.2/">
GTK+ Site</ulink>)</simpara>
</listitem>
</itemizedlist>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>Where can I get GTK+? <emphasis>[GTK 2.x]</emphasis></title>
<para>The canonical site is <ulink
url="ftp://ftp.gtk.org/pub/gtk">ftp://ftp.gtk.org/pub/gtk</ulink>.</para>
<para>This site tends to get busy around the time of a new
GTK+ release so try and use one of the mirror sites that are
listed in <ulink
url="ftp://ftp.gtk.org/etc/mirrors">ftp://ftp.gtk.org/etc/mirrors
</ulink></para>
<para>Here's a few mirror sites to get you started:</para>
<itemizedlist spacing=compact>
<listitem><simpara> Africa -
<ulink url="ftp://ftp.is.co.za/applications/gimp">
ftp://ftp.is.co.za/applications/gimp</ulink></simpara>
</listitem>
<listitem><simpara> Australia -
<ulink
url="ftp://ftp.planetmirror.com/pub/gimp/gtk">
ftp://ftp.planetmirror.com/pub/gimp/gtk</ulink></simpara>
</listitem>
<listitem><simpara> Finland -
<ulink url="ftp://ftp.funet.fi/pub/sci/graphics/packages/gimp/gtk">
ftp://ftp.funet.fi/pub/sci/graphics/packages/gimp/gtk</ulink></simpara>
</listitem>
<listitem><simpara> Germany -
<ulink url="ftp://ftp.gwdg.de/pub/misc/grafik/gimp/gtk">
ftp://ftp.gwdg.de/pub/misc/grafik/gimp/gtk</ulink></simpara>
</listitem>
<listitem><simpara> Japan -
<ulink url="ftp://sunsite.sut.ac.jp/pub/archives/packages/gimp/gtk">
ftp://sunsite.sut.ac.jp/pub/archives/packages/gimp/gtk</ulink></simpara>
</listitem>
<listitem><simpara> UK -
<ulink url="http://www.mirror.ac.uk/sites/ftp.gimp.org/pub/gtk/">
http://www.mirror.ac.uk/sites/ftp.gimp.org/pub/gtk/</ulink></simpara>
</listitem>
</itemizedlist>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>How do I configure/compile GTK+? <emphasis>[GTK 2.x]</emphasis></title>
<para>Generally, the minimum you need to do is issue the commands:</para>
<para><literallayout><literal>./configure</literal>
<literal>make</literal>
<literal>make install</literal></literallayout></para>
<para>in the GTK+ source directory.</para>
<para>This generally also holds true for each of the packages that GTK+
depends upon, listed <link linkend="faq-Compile">above</link>.</para>
<para>There are various options that you can pass to the configure script
in order to change its default settings. The one that you are most likely
to want to use is the <literal>--prefix</literal>
argument, which defines where the package is to be install, e.g.</para>
<para>
<literallayout><literal>./configure --prefix=/usr</literal></literallayout>
</para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>When compiling GTK+ I get an error like: <literal>make:
file `Makefile' line 456: Syntax error</literal> <emphasis>[GTK 2.x]</emphasis></title>
<para>Make sure that you are using GNU make
(use <literal>make -v</literal>
to check). There are many weird and wonderful versions of make
out there, and not all of them handle the automatically
generated Makefiles.</para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>I've compiled and installed GTK+, but I can't get any
programs to link with it! <emphasis>[GTK 2.x]</emphasis></title>
<para>This problem is most often encountered when the GTK+
libraries can't be found or are the wrong version. Generally,
the compiler will complain about an 'unresolved symbol'.</para>
<para>Make sure that the libraries can be
found. You want to edit <filename>/etc/ld.so.conf</filename> to
include the directories which contain the GTK libraries,
so it looks something like:</para>
<para><literallayout><literal>/usr/X11R6/lib</literal>
<literal>/usr/local/lib</literal></literallayout></para>
<para>Then you need to run /sbin/ldconfig as root. You can
find what libraries GTK requires using</para>
<para><literallayout><literal>pkg-config gtk+-2.0 --libs</literal>
</literallayout></para>
<para>If your system doesn't use ld.so to find libraries
(such as Solaris), then you will have to use the LD_LIBRARY_PATH
environment variable (or compile the path into your program, which I'm
not going to cover here). So, with a Bourne type shell you can do (if
your GTK libraries are in /usr/local/lib):</para>
<para><literallayout>
<literal>export LD_LIBRARY_PATH=/usr/local/lib</literal>
</literallayout></para>
<para>and in a csh, you can do:</para>
<para><literallayout>
<literal>setenv LD_LIBRARY_PATH /usr/local/lib</literal>
</literallayout></para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>When installing a GTK+ application, configure reports
that it can't find GTK. <emphasis>[GTK 2.x]</emphasis></title>
<para>There are several common reasons for this:</para>
<itemizedlist>
<listitem><simpara>You have an old version of GTK installed
somewhere. You should remove this old copy, but note that
this may break applications that have been compiled against
the old version.</simpara>
</listitem>
<listitem><simpara><literal>pkg-config</literal> (or another
component of GTK) isn't in your path, or there is an old
version on your system. Type:</simpara>
<para><literallayout>
<literal>pkg-config gtk+-2.0 --modversion</literal>
</literallayout></para>
<para>to check for both of these. If it returns a value
different from what you expect, then you have an old
version of GTK on your system.</para>
</listitem>
<listitem><simpara>The ./configure script can't find the GTK
libraries. As ./configure compiles various test programs, it needs to be
able to find the GTK libraries. See the question above
for help on this. </simpara></listitem>
</itemizedlist>
<para>If none of the above help, then have a look in
config.log, which is generated by ./configure as it runs. At the
bottom will be the last action it took before failing. If it is a
section of source code, copy the source code to a file and compile it
with the line just above it in config.log. If the compilation is
successful, try executing it.</para>
</sect1>
</chapter>
<!-- ***************************************************************** -->
<chapter>
<title>Development of GTK+</title>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>Whats this CVS thing that everyone keeps talking about,
and how do I access it? <emphasis>[GTK 2.x]</emphasis></title>
<para>CVS is the Concurrent Version System and is a very
popular means of version control for software projects. It is
designed to allow multiple authors to simultanously operate on the same
source tree. This source tree is centrally maintained, but each
developer has a local mirror of this repository that they make
their changes to.</para>
<para>The GTK+ developers use a CVS repository to store the
master copy of the current development version of GTK+. As
such, people wishing to contribute patches to GTK+ should
generate them against the CVS version. Normal people should
use the packaged releases.</para>
<para>The CVS toolset is available as RPM packages from the
usual RedHat sites. The latest version is available at <ulink
url="http://download.cyclic.com/pub/">http://download.cyclic.com/pub/
</ulink></para>
<para>Anyone can download the latest CVS version of GTK+ by
using anonymous access using the following steps:</para>
<itemizedlist>
<listitem><simpara> In a bourne shell descendant (e.g. bash) type:</simpara>
<para><literallayout>
<literal>CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'</literal>
<literal>export CVSROOT</literal>
</literallayout></para>
</listitem>
<listitem><simpara>Next, the first time the source tree is
checked out, a cvs login is needed. </simpara>
<para><literallayout>
<literal>cvs login</literal>
</literallayout></para>
<para>This will ask you for a password. There is no
password for cvs.gimp.org, so just enter a carriage return.</para>
</listitem>
<listitem><simpara>To get the tree and place it in a subdir of your
current working directory, issue the command:</simpara>
<para><literallayout>
<literal>cvs -z3 get gtk+</literal>
</literallayout></para>
<para>Note that with the GTK+ 1.1 tree, glib has been moved to
a separate CVS module, so if you don't have glib installed you will
need to get that as well:</para>
<para><literallayout>
<literal>cvs -z3 get glib</literal>
</literallayout></para>
</listitem>
</itemizedlist>
<para>The CVS archive stores both the current development version of
GTK+ (the CVS HEAD branch) and all current and past stable versions.
If you want to retrieve a specific version of GTK+ you have to specify
the CVS tag corresponding to the version you want to checkout. If you
want to checkout the current GTK+ 2.2 stable source code, you would need
to use the following command:</para>
<para><literallayout>
<literal>cvs -z3 get -r gtk-2-2 gtk+</literal>
</literallayout></para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1 id="faq-Patches">
<title>How can I contribute to GTK+? <emphasis>[GTK 2.x]</emphasis></title>
<para>It's simple. If something doesn't work like you think it
should in a program, check the documentation to make sure
you're not missing something. If it is a true bug or missing
feature, track it down in the GTK+ source, change it, and
then generate a patch in the form of a 'context diff'. This
can be done using a command such as <literal>diff -ru
<oldfile> <newfile></literal>.</para>
<para>The patch should then be attached to a bug report in
the GNOME bug tracking system, which can also be used to store
general patches
(<ulink url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>).
</para>
<para>This method ensures that the patch will not be lost.</para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>How do I know if my patch got applied, and if not, why
not? <emphasis>[GTK 2.x]</emphasis></title>
<para>If you have used the GNOME bug tracking system (as stated
<link linkend="faq-Patches">above</link>) then the status
of your patch should be reflected in the bug report.</para>
<para>The GTK+ developers will generally add comments to the bug
report stating what needs to be done to get the patch applied,
or why the patch is not appropriate.</para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>What is the policy on incorporating new widgets into
the library? <emphasis>[GTK 2.x]</emphasis></title>
<para>This is up to the authors, so you will have to ask them
once you are done with your widget. As a general guideline,
widgets that are generally useful, work, and are not a
disgrace to the widget set will gladly be included.</para>
<para>The new widgets that get added to GTK+ are generally either
replacements for existing widgets that are no longer
deemed to be adequate, or have been developed externally to GTK+ but
have been widely tested.
<para>Before you spend months of your valuable time implementing your
revolutionary widget, it is highly recommended that you get some
feedback on your idea via the appropriate
<link linkend="faq-MailLists">mailing list</link>.</para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>Is anyone working on bindings for languages other than
C? <emphasis>[GTK 2.x]</emphasis></title>
<para>There is a list of <ulink url="http://www.gtk.org/bindings.html">
language bindings</ulink> on the GTK+ website.</para>
<para>The 'official' language bindings are C++, Ada and Python.
However, bindings for many other languages are available.</para>
</sect1>
</chapter>
<!-- ***************************************************************** -->
<chapter>
<title>Development with GTK+: the begining</title>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>How do I get started? <emphasis>[GTK 2.x]</emphasis></title>
<para>So, after you have installed GTK+ there are a couple of
things that can ease you into developing applications with
it. There is the GTK+ Tutorial <ulink
url="http://library.gnome.org/devel/gtk-tutorial/stable/">
http://library.gnome.org/devel/gtk-tutorial/stable/</ulink>, which is undergoing
development. This will introduce you to writing applications
using C.</para>
<para>The GTK+ Tutorial doesn't contain information on all of
the widgets that are in GTK+. For example code on how to use
the basics of all the GTK+ widgets you should look in the
directory 'tests' (and associated source files) within the GTK+
distribution. Looking at these examples will give you a good
grounding on what the widgets can do.</para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>How do I use the Glade GUI builder with GTK+? <emphasis>[GTK 2.x]</emphasis></title>
<para>There are two ways to use Glade. The first way is to use
Glade's facilities for generating code; the second
way is to use the libglade library which directly loads
the XML user interface description files that Glade
generates into a running program.</para>
<para>Experienced GTK+ programmers generally strongly recommend
using libglade; you don't have to worry about the interaction
between Glade generating the source and you editing it,
and its been shown to be a method that works better
for large projects, so there is a lot of example code
out there you can look at.</para>
<para>An introduction to using libglade can be found in the
libglade API docs
(<ulink url="http://developer.gnome.org/doc/API/2.0/libglade/libglade-notes.html#libglade-basics">
http://developer.gnome.org/doc/API/2.0/libglade/libglade-notes.html#libglade-basics</ulink>)
.</para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>How do I write security sensitive/SUID/SGID programs with GTK+?
Is GTK+ secure? What's this GTK_MODULES security hole I heard about?
<emphasis>[GTK 2.x]</emphasis></title>
<para>The short answer to this question is: you can't, so don't write SUID/SGID
programs with GTK+</para>
<para>GTK+ will refuse to run with elevated privileges, as it is not designed
to be used in this manner. The only correct way to write a setuid program with
a graphical user interface is to have a setuid backend that communicates with
the non-setuid graphical user interface via a mechanism such as a pipe and that
considers the input it receives to be untrusted.</para>
<para>For a more thorough explanation of the GTK+ Developers position on
this issue see <ulink
url="http://www.gtk.org/setuid.html">http://www.gtk.org/setuid.html</ulink>.</para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>I tried to compile a small <command>Hello World</command> of mine,
but it failed. Any clue? <emphasis>[GTK 2.x]</emphasis></title>
<para>Since you are good at coding, we will not deal with
compile time errors here :)</para>
<para>The classic command line to compile a GTK+ based program is</para>
<para><literallayout>
<literal>gcc -o myprog [c files] `pkg-config gtk+-2.0 --cflags --libs`</literal>
</literallayout></para>
<para>You should notice the backquote character which is used
in this command line. A common mistake when you start a GTK+
based development is to use quotes instead of backquotes. If
you do so, the compiler will complain about an unknown file
called <filename>pkg-config gtk+-2.0 --cflags --libs</filename>. The
text in backquotes is an instruction to your shell to
substitute the output of executing this command into the
commandline.</para>
<para>The command line above ensures that:</para>
<itemizedlist>
<listitem><simpara>the correct C compiler flags will be used
to compile the program (including the complete C header
directory list)</simpara>
</listitem>
<listitem><simpara>your program will be linked with the
needed libraries.</simpara>
</listitem>
</itemizedlist>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>What about using the <command>make</command>
utility? <emphasis>[GTK 2.x]</emphasis></title>
<para>This is a sample makefile which compiles a GTK+ based
program:</para>
<programlisting role="C">
# basic GTK+ app makefile
SOURCES = myprg.c foo.c bar.c
OBJS = ${SOURCES:.c=.o}
CFLAGS = `pkg-config gtk+-2.0 --cflags`
LDADD = `pkg-config gtk+-2.0 --libs`
CC = gcc
PACKAGE = myprg
all : ${OBJS}
${CC} -o ${PACKAGE} ${OBJS} ${LDADD}
.c.o:
${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>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>I use the backquote stuff in my makefiles, but my make
process failed. <emphasis>[GTK 2.x]</emphasis></title>
<para>The backquote construction seems to not be accepted by
some old <command>make</command> utilities. If you use one of these, the
make process will probably fail. In order to have the
backquote syntax working again, you should use the GNU make
utility (get it on the GNU ftp server at <ulink
url="ftp://ftp.gnu.org/gnu/make/">ftp://ftp.gnu.org/gnu/make/</ulink>).</para>
</sect1>
<!-- ----------------------------------------------------------------- -->
<sect1>
<title>I want to add some configure stuff, how could I do
this? <emphasis>[GTK 2.x]</emphasis></title>
<para>To use autoconf/automake, you must first install the
relevant packages. These are:</para>
<itemizedlist spacing=Compact>
<listitem><simpara>the m4 preprocessor v1.4 or better</simpara>
</listitem>
<listitem><simpara>autoconf v2.54 or better</simpara>
</listitem>
<listitem><simpara>automake v1.7 or better suggested</simpara>
</listitem>
</itemizedlist>
<para>You'll find these packages on the main GNU ftp server
(<ulink url="ftp://ftp.gnu.org/">ftp://ftp.gnu.org/</ulink>)
or on any GNU mirror.</para>
<para>In order to use the powerful autoconf/automake scheme,
you must create a configure.in which may look like:</para>