Signals and Slots

Detailed Description

Provides a means of decoupled communication across objects.

Signals and slots are a communication paradigm which resembles callback or listener models of communication but with added advantages due to looser coupling between objects. CYISignal represents a signal, an entity which may be emitted and which may carry data, and which can be easily connected to a CYISignalHandler's slots at runtime. When a signal is emitted the slot to which it is connected is called with parameters that may be carried by the signal.

It is common to see CYISignal objects in the public API for You.i Engine classes. For example, CYIPushButtonView derivatives use CYISignal emissions to report user actions such as button clicks.

Connecting to a CYISignal

Suppose there is a UI element which can be clicked by a user or have its text modified by an API. In both of these cases the element will signal that these events have occurred so that the application developer may respond accordingly.

class ButtonLabel
{
public:
    CYISignal<> Clicked;
    CYISignal<CYIString> TextChanged;
    ...
};

In this example the click and text changes will simply be logged by another class which is a CYISignalHandler.

class ButtonLabelEventLogger : public CYISignalHandler
{
public:
    void LogClick();
    void LogTextChange(CYIString labelText);
};

The connection between these objects is accomplished using CYISignal::Connect

void MyScreen::Init()
{
    ButtonLabel &button = GetButton();
    ButtonLabelEventLogger &logger = GetButtonLogger();

    button.Clicked.Connect(logger, &ButtonLabelEventLogger::LogClick);
    button.TextChanged.Connect(logger, &ButtonLabelEventLogger::LogTextChange);
}

Note that the parameter CYIString of ButtonLabelEventLogger::LogTextChange matches the template arguments to ButtonLabel::TextChanged. It's possible to connect a signal containing template arguments to a slot containing fewer parameters, but it is not possible to connect a signal containing few arguments to a slot containing many parameters. Up to four parameters may be passed in this manner between an object containing a CYISignal and a CYISignalHandler.

Emitting a CYISignal

Using the example above.

class ButtonLabel
{
    ...
    void OnButtonClicked(); // Called when the user has clicked on the button
    void SetLabelText(CYIString labelText); //Called by the developer to set the label.
}

The implementation of the functions demonstrates how to emit the signals using operator(), which is equivalent to using CYISignal::Emit.

void ButtonLabel::OnButtonClicked()
{
    Clicked(); //Or Clicked.Emit()
}

void ButtonLabel::SetLabelText(CYIString labelText)
{
    ...
    TextChanged(labelText);
}

Classes
class	CYISignalAbstractConnection
	The base abstract class for signal connections. More...
struct	YiSlotTypesContainer< T >
	A templated struct used to pass multiple parameter packs to a templated class specialization or to a templated function. More...
class	CYISignalBaseConnection< SignalTypes >
	The templated abstract class for signal connections. More...
class	CYISignal< SignalTypes >
	Signals and slots are a thread-safe and flexible communication framework that will allow various objects to transfer data synchronously or asynchronously in a highly decoupled manner. The classes that are using signals and slots do not need to share any interfaces to each other of each other. Signals and slots are also highly resilient against short lived objects: if a slot is deleted, the connection will detach automatically even while a CYISignal::Emit() is in progress, in which the deletion of the slot will be delayed. More...
class	CYISignalBase
	The base abstract class for CYISignal. More...
class	CYISignalConnectionID
	An object used to identify a specific CYISignal connection. More...
class	CYISignalHandler

Enumerations
enum	EYIConnectionType : uint8_t {   EYIConnectionType::Auto = 0,   EYIConnectionType::Sync,   EYIConnectionType::Async }

Enumeration Type Documentation

EYIConnectionType

enum EYIConnectionType : uint8_t

strong

CYISignal connection types for connections between CYISignal and slots.

Enumerator
Auto	This is the default connection mode. In this mode, the CYISignal will look at the slot's thread affinity to determine if it should call it directly (synchronously), or if it should be queued on the slot's thread (asynchronously) if a CYIEventDispatcher is running on that given thread. The slot affinity is determined by the thread that instantiated it. In other word, if the CYISignal and the CYISignalHandler are on the same thread, it will be treated as EYIConnectionType::Sync. If the CYISignal and the CYISignalHandler are on different threads, it will be treated as EYIConnectionType::Async. Note For connections to static functions, the context of the default system dispatcher is used (instead of the slot's thread, since static functions do not have an associated thread).
Sync	In this mode, emitting a signal will always call the slot directly using the CYISignal's caller context, but it is your responsibility to assure thread-safety in your slot implementation.
Async	This connection type will always queue the CYISignal onto the CYIEventDispatcher of the context in which the CYISignalHandler resides. If there are no event dispatcher running on the given context, the default application event dispatcher will be used. Note For connections to static functions, the context of the default system dispatcher is used (instead of the slot's thread, since static functions do not have an associated thread).