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     # register a signal handler for gracefully killing the loop
 337     signal.signal(signal.SIGINT, self.stop)
 338     signal.signal(signal.SIGTERM, self.stop)
 339
 340     if gil:
 341       def releaseGIL():
 342         time.sleep(1e-5)
 343         return True
 344       i = gobject.idle_add(releaseGIL)
 345
 346     # enter the main loop
 347     bonobo.main()
 348
 349     if gil:
 350       gobject.source_remove(i)
 351
 352   def stop(self, *args):
 353     '''Quits the main loop.'''
 354     try:
 355       bonobo.main_quit()
 356     except RuntimeError:
 357       # ignore errors when quitting (probably already quitting)
 358       pass
 359
 360   def getDesktopCount(self):
 361     '''
 362     Gets the number of available desktops.
 363
 364     @return: Number of desktops
 365     @rtype: integer
 366     @raise LookupError: When the count cannot be retrieved
 367     '''
 368     try:
 369       return self.reg.getDesktopCount()
 370     except Exception:
 371       raise LookupError
 372
 373   def getDesktop(self, i):
 374     '''
 375     Gets a reference to the i-th desktop.
 376
 377     @param i: Which desktop to get
 378     @type i: integer
 379     @return: Desktop reference
 380     @rtype: Accessibility.Desktop
 381     @raise LookupError: When the i-th desktop cannot be retrieved
 382     '''
 383     try:
 384       return self.reg.getDesktop(i)
 385     except Exception, e:
 386       raise LookupError(e)
 387
 388   def registerEventListener(self, client, *names):
 389     '''
 390     Registers a new client callback for the given event names. Supports
 391     registration for all subevents if only partial event name is specified.
 392     Do not include a trailing colon.
 393
 394     For example, 'object' will register for all object events,
 395     'object:property-change' will register for all property change events,
 396     and 'object:property-change:accessible-parent' will register only for the
 397     parent property change event.
 398
 399     Registered clients will not be automatically removed when the client dies.
 400     To ensure the client is properly garbage collected, call
 401     L{deregisterEventListener}.
 402
 403     @param client: Callable to be invoked when the event occurs
 404     @type client: callable
 405     @param names: List of full or partial event names
 406     @type names: list of string
 407     '''
 408     for name in names:
 409       # store the callback for each specific event name
 410       self._registerClients(client, name)
 411
 412   def deregisterEventListener(self, client, *names):
 413     '''
 414     Unregisters an existing client callback for the given event names. Supports
 415     unregistration for all subevents if only partial event name is specified.
 416     Do not include a trailing colon.
 417
 418     This method must be called to ensure a client registered by
 419     L{registerEventListener} is properly garbage collected.
 420
 421     @param client: Client callback to remove
 422     @type client: callable
 423     @param names: List of full or partial event names
 424     @type names: list of string
 425     @return: Were event names specified for which the given client was not
 426       registered?
 427     @rtype: boolean
 428     '''
 429     missed = False
 430     for name in names:
 431       # remove the callback for each specific event name
 432       missed |= self._unregisterClients(client, name)
 433     return missed
 434
 435   def registerKeystrokeListener(self, client, key_set=[], mask=0,
 436                                 kind=(constants.KEY_PRESSED_EVENT,
 437                                       constants.KEY_RELEASED_EVENT),
 438                                 synchronous=True, preemptive=True,
 439                                 global_=False):
 440     '''
 441     Registers a listener for key stroke events.
 442
 443     @param client: Callable to be invoked when the event occurs
 444     @type client: callable
 445     @param key_set: Set of hardware key codes to stop monitoring. Leave empty
 446       to indicate all keys.
 447     @type key_set: list of integer
 448     @param mask: When the mask is None, the codes in the key_set will be
 449       monitored only when no modifier is held. When the mask is an
 450       integer, keys in the key_set will be monitored only when the modifiers in
 451       the mask are held. When the mask is an iterable over more than one
 452       integer, keys in the key_set will be monitored when any of the modifier
 453       combinations in the set are held.
 454     @type mask: integer, iterable, None
 455     @param kind: Kind of events to watch, KEY_PRESSED_EVENT or
 456       KEY_RELEASED_EVENT.
 457     @type kind: list
 458     @param synchronous: Should the callback notification be synchronous, giving
 459       the client the chance to consume the event?
 460     @type synchronous: boolean
 461     @param preemptive: Should the callback be allowed to preempt / consume the
 462       event?
 463     @type preemptive: boolean
 464     @param global_: Should callback occur even if an application not supporting
 465       AT-SPI is in the foreground? (requires xevie)
 466     @type global_: boolean
 467     '''
 468     try:
 469       # see if we already have an observer for this client
 470       ob = self.clients[client]
 471     except KeyError:
 472       # create a new device observer for this client
 473       ob = _DeviceObserver(self, synchronous, preemptive, global_)
 474       # store the observer to client mapping, and the inverse
 475       self.clients[ob] = client
 476       self.clients[client] = ob
 477     if mask is None:
 478       # None means all modifier combinations
 479       mask = utils.allModifiers()
 480     # register for new keystrokes on the observer
 481     ob.register(self.dev, key_set, mask, kind)
 482
 483   def deregisterKeystrokeListener(self, client, key_set=[], mask=0,
 484                                   kind=(constants.KEY_PRESSED_EVENT,
 485                                         constants.KEY_RELEASED_EVENT)):
 486     '''
 487     Deregisters a listener for key stroke events.
 488
 489     @param client: Callable to be invoked when the event occurs
 490     @type client: callable
 491     @param key_set: Set of hardware key codes to stop monitoring. Leave empty
 492       to indicate all keys.
 493     @type key_set: list of integer
 494     @param mask: When the mask is None, the codes in the key_set will be
 495       monitored only when no modifier is held. When the mask is an
 496       integer, keys in the key_set will be monitored only when the modifiers in
 497       the mask are held. When the mask is an iterable over more than one
 498       integer, keys in the key_set will be monitored when any of the modifier
 499       combinations in the set are held.
 500     @type mask: integer, iterable, None
 501     @param kind: Kind of events to stop watching, KEY_PRESSED_EVENT or
 502       KEY_RELEASED_EVENT.
 503     @type kind: list
 504     @raise KeyError: When the client isn't already registered for events
 505     '''
 506     # see if we already have an observer for this client
 507     ob = self.clients[client]
 508     if mask is None:
 509       # None means all modifier combinations
 510       mask = utils.allModifiers()
 511     # register for new keystrokes on the observer
 512     ob.unregister(self.dev, key_set, mask, kind)
 513
 514   def generateKeyboardEvent(self, keycode, keysym, kind):
 515     '''
 516     Generates a keyboard event. One of the keycode or the keysym parameters
 517     should be specified and the other should be None. The kind parameter is
 518     required and should be one of the KEY_PRESS, KEY_RELEASE, KEY_PRESSRELEASE,
 519     KEY_SYM, or KEY_STRING.
 520
 521     @param keycode: Hardware keycode or None
 522     @type keycode: integer
 523     @param keysym: Symbolic key string or None
 524     @type keysym: string
 525     @param kind: Kind of event to synthesize
 526     @type kind: integer
 527     '''
 528     if keysym is None:
 529       self.dev.generateKeyboardEvent(keycode, '', kind)
 530     else:
 531       self.dev.generateKeyboardEvent(None, keysym, kind)
 532
 533   def generateMouseEvent(self, x, y, name):
 534     '''
 535     Generates a mouse event at the given absolute x and y coordinate. The kind
 536     of event generated is specified by the name. For example, MOUSE_B1P
 537     (button 1 press), MOUSE_REL (relative motion), MOUSE_B3D (butten 3
 538     double-click).
 539
 540     @param x: Horizontal coordinate, usually left-hand oriented
 541     @type x: integer
 542     @param y: Vertical coordinate, usually left-hand oriented
 543     @type y: integer
 544     @param name: Name of the event to generate
 545     @type name: string
 546     '''
 547     self.dev.generateMouseEvent(x, y, name)
 548
 549   def handleDeviceEvent(self, event, ob):
 550     '''
 551     Dispatches L{event.DeviceEvent}s to registered clients. Clients are called
 552     in the order they were registered for the given AT-SPI event. If any
 553     client sets the L{event.DeviceEvent.consume} flag to True, callbacks cease
 554     for the event for clients of this registry instance. Clients of other
 555     registry instances and clients in other processes may be affected
 556     depending on the values of synchronous and preemptive used when invoking
 557     L{registerKeystrokeListener}.
 558
 559     @note: Asynchronous dispatch of device events is not supported.
 560
 561     @param event: AT-SPI device event
 562     @type event: L{event.DeviceEvent}
 563     @param ob: Observer that received the event
 564     @type ob: L{_DeviceObserver}
 565     '''
 566     try:
 567       # try to get the client registered for this event type
 568       client = self.clients[ob]
 569     except KeyError:
 570       # client may have unregistered recently, ignore event
 571       return
 572     # make the call to the client
 573     try:
 574       client(event)
 575     except Exception:
 576       # print the exception, but don't let it stop notification
 577       traceback.print_exc()
 578
 579   def handleEvent(self, event):
 580     '''
 581     Handles an AT-SPI event by either queuing it for later dispatch when the
 582     L{Registry.async} flag is set, or dispatching it immediately.
 583
 584     @param event: AT-SPI event
 585     @type event: L{event.Event}
 586     '''
 587     if self.async:
 588       # queue for now
 589       self.queue.put_nowait(event)
 590     else:
 591       # dispatch immediately
 592       self._dispatchEvent(event)
 593
 594   def _dispatchEvent(self, event):
 595     '''
 596     Dispatches L{event.Event}s to registered clients. Clients are called in
 597     the order they were registered for the given AT-SPI event. If any client
 598     sets the L{Event} consume flag to True, callbacks cease for the event for
 599     clients of this registry instance. Clients of other registry instances and
 600     clients in other processes are unaffected.
 601
 602     @param event: AT-SPI event
 603     @type event: L{event.Event}
 604     '''
 605     try:
 606       # try to get the client registered for this event type
 607       clients = self.clients[event.type.name]
 608     except KeyError:
 609       # client may have unregistered recently, ignore event
 610       return
 611     # make the call to each client
 612     for client in clients:
 613       try:
 614         client(event)
 615       except Exception:
 616         # print the exception, but don't let it stop notification
 617         traceback.print_exc()
 618       if event.consume:
 619         # don't allow further processing if the consume flag is set
 620         break
 621
 622   def _registerClients(self, client, name):
 623     '''
 624     Internal method that recursively associates a client with AT-SPI event
 625     names. Allows a client to incompletely specify an event name in order to
 626     register for subevents without specifying their full names manually.
 627
 628     @param client: Client callback to receive event notifications
 629     @type client: callable
 630     @param name: Partial or full event name
 631     @type name: string
 632     '''
 633     try:
 634       # look for an event name in our event tree dictionary
 635       events = constants.EVENT_TREE[name]
 636     except KeyError:
 637       # if the event name doesn't exist, it's a leaf event meaning there are
 638       # no subtypes for that event
 639       # add this client to the list of clients already in the dictionary
 640       # using the event name as the key; if there are no clients yet for this
 641       # event, insert an empty list into the dictionary before appending
 642       # the client
 643       et = event.EventType(name)
 644       clients = self.clients.setdefault(et.name, [])
 645       try:
 646         # if this succeeds, this client is already registered for the given
 647         # event type, so ignore the request
 648         clients.index(client)
 649       except ValueError:
 650         # else register the client
 651         clients.append(client)
 652         self._registerObserver(name)
 653     else:
 654         # if the event name does exist in the tree, there are subevents for
 655         # this event; loop through them calling this method again to get to
 656         # the leaf events
 657         for e in events:
 658           self._registerClients(client, e)
 659
 660   def _unregisterClients(self, client, name):
 661     '''
 662     Internal method that recursively unassociates a client with AT-SPI event
 663     names. Allows a client to incompletely specify an event name in order to
 664     unregister for subevents without specifying their full names manually.
 665
 666     @param client: Client callback to receive event notifications
 667     @type client: callable
 668     @param name: Partial or full event name
 669     @type name: string
 670     '''
 671     missed = False
 672     try:
 673       # look for an event name in our event tree dictionary
 674       events = constants.EVENT_TREE[name]
 675     except KeyError:
 676       try:
 677         # if the event name doesn't exist, it's a leaf event meaning there are
 678         # no subtypes for that event
 679         # get the list of registered clients and try to remove the one provided
 680         et = event.EventType(name)
 681         clients = self.clients[et.name]
 682         clients.remove(client)
 683         self._unregisterObserver(name)
 684       except (ValueError, KeyError):
 685         # ignore any exceptions indicating the client is not registered
 686         missed = True
 687       return missed
 688     # if the event name does exist in the tree, there are subevents for this
 689     # event; loop through them calling this method again to get to the leaf
 690     # events
 691     for e in events:
 692       missed |= self._unregisterClients(client, e)
 693     return missed
 694
 695   def _registerObserver(self, name):
 696     '''
 697     Creates a new L{_Observer} to watch for events of the given type or
 698     returns the existing observer if one is already registered. One
 699     L{_Observer} is created for each leaf in the L{constants.EVENT_TREE} or
 700     any event name not found in the tree.
 701
 702     @param name: Raw name of the event to observe
 703     @type name: string
 704     @return: L{_Observer} object that is monitoring the event
 705     @rtype: L{_Observer}
 706     '''
 707     et = event.EventType(name)
 708     try:
 709       # see if an observer already exists for this event
 710       ob = self.observers[et.name]
 711     except KeyError:
 712       # build a new observer if one does not exist
 713       ob = _EventObserver(self)
 714       # we have to register for the raw name because it may be different from
 715       # the parsed name determined by EventType (e.g. trailing ':' might be
 716       # missing)
 717       ob.register(self.reg, name)
 718       self.observers[et.name] = ob
 719     # increase our client ref count so we know someone new is watching for the
 720     # event
 721     ob.clientRef()
 722     return ob
 723
 724   def _unregisterObserver(self, name):
 725     '''
 726     Destroys an existing L{_Observer} for the given event type only if no
 727     clients are registered for the events it is monitoring.
 728
 729     @param name: Name of the event to observe
 730     @type name: string
 731     @raise KeyError: When an observer for the given event is not regist
 732     '''
 733     et = event.EventType(name)
 734     # see if an observer already exists for this event
 735     ob = self.observers[et.name]
 736     ob.clientUnref()
 737     if ob.getClientRefCount() == 0:
 738       ob.unregister(self.reg, name)
 739       del self.observers[et.name]