Communication systems

Communication Systems

1. nuiEvent: synchronous communication

We talk about the nuiEvent class in Let's-get-started.

2. nuiSignal: extended synchronous communication

Signals and Events have the same purpose. But unlike nuiEvent, a nuiSignal allows to transmit typed information.

2.1) declare a signal

class MyWidget: public nuiSimpleContainer
{
  [...]
  nuiSignal2<uint32, float> MySignal;
  [...]
};

In this example, the signal transmits two parameters and returns no value. The type of the parameters is totally up to the developer and depends on what you need to do in your program.

2.2) send a signal

void MyWidget::MyMethod()
{
  uint32 index;
  float value;

  [...] some code [...]

  MySignal(index, value); // send a signal
}

2.3) receiving a signal

first, declare the receiver in the class header, and the signal sink:

void MySignalReceiver(uint32 param1, float param2);

nuiSlotsSink mSink;

and then, implement the body in the cpp:

void MyClass::MySignalReceiver(uint32 param1, float param2)
{
  // process the signal here
}

Eventually, connect the signal to the receiver.
nui provides a system of delegates, that can be used for many purposes (see design documentation).
It is used here to connect a templated signal to a local receiver:

  mSlotsSink.Connect(GetTheSourceOfSignal().MySignal, nuiMakeDelegate(this, &MyClass::MySignalReceiver));

And there you go!

3. nuiNotification: asynchronous communication

nuiEvent and nuiSignal are provided for synchronous communication.
Sometimes you need to use the notifications instead: you need safe communication between threads, you want to centralize the process of a bunch of events instead of having a receiver for each of those, …

3.1) post a notification to a manager

#define MYNOTIF _T("mynotif")

void MyClass::MyMethod()
{
  [...]
  GetTopLevel()->PostNotification(new nuiNotification(MYNOTIF));
}

• You can define your own notification manager, but most of the time, using the one that is internal to the top level is recommended.
• You don’t have to worry about deleting the notifications, the manager does the house cleaning itself.

3.2) receive the notifications

The object intended to receive the notifications must Inherit from nuiNotificationObserver and overload the virtual OnNotification method.

class MyWidget : public nuiSimpleContainer, public nuiNotificationObserver
{
  [...]
private:

  // virtual from nuiWidget, through nuiSimpleContainer
  virtual void ConnectTopLevel();

  // virtual from nuiNotificationObserver
  virtual void OnNotification(const nuiNotification& rNotif);
};

void MyWidget::ConnectTopLevel()
{
    // subscribe to the notifications you want to catch and process in the OnNotification callback.
    nuiNotificationObserver::RegisterWithManager(GetMainWindow(), MYNOTIF);
}

void MyWidget::OnNotification(const nuiNotification& rNotif)
{
  const nglString& rName = rNotif.GetName();

  if (!rName.Compare(MYNOTIF))
  {
    // process your notification
    return;
  }

  // other notifications
}

The ConnectTopLevel virtual callback is important: it’s called when your object is fully connected to the GUI’s widget tree (i.e. sometimes after having been attached to its father).
It’s the right moment to make your notification observer subscribe to the notification manager (here, the main window), for the chosen notifications.