Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/doc/html/signals/tutorial.html @ 12

Last change on this file since 12 was 12, checked in by landauf, 18 years ago

added boost
File size: 48.7 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Tutorial</title>
5<link rel="stylesheet" href="../boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
7<link rel="start" href="../index.html" title="The Boost C++ Libraries">
8<link rel="up" href="../signals.html" title="Chapter 9. Boost.Signals">
9<link rel="prev" href="../signals.html" title="Chapter 9. Boost.Signals">
10<link rel="next" href="reference.html" title="Reference">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13<table cellpadding="2" width="100%">
14<td valign="top"><img alt="boost.png (6897 bytes)" width="277" height="86" src="../../../boost.png"></td>
15<td align="center"><a href="../../../index.htm">Home</a></td>
16<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
17<td align="center"><a href="../../../people/people.htm">People</a></td>
18<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
19<td align="center"><a href="../../../more/index.htm">More</a></td>
20</table>
21<hr>
22<div class="spirit-nav">
23<a accesskey="p" href="../signals.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../images/next.png" alt="Next"></a>
24</div>
25<div class="section" lang="en">
26<div class="titlepage"><div><div><h3 class="title">
27<a name="signals.tutorial"></a>Tutorial</h3></div></div></div>
28<div class="toc"><dl>
29<dt><span class="section"><a href="tutorial.html#id2731274">How to Read this Tutorial</a></span></dt>
30<dt><span class="section"><a href="tutorial.html#id2731333">Compatibility Note</a></span></dt>
31<dt><span class="section"><a href="tutorial.html#id2731417">Hello, World! (Beginner)</a></span></dt>
32<dt><span class="section"><a href="tutorial.html#id2731552">Calling multiple slots</a></span></dt>
33<dt><span class="section"><a href="tutorial.html#id2731908">Passing values to and from slots</a></span></dt>
34<dt><span class="section"><a href="tutorial.html#id2732772">Connection Management</a></span></dt>
35<dt><span class="section"><a href="tutorial.html#id2733461">Example: Document-View</a></span></dt>
36<dt><span class="section"><a href="tutorial.html#id2733607">Linking against the Signals library</a></span></dt>
37</dl></div>
38<div class="section" lang="en">
39<div class="titlepage"><div><div><h4 class="title">
40<a name="id2731274"></a>How to Read this Tutorial</h4></div></div></div>
41<p>This tutorial is not meant to be read linearly. Its top-level
42structure roughly separates different concepts in the library
43(e.g., handling calling multiple slots, passing values to and from
44slots) and in each of these concepts the basic ideas are presented
45first and then more complex uses of the library are described
46later. Each of the sections is marked <span class="emphasis"><em>Beginner</em></span>,
47<span class="emphasis"><em>Intermediate</em></span>, or <span class="emphasis"><em>Advanced</em></span> to help guide the
48reader. The <span class="emphasis"><em>Beginner</em></span> sections include information that all
49library users should know; one can make good use of the Signals
50library after having read only the <span class="emphasis"><em>Beginner</em></span> sections. The
51<span class="emphasis"><em>Intermediate</em></span> sections build on the <span class="emphasis"><em>Beginner</em></span>
52sections with slightly more complex uses of the library. Finally,
53the <span class="emphasis"><em>Advanced</em></span> sections detail very advanced uses of the
54Signals library, that often require a solid working knowledge of
55the <span class="emphasis"><em>Beginner</em></span> and <span class="emphasis"><em>Intermediate</em></span> topics; most users
56will not need to read the <span class="emphasis"><em>Advanced</em></span> sections.</p>
57</div>
58<div class="section" lang="en">
59<div class="titlepage"><div><div><h4 class="title">
60<a name="id2731333"></a>Compatibility Note</h4></div></div></div>
61<p>Boost.Signals has two syntactical forms: the preferred form and
62the compatibility form. The preferred form fits more closely with the
63C++ language and reduces the number of separate template parameters
64that need to be considered, often improving readability; however, the
65preferred form is not supported on all platforms due to compiler
66bugs. The compatible form will work on all compilers supported by
67Boost.Signals. Consult the table below to determine which syntactic
68form to use for your compiler. Users of Boost.Function, please note
69that the preferred syntactic form in Signals is equivalent to that of
70Function's preferred syntactic form.</p>
71<p>If your compiler does not appear in this list, please try the
72preferred syntax and report your results to the Boost list so that
73we can keep this table up-to-date.</p>
74<div class="informaltable"><table class="table">
75<colgroup>
76<col>
77<col>
78</colgroup>
79<thead><tr>
80<th align="left">Preferred syntax</th>
81<th align="left">Portable syntax</th>
82</tr></thead>
83<tbody><tr>
84<td align="left"><div class="itemizedlist"><ul type="disc">
85<li><p>GNU C++ 2.95.x, 3.0.x, 3.1.x</p></li>
86<li><p>Comeau C++ 4.2.45.2</p></li>
87<li><p>SGI MIPSpro 7.3.0</p></li>
88<li><p>Intel C++ 5.0, 6.0</p></li>
89<li><p>Compaq's cxx 6.2</p></li>
90<li><p>Microsoft Visual C++ 7.1</p></li>
91</ul></div></td>
92<td align="left"><div class="itemizedlist"><ul type="disc">
93<li><p><span class="emphasis"><em>Any compiler supporting the preferred syntax</em></span></p></li>
94<li><p>Microsoft Visual C++ 6.0, 7.0</p></li>
95<li><p>Borland C++ 5.5.1</p></li>
96<li><p>Sun WorkShop 6 update 2 C++ 5.3</p></li>
97<li><p>Metrowerks CodeWarrior 8.1</p></li>
98</ul></div></td>
99</tr></tbody>
100</table></div>
101</div>
102<div class="section" lang="en">
103<div class="titlepage"><div><div><h4 class="title">
104<a name="id2731417"></a>Hello, World! (Beginner)</h4></div></div></div>
105<p>The following example writes "Hello, World!" using signals and
106slots. First, we create a signal <code class="computeroutput">sig</code>, a signal that
107takes no arguments and has a void return value. Next, we connect
108the <code class="computeroutput">hello</code> function object to the signal using the
109<code class="computeroutput">connect</code> method. Finally, use the signal
110<code class="computeroutput">sig</code> like a function to call the slots, which in turns
111invokes <code class="computeroutput">HelloWorld::operator()</code> to print "Hello,
112World!".</p>
113<div class="informaltable"><table class="table">
114<colgroup>
115<col>
116<col>
117</colgroup>
118<thead><tr>
119<th align="left">Preferred syntax</th>
120<th align="left">Portable syntax</th>
121</tr></thead>
122<tbody><tr>
123<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">
124struct HelloWorld
125{
126  void operator()() const
127  {
128    std::cout &lt;&lt; "Hello, World!" &lt;&lt; std::endl;
129  }
130};
131
132// ...
133
134// Signal with no arguments and a void return value
135<code class="computeroutput"><a href="../signal.html" title="Class template signal">boost::signal</a></code>&lt;void ()&gt; sig;
136
137// Connect a HelloWorld slot
138HelloWorld hello;
139sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(hello);
140
141// Call all of the slots
142sig();
143</pre></td>
144<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">
145struct HelloWorld
146{
147  void operator()() const
148  {
149    std::cout &lt;&lt; "Hello, World!" &lt;&lt; std::endl;
150  }
151};
152
153// ...
154
155// Signal with no arguments and a void return value
156<code class="computeroutput"><a href="../signalN.html" title="Class template signalN">boost::signal0</a></code>&lt;void&gt; sig;
157
158// Connect a HelloWorld slot
159HelloWorld hello;
160sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(hello);
161
162// Call all of the slots
163sig();
164</pre></td>
165</tr></tbody>
166</table></div>
167</div>
168<div class="section" lang="en">
169<div class="titlepage"><div><div><h4 class="title">
170<a name="id2731552"></a>Calling multiple slots</h4></div></div></div>
171<div class="toc"><dl>
172<dt><span class="section"><a href="tutorial.html#id2731556">Connecting multiple slots (Beginner)</a></span></dt>
173<dt><span class="section"><a href="tutorial.html#id2731712">Ordering slot call groups (Intermediate)</a></span></dt>
174</dl></div>
175<div class="section" lang="en">
176<div class="titlepage"><div><div><h5 class="title">
177<a name="id2731556"></a>Connecting multiple slots (Beginner)</h5></div></div></div>
178<p>Calling a single slot from a signal isn't very interesting, so
179we can make the Hello, World program more interesting by splitting
180the work of printing "Hello, World!" into two completely separate
181slots. The first slot will print "Hello" and may look like
182this:</p>
183<pre class="programlisting">
184struct Hello
185{
186  void operator()() const
187  {
188    std::cout &lt;&lt; "Hello";
189  }
190};
191</pre>
192<p>The second slot will print ", World!" and a newline, to complete
193the program. The second slot may look like this:</p>
194<pre class="programlisting">
195struct World
196{
197  void operator()() const
198  {
199    std::cout &lt;&lt; ", World!" &lt;&lt; std::endl;
200  }
201};
202</pre>
203<p>Like in our previous example, we can create a signal
204<code class="computeroutput">sig</code> that takes no arguments and has a
205<code class="computeroutput">void</code> return value. This time, we connect both a
206<code class="computeroutput">hello</code> and a <code class="computeroutput">world</code> slot to the same
207signal, and when we call the signal both slots will be called.</p>
208<div class="informaltable"><table class="table">
209<colgroup>
210<col>
211<col>
212</colgroup>
213<thead><tr>
214<th align="left">Preferred syntax</th>
215<th align="left">Portable syntax</th>
216</tr></thead>
217<tbody><tr>
218<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../signal.html" title="Class template signal">boost::signal</a></code>&lt;void ()&gt; sig;
219
220sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(Hello());
221sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(World());
222
223sig();
224</pre></td>
225<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../signalN.html" title="Class template signalN">boost::signal0</a></code>&lt;void&gt; sig;
226
227sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(Hello());
228sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(World());
229
230sig();
231</pre></td>
232</tr></tbody>
233</table></div>
234<p>By default, slots are called in first-in first-out (FIFO) order,
235so the output of this program will be as expected:</p>
236<pre class="programlisting">
237Hello, World!
238</pre>
239</div>
240<div class="section" lang="en">
241<div class="titlepage"><div><div><h5 class="title">
242<a name="id2731712"></a>Ordering slot call groups (Intermediate)</h5></div></div></div>
243<p>Slots are free to have side effects, and that can mean that some
244slots will have to be called before others even if they are not connected in that order. The Boost.Signals
245library allows slots to be placed into groups that are ordered in
246some way. For our Hello, World program, we want "Hello" to be
247printed before ", World!", so we put "Hello" into a group that must
248be executed before the group that ", World!" is in. To do this, we
249can supply an extra parameter at the beginning of the
250<code class="computeroutput">connect</code> call that specifies the group. Group values
251are, by default, <code class="computeroutput">int</code>s, and are ordered by the integer
252&lt; relation. Here's how we construct Hello, World:</p>
253<div class="informaltable"><table class="table">
254<colgroup>
255<col>
256<col>
257</colgroup>
258<thead><tr>
259<th align="left">Preferred syntax</th>
260<th align="left">Portable syntax</th>
261</tr></thead>
262<tbody><tr>
263<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../signal.html" title="Class template signal">boost::signal</a></code>&lt;void ()&gt; sig;
264sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(1, World());
265sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(0, Hello());
266sig();
267</pre></td>
268<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../signalN.html" title="Class template signalN">boost::signal0</a></code>&lt;void&gt; sig;
269sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(1, World());
270sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(0, Hello());
271sig();
272</pre></td>
273</tr></tbody>
274</table></div>
275<p>This program will correctly print "Hello, World!", because the
276<code class="computeroutput">Hello</code> object is in group 0, which precedes group 1 where
277the <code class="computeroutput">World</code> object resides. The group
278parameter is, in fact, optional. We omitted it in the first Hello,
279World example because it was unnecessary when all of the slots are
280independent. So what happens if we mix calls to connect that use the
281group parameter and those that don't? The "unnamed" slots (i.e., those
282that have been connected without specifying a group name) can be
283placed at the front or back of the slot list (by passing
284<code class="computeroutput">boost::signals::at_front</code> or <code class="computeroutput">boost::signals::at_back</code>
285as the last parameter to <code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>, respectively), and defaults to the end of the list. When
286a group is specified, the final parameter describes where the slot
287will be placed within the group ordering. If we add a new slot
288to our example like this:</p>
289<pre class="programlisting">
290struct GoodMorning
291{
292  void operator()() const
293  {
294    std::cout &lt;&lt; "... and good morning!" &lt;&lt; std::endl;
295  }
296};
297
298sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(GoodMorning());
299</pre>
300<p>... we will get the result we wanted:</p>
301<pre class="programlisting">
302Hello, World!
303... and good morning!
304</pre>
305</div>
306</div>
307<div class="section" lang="en">
308<div class="titlepage"><div><div><h4 class="title">
309<a name="id2731908"></a>Passing values to and from slots</h4></div></div></div>
310<div class="toc"><dl>
311<dt><span class="section"><a href="tutorial.html#id2731912">Slot Arguments (Beginner)</a></span></dt>
312<dt><span class="section"><a href="tutorial.html#id2732146">Signal Return Values (Advanced)</a></span></dt>
313</dl></div>
314<div class="section" lang="en">
315<div class="titlepage"><div><div><h5 class="title">
316<a name="id2731912"></a>Slot Arguments (Beginner)</h5></div></div></div>
317<p>Signals can propagate arguments to each of the slots they call.
318For instance, a signal that propagates mouse motion events might
319want to pass along the new mouse coordinates and whether the mouse
320buttons are pressed.</p>
321<p>As an example, we'll create a signal that passes two
322<code class="computeroutput">float</code> arguments to its slots. Then we'll create a few
323slots that print the results of various arithmetic operations on
324these values.</p>
325<pre class="programlisting">
326void print_sum(float x, float y)
327{
328  std::cout &lt;&lt; "The sum is " &lt;&lt; x+y &lt;&lt; std::endl;
329}
330
331void print_product(float x, float y)
332{
333  std::cout &lt;&lt; "The product is " &lt;&lt; x*y &lt;&lt; std::endl;
334}
335
336void print_difference(float x, float y)
337{
338  std::cout &lt;&lt; "The difference is " &lt;&lt; x-y &lt;&lt; std::endl;
339}
340
341void print_quotient(float x, float y)
342{
343  std::cout &lt;&lt; "The quotient is " &lt;&lt; x/y &lt;&lt; std::endl;
344}
345</pre>
346<div class="informaltable"><table class="table">
347<colgroup>
348<col>
349<col>
350</colgroup>
351<thead><tr>
352<th align="left">Preferred syntax</th>
353<th align="left">Portable syntax</th>
354</tr></thead>
355<tbody><tr>
356<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../signal.html" title="Class template signal">boost::signal</a></code>&lt;void (float, float)&gt; sig;
357
358sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;print_sum);
359sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;print_product);
360sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;print_difference);
361sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;print_quotient);
362
363sig(5, 3);
364</pre></td>
365<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../signalN.html" title="Class template signalN">boost::signal2</a></code>&lt;void, float, float&gt; sig;
366
367sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;print_sum);
368sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;print_product);
369sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;print_difference);
370sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;print_quotient);
371
372sig(5, 3);
373</pre></td>
374</tr></tbody>
375</table></div>
376<p>This program will print out the following:</p>
377<pre class="programlisting">
378The sum is 8
379The difference is 2
380The product is 15
381The quotient is 1.66667
382</pre>
383<p>So any values that are given to <code class="computeroutput">sig</code> when it is
384called like a function are passed to each of the slots. We have to
385declare the types of these values up front when we create the
386signal. The type <code class="computeroutput"><a href="../signal.html" title="Class template signal">boost::signal</a>&lt;void (float,
387float)&gt;</code> means that the signal has a <code class="computeroutput">void</code>
388return value and takes two <code class="computeroutput">float</code> values. Any slot
389connected to <code class="computeroutput">sig</code> must therefore be able to take two
390<code class="computeroutput">float</code> values.</p>
391</div>
392<div class="section" lang="en">
393<div class="titlepage"><div><div><h5 class="title">
394<a name="id2732146"></a>Signal Return Values (Advanced)</h5></div></div></div>
395<p>Just as slots can receive arguments, they can also return
396values. These values can then be returned back to the caller of the
397signal through a <em class="firstterm">combiner</em>. The combiner is a mechanism
398that can take the results of calling slots (there many be no
399results or a hundred; we don't know until the program runs) and
400coalesces them into a single result to be returned to the caller.
401The single result is often a simple function of the results of the
402slot calls: the result of the last slot call, the maximum value
403returned by any slot, or a container of all of the results are some
404possibilities.</p>
405<p>We can modify our previous arithmetic operations example
406slightly so that the slots all return the results of computing the
407product, quotient, sum, or difference. Then the signal itself can
408return a value based on these results to be printed:</p>
409<div class="informaltable"><table class="table">
410<colgroup>
411<col>
412<col>
413</colgroup>
414<thead><tr>
415<th align="left">Preferred syntax</th>
416<th align="left">Portable syntax</th>
417</tr></thead>
418<tbody><tr>
419<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">
420float product(float x, float y) { return x*y; }
421float quotient(float x, float y) { return x/y; }
422float sum(float x, float y) { return x+y; }
423float difference(float x, float y) { return x-y; }
424
425<code class="computeroutput"><a href="../signal.html" title="Class template signal">boost::signal</a></code>&lt;float (float x, float y)&gt; sig;
426
427sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;product);
428sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;quotient);
429sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;sum);
430sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;difference);
431
432std::cout &lt;&lt; sig(5, 3) &lt;&lt; std::endl;
433</pre></td>
434<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">
435float product(float x, float y) { return x*y; }
436float quotient(float x, float y) { return x/y; }
437float sum(float x, float y) { return x+y; }
438float difference(float x, float y) { return x-y; }
439
440<code class="computeroutput"><a href="../signalN.html" title="Class template signalN">boost::signal2</a></code>&lt;float, float, float&gt; sig;
441
442sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;product);
443sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;quotient);
444sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;sum);
445sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;difference);
446
447std::cout &lt;&lt; sig(5, 3) &lt;&lt; std::endl;
448</pre></td>
449</tr></tbody>
450</table></div>
451<p>This example program will output <code class="computeroutput">2</code>. This is because the
452default behavior of a signal that has a return type
453(<code class="computeroutput">float</code>, the first template argument given to the
454<code class="computeroutput"><a href="../signal.html" title="Class template signal">boost::signal</a></code> class template) is to call all slots and
455then return the result returned by the last slot called. This
456behavior is admittedly silly for this example, because slots have
457no side effects and the result is the last slot connect.</p>
458<p>A more interesting signal result would be the maximum of the
459values returned by any slot. To do this, we create a custom
460combiner that looks like this:</p>
461<pre class="programlisting">
462template&lt;typename T&gt;
463struct maximum
464{
465  typedef T result_type;
466
467  template&lt;typename InputIterator&gt;
468  T operator()(InputIterator first, InputIterator last) const
469  {
470    // If there are no slots to call, just return the
471    // default-constructed value
472    if (first == last)
473      return T();
474
475    T max_value = *first++;
476    while (first != last) {
477      if (max_value &lt; *first)
478        max_value = *first;
479      ++first;
480    }
481 
482    return max_value;
483  }
484};
485</pre>
486<p>The <code class="computeroutput">maximum</code> class template acts as a function
487object. Its result type is given by its template parameter, and
488this is the type it expects to be computing the maximum based on
489(e.g., <code class="computeroutput">maximum&lt;float&gt;</code> would find the maximum
490<code class="computeroutput">float</code> in a sequence of <code class="computeroutput">float</code>s). When a
491<code class="computeroutput">maximum</code> object is invoked, it is given an input
492iterator sequence <code class="computeroutput">[first, last)</code> that includes the
493results of calling all of the slots. <code class="computeroutput">maximum</code> uses this
494input iterator sequence to calculate the maximum element, and
495returns that maximum value.</p>
496<p>We actually use this new function object type by installing it
497as a combiner for our signal. The combiner template argument
498follows the signal's calling signature:</p>
499<div class="informaltable"><table class="table">
500<colgroup>
501<col>
502<col>
503</colgroup>
504<thead><tr>
505<th align="left">Preferred syntax</th>
506<th align="left">Portable syntax</th>
507</tr></thead>
508<tbody><tr>
509<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../signal.html" title="Class template signal">boost::signal</a></code>&lt;float (float x, float y),
510              maximum&lt;float&gt; &gt; sig;
511</pre></td>
512<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../signalN.html" title="Class template signalN">boost::signal2</a></code>&lt;float, float, float,
513               maximum&lt;float&gt; &gt; sig;
514</pre></td>
515</tr></tbody>
516</table></div>
517<p>Now we can connect slots that perform arithmetic functions and
518use the signal:</p>
519<pre class="programlisting">
520sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;quotient);
521sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;product);
522sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;sum);
523sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;difference);
524
525std::cout &lt;&lt; sig(5, 3) &lt;&lt; std::endl;
526</pre>
527<p>The output of this program will be <code class="computeroutput">15</code>, because
528regardless of the order in which the slots are connected, the product
529of 5 and 3 will be larger than the quotient, sum, or
530difference.</p>
531<p>In other cases we might want to return all of the values
532computed by the slots together, in one large data structure. This
533is easily done with a different combiner:</p>
534<pre class="programlisting">
535template&lt;typename Container&gt;
536struct aggregate_values
537{
538  typedef Container result_type;
539
540  template&lt;typename InputIterator&gt;
541  Container operator()(InputIterator first, InputIterator last) const
542  {
543    return Container(first, last);
544  }
545};
546</pre>
547<p>
548Again, we can create a signal with this new combiner:
549</p>
550<div class="informaltable"><table class="table">
551<colgroup>
552<col>
553<col>
554</colgroup>
555<thead><tr>
556<th align="left">Preferred syntax</th>
557<th align="left">Portable syntax</th>
558</tr></thead>
559<tbody><tr>
560<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../signal.html" title="Class template signal">boost::signal</a></code>&lt;float (float, float),
561    aggregate_values&lt;std::vector&lt;float&gt; &gt; &gt; sig;
562
563sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;quotient);
564sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;product);
565sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;sum);
566sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;difference);
567
568std::vector&lt;float&gt; results = sig(5, 3);
569std::copy(results.begin(), results.end(),
570    std::ostream_iterator&lt;float&gt;(cout, " "));
571</pre></td>
572<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><code class="computeroutput"><a href="../signalN.html" title="Class template signalN">boost::signal2</a></code>&lt;float, float, float,
573    aggregate_values&lt;std::vector&lt;float&gt; &gt; &gt; sig;
574
575sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;quotient);
576sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;product);
577sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;sum);
578sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(&amp;difference);
579
580std::vector&lt;float&gt; results = sig(5, 3);
581std::copy(results.begin(), results.end(),
582    std::ostream_iterator&lt;float&gt;(cout, " "));
583</pre></td>
584</tr></tbody>
585</table></div>
586<p>The output of this program will contain 15, 8, 1.6667, and 2. It
587is interesting here that
588the first template argument for the <code class="computeroutput">signal</code> class,
589<code class="computeroutput">float</code>, is not actually the return type of the signal.
590Instead, it is the return type used by the connected slots and will
591also be the <code class="computeroutput">value_type</code> of the input iterators passed
592to the combiner. The combiner itself is a function object and its
593<code class="computeroutput">result_type</code> member type becomes the return type of the
594signal.</p>
595<p>The input iterators passed to the combiner transform dereference
596operations into slot calls. Combiners therefore have the option to
597invoke only some slots until some particular criterion is met. For
598instance, in a distributed computing system, the combiner may ask
599each remote system whether it will handle the request. Only one
600remote system needs to handle a particular request, so after a
601remote system accepts the work we do not want to ask any other
602remote systems to perform the same task. Such a combiner need only
603check the value returned when dereferencing the iterator, and
604return when the value is acceptable. The following combiner returns
605the first non-NULL pointer to a <code class="computeroutput">FulfilledRequest</code> data
606structure, without asking any later slots to fulfill the
607request:</p>
608<pre class="programlisting">
609struct DistributeRequest {
610  typedef FulfilledRequest* result_type;
611
612  template&lt;typename InputIterator&gt;
613  result_type operator()(InputIterator first, InputIterator last) const
614  {
615    while (first != last) {
616      if (result_type fulfilled = *first)
617        return fulfilled;
618      ++first;
619    }
620    return 0;
621  }
622};
623</pre>
624</div>
625</div>
626<div class="section" lang="en">
627<div class="titlepage"><div><div><h4 class="title">
628<a name="id2732772"></a>Connection Management</h4></div></div></div>
629<div class="toc"><dl>
630<dt><span class="section"><a href="tutorial.html#id2732775">Disconnecting Slots (Beginner)</a></span></dt>
631<dt><span class="section"><a href="tutorial.html#id2732896">Blocking Slots (Beginner)</a></span></dt>
632<dt><span class="section"><a href="tutorial.html#id2732970">Scoped connections (Intermediate)</a></span></dt>
633<dt><span class="section"><a href="tutorial.html#id2733016">Disconnecting equivalent slots (Intermediate)</a></span></dt>
634<dt><span class="section"><a href="tutorial.html#id2733076">Automatic connection management (Intermediate)</a></span></dt>
635<dt><span class="section"><a href="tutorial.html#id2733266">When can disconnections occur? (Intermediate)</a></span></dt>
636<dt><span class="section"><a href="tutorial.html#id2733327">Passing slots (Intermediate)</a></span></dt>
637</dl></div>
638<div class="section" lang="en">
639<div class="titlepage"><div><div><h5 class="title">
640<a name="id2732775"></a>Disconnecting Slots (Beginner)</h5></div></div></div>
641<p>Slots aren't expected to exist indefinately after they are
642connected. Often slots are only used to receive a few events and
643are then disconnected, and the programmer needs control to decide
644when a slot should no longer be connected.</p>
645<p>The entry point for managing connections explicitly is the
646<code class="computeroutput"><a href="../connection.html" title="Class connection">boost::signals::connection</a></code> class. The
647<code class="computeroutput"><a href="../connection.html" title="Class connection">connection</a></code> class uniquely represents the connection
648between a particular signal and a particular slot. The
649<code class="computeroutput"><a href="../connection.html#id2558732-bb">connected</a>()</code> method checks if the signal and slot are
650still connected, and the <code class="computeroutput"><a href="../connection.html#id2558792-bb">disconnect()</a></code> method
651disconnects the signal and slot if they are connected before it is
652called. Each call to the signal's <code class="computeroutput">connect()</code> method
653returns a connection object, which can be used to determine if the
654connection still exists or to disconnect the signal and slot.</p>
655<pre class="programlisting">
656boost::signals::connection c = sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(HelloWorld());
657if (c.<code class="computeroutput">connected</code>()) {
658<span class="emphasis"><em>// c is still connected to the signal</em></span>
659  sig(); <span class="emphasis"><em>// Prints "Hello, World!"</em></span>
660}
661
662c.disconnect(); <span class="emphasis"><em>// Disconnect the HelloWorld object</em></span>
663assert(!c.<code class="computeroutput">connected</code>()); <span class="emphasis"><em>c isn't connected any more</em></span>
664
665sig(); <span class="emphasis"><em>// Does nothing: there are no connected slots</em></span></pre>
666</div>
667<div class="section" lang="en">
668<div class="titlepage"><div><div><h5 class="title">
669<a name="id2732896"></a>Blocking Slots (Beginner)</h5></div></div></div>
670<p>Slots can be temporarily "blocked", meaning that they will be
671ignored when the signal is invoked but have not been disconnected. The
672<code class="computeroutput">block</code> member function
673temporarily blocks a slot, which can be unblocked via
674<code class="computeroutput">unblock</code>. Here is an example of
675blocking/unblocking slots:</p>
676<pre class="programlisting">
677boost::signals::connection c = sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(HelloWorld());
678sig(); <span class="emphasis"><em>// Prints "Hello, World!"</em></span>
679
680c.<code class="computeroutput">block</code>(); <span class="emphasis"><em>// block the slot</em></span>
681assert(c.<code class="computeroutput">blocked</code>());
682sig(); <span class="emphasis"><em>// No output: the slot is blocked</em></span>
683
684c.<code class="computeroutput">unblock</code>(); <span class="emphasis"><em>// unblock the slot</em></span>
685sig(); <span class="emphasis"><em>// Prints "Hello, World!"</em></span></pre>
686</div>
687<div class="section" lang="en">
688<div class="titlepage"><div><div><h5 class="title">
689<a name="id2732970"></a>Scoped connections (Intermediate)</h5></div></div></div>
690<p>The <code class="computeroutput">boost::signals::scoped_connection</code> class
691references a signal/slot connection that will be disconnected when
692the <code class="computeroutput">scoped_connection</code> class goes out of scope. This
693ability is useful when a connection need only be temporary,
694e.g.,</p>
695<pre class="programlisting">
696{
697  boost::signals::scoped_connection c = sig.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(ShortLived());
698  sig(); <span class="emphasis"><em>// will call ShortLived function object</em></span>
699}
700sig(); <span class="emphasis"><em>// ShortLived function object no longer connected to sig</em></span></pre>
701</div>
702<div class="section" lang="en">
703<div class="titlepage"><div><div><h5 class="title">
704<a name="id2733016"></a>Disconnecting equivalent slots (Intermediate)</h5></div></div></div>
705<p>One can disconnect slots that are equivalent to a given function
706object using a form of the
707<code class="computeroutput"><a href="../signalN.html#id2582644-bb">disconnect</a></code> method, so long as
708the type of the function object has an accessible <code class="computeroutput">==</code>
709operator. For instance:
710
711</p>
712<div class="informaltable"><table class="table">
713<colgroup>
714<col>
715<col>
716</colgroup>
717<thead><tr>
718<th align="left">Preferred syntax</th>
719<th align="left">Portable syntax</th>
720</tr></thead>
721<tbody><tr>
722<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">
723void foo();
724void bar();
725
726signal&lt;void()&gt; sig;
727
728sig.connect(&amp;foo);
729sig.connect(&amp;bar);
730
731// disconnects foo, but not bar
732sig.disconnect(&amp;foo);
733</pre></td>
734<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">
735void foo();
736void bar();
737
738signal0&lt;void&gt; sig;
739
740sig.connect(&amp;foo);
741sig.connect(&amp;bar);
742
743// disconnects foo, but not bar
744sig.disconnect(&amp;foo);
745</pre></td>
746</tr></tbody>
747</table></div>
748</div>
749<div class="section" lang="en">
750<div class="titlepage"><div><div><h5 class="title">
751<a name="id2733076"></a>Automatic connection management (Intermediate)</h5></div></div></div>
752<p>Boost.Signals can automatically track the lifetime of objects
753involved in signal/slot connections, including automatic
754disconnection of slots when objects involved in the slot call are
755destroyed. For instance, consider a simple news delivery service,
756where clients connect to a news provider that then sends news to
757all connected clients as information arrives. The news delivery
758service may be constructed like this: </p>
759<div class="informaltable"><table class="table">
760<colgroup>
761<col>
762<col>
763</colgroup>
764<thead><tr>
765<th align="left">Preferred syntax</th>
766<th align="left">Portable syntax</th>
767</tr></thead>
768<tbody><tr>
769<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">
770class NewsItem { /* ... */ };
771
772boost::signal&lt;void (const NewsItem&amp;)&gt; deliverNews;
773</pre></td>
774<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">
775class NewsItem { /* ... */ };
776
777boost::signal1&lt;void, const NewsItem&amp;&gt; deliverNews;
778</pre></td>
779</tr></tbody>
780</table></div>
781<p>Clients that wish to receive news updates need only connect a
782function object that can receive news items to the
783<code class="computeroutput">deliverNews</code> signal. For instance, we may have a
784special message area in our application specifically for news,
785e.g.,:</p>
786<pre class="programlisting">
787struct NewsMessageArea : public MessageArea
788{
789public:
790  // ...
791
792  void displayNews(const NewsItem&amp; news) const
793  {
794    messageText = news.text();
795    update();
796  }
797};
798
799// ...
800NewsMessageArea newsMessageArea = new NewsMessageArea(/* ... */);
801// ...
802deliverNews.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(boost::bind(&amp;NewsMessageArea::displayNews,
803                                newsMessageArea, _1));
804</pre>
805<p>However, what if the user closes the news message area,
806destroying the <code class="computeroutput">newsMessageArea</code> object that
807<code class="computeroutput">deliverNews</code> knows about? Most likely, a segmentation
808fault will occur. However, with Boost.Signals one need only make
809<code class="computeroutput">NewsMessageArea</code><span class="emphasis"><em>trackable</em></span>, and the slot
810involving <code class="computeroutput">newsMessageArea</code> will be disconnected when
811<code class="computeroutput">newsMessageArea</code> is destroyed. The
812<code class="computeroutput">NewsMessageArea</code> class is made trackable by deriving
813publicly from the <code class="computeroutput">boost::signals::trackable</code> class,
814e.g.:</p>
815<pre class="programlisting">
816struct NewsMessageArea : public MessageArea, public boost::signals::trackable
817{
818  // ...
819};
820</pre>
821<p>At this time there is a significant limitation to the use of
822<code class="computeroutput">trackable</code> objects in making slot connections: function
823objects built using Boost.Bind are understood, such that pointers
824or references to <code class="computeroutput">trackable</code> objects passed to
825<code class="computeroutput">boost::bind</code> will be found and tracked.</p>
826<p><span class="bold"><strong>Warning</strong></span>: User-defined function objects and function
827objects from other libraries (e.g., Boost.Function or Boost.Lambda)
828do not implement the required interfaces for <code class="computeroutput">trackable</code>
829object detection, and <span class="emphasis"><em>will silently ignore any bound trackable
830objects</em></span>. Future versions of the Boost libraries will address
831this limitation.</p>
832</div>
833<div class="section" lang="en">
834<div class="titlepage"><div><div><h5 class="title">
835<a name="id2733266"></a>When can disconnections occur? (Intermediate)</h5></div></div></div>
836<p>Signal/slot disconnections occur when any of these conditions
837occur:</p>
838<div class="itemizedlist"><ul type="disc">
839<li><p>The connection is explicitly disconnected via the connection's
840<code class="computeroutput">disconnect</code> method directly, or indirectly via the
841signal's <code class="computeroutput">disconnect</code> method or
842<code class="computeroutput">scoped_connection</code>'s destructor.</p></li>
843<li><p>A <code class="computeroutput">trackable</code> object bound to the slot is
844destroyed.</p></li>
845<li><p>The signal is destroyed.</p></li>
846</ul></div>
847<p>These events can occur at any time without disrupting a signal's
848calling sequence. If a signal/slot connection is disconnected at
849any time during a signal's calling sequence, the calling sequence
850will still continue but will not invoke the disconnected slot.
851Additionally, a signal may be destroyed while it is in a calling
852sequence, and which case it will complete its slot call sequence
853but may not be accessed directly.</p>
854<p>Signals may be invoked recursively (e.g., a signal A calls a
855slot B that invokes signal A...). The disconnection behavior does
856not change in the recursive case, except that the slot calling
857sequence includes slot calls for all nested invocations of the
858signal.</p>
859</div>
860<div class="section" lang="en">
861<div class="titlepage"><div><div><h5 class="title">
862<a name="id2733327"></a>Passing slots (Intermediate)</h5></div></div></div>
863<p>Slots in the Boost.Signals library are created from arbitrary
864function objects, and therefore have no fixed type. However, it is
865commonplace to require that slots be passed through interfaces that
866cannot be templates. Slots can be passed via the
867<code class="computeroutput">slot_type</code> for each particular signal type and any
868function object compatible with the signature of the signal can be
869passed to a <code class="computeroutput">slot_type</code> parameter. For instance:</p>
870<div class="informaltable"><table class="table">
871<colgroup>
872<col>
873<col>
874</colgroup>
875<thead><tr>
876<th align="left">Preferred syntax</th>
877<th align="left">Portable syntax</th>
878</tr></thead>
879<tbody><tr>
880<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">
881class Button
882{
883  typedef boost::signal&lt;void (int x, int y)&gt; OnClick;
884
885public:
886  void doOnClick(const OnClick::slot_type&amp; slot);
887
888private:
889  OnClick onClick;
890};
891
892void Button::doOnClick(
893      const OnClick::slot_type&amp; slot
894    )
895{
896  onClick.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(slot);
897}
898
899void printCoordinates(long x, long y)
900{
901  std::cout &lt;&lt; "(" &lt;&lt; x &lt;&lt; ", " &lt;&lt; y &lt;&lt; ")\n";
902}
903
904void f(Button&amp; button)
905{
906  button.doOnClick(&amp;printCoordinates);
907}
908</pre></td>
909<td align="left"><pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting">
910class Button
911{
912  typedef <code class="computeroutput"><a href="../signalN.html" title="Class template signalN">boost::signal2</a></code>&lt;void,int,int&gt; OnClick;
913
914public:
915  void doOnClick(const OnClick::slot_type&amp; slot);
916
917private:
918  OnClick onClick;
919};
920
921void Button::doOnClick(
922      const OnClick::slot_type&amp; slot
923    )
924{
925  onClick.<code class="computeroutput"><a href="../signalN.html#id2551390-bb">connect</a></code>(slot);
926}
927
928void printCoordinates(long x, long y)
929{
930  std::cout &lt;&lt; "(" &lt;&lt; x &lt;&lt; ", " &lt;&lt; y &lt;&lt; ")\n";
931}
932
933void f(Button&amp; button)
934{
935  button.doOnClick(&amp;printCoordinates);
936}
937</pre></td>
938</tr></tbody>
939</table></div>
940<p>The <code class="computeroutput">doOnClick</code> method is now functionally equivalent
941to the <code class="computeroutput">connect</code> method of the <code class="computeroutput">onClick</code>
942signal, but the details of the <code class="computeroutput">doOnClick</code> method can be
943hidden in an implementation detail file.</p>
944</div>
945</div>
946<div class="section" lang="en">
947<div class="titlepage"><div><div><h4 class="title">
948<a name="id2733461"></a>Example: Document-View</h4></div></div></div>
949<p>Signals can be used to implement flexible Document-View
950  architectures. The document will contain a signal to which each of
951  the views can connect. The following <code class="computeroutput">Document</code> class
952  defines a simple text document that supports mulitple views. Note
953  that it stores a single signal to which all of the views will be
954  connected.</p>
955<pre class="programlisting">class Document
956{
957public:
958    typedef boost::signal&lt;void (bool)&gt;  signal_t;
959    typedef boost::signals::connection  connection_t;
960
961public:
962    Document()
963    {}
964
965    connection_t connect(signal_t::slot_function_type subscriber)
966    {
967        return m_sig.connect(subscriber);
968    }
969
970    void disconnect(connection_t subscriber)
971    {
972        subscriber.disconnect();
973    }
974
975    void append(const char* s)
976    {
977        m_text += s;
978        m_sig(true);
979    }
980
981    const std::string&amp; getText() const
982    {
983        return m_text;
984    }
985
986private:
987    signal_t    m_sig;
988    std::string m_text;
989};</pre>
990<p>Next, we can define a <code class="computeroutput">View</code> base class from which
991  views can derive. This isn't strictly required, but it keeps the
992  Document-View logic separate from the logic itself. Note that the
993  constructor just connects the view to the document and the
994  destructor disconnects the view.</p>
995<pre class="programlisting">
996class View
997{
998public:
999    View(Document&amp; m)
1000        : m_document(m)
1001    {
1002        m_connection = m_document.connect(boost::bind(&amp;View::refresh, this, _1));
1003    }
1004
1005    virtual ~View()
1006    {
1007        m_document.disconnect(m_connection);
1008    }
1009
1010    virtual void refresh(bool bExtended) const = 0;
1011
1012protected:
1013    Document&amp;               m_document;
1014
1015private:
1016    Document::connection_t  m_connection;
1017};
1018  </pre>
1019<p>Finally, we can begin to define views. The
1020  following <code class="computeroutput">TextView</code> class provides a simple view of the
1021    document text.</p>
1022<pre class="programlisting">class TextView : public View
1023{
1024public:
1025    TextView(Document&amp; doc)
1026        : View(doc)
1027    {}
1028
1029    virtual void refresh(bool bExtended) const
1030    {
1031        std::cout &lt;&lt; "TextView: " &lt;&lt; m_document.getText() &lt;&lt; std::endl;
1032    }
1033};</pre>
1034<p>Alternatively, we can provide a view of the document
1035    translated into hex values using the <code class="computeroutput">HexView</code>
1036    view:</p>
1037<pre class="programlisting">class HexView : public View
1038{
1039public:
1040    HexView(Document&amp; doc)
1041        : View(doc)
1042    {}
1043
1044    virtual void refresh(bool bExtended) const
1045    {
1046        const std::string&amp;  s = m_document.getText();
1047
1048        std::cout &lt;&lt; "HexView:";
1049
1050        for (std::string::const_iterator it = s.begin(); it != s.end(); ++it)
1051            std::cout &lt;&lt; ' ' &lt;&lt; std::hex &lt;&lt; static_cast&lt;int&gt;(*it);
1052
1053        std::cout &lt;&lt; std::endl;
1054    }
1055};</pre>
1056<p>To tie the example together, here is a
1057  simple <code class="computeroutput">main</code> function that sets up two views and then
1058    modifies the document:</p>
1059<pre class="programlisting">int main(int argc, char* argv[])
1060{
1061    Document    doc;
1062    TextView    v1(doc);
1063    HexView     v2(doc);
1064
1065    doc.append(argc == 2 ? argv[1] : "Hello world!");
1066    return 0;
1067}</pre>
1068<p>The complete example source, contributed by Keith MacDonald,
1069    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>
1070</div>
1071<div class="section" lang="en">
1072<div class="titlepage"><div><div><h4 class="title">
1073<a name="id2733607"></a>Linking against the Signals library</h4></div></div></div>
1074<p>Part of the Boost.Signals library is compiled into a binary
1075  library that must be linked into your application to use Signals. To
1076  build this library, execute the command <span><strong class="command">bjam</strong></span> in
1077  either the top-level Boost directory or in
1078  <code class="computeroutput">libs/signals/build</code>. On Unix, the directory
1079  <code class="computeroutput">libs/signals/build/bin-stage</code> will then contain
1080  libraries named, e.g., <code class="computeroutput">libboost_signals.a</code> that can be
1081  linked in your program with <code class="computeroutput">-lboost_signals</code>.</p>
1082<p>On Windows, with Microsoft Visual C++ or Borland C++, the
1083  linking process is nearly automatic. As with the
1084  <a href="../../../libs/regex/index.html" target="_top">Regex</a> library, the libraries in
1085  <code class="computeroutput">libs\signals\build\bin-stage</code> will have mangled names
1086  and will be automatically be including in the link process. To link
1087  against the Signals library binary dynamically (e.g., using the
1088  Signals DLL), define <code class="computeroutput">BOOST_SIGNALS_DYN_LINK</code> when
1089  building your application; to link statically, define
1090  <code class="computeroutput">BOOST_SIGNALS_STATIC_LINK</code>. </p>
1091</div>
1092</div>
1093<table width="100%"><tr>
1094<td align="left"><small><p>Last revised: May 18, 2005 at 16:09:34 GMT</p></small></td>
1095<td align="right"><small>Copyright © 2001-2004 Douglas Gregor</small></td>
1096</tr></table>
1097<hr>
1098<div class="spirit-nav">
1099<a accesskey="p" href="../signals.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../signals.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../images/next.png" alt="Next"></a>
1100</div>
1101</body>
1102</html>
Note: See TracBrowser for help on using the repository browser.