libsigc++: sigc::scoped_connection Struct Reference

libsigc++ 3.8.1

Public Member Functions | List of all members
sigc::scoped_connection Struct Referencefinal
Signals

Convenience class for safe disconnection, including automatic disconnection upon destruction. More...

`#include <sigc++/scoped_connection.h>`

## Public Member Functions
| scoped_connection () noexcept=default
| Constructs an empty scoped connection object.
| scoped_connection (connection c) noexcept
| Constructs a scoped connection object from an unscoped connection object.
| scoped_connection (const scoped_connection &)=delete
| scoped_connection canʼt be copied as it would confuse ownership—see intro.
| scoped_connection (scoped_connection &&sc) noexcept
| Constructs a scoped connection object moving an existing one.
| ~scoped_connection ()
| scoped_connection disconnects the referred slot, if any, upon destruction.
bool | block (bool should_block=true) noexcept
| Sets or unsets the blocking state of this connection.
bool | blocked () const noexcept
| Returns whether the connection is blocked.
bool | connected () const noexcept
| Returns whether the connection is still active.
void | disconnect ()
| Disconnects the referred slot. This will also happen upon destruction.
bool | empty () const noexcept
| Returns whether the connection is still active.
| operator bool () const noexcept
| Returns whether the connection is still active.
scoped_connection & | operator= (connection c)
| Overrides this scoped connection object copying an unscoped connection.
scoped_connection & | operator= (const scoped_connection &)=delete
| scoped_connection canʼt be copied as it would confuse ownership—see intro.
scoped_connection & | operator= (scoped_connection &&sc)
| Overrides this scoped connection object moving another one.
connection | release () noexcept
| Releases the connection from a scoped connection object.
bool | unblock () noexcept
| Unsets the blocking state of this connection.

## Detailed Description

Convenience class for safe disconnection, including automatic disconnection upon destruction.

This is a variant of sigc::connection which also disconnect()s the slot automatically when the scoped_connection is destructed or re-assigned. Refer to sigc::connection for full information about the common functionality.

You will use sigc::scoped_connection by constructing it from a ‘normal’, unscoped sigc::connection, such as those returned by sigc::signal::connect() and sigc::signal::connect_first(), thus ‘wrapping’ the connection in a scoped_connection, adding auto-disconnection. It can also be assigned from an unscoped connection, in which case, if there was a previous slot referred to by the scoped connection, it is disconnected.

Once a connection is scoped, it canʼt be copied as that would make it unclear which of the copies would hold responsibility to auto-disconnect the slot. It can, however, be moved, so itʼs usable in containers or so ‘ownership’ of the connection/auto-disconnect can be moved to another instance. Moving from the scoped_connection clears its reference to the slot so it wonʼt disconnect it.

If you want a reference-counted scoped_connection, wrap in a std::shared_ptr.

// Automatic disconnection:
{
sigc::scoped_connection sconn = sig.connect(&some_function);
// Do stuff that requires the slot to be connected & called.
}
// The scoped_connection was destroyed, so the slot is no longer connected.
// ***
// Moving ownership:
{
sigc::scoped_connection sconn = sig.connect(&some_function);
// Do stuff that requires the slot to be connected & called.
take_ownership(std::move(sconn)); // Pass by rvalue.
}
// Now our `sconn` no longer referred to slot, so it did NOT auto-disconnect.
// ***
// Shared ownership:
{
auto shconn = std::make_shared<sigc::scoped_connection>(sig.connect(&some_function));
take_copy(shconn); // Pass by copy/value
// Now we AND take_copy() must destroy our shared_ptr to auto-disconnect().
}
// take_copy() may still hold a shared_ptr reference, keeping the slot alive.
std::move
constexpr _OI move(_II __first, _II __last, _OI __result)
std::ptr_fun
pointer_to_unary_function< _Arg, _Result > ptr_fun(_Result(*__x)(_Arg))
sigc::ptr_fun
decltype(auto) ptr_fun(T_return(*func)(T_args...))
Creates a functor of type sigc::pointer_functor which wraps an existing non-member function.
Definition ptr_fun.h:107
sigc::scoped_connection
Convenience class for safe disconnection, including automatic disconnection upon destruction.
Definition scoped_connection.h:81

