2 * Copyright 2002, The libsigc++ Development Team
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.
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.
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
19 #ifndef _SIGC_TRACKABLE_HPP_
20 #define _SIGC_TRACKABLE_HPP_
22 #include <sigc++config.h>
28 typedef void* (*func_destroy_notify) (void* data);
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.
36 struct SIGC_API trackable_callback
39 func_destroy_notify func_;
40 trackable_callback(void* data, func_destroy_notify func) noexcept
41 : data_(data), func_(func) {}
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.
50 struct SIGC_API trackable_callback_list
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.
57 void add_callback(void* data, func_destroy_notify func);
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().
62 void remove_callback(void* data);
64 /** This invokes all of the callback functions.
68 trackable_callback_list()
71 trackable_callback_list(const trackable_callback_list& src) = delete;
72 trackable_callback_list& operator=(const trackable_callback_list& src) = delete;
73 trackable_callback_list(trackable_callback_list&& src) = delete;
74 trackable_callback_list& operator=(trackable_callback_list&& src) = delete;
76 /** This invokes all of the callback functions.
78 ~trackable_callback_list();
81 typedef std::list<trackable_callback> callback_list;
82 callback_list callbacks_;
86 } /* namespace internal */
89 /** Base class for objects with auto-disconnection.
90 * trackable must be inherited when objects shall automatically
91 * invalidate slots referring to them on destruction.
92 * A slot built from a member function of a trackable derived
93 * type installs a callback that is invoked when the trackable object
94 * is destroyed or overwritten.
96 * add_destroy_notify_callback() and remove_destroy_notify_callback()
97 * can be used to manually install and remove callbacks when
98 * notification of the object dying is needed.
100 * notify_callbacks() invokes and removes all previously installed
101 * callbacks and can therefore be used to disconnect from all signals.
103 * Note that there is no virtual destructor. Don't use @p trackable*
104 * as pointer type for managing your data or the destructors of
105 * your derived types won't be called when deleting your objects.
109 struct SIGC_API trackable
111 // Concerning noexcept specifications:
112 // libsigc++ does not have complete control of what happens when notify_callbacks()
113 // is called. It may throw an exception. A method that calls notify_callbacks()
114 // shall not be declared noexcept.
116 trackable() noexcept;
118 trackable(const trackable& src) noexcept;
120 trackable(trackable&& src);
122 trackable& operator=(const trackable& src);
124 trackable& operator=(trackable&& src);
128 /*virtual ~trackable() {} */ /* we would need a virtual dtor for users
129 who insist on using "trackable*" as
130 pointer type for their own derived objects */
132 typedef internal::func_destroy_notify func_destroy_notify;
134 /** Add a callback that is executed (notified) when the trackable object is detroyed.
135 * @param data Passed into func upon notification.
136 * @param func Callback executed upon destruction of the object.
138 void add_destroy_notify_callback(void* data, func_destroy_notify func) const;
140 /** Remove a callback previously installed with add_destroy_notify_callback().
141 * The callback is not executed.
142 * @param data Parameter passed into previous call to add_destroy_notify_callback().
144 void remove_destroy_notify_callback(void* data) const;
146 /// Execute and remove all previously installed callbacks.
147 void notify_callbacks();
149 #ifndef DOXYGEN_SHOULD_SKIP_THIS
151 /* The callbacks are held in a list of type trackable_callback_list.
152 * This list is allocated dynamically when the first callback is added.
154 internal::trackable_callback_list* callback_list() const;
155 mutable internal::trackable_callback_list* callback_list_;
159 } /* namespace sigc */
161 #endif /* _SIGC_TRACKABLE_HPP_ */