2 Registry that hides some of the details of registering for AT-SPI events and
3 starting and stopping the main program loop.
5 @todo: PP: when to destroy device listener?
8 @organization: IBM Corporation
9 @copyright: Copyright (c) 2005, 2007 IBM Corporation
12 This library is free software; you can redistribute it and/or
13 modify it under the terms of the GNU Library General Public
14 License as published by the Free Software Foundation; either
15 version 2 of the License, or (at your option) any later version.
17 This library is distributed in the hope that it will be useful,
18 but WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 Library General Public License for more details.
22 You should have received a copy of the GNU Library General Public
23 License along with this library; if not, write to the
24 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
25 Boston, MA 02111-1307, USA.
27 Portions of this code originally licensed and copyright (c) 2005, 2007
28 IBM Corporation under the BSD license, available at
29 U{http://www.opensource.org/licenses/bsd-license.php}
40 import Accessibility__POA
45 class _Observer(object):
47 Parent class for all event observers. Dispatches all received events to the
48 L{Registry} that created this L{_Observer}. Provides basic reference counting
49 functionality needed by L{Registry} to determine when an L{_Observer} can be
50 released for garbage collection.
52 The reference counting provided by this class is independent of the reference
53 counting used by CORBA. Keeping the counts separate makes it easier for the
54 L{Registry} to detect when an L{_Observer} can be freed in the
55 L{Registry._unregisterObserver} method.
57 @ivar registry: Reference to the L{Registry} that created this L{_Observer}
58 @type registry: weakref.proxy to L{Registry}
59 @ivar ref_count: Reference count on this L{_Observer}
60 @type ref_count: integer
62 def __init__(self, registry):
64 Stores a reference to the creating L{Registry}. Intializes the reference
65 count on this object to zero.
67 @param registry: The L{Registry} that created this observer
68 @type registry: weakref.proxy to L{Registry}
70 self.registry = weakref.proxy(registry)
75 Increments the Python reference count on this L{_Observer} by one. This
76 method is called when a new client is registered in L{Registry} to receive
77 notification of an event type monitored by this L{_Observer}.
81 def clientUnref(self):
83 Decrements the pyatspi reference count on this L{_Observer} by one. This
84 method is called when a client is unregistered in L{Registry} to stop
85 receiving notifications of an event type monitored by this L{_Observer}.
89 def getClientRefCount(self):
91 @return: Current Python reference count on this L{_Observer}
97 '''Required by CORBA. Does nothing.'''
101 '''Required by CORBA. Does nothing.'''
104 class _DeviceObserver(_Observer, Accessibility__POA.DeviceEventListener):
106 Observes keyboard press and release events.
108 @ivar registry: The L{Registry} that created this observer
109 @type registry: L{Registry}
110 @ivar key_set: Set of keys to monitor
111 @type key_set: list of integer
112 @ivar mask: Watch for key events while these modifiers are held
114 @ivar kind: Kind of events to monitor
116 @ivar mode: Keyboard event mode
117 @type mode: Accessibility.EventListenerMode
119 def __init__(self, registry, synchronous, preemptive, global_):
121 Creates a mode object that defines when key events will be received from
122 the system. Stores all other information for later registration.
124 @param registry: The L{Registry} that created this observer
125 @type registry: L{Registry}
126 @param synchronous: Handle the key event synchronously?
127 @type synchronous: boolean
128 @param preemptive: Allow event to be consumed?
129 @type preemptive: boolean
130 @param global_: Watch for events on inaccessible applications too?
131 @type global_: boolean
133 _Observer.__init__(self, registry)
134 self.mode = Accessibility.EventListenerMode()
135 self.mode.preemptive = preemptive
136 self.mode.synchronous = synchronous
137 self.mode._global = global_
139 def register(self, dc, key_set, mask, kind):
141 Starts keyboard event monitoring.
143 @param dc: Reference to a device controller
144 @type dc: Accessibility.DeviceEventController
145 @param key_set: Set of keys to monitor
146 @type key_set: list of integer
147 @param mask: Integer modifier mask or an iterable over multiple masks to
149 @type mask: integer, iterable, or None
150 @param kind: Kind of events to monitor
154 # check if the mask is iterable
157 # register a single integer if not
158 dc.registerKeystrokeListener(self._this(), key_set, mask, kind,
162 dc.registerKeystrokeListener(self._this(), key_set, m, kind, self.mode)
164 def unregister(self, dc, key_set, mask, kind):
166 Stops keyboard event monitoring.
168 @param dc: Reference to a device controller
169 @type dc: Accessibility.DeviceEventController
170 @param key_set: Set of keys to monitor
171 @type key_set: list of integer
172 @param mask: Integer modifier mask or an iterable over multiple masks to
174 @type mask: integer, iterable, or None
175 @param kind: Kind of events to monitor
179 # check if the mask is iterable
182 # unregister a single integer if not
183 dc.deregisterKeystrokeListener(self._this(), key_set, mask, kind,
187 dc.deregisterKeystrokeListener(self._this(), key_set, m, kind,
190 def queryInterface(self, repo_id):
192 Reports that this class only implements the AT-SPI DeviceEventListener
193 interface. Required by AT-SPI.
195 @param repo_id: Request for an interface
196 @type repo_id: string
197 @return: The underlying CORBA object for the device event listener
198 @rtype: Accessibility.EventListener
200 if repo_id == utils.getInterfaceIID(Accessibility.DeviceEventListener):
205 def notifyEvent(self, ev):
207 Notifies the L{Registry} that an event has occurred. Wraps the raw event
208 object in our L{Event} class to support automatic ref and unref calls. An
209 observer can set the L{Event} consume flag to True to indicate this event
210 should not be allowed to pass to other AT-SPI observers or the underlying
213 @param ev: Keyboard event
214 @type ev: Accessibility.DeviceEvent
215 @return: Should the event be consumed (True) or allowed to pass on to other
216 AT-SPI observers (False)?
219 # wrap the device event
220 ev = event.DeviceEvent(ev)
221 self.registry.handleDeviceEvent(ev, self)
224 class _EventObserver(_Observer, Accessibility__POA.EventListener):
226 Observes all non-keyboard AT-SPI events. Can be reused across event types.
228 def register(self, reg, name):
230 Starts monitoring for the given event.
232 @param name: Name of the event to start monitoring
234 @param reg: Reference to the raw registry object
235 @type reg: Accessibility.Registry
237 reg.registerGlobalEventListener(self._this(), name)
239 def unregister(self, reg, name):
241 Stops monitoring for the given event.
243 @param name: Name of the event to stop monitoring
245 @param reg: Reference to the raw registry object
246 @type reg: Accessibility.Registry
248 reg.deregisterGlobalEventListener(self._this(), name)
250 def queryInterface(self, repo_id):
252 Reports that this class only implements the AT-SPI DeviceEventListener
253 interface. Required by AT-SPI.
255 @param repo_id: Request for an interface
256 @type repo_id: string
257 @return: The underlying CORBA object for the device event listener
258 @rtype: Accessibility.EventListener
260 if repo_id == utils.getInterfaceIID(Accessibility.EventListener):
265 def notifyEvent(self, ev):
267 Notifies the L{Registry} that an event has occurred. Wraps the raw event
268 object in our L{Event} class to support automatic ref and unref calls.
269 Aborts on any exception indicating the event could not be wrapped.
271 @param ev: AT-SPI event signal (anything but keyboard)
272 @type ev: Accessibility.Event
274 # wrap raw event so ref counts are correct before queueing
276 self.registry.handleEvent(ev)
278 class Registry(object):
280 Wraps the Accessibility.Registry to provide more Pythonic registration for
283 This object should be treated as a singleton, but such treatment is not
284 enforced. You can construct another instance of this object and give it a
285 reference to the Accessibility.Registry singleton. Doing so is harmless and
288 @ivar async: Should event dispatch to local listeners be decoupled from event
289 receiving from the registry?
291 @ivar reg: Reference to the real, wrapped registry object
292 @type reg: Accessibility.Registry
293 @ivar dev: Reference to the device controller
294 @type dev: Accessibility.DeviceEventController
295 @ivar queue: Queue of events awaiting local dispatch
296 @type queue: Queue.Queue
297 @ivar clients: Map of event names to client listeners
298 @type clients: dictionary
299 @ivar observers: Map of event names to AT-SPI L{_Observer} objects
300 @type observers: dictionary
302 def __init__(self, reg):
304 Stores a reference to the AT-SPI registry. Gets and stores a reference
305 to the DeviceEventController.
307 @param reg: Reference to the AT-SPI registry daemon
308 @type reg: Accessibility.Registry
312 self.dev = self.reg.getDeviceEventController()
313 self.queue = Queue.Queue()
319 @return: This instance of the registry
324 def start(self, async=False, gil=True):
326 Enter the main loop to start receiving and dispatching events.
328 @param async: Should event dispatch be asynchronous (decoupled) from
329 event receiving from the AT-SPI registry?
331 @param gil: Add an idle callback which releases the Python GIL for a few
332 milliseconds to allow other threads to run? Necessary if other threads
333 will be used in this process.
338 # register a signal handler for gracefully killing the loop
339 signal.signal(signal.SIGINT, self.stop)
340 signal.signal(signal.SIGTERM, self.stop)
346 i = gobject.idle_add(releaseGIL)
348 # enter the main loop
352 gobject.source_remove(i)
354 def stop(self, *args):
355 '''Quits the main loop.'''
359 # ignore errors when quitting (probably already quitting)
362 def getDesktopCount(self):
364 Gets the number of available desktops.
366 @return: Number of desktops
368 @raise LookupError: When the count cannot be retrieved
371 return self.reg.getDesktopCount()
375 def getDesktop(self, i):
377 Gets a reference to the i-th desktop.
379 @param i: Which desktop to get
381 @return: Desktop reference
382 @rtype: Accessibility.Desktop
383 @raise LookupError: When the i-th desktop cannot be retrieved
386 return self.reg.getDesktop(i)
390 def registerEventListener(self, client, *names):
392 Registers a new client callback for the given event names. Supports
393 registration for all subevents if only partial event name is specified.
394 Do not include a trailing colon.
396 For example, 'object' will register for all object events,
397 'object:property-change' will register for all property change events,
398 and 'object:property-change:accessible-parent' will register only for the
399 parent property change event.
401 Registered clients will not be automatically removed when the client dies.
402 To ensure the client is properly garbage collected, call
403 L{deregisterEventListener}.
405 @param client: Callable to be invoked when the event occurs
406 @type client: callable
407 @param names: List of full or partial event names
408 @type names: list of string
411 # store the callback for each specific event name
412 self._registerClients(client, name)
414 def deregisterEventListener(self, client, *names):
416 Unregisters an existing client callback for the given event names. Supports
417 unregistration for all subevents if only partial event name is specified.
418 Do not include a trailing colon.
420 This method must be called to ensure a client registered by
421 L{registerEventListener} is properly garbage collected.
423 @param client: Client callback to remove
424 @type client: callable
425 @param names: List of full or partial event names
426 @type names: list of string
427 @return: Were event names specified for which the given client was not
433 # remove the callback for each specific event name
434 missed |= self._unregisterClients(client, name)
437 def registerKeystrokeListener(self, client, key_set=[], mask=0,
438 kind=(constants.KEY_PRESSED_EVENT,
439 constants.KEY_RELEASED_EVENT),
440 synchronous=True, preemptive=True,
443 Registers a listener for key stroke events.
445 @param client: Callable to be invoked when the event occurs
446 @type client: callable
447 @param key_set: Set of hardware key codes to stop monitoring. Leave empty
448 to indicate all keys.
449 @type key_set: list of integer
450 @param mask: When the mask is None, the codes in the key_set will be
451 monitored only when no modifier is held. When the mask is an
452 integer, keys in the key_set will be monitored only when the modifiers in
453 the mask are held. When the mask is an iterable over more than one
454 integer, keys in the key_set will be monitored when any of the modifier
455 combinations in the set are held.
456 @type mask: integer, iterable, None
457 @param kind: Kind of events to watch, KEY_PRESSED_EVENT or
460 @param synchronous: Should the callback notification be synchronous, giving
461 the client the chance to consume the event?
462 @type synchronous: boolean
463 @param preemptive: Should the callback be allowed to preempt / consume the
465 @type preemptive: boolean
466 @param global_: Should callback occur even if an application not supporting
467 AT-SPI is in the foreground? (requires xevie)
468 @type global_: boolean
471 # see if we already have an observer for this client
472 ob = self.clients[client]
474 # create a new device observer for this client
475 ob = _DeviceObserver(self, synchronous, preemptive, global_)
476 # store the observer to client mapping, and the inverse
477 self.clients[ob] = client
478 self.clients[client] = ob
480 # None means all modifier combinations
481 mask = utils.allModifiers()
482 # register for new keystrokes on the observer
483 ob.register(self.dev, key_set, mask, kind)
485 def deregisterKeystrokeListener(self, client, key_set=[], mask=0,
486 kind=(constants.KEY_PRESSED_EVENT,
487 constants.KEY_RELEASED_EVENT)):
489 Deregisters a listener for key stroke events.
491 @param client: Callable to be invoked when the event occurs
492 @type client: callable
493 @param key_set: Set of hardware key codes to stop monitoring. Leave empty
494 to indicate all keys.
495 @type key_set: list of integer
496 @param mask: When the mask is None, the codes in the key_set will be
497 monitored only when no modifier is held. When the mask is an
498 integer, keys in the key_set will be monitored only when the modifiers in
499 the mask are held. When the mask is an iterable over more than one
500 integer, keys in the key_set will be monitored when any of the modifier
501 combinations in the set are held.
502 @type mask: integer, iterable, None
503 @param kind: Kind of events to stop watching, KEY_PRESSED_EVENT or
506 @raise KeyError: When the client isn't already registered for events
508 # see if we already have an observer for this client
509 ob = self.clients[client]
511 # None means all modifier combinations
512 mask = utils.allModifiers()
513 # register for new keystrokes on the observer
514 ob.unregister(self.dev, key_set, mask, kind)
516 def generateKeyboardEvent(self, keycode, keysym, kind):
518 Generates a keyboard event. One of the keycode or the keysym parameters
519 should be specified and the other should be None. The kind parameter is
520 required and should be one of the KEY_PRESS, KEY_RELEASE, KEY_PRESSRELEASE,
521 KEY_SYM, or KEY_STRING.
523 @param keycode: Hardware keycode or None
524 @type keycode: integer
525 @param keysym: Symbolic key string or None
527 @param kind: Kind of event to synthesize
531 self.dev.generateKeyboardEvent(keycode, '', kind)
533 self.dev.generateKeyboardEvent(None, keysym, kind)
535 def generateMouseEvent(self, x, y, name):
537 Generates a mouse event at the given absolute x and y coordinate. The kind
538 of event generated is specified by the name. For example, MOUSE_B1P
539 (button 1 press), MOUSE_REL (relative motion), MOUSE_B3D (butten 3
542 @param x: Horizontal coordinate, usually left-hand oriented
544 @param y: Vertical coordinate, usually left-hand oriented
546 @param name: Name of the event to generate
549 self.dev.generateMouseEvent(x, y, name)
551 def handleDeviceEvent(self, event, ob):
553 Dispatches L{event.DeviceEvent}s to registered clients. Clients are called
554 in the order they were registered for the given AT-SPI event. If any
555 client sets the L{event.DeviceEvent.consume} flag to True, callbacks cease
556 for the event for clients of this registry instance. Clients of other
557 registry instances and clients in other processes may be affected
558 depending on the values of synchronous and preemptive used when invoking
559 L{registerKeystrokeListener}.
561 @note: Asynchronous dispatch of device events is not supported.
563 @param event: AT-SPI device event
564 @type event: L{event.DeviceEvent}
565 @param ob: Observer that received the event
566 @type ob: L{_DeviceObserver}
569 # try to get the client registered for this event type
570 client = self.clients[ob]
572 # client may have unregistered recently, ignore event
574 # make the call to the client
578 # print the exception, but don't let it stop notification
579 traceback.print_exc()
581 def handleEvent(self, event):
583 Handles an AT-SPI event by either queuing it for later dispatch when the
584 L{Registry.async} flag is set, or dispatching it immediately.
586 @param event: AT-SPI event
587 @type event: L{event.Event}
591 self.queue.put_nowait(event)
593 # dispatch immediately
594 self._dispatchEvent(event)
596 def _dispatchEvent(self, event):
598 Dispatches L{event.Event}s to registered clients. Clients are called in
599 the order they were registered for the given AT-SPI event. If any client
600 sets the L{Event} consume flag to True, callbacks cease for the event for
601 clients of this registry instance. Clients of other registry instances and
602 clients in other processes are unaffected.
604 @param event: AT-SPI event
605 @type event: L{event.Event}
608 # try to get the client registered for this event type
609 clients = self.clients[event.type.name]
611 # client may have unregistered recently, ignore event
613 # make the call to each client
614 for client in clients:
618 # print the exception, but don't let it stop notification
619 traceback.print_exc()
621 # don't allow further processing if the consume flag is set
624 def _registerClients(self, client, name):
626 Internal method that recursively associates a client with AT-SPI event
627 names. Allows a client to incompletely specify an event name in order to
628 register for subevents without specifying their full names manually.
630 @param client: Client callback to receive event notifications
631 @type client: callable
632 @param name: Partial or full event name
636 # look for an event name in our event tree dictionary
637 events = constants.EVENT_TREE[name]
639 # if the event name doesn't exist, it's a leaf event meaning there are
640 # no subtypes for that event
641 # add this client to the list of clients already in the dictionary
642 # using the event name as the key; if there are no clients yet for this
643 # event, insert an empty list into the dictionary before appending
645 et = event.EventType(name)
646 clients = self.clients.setdefault(et.name, [])
648 # if this succeeds, this client is already registered for the given
649 # event type, so ignore the request
650 clients.index(client)
652 # else register the client
653 clients.append(client)
654 self._registerObserver(name)
656 # if the event name does exist in the tree, there are subevents for
657 # this event; loop through them calling this method again to get to
660 self._registerClients(client, e)
662 def _unregisterClients(self, client, name):
664 Internal method that recursively unassociates a client with AT-SPI event
665 names. Allows a client to incompletely specify an event name in order to
666 unregister for subevents without specifying their full names manually.
668 @param client: Client callback to receive event notifications
669 @type client: callable
670 @param name: Partial or full event name
675 # look for an event name in our event tree dictionary
676 events = constants.EVENT_TREE[name]
679 # if the event name doesn't exist, it's a leaf event meaning there are
680 # no subtypes for that event
681 # get the list of registered clients and try to remove the one provided
682 et = event.EventType(name)
683 clients = self.clients[et.name]
684 clients.remove(client)
685 self._unregisterObserver(name)
686 except (ValueError, KeyError):
687 # ignore any exceptions indicating the client is not registered
690 # if the event name does exist in the tree, there are subevents for this
691 # event; loop through them calling this method again to get to the leaf
694 missed |= self._unregisterClients(client, e)
697 def _registerObserver(self, name):
699 Creates a new L{_Observer} to watch for events of the given type or
700 returns the existing observer if one is already registered. One
701 L{_Observer} is created for each leaf in the L{constants.EVENT_TREE} or
702 any event name not found in the tree.
704 @param name: Raw name of the event to observe
706 @return: L{_Observer} object that is monitoring the event
709 et = event.EventType(name)
711 # see if an observer already exists for this event
712 ob = self.observers[et.name]
714 # build a new observer if one does not exist
715 ob = _EventObserver(self)
716 # we have to register for the raw name because it may be different from
717 # the parsed name determined by EventType (e.g. trailing ':' might be
719 ob.register(self.reg, name)
720 self.observers[et.name] = ob
721 # increase our client ref count so we know someone new is watching for the
726 def _unregisterObserver(self, name):
728 Destroys an existing L{_Observer} for the given event type only if no
729 clients are registered for the events it is monitoring.
731 @param name: Name of the event to observe
733 @raise KeyError: When an observer for the given event is not regist
735 et = event.EventType(name)
736 # see if an observer already exists for this event
737 ob = self.observers[et.name]
739 if ob.getClientRefCount() == 0:
740 ob.unregister(self.reg, name)
741 del self.observers[et.name]