1
# This file is part of the Frescobaldi project, http://www.frescobaldi.org/
3
# Copyright (c) 2008 - 2011 by Wilbert Berendsen
5
# This program is free software; you can redistribute it and/or
6
# modify it under the terms of the GNU General Public License
7
# as published by the Free Software Foundation; either version 2
8
# of the License, or (at your option) any later version.
10
# This program is distributed in the hope that it will be useful,
11
# but WITHOUT ANY WARRANTY; without even the implied warranty of
12
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13
# GNU General Public License for more details.
15
# You should have received a copy of the GNU General Public License
16
# along with this program; if not, write to the Free Software
17
# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
18
# See http://www.gnu.org/licenses/ for more information.
21
A simple signal/slot implementation.
34
"""A Signal can be emitted and receivers (slots) can be connected to it.
38
class MyObject(object):
40
somethingChanged = Signal()
45
def doSomething(self):
47
self.somethingChanged("Hi there!") # emit the signal
50
print "Received message:", arg
54
>>> o.somethingChanged.connect(receiver)
58
A Signal() can be used directly or as a class attribute, but can also be
59
accessed as an attribute of an instance, in which case it creates a Signal
60
instance for that instance.
62
The signal is emitted by the emit() method or by simply invoking it.
64
It is currently not possible to enforce argument types that should be used
65
when emitting the signal. But if called methods or functions expect fewer
66
arguments than were given on emit(), the superfluous arguments are left out.
68
Methods or functions are connected using connect() and disconnected using
69
disconnect(). It is no problem to call connect() or disconnect() more than
70
once for the same function or method. Only one connection to the same method
71
or function can exist.
75
def __init__(self, owner=None):
76
"""Creates the Signal.
78
If owner is given (must be a keyword argument) a weak reference to it is
79
kept, and this allows a Signal to be connected to another Signal. When
80
the owner dies, the connection is removed.
85
self._owner = weakref.ref(owner) if owner else lambda: None
87
def __get__(self, instance, cls):
88
"""Called when accessing as a descriptor: returns another instance."""
92
return self._instances[instance]
93
except AttributeError:
94
self._instances = weakref.WeakKeyDictionary()
97
ret = self._instances[instance] = Signal(owner=instance)
101
"""Returns the owner of this Signal, if any."""
104
def connect(self, slot, priority=0, owner=None):
105
"""Connects a method or function ('slot') to this Signal.
107
The priority argument determines the order the connected slots are
108
called. A lower value calls the slot earlier.
109
If owner is given, the connection will be removed if owner is garbage
112
A slot that is already connected will not be connected twice.
114
If slot is an instance method (bound method), the Signal keeps no
115
reference to the object the method belongs to. So if the object is
116
garbage collected, the signal is automatically disconnected.
118
If slot is a (normal or lambda) function, the Signal will keep a
119
reference to the function. If you want to have the function disconnected
120
automatically when some object dies, you should provide that object
121
through the owner argument. Be sure that the connected function does not
122
keep a reference to that object in that case!
125
key = makeListener(slot, owner)
126
if key not in self.listeners:
127
key.add(self, priority)
129
def disconnect(self, func):
130
"""Disconnects the method or function.
132
No exception is raised if there wasn't a connection.
135
key = makeListener(func)
137
self.listeners.remove(key)
142
"""Removes all connected slots."""
143
del self.listeners[:]
145
@contextlib.contextmanager
147
"""Returns a contextmanager that suppresses the signal.
149
An example (continued from the class documentation):
152
>>> o.somethingChanged.connect(receiver)
153
>>> with o.somethingChanged.blocked():
157
The doSomething() method will emit the signal but the connected slots
161
blocked, self._blocked = self._blocked, True
165
self._blocked = blocked
167
def emit(self, *args, **kwargs):
170
Unless blocked, all slots will be called with the supplied arguments.
173
if not self._blocked:
174
for l in self.listeners[:]:
180
def makeListener(func, owner=None):
181
if isinstance(func, (types.MethodType, types.BuiltinMethodType)):
182
return MethodListener(func)
183
elif isinstance(func, Signal):
184
return FunctionListener(func, owner or func.owner())
186
return FunctionListener(func, owner)
189
class ListenerBase(object):
190
def __lt__(self, other):
191
return self.priority < other.priority
193
def add(self, signal, priority):
194
self.priority = priority
195
bisect.insort_right(signal.listeners, self)
196
if self.obj is not None:
197
def remove(wr, selfref=weakref.ref(self), sigref=weakref.ref(signal)):
198
self, signal = selfref(), sigref()
200
signal.listeners.remove(self)
201
self.obj = weakref.ref(self.obj, remove)
203
nargs = self.func.func_code.co_argcount
204
except AttributeError:
205
self.argslice = slice(0, None)
207
self.argslice = slice(0, nargs - self.removeargs)
210
class MethodListener(ListenerBase):
212
def __init__(self, meth):
213
self.obj = meth.__self__
214
self.objid = id(meth.__self__)
216
self.func = meth.__func__
217
except AttributeError:
218
# c++ methods from PyQt4 object sometimes do not have the __func__ attribute
219
self.func = getattr(meth.__self__.__class__, meth.__name__)
221
def __eq__(self, other):
222
return self.__class__ is other.__class__ and self.objid == other.objid and self.func is other.func
224
def call(self, args, kwargs):
227
self.func(obj, *args[self.argslice], **kwargs)
230
class FunctionListener(ListenerBase):
232
def __init__(self, func, owner=None):
236
def __eq__(self, other):
237
return self.__class__ is other.__class__ and self.func is other.func
239
def call(self, args, kwargs):
240
self.func(*args[self.argslice], **kwargs)