docs/manual/libsigc_manual.xml: Update signal and slot syntax

kjellahl · kjellahl · commit 40c61c91bdb9 · 2020-06-27T10:29:18.000+02:00
Update the syntax of template parameters. sigc::signal<void,int> -> sigc::signal<void(int)>. The old syntax is deprecated. Mention lambda expressions. Although sigc::retype() is a template function, no template parameters shall be specified when it's called. See #59
diff --git a/docs/manual/libsigc_manual.xml b/docs/manual/libsigc_manual.xml
@@ -29,24 +29,24 @@
 	application using that toolkit should handle the user clicking on it.</para>
 
 	<para>In C the callbacks are generally handled by the application calling a
-	'register' function and passing a pointer to a function and a <literal remap="tt">void *</literal>
+	'register' function and passing a pointer to a function and a <literal remap="tt">void*</literal>
 	argument, eg.</para>
 
 <programlisting>
-void clicked(void *data);
+void clicked(void* data);
 
-button * okbutton = create_button("ok");
+button* okbutton = create_button("ok");
 static char somedata[] = "This is some data I want the clicked() function to have";
 
 register_click_handler(okbutton, clicked, somedata);
 </programlisting>
 
 	<para>When clicked, the toolkit will call <literal remap="tt">clicked()</literal> with the data pointer passed
-	to the <literal remap="tt">register_click_handler</literal> function.</para>
+	to the <literal remap="tt">register_click_handler()</literal> function.</para>
 
 	<para>This works in C, but is not typesafe. There is no compile-time way of
 	ensuring that <literal remap="tt">clicked()</literal> isn't expecting a struct of some sort instead of a
-	<literal remap="tt">char *</literal>.</para>
+	<literal remap="tt">char*</literal>.</para>
 
 	<para>As C++ programmers, we want type safety. We also want to be able to use
 	things other than free-standing functions as callbacks.</para>
@@ -55,7 +55,8 @@ register_click_handler(okbutton, clicked, somedata);
 	the things that can be used as a callback:
 	<itemizedlist>
 	    <listitem><para>A free-standing function as in the example</para></listitem>
-	    <listitem><para>A functor objects that defines operator()</para></listitem>
+	    <listitem><para>A functor object that defines operator() (a lambda expression
+	        is such an object)</para></listitem>
 	    <listitem><para>A pointer-to-a-member-function and an instance of an object on which to invoke it (the
 	        object should inherit from <literal remap="tt">sigc::trackable</literal>)</para></listitem>
 	</itemizedlist></para>
@@ -96,7 +97,7 @@ public:
 
     void run();
 
-    sigc::signal&lt;void&gt; signal_detected;
+    sigc::signal&lt;void()&gt; signal_detected;
 };
 </programlisting>
 
@@ -107,7 +108,7 @@ public:
 <programlisting>
 void warn_people()
 {
-    cout &lt;&lt; "There are aliens in the carpark!" &lt;&lt; endl;
+    std::cout &lt;&lt; "There are aliens in the carpark!" &lt;&lt; std::endl;
 }
 
 int main()
@@ -121,6 +122,11 @@ int main()
 }
 </programlisting>
 
+  <para>You can use a lambda expression instead of sigc::ptr_fun().</para>
+<programlisting>
+    mydetector.signal_detected.connect( [](){ warn_people(); } );
+</programlisting>
+
 	<para>Pretty simple really - you call the <literal remap="tt">connect()</literal> method on the signal to
 	connect your function. <literal remap="tt">connect()</literal> takes a <literal remap="tt">slot</literal> parameter (remember slots
 	are capable of holding any type of callback), so you convert your
@@ -175,6 +181,12 @@ int main()
 
 	<para>This code is in example2.cc, which can be compiled in the same way as
 	example1.cc</para>
+
+	<para>It's possible to use a lambda expression instead of sigc::mem_fun(),
+	but it's not recommended, if the class derives from <literal remap="tt">sigc::trackable</literal>.
+	With a lambda expression you would lose the automatic disconnection that the
+	combination of <literal remap="tt">sigc::trackable</literal> and sigc::mem_fun()
+	offers.</para>
 </sect1>
 
 <sect1>
@@ -198,22 +210,25 @@ public:
 
     void run();
 
-    sigc::signal&lt;void, std::string&gt; signal_detected;	// changed
+    sigc::signal&lt;void(std::string)&gt; signal_detected;	// changed
 };
 </programlisting>
 
 	<para>The only line I had to change was the signal line (in <literal remap="tt">run()</literal> I need to change
 	my code to supply the argument when I emit the signal too, but that's not shown
 	here).</para>
 
