libs/signals/doc/reference/connection.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
   3   "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
   4 <header name="boost/signals/connection.hpp" last-revision="$Date: 2007-11-25 10:38:02 -0800 (Sun, 25 Nov 2007) $">
   5   <namespace name="boost">
   6     <namespace name="signals">
   7       <class name="connection">
   8         <!-- Models LessThanComparable and EqualityComparable -->
   9         <purpose>Query/disconnect a signal-slot connection.</purpose>
  10
  11         <description>
  12           <para>The <classname>connection</classname> class represents
  13           a connection between a Signal and a Slot. It is a
  14           lightweight object that has the ability to query whether the
  15           signal and slot are currently connected, and to disconnect
  16           the signal and slot. It is always safe to query or
  17           disconnect a connection.</para>
  18         </description>
  19
  20         <constructor>
  21           <effects><para>Sets the currently represented connection to the
  22           NULL connection.</para></effects>
  23           <postconditions><para><computeroutput>!this-><methodname>connected</methodname>()</computeroutput>.</para></postconditions>
  24           <throws><para>Will not throw.</para></throws>
  25         </constructor>
  26
  27         <constructor>
  28           <parameter name="other">
  29             <paramtype>const <classname>connection</classname>&amp;</paramtype>
  30           </parameter>
  31
  32           <effects><para><computeroutput>this</computeroutput> references
  33           the connection referenced by
  34           <computeroutput>other</computeroutput>.</para></effects>
  35
  36           <throws><para>Will not throw.</para></throws>
  37         </constructor>
  38
  39         <copy-assignment>
  40           <parameter name="other">
  41             <paramtype>const <classname>connection</classname>&amp;</paramtype>
  42           </parameter>
  43
  44           <effects><para><computeroutput>this</computeroutput> references
  45           the connection referenced by
  46           <computeroutput>other</computeroutput>.</para></effects>
  47
  48           <throws><para>Will not throw.</para></throws>
  49         </copy-assignment>
  50
  51         <method-group name="connection management">
  52           <method name="disconnect" cv="const">
  53              <type>void</type>
  54              <effects><para>If
  55              <computeroutput>this-&gt;<methodname>connected</methodname>()</computeroutput>,
  56              disconnects the signal and slot referenced by this;
  57              otherwise, this operation is a no-op.</para></effects>
  58
  59              <postconditions><para><computeroutput>!this-&gt;<methodname>connected</methodname>()</computeroutput>.</para></postconditions>
  60           </method>
  61
  62           <method name="connected" cv="const">
  63             <type>bool</type>
  64             <returns><para><computeroutput>true</computeroutput> if this
  65             references a non-NULL connection that is still active
  66             (connected), and <computeroutput>false</computeroutput>
  67             otherwise.</para></returns>
  68             <throws><para>Will not throw.</para></throws>
  69           </method>
  70         </method-group>
  71
  72         <method-group name="blocking">
  73           <method name="block">
  74             <type>void</type>
  75             <parameter name="should_block">
  76               <paramtype>bool</paramtype>
  77               <default>true</default>
  78             </parameter>
  79             <requires><simpara><code>connected()</code></simpara></requires>
  80             <postconditions><simpara><code>blocked() == should_block</code></simpara></postconditions>
  81             <throws><simpara>Will not throw.</simpara></throws>
  82           </method>
  83           <method name="unblock">
  84             <type>void</type>
  85             <requires><simpara><code>connected()</code></simpara></requires>
  86             <postconditions><simpara><code>!blocked()</code></simpara></postconditions>
  87             <throws><simpara>Will not throw.</simpara></throws>
  88           </method>
  89           <method name="blocked" cv="const">
  90             <type>bool</type>
  91             <returns><simpara><code>true</code> if the associated slot is either disconnected or blocked, <code>false</code> otherwise.</simpara></returns>
  92             <throws><simpara>Will not throw.</simpara></throws>
  93           </method>
  94         </method-group>
  95
  96         <method-group name="modifiers">
  97           <method name="swap">
  98             <type>void</type>
  99             <parameter name="other">
 100               <paramtype>const <classname>connection</classname>&amp;</paramtype>
 101             </parameter>
 102             <effects><para>Swaps the connections referenced in
 103             <computeroutput>this</computeroutput> and
 104             <computeroutput>other</computeroutput>.</para></effects>
 105
 106             <throws><para>Will not throw.</para></throws>
 107           </method>
 108         </method-group>
 109
 110         <method-group name="comparisons">
 111           <method name="operator==" cv="const">
 112             <type>bool</type>
 113             <parameter name="other">
 114               <paramtype>const <classname>connection</classname>&amp;</paramtype>
 115             </parameter>
 116
 117             <returns><para><computeroutput>true</computeroutput> if
 118             <computeroutput>this</computeroutput> and
 119             <computeroutput>other</computeroutput> reference the same
 120             connection or both reference the NULL connection, and
 121             <computeroutput>false</computeroutput>
 122             otherwise.</para></returns>
 123
 124             <throws><para>Will not throw.</para></throws>
 125           </method>
 126
 127           <method name="operator&lt;" cv="const">
 128             <type>bool</type>
 129             <parameter name="other">
 130               <paramtype>const <classname>connection</classname>&amp;</paramtype>
 131             </parameter>
 132
 133             <returns><para><computeroutput>true</computeroutput> if the
 134             connection referenced by
 135             <computeroutput>this</computeroutput> precedes the
 136             connection referenced by
 137             <computeroutput>other</computeroutput> based on some
 138             unspecified ordering, and
 139             <computeroutput>false</computeroutput>
 140             otherwise.</para></returns>
 141
 142             <throws><para>Will not throw.</para></throws>
 143           </method>
 144         </method-group>
 145
 146         <free-function-group name="specialized algorithms">
 147           <function name="swap">
 148             <type>void</type>
 149             <parameter name="x">
 150               <paramtype><classname>connection</classname>&amp;</paramtype>
 151             </parameter>
 152             <parameter name="y">
 153               <paramtype><classname>connection</classname>&amp;</paramtype>
 154             </parameter>
 155
 156             <effects><para><computeroutput>x.swap(y)</computeroutput></para></effects>
 157             <throws><para>Will not throw.</para></throws>
 158           </function>
 159         </free-function-group>
 160       </class>
 161
 162       <class name="scoped_connection">
 163         <inherit access="private">
 164           <type><classname>noncopyable</classname></type>
 165           <purpose>Exposition only</purpose>
 166         </inherit>
 167         <purpose>Limits a signal-slot connection lifetime to a particular scope.</purpose>
 168
 169         <constructor>
 170           <parameter name="other">
 171             <paramtype>const <classname>connection</classname>&amp;</paramtype>
 172           </parameter>
 173
 174           <effects><para><computeroutput>this</computeroutput> references
 175           the connection referenced by
 176           <computeroutput>other</computeroutput>.</para></effects>
 177
 178           <throws><para>Will not throw.</para></throws>
 179         </constructor>
 180
 181         <destructor>
 182           <effects><para>If
 183           <computeroutput>this-&gt;<methodname>connected</methodname>()</computeroutput>,
 184           disconnects the signal-slot connection.</para></effects>
 185         </destructor>
 186
 187         <method-group name="connection management">
 188           <method name="disconnect" cv="const">
 189             <type>void</type>
 190              <effects><para>If
 191              <computeroutput>this-&gt;<methodname>connected</methodname>()</computeroutput>,
 192              disconnects the signal and slot referenced by this;
 193              otherwise, this operation is a no-op.</para></effects>
 194
 195              <postconditions><para><computeroutput>!this-&gt;<methodname>connected</methodname>()</computeroutput>.</para></postconditions>
 196           </method>
 197
 198           <method name="connected" cv="const">
 199             <type>bool</type>
 200             <returns><para><computeroutput>true</computeroutput> if this
 201             references a non-NULL connection that is still active
 202             (connected), and <computeroutput>false</computeroutput>
 203             otherwise.</para></returns>
 204             <throws><para>Will not throw.</para></throws>
 205           </method>
 206         </method-group>
 207       </class>
 208     </namespace>
 209   </namespace>
 210 </header>