2.7. Signals

Signals, also known as callbacks, can be connected to methods of objects (or functions), which will be called later when the signal is triggered.

For example in case you want to invoke the method 'print()' of an object, when a button labled 'Print Document' is pressed in a dialog.

2.7.1. All connect and disconnect variants

// connect a signal with a function:
TSignalLink* connect(TSignal &sig, F *function);
// connect a signla with an objects method
TSignalLink* connect(TSignal &sig, O *object, M *method);  

// remove all connections from a signal
void disconnect(TSignal &sig);
// remove all connections to a function
void disconnect(TSignal &sig, F *function);
// remove all connections to an object
void disconnect(TSignal &sig, O *object);
// remove all connections to an objects method
void disconnect(TSignal &sig, O *object, M *method);

// variants to connect with functions/method which take one or two parameters
TSignalLink* connect(TSignal &sig, F *function, P1 param1);
TSignalLink* connect(TSignal &sig, F *function, P1 param1, P2 param2);
TSignalLink* connect(TSignal &sig, O *object, M *method, P1 param1);
TSignalLink* connect(TSignal &sig, O *object, M *method, P1 param1, P2 param2);
Please note that the value of the parameter in the last four connect is defined when making the connection. In case the function or method needs to use a variable value, it must retrieve it from somewhere else, ie. an object which was specifed when creating the connection as a parameter.

2.7.2. Signal example

The example program below shows how to connect and trigger a signals:

#include <string>
#include <iostream>
#include <toad/connect.hh>

using namespace toad;
using namespace std;

class TMyButton
{
  public:
    TSignal sigActivated;
};

class TMyLauncher
{
  public:
    void launchApplication(const char *name) {
      cerr << "launch application " << name << endl;
    }
};

int main(int argc, char **argv, char **envv) 
{
  TMyButton button;
  TMyLauncher launch;
  
  // call an objects member function, with a given argument
  connect(button.sigActivated, 
          &launch, &TMyLauncher::launchApplication, "ls");
          
  // call the C libraries 'void exit(int status)' function
  connect(button.sigActivated, &exit, 0);
  
  // trigger the signal's connection in the order they were added
  button.sigActivated();
  
  cerr << "i'm not reached" << endl;

  return 0;
}

2.7.3. Lock/Unlock a Signal

In some situations it might be usefull to block a signal for a while. Ie. when implementing an observer pattern, an object might have multiple methods to change different aspects of the object and each time the objects signal triggered.

Calling the signals lock() method will prevent triggering the object. Instead a flag will be set that it was tried to trigger the signal and when calling the signals unlock() later, it will be triggered only once.

A signal which wasn't tried to be triggered between lock() and unlock() will not be triggered by unlock().