fix typo that put too many include paths for most people

[lyx.git] / sigc++ / doc / signals

1.0 Signals
==============

Signals are used for communication between objects.  Rather
that using messy pointers or pointers to member functions to implement 
callbacks this library provides an elegant connection framework for
connecting between static functions, member functions and function objects. 
To add to this all types of connections can be made with compile time
type checking through an extensable template set.  Unlike other solutions
that break the C++ language and add incompatible extensions or code 
generation, Libsigc++ uses only the standard C++ definitions.  Thus it
will not decrease the ability of tools designed to parse the C++ language 
to handle your code.  Libsigc++ provides signal framework which solves 
your problems with communication between objects.  This signal framework 
makes your objects reusable components which are independent of other 
objects it communicates with. This means reducing coupling between 
objects and resulting less dependencies and thus more reusable code. 
 
1.1 How does the communication work?
------------------------------------

In the callback mechanism there's 3 separate entities involved. 

     sender 
     receiver 
     someone making connection between sender and receiver 

In actual code, the sender specifies an interface which it can call when 
it wants to tell other objects something. This interface is specified as 
a function object and is called "Signal". Calling that interface is 
called "emitting a signal". 

The receiver of the signal can be almost anything.  In Libsigc++ the 
following objects can receive messages: 

     member function of any object derived from SigC::Object
     function object derived from SigC::Object 
     static, global or friend function 
     static function object 
     member function to a static object 

All connections share a common syntax through a factory that creates a
abstract function object called a "Slot."


     signal.connect(slot(object,Object::&method));
     signal.connect(slot(&function));
     signal.connect(functionobject.slot())

Making a connection connects sender to the receiver.  After that, if the 
sender emits a signal, all methods, functions and function objects that 
have been connected to that signal are called with the arguments given at
signal emission.  Signature of both sender interface and receiver method 
must match exactly to be able to make connection between them.  If there's 
type mismatches in the signatures, C++ compiler will give compile time 
type error. 



2.0 Implementation of signals
=============================

Signals are C++ function objects.  Because signals are normal C++-objects, 
you can use them in file scope, in function local scope - but they're 
most used inside class scope. A signal definition is of form: 

  Signal2<void, int, float> buttonPressed;

  where
    2     = number of arguments
    void  = type of the return
    int   = type of the first parameter of the signal
    float = type of the 2nd parameter of the signal

This way application programmers can specify interface for a signal. 
A connection from a signal to a (member) function matching signal's 
interface can be made:

  void my_function(int param1, float param2);
  buttonPressed.connect(slot(&my_function));

If the function is a member function, you'll need to specify the object 
too. Note that this object's class needs to be derived from Signal: 

  MyClass myobject; 
  buttonPressed.connect(slot(myobject,&MyClass::my_function));

If the signal is inside an object, you'll need to specify it too: 

  obj.buttonPressed.connect(slot(myobject, &MyClass::my_function));


When connection between a signal and a function has been made, calling 
the signal will make the system call all the connected functions with 
given parameters. Of course many connections can be made to same signal 
and the system will call all of them when the signal is called.

Calling a signal looks exactly like calling normal C++ function: 

  buttonPressed(10, 20.0);

or in case where you have the signal inside an object, call is in format: 

  obj.buttonPressed(10, 20.0);

An alternative method with a function name is also provided with
a method emit.  This is to make it easier to distiguish and provides
a method name for STL connection calls.

  obj.buttonPressed.emit(10, 20.0);



2.1 Signals with return types
------------------------------

All signals have a return type which may be void.  

  Signal1<int,int> signal;

That signal can be connected to the methods with the following signature:

  int my_callback(int);

There are a few restrictions on the types of returns.  Return
types must have:

   a default constructor  T t;
   a copy constructor     T t1,t2;  t1=t2;
   a reference form       T t1;  void func(T& t); func(t1);

A default ctor is required so that a temporary object can be
created to hold the return type.  A copy constructor is required
so that the signal can be marshalled.  A reference form is required
to pass the return types to the marshaller functions.

This means that the return type must not be a reference itself.  



2.2 Connecting to a signals 
-----------------------------

Because Libsigc++ signals use function objects heavily, there needs to be 
way to connect a signal to another signal.  Lets connect a button's 
clicked()-signal to another button's clicked signal: 

struct My_Button 
  {
   Signal0<void> clicked;
  } b1,b2;

b1.clicked.connect(b2.clicked.slot());


