This FAQ aims to answer any questions you might have about Gtk--, 
the C++ wrapper for the GTK+ C library. This FAQ is available from 
http://212.187.12.197/Gtk--FAQ/

The author appreciates your comments and suggestions concerning this
document, except on question 1.3 (try glaurent@worldnet.fr for this
one). He can be reached at Robert_Gasch@peoplesoft.com. 

Assumptions: 
	- when we talk about compilers, unless specifically mentioned 
	  otherwise, we are talking about the GNU C++ compilers g++ 
	  and egcs.
	- when talking about libgtkmm and/or Gtk--, we're talking about 
	  version 1.0.x or 1.1.x 

Version Info:
	Sep 1999: first draft
	Oct 1999: second draft, various corrections
	30Oct1999: v0.01: added CVS section + corrections

-------------------------- Index ----------------------------

1 General Information about Gtk--
1.1) What is GTK+
1.2) What is Gtk--
1.3) Why use C++ ?
1.4) What systems does it run under?
1.5) What dependencies does it have?
1.6) How is it distributed? 
1.7) How complete is it?
1.8) Does it support all the C++ goodies like inheritance, polymorphism, etc?
1.9) What applications have been written in Gtk--?
1.10) Is there a Gtk-- mailing list? 
1.11) What documentation is there for Gtk--?
1.12) How can I make sense of GTK+ documentation if I'm using Gtk--?
1.13) Where can I get help with Gtk-- problems? 

2 Getting, configuring and running Gtk-- 
2.1) What do I need to run Gtk--?
2.2) Where can I get Gtk--?
2.3) Where can I get current CVS snapshots of Gtk--?
2.4) How do I configure/compile Gtk--?
2.5) Something breaks duing 'make'. Where should I look first?
2.6) My application complains that it can't find libgtkmm.so? 
2.7) How fat of wrapper is Gtk--? 
2.8) How can build a static executable (libgtkmm.a seems to be missing)?
2.9) I get -fhuge-objects errors when compiling.
2.10) I get undefined references when linking.
2.11) I get link errors (differing symbol sizes).
2.12) I get link errors (undefined references).

3 Building from CVS
3.1) CVS
3.2) Building from CVS
3.3.1) Problems building from CVS
3.3.2) *More* problems building from CVS

4) Specifics
4.1) How does Gtk-- handle the GTK+ connection of signals to functions? 
4.1) Do Timeouts work the same way?
4.3) How do I manually pump the GTK+ event loop using Gtk--? 
4.3) How does Gtk-- handle the GTK+ connection of signals functions? 
4.4) How are widgets passed when being added/packed?
4.5) What are the Gtk-- signal names?



--------------- General Information about Gtk-- ----------------

1.1) What is GTK+
A:   GTK+ is the widget toolkit written in C originally developed for the 
     GIMP (www.gimp.org) and now used as a general windowing toolkit which 
     serves as the foundation the GNOME project as well as many stand-alone 
     applications. GTK+ is the foundation Gtk-- is built on. If you want 
     to work with Gtk--, taking a look at the materials provided at 
     the documentation and FAQ provided at www.gtk.org is probably 
     a good idea. 

1.2) What is Gtk--
A:   Gtk-- is a C++ wrapper for GTK+. That is, it creates language 
     bindings that let you use GTK+ from C++. This includes support for 
     C++ features such as inheritance, polymorphism and other powerful 
     methods/techniques which C++ programmers expects to have at their 
     disposal. 
     Gtk-- allows you to write C++ code that can uses the GTK+ widget set 
     through the Gtk-- interface, thus allowing to to work with C++ objects 
     rather than the plain Gkt+ C widgets.

     Gtk-- is maintained by
       Tero Pulkinnen <terop@modeemi.cs.tut.fi>
       Karl Nelson <kenelson@ece.ucdavis.edu>
       Guillaume Laurent <glaurent@worldnet.fr>
       Todd Dukes <tjdukes@flash.net>

     The first version was written by Elliot Lee.
     Other contributors include
       Phil Dawes
       Havoc Pennington
       and others, see the AUTHORS file for details. 

