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)
186 dc.deregisterKeystrokeListener(self._this(), key_set, m, kind)
188 def queryInterface(self, repo_id):
190 Reports that this class only implements the AT-SPI DeviceEventListener
191 interface. Required by AT-SPI.
193 @param repo_id: Request for an interface
194 @type repo_id: string
195 @return: The underlying CORBA object for the device event listener
196 @rtype: Accessibility.EventListener
198 if repo_id == utils.getInterfaceIID(Accessibility.DeviceEventListener):
203 def notifyEvent(self, ev):
205 Notifies the L{Registry} that an event has occurred. Wraps the raw event
206 object in our L{Event} class to support automatic ref and unref calls. An
207 observer can set the L{Event} consume flag to True to indicate this event
208 should not be allowed to pass to other AT-SPI observers or the underlying
211 @param ev: Keyboard event
212 @type ev: Accessibility.DeviceEvent
213 @return: Should the event be consumed (True) or allowed to pass on to other
214 AT-SPI observers (False)?
217 # wrap the device event
218 ev = event.DeviceEvent(ev)
219 self.registry.handleDeviceEvent(ev, self)
222 class _EventObserver(_Observer, Accessibility__POA.EventListener):
224 Observes all non-keyboard AT-SPI events. Can be reused across event types.
226 def register(self, reg, name):
228 Starts monitoring for the given event.
230 @param name: Name of the event to start monitoring
232 @param reg: Reference to the raw registry object
233 @type reg: Accessibility.Registry
235 reg.registerGlobalEventListener(self._this(), name)
237 def unregister(self, reg, name):
239 Stops monitoring for the given event.
241 @param name: Name of the event to stop monitoring
243 @param reg: Reference to the raw registry object
244 @type reg: Accessibility.Registry
246 reg.deregisterGlobalEventListener(self._this(), name)
248 def queryInterface(self, repo_id):
250 Reports that this class only implements the AT-SPI DeviceEventListener
251 interface. Required by AT-SPI.
253 @param repo_id: Request for an interface
254 @type repo_id: string
255 @return: The underlying CORBA object for the device event listener
256 @rtype: Accessibility.EventListener
258 if repo_id == utils.getInterfaceIID(Accessibility.EventListener):
263 def notifyEvent(self, ev):
265 Notifies the L{Registry} that an event has occurred. Wraps the raw event
266 object in our L{Event} class to support automatic ref and unref calls.
267 Aborts on any exception indicating the event could not be wrapped.
269 @param ev: AT-SPI event signal (anything but keyboard)
270 @type ev: Accessibility.Event
272 # wrap raw event so ref counts are correct before queueing
274 self.registry.handleEvent(ev)
276 class Registry(object):
278 Wraps the Accessibility.Registry to provide more Pythonic registration for
281 This object should be treated as a singleton, but such treatment is not
282 enforced. You can construct another instance of this object and give it a
283 reference to the Accessibility.Registry singleton. Doing so is harmless and
286 @ivar async: Should event dispatch to local listeners be decoupled from event
287 receiving from the registry?
289 @ivar reg: Reference to the real, wrapped registry object
290 @type reg: Accessibility.Registry
291 @ivar dev: Reference to the device controller
292 @type dev: Accessibility.DeviceEventController
293 @ivar queue: Queue of events awaiting local dispatch
294 @type queue: Queue.Queue
295 @ivar clients: Map of event names to client listeners
296 @type clients: dictionary
297 @ivar observers: Map of event names to AT-SPI L{_Observer} objects
298 @type observers: dictionary
300 def __init__(self, reg):
302 Stores a reference to the AT-SPI registry. Gets and stores a reference
303 to the DeviceEventController.
305 @param reg: Reference to the AT-SPI registry daemon
306 @type reg: Accessibility.Registry
310 self.dev = self.reg.getDeviceEventController()
311 self.queue = Queue.Queue()
317 @return: This instance of the registry
322 def start(self, async=False, gil=True):
324 Enter the main loop to start receiving and dispatching events.
326 @param async: Should event dispatch be asynchronous (decoupled) from
327 event receiving from the AT-SPI registry?
329 @param gil: Add an idle callback which releases the Python GIL for a few
330 milliseconds to allow other threads to run? Necessary if other threads
331 will be used in this process.
340 except KeyboardInterrupt, e:
341 # store the exception for later
342 releaseGIL.keyboard_exception = e
345 # make room for an exception if one occurs during the
346 releaseGIL.keyboard_exception = None
347 i = gobject.idle_add(releaseGIL)
349 # enter the main loop
353 # clear all observers
354 for name, ob in self.observers.items():
355 ob.unregister(self.reg, name)
357 gobject.source_remove(i)
358 if releaseGIL.keyboard_exception is not None:
359 # raise an keyboard exception we may have gotten earlier
360 raise releaseGIL.keyboard_exception
362 def stop(self, *args):
363 '''Quits the main loop.'''
367 # ignore errors when quitting (probably already quitting)
370 def getDesktopCount(self):
372 Gets the number of available desktops.
374 @return: Number of desktops
376 @raise LookupError: When the count cannot be retrieved
379 return self.reg.getDesktopCount()
383 def getDesktop(self, i):
385 Gets a reference to the i-th desktop.
387 @param i: Which desktop to get
389 @return: Desktop reference
390 @rtype: Accessibility.Desktop
391 @raise LookupError: When the i-th desktop cannot be retrieved
394 return self.reg.getDesktop(i)
398 def registerEventListener(self, client, *names):
400 Registers a new client callback for the given event names. Supports
401 registration for all subevents if only partial event name is specified.
402 Do not include a trailing colon.
404 For example, 'object' will register for all object events,
405 'object:property-change' will register for all property change events,
406 and 'object:property-change:accessible-parent' will register only for the
407 parent property change event.
409 Registered clients will not be automatically removed when the client dies.
410 To ensure the client is properly garbage collected, call
411 L{deregisterEventListener}.
413 @param client: Callable to be invoked when the event occurs
414 @type client: callable
415 @param names: List of full or partial event names
416 @type names: list of string
419 # store the callback for each specific event name
420 self._registerClients(client, name)
422 def deregisterEventListener(self, client, *names):
424 Unregisters an existing client callback for the given event names. Supports
425 unregistration for all subevents if only partial event name is specified.
426 Do not include a trailing colon.
428 This method must be called to ensure a client registered by
429 L{registerEventListener} is properly garbage collected.
431 @param client: Client callback to remove
432 @type client: callable
433 @param names: List of full or partial event names
434 @type names: list of string
435 @return: Were event names specified for which the given client was not
441 # remove the callback for each specific event name
442 missed |= self._unregisterClients(client, name)
445 def registerKeystrokeListener(self, client, key_set=[], mask=0,
446 kind=(constants.KEY_PRESSED_EVENT,
447 constants.KEY_RELEASED_EVENT),
448 synchronous=True, preemptive=True,
451 Registers a listener for key stroke events.
453 @param client: Callable to be invoked when the event occurs
454 @type client: callable
455 @param key_set: Set of hardware key codes to stop monitoring. Leave empty
456 to indicate all keys.
457 @type key_set: list of integer
458 @param mask: When the mask is None, the codes in the key_set will be
459 monitored only when no modifier is held. When the mask is an
460 integer, keys in the key_set will be monitored only when the modifiers in
461 the mask are held. When the mask is an iterable over more than one
462 integer, keys in the key_set will be monitored when any of the modifier
463 combinations in the set are held.
464 @type mask: integer, iterable, None
465 @param kind: Kind of events to watch, KEY_PRESSED_EVENT or
468 @param synchronous: Should the callback notification be synchronous, giving
469 the client the chance to consume the event?
470 @type synchronous: boolean
471 @param preemptive: Should the callback be allowed to preempt / consume the
473 @type preemptive: boolean
474 @param global_: Should callback occur even if an application not supporting
475 AT-SPI is in the foreground? (requires xevie)
476 @type global_: boolean
479 # see if we already have an observer for this client
480 ob = self.clients[client]
482 # create a new device observer for this client
483 ob = _DeviceObserver(self, synchronous, preemptive, global_)
484 # store the observer to client mapping, and the inverse
485 self.clients[ob] = client
486 self.clients[client] = ob
488 # None means all modifier combinations
489 mask = utils.allModifiers()
490 # register for new keystrokes on the observer
491 ob.register(self.dev, key_set, mask, kind)
493 def deregisterKeystrokeListener(self, client, key_set=[], mask=0,
494 kind=(constants.KEY_PRESSED_EVENT,
495 constants.KEY_RELEASED_EVENT)):
497 Deregisters a listener for key stroke events.
499 @param client: Callable to be invoked when the event occurs
500 @type client: callable
501 @param key_set: Set of hardware key codes to stop monitoring. Leave empty
502 to indicate all keys.
503 @type key_set: list of integer
504 @param mask: When the mask is None, the codes in the key_set will be
505 monitored only when no modifier is held. When the mask is an
506 integer, keys in the key_set will be monitored only when the modifiers in
507 the mask are held. When the mask is an iterable over more than one
508 integer, keys in the key_set will be monitored when any of the modifier
509 combinations in the set are held.
510 @type mask: integer, iterable, None
511 @param kind: Kind of events to stop watching, KEY_PRESSED_EVENT or
514 @raise KeyError: When the client isn't already registered for events
516 # see if we already have an observer for this client
517 ob = self.clients[client]
519 # None means all modifier combinations
520 mask = utils.allModifiers()
521 # register for new keystrokes on the observer
522 ob.unregister(self.dev, key_set, mask, kind)
524 def generateKeyboardEvent(self, keycode, keysym, kind):
526 Generates a keyboard event. One of the keycode or the keysym parameters
527 should be specified and the other should be None. The kind parameter is
528 required and should be one of the KEY_PRESS, KEY_RELEASE, KEY_PRESSRELEASE,
529 KEY_SYM, or KEY_STRING.
531 @param keycode: Hardware keycode or None
532 @type keycode: integer
533 @param keysym: Symbolic key string or None
535 @param kind: Kind of event to synthesize
539 self.dev.generateKeyboardEvent(keycode, '', kind)
541 self.dev.generateKeyboardEvent(None, keysym, kind)
543 def generateMouseEvent(self, x, y, name):
545 Generates a mouse event at the given absolute x and y coordinate. The kind
546 of event generated is specified by the name. For example, MOUSE_B1P
547 (button 1 press), MOUSE_REL (relative motion), MOUSE_B3D (butten 3
550 @param x: Horizontal coordinate, usually left-hand oriented
552 @param y: Vertical coordinate, usually left-hand oriented
554 @param name: Name of the event to generate
557 self.dev.generateMouseEvent(x, y, name)
559 def handleDeviceEvent(self, event, ob):
561 Dispatches L{event.DeviceEvent}s to registered clients. Clients are called
562 in the order they were registered for the given AT-SPI event. If any
563 client sets the L{event.DeviceEvent.consume} flag to True, callbacks cease
564 for the event for clients of this registry instance. Clients of other
565 registry instances and clients in other processes may be affected
566 depending on the values of synchronous and preemptive used when invoking
567 L{registerKeystrokeListener}.
569 @note: Asynchronous dispatch of device events is not supported.
571 @param event: AT-SPI device event
572 @type event: L{event.DeviceEvent}
573 @param ob: Observer that received the event
574 @type ob: L{_DeviceObserver}
577 # try to get the client registered for this event type
578 client = self.clients[ob]
580 # client may have unregistered recently, ignore event
582 # make the call to the client
586 # print the exception, but don't let it stop notification
587 traceback.print_exc()
589 def handleEvent(self, event):
591 Handles an AT-SPI event by either queuing it for later dispatch when the
592 L{Registry.async} flag is set, or dispatching it immediately.
594 @param event: AT-SPI event
595 @type event: L{event.Event}
599 self.queue.put_nowait(event)
601 # dispatch immediately
602 self._dispatchEvent(event)
604 def _dispatchEvent(self, event):
606 Dispatches L{event.Event}s to registered clients. Clients are called in
607 the order they were registered for the given AT-SPI event. If any client
608 sets the L{Event} consume flag to True, callbacks cease for the event for
609 clients of this registry instance. Clients of other registry instances and
610 clients in other processes are unaffected.
612 @param event: AT-SPI event
613 @type event: L{event.Event}
616 # try to get the client registered for this event type
617 clients = self.clients[event.type.name]
619 # client may have unregistered recently, ignore event
621 # make the call to each client
622 for client in clients:
626 # print the exception, but don't let it stop notification
627 traceback.print_exc()
629 # don't allow further processing if the consume flag is set
632 def _registerClients(self, client, name):
634 Internal method that recursively associates a client with AT-SPI event
635 names. Allows a client to incompletely specify an event name in order to
636 register for subevents without specifying their full names manually.
638 @param client: Client callback to receive event notifications
639 @type client: callable
640 @param name: Partial or full event name
644 # look for an event name in our event tree dictionary
645 events = constants.EVENT_TREE[name]
647 # if the event name doesn't exist, it's a leaf event meaning there are
648 # no subtypes for that event
649 # add this client to the list of clients already in the dictionary
650 # using the event name as the key; if there are no clients yet for this
651 # event, insert an empty list into the dictionary before appending
653 et = event.EventType(name)
654 clients = self.clients.setdefault(et.name, [])
656 # if this succeeds, this client is already registered for the given
657 # event type, so ignore the request
658 clients.index(client)
660 # else register the client
661 clients.append(client)
662 self._registerObserver(name)
664 # if the event name does exist in the tree, there are subevents for
665 # this event; loop through them calling this method again to get to
668 self._registerClients(client, e)
670 def _unregisterClients(self, client, name):
672 Internal method that recursively unassociates a client with AT-SPI event
673 names. Allows a client to incompletely specify an event name in order to
674 unregister for subevents without specifying their full names manually.
676 @param client: Client callback to receive event notifications
677 @type client: callable
678 @param name: Partial or full event name
683 # look for an event name in our event tree dictionary
684 events = constants.EVENT_TREE[name]
687 # if the event name doesn't exist, it's a leaf event meaning there are
688 # no subtypes for that event
689 # get the list of registered clients and try to remove the one provided
690 et = event.EventType(name)
691 clients = self.clients[et.name]
692 clients.remove(client)
693 self._unregisterObserver(name)
694 except (ValueError, KeyError):
695 # ignore any exceptions indicating the client is not registered
698 # if the event name does exist in the tree, there are subevents for this
699 # event; loop through them calling this method again to get to the leaf
702 missed |= self._unregisterClients(client, e)
705 def _registerObserver(self, name):
707 Creates a new L{_Observer} to watch for events of the given type or
708 returns the existing observer if one is already registered. One
709 L{_Observer} is created for each leaf in the L{constants.EVENT_TREE} or
710 any event name not found in the tree.
712 @param name: Raw name of the event to observe
714 @return: L{_Observer} object that is monitoring the event
717 et = event.EventType(name)
719 # see if an observer already exists for this event
720 ob = self.observers[et.name]
722 # build a new observer if one does not exist
723 ob = _EventObserver(self)
724 # we have to register for the raw name because it may be different from
725 # the parsed name determined by EventType (e.g. trailing ':' might be
727 ob.register(self.reg, name)
728 self.observers[et.name] = ob
729 # increase our client ref count so we know someone new is watching for the
734 def _unregisterObserver(self, name):
736 Destroys an existing L{_Observer} for the given event type only if no
737 clients are registered for the events it is monitoring.
739 @param name: Name of the event to observe
741 @raise KeyError: When an observer for the given event is not regist
743 et = event.EventType(name)
744 # see if an observer already exists for this event
745 ob = self.observers[et.name]
747 if ob.getClientRefCount() == 0:
748 ob.unregister(self.reg, name)
749 del self.observers[et.name]