untracked/docs/manual/html/chapter-introduction.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   4 <title>Chapter 1. Introduction</title>
   5 <meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
   6 <link rel="home" href="index.html" title="libsigc++">
   7 <link rel="up" href="index.html" title="libsigc++">
   8 <link rel="prev" href="index.html" title="libsigc++">
   9 <link rel="next" href="chapter-connecting.html" title="Chapter 2. Connecting your code to signals">
  10 </head>
  11 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  12 <div class="navheader">
  13 <table width="100%" summary="Navigation header">
  14 <tr><th colspan="3" align="center">Chapter 1. Introduction</th></tr>
  15 <tr>
  16 <td width="20%" align="left">
  17 <a accesskey="p" href="index.html">Prev</a> </td>
  18 <th width="60%" align="center"> </th>
  19 <td width="20%" align="right"> <a accesskey="n" href="chapter-connecting.html">Next</a>
  20 </td>
  21 </tr>
  22 </table>
  23 <hr>
  24 </div>
  25 <div class="chapter">
  26 <div class="titlepage"><div><div><h1 class="title">
  27 <a name="chapter-introduction"></a>Chapter 1. Introduction</h1></div></div></div>
  28 <div class="toc">
  29 <p><b>Table of Contents</b></p>
  30 <ul class="toc"><li><span class="section"><a href="chapter-introduction.html#sect-motivation">Motivation</a></span></li></ul>
  31 </div>
  32
  33
  34 <div class="section">
  35 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  36 <a name="sect-motivation"></a>Motivation</h2></div></div></div>
  37
  38
  39         <p>There are many situations in which it is desirable to decouple code that
  40         detects an event, and the code that deals with it. This is especially common in
  41         GUI programming, where a toolkit might provide user interface elements such as
  42         clickable buttons but, being a generic toolkit, doesn't know how an individual
  43         application using that toolkit should handle the user clicking on it.</p>
  44
  45         <p>In C the callbacks are generally handled by the application calling a
  46         'register' function and passing a pointer to a function and a <code class="literal">void*</code>
  47         argument, eg.</p>
  48
  49 <pre class="programlisting">
  50 void clicked(void* data);
  51
  52 button* okbutton = create_button("ok");
  53 static char somedata[] = "This is some data I want the clicked() function to have";
  54
  55 register_click_handler(okbutton, clicked, somedata);
  56 </pre>
  57
  58         <p>When clicked, the toolkit will call <code class="literal">clicked()</code> with the data pointer passed
  59         to the <code class="literal">register_click_handler()</code> function.</p>
  60
  61         <p>This works in C, but is not typesafe. There is no compile-time way of
  62         ensuring that <code class="literal">clicked()</code> isn't expecting a struct of some sort instead of a
  63         <code class="literal">char*</code>.</p>
  64
  65         <p>As C++ programmers, we want type safety. We also want to be able to use
  66         things other than free-standing functions as callbacks.</p>
  67
  68         <p>libsigc++ provides the concept of a slot, which holds a reference to one of
  69         the things that can be used as a callback:
  70         </p>
  71 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  72 <li class="listitem"><p>A free-standing function as in the example</p></li>
  73 <li class="listitem"><p>A functor object that defines operator() (a lambda expression
  74                 is such an object)</p></li>
  75 <li class="listitem"><p>A pointer-to-a-member-function and an instance of an object on which to invoke it (the
  76                 object should inherit from <code class="literal">sigc::trackable</code>)</p></li>
  77 </ul></div>
  78
  79         <p>All of which can take different numbers and types of arguments.</p>
  80
  81         <p>To make it easier to construct these, libsigc++ provides the sigc::ptr_fun() and sigc::mem_fun() functions, for creating slots from static functions and member functions, respectively. They return
  82         a generic <code class="literal">signal::slot</code> type that can be invoked with <code class="literal">emit()</code> or <code class="literal">operator()</code>.</p>
  83
  84         <p>For the other side of the fence, libsigc++ provides <code class="literal">signal</code>s, to which the
  85         client can attach <code class="literal">slot</code>s. When the <code class="literal">signal</code> is emitted, all the connected
  86         <code class="literal">slot</code>s are called.</p>
  87 </div>
  88 </div>
  89 <div class="navfooter">
  90 <hr>
  91 <table width="100%" summary="Navigation footer">
  92 <tr>
  93 <td width="40%" align="left">
  94 <a accesskey="p" href="index.html">Prev</a> </td>
  95 <td width="20%" align="center"> </td>
  96 <td width="40%" align="right"> <a accesskey="n" href="chapter-connecting.html">Next</a>
  97 </td>
  98 </tr>
  99 <tr>
 100 <td width="40%" align="left" valign="top">libsigc++ </td>
 101 <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
 102 <td width="40%" align="right" valign="top"> Chapter 2. Connecting your code to signals</td>
 103 </tr>
 104 </table>
 105 </div>
 106 </body>
 107 </html>