| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> |
| <title>Tutorial</title> |
| <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> |
| <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> |
| <link rel="up" href="../signals.html" title="Chapter 18. Boost.Signals"> |
| <link rel="prev" href="../signals.html" title="Chapter 18. Boost.Signals"> |
| <link rel="next" href="reference.html" title="Reference"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table cellpadding="2" width="100%"><tr> |
| <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> |
| <td align="center"><a href="../../../index.html">Home</a></td> |
| <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> |
| <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> |
| <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> |
| <td align="center"><a href="../../../more/index.htm">More</a></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="../signals.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="signals.tutorial"></a>Tutorial</h2></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="tutorial.html#id2524870">How to Read this Tutorial</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2524933">Compatibility Note</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2525045">Hello, World! (Beginner)</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2525201">Calling multiple slots</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2525614">Passing values to and from slots</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2526529">Connection Management</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2527303">Example: Document-View</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2527430">Linking against the Signals library</a></span></dt> |
| </dl></div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="id2524870"></a>How to Read this Tutorial</h3></div></div></div> |
| <p>This tutorial is not meant to be read linearly. Its top-level |
| structure roughly separates different concepts in the library |
| (e.g., handling calling multiple slots, passing values to and from |
| slots) and in each of these concepts the basic ideas are presented |
| first and then more complex uses of the library are described |
| later. Each of the sections is marked <span class="emphasis"><em>Beginner</em></span>, |
| <span class="emphasis"><em>Intermediate</em></span>, or <span class="emphasis"><em>Advanced</em></span> to help guide the |
| reader. The <span class="emphasis"><em>Beginner</em></span> sections include information that all |
| library users should know; one can make good use of the Signals |
| library after having read only the <span class="emphasis"><em>Beginner</em></span> sections. The |
| <span class="emphasis"><em>Intermediate</em></span> sections build on the <span class="emphasis"><em>Beginner</em></span> |
| sections with slightly more complex uses of the library. Finally, |
| the <span class="emphasis"><em>Advanced</em></span> sections detail very advanced uses of the |
| Signals library, that often require a solid working knowledge of |
| the <span class="emphasis"><em>Beginner</em></span> and <span class="emphasis"><em>Intermediate</em></span> topics; most users |
| will not need to read the <span class="emphasis"><em>Advanced</em></span> sections.</p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="id2524933"></a>Compatibility Note</h3></div></div></div> |
| <p>Boost.Signals has two syntactical forms: the preferred form and |
| the compatibility form. The preferred form fits more closely with the |
| C++ language and reduces the number of separate template parameters |
| that need to be considered, often improving readability; however, the |
| preferred form is not supported on all platforms due to compiler |
| bugs. The compatible form will work on all compilers supported by |
| Boost.Signals. Consult the table below to determine which syntactic |
| form to use for your compiler. Users of Boost.Function, please note |
| that the preferred syntactic form in Signals is equivalent to that of |
| Function's preferred syntactic form.</p> |
| <p>If your compiler does not appear in this list, please try the |
| preferred syntax and report your results to the Boost list so that |
| we can keep this table up-to-date.</p> |
| <div class="informaltable"><table class="table"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th align="left">Preferred syntax</th> |
| <th align="left">Portable syntax</th> |
| </tr></thead> |
| <tbody><tr> |
| <td align="left"> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"><p>GNU C++ 2.95.x, 3.0.x, 3.1.x</p></li> |
| <li class="listitem"><p>Comeau C++ 4.2.45.2</p></li> |
| <li class="listitem"><p>SGI MIPSpro 7.3.0</p></li> |
| <li class="listitem"><p>Intel C++ 5.0, 6.0</p></li> |
| <li class="listitem"><p>Compaq's cxx 6.2</p></li> |
| <li class="listitem"><p>Microsoft Visual C++ 7.1</p></li> |
| </ul></div> |
| </td> |
| <td align="left"> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"><p><span class="emphasis"><em>Any compiler supporting the preferred syntax</em></span></p></li> |
| <li class="listitem"><p>Microsoft Visual C++ 6.0, 7.0</p></li> |
| <li class="listitem"><p>Borland C++ 5.5.1</p></li> |
| <li class="listitem"><p>Sun WorkShop 6 update 2 C++ 5.3</p></li> |
| <li class="listitem"><p>Metrowerks CodeWarrior 8.1</p></li> |
| </ul></div> |
| </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="id2525045"></a>Hello, World! (Beginner)</h3></div></div></div> |
| <p>The following example writes "Hello, World!" using signals and |
| slots. First, we create a signal <code class="computeroutput">sig</code>, a signal that |
| takes no arguments and has a void return value. Next, we connect |
| the <code class="computeroutput">hello</code> function object to the signal using the |
| <code class="computeroutput">connect</code> method. Finally, use the signal |
| <code class="computeroutput">sig</code> like a function to call the slots, which in turns |
| invokes <code class="computeroutput">HelloWorld::operator()</code> to print "Hello, |
| World!".</p> |
| <div class="informaltable"><table class="table"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th align="left">Preferred syntax</th> |
| <th align="left">Portable syntax</th> |
| </tr></thead> |
| <tbody><tr> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| struct HelloWorld |
| { |
| void operator()() const |
| { |
| std::cout << "Hello, World!" << std::endl; |
| } |
| }; |
| |
| // ... |
| |
| // Signal with no arguments and a void return value |
| <code class="computeroutput"><a class="link" href="../boost/signal.html" title="Class template signal">boost::signal</a></code><void ()> sig; |
| |
| // Connect a HelloWorld slot |
| HelloWorld hello; |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(hello); |
| |
| // Call all of the slots |
| sig(); |
| </pre> |
| </td> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| struct HelloWorld |
| { |
| void operator()() const |
| { |
| std::cout << "Hello, World!" << std::endl; |
| } |
| }; |
| |
| // ... |
| |
| // Signal with no arguments and a void return value |
| <code class="computeroutput"><a class="link" href="../boost/signalN.html" title="Class template signalN">boost::signal0</a></code><void> sig; |
| |
| // Connect a HelloWorld slot |
| HelloWorld hello; |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(hello); |
| |
| // Call all of the slots |
| sig(); |
| </pre> |
| </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="id2525201"></a>Calling multiple slots</h3></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="tutorial.html#id2525206">Connecting multiple slots (Beginner)</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2525391">Ordering slot call groups (Intermediate)</a></span></dt> |
| </dl></div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id2525206"></a>Connecting multiple slots (Beginner)</h4></div></div></div> |
| <p>Calling a single slot from a signal isn't very interesting, so |
| we can make the Hello, World program more interesting by splitting |
| the work of printing "Hello, World!" into two completely separate |
| slots. The first slot will print "Hello" and may look like |
| this:</p> |
| <pre class="programlisting"> |
| struct Hello |
| { |
| void operator()() const |
| { |
| std::cout << "Hello"; |
| } |
| }; |
| </pre> |
| <p>The second slot will print ", World!" and a newline, to complete |
| the program. The second slot may look like this:</p> |
| <pre class="programlisting"> |
| struct World |
| { |
| void operator()() const |
| { |
| std::cout << ", World!" << std::endl; |
| } |
| }; |
| </pre> |
| <p>Like in our previous example, we can create a signal |
| <code class="computeroutput">sig</code> that takes no arguments and has a |
| <code class="computeroutput">void</code> return value. This time, we connect both a |
| <code class="computeroutput">hello</code> and a <code class="computeroutput">world</code> slot to the same |
| signal, and when we call the signal both slots will be called.</p> |
| <div class="informaltable"><table class="table"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th align="left">Preferred syntax</th> |
| <th align="left">Portable syntax</th> |
| </tr></thead> |
| <tbody><tr> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| <code class="computeroutput"><a class="link" href="../boost/signal.html" title="Class template signal">boost::signal</a></code><void ()> sig; |
| |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(Hello()); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(World()); |
| |
| sig(); |
| </pre> |
| </td> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| <code class="computeroutput"><a class="link" href="../boost/signalN.html" title="Class template signalN">boost::signal0</a></code><void> sig; |
| |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(Hello()); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(World()); |
| |
| sig(); |
| </pre> |
| </td> |
| </tr></tbody> |
| </table></div> |
| <p>By default, slots are called in first-in first-out (FIFO) order, |
| so the output of this program will be as expected:</p> |
| <pre class="programlisting"> |
| Hello, World! |
| </pre> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id2525391"></a>Ordering slot call groups (Intermediate)</h4></div></div></div> |
| <p>Slots are free to have side effects, and that can mean that some |
| slots will have to be called before others even if they are not connected in that order. The Boost.Signals |
| library allows slots to be placed into groups that are ordered in |
| some way. For our Hello, World program, we want "Hello" to be |
| printed before ", World!", so we put "Hello" into a group that must |
| be executed before the group that ", World!" is in. To do this, we |
| can supply an extra parameter at the beginning of the |
| <code class="computeroutput">connect</code> call that specifies the group. Group values |
| are, by default, <code class="computeroutput">int</code>s, and are ordered by the integer |
| < relation. Here's how we construct Hello, World:</p> |
| <div class="informaltable"><table class="table"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th align="left">Preferred syntax</th> |
| <th align="left">Portable syntax</th> |
| </tr></thead> |
| <tbody><tr> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| <code class="computeroutput"><a class="link" href="../boost/signal.html" title="Class template signal">boost::signal</a></code><void ()> sig; |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(1, World()); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(0, Hello()); |
| sig(); |
| </pre> |
| </td> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| <code class="computeroutput"><a class="link" href="../boost/signalN.html" title="Class template signalN">boost::signal0</a></code><void> sig; |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(1, World()); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(0, Hello()); |
| sig(); |
| </pre> |
| </td> |
| </tr></tbody> |
| </table></div> |
| <p>This program will correctly print "Hello, World!", because the |
| <code class="computeroutput">Hello</code> object is in group 0, which precedes group 1 where |
| the <code class="computeroutput">World</code> object resides. The group |
| parameter is, in fact, optional. We omitted it in the first Hello, |
| World example because it was unnecessary when all of the slots are |
| independent. So what happens if we mix calls to connect that use the |
| group parameter and those that don't? The "unnamed" slots (i.e., those |
| that have been connected without specifying a group name) can be |
| placed at the front or back of the slot list (by passing |
| <code class="computeroutput">boost::signals::at_front</code> or <code class="computeroutput">boost::signals::at_back</code> |
| as the last parameter to <code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>, respectively), and defaults to the end of the list. When |
| a group is specified, the final parameter describes where the slot |
| will be placed within the group ordering. If we add a new slot |
| to our example like this:</p> |
| <pre class="programlisting"> |
| struct GoodMorning |
| { |
| void operator()() const |
| { |
| std::cout << "... and good morning!" << std::endl; |
| } |
| }; |
| |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(GoodMorning()); |
| </pre> |
| <p>... we will get the result we wanted:</p> |
| <pre class="programlisting"> |
| Hello, World! |
| ... and good morning! |
| </pre> |
| </div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="id2525614"></a>Passing values to and from slots</h3></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="tutorial.html#id2525620">Slot Arguments (Beginner)</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2525865">Signal Return Values (Advanced)</a></span></dt> |
| </dl></div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id2525620"></a>Slot Arguments (Beginner)</h4></div></div></div> |
| <p>Signals can propagate arguments to each of the slots they call. |
| For instance, a signal that propagates mouse motion events might |
| want to pass along the new mouse coordinates and whether the mouse |
| buttons are pressed.</p> |
| <p>As an example, we'll create a signal that passes two |
| <code class="computeroutput">float</code> arguments to its slots. Then we'll create a few |
| slots that print the results of various arithmetic operations on |
| these values.</p> |
| <pre class="programlisting"> |
| void print_sum(float x, float y) |
| { |
| std::cout << "The sum is " << x+y << std::endl; |
| } |
| |
| void print_product(float x, float y) |
| { |
| std::cout << "The product is " << x*y << std::endl; |
| } |
| |
| void print_difference(float x, float y) |
| { |
| std::cout << "The difference is " << x-y << std::endl; |
| } |
| |
| void print_quotient(float x, float y) |
| { |
| std::cout << "The quotient is " << x/y << std::endl; |
| } |
| </pre> |
| <div class="informaltable"><table class="table"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th align="left">Preferred syntax</th> |
| <th align="left">Portable syntax</th> |
| </tr></thead> |
| <tbody><tr> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| <code class="computeroutput"><a class="link" href="../boost/signal.html" title="Class template signal">boost::signal</a></code><void (float, float)> sig; |
| |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&print_sum); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&print_product); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&print_difference); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&print_quotient); |
| |
| sig(5, 3); |
| </pre> |
| </td> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| <code class="computeroutput"><a class="link" href="../boost/signalN.html" title="Class template signalN">boost::signal2</a></code><void, float, float> sig; |
| |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&print_sum); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&print_product); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&print_difference); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&print_quotient); |
| |
| sig(5, 3); |
| </pre> |
| </td> |
| </tr></tbody> |
| </table></div> |
| <p>This program will print out the following:</p> |
| <pre class="programlisting"> |
| The sum is 8 |
| The product is 15 |
| The difference is 2 |
| The quotient is 1.66667 |
| </pre> |
| <p>So any values that are given to <code class="computeroutput">sig</code> when it is |
| called like a function are passed to each of the slots. We have to |
| declare the types of these values up front when we create the |
| signal. The type <code class="computeroutput"><a class="link" href="../boost/signal.html" title="Class template signal">boost::signal</a><void (float, |
| float)></code> means that the signal has a <code class="computeroutput">void</code> |
| return value and takes two <code class="computeroutput">float</code> values. Any slot |
| connected to <code class="computeroutput">sig</code> must therefore be able to take two |
| <code class="computeroutput">float</code> values.</p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id2525865"></a>Signal Return Values (Advanced)</h4></div></div></div> |
| <p>Just as slots can receive arguments, they can also return |
| values. These values can then be returned back to the caller of the |
| signal through a <em class="firstterm">combiner</em>. The combiner is a mechanism |
| that can take the results of calling slots (there many be no |
| results or a hundred; we don't know until the program runs) and |
| coalesces them into a single result to be returned to the caller. |
| The single result is often a simple function of the results of the |
| slot calls: the result of the last slot call, the maximum value |
| returned by any slot, or a container of all of the results are some |
| possibilities.</p> |
| <p>We can modify our previous arithmetic operations example |
| slightly so that the slots all return the results of computing the |
| product, quotient, sum, or difference. Then the signal itself can |
| return a value based on these results to be printed:</p> |
| <div class="informaltable"><table class="table"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th align="left">Preferred syntax</th> |
| <th align="left">Portable syntax</th> |
| </tr></thead> |
| <tbody><tr> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| float product(float x, float y) { return x*y; } |
| float quotient(float x, float y) { return x/y; } |
| float sum(float x, float y) { return x+y; } |
| float difference(float x, float y) { return x-y; } |
| |
| <code class="computeroutput"><a class="link" href="../boost/signal.html" title="Class template signal">boost::signal</a></code><float (float x, float y)> sig; |
| |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&product); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&quotient); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&sum); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&difference); |
| |
| std::cout << sig(5, 3) << std::endl; |
| </pre> |
| </td> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| float product(float x, float y) { return x*y; } |
| float quotient(float x, float y) { return x/y; } |
| float sum(float x, float y) { return x+y; } |
| float difference(float x, float y) { return x-y; } |
| |
| <code class="computeroutput"><a class="link" href="../boost/signalN.html" title="Class template signalN">boost::signal2</a></code><float, float, float> sig; |
| |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&product); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&quotient); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&sum); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&difference); |
| |
| std::cout << sig(5, 3) << std::endl; |
| </pre> |
| </td> |
| </tr></tbody> |
| </table></div> |
| <p>This example program will output <code class="computeroutput">2</code>. This is because the |
| default behavior of a signal that has a return type |
| (<code class="computeroutput">float</code>, the first template argument given to the |
| <code class="computeroutput"><a class="link" href="../boost/signal.html" title="Class template signal">boost::signal</a></code> class template) is to call all slots and |
| then return the result returned by the last slot called. This |
| behavior is admittedly silly for this example, because slots have |
| no side effects and the result is the last slot connect.</p> |
| <p>A more interesting signal result would be the maximum of the |
| values returned by any slot. To do this, we create a custom |
| combiner that looks like this:</p> |
| <pre class="programlisting"> |
| template<typename T> |
| struct maximum |
| { |
| typedef T result_type; |
| |
| template<typename InputIterator> |
| T operator()(InputIterator first, InputIterator last) const |
| { |
| // If there are no slots to call, just return the |
| // default-constructed value |
| if (first == last) |
| return T(); |
| |
| T max_value = *first++; |
| while (first != last) { |
| if (max_value < *first) |
| max_value = *first; |
| ++first; |
| } |
| |
| return max_value; |
| } |
| }; |
| </pre> |
| <p>The <code class="computeroutput">maximum</code> class template acts as a function |
| object. Its result type is given by its template parameter, and |
| this is the type it expects to be computing the maximum based on |
| (e.g., <code class="computeroutput">maximum<float></code> would find the maximum |
| <code class="computeroutput">float</code> in a sequence of <code class="computeroutput">float</code>s). When a |
| <code class="computeroutput">maximum</code> object is invoked, it is given an input |
| iterator sequence <code class="computeroutput">[first, last)</code> that includes the |
| results of calling all of the slots. <code class="computeroutput">maximum</code> uses this |
| input iterator sequence to calculate the maximum element, and |
| returns that maximum value.</p> |
| <p>We actually use this new function object type by installing it |
| as a combiner for our signal. The combiner template argument |
| follows the signal's calling signature:</p> |
| <div class="informaltable"><table class="table"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th align="left">Preferred syntax</th> |
| <th align="left">Portable syntax</th> |
| </tr></thead> |
| <tbody><tr> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| <code class="computeroutput"><a class="link" href="../boost/signal.html" title="Class template signal">boost::signal</a></code><float (float x, float y), |
| maximum<float> > sig; |
| </pre> |
| </td> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| <code class="computeroutput"><a class="link" href="../boost/signalN.html" title="Class template signalN">boost::signal2</a></code><float, float, float, |
| maximum<float> > sig; |
| </pre> |
| </td> |
| </tr></tbody> |
| </table></div> |
| <p>Now we can connect slots that perform arithmetic functions and |
| use the signal:</p> |
| <pre class="programlisting"> |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&quotient); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&product); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&sum); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&difference); |
| |
| std::cout << sig(5, 3) << std::endl; |
| </pre> |
| <p>The output of this program will be <code class="computeroutput">15</code>, because |
| regardless of the order in which the slots are connected, the product |
| of 5 and 3 will be larger than the quotient, sum, or |
| difference.</p> |
| <p>In other cases we might want to return all of the values |
| computed by the slots together, in one large data structure. This |
| is easily done with a different combiner:</p> |
| <pre class="programlisting"> |
| template<typename Container> |
| struct aggregate_values |
| { |
| typedef Container result_type; |
| |
| template<typename InputIterator> |
| Container operator()(InputIterator first, InputIterator last) const |
| { |
| return Container(first, last); |
| } |
| }; |
| </pre> |
| <p> |
| Again, we can create a signal with this new combiner: |
| </p> |
| <div class="informaltable"><table class="table"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th align="left">Preferred syntax</th> |
| <th align="left">Portable syntax</th> |
| </tr></thead> |
| <tbody><tr> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| <code class="computeroutput"><a class="link" href="../boost/signal.html" title="Class template signal">boost::signal</a></code><float (float, float), |
| aggregate_values<std::vector<float> > > sig; |
| |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&quotient); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&product); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&sum); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&difference); |
| |
| std::vector<float> results = sig(5, 3); |
| std::copy(results.begin(), results.end(), |
| std::ostream_iterator<float>(cout, " ")); |
| </pre> |
| </td> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| <code class="computeroutput"><a class="link" href="../boost/signalN.html" title="Class template signalN">boost::signal2</a></code><float, float, float, |
| aggregate_values<std::vector<float> > > sig; |
| |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&quotient); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&product); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&sum); |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(&difference); |
| |
| std::vector<float> results = sig(5, 3); |
| std::copy(results.begin(), results.end(), |
| std::ostream_iterator<float>(cout, " ")); |
| </pre> |
| </td> |
| </tr></tbody> |
| </table></div> |
| <p>The output of this program will contain 15, 8, 1.6667, and 2. It |
| is interesting here that |
| the first template argument for the <code class="computeroutput">signal</code> class, |
| <code class="computeroutput">float</code>, is not actually the return type of the signal. |
| Instead, it is the return type used by the connected slots and will |
| also be the <code class="computeroutput">value_type</code> of the input iterators passed |
| to the combiner. The combiner itself is a function object and its |
| <code class="computeroutput">result_type</code> member type becomes the return type of the |
| signal.</p> |
| <p>The input iterators passed to the combiner transform dereference |
| operations into slot calls. Combiners therefore have the option to |
| invoke only some slots until some particular criterion is met. For |
| instance, in a distributed computing system, the combiner may ask |
| each remote system whether it will handle the request. Only one |
| remote system needs to handle a particular request, so after a |
| remote system accepts the work we do not want to ask any other |
| remote systems to perform the same task. Such a combiner need only |
| check the value returned when dereferencing the iterator, and |
| return when the value is acceptable. The following combiner returns |
| the first non-NULL pointer to a <code class="computeroutput">FulfilledRequest</code> data |
| structure, without asking any later slots to fulfill the |
| request:</p> |
| <pre class="programlisting"> |
| struct DistributeRequest { |
| typedef FulfilledRequest* result_type; |
| |
| template<typename InputIterator> |
| result_type operator()(InputIterator first, InputIterator last) const |
| { |
| while (first != last) { |
| if (result_type fulfilled = *first) |
| return fulfilled; |
| ++first; |
| } |
| return 0; |
| } |
| }; |
| </pre> |
| </div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="id2526529"></a>Connection Management</h3></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="tutorial.html#id2526534">Disconnecting Slots (Beginner)</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2526656">Blocking Slots (Beginner)</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2526735">Scoped connections (Intermediate)</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2526785">Disconnecting equivalent slots (Intermediate)</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2526870">Automatic connection management (Intermediate)</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2527073">When can disconnections occur? (Intermediate)</a></span></dt> |
| <dt><span class="section"><a href="tutorial.html#id2527144">Passing slots (Intermediate)</a></span></dt> |
| </dl></div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id2526534"></a>Disconnecting Slots (Beginner)</h4></div></div></div> |
| <p>Slots aren't expected to exist indefinately after they are |
| connected. Often slots are only used to receive a few events and |
| are then disconnected, and the programmer needs control to decide |
| when a slot should no longer be connected.</p> |
| <p>The entry point for managing connections explicitly is the |
| <code class="computeroutput"><a class="link" href="../boost/signals/connection.html" title="Class connection">boost::signals::connection</a></code> class. The |
| <code class="computeroutput"><a class="link" href="../boost/signals/connection.html" title="Class connection">connection</a></code> class uniquely represents the connection |
| between a particular signal and a particular slot. The |
| <code class="computeroutput"><a class="link" href="../boost/signals/connection.html#id623416-bb">connected</a>()</code> method checks if the signal and slot are |
| still connected, and the <code class="computeroutput"><a class="link" href="../boost/signals/connection.html#id623380-bb">disconnect()</a></code> method |
| disconnects the signal and slot if they are connected before it is |
| called. Each call to the signal's <code class="computeroutput">connect()</code> method |
| returns a connection object, which can be used to determine if the |
| connection still exists or to disconnect the signal and slot.</p> |
| <pre class="programlisting"> |
| boost::signals::connection c = sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(HelloWorld()); |
| if (c.<code class="computeroutput">connected</code>()) { |
| <span class="emphasis"><em>// c is still connected to the signal</em></span> |
| sig(); <span class="emphasis"><em>// Prints "Hello, World!"</em></span> |
| } |
| |
| c.disconnect(); <span class="emphasis"><em>// Disconnect the HelloWorld object</em></span> |
| assert(!c.<code class="computeroutput">connected</code>()); <span class="emphasis"><em>c isn't connected any more</em></span> |
| |
| sig(); <span class="emphasis"><em>// Does nothing: there are no connected slots</em></span> |
| </pre> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id2526656"></a>Blocking Slots (Beginner)</h4></div></div></div> |
| <p>Slots can be temporarily "blocked", meaning that they will be |
| ignored when the signal is invoked but have not been disconnected. The |
| <code class="computeroutput">block</code> member function |
| temporarily blocks a slot, which can be unblocked via |
| <code class="computeroutput">unblock</code>. Here is an example of |
| blocking/unblocking slots:</p> |
| <pre class="programlisting"> |
| boost::signals::connection c = sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(HelloWorld()); |
| sig(); <span class="emphasis"><em>// Prints "Hello, World!"</em></span> |
| |
| c.<code class="computeroutput">block</code>(); <span class="emphasis"><em>// block the slot</em></span> |
| assert(c.<code class="computeroutput">blocked</code>()); |
| sig(); <span class="emphasis"><em>// No output: the slot is blocked</em></span> |
| |
| c.<code class="computeroutput">unblock</code>(); <span class="emphasis"><em>// unblock the slot</em></span> |
| sig(); <span class="emphasis"><em>// Prints "Hello, World!"</em></span> |
| </pre> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id2526735"></a>Scoped connections (Intermediate)</h4></div></div></div> |
| <p>The <code class="computeroutput">boost::signals::scoped_connection</code> class |
| references a signal/slot connection that will be disconnected when |
| the <code class="computeroutput">scoped_connection</code> class goes out of scope. This |
| ability is useful when a connection need only be temporary, |
| e.g.,</p> |
| <pre class="programlisting"> |
| { |
| boost::signals::scoped_connection c = sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(ShortLived()); |
| sig(); <span class="emphasis"><em>// will call ShortLived function object</em></span> |
| } |
| sig(); <span class="emphasis"><em>// ShortLived function object no longer connected to sig</em></span> |
| </pre> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id2526785"></a>Disconnecting equivalent slots (Intermediate)</h4></div></div></div> |
| <p>One can disconnect slots that are equivalent to a given function |
| object using a form of the |
| <code class="computeroutput"><a class="link" href="../boost/signalN.html#id662943-bb">disconnect</a></code> method, so long as |
| the type of the function object has an accessible <code class="computeroutput">==</code> |
| operator. For instance: |
| |
| </p> |
| <div class="informaltable"><table class="table"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th align="left">Preferred syntax</th> |
| <th align="left">Portable syntax</th> |
| </tr></thead> |
| <tbody><tr> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| void foo(); |
| void bar(); |
| |
| signal<void()> sig; |
| |
| sig.connect(&foo); |
| sig.connect(&bar); |
| |
| // disconnects foo, but not bar |
| sig.disconnect(&foo); |
| </pre> |
| </td> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| void foo(); |
| void bar(); |
| |
| signal0<void> sig; |
| |
| sig.connect(&foo); |
| sig.connect(&bar); |
| |
| // disconnects foo, but not bar |
| sig.disconnect(&foo); |
| </pre> |
| </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id2526870"></a>Automatic connection management (Intermediate)</h4></div></div></div> |
| <p>Boost.Signals can automatically track the lifetime of objects |
| involved in signal/slot connections, including automatic |
| disconnection of slots when objects involved in the slot call are |
| destroyed. For instance, consider a simple news delivery service, |
| where clients connect to a news provider that then sends news to |
| all connected clients as information arrives. The news delivery |
| service may be constructed like this: </p> |
| <div class="informaltable"><table class="table"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th align="left">Preferred syntax</th> |
| <th align="left">Portable syntax</th> |
| </tr></thead> |
| <tbody><tr> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| class NewsItem { /* ... */ }; |
| |
| boost::signal<void (const NewsItem&)> deliverNews; |
| </pre> |
| </td> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| class NewsItem { /* ... */ }; |
| |
| boost::signal1<void, const NewsItem&> deliverNews; |
| </pre> |
| </td> |
| </tr></tbody> |
| </table></div> |
| <p>Clients that wish to receive news updates need only connect a |
| function object that can receive news items to the |
| <code class="computeroutput">deliverNews</code> signal. For instance, we may have a |
| special message area in our application specifically for news, |
| e.g.,:</p> |
| <pre class="programlisting"> |
| struct NewsMessageArea : public MessageArea |
| { |
| public: |
| // ... |
| |
| void displayNews(const NewsItem& news) const |
| { |
| messageText = news.text(); |
| update(); |
| } |
| }; |
| |
| // ... |
| NewsMessageArea newsMessageArea = new NewsMessageArea(/* ... */); |
| // ... |
| deliverNews.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(boost::bind(&NewsMessageArea::displayNews, |
| newsMessageArea, _1)); |
| </pre> |
| <p>However, what if the user closes the news message area, |
| destroying the <code class="computeroutput">newsMessageArea</code> object that |
| <code class="computeroutput">deliverNews</code> knows about? Most likely, a segmentation |
| fault will occur. However, with Boost.Signals one need only make |
| <code class="computeroutput">NewsMessageArea</code> <span class="emphasis"><em>trackable</em></span>, and the slot |
| involving <code class="computeroutput">newsMessageArea</code> will be disconnected when |
| <code class="computeroutput">newsMessageArea</code> is destroyed. The |
| <code class="computeroutput">NewsMessageArea</code> class is made trackable by deriving |
| publicly from the <code class="computeroutput">boost::signals::trackable</code> class, |
| e.g.:</p> |
| <pre class="programlisting"> |
| struct NewsMessageArea : public MessageArea, public boost::signals::trackable |
| { |
| // ... |
| }; |
| </pre> |
| <p>At this time there is a significant limitation to the use of |
| <code class="computeroutput">trackable</code> objects in making slot connections: function |
| objects built using Boost.Bind are understood, such that pointers |
| or references to <code class="computeroutput">trackable</code> objects passed to |
| <code class="computeroutput">boost::bind</code> will be found and tracked.</p> |
| <p><span class="bold"><strong>Warning</strong></span>: User-defined function objects and function |
| objects from other libraries (e.g., Boost.Function or Boost.Lambda) |
| do not implement the required interfaces for <code class="computeroutput">trackable</code> |
| object detection, and <span class="emphasis"><em>will silently ignore any bound trackable |
| objects</em></span>. Future versions of the Boost libraries will address |
| this limitation.</p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id2527073"></a>When can disconnections occur? (Intermediate)</h4></div></div></div> |
| <p>Signal/slot disconnections occur when any of these conditions |
| occur:</p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"><p>The connection is explicitly disconnected via the connection's |
| <code class="computeroutput">disconnect</code> method directly, or indirectly via the |
| signal's <code class="computeroutput">disconnect</code> method or |
| <code class="computeroutput">scoped_connection</code>'s destructor.</p></li> |
| <li class="listitem"><p>A <code class="computeroutput">trackable</code> object bound to the slot is |
| destroyed.</p></li> |
| <li class="listitem"><p>The signal is destroyed.</p></li> |
| </ul></div> |
| <p>These events can occur at any time without disrupting a signal's |
| calling sequence. If a signal/slot connection is disconnected at |
| any time during a signal's calling sequence, the calling sequence |
| will still continue but will not invoke the disconnected slot. |
| Additionally, a signal may be destroyed while it is in a calling |
| sequence, and which case it will complete its slot call sequence |
| but may not be accessed directly.</p> |
| <p>Signals may be invoked recursively (e.g., a signal A calls a |
| slot B that invokes signal A...). The disconnection behavior does |
| not change in the recursive case, except that the slot calling |
| sequence includes slot calls for all nested invocations of the |
| signal.</p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id2527144"></a>Passing slots (Intermediate)</h4></div></div></div> |
| <p>Slots in the Boost.Signals library are created from arbitrary |
| function objects, and therefore have no fixed type. However, it is |
| commonplace to require that slots be passed through interfaces that |
| cannot be templates. Slots can be passed via the |
| <code class="computeroutput">slot_type</code> for each particular signal type and any |
| function object compatible with the signature of the signal can be |
| passed to a <code class="computeroutput">slot_type</code> parameter. For instance:</p> |
| <div class="informaltable"><table class="table"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th align="left">Preferred syntax</th> |
| <th align="left">Portable syntax</th> |
| </tr></thead> |
| <tbody><tr> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| class Button |
| { |
| typedef boost::signal<void (int x, int y)> OnClick; |
| |
| public: |
| void doOnClick(const OnClick::slot_type& slot); |
| |
| private: |
| OnClick onClick; |
| }; |
| |
| void Button::doOnClick( |
| const OnClick::slot_type& slot |
| ) |
| { |
| onClick.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(slot); |
| } |
| |
| void printCoordinates(long x, long y) |
| { |
| std::cout << "(" << x << ", " << y << ")\n"; |
| } |
| |
| void f(Button& button) |
| { |
| button.doOnClick(&printCoordinates); |
| } |
| </pre> |
| </td> |
| <td align="left"> |
| <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"> |
| class Button |
| { |
| typedef <code class="computeroutput"><a class="link" href="../boost/signalN.html" title="Class template signalN">boost::signal2</a></code><void,int,int> OnClick; |
| |
| public: |
| void doOnClick(const OnClick::slot_type& slot); |
| |
| private: |
| OnClick onClick; |
| }; |
| |
| void Button::doOnClick( |
| const OnClick::slot_type& slot |
| ) |
| { |
| onClick.<code class="computeroutput"><a class="link" href="../boost/signalN.html#id616339-bb">connect</a></code>(slot); |
| } |
| |
| void printCoordinates(long x, long y) |
| { |
| std::cout << "(" << x << ", " << y << ")\n"; |
| } |
| |
| void f(Button& button) |
| { |
| button.doOnClick(&printCoordinates); |
| } |
| </pre> |
| </td> |
| </tr></tbody> |
| </table></div> |
| <p>The <code class="computeroutput">doOnClick</code> method is now functionally equivalent |
| to the <code class="computeroutput">connect</code> method of the <code class="computeroutput">onClick</code> |
| signal, but the details of the <code class="computeroutput">doOnClick</code> method can be |
| hidden in an implementation detail file.</p> |
| </div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="id2527303"></a>Example: Document-View</h3></div></div></div> |
| <p>Signals can be used to implement flexible Document-View |
| architectures. The document will contain a signal to which each of |
| the views can connect. The following <code class="computeroutput">Document</code> class |
| defines a simple text document that supports mulitple views. Note |
| that it stores a single signal to which all of the views will be |
| connected.</p> |
| <pre class="programlisting">class Document |
| { |
| public: |
| typedef boost::signal<void (bool)> signal_t; |
| typedef boost::signals::connection connection_t; |
| |
| public: |
| Document() |
| {} |
| |
| connection_t connect(signal_t::slot_function_type subscriber) |
| { |
| return m_sig.connect(subscriber); |
| } |
| |
| void disconnect(connection_t subscriber) |
| { |
| subscriber.disconnect(); |
| } |
| |
| void append(const char* s) |
| { |
| m_text += s; |
| m_sig(true); |
| } |
| |
| const std::string& getText() const |
| { |
| return m_text; |
| } |
| |
| private: |
| signal_t m_sig; |
| std::string m_text; |
| };</pre> |
| <p>Next, we can define a <code class="computeroutput">View</code> base class from which |
| views can derive. This isn't strictly required, but it keeps the |
| Document-View logic separate from the logic itself. Note that the |
| constructor just connects the view to the document and the |
| destructor disconnects the view.</p> |
| <pre class="programlisting"> |
| class View |
| { |
| public: |
| View(Document& m) |
| : m_document(m) |
| { |
| m_connection = m_document.connect(boost::bind(&View::refresh, this, _1)); |
| } |
| |
| virtual ~View() |
| { |
| m_document.disconnect(m_connection); |
| } |
| |
| virtual void refresh(bool bExtended) const = 0; |
| |
| protected: |
| Document& m_document; |
| |
| private: |
| Document::connection_t m_connection; |
| }; |
| </pre> |
| <p>Finally, we can begin to define views. The |
| following <code class="computeroutput">TextView</code> class provides a simple view of the |
| document text.</p> |
| <pre class="programlisting">class TextView : public View |
| { |
| public: |
| TextView(Document& doc) |
| : View(doc) |
| {} |
| |
| virtual void refresh(bool bExtended) const |
| { |
| std::cout << "TextView: " << m_document.getText() << std::endl; |
| } |
| };</pre> |
| <p>Alternatively, we can provide a view of the document |
| translated into hex values using the <code class="computeroutput">HexView</code> |
| view:</p> |
| <pre class="programlisting">class HexView : public View |
| { |
| public: |
| HexView(Document& doc) |
| : View(doc) |
| {} |
| |
| virtual void refresh(bool bExtended) const |
| { |
| const std::string& s = m_document.getText(); |
| |
| std::cout << "HexView:"; |
| |
| for (std::string::const_iterator it = s.begin(); it != s.end(); ++it) |
| std::cout << ' ' << std::hex << static_cast<int>(*it); |
| |
| std::cout << std::endl; |
| } |
| };</pre> |
| <p>To tie the example together, here is a |
| simple <code class="computeroutput">main</code> function that sets up two views and then |
| modifies the document:</p> |
| <pre class="programlisting">int main(int argc, char* argv[]) |
| { |
| Document doc; |
| TextView v1(doc); |
| HexView v2(doc); |
| |
| doc.append(argc == 2 ? argv[1] : "Hello world!"); |
| return 0; |
| }</pre> |
| <p>The complete example source, contributed by Keith MacDonald, |
| is available in <a href="../../../libs/signals/example/doc_view.cpp" target="_top"><code class="computeroutput">libs/signals/example/doc_view.cpp</code></a>.</p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="id2527430"></a>Linking against the Signals library</h3></div></div></div> |
| <p>Part of the Boost.Signals library is compiled into a binary |
| library that must be linked into your application to use |
| Signals. Please refer to |
| the <a href="../../../more/getting_started.html" target="_top">Getting Started</a> |
| guide. You will need to link against the <code class="computeroutput">boost_signals</code> |
| library.</p> |
| </div> |
| </div> |
| <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> |
| <td align="left"><p><small>Last revised: January 29, 2007 at 20:05:29 +0000</small></p></td> |
| <td align="right"><div class="copyright-footer">Copyright © 2001-2004 Douglas Gregor<p>Use, modification and distribution is subject to the Boost |
| Software License, Version 1.0. (See accompanying file |
| <code class="filename">LICENSE_1_0.txt</code> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p> |
| </div></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="../signals.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| </body> |
| </html> |