sigc::scoped_connection Struct Reference

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

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.

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.