<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY wwwgtk "http://www.gtk.org">
  <!ENTITY wwwgtkmm	"http://www.gtkmm.org">
  <!ENTITY wwwglademm "http://home.wtal.de/petig/">
  <!ENTITY wwwbakery "http://bakery.sourceforge.net/">
]>

<article class="faq" id="gtkmm-faq">
<articleinfo>
  <title>gtkmm Frequently Asked Questions</title>
  <titleabbrev>gtkmm-faq</titleabbrev>
  <edition>v1.0.0</edition>
  <date>2001-06-24</date>
  <abstract>
    <para>Here are some frequently-asked questions and answers about
    gtkmm. If your questions aren't answered here then please email
    the <ulink url="&wwwgtkmm;/mailinglist.shtml">gtkmm mailing
    list</ulink>. If you would like to add to this FAQ, then please
    patch this file (gtkmm-faq.xml) or just send your suggestion to
    the <ulink url="&wwwgtkmm;/mailinglist.shtml">mailing
    list</ulink>.</para>
  </abstract>
</articleinfo>

<qandaset >

<qandadiv>
<title>gtkmm's place in the world.</title>

<qandaentry>
<question>
<para>What is GTK+?</para>
</question>
<answer>
<para>GTK+ is the GUI widget toolkit, written in C, which serves as the foundation for the GNOME project as well as many stand-alone applications. GTK+ is the foundation on which gtkmm is built. See <ulink url="&wwwgtk;">&wwwgtk;</ulink>.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>What is gtkmm (Previously known as Gtk--)?</para>
</question>
<answer>
<para>gtkmm is a C++ wrapper for GTK+. That is, it is a language binding that lets you use GTK+ from C++. This includes support for C++ features such as inheritance, polymorphism and other powerful techniques which C++ programmers expect to have at their disposal.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>Why is it named gtkmm?</para>
</question>
<answer>
<para> gtkmm was orignally named gtk-- because GTK+ already has a + in the name. However, as -- is not easily indexed by search engines the package generally went by the name gtkmm, and that's what we stuck with.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>Why use gtkmm instead of GTK+?</para></question>
<answer>
<orderedlist>
<listitem><para>gtkmm allows you to write code using normal C++ techniques such as encapsulation, derivation, and polymorphism. As a C++ programmer you probably already realise that this leads to clearer and better organised code.</para></listitem>
<listitem><para>gtkmm is more type-safe, so the compiler can detect errors that would only be detected at run time when using C. This use of specific types also makes the API clearer because you can see what types should be used just by looking at a method's declaration.</para></listitem>
<listitem><para>Inheritance can be used to derive new widgets. The derivation of new widgets in GTK+ C code is so complicated and error prone that almost no C coders do it. As a C++ developer you know that derivation is an essential Object Orientated technique.</para></listitem>
<listitem><para>Member instances can be used, simplifying memory management. All GTK+ C widgets are dealt with by use of pointers. As a C++ coder you know that pointers should be avoided where possible.</para></listitem>
<listitem><para>Less code. The GTK+ C object model uses prefixed function names and cast macros. For instance:</para>
<programlisting>gtk_button_set_text(GTK_BUTTON(button), "sometext");</programlisting>
<para>gtkmm C++ code is shorter and clearer. For instance:</para>
<programlisting>button.set_text("sometext");</programlisting></listitem>
<listitem><para>There's no need to worry about GTK+'s inconsistent reference-counting policy.</para></listitem>
</orderedlist>
</answer>
</qandaentry>

<qandaentry>
<question><para>Why use libsigc++? Why not just use the regular GTK+ signal functions?</para></question>
<answer>
<orderedlist>
<listitem><para>GTK+ signals aren't typesafe, so the compiler can't tell you whether your callback has the wrong number or type of arguments or return value.</para></listitem>
<listitem><para>They can only be used with functions or static methods. With libsigc++ callbacks can also be instance methods, using the member data of a particular object. They can also be virtual methods which you could override in a derived class.</para></listitem>
</orderedlist>
</answer>
</qandaentry>

