GTK+ FAQ
Shawn T. Amundson, amundson@cs.umn.edu
July 31, 1997This 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+.
1. General Information
2. Widgets
1. General Information
1.1 Authors and Copyright
The authors of GTK+ are:
Peter Mattis (petm@xcf.berkeley.edu) Spencer Kimball (spencer@xcf.berkeley.edu) Josh MacDonald (jmacd@xcf.berkeley.edu)
The copyright notice on the library files is the following:
/* GTK - The GIMP Toolkit
* Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
* License along with this library; if not, write to the Free
* Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
1.2 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.
1.3 What is the + in GTK+?
Peter Mattis informed the gtk mailing list that:
"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."
1.4 What is the policy on incorporating new widgets into the gtk 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.
1.5 Does the G in GTK stand for General, Gimp, or GNU?
Peter Mattis informed the gtk mailing list that:
"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."
1.6 Why use g_print, g_malloc, g_strdup and fellow glib functions ?
Thanks to Tim Janik who wrote to gtk-list: (slightly modified)
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).
1.7 What applications have been written with GTK+?
Some applications which use GTK+ are:
1.8 Is anyone working on C++ bindings?
Yes! Elliot Lee has started gtk--, and has released a couple versions already. So far so good! You can find these bindings at ftp://ftp.redhat.com/sopwith.
1.9 Is anyone working on Guile bindings?
Yes, Peter Mattis. Here is what he said:
"Btw, guile-1.1 is on prep.ai.mit.edu if anyone didn't know. Guile is an R4RS scheme interpreter and extension library. I've already done scheme bindings for gtk using SIOD, but SIOD isn't R4RS (the scheme standard) compatible. And the new bindings will be much much better."
1.10 The gtk-list hasn't had any traffic for days, is it dead?
No, everyone's just busy coding.
1.11 Where is the documentation for GTK+?
Look in the GTK distribution's doc/ directory. In addition, if you are on the web, you cat get it by going to http://web.archive.org/web/19970807203942/http://www.cs.umn.edu/~amundson/gtk/docs/, where they are already converted to HTML format.
You can download the HTML to your home machine with your browser. There are only four files in these docs:
http://www.cs.umn.edu/~amundson/gtk/docs/gtk_toc.html http://www.cs.umn.edu/~amundson/gtk/docs/gtk.html http://www.cs.umn.edu/~amundson/gtk/docs/gdk_toc.html http://www.cs.umn.edu/~amundson/gtk/docs/gdk.html
This is the only place to get them in html that I know of. I do not have time to gzip them, but they are not so huge anyway. (I'm lazy too!)
2. Widgets
2.1 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.
2.2 How do I find out about the selection of a GtkList?
Get the selection something like this:
GList *sel;
sel = GTK_LIST(list)->selection;
This is how GList is defined (quoting glist.h):
typedef struct _GList GList;
struct _GList
{
gpointer data;
GList *next;
GList *prev;
};
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:
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.
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:
{
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);
}
}
To get known about the selection:
{
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");
}
2.3 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.
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);
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).
2.4 How do I make menus?
Sascha Ziemann wrote to the gtk-list: (slightly modified)
First you have to write a function for every menu: (the translate function returns simple strings)
/***********************************************************************
** Create the File-Menu
*/
GtkWidget* create_file_menu (GtkWidget *window)
{
GtkWidget *menu;
GtkWidget *submenu;
GtkWidget *menuitem;
GSList *group;
menu = gtk_menu_new ();
submenu = NULL;
group = NULL;
menuitem = gtk_menu_item_new_with_label(translate("file-new-label"));
gtk_menu_append (GTK_MENU (menu), menuitem);
gtk_widget_show (menuitem);
menuitem = gtk_menu_item_new_with_label(translate("file-open-label"));
gtk_menu_append (GTK_MENU (menu), menuitem);
gtk_widget_show (menuitem);
gtk_menu_line_new(GTK_MENU(menu));
menuitem = gtk_menu_item_new_with_label(translate("file-save-label"));
gtk_menu_append (GTK_MENU (menu), menuitem);
gtk_widget_show (menuitem);
menuitem = gtk_menu_item_new_with_label(translate("file-saveas-label"));
gtk_menu_append (GTK_MENU (menu), menuitem);
gtk_widget_show (menuitem);
menuitem = gtk_menu_item_new_with_label(translate("file-saveall-label"));
gtk_menu_append (GTK_MENU (menu), menuitem);
gtk_widget_show (menuitem);
gtk_menu_line_new(GTK_MENU(menu));
menuitem = gtk_menu_item_new_with_label(translate("file-export-label"));
gtk_menu_append (GTK_MENU (menu), menuitem);
gtk_widget_show (menuitem);
return menu;
}
And in your main window creation function you create a menubar in a box.
/*
** base frame
*/
window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
gtk_signal_connect (GTK_OBJECT (window), "destroy",
(GtkSignalFunc) destroy_program,
&window);
gtk_widget_set_name (window, "EDINI");
gtk_widget_set_uposition (window, 20, 20);
base_frame_box = gtk_vbox_new (FALSE, 10);
gtk_container_add (GTK_CONTAINER (window), base_frame_box);
gtk_widget_show (base_frame_box);
/*
** the menu bar
*/
menubar = gtk_menu_bar_new ();
gtk_box_pack_start (GTK_BOX (base_frame_box), menubar, FALSE, TRUE, 0);
gtk_widget_show (menubar);
menu = create_file_menu(window);
menuitem = gtk_menu_item_new_with_label(translate("file-menu-label"));
gtk_menu_item_set_submenu (GTK_MENU_ITEM (menuitem), menu);
gtk_menu_bar_append (GTK_MENU_BAR (menubar), menuitem);
gtk_widget_show (menuitem);
2.5 Is there a better way to do the menus?
Jay Painter wrote to the gtk-list: (slightly modified)
The best way to make menus is with gtk_menu_factory where you create a structure with all your menus in it, feed it to a function, and all your menus get created for you without 50 calls to gtk_menuitem_new. You can find a good example in the GZilla code. I still don't know exaclty what all the fields are in the structure, but NULL is always a good choice for those. :)
2.6 How can I define a separation line in a menu?
Just insert an empty menu item:
menuitem = gtk_menu_item_new();
gtk_menu_append(GTK_MENU(menu), menuitem);
gtk_widget_show(menuitem);
Copyright 1997