pyatspi/registry.py

   1 '''
   2 Registry that hides some of the details of registering for AT-SPI events and
   3 starting and stopping the main program loop.
   4
   5 @todo: PP: when to destroy device listener?
   6
   7 @author: Peter Parente
   8 @organization: IBM Corporation
   9 @copyright: Copyright (c) 2005, 2007 IBM Corporation
  10 @license: LGPL
  11
  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.
  16
  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.
  21
  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.
  26
  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}
  30 '''
  31 import signal
  32 import time
  33 import weakref
  34 import Queue
  35 import traceback
  36 import ORBit
  37 import bonobo
  38 import gobject
  39 import Accessibility
  40 import Accessibility__POA
  41 import utils
  42 import constants
  43 import event
  44
  45 class _Observer(object):
  46   '''
  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.
  51
  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.
  56
  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
  61   '''
  62   def __init__(self, registry):
  63     '''
  64     Stores a reference to the creating L{Registry}. Intializes the reference
  65     count on this object to zero.
  66
  67     @param registry: The L{Registry} that created this observer
  68     @type registry: weakref.proxy to L{Registry}
  69     '''
  70     self.registry = weakref.proxy(registry)
  71     self.ref_count = 0
  72
  73   def clientRef(self):
  74     '''
  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}.
  78     '''
  79     self.ref_count += 1
  80
  81   def clientUnref(self):
  82     '''
  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}.
  86     '''
  87     self.ref_count -= 1
  88
  89   def getClientRefCount(self):
  90     '''
  91     @return: Current Python reference count on this L{_Observer}
  92     @rtype: integer
  93     '''
  94     return self.ref_count
  95
  96   def ref(self):
  97     '''Required by CORBA. Does nothing.'''
  98     pass
  99
 100   def unref(self):
 101     '''Required by CORBA. Does nothing.'''
 102     pass
 103
 104 class _DeviceObserver(_Observer, Accessibility__POA.DeviceEventListener):
 105   '''
 106   Observes keyboard press and release events.
 107
 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
 113   @type mask: integer
 114   @ivar kind: Kind of events to monitor
 115   @type kind: integer
 116   @ivar mode: Keyboard event mode
 117   @type mode: Accessibility.EventListenerMode
 118   '''
 119   def __init__(self, registry, synchronous, preemptive, global_):
 120     '''
 121     Creates a mode object that defines when key events will be received from
 122     the system. Stores all other information for later registration.
 123
 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
 132     '''
 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_
 138
 139   def register(self, dc, key_set, mask, kind):
 140     '''
 141     Starts keyboard event monitoring.
 142
 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
 148       unapply all at once
 149     @type mask: integer, iterable, or None
 150     @param kind: Kind of events to monitor
 151     @type kind: integer
 152     '''
 153     try:
 154       # check if the mask is iterable
 155       iter(mask)
 156     except TypeError:
 157       # register a single integer if not
 158       dc.registerKeystrokeListener(self._this(), key_set, mask, kind,
 159                                    self.mode)
 160     else:
 161       for m in mask:
 162         dc.registerKeystrokeListener(self._this(), key_set, m, kind, self.mode)
 163
 164   def unregister(self, dc, key_set, mask, kind):
 165     '''
 166     Stops keyboard event monitoring.
 167
 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
 173       unapply all at once
 174     @type mask: integer, iterable, or None
 175     @param kind: Kind of events to monitor
 176     @type kind: integer
 177     '''
 178     try:
 179       # check if the mask is iterable
 180       iter(mask)
 181     except TypeError:
 182       # unregister a single integer if not
 183       dc.deregisterKeystrokeListener(self._this(), key_set, mask, kind)
 184     else:
 185       for m in mask:
 186         dc.deregisterKeystrokeListener(self._this(), key_set, m, kind)
 187
 188   def queryInterface(self, repo_id):
 189     '''
 190     Reports that this class only implements the AT-SPI DeviceEventListener
 191     interface. Required by AT-SPI.
 192
 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
 197     '''
 198     if repo_id == utils.getInterfaceIID(Accessibility.DeviceEventListener):
 199       return self._this()
 200     else:
 201       return None
 202
 203   def notifyEvent(self, ev):
 204     '''
 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
 209     application.
 210
 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)?
 215     @rtype: boolean
 216     '''
 217     # wrap the device event
 218     ev = event.DeviceEvent(ev)
 219     self.registry.handleDeviceEvent(ev, self)
 220     return ev.consume
 221
 222 class _EventObserver(_Observer, Accessibility__POA.EventListener):
 223   '''
 224   Observes all non-keyboard AT-SPI events. Can be reused across event types.
 225   '''
 226   def register(self, reg, name):
 227     '''
 228     Starts monitoring for the given event.
 229
 230     @param name: Name of the event to start monitoring
 231     @type name: string
 232     @param reg: Reference to the raw registry object
 233     @type reg: Accessibility.Registry
 234     '''
 235     reg.registerGlobalEventListener(self._this(), name)
 236
 237   def unregister(self, reg, name):
 238     '''
 239     Stops monitoring for the given event.
 240
 241     @param name: Name of the event to stop monitoring
 242     @type name: string
 243     @param reg: Reference to the raw registry object
 244     @type reg: Accessibility.Registry
 245     '''
 246     reg.deregisterGlobalEventListener(self._this(), name)
 247
 248   def queryInterface(self, repo_id):
 249     '''
 250     Reports that this class only implements the AT-SPI DeviceEventListener
 251     interface. Required by AT-SPI.
 252
 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
 257     '''
 258     if repo_id == utils.getInterfaceIID(Accessibility.EventListener):
 259       return self._this()
 260     else:
 261       return None
 262
 263   def notifyEvent(self, ev):
 264     '''
 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.
 268
 269     @param ev: AT-SPI event signal (anything but keyboard)
 270     @type ev: Accessibility.Event
 271     '''
 272     # wrap raw event so ref counts are correct before queueing
 273     ev = event.Event(ev)
 274     self.registry.handleEvent(ev)
 275
 276 class Registry(object):
 277   '''
 278   Wraps the Accessibility.Registry to provide more Pythonic registration for
 279   events.
 280
 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
 284   has no point.
 285
 286   @ivar async: Should event dispatch to local listeners be decoupled from event
 287     receiving from the registry?
 288   @type async: boolean
 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
 299   '''
 300   def __init__(self, reg):
 301     '''
 302     Stores a reference to the AT-SPI registry. Gets and stores a reference
 303     to the DeviceEventController.
 304
 305     @param reg: Reference to the AT-SPI registry daemon
 306     @type reg: Accessibility.Registry
 307     '''
 308     self.async = None
 309     self.reg = reg
 310     self.dev = self.reg.getDeviceEventController()
 311     self.queue = Queue.Queue()
 312     self.clients = {}
 313     self.observers = {}
 314
 315   def __call__(self):
 316     '''
 317     @return: This instance of the registry
 318     @rtype: L{Registry}
 319     '''
 320     return self
 321
 322   def start(self, async=False, gil=True):
 323     '''
 324     Enter the main loop to start receiving and dispatching events.
 325
 326     @param async: Should event dispatch be asynchronous (decoupled) from
 327       event receiving from the AT-SPI registry?
 328     @type async: boolean
 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.
 332     @type gil: boolean
 333     '''
 334     self.async = async
 335
 336     if gil:
 337       def releaseGIL():
 338         try:
 339           time.sleep(1e-5)
 340         except KeyboardInterrupt, e:
 341           # store the exception for later
 342           releaseGIL.keyboard_exception = e
 343           self.stop()
 344         return True
 345       # make room for an exception if one occurs during the
 346       releaseGIL.keyboard_exception = None
 347       i = gobject.idle_add(releaseGIL)
 348
 349     # enter the main loop
 350     exc = None
 351     try:
 352       bonobo.main()
 353     except Exception, e:
 354       # re-raise the keyboard interrupt later
 355       exc = e
 356
 357     # clear all observers
 358     for name, ob in self.observers.items():
 359       ob.unregister(self.reg, name)
 360     if gil:
 361       gobject.source_remove(i)
 362       exc = releaseGIL.keyboard_exception
 363     if exc is not None:
 364       # raise an keyboard exception we may have gotten earlier
 365       raise exc
 366
 367   def stop(self, *args):
 368     '''Quits the main loop.'''
 369     try:
 370       bonobo.main_quit()
 371     except RuntimeError:
 372       # ignore errors when quitting (probably already quitting)
 373       pass
 374
 375   def getDesktopCount(self):
 376     '''
 377     Gets the number of available desktops.
 378
 379     @return: Number of desktops
 380     @rtype: integer
 381     @raise LookupError: When the count cannot be retrieved
 382     '''
 383     try:
 384       return self.reg.getDesktopCount()
 385     except Exception:
 386       raise LookupError
 387
 388   def getDesktop(self, i):
 389     '''
 390     Gets a reference to the i-th desktop.
 391
 392     @param i: Which desktop to get
 393     @type i: integer
 394     @return: Desktop reference
 395     @rtype: Accessibility.Desktop
 396     @raise LookupError: When the i-th desktop cannot be retrieved
 397     '''
 398     try:
 399       return self.reg.getDesktop(i)
 400     except Exception, e:
 401       raise LookupError(e)
 402
 403   def registerEventListener(self, client, *names):
 404     '''
 405     Registers a new client callback for the given event names. Supports
 406     registration for all subevents if only partial event name is specified.
 407     Do not include a trailing colon.
 408
 409     For example, 'object' will register for all object events,
 410     'object:property-change' will register for all property change events,
 411     and 'object:property-change:accessible-parent' will register only for the
 412     parent property change event.
 413
 414     Registered clients will not be automatically removed when the client dies.
 415     To ensure the client is properly garbage collected, call
 416     L{deregisterEventListener}.
 417
 418     @param client: Callable to be invoked when the event occurs
 419     @type client: callable
 420     @param names: List of full or partial event names
 421     @type names: list of string
 422     '''
 423     for name in names:
 424       # store the callback for each specific event name
 425       self._registerClients(client, name)
 426
 427   def deregisterEventListener(self, client, *names):
 428     '''
 429     Unregisters an existing client callback for the given event names. Supports
 430     unregistration for all subevents if only partial event name is specified.
 431     Do not include a trailing colon.
 432
 433     This method must be called to ensure a client registered by
 434     L{registerEventListener} is properly garbage collected.
 435
 436     @param client: Client callback to remove
 437     @type client: callable
 438     @param names: List of full or partial event names
 439     @type names: list of string
 440     @return: Were event names specified for which the given client was not
 441       registered?
 442     @rtype: boolean
 443     '''
 444     missed = False
 445     for name in names:
 446       # remove the callback for each specific event name
 447       missed |= self._unregisterClients(client, name)
 448     return missed
 449
 450   def registerKeystrokeListener(self, client, key_set=[], mask=0,
 451                                 kind=(constants.KEY_PRESSED_EVENT,
 452                                       constants.KEY_RELEASED_EVENT),
 453                                 synchronous=True, preemptive=True,
 454                                 global_=False):
 455     '''
 456     Registers a listener for key stroke events.
 457
 458     @param client: Callable to be invoked when the event occurs
 459     @type client: callable
 460     @param key_set: Set of hardware key codes to stop monitoring. Leave empty
 461       to indicate all keys.
 462     @type key_set: list of integer
 463     @param mask: When the mask is None, the codes in the key_set will be
 464       monitored only when no modifier is held. When the mask is an
 465       integer, keys in the key_set will be monitored only when the modifiers in
 466       the mask are held. When the mask is an iterable over more than one
 467       integer, keys in the key_set will be monitored when any of the modifier
 468       combinations in the set are held.
 469     @type mask: integer, iterable, None
 470     @param kind: Kind of events to watch, KEY_PRESSED_EVENT or
 471       KEY_RELEASED_EVENT.
 472     @type kind: list
 473     @param synchronous: Should the callback notification be synchronous, giving
 474       the client the chance to consume the event?
 475     @type synchronous: boolean
 476     @param preemptive: Should the callback be allowed to preempt / consume the
 477       event?
 478     @type preemptive: boolean
 479     @param global_: Should callback occur even if an application not supporting
 480       AT-SPI is in the foreground? (requires xevie)
 481     @type global_: boolean
 482     '''
 483     try:
 484       # see if we already have an observer for this client
 485       ob = self.clients[client]
 486     except KeyError:
 487       # create a new device observer for this client
 488       ob = _DeviceObserver(self, synchronous, preemptive, global_)
 489       # store the observer to client mapping, and the inverse
 490       self.clients[ob] = client
 491       self.clients[client] = ob
 492     if mask is None:
 493       # None means all modifier combinations
 494       mask = utils.allModifiers()
 495     # register for new keystrokes on the observer
 496     ob.register(self.dev, key_set, mask, kind)
 497
 498   def deregisterKeystrokeListener(self, client, key_set=[], mask=0,
 499                                   kind=(constants.KEY_PRESSED_EVENT,
 500                                         constants.KEY_RELEASED_EVENT)):
 501     '''
 502     Deregisters a listener for key stroke events.
 503
 504     @param client: Callable to be invoked when the event occurs
 505     @type client: callable
 506     @param key_set: Set of hardware key codes to stop monitoring. Leave empty
 507       to indicate all keys.
 508     @type key_set: list of integer
 509     @param mask: When the mask is None, the codes in the key_set will be
 510       monitored only when no modifier is held. When the mask is an
 511       integer, keys in the key_set will be monitored only when the modifiers in
 512       the mask are held. When the mask is an iterable over more than one
 513       integer, keys in the key_set will be monitored when any of the modifier
 514       combinations in the set are held.
 515     @type mask: integer, iterable, None
 516     @param kind: Kind of events to stop watching, KEY_PRESSED_EVENT or
 517       KEY_RELEASED_EVENT.
 518     @type kind: list
 519     @raise KeyError: When the client isn't already registered for events
 520     '''
 521     # see if we already have an observer for this client
 522     ob = self.clients[client]
 523     if mask is None:
 524       # None means all modifier combinations
 525       mask = utils.allModifiers()
 526     # register for new keystrokes on the observer
 527     ob.unregister(self.dev, key_set, mask, kind)
 528
 529   def generateKeyboardEvent(self, keycode, keysym, kind):
 530     '''
 531     Generates a keyboard event. One of the keycode or the keysym parameters
 532     should be specified and the other should be None. The kind parameter is
 533     required and should be one of the KEY_PRESS, KEY_RELEASE, KEY_PRESSRELEASE,
 534     KEY_SYM, or KEY_STRING.
 535
 536     @param keycode: Hardware keycode or None
 537     @type keycode: integer
 538     @param keysym: Symbolic key string or None
 539     @type keysym: string
 540     @param kind: Kind of event to synthesize
 541     @type kind: integer
 542     '''
 543     if keysym is None:
 544       self.dev.generateKeyboardEvent(keycode, '', kind)
 545     else:
 546       self.dev.generateKeyboardEvent(None, keysym, kind)
 547
 548   def generateMouseEvent(self, x, y, name):
 549     '''
 550     Generates a mouse event at the given absolute x and y coordinate. The kind
 551     of event generated is specified by the name. For example, MOUSE_B1P
 552     (button 1 press), MOUSE_REL (relative motion), MOUSE_B3D (butten 3
 553     double-click).
 554
 555     @param x: Horizontal coordinate, usually left-hand oriented
 556     @type x: integer
 557     @param y: Vertical coordinate, usually left-hand oriented
 558     @type y: integer
 559     @param name: Name of the event to generate
 560     @type name: string
 561     '''
 562     self.dev.generateMouseEvent(x, y, name)
 563
 564   def handleDeviceEvent(self, event, ob):
 565     '''
 566     Dispatches L{event.DeviceEvent}s to registered clients. Clients are called
 567     in the order they were registered for the given AT-SPI event. If any
 568     client sets the L{event.DeviceEvent.consume} flag to True, callbacks cease
 569     for the event for clients of this registry instance. Clients of other
 570     registry instances and clients in other processes may be affected
 571     depending on the values of synchronous and preemptive used when invoking
 572     L{registerKeystrokeListener}.
 573
 574     @note: Asynchronous dispatch of device events is not supported.
 575
 576     @param event: AT-SPI device event
 577     @type event: L{event.DeviceEvent}
 578     @param ob: Observer that received the event
 579     @type ob: L{_DeviceObserver}
 580     '''
 581     try:
 582       # try to get the client registered for this event type
 583       client = self.clients[ob]
 584     except KeyError:
 585       # client may have unregistered recently, ignore event
 586       return
 587     # make the call to the client
 588     try:
 589       client(event)
 590     except Exception:
 591       # print the exception, but don't let it stop notification
 592       traceback.print_exc()
 593
 594   def handleEvent(self, event):
 595     '''
 596     Handles an AT-SPI event by either queuing it for later dispatch when the
 597     L{Registry.async} flag is set, or dispatching it immediately.
 598
 599     @param event: AT-SPI event
 600     @type event: L{event.Event}
 601     '''
 602     if self.async:
 603       # queue for now
 604       self.queue.put_nowait(event)
 605     else:
 606       # dispatch immediately
 607       self._dispatchEvent(event)
 608
 609   def _dispatchEvent(self, event):
 610     '''
 611     Dispatches L{event.Event}s to registered clients. Clients are called in
 612     the order they were registered for the given AT-SPI event. If any client
 613     sets the L{Event} consume flag to True, callbacks cease for the event for
 614     clients of this registry instance. Clients of other registry instances and
 615     clients in other processes are unaffected.
 616
 617     @param event: AT-SPI event
 618     @type event: L{event.Event}
 619     '''
 620     try:
 621       # try to get the client registered for this event type
 622       clients = self.clients[event.type.name]
 623     except KeyError:
 624       # client may have unregistered recently, ignore event
 625       return
 626     # make the call to each client
 627     for client in clients:
 628       try:
 629         client(event)
 630       except Exception:
 631         # print the exception, but don't let it stop notification
 632         traceback.print_exc()
 633       if event.consume:
 634         # don't allow further processing if the consume flag is set
 635         break
 636
 637   def _registerClients(self, client, name):
 638     '''
 639     Internal method that recursively associates a client with AT-SPI event
 640     names. Allows a client to incompletely specify an event name in order to
 641     register for subevents without specifying their full names manually.
 642
 643     @param client: Client callback to receive event notifications
 644     @type client: callable
 645     @param name: Partial or full event name
 646     @type name: string
 647     '''
 648     try:
 649       # look for an event name in our event tree dictionary
 650       events = constants.EVENT_TREE[name]
 651     except KeyError:
 652       # if the event name doesn't exist, it's a leaf event meaning there are
 653       # no subtypes for that event
 654       # add this client to the list of clients already in the dictionary
 655       # using the event name as the key; if there are no clients yet for this
 656       # event, insert an empty list into the dictionary before appending
 657       # the client
 658       et = event.EventType(name)
 659       clients = self.clients.setdefault(et.name, [])
 660       try:
 661         # if this succeeds, this client is already registered for the given
 662         # event type, so ignore the request
 663         clients.index(client)
 664       except ValueError:
 665         # else register the client
 666         clients.append(client)
 667         self._registerObserver(name)
 668     else:
 669         # if the event name does exist in the tree, there are subevents for
 670         # this event; loop through them calling this method again to get to
 671         # the leaf events
 672         for e in events:
 673           self._registerClients(client, e)
 674
 675   def _unregisterClients(self, client, name):
 676     '''
 677     Internal method that recursively unassociates a client with AT-SPI event
 678     names. Allows a client to incompletely specify an event name in order to
 679     unregister for subevents without specifying their full names manually.
 680
 681     @param client: Client callback to receive event notifications
 682     @type client: callable
 683     @param name: Partial or full event name
 684     @type name: string
 685     '''
 686     missed = False
 687     try:
 688       # look for an event name in our event tree dictionary
 689       events = constants.EVENT_TREE[name]
 690     except KeyError:
 691       try:
 692         # if the event name doesn't exist, it's a leaf event meaning there are
 693         # no subtypes for that event
 694         # get the list of registered clients and try to remove the one provided
 695         et = event.EventType(name)
 696         clients = self.clients[et.name]
 697         clients.remove(client)
 698         self._unregisterObserver(name)
 699       except (ValueError, KeyError):
 700         # ignore any exceptions indicating the client is not registered
 701         missed = True
 702       return missed
 703     # if the event name does exist in the tree, there are subevents for this
 704     # event; loop through them calling this method again to get to the leaf
 705     # events
 706     for e in events:
 707       missed |= self._unregisterClients(client, e)
 708     return missed
 709
 710   def _registerObserver(self, name):
 711     '''
 712     Creates a new L{_Observer} to watch for events of the given type or
 713     returns the existing observer if one is already registered. One
 714     L{_Observer} is created for each leaf in the L{constants.EVENT_TREE} or
 715     any event name not found in the tree.
 716
 717     @param name: Raw name of the event to observe
 718     @type name: string
 719     @return: L{_Observer} object that is monitoring the event
 720     @rtype: L{_Observer}
 721     '''
 722     et = event.EventType(name)
 723     try:
 724       # see if an observer already exists for this event
 725       ob = self.observers[et.name]
 726     except KeyError:
 727       # build a new observer if one does not exist
 728       ob = _EventObserver(self)
 729       # we have to register for the raw name because it may be different from
 730       # the parsed name determined by EventType (e.g. trailing ':' might be
 731       # missing)
 732       ob.register(self.reg, name)
 733       self.observers[et.name] = ob
 734     # increase our client ref count so we know someone new is watching for the
 735     # event
 736     ob.clientRef()
 737     return ob
 738
 739   def _unregisterObserver(self, name):
 740     '''
 741     Destroys an existing L{_Observer} for the given event type only if no
 742     clients are registered for the events it is monitoring.
 743
 744     @param name: Name of the event to observe
 745     @type name: string
 746     @raise KeyError: When an observer for the given event is not regist
 747     '''
 748     et = event.EventType(name)
 749     # see if an observer already exists for this event
 750     ob = self.observers[et.name]
 751     ob.clientUnref()
 752     if ob.getClientRefCount() == 0:
 753       ob.unregister(self.reg, name)
 754       del self.observers[et.name]