gtk2/docs/gtkfaq.sgml

<!doctype linuxdoc system>

<article>

<!-- Title information -->

<title>GTK+ FAQ
<author>Nathan Froyd, <tt/maestrox@geocities.com/&gt;,
Tony Gale, &lt;<tt/trogsta@geocities.com/&gt;, 
Shawn T. Amundson, <tt/amundson@gimp.org/
<date>January 27th 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>

<!-- Table of contents -->
<toc>

<!-- Begin the document -->

<!-- ***************************************************************** -->
<sect>General Information

<!-- ----------------------------------------------------------------- -->
<sect1>Authors
<p>
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+?
<p>
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+?
<P>
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?
<p>
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+?
<p>
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/">

In addition, if you are
on the web, you can browse all of the above by going to 
<htmlurl url="http://www.gimp.org/gtk/docs" 
name="http://www.gimp.org/gtk/docs">, where they
are already converted to HTML format.

<!-- ----------------------------------------------------------------- -->
<sect1>Is there a mailing list (or mailing list archive) for GTK+?
<p>
A mailing list is located 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 <em>subscribe</em> 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">

<!-- ----------------------------------------------------------------- -->
<sect1>The gtk-list hasn't had any traffic for days, is it dead?
<p>
No, everyone's just busy coding.

<!-- ----------------------------------------------------------------- -->
<sect1>How to get help with GTK+
<p>
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+
<p>
Bug reports should be sent to the GTK+ mailing list.

<!-- ----------------------------------------------------------------- -->
<sect1>What applications have been written with GTK+?
<p>
Some applications which use GTK+ are:
<itemize>
<item>GIMP (<url url="http://www.XCF.Berkeley.EDU/~gimp/"> ), 
      an image manipulation program
<item>Gsumi (<url url="http://student-www.uchicago.edu/users/otaylor/gsumi/gsumi.html">),
      a port of xink
<item>GUBI (<url url="http://www.SoftHome.net/pub/users/timj/gubi/index.htm"> ),
      a user interface builder
<item>Gzilla (<url url="http://www.levien.com/gzilla/"> ),
      a web browser
<item>SANE (<url url="http://www.azstarnet.com/~axplinux/sane/"> ),
      a universal scanner interface
</itemize>

<!-- ***************************************************************** -->
<sect>How to find, configure, install, and troubleshoot GTK+

<!-- ***************************************************************** -->
<sect1>What do I need to run GTK+?
<p>
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+?
<p>
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+?
<p>
Generally, all you will need to do is issue the commands:
<verb>
./configure
make
</verb>
in the gtk+-version/ directory.

<sect1>I've compiled and installed GTK+, but I can't get any programs to link
with it!
<p>
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. 
<p>
<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?
<p>
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>
<p>

<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>
<p>

<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+?
<p>
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 <em>anything</em>, send the README to ftp-admin@gimp.org

<!-- ----------------------------------------------------------------- -->
<sect1>What is the policy on incorporating new widgets into the library?
<p>
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?
<p>
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>
<p>

<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.
<p>

<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>
</itemize>
<!-- ***************************************************************** -->
<sect>Widgets

<!-- ----------------------------------------------------------------- -->
<sect1>How can I prevent redrawing and resizing while I change multiple widgets?
<p> 
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 find out about the selection of a GtkList?
<p>

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? 
<p>
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>How do I make menus?
<p>
Sascha Ziemann wrote to the gtk-list:  (slightly modified)
<quote>
First you have to write a function for every menu: (the translate
function returns simple strings)
</quote>
<tscreen><verb>
/***********************************************************************
** 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;
}
</verb></tscreen>
<quote>
And in your main window creation function you create a menubar in a box.
</quote>
<tscreen><verb>
  /*
  ** base frame
  */
  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  gtk_signal_connect (GTK_OBJECT (window), "destroy",
                      (GtkSignalFunc) destroy_program,
                      &amp
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);

</verb></tscreen>

<!-- ----------------------------------------------------------------- -->
<sect1>Is there a better way to do the menus?
<p>
Jay Painter wrote to the gtk-list: (slightly modified)
<quote>
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.  :)
</quote>

<!-- ----------------------------------------------------------------- -->
<sect1>How can I define a separation line in a menu? 
<p>
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 glib

<!-- ----------------------------------------------------------------- -->
<sect1>What is glib?
<p>
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.
<p>
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 ?  
<p>
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()).
<p>
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. ;)
<p>
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 and Maintainer 
<p>
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="&lt;maestrox@geocities.com&gt;">
and Tony Gale <htmlurl url="mailto:trogsta@geocities.com" name="&lt;trogsta@geocities.com&gt;">. 
Previously, Shawn T. Amundson, took care of it.

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 maintainer of the information provided within can 
not make any guarentee that the information is even accurate.

</article>