1 <!doctype linuxdoc system>
5 <!-- Title information -->
8 <author>Shawn T. Amundson, <tt/amundson@cs.umn.edu/
11 This document is intended to answer questions that are likely to be
12 frequently asked by programmers using GTK+ or people who are just
13 looking at using GTK+.
16 <!-- Table of contents -->
19 <!-- Begin the document -->
21 <!-- ***************************************************************** -->
22 <sect>General Information
24 <!-- ----------------------------------------------------------------- -->
25 <sect1>Authors and Copyright
27 The authors of GTK+ are:
30 Peter Mattis (petm@xcf.berkeley.edu)
31 Spencer Kimball (spencer@xcf.berkeley.edu)
32 Josh MacDonald (jmacd@xcf.berkeley.edu)
35 The copyright notice on the library files is the following:
38 /* GTK - The GIMP Toolkit
39 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
41 * This library is free software; you can redistribute it and/or
42 * modify it under the terms of the GNU Library General Public
43 * License as published by the Free Software Foundation; either
44 * version 2 of the License, or (at your option) any later version.
46 * This library is distributed in the hope that it will be useful,
47 * but WITHOUT ANY WARRANTY; without even the implied warranty of
48 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
49 * Library General Public License for more details.
51 * You should have received a copy of the GNU Library General Public
52 * License along with this library; if not, write to the Free
53 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
57 <!-- ----------------------------------------------------------------- -->
60 GTK is a small and efficient widget set designed with the general look
61 and feel of Motif. In reality, it looks much better than Motif. It
62 contains common widgets and some more complex widgets such as a file
63 selection, and color selection widgets.
65 <!-- ----------------------------------------------------------------- -->
66 <sect1>What is the + in GTK+?
68 Peter Mattis informed the gtk mailing list that:
70 "I originally wrote gtk which included the three libraries, libglib,
71 libgdk and libgtk. It featured a flat widget hierarchy. That is, you
72 couldn't derive a new widget from an existing one. And it contained
73 a more standard callback mechanism instead of the signal mechanism now
74 present in gtk+. The + was added to distinguish between the original
75 version of gtk and the new version. You can think of it as being an
76 enhancement to the original gtk that adds object oriented features."
79 <!-- ----------------------------------------------------------------- -->
80 <sect1>What is the policy on incorporating new widgets into the gtk library?
82 This is up to the authors, so you will have to ask them once you
83 are done with your widget. As a general guideline, widgets that are
84 generally useful, work, and are not a disgrace to the widget set will
87 <!-- ----------------------------------------------------------------- -->
88 <sect1>Does the G in GTK stand for General, Gimp, or GNU?
90 Peter Mattis informed the gtk mailing list that:
92 "I think the last time Spencer and I talked about it we decided on
93 GTK = Gimp ToolKit. But I don't know for sure. Its definately not
96 <!-- ----------------------------------------------------------------- -->
97 <sect1>Why use g_print, g_malloc, g_strdup and fellow glib functions ?
99 Thanks to Tim Janik who wrote to gtk-list: (slightly modified)
101 Regarding g_malloc(), g_free() and siblings, these functions are much safer
102 than thier libc equivalences. For example, g_free() just returns if called
103 with NULL. Also, if USE_DMALLOC is defined, the definition for these
104 functions changes (in glib.h) to use MALLOC(), FREE() etc... If MEM_PROFILE
105 or MEM_CHECK are defined, there are even small statistics made counting
106 the used block sizes (shown by g_mem_profile() / g_mem_check()).
108 Considering the fact that glib provides an interface for memory chunks
109 to save space if you have lots of blocks that are always the same size
110 and to mark them ALLOC_ONLY if needed, it is just straight forward to
111 create a small saver (debug able) wrapper around the normal malloc/free
112 stuff as well - just like gdk covers Xlib. ;)
114 Using g_error() and g_warning() inside of applications like the GIMP
115 that fully rely on gtk even gives the opportunity to pop up a window
116 showing the messages inside of a gtk window with your own handler
117 (by using g_set_error_handler()) along the lines of gtk_print()
118 (inside of gtkmain.c).
121 <!-- ----------------------------------------------------------------- -->
122 <sect1>What applications have been written with GTK+?
124 Some applications which use GTK+ are:
126 <item>GIMP (<url url="http://www.XCF.Berkeley.EDU/~gimp/"> ),
127 an image manipulation program
128 <item>Gsumi (<url url="http://student-www.uchicago.edu/users/otaylor/gsumi/gsumi.html">),
130 <item>GUBI (<url url="http://www.SoftHome.net/pub/users/timj/gubi/index.htm"> ),
131 a user interface builder
132 <item>Gzilla (<url url="http://www.levien.com/gzilla/"> ),
134 <item>SANE (<url url="http://www.azstarnet.com/~axplinux/sane/"> ),
135 a universal scanner interface
138 <!-- ----------------------------------------------------------------- -->
139 <sect1>Is anyone working on C++ bindings?
141 Yes! Elliot Lee has started gtk--, and has released a couple versions
142 already. So far so good! You can find these bindings at
143 <url url="ftp://ftp.redhat.com/sopwith">.
145 <!-- ----------------------------------------------------------------- -->
146 <sect1>Is anyone working on Guile bindings?
148 Yes, Peter Mattis. Here is what he said:
151 "Btw, guile-1.1 is on prep.ai.mit.edu if anyone didn't know. Guile is
152 an R4RS scheme interpreter and extension library. I've
153 already done scheme bindings for gtk using SIOD, but SIOD isn't R4RS
154 (the scheme standard) compatible. And the new bindings will be much
159 <!-- ----------------------------------------------------------------- -->
160 <sect1>The gtk-list hasn't had any traffic for days, is it dead?
162 No, everyone's just busy coding.
164 <!-- ----------------------------------------------------------------- -->
165 <sect1>Where is the documentation for GTK+?
167 Look in the GTK distribution's doc/ directory. In addition, if you
168 are on the web, you cat get it by going to
169 <url url="http://www.cs.umn.edu/~amundson/gtk/docs/">, where they
170 are already converted to HTML format.
172 You can download the HTML to your home machine with your browser. There
173 are only four files in these docs:
175 http://www.cs.umn.edu/~amundson/gtk/docs/gtk_toc.html
176 http://www.cs.umn.edu/~amundson/gtk/docs/gtk.html
177 http://www.cs.umn.edu/~amundson/gtk/docs/gdk_toc.html
178 http://www.cs.umn.edu/~amundson/gtk/docs/gdk.html
181 This is the only place to get them in html that I know of. I do not have
182 time to gzip them, but they are not so huge anyway. (I'm lazy too!)
184 <!-- ***************************************************************** -->
187 <!-- ----------------------------------------------------------------- -->
188 <sect1>How can I prevent redrawing and resizing while I change multiple widgets?
190 Use gtk_container_disable_resize and gtk_container_enable_resize around the
191 code where you are changing a lot of stuff. This will result in much faster
192 speed since it will prevent resizing of the entire widget hierarchy.
194 <!-- ----------------------------------------------------------------- -->
195 <sect1>How do I find out about the selection of a GtkList?
198 Get the selection something like this:
201 sel = GTK_LIST(list)->selection;
204 This is how GList is defined (quoting glist.h):
206 typedef struct _GList GList;
216 A GList structure is just a simple structure for doubly linked lists.
217 there exist several g_list_*() functions to modify a linked list in
218 glib.h. However the GTK_LIST(MyGtkList)->selection is maintained
219 by the gtk_list_*() functions and should not be modified.
221 The selection_mode of the GtkList determines the selection
222 facilities of a GtkList and therefore the contents
223 of GTK_LIST(AnyGtkList)->selection:
226 selection_mode GTK_LIST()->selection contents
227 ------------------------------------------------------
229 GTK_SELECTION_SINGLE) selection is either NULL
230 or contains a GList* pointer
231 for a single selected item.
233 GTK_SELECTION_BROWSE) selection is NULL if the list
234 contains no widgets, otherwise
235 it contains a GList* pointer
236 for one GList structure.
237 GTK_SELECTION_MULTIPLE) selection is NULL if no listitems
238 are selected or a a GList* pointer
239 for the first selected item. that
240 in turn points to a GList structure
241 for the second selected item and so
244 GTK_SELECTION_EXTENDED) selection is NULL.
247 The data field of the GList structure GTK_LIST(MyGtkList)->selection points
248 to the first GtkListItem that is selected. So if you would like to determine
249 which listitems are selected you should go like this:
254 gchar *list_items[]={
260 guint nlist_items=sizeof(list_items)/sizeof(list_items[0]);
261 GtkWidget *list_item;
265 gtk_list_set_selection_mode(GTK_LIST(list), GTK_SELECTION_MULTIPLE);
266 gtk_container_add(GTK_CONTAINER(AnyGtkContainer), list);
267 gtk_widget_show (list);
269 for (i = 0; i < nlist_items; i++)
271 list_item=gtk_list_item_new_with_label(list_items[i]);
272 gtk_object_set_user_data(GTK_OBJECT(list_item), (gpointer)i);
273 gtk_container_add(GTK_CONTAINER(list), list_item);
274 gtk_widget_show(list_item);
279 To get known about the selection:
284 items=GTK_LIST(list)->selection;
286 printf("Selected Items: ");
288 if (GTK_IS_LIST_ITEM(items->data))
289 printf("%d ", (guint)
290 gtk_object_get_user_data(items->data));
296 <!-- ----------------------------------------------------------------- -->
297 <sect1>Is it possible to get some text displayed which is truncated to fit inside its allocation?
299 GTK's behavior (no clipping) is a consequence of its attempts to
300 conserve X resources. Label widgets (among others) don't get their own
301 X window - they just draw their contents on their parent's window.
302 While it might be possible to have clipping occur by setting the clip
303 mask before drawing the text, this would probably cause a substantial
306 Its possible that, in the long term, the best solution to such
307 problems might be just to change gtk to give labels X windows.
308 A short term workaround is to put the label widget inside another
309 widget that does get it's own window - one possible candidate would
310 be the viewport widget.
313 viewport = gtk_viewport (NULL, NULL);
314 gtk_widget_set_usize (viewport, 50, 25);
315 gtk_viewport_set_shadow_type (GTK_VIEWPORT(viewport), GTK_SHADOW_NONE);
316 gtk_widget_show(viewport);
318 label = gtk_label ("a really long label that won't fit");
319 gtk_container_add (GTK_CONTAINER(viewport), label);
320 gtk_widget_show (label);
323 If you were doing this for a bunch of widgets, you might want to
324 copy gtkviewport.c and strip out the adjustment and shadow
325 functionality (perhaps you could call it GtkClipper).
327 <!-- ----------------------------------------------------------------- -->
328 <sect1>How do I make menus?
330 Sascha Ziemann wrote to the gtk-list: (slightly modified)
332 First you have to write a function for every menu: (the translate
333 function returns simple strings)
336 /***********************************************************************
337 ** Create the File-Menu
339 GtkWidget* create_file_menu (GtkWidget *window)
346 menu = gtk_menu_new ();
350 menuitem = gtk_menu_item_new_with_label(translate("file-new-label"));
351 gtk_menu_append (GTK_MENU (menu), menuitem);
352 gtk_widget_show (menuitem);
354 menuitem = gtk_menu_item_new_with_label(translate("file-open-label"));
355 gtk_menu_append (GTK_MENU (menu), menuitem);
356 gtk_widget_show (menuitem);
358 gtk_menu_line_new(GTK_MENU(menu));
360 menuitem = gtk_menu_item_new_with_label(translate("file-save-label"));
361 gtk_menu_append (GTK_MENU (menu), menuitem);
362 gtk_widget_show (menuitem);
364 menuitem = gtk_menu_item_new_with_label(translate("file-saveas-label"));
365 gtk_menu_append (GTK_MENU (menu), menuitem);
366 gtk_widget_show (menuitem);
368 menuitem = gtk_menu_item_new_with_label(translate("file-saveall-label"));
369 gtk_menu_append (GTK_MENU (menu), menuitem);
370 gtk_widget_show (menuitem);
372 gtk_menu_line_new(GTK_MENU(menu));
374 menuitem = gtk_menu_item_new_with_label(translate("file-export-label"));
375 gtk_menu_append (GTK_MENU (menu), menuitem);
376 gtk_widget_show (menuitem);
382 And in your main window creation function you create a menubar in a box.
388 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
389 gtk_signal_connect (GTK_OBJECT (window), "destroy",
390 (GtkSignalFunc) destroy_program,
393 gtk_widget_set_name (window, "EDINI");
394 gtk_widget_set_uposition (window, 20, 20);
395 base_frame_box = gtk_vbox_new (FALSE, 10);
396 gtk_container_add (GTK_CONTAINER (window), base_frame_box);
397 gtk_widget_show (base_frame_box);
402 menubar = gtk_menu_bar_new ();
403 gtk_box_pack_start (GTK_BOX (base_frame_box), menubar, FALSE, TRUE, 0);
404 gtk_widget_show (menubar);
406 menu = create_file_menu(window);
408 menuitem = gtk_menu_item_new_with_label(translate("file-menu-label"));
409 gtk_menu_item_set_submenu (GTK_MENU_ITEM (menuitem), menu);
410 gtk_menu_bar_append (GTK_MENU_BAR (menubar), menuitem);
411 gtk_widget_show (menuitem);
415 <!-- ----------------------------------------------------------------- -->
416 <sect1>Is there a better way to do the menus?
418 Jay Painter wrote to the gtk-list: (slightly modified)
420 The best way to make menus is with gtk_menu_factory where you create a
421 structure with all your menus in it, feed it to a function, and all your
422 menus get created for you without 50 calls to gtk_menuitem_new. You can
423 find a good example in the GZilla code. I still don't know exaclty what
424 all the fields are in the structure, but NULL is always a good choice for
428 <!-- ----------------------------------------------------------------- -->
429 <sect1>How can I define a separation line in a menu?
431 Just insert an empty menu item:
434 menuitem = gtk_menu_item_new();
435 gtk_menu_append(GTK_MENU(menu), menuitem);
436 gtk_widget_show(menuitem);
440 <!-- ***************************************************************** -->
441 <sect>Contributions and Maintainer
443 If you would like to make a contribution to the FAQ, send me an e-mail
444 message with the exact text you think should be included (question and
445 answer). With your help, this document can grow and become more useful!
447 This document is maintained by Shawn T. Amundson <
448 amundson@cs.umn.edu>
451 There is no guarentee that this document lives up to its intended
452 purpose. This is simply provided as a free resource. As such,
453 the authors and maintainer of the information provided within can
454 not make any guarentee that the information is even accurate.