<qandaentry>
<question><para>Why isn't GTK+/GNOME itself written in C++.</para></question>
<answer>
<orderedlist>
<listitem><para>C is a simpler language so more people are familiar with it, particularly on Unix.</para></listitem>
<listitem><para>C can be wrapped by any other language, making the API available to more developers.</para></listitem>
<listitem><para>GTK+ and GNOME have very well organised C code, much more sane than most of the gnarly C code that we encounter. This is partly due to it's C-based object-orientated structure.</para></listitem>
</orderedlist>
</answer>
</qandaentry>

<qandaentry>
<question><para>Why not just use Qt if you like C++ so much?</para></question>
<answer><para>gtkmm developers tend to prefer gtkmm to Qt because gtkmm does things in a more C++ way. Qt originates from a time when C++ and the standard library were not standardised or well supported by compilers. It therefore duplicates a lot of stuff that is now in the standard library, such as containers and type information. Most significantly, they modified the C++ language to provide signals, so that Qt classes can not be used easily with non-Qt classes.  gtkmm was able to use standard C++ to provide signals without changing the C++ language.</para>
<para>Also, gtkmm and gnomemm allow you to build software which works more closely with the GNOME desktop.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>What about Inti or gcode?</para>
</question>
<answer>
<para>Inti was a RedHat project which aimed to create a monolothic C++
programming framework palatable to corporate customers, and
which could be led by RedHat. Among other things, it was intended to include a
GTK+ binding for C++. That binding was to be similar, but less
versatile, than gtkmm. Inti did not release any code, though some existed in CVS. That project was discontinued see <ulink url="http://sources.redhat.com/ml/inti/2002-q2/msg00001.html">here</ulink>. The Inti name has now been adopted by the previously-named gcode project.</para>
<para>GCode/Inti seems to have inherited some of the original Inti's code while also
tracking gtkmm. As far as we can tell, the only difference is that
GCode uses less C++ techniques, preferring to expose more of the GTK+
C API. At the present time, the gcode/inti FAQ makes false suggestions about gtkmm - See the questions about <link linkend="question-stl-style">STL-style iterfaces</link> and <link linkend="question-c-types">C types</link>. Also, gcode/inti forces the use of a memory management system that is equivalent to gtkmm's optional Gtk::manage() feature. It does not allow the complete range of normal C++ memory management techniques.
</para>

<para>We don't know why the author chose to start a
separate and secret project instead of helping the gtkmm community.</para>  
</answer>
</qandaentry>


</qandadiv>


<qandadiv>
<title>How good is gtkmm?</title>

<qandaentry>
<question>
<para>What systems does it run under?</para>
</question>
<answer><para>gtkmm should run under any UNIX-type system with the
proper compilers and libraries installed. The GNU C++ compiler (g++,
part of gcc) together with the GNU toolset (such as found on Linux and
*BSD systems) comprise its default build environment.</para>
<para>gtkmm can also be be built and used with:
<orderedlist>
<listitem><para>Sun's Forte C++, on Solaris.</para></listitem>
<listitem><para>Windows, with the mingw build tools.</para></listitem>
</orderedlist>
</para>
</answer>
</qandaentry>


<qandaentry>
<question>
<para>How complete is it?</para>
</question>
<answer>
<para>gtkmm tries to offer all of the functionality offered by GTK+. This means that you should be able to do anything with gtkmm that's supported by GTK+, and do it more easily. If something isn't covered then we want to know about it.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>Does gtkmm support all the C++ goodies like inheritance, polymorphism, etc?</para>
</question>
<answer>
<para>Yes. gtkmm objects are normal C++ objects which implement the GTK+ inheritance model through C++ inheritance. You can do with the gtkmm widgets everything that you can do with any other C++ class.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>Does gtkmm use Standard C++ (STL) containers such as std::string and std::list</para>
</question>
<answer>
<para>Yes, we believe in reusing standard C++ code wherever
possible. This might not be obvious at first because:
<orderedlist>
<listitem><para>gtkmm has Glib::ustring which has almost the same
interface as std::string.  This new type exists because the C++
standard does not support UTF8-encoded strings.</para></listitem>
<listitem><para>The gtkmm API uses types such as
Glib::ListHandle&lt;int&gt; which can be assigned to almost any
standard C++ container, such as std::list or std::vector. These
intermediate types have been used instead of forcing you to use
any particular container.</para></listitem>
</orderedlist>
</para>

