<?xml version="1.0" encoding="utf-8"?>
<!--
   Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com>
  
   Distributed under the Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt or copy at
   http://www.boost.org/LICENSE_1_0.txt)
  -->
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<section last-revision="$Date: 2006/11/03 19:45:40 $">
  <title>Frequently Asked Questions</title>
  
  <qandaset>
    <qandaentry>
      <question>
        <para>Don't noncopyable signal semantics mean that a class
        with a signal member will be noncopyable as well?</para>
      </question>
      <answer>
        <para>No. The compiler will not be able to generate a copy
        constructor or copy assignment operator for your class if it
        has a signal as a member, but you are free to write your own
        copy constructor and/or copy assignment operator. Just don't
        try to copy the signal.</para>
      </answer>
    </qandaentry>
    <qandaentry>
      <question>
        <para>Is Boost.Signals thread-safe?</para>
      </question>
      <answer>
        <para>No. Using Boost.Signals in a multithreaded concept is
        very dangerous, and it is very likely that the results will be
        less than satisfying. Even trying to invoke the same signal from
        two different threads is dangerous. Although we would like to
        make Signals thread-safe, it is unlikely to happen without
        help from other developers.</para>
      </answer>
    </qandaentry>
    <qandaentry>
      <question>
        <para>How do I get Boost.Signals to work with Qt?</para>
      </question>
      <answer>
        <para>When building with Qt, the Moc keywords
        <code>signals</code> and <code>slots</code> are defined using
        preprocessor macros, causing programs using Boost.Signals and
        Qt together to fail to compile.</para>

        <para><emphasis>For Qt 4.1 and later</emphasis>, This behavior
        can be turned off in Qt on a per-project or per-file basis
        with the <code>no_keywords</code> option.  This works with
        out-of-the-box builds of Boost and Qt. You do not need to
        re-configure, re-build, or duplicate existing libraries. For a
        project where you want to use both Boost.Signals and Qt
        Signals and Slots, the relevant part of your .pro file might
        look like this:</para>

        <programlisting>
CONFIG      += no_keywords # so Qt won't #define any non-all-caps `keywords'
INCLUDEPATH += . /usr/local/include/boost-1_33_1/
macx:LIBS   += /usr/local/lib/libboost_signals-1_33_1.a  # ...your exact paths may vary
</programlisting>

        <para>Now you can mix Boost.Signals and Qt Signals and Slots
        in the same files, and even within the same class or function.
        You will have to use the upper-case versions of Qt macros in
        your own code.  See the article <ulink
        url="http://scottcollins.net/articles/a-deeper-look-at-signals-and-slots.html">A
        Deeper Look at Signals and Slots</ulink> [off-site] for more
        complete examples and a survey of the strengths of the two
        systems.</para>

        <para><emphasis>Older versions of Qt</emphasis> did not
        provide a reliable mechanism for avoiding these unfriendly,
        all lower-case `keyword'-like macros.  Although this is a
        problem with Qt and not Boost.Signals, a user can use the two
        systems together with a little extra effort. There are two
        ways to do this:</para>

        <para>The first way involves defining
        the <code>BOOST_SIGNALS_NAMESPACE</code> 
        macro to some other identifier (e.g., <code>signalslib</code>)
        when building and using the Boost.Signals library. Then the
        namespace of the Boost.Signals library will be
        <code>boost::BOOST_SIGNALS_NAMESPACE</code> instead of
        <code>boost::signals</code>. To retain the original namespace
        name in translation units that do not interact with Qt, you
        can use a namespace alias:</para>

        <programlisting>
  namespace boost {
    namespace signals = BOOST_SIGNALS_NAMESPACE;
  }
</programlisting>

        <para>The second way, provided by Frank Hess, involves
        creating a header <code>signalslib.hpp</code> that contains
          the following code:</para>

        <programlisting>#ifdef signals
#error "signalslib.hpp must be included before any qt header"
#endif

#include &lt;boost/signal.hpp&gt;
namespace boost
{
  namespace signalslib = signals;
}</programlisting>

        <para>This header must be included before any Qt headers. Once
        it has been included, you can refer to the Signals library via
        the namespace <code>boost::signalslib</code>. This option is
        preferable to the first option because it can be used without
        recompiling the Signals library binary. </para>
      </answer>
    </qandaentry>
  </qandaset>
</section>
