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_TRACKABLE_HPP_ 20 #define _SIGC_TRACKABLE_HPP_ 21 #include <list> 22 #include <sigc++config.h> 23 24 namespace sigc { 25 26 namespace internal { 27 28 typedef void* (*func_destroy_notify) (void* data); 29 30 /** Destroy notification callback. 31 * A destroy notification callback consists of a data pointer and a 32 * function pointer. The function is executed from the owning callback 33 * list (of type sigc::internal::trackable_callback_list) when its parent 34 * object (of type sigc::trackable) is destroyed or overwritten. 35 */ 36 struct SIGC_API trackable_callback 37 { 38 void* data_; 39 func_destroy_notify func_; trackable_callbacktrackable_callback40 trackable_callback(void* data, func_destroy_notify func) 41 : data_(data), func_(func) {} 42 }; 43 44 /** Callback list. 45 * A callback list holds an STL list of callbacks of type 46 * trackable_callback. Callbacks are added and removed with 47 * add_callback(), remove_callback() and clear(). The callbacks 48 * are invoked from clear() and from the destructor. 49 */ 50 struct SIGC_API trackable_callback_list 51 { 52 /** Add a callback function. 53 * @param data Data that will be sent as a parameter to teh callback function. 54 * @param func The callback function. 55 * 56 */ 57 void add_callback(void* data, func_destroy_notify func); 58 59 /** Remove the callback which has this data associated with it. 60 * @param data The data that was given as a parameter to add_callback(). 61 */ 62 void remove_callback(void* data); 63 64 /** This invokes all of the callback functions. 65 */ 66 void clear(); 67 trackable_callback_listtrackable_callback_list68 trackable_callback_list() 69 : clearing_(false) {} 70 71 /** This invokes all of the callback functions. 72 */ 73 ~trackable_callback_list(); 74 75 private: 76 typedef std::list<trackable_callback> callback_list; 77 callback_list callbacks_; 78 bool clearing_; 79 }; 80 81 } /* namespace internal */ 82 83 84 /** Base class for objects with auto-disconnection. 85 * trackable must be inherited when objects shall automatically 86 * invalidate slots referring to them on destruction. 87 * A slot built from a member function of a trackable derived 88 * type installs a callback that is invoked when the trackable object 89 * is destroyed or overwritten. 90 * 91 * add_destroy_notify_callback() and remove_destroy_notify_callback() 92 * can be used to manually install and remove callbacks when 93 * notification of the object dying is needed. 94 * 95 * notify_callbacks() invokes and removes all previously installed 96 * callbacks and can therefore be used to disconnect from all signals. 97 * 98 * Note that there is no virtual destructor. Don't use @p trackable* 99 * as pointer type for managing your data or the destructors of 100 * your derived types won't be called when deleting your objects. 101 * 102 * @ingroup signal 103 */ 104 struct SIGC_API trackable 105 { 106 trackable(); 107 108 trackable(const trackable& src); 109 110 trackable& operator=(const trackable& src); 111 112 ~trackable(); 113 114 /*virtual ~trackable() {} */ /* we would need a virtual dtor for users 115 who insist on using "trackable*" as 116 pointer type for their own derived objects */ 117 118 119 typedef internal::func_destroy_notify func_destroy_notify; 120 121 /** Add a callback that is executed (notified) when the trackable object is detroyed. 122 * @param data Passed into func upon notification. 123 * @param func Callback executed upon destruction of the object. 124 */ 125 void add_destroy_notify_callback(void* data, func_destroy_notify func) const; 126 127 /** Remove a callback previously installed with add_destroy_notify_callback(). 128 * The callback is not executed. 129 * @param data Parameter passed into previous call to add_destroy_notify_callback(). 130 */ 131 void remove_destroy_notify_callback(void* data) const; 132 133 /// Execute and remove all previously installed callbacks. 134 void notify_callbacks(); 135 136 #ifndef DOXYGEN_SHOULD_SKIP_THIS 137 private: 138 /* The callbacks are held in a list of type trackable_callback_list. 139 * This list is allocated dynamically when the first callback is added. 140 */ 141 internal::trackable_callback_list* callback_list() const; 142 mutable internal::trackable_callback_list* callback_list_; 143 #endif 144 }; 145 146 } /* namespace sigc */ 147 148 #endif /* _SIGC_TRACKABLE_HPP_ */ 149