GTK+ FAQ  <author>Nathan Froyd, Tony Gale, Shawn T. Amundson. <date>February 25th 1998 <abstract> This document is intended to answer questions that are likely to be frequently asked by programmers using GTK+ or people who are just looking at using GTK+. </abstract>  <toc>   <sect>General Information  <sect1>Authors The authors of GTK+ are: <itemize> <item>Peter Mattis (petm@xcf.berkeley.edu) <item>Spencer Kimball (spencer@xcf.berkeley.edu) <item>Josh MacDonald (jmacd@xcf.berkeley.edu) </itemize> GTK+ is distributed under the GNU Library General Public License  <sect1>What is GTK+? GTK+ is a small and efficient widget set designed with the general look and feel of Motif. In reality, it looks much better than Motif. It contains common widgets and some more complex widgets such as a file selection, and color selection widgets. GTK+ provides some unique features. (At least, I know of no other widget library which provides them). For example, a button does not contain a label, it contains a child widget, which in most instances will be a label. However, the child widget can also be a pixmap, image or any combination possible the programmer desires. This flexibility is adhered to throughout the library.  <sect1>What is the + in GTK+? Peter Mattis informed the gtk mailing list that: <quote> "I originally wrote gtk which included the three libraries, libglib, libgdk and libgtk. It featured a flat widget hierarchy. That is, you couldn't derive a new widget from an existing one. And it contained a more standard callback mechanism instead of the signal mechanism now present in gtk+. The + was added to distinguish between the original version of gtk and the new version. You can think of it as being an enhancement to the original gtk that adds object oriented features." </quote>  <sect1>Does the G in GTK+ stand for General, Gimp, or GNU? Peter Mattis informed the gtk mailing list that: <quote> "I think the last time Spencer and I talked about it we decided on GTK = Gimp ToolKit. But I don't know for sure. Its definately not GNU, though." </quote>  <sect1>Where is the documentation for GTK+? In the GTK+ distribution's doc/ directory you will find the reference material for both GTK and GDK, and this FAQ. There is also a GTK+ Tutorial which can be found at <htmlurl url="http://www.levien.com/~slow/gtk/" name="http://www.levien.com/~slow/gtk/">. The Tutorial and FAQ can also be found at <htmlurl url="http://www.geocities.com/ResearchTriangle/Lab/4299/" name="http://www.geocities.com/ResearchTriangle/Lab/4299/">. In addition, you can find links to all of these documents by going to <htmlurl url="http://www.gimp.org/gtk/docs" name="http://www.gimp.org/gtk/docs">.  <sect1>Is there a mailing list (or mailing list archive) for GTK+? There are two mailing lists: <itemize> <item>A mailing list for discussion of development of GTK based applications is hosted at gtk-app-devel-list@redhat.com. To subscribe send an email message to <htmlurl url="mailto:gtk-app-devel-list-request@redhat.com" name="gtk-app-devel-list-request@redhat.com"> with subscribe in the <bf>subject</bf>. <item>A mailing list for discussion of development of GTK is hosted at gtk-list@redhat.com. To subscribe send an email message to <htmlurl url="mailto:gtk-list-request@redhat.com" name="gtk-list-request@redhat.com"> with subscribe in the <bf>subject</bf>. A searchable archive of the mailing list can be found at <htmlurl url="http://www.redhat.com/linux-info/gtk/gtk-list/index.html" name="http://www.redhat.com/linux-info/gtk/gtk-list/index.html"> </itemize>  <sect1>The gtk-list hasn't had any traffic for days, is it dead? No, everyone's just busy coding.  <sect1>How to get help with GTK+ First, make sure your question isn't answered in the documentation, this FAQ or the tutorial. Done that? You're sure you've done that, right? In that case, the best place to post questions is to the GTK+ mailing list.  <sect1>How to report bugs in GTK+ Bug reports should be sent to the GTK+ mailing list.  <sect1>What applications have been written with GTK+? Some applications which use GTK+ are: <itemize> <item>GIMP (<htmlurl url="http://www.XCF.Berkeley.EDU/~gimp/" name="http://www.XCF.Berkeley.EDU/~gimp/"> ), an image manipulation program <item>Gsumi (<htmlurl url="http://www.msc.cornell.edu/~otaylor/gsumi/gsumi.html" name="http://www.msc.cornell.edu/~otaylor/gsumi/gsumi.html">), a fun B+W doodling program with XInput support. <item>GUBI (<htmlurl url="http://www.SoftHome.net/pub/users/timj/gubi/index.htm" name="http://www.SoftHome.net/pub/users/timj/gubi/index.htm">), a user interface builder <item>Gzilla (<htmlurl url="http://www.levien.com/gzilla/" name="http://www.levien.com/gzilla/">), a web browser <item>SANE (<htmlurl url="http://www.azstarnet.com/~axplinux/sane/" name="http://www.azstarnet.com/~axplinux/sane/"> ), a universal scanner interface <item>XQF (<htmlurl url="http://www.botik.ru/~roma/quake/" name="http://www.botik.ru/~roma/quake/">), a QuakeWorld/Quake2 server browser and launcher <item>ElectricEyes (<htmlurl url="http://www.labs.redhat.com/ee.shtml" name="http://www.labs.redhat.com/ee.shtml">), an image viewer that aims to be a free replacement for xv <item>GPK - the General Proxy Kit (<htmlurl url="http://www.humanfactor.com/gpk/" name="http://www.humanfactor.com/gpk/">), an add-on library to permit thread-safe access to GTK+ <item>GCK - the General Convenience Kit (<htmlurl url="http://www.ii.uib.no/~tomb/gck.html" name="http://www.ii.uib.no/~tomb/gck.html">), miscellaneous functions intended to ease color handling, UI construction, vector operations, and math functions <item>GDK Imlib (<htmlurl url="http://www.labs.redhat.com/imlib/" name="http://www.labs.redhat.com/imlib/">), a fast image loading and manipulation library for GDK </itemize> In addition to the above, the GNOME project (<htmlurl url="http://www.gnome.org" name="http://www.gnome.org">) is using GTK+ to build a free desktop for Linux. Many more programs can be found there.  <sect>How to find, configure, install, and troubleshoot GTK+   <sect1>What do I need to run GTK+? To compile GTK+, all you need is a C compiler (gcc) and the X Window System and associated libraries on your system.  <sect1>Where can I get GTK+? The canonical site is: <verb> ftp://ftp.gimp.org/pub/gtk </verb> Of course, any mirrors of ftp.gimp.org should have the latest version, too. <sect1>How do I configure/compile GTK+? Generally, all you will need to do is issue the commands: <verb> ./configure make </verb> in the gtk+-version/ directory.  <sect1>When compiling GTK+ I get an error like: <tt/make: file `Makefile' line 456: Syntax error/ Make sure that you are using GNU make (use <tt/make -v/ to check). There are many weird and wonderful versions of make out there, and not all of them handle the automatically generated Makefiles.  <sect1>I've compiled and installed GTK+, but I can't get any programs to link with it! This problem is most often encountered when the GTK+ libraries can't be found or are the wrong version. Generally, the compiler will complain about an 'unresolved symbol'. There are two things you need to check: <itemize> <item>Make sure that the libraries can be found. You want to edit /etc/ld.so.conf to include /usr/local/lib (or whereever you installed GTK+), so it looks something like: <verb> /usr/X11R6/lib /usr/local/lib </verb> Then you need to run /sbin/ldconfig as root. <item>Make sure the linker is finding the correct set of libraries. If you have a Linux distribution that installs GTK+ (e.g. RedHat 5.0) then this older version may be used. Now (assuming you have a RedHat system), issue the command <verb> rpm -e gtk gtk-devel </verb> You may also want to remove the packages that depend on gtk (rpm will tell you which ones they are). If you don't have a RedHat Linux system, check to make sure that neither <verb>/usr/lib</verb> or <verb>/usr/local/lib</verb> contain any of the libraries libgtk, libgdk, libglib, or libgck. If they do exist, remove them (and any gtk include files, such as /usr/include/gtk and /usr/include/gdk) and reinstall gtk+. </itemize>  <sect>Development of GTK+   <sect1>When will it reach version 1.0? The file 'TODO' in the gtk+ distribution lists the things that need to be done before version 1.0 is repleased. Not including bugs, this includes: <itemize> <item>New Features <itemize> <item>gdk_expose_compress: ala-Xt, this would really help for opaque moves and such </itemize> <item>Widgets <itemize> <item>Column-list (Jay Painter) <item>Text widget (needs to be finished) <item>Entry should have a password mode (and it should show stars for user feedback) </itemize> <item>Drag-and-Drop (DND) <itemize> <item> It seems to be having problems again. The way DND data types are set in GtkWidget really needs to be fixed. This is pretty high on my priority list, and I'll get to it as soon as the column list widget is done. The correct way dnd data needs to be set is to have a additional keyed data type with GtkWidget, which is applied to the widget's window upon realize. There also needs to be a way to set dnd-data on widget windows which are not the main window (for widgets that create more than one window). -- Jay Painter <item> DnD seems to work for me, but yes, there needs to be some sort of gtk_widget layer that makes it easier... Also, adding support for drop zones might be nice. -- Elliot </itemize> </itemize>  <sect1>How can I contribute to GTK+? 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, track it down in the GTK+ source, change it, and then upload the patchfile to: <verb> ftp://ftp.gimp.org/incoming </verb> along with a README file. Make sure you follow the naming conventions or your will just be deleted! The filenames should be of this form: <verb> gtk-<username>-<date yymmdd-n>.patch.gz gtk-<username>-<date yymmdd-n>.patch.README </verb> The "n" in the date indicates a unique number (starting from 0) of patches you uploaded that day. It should be 0, unless you upload more than one patch in the same day. Example: <verb> gtk-gale-982701-0.patch.gz gtk-gale-982701-0.patch.README </verb> Once you upload anything, send the README to ftp-admin@gimp.org  <sect1>What is the policy on incorporating new widgets into the library? 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.  <sect1>Is anyone working on bindings for languages other than C? Yes. There is <itemize> <item>a C++ wrapper for GTK+ called gtk--. You can find the home page at: <verb> http://www.cs.tut.fi/~p150650/gtk/gtk--.html </verb> The FTP site is: <verb> ftp://ftp.gimp.org/pub/gtk/gtk--/ </verb> <item>Perl bindings <verb> ftp://ftp.gimp.org/pub/gtk/perl </verb> <item>Guile bindings. The home page is at: <verb> http://www.ping.de/sites/zagadka/guile-gtk/ </verb> By the way, Guile is the GNU Project's implemention of R4RS Scheme (the standard). If you like Scheme, you may want to take a look at this. <item>David Monniaux reports: <quote>I've started a gtk-O'Caml binding system. The basics of the system, including callbacks, work fine. The current development is in http://www.ens-lyon.fr/~dmonniau/arcs/ </quote> <item> Several python-gtk interfaces have been done. python-gtk is at: <verb> http://www.acs.ucalgary.cs/~nashceme/python-gtk/ </verb> If you try python-gtk and don't like it, there's also pygtk located at: <verb> ftp://ftp.gimp.org/pub/gtk/python/ </verb> <item> There's a OpenGL/Mesa widget available for GTK+. Grab it at: <verb> http://www.sakuranet.or.jp/~aozasa/shige/doc/comp/gtk/gtkGL/files-en.html </verb> </itemize>  <sect>Development with GTK+   <sect1>How do I get started? 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 <htmlurl url="http://www.levien.com/~slow/gtk/tutorial" name="<http://www.levien.com/~slow/gtk/tutorial>">, which is undergoing development. This will introduce you to writing applications using C. The Tutorial doesn't (yet) contain information on all of the widgets that are in GTK+. For example code on how to use the basics of all the GTK+ widgets you should look at the file gtk/testgtk.c (and associated source files) within the GTK+ distribution. Looking at these exmaples will give you a good grounding on what the widgets can do. <sect1>What widgets are in GTK? The GTK+ Tutorial lists the following widgets: <verb> GtkObject +-- GtkData | \-- GtkAdjustment | \-- GtkWidget +-- GtkContainer | +-- GtkBin | | +-- GtkAlignment | | +-- GtkFrame | | | *-- GtkAspectFrame | | | | | +-- GtkItem | | | +-- GtkListItem | | | +-- GtkMenuItem | | | | +-- GtkCheckMenuItem | | | | *-- GtkRadioMenuItem | | | | | | | *-- GtkTreeItem | | | | | +-- GtkViewport | | \-- GtkWindow | | +-- GtkDialog | | \-- GtkFileSelection | | | +-- GtkBox | | +-- GtkHBox | | \-- GtkVBox | | +-- GtkColorSelection | | \-- GtkCurve | | | +-- GtkButton | | +-- GtkOptionMenu | | \-- GtkToggleButton | | \-- GtkCheckButton | | \-- GtkRadioButton | | | +-- GtkList | +-- GtkMenuShell | | +-- GtkMenu | | \-- GtkMenuBar | | | +-- GtkNotebook | +-- GtkScrolledWindow | +-- GtkTable | \-- GtkTree | +-- GtkDrawingArea +-- GtkEntry +-- GtkMisc | +-- GtkArrow | +-- GtkImage | +-- GtkLabel | \-- GtkPixmap | +-- GtkPreview +-- GtkProgressBar +-- GtkRange | +-- GtkScale | | +-- GtkHScale | | \-- GtkVScale | | | \-- GtkScrollbar | +-- GtkHScrollbar | \-- GtkVScrollbar | +-- GtkRuler | +-- GtkHRuler | \-- GtkVRuler | \-- GtkSeparator +-- GtkHSeparator \-- GtkVSeparator </verb>  <sect1>How can I prevent redrawing and resizing while I change multiple widgets? Use gtk_container_disable_resize and gtk_container_enable_resize around the code where you are changing a lot of stuff. This will result in much faster speed since it will prevent resizing of the entire widget hierarchy.  <sect1>How do I catch a double click event in a list widget? Tim Janik wrote to gtk-list (slightly modified): Define a signal handler: <tscreen><verb> gint signal_handler_event(GtkWiget *widget, GdkEvenButton *event, gpointer func_data) { if (GTK_IS_LIST_ITEM(widget) && (event->type==GDK_2BUTTON_PRESS || event->type==GDK_3BUTTON_PRESS) ) { printf("I feel %s clicked on button %d\", event->type==GDK_2BUTTON_PRESS ? "double" : "triple", event->button); } return FALSE; } </verb></tscreen> And connect the handler to your object: <tscreen><verb> { /* list, list item init stuff */ gtk_signal_connect(GTK_OBJECT(list_item), "button_press_event", GTK_SIGNAL_FUNC(signal_handler_event), NULL); /* and/or */ gtk_signal_connect(GTK_OBJECT(list_item), "button_release_event", GTK_SIGNAL_FUNC(signal_handler_event), NULL); /* something else */ } </verb></tscreen>  <sect1>How do I find out about the selection of a GtkList? Get the selection something like this: <tscreen><verb> GList *sel; sel = GTK_LIST(list)->selection; </verb></tscreen> This is how GList is defined (quoting glist.h): <tscreen><verb> typedef struct _GList GList; struct _GList { gpointer data; GList *next; GList *prev; }; </verb></tscreen> A GList structure is just a simple structure for doubly linked lists. there exist several g_list_*() functions to modify a linked list in glib.h. However the GTK_LIST(MyGtkList)->selection is maintained by the gtk_list_*() functions and should not be modified. The selection_mode of the GtkList determines the selection facilities of a GtkList and therefore the contents of GTK_LIST(AnyGtkList)->selection: <verb> selection_mode GTK_LIST()->selection contents ------------------------------------------------------ GTK_SELECTION_SINGLE) selection is either NULL or contains a GList* pointer for a single selected item. GTK_SELECTION_BROWSE) selection is NULL if the list contains no widgets, otherwise it contains a GList* pointer for one GList structure. GTK_SELECTION_MULTIPLE) selection is NULL if no listitems are selected or a a GList* pointer for the first selected item. that in turn points to a GList structure for the second selected item and so on GTK_SELECTION_EXTENDED) selection is NULL. </verb> The data field of the GList structure GTK_LIST(MyGtkList)->selection points to the first GtkListItem that is selected. So if you would like to determine which listitems are selected you should go like this: Upon Initialization: <tscreen><verb> { gchar *list_items[]={ "Item0", "Item1", "foo", "last Item", }; guint nlist_items=sizeof(list_items)/sizeof(list_items[0]); GtkWidget *list_item; guint i; list=gtk_list_new(); gtk_list_set_selection_mode(GTK_LIST(list), GTK_SELECTION_MULTIPLE); gtk_container_add(GTK_CONTAINER(AnyGtkContainer), list); gtk_widget_show (list); for (i = 0; i < nlist_items; i++) { list_item=gtk_list_item_new_with_label(list_items[i]); gtk_object_set_user_data(GTK_OBJECT(list_item), (gpointer)i); gtk_container_add(GTK_CONTAINER(list), list_item); gtk_widget_show(list_item); } } </verb></tscreen> To get known about the selection: <tscreen><verb> { GList *items; items=GTK_LIST(list)->selection; printf("Selected Items: "); while (items) { if (GTK_IS_LIST_ITEM(items->data)) printf("%d ", (guint) gtk_object_get_user_data(items->data)); items=items->next; } printf("\n"); } </verb></tscreen>  <sect1>Is it possible to get some text displayed which is truncated to fit inside its allocation? GTK's behavior (no clipping) is a consequence of its attempts to conserve X resources. Label widgets (among others) don't get their own X window - they just draw their contents on their parent's window. While it might be possible to have clipping occur by setting the clip mask before drawing the text, this would probably cause a substantial performance penalty. Its possible that, in the long term, the best solution to such problems might be just to change gtk to give labels X windows. A short term workaround is to put the label widget inside another widget that does get it's own window - one possible candidate would be the viewport widget. <tscreen><verb> viewport = gtk_viewport (NULL, NULL); gtk_widget_set_usize (viewport, 50, 25); gtk_viewport_set_shadow_type (GTK_VIEWPORT(viewport), GTK_SHADOW_NONE); gtk_widget_show(viewport); label = gtk_label ("a really long label that won't fit"); gtk_container_add (GTK_CONTAINER(viewport), label); gtk_widget_show (label); </verb></tscreen> If you were doing this for a bunch of widgets, you might want to copy gtkviewport.c and strip out the adjustment and shadow functionality (perhaps you could call it GtkClipper).  <sect1>Why don't the contents of a button move when the button is pressed? Here's a patch to make it work that way... From: Peter Mattis The reason buttons don't move their child down and to the right when they are depressed is because I don't think that's what is happening visually. My view of buttons is that you are looking at them straight on. That is, the user interface lies in a plane and you're above it looking straight at it. When a button gets pressed it moves directly away from you. To be absolutely correct I guess the child should actually shrink a tiny amount. But I don't see why the child should shift down and to the left. Remember, the child is supposed to be attached to the buttons surface. Its not good for it to appear like the child is slipping on the surface of the button. On a more practical note, I did implement this at one point and determined it didn't look good and removed it.  <sect1>How can I define a separation line in a menu? See the <htmlurl url="http://www.levien.com/~slow/gtk/" name="Tutorial"> for information on how to create menus. However, to create a separation line in a menu, just insert an empty menu item: <tscreen><verb> menuitem = gtk_menu_item_new(); gtk_menu_append(GTK_MENU(menu), menuitem); gtk_widget_show(menuitem); </verb></tscreen>  <sect>About gdk   <sect1>What is gdk? gdk is basically a wrapper around the standard Xlib functions calls. If you are at all familiar with Xlib, a lot of the functions in gdk will require little or no getting used to. All functions are written to provide an easy way to access Xlib functions in an easier an slightly more intuitive manner. In addition, since gdk uses glib (see below), it will be more portable and safer to use on multiple platforms.  <sect1>How do I use color allocation? One of the nice things about GDK is that it's based on top of Xlib; this is also a problem, especially in the area of color management. If you want to use color in your program (drawing a rectangle or such, your code should look something like this: <tscreen> <verb> { GdkColor *color; int width, height; GtkWidget *widget; ... /* first, create a GC to draw on */ gc = gdk_gc_new(widget->window); /* find proper dimensions for rectangle */ gdk_window_get_size(widget->window, &width, &height); /* the color we want to use */ color = (GdkColor *)malloc(sizeof(GdkColor)); /* red, green, and blue are passed values, indicating the RGB triple * of the color we want to draw. Note that the values of the RGB components * within the GdkColor are taken from 0 to 65535, not 0 to 255. */ color->red = red * (65535/255); color->green = green * (65535/255); color->blue = blue * (65535/255); /* the pixel value indicates the index in the colormap of the color. * it is simply a combination of the RGB values we set earlier */ color->pixel = (gulong)(red*65536 + green*256 + blue); /* However, the pixel valule is only truly valid on 24-bit (TrueColor) * displays. Therefore, this call is required so that GDK and X can * give us the closest color available in the colormap */ gdk_color_alloc(gtk_widget_get_colormap(widget), color); /* set the foreground to our color */ gdk_gc_set_foreground(gc, color); /* draw the rectangle */ gdk_draw_rectangle(widget->window, gc, 1, 0, 0, width, height); ... } </verb> </tscreen>  <sect>About glib   <sect1>What is glib? glib is a library of useful functions and definitions available for use when creating GDK and GTK applications. It provides replacements for some standard libc functions, such as malloc, which are buggy on some systems. It also provides routines for handling: <itemize> <item>Doubly Linked Lists <item>Singly Linked Lists <item>Timers <item>String Handling <item>A Lexical Scanner <item>Error Functions </itemize>   <sect1>Why use g_print, g_malloc, g_strdup and fellow glib functions ? Thanks to Tim Janik who wrote to gtk-list: (slightly modified) <quote> Regarding g_malloc(), g_free() and siblings, these functions are much safer than thier libc equivalences. For example, g_free() just returns if called with NULL. Also, if USE_DMALLOC is defined, the definition for these functions changes (in glib.h) to use MALLOC(), FREE() etc... If MEM_PROFILE or MEM_CHECK are defined, there are even small statistics made counting the used block sizes (shown by g_mem_profile() / g_mem_check()). Considering the fact that glib provides an interface for memory chunks to save space if you have lots of blocks that are always the same size and to mark them ALLOC_ONLY if needed, it is just straight forward to create a small saver (debug able) wrapper around the normal malloc/free stuff as well - just like gdk covers Xlib. ;) Using g_error() and g_warning() inside of applications like the GIMP that fully rely on gtk even gives the opportunity to pop up a window showing the messages inside of a gtk window with your own handler (by using g_set_error_handler()) along the lines of gtk_print() (inside of gtkmain.c). </quote>  <sect>GTK+ FAQ Contributions, Maintainers and Copyright If you would like to make a contribution to the FAQ, send either one of us an e-mail message with the exact text you think should be included (question and answer). With your help, this document can grow and become more useful! This document is maintained by Nathan Froyd <htmlurl url="mailto:maestrox@geocities.com" name="<maestrox@geocities.com>"> and Tony Gale <htmlurl url="mailto:gale@gimp.org" name="<gale@gimp.org>">. This FAQ was created by Shawn T. Amundson <htmlurl url="mailto:amundson@gimp.org" name="<amundson@gimp.org>">who continues to provide support. The GTK+ FAQ is Copyright (C) 1997,1998 by Shawn T. Amundson, Nathan Froyd and Tony Gale. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this document under the conditions for verbatim copying, provided that this copyright notice is included exactly as in the original, and that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this document into another language, under the above conditions for modified versions. If you are intending to incorporate this document into a published work, please contact one of the maintainers, and we will make an effort to ensure that you have the most up to date information available. There is no guarentee that this document lives up to its intended purpose. This is simply provided as a free resource. As such, the authors and maintainers of the information provided within can not make any guarentee that the information is even accurate. </article>