<para>In addition, some widgets, such as Gtk::TreeView, have
interfaces which are very similar to the standard containers. For
instance, you can iterate through the selected rows.
</para>
</answer>
</qandaentry>

<qandaentry>
<question id="question-stl-style">
<para>Does gtkmm force STL-style interfaces onto GTK+ widgets in a way that is inappropriate, difficult, or badly-implemented?</para>
</question>
<answer>
<para>
No, we do not force you. We have provided STL-style interfaces for some container widgets, to allow you to iterate over the child widgets, but these are in addition the the simpler interfaces. We have done this because we believe that STL-style interfaces sometimes require too much code to perform simple tasks. On the other hand, some people religiously prefer STL-code wherever possible. You have the choice.
</para>
<para>
These STL-interfaces are implemented with quite simple code and have been found to work without problems. There are no known bugs, as you can see on the bugs page.
</para>
<para>
Some classes such as Gtk::TextBuffer have only an STL-style interface. This is because the underlying widget has an STL-style interface, implemented in C. So this is the most appropriate, and easiest, way to wrap that API in C++.
</para>
</answer>
</qandaentry>

<qandaentry>
<question id="question-c-types">
<para>Does the gtkmm API use C types, such as structs?</para>
</question>
<answer>
<para>No, we wrap almost all parameters as C++ classes. which use C++ memory management. If you find parameters that use C types without good reason then we want to know about it.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>What applications have been written in gtkmm?</para>
</question>
<answer>
<para>Check out the list of applications on the <ulink url="&wwwgtkmm;/extra.shtml">Additional Resources</ulink> page from the gtkmm site.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>How does gtkmm compare to Qt?</para>
</question>
<answer>
<orderedlist>
<listitem><para>gtkmm uses pure C++. Qt requires extensions to C++ that are parsed by the moc  pre-processor.</para></listitem>
<listitem><para>gtkmm uses std::string, std::list, std::vector, iterators, etc. Qt has it's own Qt-specific containers.</para></listitem>
<listitem><para>With gtkmm normal C++ memory management can be used. Qt demands that all widgets are dealt with as pointers, and that deletion of widgets is surrendered to parent widgets.</para></listitem>
<listitem><para>Arrangement of widgets seems to be simpler in gtkmm. In Qt, Containers and Layouts are separate classes, and child widgets must be added to both. </para></listitem>
<listitem><para>The gtkmm API tends to be more explicit. The behaviour of Qt classes is often dependent upon the implicit effects of confusingly-overridden constructors.</para></listitem>
</orderedlist>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>Have you wrapped all of the GNOME APIs as well as GTK+?</para>
</question>
<answer>
<para>We have wrapped gnome-libs, in gnomemm, which provides the additional GNOME functionality. Some parts, such as the gnome-vfs, and Bonobo wrappers are not yet mature.</para>
</answer>
</qandaentry>


<qandaentry>
<question>
<para>Is gtkmm &quot;bloated&quot;</para>
</question>
<answer>
<para>No, gtkmm is a thin wrapper. People might be surprised at the large size of the gtkmm source tarball. The gtkmm tarball is large because
<orderedlist>
<listitem><para>It contains lots of generated HTML documentation - the reference documentation, the book, and this FAQ, for instance. It also contains the Docbook XML sources for that documentation.</para></listitem>
<listitem><para>It contains the .hg/.ccg source files used to generate the .h/.cc C++ source files, as well as those generated files.</para></listitem>
</orderedlist>
We ship these generated files to reduce the dependencies needed to build gtkmm itself, to make your life easier.
</para>
</answer>
</qandaentry>

</qandadiv>