1.3) Why use C++ ? It's too complicated, slow and bloated. I know,
     I've tried it and it sucked. Look at all those huge Windows apps,
     compared to slim and fast Linux apps written in C.
A:   But of course. How come we never thought about it
     before. Thanks for setting us straight on this. If it weren't
     for geniuses like yourself who can fully grasp all the
     subtleties of a language by just "trying it", (or, even more
     impressive, by reading about it on Usenet and slashdot.org),
     the whole Open Source community would be doomed. Thank you so
     much, really. And since the future of mankind certainly depends
     on the thriving of Open Source software, today you just saved
     humanity. The whole Gtk-- team shall chant your name and deeds
     for as long as we live, and so shall our children, and the
     children of our children. We hope that gives you a warm feeling
     deep inside.

1.4) What systems does it run under?
A:   Gtk-- should run under any UNIX type system with the proper compilers 
     and libraries installed. The GNU C++ compiler (g++) together with the GNU 
     toolset (such as found on Linux and *BSD systems) comprise it's default 
     build build environment. 

1.5) What dependencies does it have?
A:   Gtk-- (as of version 1.0.x) requires
	- Glib and GTK+ (1.2.x)
	- C++ compiler supporting most ANSI C++ features
	- optionally, GNOME and gdk_imlib 

1.6) How is it distributed? 
A:   Gtk-- is distributed under the GNU Library General Public
     Licence. The GPL is distributed with Gtk-- (see the file COPYING)
     or can alternativeley be found at http://www.gnu.org/copyleft/gpl.html

1.7) How complete is it?
A:   As of version 1.0.x, Gtk-- handles most if not all the functionality 
     offered of the GTK+ 1.2.x series. This means that you should be able 
     to do anything with Gtk-- that's supported by GTK+. 

1.8) Does Gtk-- support all the C++ goodies like inheritance, polymorphism, etc?
A:   Yes. Gtk-- objects are normal C++ objects which implement the GTK+ 
     inheritance model through C++ inheritance. You can do with the Gtk-- 
     widgets everything that you can do with any other C++ class. 

1.9) What applications have been written in Gtk--?
A:   The following applications have progressed beyond the simple demo stage:
        EOS - an electronic object simulator
                www.mondoshawan.ml.org/eos/
        Mage adventure game engine
                mage.rulez.org
        Radioactive
                cactus.rulez.org/radioactive
        Terraform - an interactive digital terrain editor
                212.187.12.197/RNG/terraform/
        XCallerid
                www.cs.unc.edu/~yandle/xcallerid/

1.10) Is there a Gtk-- mailing list? 
A:    Yes. Send a 'subscribe' request to majordomo@modeemi.cs.tut.fi.

1.11) Where can I get help with Gtk-- problems? 
A:    Your best bet is probably the Gtk-- mailing-list. You can try the
      main GTK+ mailing-list too (gtk-list@redhat.com), some of the
      Gtk-- maintainers read it. However, if you post on gtk-list,
      please add '[gtk--]' in the subject of your message to make it
      easier to spot.

1.12) What documentation is there for Gtk--?
A:    Not much, beyond a brief tutorial and a few sample programs. Fortunateley 
      for most code, the translation from GTK+ to Gtk-- is rather trivial. 

1.13) How can I make sense of GTK+ documentation if I'm using Gtk--?
A:    It's pretty easy. If you have the following GTK+ code

        GtkWidget       *w = gtk_widget_new ();
        gtk_widget_realize (w);
        gtk_widget_set_usize (w, width, height);
        gtk_widget_destroy (w);

      it becomes the following Gtk-- code.

        Gtk_Widget      *w = new Gtk_Widget();
        w->realize ();
        w->set_usize (width, height);
        w->destroy ();

      You might want to take a look at some of examples that have also
      been translated into Gtk-- and compare them to their GTK+
      counterparts.

      Derivation of widgets follows C++ rules and every signal
      has a _impl that you can overide as usual. Thus you always
      have the choice of deriving or connecting. Most programs
      use both. For a button to call something when pressed
      you will likely just use signals. For the main window most
      likely you will derive.

	As a general rule conversion from GTK+ to gtk-- uses
  		GtkFoo*                        =>  Gtk_Foo
  		gtk_foo_method(GtkFoo* f,args) =>  f.method(args);
  		GdkFoo*                        =>  Gdk_Foo
  		gchar *                        =>  string&

      Things to note:
      * Most Gdk-- types are handles and not objects themselves.
        (Don't new them, use type.create();)  They CAN point to a NULL object.
        These are properties inherited from X.)




