1 <!doctype linuxdoc system>
5 <!-- Title information -->
9 <!-- NOTE: Use only one author tag, otherwise sgml2txt barfs - TRG -->
10 <author>Nathan Froyd, Tony Gale, Shawn T. Amundson.
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+.
18 <!-- Table of contents -->
21 <!-- Begin the document -->
23 <!-- ***************************************************************** -->
24 <sect>General Information
26 <!-- ----------------------------------------------------------------- -->
29 The authors of GTK+ are:
32 <item>Peter Mattis (petm@xcf.berkeley.edu)
33 <item>Spencer Kimball (spencer@xcf.berkeley.edu)
34 <item>Josh MacDonald (jmacd@xcf.berkeley.edu)
36 GTK+ is distributed under the GNU Library General Public License
38 <!-- ----------------------------------------------------------------- -->
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.
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.
54 <!-- ----------------------------------------------------------------- -->
55 <sect1>What is the + in GTK+?
57 Peter Mattis informed the gtk mailing list that:
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."
68 <!-- ----------------------------------------------------------------- -->
69 <sect1>Does the G in GTK+ stand for General, Gimp, or GNU?
71 Peter Mattis informed the gtk mailing list that:
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
78 <!-- ----------------------------------------------------------------- -->
79 <sect1>Where is the documentation for GTK+?
81 In the GTK+ distribution's doc/ directory you will find the
82 reference material for both GTK and GDK, this FAQ and the
85 In addition, you can find links to HTML versions of these documents
87 <htmlurl url="http://www.gtk.org/"
88 name="http://www.gtk.org/">.
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/">.
94 <!-- ----------------------------------------------------------------- -->
95 <sect1>Is there a mailing list (or mailing list archive) for GTK+?
97 There are two mailing lists:
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>.
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>.
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">
113 <!-- ----------------------------------------------------------------- -->
114 <sect1>The gtk-list hasn't had any traffic for days, is it dead?
116 No, everyone's just busy coding.
118 <!-- ----------------------------------------------------------------- -->
119 <sect1>How to get help with GTK+
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.
125 <!-- ----------------------------------------------------------------- -->
126 <sect1>How to report bugs in GTK+
128 Bug reports should be sent to the GTK+ mailing list.
130 <!-- ----------------------------------------------------------------- -->
131 <sect1>What applications have been written with GTK+?
133 Some applications which use GTK+ are:
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/">),
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
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
166 <!-- ----------------------------------------------------------------- -->
167 <sect1>I'm looking for an application to write in GTK+. How about an IRC client?
170 Ask on gtk-list for suggestions. There are at least four IRC
171 clients already under development
174 <item>girc. (Included with GNOME)
175 <item>Bezerk (<htmlurl url="http://www.gtk.org/~trog/"
176 name="http://www.gtk.org/~trog/">)
177 <item>gsirc. (Location?)
178 <item>Gnirc. (<htmlurl url="http://www.imaginet.fr/~dramboz/gnirc"
179 name="http://www.imaginet.fr/~dramboz/gnirc">)
183 <!-- ***************************************************************** -->
184 <sect>How to find, configure, install, and troubleshoot GTK+
186 <!-- ***************************************************************** -->
188 <!-- ----------------------------------------------------------------- -->
189 <sect1>What do I need to run GTK+?
191 To compile GTK+, all you need is a C compiler (gcc) and the X Window System
192 and associated libraries on your system.
194 <!-- ----------------------------------------------------------------- -->
195 <sect1>Where can I get GTK+?
197 The canonical site is:
199 ftp://ftp.gtk.org/pub/gtk
201 Of course, any mirrors of ftp.gtk.org should have the latest version, too.
203 <sect1>How do I configure/compile GTK+?
205 Generally, all you will need to do is issue the commands:
210 in the gtk+-version/ directory.
212 <!-- ----------------------------------------------------------------- -->
213 <sect1>When compiling GTK+ I get an error like:
214 <tt/make: file `Makefile' line 456: Syntax error/
216 Make sure that you are using GNU make (use <tt/make -v/ to check). There are
217 many weird and wonderful versions of make out there, and not all of them
218 handle the automatically generated Makefiles.
220 <!-- ----------------------------------------------------------------- -->
222 <sect1>I've compiled and installed GTK+, but I can't get any programs to link with it!
224 This problem is most often encountered when the GTK+ libraries can't be
225 found or are the wrong version. Generally, the compiler will complain about an
226 'unresolved symbol'. There are two things you need to check:
228 <item>Make sure that the libraries can be found. You want to edit
229 /etc/ld.so.conf to include the directories which contain the GTK libraries,
230 so it looks something like:
235 Then you need to run /sbin/ldconfig as root. You can find what directory
241 If your system doesn't use ld.so to find libraries (such as Solaris), then
242 you will have to use the LD_LIBRARY_PATH environment variable (or compile
243 the path into your program, which I'm not going to cover here). So, with a
244 Bourne type shell you can do (if your GTK libraries are in /usr/local/lib):
246 export LD_LIBRARY_PATH=/usr/local/lib
248 and in a csh, you can do:
250 setenv LD_LIBRARY_PATH /usr/local/lib
253 <item>Make sure the linker is finding the correct set of libraries. If you
254 have a Linux distribution that installs GTK+ (e.g. RedHat 5.0) then this
255 older version may be used. Now (assuming you have a RedHat
256 system), issue the command
260 You may also want to remove the packages that depend on gtk (rpm will tell you
261 which ones they are). If you don't have a RedHat Linux system, check to make sure
262 that neither <verb>/usr/lib</verb> or <verb>/usr/local/lib</verb> contain any of
263 the libraries libgtk, libgdk, libglib, or libgck. If they do exist, remove them
264 (and any gtk include files, such as /usr/include/gtk and /usr/include/gdk)
268 <!-- ----------------------------------------------------------------- -->
269 <sect1>When compiling programs with GTK+, I get compiler error messages about not being able to find <tt/"glibconfig.h"/.
271 <p> The header file "glibconfig.h" was moved to the directory
272 $exec_prefix/lib/glib/include/. $exec_prefix is the
273 directory that was specified by giving the --exec-prefix
274 flags to ./configure when compiling GTK+. It defaults to
275 $prefix, (specified with --prefix), which in turn defaults
278 <p> This was done because "glibconfig.h" includes architecture
279 dependent information, and the rest of the include files
280 are put in $prefix/include, which can be shared between different
283 <p> GTK+ includes a shell script, <tt/gtk-config/, that
284 makes it easy to find out the correct include paths.
285 The GTK+ tutorial includes an example of using <tt/gtk-config/
286 for simple compilation from the command line. For information
287 about more complicated configuration, see the file
288 docs/gtk-config.txt in the GTK+ distribution.
290 <p> If you are trying to compile an old program, you may
291 be able to work around the problem by configuring it
292 with a command line like:
295 CPPFLAGS="-I/usr/local/include/glib/include ./configure
299 for Bourne-compatible shells like bash, or for csh variants:
302 setenv CPPFLAGS "-I/usr/local/include/glib/include
307 (Substitute the appropriate value of $exec_prefix for /usr/local.)
309 <!-- ----------------------------------------------------------------- -->
310 <sect1>When installing The GIMP, configure reports that it can't find GTK.
312 There are several common reasons for this:
314 <item>You have an old version of GTK installed somewhere. RedHat 5.0, for
315 example, installs an older copy of GTK that will not work with the latest
316 versions of GIMP. You should remove this old copy, but note that in the case
317 of RedHat 5.0 this will break the <tt/control-panel/ applications.
319 <item><tt/gtk-config/ (or another component of GTK) isn't in your path, or
320 there is an old version on your system. Type:
324 to check for both of these. This should return a value of at least 0.99.8
325 for things to work properly with GIMP 0.99.23. If it returns a value
326 different from what you expect, then you have an old version of GTK on
329 <item>The ./configure script can't find the GTK libraries. As ./configure
330 compiles various test programs, it needs to be able to find the GTK
331 libraries. See the question above for help on this.
334 If none of the above help, then have a look in config.log, which is
335 generated by ./configure as it runs. At the bottom will be the last
336 action it took before failing. If it is a section of source code, copy
337 the source code to a file and compile it with the line just above it in
338 config.log. If the compilation is successful, try executing it.
340 <!-- ***************************************************************** -->
341 <sect>Development of GTK+
342 <!-- ***************************************************************** -->
344 <!-- ----------------------------------------------------------------- -->
345 <sect1>Whats this CVS thing that everyone keeps talking about, and how do I access it?
347 CVS is the Concurent Version System and is a very popular mean of
348 version control for software projects. It is designed to allow multiple
349 authors to be able to simultanously operate on the same source tree.
350 This source tree is centrally maintained, but each developer has a
351 local mirror of this repository that they make there changes to.
353 The GTK+ developers use a CVS repository to store the master copy of
354 the current development version of GTK+. As such, people wishing to
355 contribute patches to GTK+ should generate them against the CVS version.
356 Normal people should use the packaged releases.
358 The CVS toolset is available as RPM packages from the usual RedHat sites.
359 The latest version is available at
360 <htmlurl url="http://download.cyclic.com/pub/"
361 name="<http://download.cyclic.com/pub/>">
363 Anyone can download the latest CVS version of GTK+ by using anonymous access
364 using the following steps:
366 <item> In a bourne shell descendant (e.g. bash) type:
368 export CVSROOT=':pserver:anonymous@cvs.gimp.org:/debian/home/gnomecvs'
370 <item>Next, the first time the source tree is checked out, a cvs login
375 This will ask you for a password. There is no password for cvs.gimp.org,
376 so just enter a carriage return.
377 <item>To get the tree and place it in a subdir of your current working directory, issue the command:
382 <!-- ----------------------------------------------------------------- -->
383 <sect1>How can I contribute to GTK+?
385 It's simple. If something doesn't work like you think it should in a program,
386 check the documentation to make sure you're not missing something. If it is a
387 true bug or missing feature, track it down in the GTK+ source, change it,
388 and then generate a patch in the form of a 'context diff'. This can be done
389 using a command such as <tt/diff -ru <oldfile> <newfile>/.
390 Then upload the patchfile to:
392 ftp://ftp.gtk.org/incoming
394 along with a README file. Make sure you follow the naming conventions or your
395 patch will just be deleted! The filenames should be of this form:
397 gtk-<username>-<date yymmdd-n>.patch.gz
398 gtk-<username>-<date yymmdd-n>.patch.README
400 The "n" in the date indicates a unique number (starting from 0)
401 of patches you uploaded that day. It should be 0, unless you
402 upload more than one patch in the same day.
406 gtk-gale-982701-0.patch.gz
407 gtk-gale-982701-0.patch.README
409 Once you upload <em>anything</em>, send the README to ftp-admin@gtk.org
411 <!-- ----------------------------------------------------------------- -->
412 <sect1>How do I know if my patch got applied, and if not, why not?
414 Uploaded patches will be moved to <tt>ftp://ftp.gtk.org/pub/gtk/patches</tt>
415 where one of the GTK+ development team will pick them up. If applied, they
416 will be moved to <tt>/pub/gtk/patches/old</tt>.
418 Patches that aren't applied, for whatever reason, are moved to
419 <tt>/pub/gtk/patches/unapplied</tt> or <tt>/pub/gtk/patches/outdated</tt>.
420 At this point you can ask on the <tt/gtk-list/ mailing list why your patch
421 wasn't applied. There are many possible reasons why patches may not be
422 applied, ranging from it doesn't apply cleanly, to it isn't right. Don't
423 be put off if your patch didn't make it first time round.
425 <!-- ----------------------------------------------------------------- -->
426 <sect1>What is the policy on incorporating new widgets into the library?
428 This is up to the authors, so you will have to ask them once you
429 are done with your widget. As a general guideline, widgets that are
430 generally useful, work, and are not a disgrace to the widget set will
433 <!-- ----------------------------------------------------------------- -->
434 <sect1>Is anyone working on bindings for languages other than C?
438 <item>a C++ wrapper for GTK+ called gtk--. You can find the home page at:
440 http://www.cs.tut.fi/~p150650/gtk/gtk--.html
444 ftp://ftp.gtk.org/pub/gtk/gtk--/
448 <item>There are two Objective-c bindings currently in development:
452 <item>The <htmlurl url="http://www.gnome.org/" name="GNOME project's"> package
453 of choice is obgtk. Objgtk is based on the Object class and is maintained by
454 <htmlurl url="mailto:sopwith@cuc.edu" name="Elliot Lee">. Apparently, objgtk
455 is being accepted as the `standard' Objective-C binding for GTK+.
457 <item>If you are more inclined towards the
458 <htmlurl url="http://www.gnustep.org/" name="GNUstep project">,
459 you may want to check out GTKKit by
460 <htmlurl url="mailto:helge@mdlink.de" name="Helge Heß">.
461 The intention is to setup a GTK+ binding using the FoundationKit.
462 GTKKit includes nicities like writing a XML-type template file to
463 construct a GTK+ interface.
469 ftp://ftp.gtk.org/pub/gtk/perl
472 <item>Guile bindings. The home page is at:
474 http://www.ping.de/sites/zagadka/guile-gtk/
476 By the way, Guile is the GNU Project's implemention of R4RS Scheme (the
477 standard). If you like Scheme, you may want to take a look at this.
480 <item>David Monniaux reports:
481 <quote>I've started a gtk-O'Caml binding system.
482 The basics of the system, including callbacks, work fine.
484 The current development is in
485 http://www.ens-lyon.fr/~dmonniau/arcs/
489 Several python-gtk interfaces have been done. python-gtk is at:
491 http://www.acs.ucalgary.cs/~nashceme/python-gtk/
493 If you try python-gtk and don't like it, there's also pygtk located at:
495 ftp://ftp.gtk.org/pub/gtk/python/
499 There's a OpenGL/Mesa widget available for GTK+. Grab it at:
501 http://www.sakuranet.or.jp/~aozasa/shige/doc/comp/gtk/gtkGL/files-en.html
506 <!-- ***************************************************************** -->
507 <sect>Development with GTK+
508 <!-- ***************************************************************** -->
509 <!-- ----------------------------------------------------------------- -->
510 <sect1>How do I get started?
512 So, after you have installed GTK+ there are a couple of things that can
513 ease you into developing applications with it. There is the
514 GTK+ Tutorial <htmlurl url="http://www.gtk.org/tutorial/"
515 name="<http://www.gtk.org/tutorial/>">, which is undergoing
516 development. This will introduce you to writing applications using C.
518 The Tutorial doesn't (yet) contain information on all of the widgets
519 that are in GTK+. For example code on how to use the basics of all the
520 GTK+ widgets you should look at the file gtk/testgtk.c (and associated
521 source files) within the GTK+ distribution. Looking at these exmaples will
522 give you a good grounding on what the widgets can do.
524 <sect1>What widgets are in GTK?
526 The GTK+ Tutorial lists the following widgets:
538 | | | `GtkAspectFrame
543 | | | | `GtkCheckMenuItem
544 | | | | `GtkRadioMenuItem
548 | | +GtkColorSelectionDialog
550 | | | `GtkInputDialog
551 | | `GtkFileSelection
560 | | +GtkColorSelection
611 <!-- ----------------------------------------------------------------- -->
612 <sect1>How can I prevent redrawing and resizing while I change multiple widgets?
614 Use gtk_container_disable_resize and gtk_container_enable_resize around the
615 code where you are changing a lot of stuff. This will result in much faster
616 speed since it will prevent resizing of the entire widget hierarchy.
618 <!-- ----------------------------------------------------------------- -->
619 <sect1>How do I catch a double click event in a list widget?
621 Tim Janik wrote to gtk-list (slightly modified):
623 Define a signal handler:
627 signal_handler_event(GtkWiget *widget, GdkEvenButton *event, gpointer func_data)
629 if (GTK_IS_LIST_ITEM(widget) &&
630 (event->type==GDK_2BUTTON_PRESS ||
631 event->type==GDK_3BUTTON_PRESS) ) {
632 printf("I feel %s clicked on button %d\",
633 event->type==GDK_2BUTTON_PRESS ? "double" : "triple",
641 And connect the handler to your object:
645 /* list, list item init stuff */
647 gtk_signal_connect(GTK_OBJECT(list_item),
648 "button_press_event",
649 GTK_SIGNAL_FUNC(signal_handler_event),
654 gtk_signal_connect(GTK_OBJECT(list_item),
655 "button_release_event",
656 GTK_SIGNAL_FUNC(signal_handler_event),
663 <!-- ----------------------------------------------------------------- -->
664 <sect1>How do I find out about the selection of a GtkList?
667 Get the selection something like this:
670 sel = GTK_LIST(list)->selection;
673 This is how GList is defined (quoting glist.h):
675 typedef struct _GList GList;
685 A GList structure is just a simple structure for doubly linked lists.
686 there exist several g_list_*() functions to modify a linked list in
687 glib.h. However the GTK_LIST(MyGtkList)->selection is maintained
688 by the gtk_list_*() functions and should not be modified.
690 The selection_mode of the GtkList determines the selection
691 facilities of a GtkList and therefore the contents
692 of GTK_LIST(AnyGtkList)->selection:
695 selection_mode GTK_LIST()->selection contents
696 ------------------------------------------------------
698 GTK_SELECTION_SINGLE) selection is either NULL
699 or contains a GList* pointer
700 for a single selected item.
702 GTK_SELECTION_BROWSE) selection is NULL if the list
703 contains no widgets, otherwise
704 it contains a GList* pointer
705 for one GList structure.
706 GTK_SELECTION_MULTIPLE) selection is NULL if no listitems
707 are selected or a a GList* pointer
708 for the first selected item. that
709 in turn points to a GList structure
710 for the second selected item and so
713 GTK_SELECTION_EXTENDED) selection is NULL.
716 The data field of the GList structure GTK_LIST(MyGtkList)->selection points
717 to the first GtkListItem that is selected. So if you would like to determine
718 which listitems are selected you should go like this:
723 gchar *list_items[]={
729 guint nlist_items=sizeof(list_items)/sizeof(list_items[0]);
730 GtkWidget *list_item;
734 gtk_list_set_selection_mode(GTK_LIST(list), GTK_SELECTION_MULTIPLE);
735 gtk_container_add(GTK_CONTAINER(AnyGtkContainer), list);
736 gtk_widget_show (list);
738 for (i = 0; i < nlist_items; i++)
740 list_item=gtk_list_item_new_with_label(list_items[i]);
741 gtk_object_set_user_data(GTK_OBJECT(list_item), (gpointer)i);
742 gtk_container_add(GTK_CONTAINER(list), list_item);
743 gtk_widget_show(list_item);
748 To get known about the selection:
753 items=GTK_LIST(list)->selection;
755 printf("Selected Items: ");
757 if (GTK_IS_LIST_ITEM(items->data))
758 printf("%d ", (guint)
759 gtk_object_get_user_data(items->data));
765 <!-- ----------------------------------------------------------------- -->
766 <sect1>Is it possible to get some text displayed which is truncated to fit inside its allocation?
768 GTK's behavior (no clipping) is a consequence of its attempts to
769 conserve X resources. Label widgets (among others) don't get their own
770 X window - they just draw their contents on their parent's window.
771 While it might be possible to have clipping occur by setting the clip
772 mask before drawing the text, this would probably cause a substantial
775 Its possible that, in the long term, the best solution to such
776 problems might be just to change gtk to give labels X windows.
777 A short term workaround is to put the label widget inside another
778 widget that does get it's own window - one possible candidate would
779 be the viewport widget.
782 viewport = gtk_viewport (NULL, NULL);
783 gtk_widget_set_usize (viewport, 50, 25);
784 gtk_viewport_set_shadow_type (GTK_VIEWPORT(viewport), GTK_SHADOW_NONE);
785 gtk_widget_show(viewport);
787 label = gtk_label ("a really long label that won't fit");
788 gtk_container_add (GTK_CONTAINER(viewport), label);
789 gtk_widget_show (label);
792 If you were doing this for a bunch of widgets, you might want to
793 copy gtkviewport.c and strip out the adjustment and shadow
794 functionality (perhaps you could call it GtkClipper).
796 <!-- ----------------------------------------------------------------- -->
797 <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...
801 The reason buttons don't move their child down and to the right when
802 they are depressed is because I don't think that's what is happening
803 visually. My view of buttons is that you are looking at them straight
804 on. That is, the user interface lies in a plane and you're above it
805 looking straight at it. When a button gets pressed it moves directly
806 away from you. To be absolutely correct I guess the child should
807 actually shrink a tiny amount. But I don't see why the child should
808 shift down and to the left. Remember, the child is supposed to be
809 attached to the buttons surface. Its not good for it to appear like
810 the child is slipping on the surface of the button.
812 On a more practical note, I did implement this at one point and
813 determined it didn't look good and removed it.
815 <!-- ----------------------------------------------------------------- -->
816 <sect1>How can I define a separation line in a menu?
818 See the <htmlurl url="http://www.gtk.org/tutorial/"
819 name="Tutorial"> for information on how to create menus.
820 However, to create a separation line in a menu, just insert an
824 menuitem = gtk_menu_item_new();
825 gtk_menu_append(GTK_MENU(menu), menuitem);
826 gtk_widget_show(menuitem);
829 <!-- ----------------------------------------------------------------- -->
830 <sect1>How can I right justify a menu, such as Help, when using the MenuFactory?
832 Use something like the following:
835 menu_path = gtk_menu_factory_find (factory, "<MyApp>/Help");
836 gtk_menu_item_right_justify(menu_path->widget);
838 <!-- ----------------------------------------------------------------- -->
839 <sect1>How do I make my window modal? / How do I make a single window active?
841 After you create your window, do gtk_grab_add(my_window). And after
842 closing the window do gtk_grab_remove(my_window).
844 <!-- ----------------------------------------------------------------- -->
845 <sect1>Why doesn't my widget (e.g. progressbar) update?
848 You are probably doing all the changes within a function
849 without returning control to gtk_main. Most drawing updates are only
850 placed on a queue, which is processed within gtk_main. You can
851 force the drawing queue to be processed using something like:
854 while (gtk_events_pending())
855 gtk_main_iteration();
858 inside you're function that changes the widget.
860 What the above snippet does is run all pending events and high priority
861 idle functions, then return immediately (the drawing is done in a
862 high priority idle function).
864 <!-- ***************************************************************** -->
866 <!-- ***************************************************************** -->
868 <!-- ----------------------------------------------------------------- -->
871 gdk is basically a wrapper around the standard Xlib function calls. If you are
872 at all familiar with Xlib, a lot of the functions in gdk will require little
873 or no getting used to. All functions are written to provide an easy way
874 to access Xlib functions in an easier an slightly more intuitive manner.
875 In addition, since gdk uses glib (see below), it will be more portable
876 and safer to use on multiple platforms.
878 <!-- Examples, anybody? I've been mulling some over. NF -->
880 <sect1>How do I use color allocation?
882 One of the nice things about GDK is that it's based on top of Xlib; this is
883 also a problem, especially in the area of color management. If you want
884 to use color in your program (drawing a rectangle or such, your code
885 should look something like this:
896 /* first, create a GC to draw on */
897 gc = gdk_gc_new(widget->window);
899 /* find proper dimensions for rectangle */
900 gdk_window_get_size(widget->window, &width, &height);
902 /* the color we want to use */
903 color = (GdkColor *)malloc(sizeof(GdkColor));
905 /* red, green, and blue are passed values, indicating the RGB triple
906 * of the color we want to draw. Note that the values of the RGB components
907 * within the GdkColor are taken from 0 to 65535, not 0 to 255.
909 color->red = red * (65535/255);
910 color->green = green * (65535/255);
911 color->blue = blue * (65535/255);
913 /* the pixel value indicates the index in the colormap of the color.
914 * it is simply a combination of the RGB values we set earlier
916 color->pixel = (gulong)(red*65536 + green*256 + blue);
918 /* However, the pixel valule is only truly valid on 24-bit (TrueColor)
919 * displays. Therefore, this call is required so that GDK and X can
920 * give us the closest color available in the colormap
922 gdk_color_alloc(gtk_widget_get_colormap(widget), color);
924 /* set the foreground to our color */
925 gdk_gc_set_foreground(gc, color);
927 /* draw the rectangle */
928 gdk_draw_rectangle(widget->window, gc, 1, 0, 0, width, height);
935 <!-- ***************************************************************** -->
937 <!-- ***************************************************************** -->
939 <!-- ----------------------------------------------------------------- -->
942 glib is a library of useful functions and definitions available for use
943 when creating GDK and GTK applications. It provides replacements for some
944 standard libc functions, such as malloc, which are buggy on some systems.
946 It also provides routines for handling:
948 <item>Doubly Linked Lists
949 <item>Singly Linked Lists
951 <item>String Handling
952 <item>A Lexical Scanner
953 <item>Error Functions
956 <!-- Some Examples might be useful here! NF -->
958 <!-- ----------------------------------------------------------------- -->
959 <sect1>Why use g_print, g_malloc, g_strdup and fellow glib functions ?
961 Thanks to Tim Janik who wrote to gtk-list: (slightly modified)
963 Regarding g_malloc(), g_free() and siblings, these functions are much safer
964 than thier libc equivalences. For example, g_free() just returns if called
965 with NULL. Also, if USE_DMALLOC is defined, the definition for these
966 functions changes (in glib.h) to use MALLOC(), FREE() etc... If MEM_PROFILE
967 or MEM_CHECK are defined, there are even small statistics made counting
968 the used block sizes (shown by g_mem_profile() / g_mem_check()).
970 Considering the fact that glib provides an interface for memory chunks
971 to save space if you have lots of blocks that are always the same size
972 and to mark them ALLOC_ONLY if needed, it is just straight forward to
973 create a small saver (debug able) wrapper around the normal malloc/free
974 stuff as well - just like gdk covers Xlib. ;)
976 Using g_error() and g_warning() inside of applications like the GIMP
977 that fully rely on gtk even gives the opportunity to pop up a window
978 showing the messages inside of a gtk window with your own handler
979 (by using g_set_error_handler()) along the lines of gtk_print()
980 (inside of gtkmain.c).
983 <!-- ***************************************************************** -->
984 <sect>GTK+ FAQ Contributions, Maintainers and Copyright
986 If you would like to make a contribution to the FAQ, send either one of us
987 an e-mail message with the exact text you think should be included (question and
988 answer). With your help, this document can grow and become more useful!
990 This document is maintained by Nathan Froyd
991 <htmlurl url="mailto:maestrox@geocities.com" name="<maestrox@geocities.com>">
992 and Tony Gale <htmlurl url="mailto:gale@gimp.org" name="<gale@gimp.org>">.
993 This FAQ was created by Shawn T. Amundson <htmlurl url="mailto:amundson@gimp.org"
994 name="<amundson@gimp.org>">who continues to provide support.
996 The GTK+ FAQ is Copyright (C) 1997,1998 by Shawn T. Amundson, Nathan Froyd and Tony Gale.
998 Permission is granted to make and distribute verbatim copies of this manual provided the
999 copyright notice and this permission notice are preserved on all copies.
1001 Permission is granted to copy and distribute modified versions of this document under the conditions
1002 for verbatim copying, provided that this copyright notice is included exactly as in the original,
1003 and that the entire resulting derived work is distributed under the terms of a permission
1004 notice identical to this one.
1006 Permission is granted to copy and distribute translations of this document into another language,
1007 under the above conditions for modified versions.
1009 If you are intending to incorporate this document into a published work, please contact one of
1010 the maintainers, and we will make an effort to ensure that you have the most up to date
1011 information available.
1013 There is no guarentee that this document lives up to its intended
1014 purpose. This is simply provided as a free resource. As such,
1015 the authors and maintainers of the information provided within can
1016 not make any guarentee that the information is even accurate.