Skip to content

KDBindings::Signal

A Signal provides a mechanism for communication between objects. More...

#include <signal.h>

Public Functions

Name
Signal() =default
Signal(const Signal & ) =delete
Signal(Signal && other) =default
~Signal()
bool blockConnection(const ConnectionHandle & handle, bool blocked)
template <typename Func ,typename... FuncArgs,typename =std::enable_if_t>>, std::integral_constant\>>>
ConnectionHandle		 connect(Func && slot, FuncArgs &&... args)
ConnectionHandle connect(std::function< void(Args...)> const & slot)
void disconnect(const ConnectionHandle & handle)
void disconnectAll()
void emit(Args... p) const
bool isConnectionBlocked(const ConnectionHandle & handle) const
Signal & operator=(Signal && other) =default
Signal & operator=(Signal const & other) =delete

Friends

Name
class ConnectionHandle

Detailed Description

1
2
template <typename... Args>
class KDBindings::Signal;

A Signal provides a mechanism for communication between objects.

KDBindings::Signal recreates the Qt's Signals & Slots mechanism in pure C++17. A Signal can be used to notify any number of slots that a certain event has occurred.

The slot can be almost any callable object, including member functions and lambdas.

This connection happens in a type-safe manner, as a slot can only be connected to a Signal when the arguments of the slot match the values the Signal emits.

The Args type parameter pack describe which value types the Signal will emit.

Examples:

Public Functions Documentation

function Signal

1
Signal() =default

Signals are default constructible

function Signal

1
2
3
Signal(
    const Signal & 
) =delete

Signals cannot be copied.

function Signal

1
2
3
Signal(
    Signal && other
) =default

Signals can be moved

function ~Signal

1
inline ~Signal()

A signal disconnects all slots when it is destructed

Therefore, all active ConnectionHandles that belonged to this Signal will no longer be active (i.e. ConnectionHandle::isActive will return false).

function blockConnection

1
2
3
4
inline bool blockConnection(
    const ConnectionHandle & handle,
    bool blocked
)

Parameters:

  • blocked Whether the connection should be blocked from now on.
  • handle The ConnectionHandle to block.

Exceptions:

Return: Whether the connection was previously blocked.

Sets the block state of the connection. If a connection is blocked, emitting the Signal will no longer call this connections slot, until the connection is unblocked.

ConnectionHandle::block can be used as an alternative.

To temporarily block a connection, consider using an instance of ConnectionBlocker, which offers a RAII-style implementation that makes sure the connection is always returned to its original state.

function connect

1
2
3
4
5
6
7
template <typename Func ,
typename... FuncArgs,
typename  =std::enable_if_t<std::disjunction_v<std::negation<std::is_convertible<Func, std::function<void(Args...)>>>, std::integral_constant<bool, sizeof...(FuncArgs) >>>>
inline ConnectionHandle connect(
    Func && slot,
    FuncArgs &&... args
)

Return: An instance of a Signal::ConnectionHandle that refers to this connection. Warning: When connecting a member function you must use the returned ConnectionHandle to disconnect when the object containing the slot goes out of scope!

A template overload of Signal::connect that makes it easier to connect arbitrary functions to this Signal. It connects a function to this Signal, binds any provided arguments to that function and discards any values emitted by this Signal that aren't needed by the resulting function.

This is especially useful for connecting member functions to signals.

Examples: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
Signal<int> signal;
std::vector<int> numbers{ 1, 2, 3 };
bool emitted = false;

// disambiguation necessary, as push_back is overloaded.
void (std::vector<int>::*push_back)(const int &) = &std::vector<int>::push_back;
signal.connect(push_back, &numbers);

// this slot doesn't require the int argument, so it will be discarded.
signal.connect([&emitted]() { emitted = true; });

signal.emit(4); // Will add 4 to the vector and set emitted to true

For more examples see the 07-advanced-connections/main.cpp example.

function connect

1
2
3
inline ConnectionHandle connect(
    std::function< void(Args...)> const & slot
)

Return: An instance of ConnectionHandle, that can be used to disconnect or temporarily block the connection.

Connects a std::function to the signal.

When emit() is called on the Signal, the functions will be called with the arguments provided to emit().

function disconnect

1
2
3
inline void disconnect(
    const ConnectionHandle & handle
)

Exceptions:

Disconnect a previously connected slot.

After the slot was successfully disconnected, the ConnectionHandle will no longer be active. (i.e. ConnectionHandle::isActive will return false).

function disconnectAll

1
inline void disconnectAll()

Disconnect all previously connected functions.

All currently active ConnectionHandles that belong to this Signal will no longer be active afterwards. (i.e. ConnectionHandle::isActive will return false).

function emit

1
2
3
inline void emit(
    Args... p
) const

Emits the Signal, which causes all connected slots to be called, as long as they are not blocked.

The arguments provided to emit will be passed to each slot by copy, therefore consider using (const) references as the Args to the Signal wherever possible.

Note: Slots may disconnect themselves during an emit, however it is undefined whether a slot that is connected during the emit function of the Signal will also be called during this emit, or only at the next emit.

function isConnectionBlocked

1
2
3
inline bool isConnectionBlocked(
    const ConnectionHandle & handle
) const

Exceptions:

Return: Whether the connection is currently blocked

Checks whether the connection is currently blocked.

To change the blocked state of a connection, call blockConnection().

function operator=

1
2
3
Signal & operator=(
    Signal && other
) =default

function operator=

1
2
3
Signal & operator=(
    Signal const & other
) =delete

Friends

friend ConnectionHandle

1
2
3
friend class ConnectionHandle(
    ConnectionHandle 
);

Updated on 2024-07-13 at 00:00:32 +0000