--------------- Getting, configuring and running Gtk-- ---------------

2.1) What do I need to run Gtk--?
A:   Gtk-- (as of version 1.0.x) requires a UNIX system running X11R6 and 
     the proper software: 
	- a sufficiently recent Glib and GTK+ (1.2.x)
	- a C++ compiler supporting ANSI C++ features (such as g++ 2.8.1)
	- optionally, GNOME and gdk_imlib 
	- on some systems (IRIX, ???) you may have to install GNU make
     The configure script tests for all these requirements. 

2.2) Where can I get Gtk--?
A:   You can get Gtk-- from it's homepage: 
	http://www.iki.fi/terop/gtk/gtk--.html

2.3) Where can I get current CVS snapshots of Gtk--?
A:   Current CVS snapshots of all GNome software can be found at
	ftp://ftp.jimpick.com/pub/gnome/snap/
     where they are updated daily. 

2.4) How do I configure/compile Gtk--?
A:   Typically it should be enough to say

	./configure
	make
	make install

2.5) Something breaks duing 'make'. Where should I look first?
A:   First of all, check the GTK+ FAQ. Since Gtk-- is built on top of 
     GTK+, they share some common dependencies, such as a proper 
     version of Perl and a fully functional (GNU style) make. 

     If you've managed to successfully compile GTK+, you know that the 
     basic parts of your C compile environment are OK and you can start to 
     focus on the C++ side of things. 

2.6) My application complains that it can't find libgtkmm.so. 
A:   Since this is the single most asked question about running Gtk programs, 
     we'll answer it here, even though it is in the GTK+ FAQ. 
     Make sure the /usr/local/lib (the default install dir for Gtk--)
     is properly configured in your /etc/ldconf or that it is in your 
     LD_LIBRARY_PATH environment variable 

2.7) How fat or skinny of wrapper is Gtk--? 
A:   It's pretty skinny. Looking at some of the tutorial examples, after 
     strippig the (dynamic) executables, we get the following sizes (on 
     a RH 6.0 system, using egcs 2.91.66, not using any Gtk themes): 

	Example		GTK+File 	GTK+Mem		Gtk--File 	Gtk--Mem

	buttons		6256		1844		30996		2820
	clist		7720		1900		32012		2840
	filesel		5496		2076		27280		3052
	progressbar	9844		1916		34056		2932
	rulers		6632		1812		24300		2740

      where GTK+File is the file size and GTK+Mem the resident memory size of 
      the GTK+ executables; and Gtk--File and Gtk--Mem the respective sizes 
      of the Gtk-- executables. 

      All Unices today are clever enough to actually load in
      memory only what is needed. Therefore, a large executable and
      large dynamic libraries do not necessarily mean large memory
      consumption.

2.8) How can build a static executable (libgtkmm.a seems to be missing)?
A:   Reconfigure Gtk-- by doing a

	./configure --enable-static
	make
	make install

     in the Gtk-- distribution directory to create and install libgtkmm.a. 


2.9) I get -fhuge_objects compile errors like
     TFDialogOptions.h:87: sorry, not implemented: object size exceeds normal
	limit for virtual function table implementation, recompile all source 
	and use -fhuge-objects
A:   Yes, on certain platforms gcc/egcs seem to be more succeptible to run 
     into this error. Your immediate workaround would be to recompile 
     Gtk-- and all software that uses it using the -fhuge-objects flag. 

     The proper solution to this problem however is that the code 
     you're compiling should be changed so that is uses more dynamic 
     less stack based memory allocation. 