-	<para>The name of the type is '<literal remap="tt">sigc::signal</literal>'. The template parameters are the return type, then the argument types.</para>
+	<para>The name of the type is '<literal remap="tt">sigc::signal</literal>'.
+	The template parameters are the return type, then the argument types in parentheses.
+	(libsigc++2 also accepts a different syntax, with a comma between the return type
+	and the parameter types. That syntax is deprecated, though.)</para>
 
 	<para>The types in the function signature are in the same order as the template
 	parameters, eg:</para>
 
 <programlisting>
-sigc::signal&lt;void,         std::string&gt;
-              void function(std::string foo);
+sigc::signal&lt;void(std::string)&gt;
+    void function(std::string foo);
 </programlisting>
 
 		<para>So now you can update your alerter (for simplicity, lets go back to the
@@ -222,7 +237,7 @@ sigc::signal&lt;void,         std::string&gt;
 <programlisting>
 void warn_people(std::string where)
 {
-    cout &lt;&lt; "There are aliens in " &lt;&lt; where &lt;&lt; "!" &lt;&lt; endl;
+    std::cout &lt;&lt; "There are aliens in " &lt;&lt; where &lt;&lt; "!" &lt;&lt; std::endl;
 }
 
 int main()
@@ -269,7 +284,7 @@ int main()
 	<para>A signal is an instance of a template, named <literal remap="tt">sigc::signal</literal>.
         The template arguments are the types,
 	in the order they appear in the function signature that can be connected to that
-	signal; that is the return type, then the argument types.</para>
+	signal; that is the return type, then the argument types in parentheses.</para>
 
 	<para>To provide a signal for people to connect to, you must make available an
 	instance of that <literal remap="tt">sigc::signal</literal>. In <literal remap="tt">AlienDetector</literal> this was done
@@ -297,7 +312,7 @@ void AlienDetector::run()
 {
     sleep(3);                // wait for aliens
     signal_detected("the carpark"); // this is the std::string version, looks like
-       	                     // they landed in the carpark afterall.
+                             // they landed in the carpark after all.
 }
 </programlisting>
 </sect1>
@@ -308,7 +323,7 @@ void AlienDetector::run()
 	about the return value of the last registered one, it's quite straightforward:</para>
 
 <programlisting>
-sigc::signal&lt;int&gt; somesignal;
+sigc::signal&lt;int()&gt; somesignal;
 int a_return_value;
 
 a_return_value = somesignal.emit();
@@ -390,23 +405,21 @@ myaliendetector.signal_detected.connect( sigc::hide&lt;std::string&gt;( sigc::pt
 	<para>A similar topic is retyping. Perhaps you have a signal that takes an <literal remap="tt">int</literal>, but
 	you want to connect a function that takes a <literal remap="tt">double</literal>.</para>
 
-	<para>This can be achieved with the <literal remap="tt">sigc::retype</literal> template. <literal remap="tt">retype</literal> has template arguments
-	just like <literal remap="tt">sigc::signal</literal> - return value, signal types.</para>
-
-	<para>It's a function template that takes a <literal remap="tt">sigc::slot</literal>, and returns a <literal remap="tt">sigc::slot</literal>. eg.</para>
+	<para>This can be achieved with the <literal remap="tt">sigc::retype()</literal> template.
+	It takes a <literal remap="tt">sigc::slot</literal>, and returns a <literal remap="tt">sigc::slot</literal>. eg.</para>
 
 <programlisting>
 void dostuff(double foo)
 {
 }
 
-sigc::signal&lt;void,int&gt; asignal;
+sigc::signal&lt;void(int)&gt; asignal;
 
-asignal.connect(  sigc::retype&lt;void, int&gt;( slot(&amp;dostuff) )  );
+asignal.connect( sigc::retype( sigc::ptr_fun(&amp;dostuff) ) );
 </programlisting>
 
-	<para>If you only want to change the return type, you can use <literal remap="tt">sigc::retype_return</literal>.
-	<literal remap="tt">retype_return</literal> needs only one template argument.</para>
+	<para>If you only want to change the return type, you can use <literal remap="tt">sigc::retype_return()</literal>.
+	<literal remap="tt">retype_return()</literal> needs one template argument, the new return type.</para>
 </sect1>
 </chapter>
 
