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$">
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>
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>
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>
28 <parameter name=
"other">
29 <paramtype>const
<classname>connection
</classname>&</paramtype>
32 <effects><para><computeroutput>this
</computeroutput> references
33 the connection referenced by
34 <computeroutput>other
</computeroutput>.
</para></effects>
36 <throws><para>Will not throw.
</para></throws>
40 <parameter name=
"other">
41 <paramtype>const
<classname>connection
</classname>&</paramtype>
44 <effects><para><computeroutput>this
</computeroutput> references
45 the connection referenced by
46 <computeroutput>other
</computeroutput>.
</para></effects>
48 <throws><para>Will not throw.
</para></throws>
51 <method-group name=
"connection management">
52 <method name=
"disconnect" cv=
"const">
55 <computeroutput>this-
><methodname>connected
</methodname>()
</computeroutput>,
56 disconnects the signal and slot referenced by this;
57 otherwise, this operation is a no-op.
</para></effects>
59 <postconditions><para><computeroutput>!this-
><methodname>connected
</methodname>()
</computeroutput>.
</para></postconditions>
62 <method name=
"connected" cv=
"const">
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>
72 <method-group name=
"blocking">
75 <parameter name=
"should_block">
76 <paramtype>bool
</paramtype>
77 <default>true
</default>
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>
83 <method name=
"unblock">
85 <requires><simpara><code>connected()
</code></simpara></requires>
86 <postconditions><simpara><code>!blocked()
</code></simpara></postconditions>
87 <throws><simpara>Will not throw.
</simpara></throws>
89 <method name=
"blocked" cv=
"const">
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>
96 <method-group name=
"modifiers">
99 <parameter name=
"other">
100 <paramtype>const
<classname>connection
</classname>&</paramtype>
102 <effects><para>Swaps the connections referenced in
103 <computeroutput>this
</computeroutput> and
104 <computeroutput>other
</computeroutput>.
</para></effects>
106 <throws><para>Will not throw.
</para></throws>
110 <method-group name=
"comparisons">
111 <method name=
"operator==" cv=
"const">
113 <parameter name=
"other">
114 <paramtype>const
<classname>connection
</classname>&</paramtype>
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>
124 <throws><para>Will not throw.
</para></throws>
127 <method name=
"operator<" cv=
"const">
129 <parameter name=
"other">
130 <paramtype>const
<classname>connection
</classname>&</paramtype>
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>
142 <throws><para>Will not throw.
</para></throws>
146 <free-function-group name=
"specialized algorithms">
147 <function name=
"swap">
150 <paramtype><classname>connection
</classname>&</paramtype>
153 <paramtype><classname>connection
</classname>&</paramtype>
156 <effects><para><computeroutput>x.swap(y)
</computeroutput></para></effects>
157 <throws><para>Will not throw.
</para></throws>
159 </free-function-group>
162 <class name=
"scoped_connection">
163 <inherit access=
"private">
164 <type><classname>noncopyable
</classname></type>
165 <purpose>Exposition only
</purpose>
167 <purpose>Limits a signal-slot connection lifetime to a particular scope.
</purpose>
170 <parameter name=
"other">
171 <paramtype>const
<classname>connection
</classname>&</paramtype>
174 <effects><para><computeroutput>this
</computeroutput> references
175 the connection referenced by
176 <computeroutput>other
</computeroutput>.
</para></effects>
178 <throws><para>Will not throw.
</para></throws>
183 <computeroutput>this-
><methodname>connected
</methodname>()
</computeroutput>,
184 disconnects the signal-slot connection.
</para></effects>
187 <method-group name=
"connection management">
188 <method name=
"disconnect" cv=
"const">
191 <computeroutput>this-
><methodname>connected
</methodname>()
</computeroutput>,
192 disconnects the signal and slot referenced by this;
193 otherwise, this operation is a no-op.
</para></effects>
195 <postconditions><para><computeroutput>!this-
><methodname>connected
</methodname>()
</computeroutput>.
</para></postconditions>
198 <method name=
"connected" cv=
"const">
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>