| <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.78.1"> | |
| <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> | |
| <link rel="up" href="../signals.html" title="Chapter 26. Boost.Signals"> | |
| <link rel="prev" href="../signals.html" title="Chapter 26. 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 class="toc"> | |
| <dt><span class="section"><a href="tutorial.html#idp419046320">How to Read this Tutorial</a></span></dt> | |
| <dt><span class="section"><a href="tutorial.html#idp419053104">Compatibility Note</a></span></dt> | |
| <dt><span class="section"><a href="tutorial.html#idp419066784">Hello, World! (Beginner)</a></span></dt> | |
| <dt><span class="section"><a href="tutorial.html#idp419083952">Calling multiple slots</a></span></dt> | |
| <dt><span class="section"><a href="tutorial.html#idp419130768">Passing values to and from slots</a></span></dt> | |
| <dt><span class="section"><a href="tutorial.html#idp419237648">Connection Management</a></span></dt> | |
| <dt><span class="section"><a href="tutorial.html#idp419324768">Example: Document-View</a></span></dt> | |
| <dt><span class="section"><a href="tutorial.html#idp419339952">Linking against the Signals library</a></span></dt> | |
| </dl></div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h3 class="title"> | |
| <a name="idp419046320"></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="idp419053104"></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" style="list-style-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" style="list-style-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="idp419066784"></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#idp142778080-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#idp142778080-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="idp419083952"></a>Calling multiple slots</h3></div></div></div> | |
| <div class="toc"><dl class="toc"> | |
| <dt><span class="section"><a href="tutorial.html#idp419084496">Connecting multiple slots (Beginner)</a></span></dt> | |
| <dt><span class="section"><a href="tutorial.html#idp419105760">Ordering slot call groups (Intermediate)</a></span></dt> | |
| </dl></div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="idp419084496"></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#idp142778080-bb">connect</a></code>(Hello()); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-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#idp142778080-bb">connect</a></code>(Hello()); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-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="idp419105760"></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#idp142778080-bb">connect</a></code>(1, World()); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-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#idp142778080-bb">connect</a></code>(1, World()); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-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#idp142778080-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#idp142778080-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="idp419130768"></a>Passing values to and from slots</h3></div></div></div> | |
| <div class="toc"><dl class="toc"> | |
| <dt><span class="section"><a href="tutorial.html#idp419131328">Slot Arguments (Beginner)</a></span></dt> | |
| <dt><span class="section"><a href="tutorial.html#idp419160608">Signal Return Values (Advanced)</a></span></dt> | |
| </dl></div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="idp419131328"></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#idp142778080-bb">connect</a></code>(&print_sum); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-bb">connect</a></code>(&print_product); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-bb">connect</a></code>(&print_difference); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-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#idp142778080-bb">connect</a></code>(&print_sum); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-bb">connect</a></code>(&print_product); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-bb">connect</a></code>(&print_difference); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-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="idp419160608"></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#idp142778080-bb">connect</a></code>(&product); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-bb">connect</a></code>(&quotient); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-bb">connect</a></code>(&sum); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-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#idp142778080-bb">connect</a></code>(&product); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-bb">connect</a></code>(&quotient); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-bb">connect</a></code>(&sum); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-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#idp142778080-bb">connect</a></code>(&quotient); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-bb">connect</a></code>(&product); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-bb">connect</a></code>(&sum); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-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#idp142778080-bb">connect</a></code>(&quotient); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-bb">connect</a></code>(&product); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-bb">connect</a></code>(&sum); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-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#idp142778080-bb">connect</a></code>(&quotient); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-bb">connect</a></code>(&product); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-bb">connect</a></code>(&sum); | |
| sig.<code class="computeroutput"><a class="link" href="../boost/signalN.html#idp142778080-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="idp419237648"></a>Connection Management</h3></div></div></div> | |
| <div class="toc"><dl class="toc"> | |
| <dt><span class="section"><a href="tutorial.html#idp419238192">Disconnecting Slots (Beginner)</a></span></dt> | |
| <dt><span class="section"><a href="tutorial.html#idp419252400">Blocking Slots (Beginner)</a></span></dt> | |
| <dt><span class="section"><a href="tutorial.html#idp419261488">Scoped connections (Intermediate)</a></span></dt> | |
| <dt><span class="section"><a href="tutorial.html#idp419267088">Disconnecting equivalent slots (Intermediate)</a></span></dt> | |
| <dt><span class="section"><a href="tutorial.html#idp419276496">Automatic connection management (Intermediate)</a></span></dt> | |
| <dt><span class="section"><a href="tutorial.html#idp419300112">When can disconnections occur? (Intermediate)</a></span></dt> | |
| <dt><span class="section"><a href="tutorial.html#idp419307600">Passing slots (Intermediate)</a></span></dt> | |
| </dl></div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="idp419238192"></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#idp148223824-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#idp205515392-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#idp142778080-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="idp419252400"></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#idp142778080-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="idp419261488"></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#idp142778080-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="idp419267088"></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#idp211132960-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="idp419276496"></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#idp142778080-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="idp419300112"></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" style="list-style-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="idp419307600"></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#idp142778080-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#idp142778080-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="idp419324768"></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="idp419339952"></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"></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> |