2.3 Summery
------------

Here is the summery of the properties of a signal

class Signal<Rettype,Args>
  {
   public:
      Connection connect(const Slot<Rettype Args>&);
      Slot<Rettype,Args> slot();
      Rettype emit(Args);
      Rettype operator()(Args);
  };

Where:
  Rettype is the return type of the signal.
  Args are the arguments taken.

connect() inserts a slot with the same profile into the signal.
slot() returns a slot for connecting this signal to another.
emit() calls all slots in the signal.
 

3.0 Common errors in use of the signals
=======================================

Here are some common errors and an example of some of the errors that
they generate.  (Do not take this as an example of proper use!
Errors similified for clarity.  Your compiler messages will differ)

 * Signature of function does not match signal 
     Return type? 
     arguments have correct type? 
     the signal has correct types?

   Example error session:
     void foo(int i);
     Signal1<int,int> sig;
     sig.connect(slot(foo));
   
     >>foobar.cc: In function `int main()':
     >>foobar.cc:17: no matching function for call to 
         `Signal1<int,int>::connect (Slot1<void,int> *)'
                                         ^^^^^^^^^^^^^^^^
                                       Signiture of function
     >>signal.h: candidates are: 
          Signal1<int,int>::connect<int, int> (Slot1<int,int> *)
                                              ^^^^^^^^^^^^^^
                                           Signiture of Signal
 
 * Using a reference as a return type

   Example error session:
     Signal1<int&,int> sig;

     >>basic_signal.h: In method `int & Signal1_<int &,int>::Impl::
       emit<int &, int>(int)':
     >>signal.h:100:   instantiated from here
     >>basic_signal.h:244: `rc' declared as reference but not initialized

  

 * Connecting object is not derived from SigC::Object
     
   Example error session:
     struct A {int foo(int);} a;
     Signal1<int,int> sig;

     sig.connect(slot(a,&A::foo));

     foobar.cc:58: conversion from `A' to non-scalar type `Object' requested
    
   
 * Forgot to name the connected function as a method.
  
   Example error session: 
     struct A:public SigC::Object {int foo(int);} a;
     Signal1<int,int> sig;

     sig.connect(slot(a,foo));  // should be sig.connect(slot(a,&A::foo));

     >>foobar.cc:47: no matching function for call to `slot (A &, int ()(int))'


 * Forgot to use address of method on connection 
   
   Example error session:
     struct A:public SigC::Object {int foo(int);} a;
     Signal1<int,int> sig;

     sig.connect(slot(a,A::foo)); // should be sig.connect(slot(a,&A::foo));

     >> foobar.cc:23: warning: assuming & on `A::foo1(int)'
  
 
 * Passed a pointer as object (**This is different from Gtk--**)
    
   Example error session:
     struct A:public SigC::Object {int foo(int);} a;
     Signal1<int,int> sig;

     sig.connect(slot(&a,&A::foo)); // should be sig.connect(slot(a,&A::foo));

     >>foobar.cc:93: conversion from `A *' to non-scalar type `Object' 
       requested
     >>object_slot.h:177: in passing argument 1 of 
       `slot<A, int, int>(Object &, int (A::*)(int))'


4.0 Connections
===============

4.1 Disconnecting signals
-------------------------

Every signal.connect()-function returns a Connection object, 
which can be stored and it can be used to disconnect the connection 
by calling function disconnect(). 

Connection c;
c=o.buttonPressed.connect(slot(&myfunction));
...
c.disconnect();

Its perfectly legal to just ignore the return value of connect() functions - 
all bookeeping information used by signal system is released properly.


5.0 Adaptors
============

Often it is desirable to connect to a function and a signal
in which the signal and function signatures are not
exactly the same.

For example, it would be good to ignore the return type
of a function when placing it into a signal with a void return 
type.  

Fortunately, Libsigc++ provides a mechanism to accomplish this
type of connection.  There is a broad class of slot "Adaptors".
These functions take a slot of one type and produce a slot of
another.  Here are some sample adaptors provided:

  bind(Slot, v1) - Passes v1 as last argument to Slot
    (The number of arguments is reduced for the resulting slot)
  bind(Slot, v1, v2) - Passes v1 and v2 as last arguments to Slot

  Examples:

    int func(float);
    Signal1<void,float> sig1;
    Signal1<int> sig2;

    // cover up float argument 
    sig2.connect(bind(slot(&func),20.0f));