<qandadiv>
<title>Further information</title>

<qandaentry>
<question>
<para>Is there a gtkmm mailing list?</para>
</question>
<answer>
<para>Yes. See the <ulink url="&wwwgtkmm;/mailinglist.shtml">subscription page</ulink></para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>What documentation is there for gtkmm?</para>
</question>
<answer>
<para>There is a largely complete tutorial, automatically-generated reference documentation, this faq, and a wealth of running examples available at the <ulink url="&wwwgtkmm;/docs/gtkmm-2.4/docs/">documentation page</ulink></para>
</answer>
</qandaentry>


<qandaentry>
<question><para>Where can I find some example code?</para></question>
<answer><para>See the examples directory in the gtkmm distribution. There are also several large third-party applications whose source you can examine.</para></answer>
</qandaentry>


</qandadiv>


<qandadiv>
<title>Using gtkmm</title>

<qandaentry>
<question><para>What compiler arguments should I use to compile a gtkmm program?</para></question>
<answer>
<para>For gtkmm 2, you should use pkg-config. For instance, for gtkmm 2.0/2.2:</para>
<para><command>pkg-config gtkmm-2.0 --libs --cflags</command></para>
<para>Or for gtkmm 2.4, wich installs in parallel with gtkmm 2.0/2.2:</para>
<para><command>pkg-config gtkmm-2.4 --libs --cflags</command></para>
<para>You should use pkg-config's PKG_CHECK_MODULES macro in your configure.in file, as demonstrated in the gtkmm_hello package.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>My application complains that it can't find libgtkmm.so</para>
</question>
<answer>
<para>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 gtkmm) is properly configured in your /etc/ldconf or that it is in your LD_LIBRARY_PATH environment variable.</para>
<para>Alternatively, specify another prefix when running configure. For instance, on RedHat, you should do this: ./configure --prefix=/usr</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>How can I build a static executable?</para>
</question>
<answer>
<para>gtkmm is pre-installed on most linux distributions so you don't really need to, but you can reconfigure gtkmm like so:</para>
<para><command>./configure --enable-static</command></para>
<para><command>make</command></para>
<para><command>make install</command></para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>How can I get the GTK+ object from a gtkmm object?</para>
</question>
<answer>
<para>If you need some GTK+ functionality which is not supported through gtkmm, you can call <command>Gtk::Widget::gobj()</command> (<command>gtkobj()</command> in gtkmm version 1.x) which will return a pointer to the plain C GTK+ data structure. You can then operate directly on this C object as you would in any GTK+ program.</para> 
</answer>
</qandaentry>

<qandaentry>
<question>
<para>How can I wrap a GTK+ widget in a gtkmm instance?</para>
</question>
<answer>
<para>Glib::wrap() will give you a pointer to gtkmm object. It is an
overloaded function, so it will give you an instance of the appropriate
class.</para> 
</answer>
</qandaentry>

<qandaentry>
<question>
<para>Can I use C++ exceptions with gtkmm?</para>
</question>
<answer>
<para>Yes, it is possible but it is not a very good idea. The official
answer is that, since plain C doesn't know what a C++ exception is,
you can use exceptions in your gtkmm code as long as there are no C
functions in your call stack between the thrower and the catcher. This
means that you have to catch your exception locally.</para>
<para>You will be warned at runtime
about uncaught exceptions, and you can specify a different handler for
uncaught exceptions.  Some gtkmm methods do even use exceptions to report
errors.  The exceptions types that might be thrown are listed in the
reference documentation of these methods.
</para>
</answer>
</qandaentry>

<qandaentry>
<question><para>How can I use Glade and/or libglade with gtkmm?</para></question>
<answer>
<orderedlist>
<listitem><para>Use libglademm, which is part of gnomemm and wraps libglade.
It allows you to load widget information from the XML user interface
description files that Glade generates at runtime. This method is strongly
recommended. Experience has shown that it works well for large projects, and
there is a lot of example code out there you can look at. For an introduction,
see the corresponding chapter in the gtkmm tutorial.</para></listitem>

