lxgui::utils::signal< T > Class Template Reference

Generic class for observing and triggering events. More...

#include <utils_signal.hpp>

Public Types
using	function_type = std::function< T >
	Type of the callable function stored in a slot. Can use any function/delegate type here, as long as it has a matching call operator. The function type does not need to be owning; in this case, the slot must be manually disconnected whenever the pointed function is destroyed.
using	slot_list_view = utils::view::adaptor< slot_list, slot_dereferencer, non_disconnected_filter >
	Type of the view returned by slots().

Public Member Functions
	signal ()
	Default constructor (no slot).
	~signal ()
	Destructor.
	signal (const signal &)=delete
	signal (signal &&)=default
signal &	operator= (const signal &)=delete
signal &	operator= (signal &&)=default
void	disconnect_all () noexcept
	Disconnects all slots.
bool	empty () const noexcept
	Check if this signal contains any slot.
slot_list_view	slots () const noexcept
	Return a constant view onto the connected slots.
connection	connect (function_type function)
	Connect a new slot to this signal.
template<typename... Args>
void	operator() (Args &&... args)
	Trigger the signal.

Detailed Description

template<typename T>
class lxgui::utils::signal< T >

Generic class for observing and triggering events.

The implementation guarantees that the following is safe:

• Connecting or disconnecting a slot from inside any other slot (including self).
• Destroying the signal from any slot.
• Calling the signal recursively from any slot (up to standard stack exhaustion limits).

Other notable behaviors:

• Slots will be called in order of connection.
• Slots connected while the signal is being triggered will not be called until the next trigger of the signal.

Example:

// Create a signal. This can be called at any time,
// and will just forward its argument to all registered slots.
utils::signal<void(int)> sig;
 
// By default, no slot is registered, so calling does nothing.
sig(42); // nothing happens
 
// Register one slot that prints the value.
sig.connect([](int i) { std::cout << i << std::endl; });
sig(42); // prints 42
 
// We can register more than one slot; here we print a modified value.
sig.connect([](int i) { std::cout << 2*i << std::endl; });
sig(42); // prints 42 then 84
 
// We can use a connection to control when a slot is no longer called.
utils::connection c = sig.connect([](int i) { std::cout << 3*i << std::endl; });
sig(42); // prints 42, then 84, then 126
 
// Disconnect the last slot.
c.disconnect();
sig(42); // prints 42, then 84
 
// The safest way to do this is to use a scoped connection
int val = 0;
{
    utils::scoped_connection sc = sig.connect([](int i) { val = i; });
    sig(42); // prints 42, then 84, and stores 42 in val
}
 
// The last slot is automatically disconnected when out of scope.
sig(43); // prints 43, then 86; val is not changed

Definition at line 142 of file utils_signal.hpp.

Member Typedef Documentation

function_type

template<typename T >

using lxgui::utils::signal< T >::function_type = std::function<T>

Type of the callable function stored in a slot. Can use any function/delegate type here, as long as it has a matching call operator. The function type does not need to be owning; in this case, the slot must be manually disconnected whenever the pointed function is destroyed.

Definition at line 151 of file utils_signal.hpp.

slot_list_view

template<typename T >

using lxgui::utils::signal< T >::slot_list_view = utils::view::adaptor<slot_list, slot_dereferencer, non_disconnected_filter>

Type of the view returned by slots().

Definition at line 218 of file utils_signal.hpp.

Constructor & Destructor Documentation

signal() [1/3]

template<typename T >

lxgui::utils::signal< T >::signal ( )

inline

Default constructor (no slot).

Definition at line 222 of file utils_signal.hpp.

~signal()

template<typename T >

lxgui::utils::signal< T >::~signal ( )

inline

Destructor.

Definition at line 225 of file utils_signal.hpp.

signal() [2/3]

template<typename T >

lxgui::utils::signal< T >::signal ( const signal< T > &  )

delete

signal() [3/3]

template<typename T >

lxgui::utils::signal< T >::signal ( signal< T > &&  )

default

Member Function Documentation

connect()

template<typename T >

connection lxgui::utils::signal< T >::connect ( function_type  function )

inline

Connect a new slot to this signal.

Parameters

function

The function to store in the slot.

Returns

A connection object, which can be used to disconnect the slot at any time.

Note

If the returned connection object is discarded, the slot will remain connected for the entire lifetime of the signal, or until disconnect_all is called. If this is not desirable, store the returned connection, and disconnect the slot when it should no longer be called. The RAII helper class scoped_connection can do this safely.

Definition at line 283 of file utils_signal.hpp.

disconnect_all()

template<typename T >

void lxgui::utils::signal< T >::disconnect_all ( )

inlinenoexcept

Disconnects all slots.

Definition at line 238 of file utils_signal.hpp.

empty()

template<typename T >

bool lxgui::utils::signal< T >::empty ( ) const

inlinenoexcept

Check if this signal contains any slot.

Returns

'true' if at least one slot is connected.

Definition at line 258 of file utils_signal.hpp.

operator()()

template<typename T >

template<typename... Args>

void lxgui::utils::signal< T >::operator() ( Args &&...  args )

inline

Trigger the signal.

Parameters

args	Arguments to forward to all the connected slots.

Definition at line 293 of file utils_signal.hpp.

operator=() [1/2]

template<typename T >

signal & lxgui::utils::signal< T >::operator= ( const signal< T > &  )

delete

operator=() [2/2]

template<typename T >

signal & lxgui::utils::signal< T >::operator= ( signal< T > &&  )

default

slots()

template<typename T >

slot_list_view lxgui::utils::signal< T >::slots ( ) const

inlinenoexcept

Return a constant view onto the connected slots.

Returns

A constant view onto the connected slots

Warning

Do not attempt to connect or disconnect slots while iterating over this view.

Definition at line 269 of file utils_signal.hpp.

---

The documentation for this class was generated from the following file:

• /home/runner/work/lxgui/lxgui/include/lxgui/utils_signal.hpp