Since libsigc++ 3.6:

## Constructor & Destructor Documentation

## ◆ scoped_connection() [1/4]

sigc::scoped_connection::scoped_connection | ( |  | ) |
| defaultnoexcept

Constructs an empty scoped connection object.

## ◆ scoped_connection() [2/4]

sigc::scoped_connection::scoped_connection | ( | connection | c | ) |
| noexcept

Constructs a scoped connection object from an unscoped connection object.

The source connection still refers to the slot and can manually disconnect.

Parameters

  c | The connection object to make a copy from, whose slot weʼll automatically disconnect when the scoped_connection object is destroyed.

## ◆ scoped_connection() [3/4]

sigc::scoped_connection::scoped_connection | ( | const scoped_connection & |  | ) |
| delete

scoped_connection canʼt be copied as it would confuse ownership—see intro.

## ◆ scoped_connection() [4/4]

sigc::scoped_connection::scoped_connection | ( | scoped_connection && | sc | ) |
| noexcept

Constructs a scoped connection object moving an existing one.

The source scoped connection will no longer refer to / disconnect the slot.

Parameters

  sc | The scoped connection object to move from.

## ◆ ~scoped_connection()

sigc::scoped_connection::~scoped_connection | ( |  | ) |

scoped_connection disconnects the referred slot, if any, upon destruction.

## Member Function Documentation

## ◆ block()

bool sigc::scoped_connection::block | ( | bool | should_block = `true` | ) |
| noexcept

Sets or unsets the blocking state of this connection.

See slot_base::block() for details.

Parameters

  should_block | Indicates whether the blocking state should be set or unset.

Returns
  `true` if the connection has been in blocking state before.

## ◆ blocked()

bool sigc::scoped_connection::blocked | ( |  | ) | const
| noexcept

Returns whether the connection is blocked.

Returns
  `true` if the connection is blocked.

## ◆ connected()

bool sigc::scoped_connection::connected | ( |  | ) | const
| noexcept

Returns whether the connection is still active.

Returns
  `true` if the connection is still active.

## ◆ disconnect()

void sigc::scoped_connection::disconnect | ( |  | ) |

Disconnects the referred slot. This will also happen upon destruction.

## ◆ empty()

bool sigc::scoped_connection::empty | ( |  | ) | const
| noexcept

Returns whether the connection is still active.

Returns
  `false` if the connection is still active.

## ◆ operator bool()

sigc::scoped_connection::operator bool | ( |  | ) | const
| explicitnoexcept

Returns whether the connection is still active.

Returns
  `true` if the connection is still active.

## ◆ operator=() [1/3]

scoped_connection & sigc::scoped_connection::operator= | ( | connection | c | ) |

Overrides this scoped connection object copying an unscoped connection.

The current slot, if any, will be disconnect()ed before being replaced. The source connection still refers to the slot and can manually disconnect.

Parameters

  c | The connection object to make a copy from, whose slot weʼll automatically disconnect when the scoped_connection object is destroyed.

## ◆ operator=() [2/3]

scoped_connection & sigc::scoped_connection::operator= | ( | const scoped_connection & |  | ) |
| delete

scoped_connection canʼt be copied as it would confuse ownership—see intro.

## ◆ operator=() [3/3]

scoped_connection & sigc::scoped_connection::operator= | ( | scoped_connection && | sc | ) |

Overrides this scoped connection object moving another one.

The current slot, if any, will be disconnect()ed before being replaced. The source scoped connection will no longer refer to / disconnect the slot.

Parameters

  sc | The scoped connection object to move from.

## ◆ release()

connection sigc::scoped_connection::release | ( |  | ) |
| noexcept

Releases the connection from a scoped connection object.

The scoped connection will no longer refer to / disconnect the slot.

Returns
  An unscoped connection object referring to the same slot.

## ◆ unblock()

bool sigc::scoped_connection::unblock | ( |  | ) |
| noexcept

Unsets the blocking state of this connection.

Returns
  `true` if the connection has been in blocking state before.