2.10) I get link errors like 
     TFWindow.o: In function `ItemFactoryConnector<TFWindow, basic_string
	<char, string_char_traits<char>, __default_alloc_template<true, 0> > 
	>::connectTo(Gtk_Widget *) const':
	TFWindow.o(.ItemFactoryConnector<TFWindow, basic_string<char, 
	string_char_traits<char>, __default_alloc_template<1, 0> > 
	>::gnu.linkonce.t.connectTo(Gtk_Widget *) const+0x23e): 
	undefined reference to `Gtk_Object::signal_connect(char const *, 
	void (*)(...), void *)'
A:   This is usually the result of having different compile options 
     for glib, GTK+ and Gtk--, specifically the -pedantic option. Make 
     sure you use the same '-pedantic'ness for each of these libraries. 
     Either all or none of these should be compiled with -pedantic. 


2.11) I get link errors (differing symbol sizes) looking like this: 
       ld: warning: symbol 'Connection_impl virtual table' has differing sizes: 
     	(file GuiBufferedDrawingArea.o value=0x10; file 
	/usr/local/opt/libgtk--/lib/libgtkmm.so value=0x20);
	GuiBufferedDrawingArea.o definition taken
A:   This seems to be the reault of having different compile options for Gtk-- 
     and your application, specifically the -fhuge-objects flag. Make sure you 
     use the same '-fhuge-object'ness for both Gtk-- and all your Gtk-- 
     programs). Either all or none of these should be compiled with 
     -fhuge-objects. See the -fhuge-objects question above for 
     details on how to avoid this warning. 


2.12) Closing certain dialogs results in a Gtk-CRITICAL warning like: 
	Gtk-CRITICAL **: file gtkwidget.c: line 1396 (gtk_widget_destroy): 
	assertion `GTK_OBJECT_CONSTRUCTED (widget)' failed.
A:    This is a bug in Gtk-- 1.0.0. It is fixed in 1.0.1. or current CVS 
      snapshots (as of mid-April 1999). 



------------------------ Building from CVS ------------------------

3.1) CVS
A:   There are excellent sources of information and tutorials available,
     both on the Gnome Developer's website (http://developer.gnome.org).
     In fact, if you got to this FAQ, you've probably passed by the CVS
     tutorial at http://developer.gnome.org/tools/cvs.html.  There's also
     documentation at the following addresses:

     http://www.cyclic.com/cvs/doc-blandy-text.html (Introduction to CVS)
     http://www.loria.fr/~molli/cvs/doc/cvs_toc.html (CVS manual)


3.2) Building from CVS

     Once you have checked out the code, you need to run the
     autoconf/automake scripts to generate the configure script and
     makefiles.  It's fairly simple:

     (assuming you've logged into the cvs server)
     % cvs checkout <target>
     % cd <target>
     % ./autogen.sh      # this should run autoconf/automake and configure

     If there are any arguments you want to supply to the configure script,
     add them as arguments to the autogen.sh command.  Or simply erase the
     config.cache file and run ./configure with the proper args.

3.3.1) Problems building from CVS

     Sometimes, depending on what other packages you've installed or
     compiled or upgraded, you may run into problems during the autogen.sh
     script.  Some symptoms of these problems look like:

     % ./autogen.sh
     [snip]
     Running aclocal  -I macros ...
     aclocal: configure.in: 13: macro `AM_PROG_LIBTOOL' not found in library
     aclocal: configure.in: 19: macro `AM_PATH_GTK' not found in library
     aclocal: configure.in: 19: macro `AM_PATH_GTK' not found in library
     [snip]

     This is caused when the aclocal program cannot find all the required
     m4 macro files.  In this case, we have installed or upgraded software
     packages into the /usr/local directory hierarchy.  However, aclocal is
     only looking in the standard /usr/share/aclocal directory and the
     local ./macros directory.  We need to tell aclocal to look in the
     /usr/local/share/aclocal directory for user-installed files.

     % export ACLOCAL_FLAGS='-I /usr/local/share/aclocal'
     % ./autogen.sh

     This should lead to a successful install


