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