KDBindings::ConnectionHandle Class Reference

A ConnectionHandle represents the connection of a Signal to a slot (i.e. a function that is called when the Signal is emitted). More...

#include <connection_handle.h>

Public Member Functions
	ConnectionHandle ()=default
	ConnectionHandle (ConnectionHandle &&) noexcept=default
	ConnectionHandle (const ConnectionHandle &) noexcept=default
template<typename... Args>
bool	belongsTo (const Signal< Args... > &signal) const
bool	block (bool blocked)
void	disconnect () noexcept
bool	isActive () const
bool	isBlocked () const
ConnectionHandle &	operator= (ConnectionHandle &&) noexcept=default
ConnectionHandle &	operator= (const ConnectionHandle &) noexcept=default
bool	operator== (const ConnectionHandle &other) const
void	release () const

Detailed Description

A ConnectionHandle represents the connection of a Signal to a slot (i.e. a function that is called when the Signal is emitted).

It is returned from a Signal when a connection is created and used to manage the connection by disconnecting, (un)blocking it and checking its state.

Definition at line 54 of file connection_handle.h.

Constructor & Destructor Documentation

ConnectionHandle() [1/3]

KDBindings::ConnectionHandle::ConnectionHandle ( )

default

A ConnectionHandle can be default constructed. In this case the ConnectionHandle will not reference any active connection (i.e. isActive() will return false), and not belong to any Signal.

ConnectionHandle() [2/3]

KDBindings::ConnectionHandle::ConnectionHandle ( const ConnectionHandle &  )

defaultnoexcept

A ConnectionHandle can be copied.

ConnectionHandle() [3/3]

KDBindings::ConnectionHandle::ConnectionHandle ( ConnectionHandle &&  )

defaultnoexcept

A ConnectionHandle can be moved.

Member Function Documentation

belongsTo()

template<typename... Args>

bool KDBindings::ConnectionHandle::belongsTo ( const Signal< Args... > &  signal ) const

inline

Check whether this ConnectionHandle belongs to the given Signal.

Returns

true if this ConnectionHandle refers to a connection within the given Signal

Definition at line 157 of file connection_handle.h.

Referenced by KDBindings::Signal< Args >::blockConnection(), KDBindings::Signal< Args >::disconnect(), and KDBindings::Signal< Args >::isConnectionBlocked().

block()

bool KDBindings::ConnectionHandle::block ( bool  blocked )

inline

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.

Behaves the same as calling Signal::blockConnection with this ConnectionHandle as argument.

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.

Parameters

blocked

The new blocked state of the connection.

Returns

whether the connection was previously blocked.

Exceptions

std::out_of_range

Throws if the connection is not active (i.e. isActive() returns false).

Definition at line 128 of file connection_handle.h.

Referenced by KDBindings::ConnectionBlocker::ConnectionBlocker().

disconnect()

void KDBindings::ConnectionHandle::disconnect ( )

inlinenoexcept

Disconnect the slot.

When this function is called, the function that was passed to Signal::connect to create this ConnectionHandle will no longer be called when the Signal is emitted.

If the ConnectionHandle is not active or the connection has already been disconnected, nothing happens.

After this call, the ConnectionHandle will be inactive (i.e. isActive() returns false) and will no longer belong to any Signal (i.e. belongsTo returns false).

Warning

While this function is marked with noexcept, it may terminate the program if it is not possible to allocate memory or if mutex locking isn't possible.

Definition at line 91 of file connection_handle.h.

isActive()

bool KDBindings::ConnectionHandle::isActive ( ) const

inline

Check whether the connection of this ConnectionHandle is active.

Returns

true if the ConnectionHandle refers to an active Signal and the connection was not disconnected previously, false otherwise.

Definition at line 107 of file connection_handle.h.

isBlocked()

bool KDBindings::ConnectionHandle::isBlocked ( ) const

inline

Checks whether the connection is currently blocked.

To change the blocked state of a connection, call ConnectionHandle::block.

Returns

whether the connection is currently blocked.

Definition at line 143 of file connection_handle.h.

operator=() [1/2]

ConnectionHandle& KDBindings::ConnectionHandle::operator= ( ConnectionHandle &&  )

defaultnoexcept

operator=() [2/2]

ConnectionHandle& KDBindings::ConnectionHandle::operator= ( const ConnectionHandle &  )

defaultnoexcept

operator==()

bool KDBindings::ConnectionHandle::operator== ( const ConnectionHandle &  other ) const

inline

Definition at line 164 of file connection_handle.h.

release()

void KDBindings::ConnectionHandle::release ( ) const

inline

This function exists to intentionally silence the [[nodiscard]] warning generated when connecting.

In cases where you know for certain that the lifetime of the signal does not extend beyond the lifetime of the slot, you may not need the ConnectionHandle, so you can use release to discard it.

Example:

bool called = false;
{
    Signal<int> mySignal;
    // The signal will not outlive the reference to the `called` bool, so it's fine to ignore the ConnectionHandle.
    mySignal.connect([&called](){ called = true; }).release();
}

Definition at line 198 of file connection_handle.h.

---

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

• connection_handle.h