sigc++/connection.h

   1 /*
   2  * Copyright 2002, The libsigc++ Development Team
   3  *
   4  *  This library is free software; you can redistribute it and/or
   5  *  modify it under the terms of the GNU Lesser General Public
   6  *  License as published by the Free Software Foundation; either
   7  *  version 2.1 of the License, or (at your option) any later version.
   8  *
   9  *  This library is distributed in the hope that it will be useful,
  10  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  12  *  Lesser General Public License for more details.
  13  *
  14  *  You should have received a copy of the GNU Lesser General Public
  15  *  License along with this library; if not, write to the Free Software
  16  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  17  *
  18  */
  19 #ifndef _SIGC_CONNECTION_HPP_
  20 #define _SIGC_CONNECTION_HPP_
  21 #include <sigc++config.h>
  22 #include <sigc++/signal.h>
  23
  24 namespace sigc {
  25
  26 /** Convinience class for safe disconnection.
  27  * Iterators must not be used beyond the lifetime of the list
  28  * they work on. A connection object can be created from a
  29  * slot list iterator and may safely be used to disconnect
  30  * the referred slot at any time (disconnect()). If the slot
  31  * has already been destroyed, disconnect() does nothing. empty() or
  32  * operator bool() can be used to test whether the connection is
  33  * still active. The connection can be blocked (block(), unblock()).
  34  *
  35  * This is possible because the connection object gets notified
  36  * when the referred slot dies (notify()).
  37  *
  38  * @ingroup signal
  39  */
  40 struct SIGC_API connection
  41 {
  42   /** Constructs an empty connection object. */
  43   connection() noexcept;
  44
  45   /** Constructs a connection object copying an existing one.
  46    * @param c The connection object to make a copy from.
  47    */
  48   connection(const connection& c);
  49
  50   /** Constructs a connection object from a slot list iterator.
  51    * @param it The slot list iterator to take the slot from.
  52    */
  53   template <typename T_slot>
  54   connection(const slot_iterator<T_slot>& it) : slot_(&(*it))
  55     { if (slot_) slot_->add_destroy_notify_callback(this, &notify); }
  56
  57   /** Constructs a connection object from a slot object.
  58    * This is only useful if you create your own slot list.
  59    * @param sl The slot to operate on.
  60    */
  61   explicit connection(slot_base& sl);
  62
  63   /** Overrides this connection object copying another one.
  64    * @param c The connection object to make a copy from.
  65    */
  66   connection& operator=(const connection& c);
  67
  68   /** Overrides this connection object with another slot list iterator.
  69    * @param it The new slot list iterator to take the slot from.
  70    */
  71   template <typename T_slot>
  72   connection& operator=(const slot_iterator<T_slot>& it)
  73     { set_slot(&(*it)); return *this; }
  74
  75   ~connection();
  76
  77   /** Returns whether the connection is still active.
  78    * @return @p false if the connection is still active.
  79    */
  80   bool empty() const noexcept;
  81
  82   /** Returns whether the connection is still active.
  83    * @return @p true if the connection is still active.
  84    */
  85   bool connected() const noexcept;
  86
  87   /** Returns whether the connection is blocked.
  88    * @return @p true if the connection is blocked.
  89    */
  90   bool blocked() const noexcept;
  91
  92   /** Sets or unsets the blocking state of this connection.
  93    * See slot_base::block() for details.
  94    * @param should_block Indicates whether the blocking state should be set or unset.
  95    * @return @p true if the connection has been in blocking state before.
  96    */
  97   bool block(bool should_block = true) noexcept;
  98
  99   /** Unsets the blocking state of this connection.
 100    * @return @p true if the connection has been in blocking state before.
 101    */
 102   bool unblock() noexcept;
 103
 104   /// Disconnects the referred slot.
 105   void disconnect();
 106
 107   //TODO: When we can break API and ABI, make operator bool() const
 108   /** Returns whether the connection is still active.
 109    * @return @p true if the connection is still active.
 110    */
 111   explicit operator bool() noexcept;
 112
 113   /** Callback that is executed when the referred slot is destroyed.
 114    * @param data The connection object notified (@p this).
 115    */
 116   static void* notify(void* data);
 117
 118 private:
 119   void set_slot(slot_base* sl);
 120
 121   /* Referred slot. Set to zero from notify().
 122    * A value of zero indicates an "empty" connection.
 123    */
 124   slot_base* slot_;
 125 };
 126
 127 } /* namespace sigc */
 128
 129
 130 #endif /* _SIGC_TRACKABLE_HPP_ */