diff options
Diffstat (limited to 'doc/html/signals2/tutorial.html')
| -rw-r--r-- | doc/html/signals2/tutorial.html | 118 |
1 files changed, 59 insertions, 59 deletions
diff --git a/doc/html/signals2/tutorial.html b/doc/html/signals2/tutorial.html index 1e91c6fe38..b97d3af3ae 100644 --- a/doc/html/signals2/tutorial.html +++ b/doc/html/signals2/tutorial.html @@ -4,10 +4,10 @@ <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.76.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> -<link rel="up" href="../signals2.html" title="Chapter 30. Boost.Signals2"> -<link rel="prev" href="../signals2.html" title="Chapter 30. Boost.Signals2"> +<link rel="up" href="../signals2.html" title="Chapter 33. Boost.Signals2"> +<link rel="prev" href="../signals2.html" title="Chapter 33. Boost.Signals2"> <link rel="next" href="examples.html" title="Example programs"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> @@ -26,20 +26,20 @@ <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="signals2.tutorial"></a>Tutorial</h2></div></div></div> -<div class="toc"><dl> -<dt><span class="section"><a href="tutorial.html#idp394522480">How to Read this Tutorial</a></span></dt> -<dt><span class="section"><a href="tutorial.html#idp394529264">Hello, World! (Beginner)</a></span></dt> -<dt><span class="section"><a href="tutorial.html#idp394536896">Calling Multiple Slots</a></span></dt> -<dt><span class="section"><a href="tutorial.html#idp394564960">Passing Values to and from Slots</a></span></dt> -<dt><span class="section"><a href="tutorial.html#idp394616720">Connection Management</a></span></dt> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="tutorial.html#idm45927784853120">How to Read this Tutorial</a></span></dt> +<dt><span class="section"><a href="tutorial.html#idm45927784846368">Hello, World! (Beginner)</a></span></dt> +<dt><span class="section"><a href="tutorial.html#idm45927784838688">Calling Multiple Slots</a></span></dt> +<dt><span class="section"><a href="tutorial.html#idm45927784810560">Passing Values to and from Slots</a></span></dt> +<dt><span class="section"><a href="tutorial.html#idm45927784758800">Connection Management</a></span></dt> <dt><span class="section"><a href="tutorial.html#signals2.tutorial.document-view">Example: Document-View</a></span></dt> <dt><span class="section"><a href="tutorial.html#signals2.tutorial.extended-slot-type">Giving a Slot Access to its Connection (Advanced)</a></span></dt> <dt><span class="section"><a href="tutorial.html#signals2.tutorial.signal-mutex-template-parameter">Changing the <code class="computeroutput">Mutex</code> Type of a Signal (Advanced).</a></span></dt> -<dt><span class="section"><a href="tutorial.html#idp394767824">Linking against the Signals2 library</a></span></dt> +<dt><span class="section"><a href="tutorial.html#idm45927784607440">Linking against the Signals2 library</a></span></dt> </dl></div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp394522480"></a>How to Read this Tutorial</h3></div></div></div> +<a name="idm45927784853120"></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 @@ -59,7 +59,7 @@ will not need to read the <span class="emphasis"><em>Advanced</em></span> sectio </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp394529264"></a>Hello, World! (Beginner)</h3></div></div></div> +<a name="idm45927784846368"></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 @@ -89,14 +89,14 @@ World!".</p> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp394536896"></a>Calling Multiple Slots</h3></div></div></div> -<div class="toc"><dl> -<dt><span class="section"><a href="tutorial.html#idp394537440">Connecting Multiple Slots (Beginner)</a></span></dt> -<dt><span class="section"><a href="tutorial.html#idp394547616">Ordering Slot Call Groups (Intermediate)</a></span></dt> +<a name="idm45927784838688"></a>Calling Multiple Slots</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="tutorial.html#idm45927784838144">Connecting Multiple Slots (Beginner)</a></span></dt> +<dt><span class="section"><a href="tutorial.html#idm45927784827968">Ordering Slot Call Groups (Intermediate)</a></span></dt> </dl></div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp394537440"></a>Connecting Multiple Slots (Beginner)</h4></div></div></div> +<a name="idm45927784838144"></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 @@ -140,7 +140,7 @@ Hello, World! </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp394547616"></a>Ordering Slot Call Groups (Intermediate)</h4></div></div></div> +<a name="idm45927784827968"></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.Signals2 library allows slots to be placed into groups that are ordered in @@ -166,7 +166,7 @@ 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::signals2::at_front</code> or <code class="computeroutput">boost::signals2::at_back</code> -as the last parameter to <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idp134764096-bb">connect</a></code>, respectively), +as the last parameter to <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idm46563209038672-bb">connect</a></code>, respectively), and default to the end of the list. When a group is specified, the final <code class="computeroutput">at_front</code> or <code class="computeroutput">at_back</code> parameter describes where the slot @@ -204,14 +204,14 @@ Hello, World! </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp394564960"></a>Passing Values to and from Slots</h3></div></div></div> -<div class="toc"><dl> -<dt><span class="section"><a href="tutorial.html#idp394565520">Slot Arguments (Beginner)</a></span></dt> -<dt><span class="section"><a href="tutorial.html#idp394578384">Signal Return Values (Advanced)</a></span></dt> +<a name="idm45927784810560"></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#idm45927784810000">Slot Arguments (Beginner)</a></span></dt> +<dt><span class="section"><a href="tutorial.html#idm45927784797136">Signal Return Values (Advanced)</a></span></dt> </dl></div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp394565520"></a>Slot Arguments (Beginner)</h4></div></div></div> +<a name="idm45927784810000"></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 @@ -272,7 +272,7 @@ connected to <code class="computeroutput">sig</code> must therefore be able to t </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp394578384"></a>Signal Return Values (Advanced)</h4></div></div></div> +<a name="idm45927784797136"></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 @@ -451,20 +451,20 @@ struct DistributeRequest { </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp394616720"></a>Connection Management</h3></div></div></div> -<div class="toc"><dl> -<dt><span class="section"><a href="tutorial.html#idp394617264">Disconnecting Slots (Beginner)</a></span></dt> -<dt><span class="section"><a href="tutorial.html#idp394626864">Blocking Slots (Beginner)</a></span></dt> -<dt><span class="section"><a href="tutorial.html#idp394633632">Scoped Connections (Intermediate)</a></span></dt> -<dt><span class="section"><a href="tutorial.html#idp394644896">Disconnecting Equivalent Slots (Intermediate)</a></span></dt> +<a name="idm45927784758800"></a>Connection Management</h3></div></div></div> +<div class="toc"><dl class="toc"> +<dt><span class="section"><a href="tutorial.html#idm45927784758256">Disconnecting Slots (Beginner)</a></span></dt> +<dt><span class="section"><a href="tutorial.html#idm45927784748720">Blocking Slots (Beginner)</a></span></dt> +<dt><span class="section"><a href="tutorial.html#idm45927784741888">Scoped Connections (Intermediate)</a></span></dt> +<dt><span class="section"><a href="tutorial.html#idm45927784730688">Disconnecting Equivalent Slots (Intermediate)</a></span></dt> <dt><span class="section"><a href="tutorial.html#signals2.tutorial.connection-management">Automatic Connection Management (Intermediate)</a></span></dt> <dt><span class="section"><a href="tutorial.html#signals2.tutorial.deconstruct">Postconstructors and Predestructors (Advanced)</a></span></dt> -<dt><span class="section"><a href="tutorial.html#idp394698368">When Can Disconnections Occur? (Intermediate)</a></span></dt> -<dt><span class="section"><a href="tutorial.html#idp394705968">Passing Slots (Intermediate)</a></span></dt> +<dt><span class="section"><a href="tutorial.html#idm45927784677088">When Can Disconnections Occur? (Intermediate)</a></span></dt> +<dt><span class="section"><a href="tutorial.html#idm45927784669488">Passing Slots (Intermediate)</a></span></dt> </dl></div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp394617264"></a>Disconnecting Slots (Beginner)</h4></div></div></div> +<a name="idm45927784758256"></a>Disconnecting Slots (Beginner)</h4></div></div></div> <p>Slots aren't expected to exist indefinitely 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 @@ -473,8 +473,8 @@ when a slot should no longer be connected.</p> <code class="computeroutput"><a class="link" href="../boost/signals2/connection.html" title="Class connection">boost::signals2::connection</a></code> class. The <code class="computeroutput">connection</code> class uniquely represents the connection between a particular signal and a particular slot. The -<code class="computeroutput"><a class="link" href="../boost/signals2/connection.html#idp200558704-bb">connected</a>()</code> method checks if the signal and slot are -still connected, and the <code class="computeroutput"><a class="link" href="../boost/signals2/connection.html#idp38334944-bb">disconnect()</a></code> method +<code class="computeroutput"><a class="link" href="../boost/signals2/connection.html#idm46563209460720-bb">connected</a>()</code> method checks if the signal and slot are +still connected, and the <code class="computeroutput"><a class="link" href="../boost/signals2/connection.html#idm46563209465584-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 @@ -490,7 +490,7 @@ connection still exists or to disconnect the signal and slot.</p> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp394626864"></a>Blocking Slots (Beginner)</h4></div></div></div> +<a name="idm45927784748720"></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 permanently disconnected. This is typically used to prevent infinite recursion in cases where @@ -499,7 +499,7 @@ invoked again. A <code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html" title="Class shared_connection_block">boost::signals2::shared_connection_block</a></code> object will temporarily block a slot. The connection is unblocked by either destroying or calling -<code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html#idp82434720-bb">unblock</a></code> +<code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html#idm46563209120112-bb">unblock</a></code> on all the <code class="computeroutput">shared_connection_block</code> objects that reference the connection. Here is an example of @@ -519,7 +519,7 @@ blocking/unblocking slots:</p> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp394633632"></a>Scoped Connections (Intermediate)</h4></div></div></div> +<a name="idm45927784741888"></a>Scoped Connections (Intermediate)</h4></div></div></div> <p>The <code class="computeroutput"><a class="link" href="../boost/signals2/scoped_connection.html" title="Class scoped_connection">boost::signals2::scoped_connection</a></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 @@ -540,22 +540,22 @@ e.g.,</p> </p> <pre class="programlisting"> // doesn't compile due to compiler attempting to copy a temporary scoped_connection object -// boost::signals2::scoped_connection c0 = sig.<code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idp134764096-bb">connect</a></code>(ShortLived()); +// boost::signals2::scoped_connection c0 = sig.<code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idm46563209038672-bb">connect</a></code>(ShortLived()); // okay -boost::signals2::scoped_connection c1(sig.<code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idp134764096-bb">connect</a></code>(ShortLived())); +boost::signals2::scoped_connection c1(sig.<code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idm46563209038672-bb">connect</a></code>(ShortLived())); // also okay boost::signals2::scoped_connection c2; -c2 = sig.<code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idp134764096-bb">connect</a></code>(ShortLived()); +c2 = sig.<code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idm46563209038672-bb">connect</a></code>(ShortLived()); </pre> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp394644896"></a>Disconnecting Equivalent Slots (Intermediate)</h4></div></div></div> +<a name="idm45927784730688"></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/signals2/signal.html#idp64426752-bb">signal::disconnect</a></code> method, so long as +<code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idm46563209009120-bb">signal::disconnect</a></code> method, so long as the type of the function object has an accessible <code class="computeroutput">==</code> operator. For instance: @@ -610,7 +610,7 @@ public: // ... NewsMessageArea *newsMessageArea = new NewsMessageArea(/* ... */); // ... -deliverNews.<code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idp134764096-bb">connect</a></code>(boost::bind(&NewsMessageArea::displayNews, +deliverNews.<code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idm46563209038672-bb">connect</a></code>(boost::bind(&NewsMessageArea::displayNews, newsMessageArea, _1)); </pre> <p>However, what if the user closes the news message area, @@ -618,21 +618,21 @@ 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.Signals2 one may track any object which is managed by a shared_ptr, by using -<code class="computeroutput"><a class="link" href="../boost/signals2/slot.html#idp131977696-bb">slot::track</a></code>. A slot will automatically +<code class="computeroutput"><a class="link" href="../boost/signals2/slot.html#idm46563208783264-bb">slot::track</a></code>. A slot will automatically disconnect when any of its tracked objects expire. In addition, Boost.Signals2 will ensure that no tracked object expires while the slot it is associated with is in mid-execution. It does so by creating temporary shared_ptr copies of the slot's tracked objects before executing it. To track <code class="computeroutput">NewsMessageArea</code>, we use a shared_ptr to manage its lifetime, and pass the shared_ptr to the slot via its -<code class="computeroutput"><a class="link" href="../boost/signals2/slot.html#idp131977696-bb">slot::track</a></code> +<code class="computeroutput"><a class="link" href="../boost/signals2/slot.html#idm46563208783264-bb">slot::track</a></code> method before connecting it, e.g.:</p> <pre class="programlisting"> // ... boost::shared_ptr<NewsMessageArea> newsMessageArea(new NewsMessageArea(/* ... */)); // ... -deliverNews.<code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idp134764096-bb">connect</a></code>(signal_type::slot_type(&NewsMessageArea::displayNews, +deliverNews.<code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idm46563209038672-bb">connect</a></code>(signal_type::slot_type(&NewsMessageArea::displayNews, newsMessageArea.get(), _1).track(newsMessageArea)); </pre> <p> @@ -647,14 +647,14 @@ deliverNews.<code class="computeroutput"><a class="link" href="../boost/signals2 <code class="computeroutput">newsMessageArea</code> itself, a copy of the <code class="computeroutput">shared_ptr</code> would have been bound into the slot function, preventing the <code class="computeroutput">shared_ptr</code> from expiring. However, the use of - <code class="computeroutput"><a class="link" href="../boost/signals2/slot.html#idp131977696-bb">slot::track</a></code> + <code class="computeroutput"><a class="link" href="../boost/signals2/slot.html#idm46563208783264-bb">slot::track</a></code> implies we wish to allow the tracked object to expire, and automatically disconnect the connection when this occurs. </p> <p> <code class="computeroutput">shared_ptr</code> classes other than <code class="computeroutput">boost::shared_ptr</code> (such as <code class="computeroutput">std::shared_ptr</code>) may also be tracked for connection management - purposes. They are supported by the <code class="computeroutput"><a class="link" href="../boost/signals2/slot.html#idp84715072-bb">slot::track_foreign</a></code> method. + purposes. They are supported by the <code class="computeroutput"><a class="link" href="../boost/signals2/slot.html#idm46563208769248-bb">slot::track_foreign</a></code> method. </p> </div> <div class="section"> @@ -696,10 +696,10 @@ deliverNews.<code class="computeroutput"><a class="link" href="../boost/signals2 </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp394698368"></a>When Can Disconnections Occur? (Intermediate)</h4></div></div></div> +<a name="idm45927784677088"></a>When Can Disconnections Occur? (Intermediate)</h4></div></div></div> <p>Signal/slot disconnections occur when any of these conditions occur:</p> -<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<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 @@ -731,7 +731,7 @@ signal.</p> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp394705968"></a>Passing Slots (Intermediate)</h4></div></div></div> +<a name="idm45927784669488"></a>Passing Slots (Intermediate)</h4></div></div></div> <p>Slots in the Boost.Signals2 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 @@ -920,7 +920,7 @@ private: access to a <code class="computeroutput"><a class="link" href="../boost/signals2/connection.html" title="Class connection">signals2::connection</a></code> object which references the invoking signal-slot connection. The difficulty is, the <code class="computeroutput">connection</code> object is returned by the - <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idp134764096-bb">signal::connect</a></code> + <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idm46563209038672-bb">signal::connect</a></code> method, and therefore is not available until after the slot is already connected to the signal. This can be particularly troublesome in a multi-threaded environment where the signal may be invoked @@ -928,11 +928,11 @@ private: </p> <p> Therefore, the signal classes provide - <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idp134091680-bb">signal::connect_extended</a></code> + <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idm46563209021696-bb">signal::connect_extended</a></code> methods, which allow slots which take an extra argument to be connected to a signal. The extra argument is a <code class="computeroutput"><a class="link" href="../boost/signals2/connection.html" title="Class connection">signals2::connection</a></code> object which refers to the signal-slot connection currently invoking the slot. - <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idp134091680-bb">signal::connect_extended</a></code> + <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idm46563209021696-bb">signal::connect_extended</a></code> uses slots of the type given by the <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#boost.signals2.signal.extended_slot_type">signal::extended_slot_type</a></code> typedef. @@ -941,7 +941,7 @@ private: The examples section includes an <a class="link" href="examples.html#signals2.examples.tutorial.extended_slot" title="extended_slot">extended_slot</a> program which demonstrates the syntax for using - <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idp134091680-bb">signal::connect_extended</a></code>. + <code class="computeroutput"><a class="link" href="../boost/signals2/signal.html#idm46563209021696-bb">signal::connect_extended</a></code>. </p> </div> <div class="section"> @@ -974,13 +974,13 @@ private: for its <code class="computeroutput">Mutex</code> types, you could write: </p> <pre class="programlisting">namespace bs2 = boost::signals2; -using bs2::keywords; +using namespace bs2::keywords; bs2::signal_type<void (int), mutex_type<bs2::dummy_mutex> >::type sig; </pre> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp394767824"></a>Linking against the Signals2 library</h3></div></div></div> +<a name="idm45927784607440"></a>Linking against the Signals2 library</h3></div></div></div> <p>Unlike the original Boost.Signals library, Boost.Signals2 is currently header-only. </p> </div> |