<pubdate>September 2002. Updated January 2004 and March 2016 by Murray Cumming</pubdate>

<para>There are many situations in which it is desirable to decouple code that

detects an event, and the code that deals with it. This is especially common in

<para>For the other side of the fence, libsigc++ provides <literal remap="tt">signal</literal>s, to which the

client can attach <literal remap="tt">slot</literal>s. When the <literal remap="tt">signal</literal> is emitted, all the connected

<literal remap="tt">slot</literal>s are called.</para>

</chapter>

<para>So to get some experience, lets look at a simple example...</para>

<para>Lets say you and I are writing an application which informs the user when

<programlisting>./example1</programlisting>

<para>(Try not to panic when the aliens land!)</para>

<para>Suppose you found a more sophisticated alien alerter class on the web,

such as this:</para>

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>

<para>Functions taking no parameters and returning void are quite useful,

especially when they're members of classes that can store unlimited amounts of

</programlisting>

<para>Easy.</para>

<para>If you decide you no longer want your code to be called whenever a signal is

emitted, you must remember the return value of <literal remap="tt">connect()</literal>, which we've been

ignoring until now.</para>

<para><literal remap="tt">connect()</literal> returns a <literal remap="tt">sigc::connection</literal> object, which has a <literal remap="tt">disconnect()</literal> member method. This does just what you think it does.</para>

</chapter>

<para>If all you want to do is use gtkmm, and connect your functionality to its

signals, you can probably stop reading here.</para>

// they landed in the carpark after all.

}

</programlisting>

<para>If you only ever have one slot connected to a signal, or if you only care

about the return value of the last registered one, it's quite straightforward:</para>

a_return_value = somesignal.emit();

</programlisting>

</chapter>

<para>Suppose you already have a function that you want to be called when a

signal is emitted, but it takes the wrong argument types. For example, lets try

to attach the <literal remap="tt">warn_people(std::string)</literal> function to the detected signal

hide the first argument of 3, for example, only the last).</para>

<para><literal remap="tt">sigc::hide_return</literal> effectively makes the return type void.</para>

<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>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>

</chapter>

</chapter>

</book>

xmllint = find_program('xmllint', required: false)

can_parse_and_validate = xmllint.found()

validate = get_option('validation') ? 'true' : 'false'

dblatex = find_program('dblatex', required: false)

build_pdf_by_default = get_option('build-pdf')

if can_build_pdf

# Create a PDF file of the DocBook.

custom_target('manual_pdf',

input: sigc_manual_xml,

output: sigc_manual_pdf,

command: [

python3, tutorial_custom_cmd,

'@INPUT@',

'@OUTPUT@'

],

build_pdf = build_pdf_by_default and can_build_pdf

explain_pdf = ''

if build_pdf_by_default and not build_pdf

summary = [

'',

'------',

import os

import sys

import subprocess

import shutil

subcommand = sys.argv[1]

'--stringparam', 'chunker.output.indent', 'yes',

'--stringparam', 'chunker.output.encoding', 'UTF-8',

'--stringparam', 'toc.list.type', 'ul',

]

xslt_stylesheet = 'http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl'

return result.returncode

def xmllint():

# argv[2] argv[3] argv[4]

# <validate> <input_xml_file> <stamp_file_path>

validate = sys.argv[2]

input_xml_file = sys.argv[3]

stamp_file_path = sys.argv[4]

cmd = [

'xmllint',

'--noout',

'--noent',

'--xinclude',

]

if validate == 'true':

cmd += [input_xml_file]

result = subprocess.run(cmd)

if result.returncode:

Path(stamp_file_path).touch(exist_ok=True)

return 0

def dblatex():

# argv[2] argv[3]

# <input_xml_file> <output_pdf_file>

# For a list of available parameters, see http://dblatex.sourceforge.net/doc/manual/

dblatex_params = [

'-P', 'paper.type=a4paper',

]

cmd = [

'dblatex',

] + dblatex_params + [

'-o', output_pdf_file,

]

return subprocess.run(cmd).returncode

# argv[2] argv[3]

# <input_xml_file> <output_pdf_file>

input_xml_file = sys.argv[2]

output_pdf_file = sys.argv[3]

cmd = [

'--xinclude',

input_xml_file,

]

result = subprocess.run(cmd)

if result.returncode:

return result.returncode

cmd = [

]

return subprocess.run(cmd).returncode

sys.exit(xmllint())

if subcommand == 'dblatex':

sys.exit(dblatex())

if subcommand == 'dist_doc':

sys.exit(dist_doc())

print(sys.argv[0], ': illegal subcommand,', subcommand)