3.3.2) *More* problems building from CVS

     However, after trying the above ACLOCAL_FLAGS trick, you might run
     into further problems, as shown below:

     % ./autogen.sh
     [snip]
     aclocal: /usr/local/share/aclocal/glib.m4: 8: duplicated macro
     `AM_PATH_GLIB'
     [snip]
     aclocal: configure.in: 13: macro `AM_PROG_LIBTOOL' not found in library
     aclocal: configure.in: 19: macro `AM_PATH_GTK' not found in library
     aclocal: configure.in: 19: macro `AM_PATH_GTK' not found in library
     [snip]

     This is caused when there is something wrong with the m4 macros.  In
     this case, the "duplicated macro" is the first warning that something
     has gone awry.  Iff we look at the /usr/share/aclocal directory, we
     find the files:

     % ls /usr/share/aclocal
     ccstdc.m4   gimp.m4    lcmessage.m4   missing.m4   protos.m4   strtod.m4
     cond.m4     glib.m4    lex.m4         mktime.m4    ptrdiff.m4 
     termios.m4
     dmalloc.m4  guile.m4   libmikmod.m4   multi.m4     qthreads.m4  winsz.m4
     error.m4    header.m4  lispdir.m4     obstack.m4   regex.m4
     gettext.m4  init.m4    maintainer.m4  progtest.m4  sanity.m4
 
     while in /usr/local/share/aclocal  we find:

     % ls /usr/local/share/aclocal
     audiofile.m4  glib.m4   gtk.m4    libIDL.m4  libglade.m4  sigc++.m4
     esd.m4        gtk--.m4  imlib.m4  libart.m4  libtool.m4


     Clearly, the glib.m4 file is duplicated.  We must get rid of the
     duplication, in favor of the new(er) libraries installed in
     /usr/local.  So a simple:

     % mv /usr/share/aclocal/glib.m4 /usr/share/aclocal/glib.m4.old

     and rerun the autogen.sh leads to a successful build.


     Thanks to Carl Nygard <cnygard@bellatlantic.net>, Michael Meeks, 
     Morten Welinder, and Miguel Icaza for this section.



------------------------ Specifics ------------------------

4.1) How does Gtk-- handle the GTK+ connection of signals functions? 
A:   In GTK+, you connect to C functions. In Gtk--, you connect to 
     C++ class methods. The call now looks like this: 

	connect_to_method(d_adjustment.value_changed, this, &MyClass::adj_callback);

     where the 1st parameter is the widget property we bind to, the second one 
     the class pointer and the third one the method from the specified class 
     that will be called. 

	Traditionally, you'll see a lot of code that looks like this: 

	connect_to_method(d_adjustment.value_changed, this, adj_callback);

	but you should use the 1st version as it seems starting with 
	GCC 2.95, the gcc compilers will not accept the 2nd type anymore. 


4.2) Do timeouts work the same way?
A:   Yes, you can connect to a timeout using

	connect_to_method (Gtk_Main::timeout(50), this, &MyClass::timeout_callback);
	

4.3) How do I manually pump the GTK+ event loop using Gtk--? 
A:   Try the following: 

	Gtk_Main *gtkMain = Gtk_Main::instance();
	while (gtkMain->events_pending())
		gtkMain->iteration ();


4.4) How are widgets passed when being added/packed?
A:   Gtk-- uses the convention that the first parameter to such a 
     method (ie: the widget which is being added/packed) is passed as 
     a reference. In practice, this looks as follows; 

	Gtk_Window	w;
	Gtk_Frame	*f = new Gtk_Frame("FrameTitle");
	Gtk_HSeparator	s;

	w.add (*f);
	f->add (s);


4.5) Why do some of the signal types have GTK+ parameters as objects?

A: 	This is a direct result of the code generator not being able to
	handle changes in the argument lists.  For those places you will
	have to write functions that use the gtk+ object rather than the C++ one.
	The connection of the signal is not altered by this, only the
	parameter list.  Most major methods with this problem have been
	kludged arround using a C++ signal combined with a C one.  This is
	set to be improved in Gtk-- 1.2.

