]> Pileus Git - ~andy/gtk/blob - docs/faq/gtkfaq.sgml
update links to documentation and remove question on whats needs to be
[~andy/gtk] / docs / faq / gtkfaq.sgml
1 <!doctype linuxdoc system>
2
3 <article>
4
5 <!-- Title information -->
6
7 <title>GTK+ FAQ
8
9 <!-- NOTE: Use only one author tag, otherwise sgml2txt barfs - TRG --> 
10 <author>Nathan Froyd, Tony Gale, Shawn T. Amundson.
11 <date>March 13th 1998
12 <abstract>
13 This document is intended to answer questions that are likely to be 
14 frequently asked by programmers using GTK+ or people who are just
15 looking at using GTK+.  
16 </abstract>
17
18 <!-- Table of contents -->
19 <toc>
20
21 <!-- Begin the document -->
22
23 <!-- ***************************************************************** -->
24 <sect>General Information
25
26 <!-- ----------------------------------------------------------------- -->
27 <sect1>Authors
28 <p>
29 The authors of GTK+ are:
30
31 <itemize>
32 <item>Peter Mattis    (petm@xcf.berkeley.edu)
33 <item>Spencer Kimball (spencer@xcf.berkeley.edu)
34 <item>Josh MacDonald  (jmacd@xcf.berkeley.edu)
35 </itemize>
36 GTK+ is distributed under the GNU Library General Public License
37
38 <!-- ----------------------------------------------------------------- -->
39 <sect1>What is GTK+?
40 <p>
41 GTK+ is a small and efficient widget set designed with the general look 
42 and feel of Motif.  In reality, it looks much better than Motif.  It
43 contains common widgets and some more complex widgets such as a file
44 selection, and color selection widgets.
45
46 GTK+ provides some unique features. (At least, I know of no other widget 
47 library which provides them). For
48 example, a button does not contain a label, it contains a child widget, 
49 which in most instances will be a label.
50 However, the child widget can also be a pixmap, image or any combination 
51 possible the programmer desires.
52 This flexibility is adhered to throughout the library. 
53
54 <!-- ----------------------------------------------------------------- -->
55 <sect1>What is the + in GTK+?
56 <P>
57 Peter Mattis informed the gtk mailing list that:
58 <quote>
59 "I originally wrote gtk which included the three libraries, libglib,
60 libgdk and libgtk. It featured a flat widget hierarchy. That is, you
61 couldn't derive a new widget from an existing one. And it contained
62 a more standard callback mechanism instead of the signal mechanism now
63 present in gtk+. The + was added to distinguish between the original
64 version of gtk and the new version. You can think of it as being an
65 enhancement to the original gtk that adds object oriented features."
66 </quote>
67
68 <!-- ----------------------------------------------------------------- -->
69 <sect1>Does the G in GTK+ stand for General, Gimp, or GNU?
70 <p>
71 Peter Mattis informed the gtk mailing list that:
72 <quote>
73 "I think the last time Spencer and I talked about it we decided on 
74 GTK = Gimp ToolKit. But I don't know for sure. Its definately not
75 GNU, though."
76 </quote>
77
78 <!-- ----------------------------------------------------------------- -->
79 <sect1>Where is the documentation for GTK+?
80 <p>
81 In the GTK+ distribution's doc/ directory you will find the
82 reference material for both GTK and GDK, this FAQ and the
83 GTK Tutorial.
84
85 In addition, you can find links to HTML versions of these documents 
86 by going to 
87 <htmlurl url="http://www.gimp.org/gtk/" 
88 name="http://www.gimp.org/gtk/">.
89
90 The Tutorial and FAQ can also be found at
91 <htmlurl url="http://www.geocities.com/ResearchTriangle/Lab/4299/"
92 name="http://www.geocities.com/ResearchTriangle/Lab/4299/">.
93
94 <!-- ----------------------------------------------------------------- -->
95 <sect1>Is there a mailing list (or mailing list archive) for GTK+?
96 <p>
97 There are two mailing lists:
98 <itemize>
99 <item>A mailing list for discussion of development of GTK based applications
100 is hosted at gtk-app-devel-list@redhat.com. To subscribe send an
101 email message to <htmlurl url="mailto:gtk-app-devel-list-request@redhat.com"
102 name="gtk-app-devel-list-request@redhat.com">
103 with <em>subscribe</em> in the <bf>subject</bf>.
104 <p>
105 <item>A mailing list for discussion of development of GTK is hosted 
106 at gtk-list@redhat.com. To subscribe send an
107 email message to <htmlurl url="mailto:gtk-list-request@redhat.com" 
108 name="gtk-list-request@redhat.com">
109 with <em>subscribe</em> in the <bf>subject</bf>.
110 <p>
111 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">
112 </itemize>
113 <!-- ----------------------------------------------------------------- -->
114 <sect1>The gtk-list hasn't had any traffic for days, is it dead?
115 <p>
116 No, everyone's just busy coding.
117
118 <!-- ----------------------------------------------------------------- -->
119 <sect1>How to get help with GTK+
120 <p>
121 First, make sure your question isn't answered in the documentation, this
122 FAQ or the tutorial. Done that? You're sure you've done that, right? In
123 that case, the best place to post questions is to the GTK+ mailing list.
124
125 <!-- ----------------------------------------------------------------- -->
126 <sect1>How to report bugs in GTK+
127 <p>
128 Bug reports should be sent to the GTK+ mailing list.
129
130 <!-- ----------------------------------------------------------------- -->
131 <sect1>What applications have been written with GTK+?
132 <p>
133 Some applications which use GTK+ are:
134 <itemize>
135 <item>GIMP (<htmlurl url="http://www.XCF.Berkeley.EDU/~gimp/" 
136                   name="http://www.XCF.Berkeley.EDU/~gimp/"> ), 
137       an image manipulation program
138 <item>Gsumi (<htmlurl url="http://www.msc.cornell.edu/~otaylor/gsumi/gsumi.html" 
139                   name="http://www.msc.cornell.edu/~otaylor/gsumi/gsumi.html">),
140       a fun B+W doodling program with XInput support.
141 <item>GUBI (<htmlurl url="http://www.SoftHome.net/pub/users/timj/gubi/index.htm"
142             name="http://www.SoftHome.net/pub/users/timj/gubi/index.htm">),
143       a user interface builder
144 <item>Gzilla (<htmlurl url="http://www.levien.com/gzilla/" name="http://www.levien.com/gzilla/">),
145       a web browser
146 <item>SANE (<htmlurl url="http://www.azstarnet.com/~axplinux/sane/" name="http://www.azstarnet.com/~axplinux/sane/"> ),
147       a universal scanner interface
148 <item>XQF (<htmlurl url="http://www.botik.ru/~roma/quake/" name="http://www.botik.ru/~roma/quake/">),
149       a QuakeWorld/Quake2 server browser and launcher
150 <item>ElectricEyes (<htmlurl url="http://www.labs.redhat.com/ee.shtml" name="http://www.labs.redhat.com/ee.shtml">),
151       an image viewer that aims to be a free replacement for xv
152 <item>GPK - the General Proxy Kit (<htmlurl url="http://www.humanfactor.com/gpk/" name="http://www.humanfactor.com/gpk/">),
153       an add-on library to permit thread-safe access to GTK+
154 <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">),
155       miscellaneous functions intended to ease color handling, UI construction,
156       vector operations, and math functions
157 <item>GDK Imlib (<htmlurl url="http://www.labs.redhat.com/imlib/" name="http://www.labs.redhat.com/imlib/">),
158       a fast image loading and manipulation library for GDK      
159 </itemize>
160 <p>
161 In addition to the above, the GNOME project (<htmlurl url="http://www.gnome.org"
162 name="http://www.gnome.org">)
163 is using GTK+ to build a free desktop for Linux. Many more programs can be found
164 there.
165
166 <!-- ***************************************************************** -->
167 <sect>How to find, configure, install, and troubleshoot GTK+
168
169 <!-- ***************************************************************** -->
170
171 <!-- ----------------------------------------------------------------- -->
172 <sect1>What do I need to run GTK+?
173 <p>
174 To compile GTK+, all you need is a C compiler (gcc) and the X Window System
175 and associated libraries on your system.
176
177 <!-- ----------------------------------------------------------------- -->
178 <sect1>Where can I get GTK+?
179 <p>
180 The canonical site is:
181 <verb>
182 ftp://ftp.gimp.org/pub/gtk
183 </verb>
184 Of course, any mirrors of ftp.gimp.org should have the latest version, too.
185
186 <sect1>How do I configure/compile GTK+?
187 <p>
188 Generally, all you will need to do is issue the commands:
189 <verb>
190 ./configure
191 make
192 </verb>
193 in the gtk+-version/ directory.
194
195 <!-- ----------------------------------------------------------------- -->
196 <sect1>When compiling GTK+ I get an error like: 
197 <tt/make: file `Makefile' line 456: Syntax error/
198 <p>
199 Make sure that you are using GNU make (use <tt/make -v/ to check). There are
200 many weird and wonderful versions of make out there, and not all of them
201 handle the automatically generated Makefiles.
202
203 <!-- ----------------------------------------------------------------- -->
204  
205 <sect1>I've compiled and installed GTK+, but I can't get any programs to link
206 with it!
207 <p>
208 This problem is most often encountered when the GTK+ libraries can't be 
209 found or are the wrong version. Generally, the compiler will complain about an
210 'unresolved symbol'.  There are two things you need to check:
211 <itemize>
212 <item>Make sure that the libraries can be found. You want to edit 
213 /etc/ld.so.conf to include /usr/local/lib (or whereever you installed GTK+),
214  so it looks something like:
215 <verb>
216 /usr/X11R6/lib
217 /usr/local/lib
218 </verb>
219 Then you need to run /sbin/ldconfig as root. 
220 <p>
221 <item>Make sure the linker is finding the correct set of libraries. If you
222 have a Linux distribution that installs GTK+ (e.g. RedHat 5.0) then this 
223 older version may be used. Now (assuming you have a RedHat
224 system), issue the command
225 <verb>
226 rpm -e gtk gtk-devel
227 </verb>
228 You may also want to remove the packages that depend on gtk (rpm will tell you
229 which ones they are).  If you don't have a RedHat Linux system, check to make sure
230 that neither <verb>/usr/lib</verb> or <verb>/usr/local/lib</verb> contain any of
231 the libraries libgtk, libgdk, libglib, or libgck.  If they do exist, remove them
232 (and any gtk include files, such as /usr/include/gtk and /usr/include/gdk) 
233 and reinstall gtk+.
234 </itemize>
235
236 <!-- ***************************************************************** -->
237 <sect>Development of GTK+
238 <!-- ***************************************************************** -->
239
240 <!-- ----------------------------------------------------------------- -->
241 <sect1>Whats this CVS thing that everyone keeps talking about, and how do I access it?
242 <p>
243 CVS is the Concurent Version System and is a very popular mean of 
244 version control for software projects. It is designed to allow multiple 
245 authors to be able to simultanously operate on the same source tree. 
246 This source tree is centrally maintained, but each developer has a
247 local mirror of this repository that they make there changes to.
248
249 The GTK+ developers use a CVS repository to store the master copy of
250 the current development version of GTK+. As such, people wishing to
251 contribute patches to GTK+ should generate them against the CVS version.
252 Normal people should use the packaged releases.
253
254 The CVS toolset is available as RPM packages from the usual RedHat sites.
255 The latest version is available at 
256 <htmlurl url="http://download.cyclic.com/pub/" 
257 name="&lt;http://download.cyclic.com/pub/&gt;">
258
259 Anyone can download the latest CVS version of GTK+ by using anonymous access
260 using the following steps:
261 <itemize>
262 <item> In a bourne shell descendant (e.g. bash) type:
263 <verb>
264 export CVSROOT=':pserver:anonymous@cvs.gimp.org:/debian/home/gnomecvs'
265 </verb>
266 <item>Next, the first time the source tree is checked out, a cvs login 
267 is needed. 
268 <verb>
269 cvs login
270 </verb>
271 This will ask you for a password. There is no password for cvs.gimp.org, 
272 so just enter a carriage return. 
273 <item>To get the tree and place it in a subdir of your current working directory, issue the command: 
274 <verb>
275 cvs -z9 get gtk+
276 </verb>
277 </itemize>
278 <!-- ----------------------------------------------------------------- -->
279 <sect1>How can I contribute to GTK+?
280 <p>
281 It's simple.  If something doesn't work like you think it should in a program,
282 check the documentation to make sure you're not missing something.  If it is a
283 true bug or missing feature, track it down in the GTK+ source, change it, 
284 and then generate a patch in the form of a 'context diff'. This can be done
285 using a command such as <tt/diff -ru &lt;oldfile&gt; &lt;newfile&gt;/. 
286 Then upload the patchfile to:
287 <verb>
288 ftp://ftp.gimp.org/incoming
289 </verb>
290 along with a README file.  Make sure you follow the naming conventions or your
291 patch will just be deleted! The filenames should be of this form:
292 <verb>
293 gtk-<username>-<date yymmdd-n>.patch.gz
294 gtk-<username>-<date yymmdd-n>.patch.README
295 </verb>
296 The "n" in the date indicates a unique number (starting from 0)
297 of patches you uploaded that day.  It should be 0, unless you
298 upload more than one patch in the same day.
299
300 Example:
301 <verb>
302 gtk-gale-982701-0.patch.gz
303 gtk-gale-982701-0.patch.README
304 </verb>
305 Once you upload <em>anything</em>, send the README to ftp-admin@gimp.org
306
307 <!-- ----------------------------------------------------------------- -->
308 <sect1>How do I know if my patch got applied, and if not, why not?
309 <p>
310 Uploaded patches will be moved to <tt>ftp://ftp.gimp.org/pub/gtk/patches</tt>
311 where one of the GTK+ development team will pick them up. If applied, they
312 will be moved to <tt>/pub/gtk/patches/old</tt>.
313
314 Patches that aren't applied, for whatever reason, are moved to 
315 <tt>/pub/gtk/patches/unapplied</tt> or <tt>/pub/gtk/patches/outdated</tt>.
316 At this point you can ask on the <tt/gtk-list/ mailing list why your patch
317 wasn't applied. There are many possible reasons why patches may not be
318 applied, ranging from it doesn't apply cleanly, to it isn't right. Don't
319 be put off if your patch didn't make it first time round.
320
321 <!-- ----------------------------------------------------------------- -->
322 <sect1>What is the policy on incorporating new widgets into the library?
323 <p>
324 This is up to the authors, so you will have to ask them once you
325 are done with your widget.  As a general guideline, widgets that are 
326 generally useful, work, and are not a disgrace to the widget set will 
327 gladly be included.
328
329 <!-- ----------------------------------------------------------------- -->
330 <sect1>Is anyone working on bindings for languages other than C?
331 <p>
332 Yes. There is 
333 <itemize>
334 <item>a C++ wrapper for GTK+ called gtk--. You can find the home page at:
335 <verb>
336 http://www.cs.tut.fi/~p150650/gtk/gtk--.html
337 </verb>
338 The FTP site is:
339 <verb>
340 ftp://ftp.gimp.org/pub/gtk/gtk--/
341 </verb>
342 <p>
343
344 <item>There are two Objective-c bindings currently in development:
345
346  <itemize>
347
348  <item>The <htmlurl url="http://www.gnome.org/" name="GNOME project's"> package
349  of choice is obgtk. Objgtk is based on the Object class and is maintained by
350  <htmlurl url="mailto:sopwith@cuc.edu" name="Elliot Lee">. Apparently, objgtk
351  is being accepted as the `standard' Objective-C binding for GTK+.
352
353  <item>If you are more inclined towards the 
354  <htmlurl url="http://www.gnustep.org/" name="GNUstep project">,
355  you may want to check out GTKKit by 
356  <htmlurl url="mailto:helge@mdlink.de" name="Helge Heszlig">.
357  The intention is to setup a GTK+ binding using the FoundationKit. 
358  GTKKit includes nicities like writing a XML-type template file to 
359  construct a GTK+ interface.
360
361  </itemize> 
362 <p>               
363 <item>Perl bindings
364 <verb>
365 ftp://ftp.gimp.org/pub/gtk/perl
366 </verb>
367    
368 <item>Guile bindings. The home page is at:
369 <verb>
370 http://www.ping.de/sites/zagadka/guile-gtk/
371 </verb>
372 By the way, Guile is the GNU Project's implemention of R4RS Scheme (the
373 standard). If you like Scheme, you may want to take a look at this.
374 <p>
375
376 <item>David Monniaux reports:
377 <quote>I've started a gtk-O'Caml binding system.
378 The basics of the system, including callbacks, work fine.
379
380 The current development is in
381 http://www.ens-lyon.fr/~dmonniau/arcs/
382 </quote>
383
384 <item>
385 Several python-gtk interfaces have been done. python-gtk is at:
386 <verb>
387 http://www.acs.ucalgary.cs/~nashceme/python-gtk/
388 </verb>
389 If you try python-gtk and don't like it, there's also pygtk located at:
390 <verb>
391 ftp://ftp.gimp.org/pub/gtk/python/
392 </verb>
393
394 <item>
395 There's a OpenGL/Mesa widget available for GTK+. Grab it at:
396 <verb>
397 http://www.sakuranet.or.jp/~aozasa/shige/doc/comp/gtk/gtkGL/files-en.html
398 </verb>
399
400 </itemize>
401
402 <!-- ***************************************************************** -->
403 <sect>Development with GTK+
404 <!-- ***************************************************************** -->
405 <!-- ----------------------------------------------------------------- -->
406 <sect1>How do I get started?
407 <p>
408 So, after you have installed GTK+ there are a couple of things that can
409 ease you into developing applications with it. There is the
410 GTK+ Tutorial <htmlurl url="http://www.gimp.org/gtk/tutorial/" 
411 name="&lt;http://www.gimp.org/gtk/tutorial/&gt;">, which is undergoing 
412 development. This will introduce you to writing applications using C.
413
414 The Tutorial doesn't (yet) contain information on all of the widgets
415 that are in GTK+. For example code on how to use the basics of all the
416 GTK+ widgets you should look at the file gtk/testgtk.c (and associated
417 source files) within the GTK+ distribution. Looking at these exmaples will
418 give you a good grounding on what the widgets can do.
419
420 <sect1>What widgets are in GTK?
421 <p>
422 The GTK+ Tutorial lists the following widgets:
423 <verb>
424   GtkObject
425    +GtkData
426    | +GtkAdjustment
427    | `GtkTooltips
428    `GtkWidget
429      +GtkContainer
430      | +GtkBin
431      | | +GtkAlignment
432      | | +GtkEventBox
433      | | +GtkFrame
434      | | | `GtkAspectFrame
435      | | +GtkHandleBox
436      | | +GtkItem
437      | | | +GtkListItem
438      | | | +GtkMenuItem
439      | | | | `GtkCheckMenuItem
440      | | | |   `GtkRadioMenuItem
441      | | | `GtkTreeItem
442      | | +GtkViewport
443      | | `GtkWindow
444      | |   +GtkColorSelectionDialog
445      | |   +GtkDialog
446      | |   | `GtkInputDialog
447      | |   `GtkFileSelection
448      | +GtkBox
449      | | +GtkButtonBox
450      | | | +GtkHButtonBox
451      | | | `GtkVButtonBox
452      | | +GtkHBox
453      | | | +GtkCombo
454      | | | `GtkStatusbar
455      | | `GtkVBox
456      | |   +GtkColorSelection
457      | |   `GtkGammaCurve
458      | +GtkButton
459      | | +GtkOptionMenu
460      | | `GtkToggleButton
461      | |   `GtkCheckButton
462      | |     `GtkRadioButton
463      | +GtkCList
464      | +GtkFixed
465      | +GtkList
466      | +GtkMenuShell
467      | | +GtkMenuBar
468      | | `GtkMenu
469      | +GtkNotebook
470      | +GtkPaned
471      | | +GtkHPaned
472      | | `GtkVPaned
473      | +GtkScrolledWindow
474      | +GtkTable
475      | +GtkToolbar
476      | `GtkTree
477      +GtkDrawingArea
478      | `GtkCurve
479      +GtkEditable
480      | +GtkEntry
481      | | `GtkSpinButton
482      | `GtkText
483      +GtkMisc
484      | +GtkArrow
485      | +GtkImage
486      | +GtkLabel
487      | | `GtkTipsQuery
488      | `GtkPixmap
489      +GtkPreview
490      +GtkProgressBar
491      +GtkRange
492      | +GtkScale
493      | | +GtkHScale
494      | | `GtkVScale
495      | `GtkScrollbar
496      |   +GtkHScrollbar
497      |   `GtkVScrollbar
498      +GtkRuler
499      | +GtkHRuler
500      | `GtkVRuler
501      `GtkSeparator
502        +GtkHSeparator
503        `GtkVSeparator
504 </verb>
505
506 <!-- ----------------------------------------------------------------- -->
507 <sect1>How can I prevent redrawing and resizing while I change multiple widgets?
508 <p> 
509 Use gtk_container_disable_resize and gtk_container_enable_resize around the 
510 code where you are changing a lot of stuff. This will result in much faster 
511 speed since it will prevent resizing of the entire widget hierarchy. 
512
513 <!-- ----------------------------------------------------------------- -->
514 <sect1>How do I catch a double click event in a list widget?
515 <p>
516 Tim Janik wrote to gtk-list (slightly modified):
517
518 Define a signal handler:
519
520 <tscreen><verb>
521 gint
522 signal_handler_event(GtkWiget *widget, GdkEvenButton *event, gpointer func_data)
523 {
524   if (GTK_IS_LIST_ITEM(widget) &&
525        (event->type==GDK_2BUTTON_PRESS ||
526         event->type==GDK_3BUTTON_PRESS) ) {
527     printf("I feel %s clicked on button %d\",
528            event->type==GDK_2BUTTON_PRESS ? "double" : "triple",
529            event->button);
530   }
531
532   return FALSE;
533 }
534 </verb></tscreen>
535
536 And connect the handler to your object:
537
538 <tscreen><verb>
539 {
540   /* list, list item init stuff */     
541
542   gtk_signal_connect(GTK_OBJECT(list_item),
543                      "button_press_event",
544                      GTK_SIGNAL_FUNC(signal_handler_event),
545                      NULL);
546
547   /* and/or */
548
549   gtk_signal_connect(GTK_OBJECT(list_item),
550                      "button_release_event",
551                      GTK_SIGNAL_FUNC(signal_handler_event),
552                      NULL);
553
554   /* something else */
555 }
556 </verb></tscreen>
557                           
558 <!-- ----------------------------------------------------------------- -->
559 <sect1>How do I find out about the selection of a GtkList?
560 <p>
561
562 Get the selection something like this:
563 <tscreen><verb>
564 GList *sel;
565 sel = GTK_LIST(list)->selection;
566 </verb></tscreen>
567
568 This is how GList is defined (quoting glist.h):
569 <tscreen><verb>
570 typedef struct _GList GList;
571
572 struct _GList
573 {
574   gpointer data;
575   GList *next;
576   GList *prev;
577 };
578 </verb></tscreen>
579
580 A GList structure is just a simple structure for doubly linked lists.
581 there exist several g_list_*() functions to modify a linked list in
582 glib.h.  However the GTK_LIST(MyGtkList)->selection is maintained
583 by the gtk_list_*() functions and should not be modified.
584
585 The selection_mode of the GtkList determines the selection
586 facilities of a GtkList and therefore the contents
587 of GTK_LIST(AnyGtkList)->selection:
588
589 <verb>
590 selection_mode          GTK_LIST()->selection contents
591 ------------------------------------------------------
592
593 GTK_SELECTION_SINGLE)   selection is either NULL
594                         or contains a GList* pointer
595                         for a single selected item.
596
597 GTK_SELECTION_BROWSE)   selection is NULL if the list
598                         contains no widgets, otherwise
599                         it contains a GList* pointer
600                         for one GList structure.
601 GTK_SELECTION_MULTIPLE) selection is NULL if no listitems
602                         are selected or a a GList* pointer
603                         for the first selected item. that
604                         in turn points to a GList structure
605                         for the second selected item and so
606                         on
607
608 GTK_SELECTION_EXTENDED) selection is NULL.
609 </verb>
610
611 The data field of the GList structure GTK_LIST(MyGtkList)->selection points
612 to the first GtkListItem that is selected.  So if you would like to determine 
613 which listitems are selected you should go like this:
614
615 Upon Initialization:
616 <tscreen><verb>
617 {
618         gchar           *list_items[]={
619                                 "Item0",
620                                 "Item1",
621                                 "foo",
622                                 "last Item",
623                         };
624         guint           nlist_items=sizeof(list_items)/sizeof(list_items[0]);
625         GtkWidget       *list_item;
626         guint           i;
627
628         list=gtk_list_new();
629         gtk_list_set_selection_mode(GTK_LIST(list), GTK_SELECTION_MULTIPLE);
630         gtk_container_add(GTK_CONTAINER(AnyGtkContainer), list);
631         gtk_widget_show (list);
632
633         for (i = 0; i < nlist_items; i++)
634         {
635                 list_item=gtk_list_item_new_with_label(list_items[i]);
636                 gtk_object_set_user_data(GTK_OBJECT(list_item), (gpointer)i);
637                 gtk_container_add(GTK_CONTAINER(list), list_item);
638                 gtk_widget_show(list_item);
639         }
640 }
641 </verb></tscreen>
642
643 To get known about the selection:
644 <tscreen><verb>
645 {
646         GList   *items;
647
648         items=GTK_LIST(list)->selection;
649
650         printf("Selected Items: ");
651         while (items) {
652                 if (GTK_IS_LIST_ITEM(items->data))
653                         printf("%d ", (guint) 
654                 gtk_object_get_user_data(items->data));
655                 items=items->next;
656         }
657         printf("\n");
658 }
659 </verb></tscreen>
660 <!-- ----------------------------------------------------------------- -->
661 <sect1>Is it possible to get some text displayed which is truncated to fit inside its allocation? 
662 <p>
663 GTK's behavior (no clipping) is a consequence of its attempts to
664 conserve X resources. Label widgets (among others) don't get their own
665 X window - they just draw their contents on their parent's window.
666 While it might be possible to have clipping occur by setting the clip
667 mask before drawing the text, this would probably cause a substantial
668 performance penalty.
669
670 Its possible that, in the long term, the best solution to such
671 problems might be just to change gtk to give labels X windows.
672 A short term workaround is to put the label widget inside another
673 widget that does get it's own window - one possible candidate would
674 be the viewport widget.
675
676 <tscreen><verb>
677 viewport = gtk_viewport (NULL, NULL);
678 gtk_widget_set_usize (viewport, 50, 25);
679 gtk_viewport_set_shadow_type (GTK_VIEWPORT(viewport), GTK_SHADOW_NONE);
680 gtk_widget_show(viewport);
681
682 label = gtk_label ("a really long label that won't fit");
683 gtk_container_add (GTK_CONTAINER(viewport), label);
684 gtk_widget_show (label);
685 </verb></tscreen>
686
687 If you were doing this for a bunch of widgets, you might want to
688 copy gtkviewport.c and strip out the adjustment and shadow
689 functionality (perhaps you could call it GtkClipper).
690
691 <!-- ----------------------------------------------------------------- -->
692 <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...
693 <p>
694 From: Peter Mattis
695
696 The reason buttons don't move their child down and to the right when
697 they are depressed is because I don't think that's what is happening
698 visually. My view of buttons is that you are looking at them straight
699 on. That is, the user interface lies in a plane and you're above it
700 looking straight at it. When a button gets pressed it moves directly
701 away from you. To be absolutely correct I guess the child should
702 actually shrink a tiny amount. But I don't see why the child should
703 shift down and to the left. Remember, the child is supposed to be
704 attached to the buttons surface. Its not good for it to appear like
705 the child is slipping on the surface of the button.
706
707 On a more practical note, I did implement this at one point and
708 determined it didn't look good and removed it.
709      
710 <!-- ----------------------------------------------------------------- -->
711 <sect1>How can I define a separation line in a menu? 
712 <p>
713 See the <htmlurl url="http://www.gimp.org/gtk/tutorial/"
714 name="Tutorial"> for information on how to create menus.
715 However, to create a separation line in a menu, just insert an
716 empty menu item:
717
718 <tscreen><verb>
719 menuitem = gtk_menu_item_new();
720 gtk_menu_append(GTK_MENU(menu), menuitem);
721 gtk_widget_show(menuitem);
722 </verb></tscreen>
723
724 <!-- ----------------------------------------------------------------- -->
725 <sect1>How can I right justify a menu, such as Help, when using the MenuFactory? 
726 <p>
727 Use something like the following:
728
729 <tscreen><verb>
730 menu_path = gtk_menu_factory_find (factory,  "<MyApp>/Help");
731 gtk_menu_item_right_justify(menu_path->widget);
732 </verb></tscreen>
733
734 <!-- ***************************************************************** -->
735 <sect>About gdk
736 <!-- ***************************************************************** -->
737
738 <!-- ----------------------------------------------------------------- -->
739 <sect1>What is gdk?
740 <p>
741 gdk is basically a wrapper around the standard Xlib function calls. If you are
742 at all familiar with Xlib, a lot of the functions in gdk will require little 
743 or no getting used to. All functions are written to provide an easy way 
744 to access Xlib functions in an easier an slightly more intuitive manner. 
745 In addition, since gdk uses glib (see below), it will be more portable 
746 and safer to use on multiple platforms.
747
748 <!-- Examples, anybody? I've been mulling some over. NF -->
749    
750 <sect1>How do I use color allocation?
751 <p>
752 One of the nice things about GDK is that it's based on top of Xlib; this is 
753 also a problem, especially in the area of color management. If you want 
754 to use color in your program (drawing a rectangle or such, your code 
755 should look something like this:
756 <tscreen>
757 <verb>
758 {
759   GdkColor *color;
760   int width, height;
761   GtkWidget *widget;
762   GdkGC *gc;
763
764   ...
765   
766   /* first, create a GC to draw on */
767   gc = gdk_gc_new(widget->window);
768
769   /* find proper dimensions for rectangle */
770   gdk_window_get_size(widget->window, &amp;width, &amp;height);
771
772   /* the color we want to use */
773   color = (GdkColor *)malloc(sizeof(GdkColor));
774   
775   /* red, green, and blue are passed values, indicating the RGB triple
776    * of the color we want to draw. Note that the values of the RGB components
777    * within the GdkColor are taken from 0 to 65535, not 0 to 255.
778    */
779   color->red = red * (65535/255);
780   color->green = green * (65535/255);
781   color->blue = blue * (65535/255);
782   
783   /* the pixel value indicates the index in the colormap of the color.
784    * it is simply a combination of the RGB values we set earlier
785    */
786   color->pixel = (gulong)(red*65536 + green*256 + blue);
787
788   /* However, the pixel valule is only truly valid on 24-bit (TrueColor)
789    * displays. Therefore, this call is required so that GDK and X can
790    * give us the closest color available in the colormap
791    */
792   gdk_color_alloc(gtk_widget_get_colormap(widget), color);
793
794   /* set the foreground to our color */
795   gdk_gc_set_foreground(gc, color);
796   
797   /* draw the rectangle */
798   gdk_draw_rectangle(widget->window, gc, 1, 0, 0, width, height);
799
800   ...
801 }
802 </verb>
803 </tscreen>
804
805 <!-- ***************************************************************** -->
806 <sect>About glib
807 <!-- ***************************************************************** -->
808
809 <!-- ----------------------------------------------------------------- -->
810 <sect1>What is glib?
811 <p>
812 glib is a library of useful functions and definitions available for use 
813 when creating GDK and GTK applications. It provides replacements for some
814 standard libc functions, such as malloc, which are buggy on some systems.
815 <p>
816 It also provides routines for handling:
817 <itemize>
818 <item>Doubly Linked Lists
819 <item>Singly Linked Lists
820 <item>Timers
821 <item>String Handling
822 <item>A Lexical Scanner
823 <item>Error Functions
824 </itemize>
825
826 <!-- Some Examples might be useful here! NF -->         
827
828 <!-- ----------------------------------------------------------------- -->
829 <sect1>Why use g_print, g_malloc, g_strdup and fellow glib functions ?  
830 <p>
831 Thanks to Tim Janik who wrote to gtk-list: (slightly modified)
832 <quote>
833 Regarding g_malloc(), g_free() and siblings, these functions are much safer
834 than thier libc equivalences.  For example, g_free() just returns if called 
835 with NULL.  Also, if USE_DMALLOC is defined, the definition for these 
836 functions changes (in glib.h) to use MALLOC(), FREE() etc...  If MEM_PROFILE
837 or MEM_CHECK are defined, there are even small statistics made counting
838 the used block sizes (shown by g_mem_profile() / g_mem_check()).
839 <p>
840 Considering the fact that glib provides an interface for memory chunks
841 to save space if you have lots of blocks that are always the same size
842 and to mark them ALLOC_ONLY if needed, it is just straight forward to
843 create a small saver (debug able) wrapper around the normal malloc/free
844 stuff as well - just like gdk covers Xlib. ;)
845 <p>
846 Using g_error() and g_warning() inside of applications like the GIMP
847 that fully rely on gtk even gives the opportunity to pop up a window
848 showing the messages inside of a gtk window with your own handler
849 (by using g_set_error_handler()) along the lines of gtk_print()
850 (inside of gtkmain.c).
851 </quote>
852
853 <!-- ***************************************************************** -->
854 <sect>GTK+ FAQ Contributions, Maintainers and Copyright
855 <p>
856 If you would like to make a contribution to the FAQ, send either one of us
857 an e-mail message with the exact text you think should be included (question and
858 answer).  With your help, this document can grow and become more useful!
859
860 This document is maintained by Nathan Froyd 
861 <htmlurl url="mailto:maestrox@geocities.com" name="&lt;maestrox@geocities.com&gt;">
862 and Tony Gale <htmlurl url="mailto:gale@gimp.org" name="&lt;gale@gimp.org&gt;">. 
863 This FAQ was created by Shawn T. Amundson <htmlurl url="mailto:amundson@gimp.org" 
864 name="&lt;amundson@gimp.org&gt;">who continues to provide support.
865
866 The GTK+ FAQ is Copyright (C) 1997,1998 by Shawn T. Amundson, Nathan Froyd and Tony Gale.
867
868 Permission is granted to make and distribute verbatim copies of this manual provided the 
869 copyright notice and this permission notice are preserved on all copies.
870
871 Permission is granted to copy and distribute modified versions of this document under the conditions 
872 for verbatim copying, provided that this copyright notice is included exactly as in the original, 
873 and that the entire resulting derived work is distributed under the terms of a permission 
874 notice identical to this one.
875
876 Permission is granted to copy and distribute translations of this document into another language, 
877 under the above conditions for modified versions.
878
879 If you are intending to incorporate this document into a published work, please contact one of
880 the maintainers, and we will make an effort to ensure that you have the most up to date 
881 information available.
882
883 There is no guarentee that this document lives up to its intended
884 purpose.  This is simply provided as a free resource.  As such,
885 the authors and maintainers of the information provided within can 
886 not make any guarentee that the information is even accurate.
887
888 </article>