<listitem><para>Alternatively, Glade 2 can output C++ code instead of C code,
when using <ulink url="&wwwglademm;">Glade--</ulink>, which is not part of gnomemm.
Note that code generation is a deprecated feature in Glade 3. For questions
regarding Glade--, please use its own mailing list.</para></listitem>
</orderedlist>
</answer>
</qandaentry>

<qandaentry>
<question><para>What does Gtk::manage(widget) do?</para></question>
<answer><para>- This means 'The container widget will delete this widget.' Some people prefer to use it so that they don't need to worry about when to delete their widgets. Gtk::manage() should only be used when add()ing a widget to a container widget.</para></answer>
</qandaentry>

<qandaentry>
<question>
<para>How can I learn about arranging widgets? I am confused by the packing options</para>
</question>
<answer>
<para>Glade is a great way to see what can be done with GTK+ and GNOME
widgets. Use Glade to explore the choice of widgets and to see how
they can be put together. You should then be able to use the same
settings as arguments to your widget constructors, and to the add()
and pack() method. Or you could us libglademm to load the GUI at runtime.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>I'm used to MFC. Where's the Document and the View? or How do I use the Document/View idea? or How do I use the MVC pattern?</para>
</question>
<answer>
<orderedlist>
<listitem><para>Document/View (which is a useful version of MVC) is not supported directly by GTK+, though it is commonly used by GTK+ programmers.  However, the TextView and TreeView interfaces are split up into model and view.</para></listitem>
<listitem><para>The <ulink url="&wwwbakery;">Bakery</ulink> library makes it very easy for  gtkmm/gnomemm C++ coders to use the Document/View framework.</para></listitem>
</orderedlist>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>How do I load pixmaps for use with gtkmm?</para>
</question>
<answer>
<para>Use Gdk::Pixbuf and/or Gtk::Image.  Both are easy to use and support a wide range of image file types via pixbuf loader plugins.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>Is gtkmm thread-safe?</para>
</question>
<answer>
<para>Paul Davis wrote:</para>
<para>Neither X, nor GDK nor GTK+ nor gtkmm are thread safe by
themselves. You must use either the gdk_threads_{enter,leave}() functions to
protect any and every call to GDK/GTK+/gtkmm functions, or
alternatively, ensure that only a single thread makes such calls. One
common way to do this is to have non-GUI threads send requests to the
GUI thread via a pipe.  The pipe is hooked into the main glib event
loop used by GTK.
</para>
<para>
Personally, i have always used the single-threaded approach, which I
find much more suitable for my apps.
</para>
<para>
Note that glibmm comes with Glib::Dispatcher, which implements
a cross-thread signal using the pipe approach described above.
</para>
<para>Andreas Rottmann added:</para>
<para>
If you need a more sophisticated cross-thread message-passing
approach, take a look at <ulink
url="http://libsigcx.sourceforge.net">libsigc++ extras</ulink>. It
provides cross-thread, typesafe slot invocation on top of <ulink
url="http://libsigc.sourceforge.net">libsigc++</ulink> and comes with
a <ulink
url="http://libsigcx.sourceforge.net/docs/sigcx_starting.html">gtkmm
example</ulink>.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>Why does my application seem to segfault inside a dynamic_cast&lt;&gt;
in gtkmm?</para>
</question>
<answer>
<para>
gcc 2.96 and earlier have a bug which prevents use of dynamic_cast&lt;&gt;
during a constructor. This is only a problem when you derive a new
class from a gtkmm class and specify a specific base class
constructor. You can avoid this by using a different constructor. For instance, instead of using the
Gtk::Button(&quot;sometext&quot;) constructor, you could use the
default constructor and then call Gtk::Button::set_label().
See this <ulink
		url="http://bugzilla.gnome.org/show_bug.cgi?id=78578">bug report</ulink> for more information. This bug does not apply to all non-default constructors - if you are using an old compiler then you should just try it and see.
</para>
</answer>
</qandaentry>


</qandadiv>

</qandaset>


  

</article>
