#Copyright (C) 2010 Novell, Inc.
#Copyright (C) 2008 Codethink Ltd
#copyright: Copyright (c) 2005, 2007 IBM Corporation

#This library is free software; you can redistribute it and/or
#modify it under the terms of the GNU Lesser General Public
#License version 2 as published by the Free Software Foundation.

#This program is distributed in the hope that it will be useful,
#but WITHOUT ANY WARRANTY; without even the implied warranty of
#MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#GNU General Public License for more details.
#You should have received a copy of the GNU Lesser General Public License
#along with this program; if not, write to the Free Software
#Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

#Portions of this code originally licensed and copyright (c) 2005, 2007
#IBM Corporation under the BSD license, available at
#U{http://www.opensource.org/licenses/bsd-license.php}

#authors: Peter Parente, Mark Doffman

#------------------------------------------------------------------------------

__all__ = ["Registry",
           "MAIN_LOOP_GLIB",
           "MAIN_LOOP_NONE",
           "set_default_registry"]

import os as _os
from gi.repository import Atspi
from gi.repository import GLib
import time

#------------------------------------------------------------------------------

MAIN_LOOP_GLIB = 'GLib'
MAIN_LOOP_QT   = 'Qt'
MAIN_LOOP_NONE = 'None'

#------------------------------------------------------------------------------

class Registry(object):
        """
        Wraps the Accessibility.Registry to provide more Pythonic registration for
        events.

        This object should be treated as a singleton, but such treatment is not
        enforced. You can construct another instance of this object and give it a
        reference to the Accessibility.Registry singleton. Doing so is harmless and
        has no point.

        @@ivar asynchronous: Should event dispatch to local listeners be decoupled
                from event receiving from the registry?
        @@type asynchronous: boolean
        @@ivar reg: Reference to the real, wrapped registry object
        @@type reg: Accessibility.Registry
        @@ivar dev: Reference to the device controller
        @@type dev: Accessibility.DeviceEventController
        @@ivar clients: Map of event names to client listeners
        @@type clients: dictionary
        @@ivar observers: Map of event names to AT-SPI L{_Observer} objects
        @@type observers: dictionary
        """
        __shared_state = {}

        def __init__(self):
                self.__dict__ = self.__shared_state

                try:
                        if (self.has_implementations):
                                return
                except (AttributeError):
                        pass

                self.has_implementations = False

                self.device_event_register = None
                self.app_event_register = None
                self.desktop = None

                self.main_loop = GLib.MainLoop()

        def __call__(self):
                """
                @@return: This instance of the registry
                @@rtype: L{Registry}
                """
                return self

        def _set_registry (self, main_loop_type, app_name=None):
                """
                Creates a new 'Registry' object and sets this object
                as the default returned by pyatspi.Registry.

                The default registry (without calling this function) uses the
                GLib main loop with caching. It connects to a registry daemon.

                This function should be called before pyatspi is used if you
                wish to change these defaults.

                @@param main_loop_type: 'GLib', 'None' or 'Qt'. If 'None' is selected then caching
                                       is disabled.

                @@param use_registry: Whether to connect to a registry daemon for device events.
                                     Without this the application to connect to must be declared in the
                                     app_name parameter.

                @@param app_name: D-Bus name of the application to connect to when not using the registry daemon.
                """

                self.has_implementations = True

                self.asynchronous = False	# not fully supported yet
                self.started = False
                self.event_listeners = dict()

        def __getattr__(self, name):
            """
            For backwards compatibility with old API
            """
            if name == 'async':
                return self.asynchronous
            return object.__getattr__(self, name)

        def __setattr__(self, name, value):
            """
            For backwards compatibility with old API
            """
            if name == 'async':
                self.asynchronous = value
            object.__setattr__(self, name, value)

        def _set_default_registry (self):
                self._set_registry (MAIN_LOOP_GLIB)

        def start(self, asynchronous=False, gil=True, **kwargs):
                """
                Enter the main loop to start receiving and dispatching events.

                @@param asynchronous: Should event dispatch be asynchronous
                        (decoupled) from event receiving from the AT-SPI registry?
                @@type asynchronous: boolean
                @@param gil: Add an idle callback which releases the Python GIL for a few
                        milliseconds to allow other threads to run? Necessary if other threads
                        will be used in this process.
                @@type gil: boolean
                """
                if 'async' in kwargs:
                    # support previous API
                    asynchronous = kwargs['async']
                if not self.has_implementations:
                        self._set_default_registry ()
                self.started = True

                if gil:
                        def releaseGIL():
                                try:
                                        time.sleep(1e-2)
                                except KeyboardInterrupt as e:
                                        # store the exception for later
                                        releaseGIL.keyboard_exception = e
                                        self.stop()
                                return True
                        # make room for an exception if one occurs during the 
                        releaseGIL.keyboard_exception = None
                        i = GLib.idle_add(releaseGIL)
                        Atspi.event_main()
                        GLib.source_remove(i)
                        if releaseGIL.keyboard_exception is not None:
                                # raise an keyboard exception we may have gotten earlier
                                raise releaseGIL.keyboard_exception
                else:
                        Atspi.event_main()

                self.started = False

        def stop(self, *args):
                """
                Quits the main loop.
                """
                if not self.has_implementations:
                        self._set_default_registry ()
                Atspi.event_quit()

        def getDesktopCount(self):
                """
                Gets the number of available desktops.

                @@return: Number of desktops
                @@rtype: integer
                """
                return 1

        def getDesktop(self, i):
                """
                Gets a reference to the i-th desktop.

                @@param i: Which desktop to get
                @@type i: integer
                @@return: Desktop reference
                @@rtype: Accessibility.Desktop
                """
                if not self.has_implementations:
                        self._set_default_registry ()
                return Atspi.get_desktop(i)

        def eventWrapper(self, event, callback):
                return callback(event)

        def registerEventListener(self, client, *names):
                """
                Registers a new client callback for the given event names. Supports 
                registration for all subevents if only partial event name is specified.
                Do not include a trailing colon.

                For example, 'object' will register for all object events, 
                'object:property-change' will register for all property change events,
                and 'object:property-change:accessible-parent' will register only for the
                parent property change event.

                Registered clients will not be automatically removed when the client dies.
                To ensure the client is properly garbage collected, call 
                L{deregisterEventListener}.

                @@param client: Callable to be invoked when the event occurs
                @@type client: callable
                @@param names: List of full or partial event names
                @@type names: list of string
                """
                if not self.has_implementations:
                        self._set_default_registry ()
                try:
                        listener = self.event_listeners[client]
                except:
                        listener = self.event_listeners[client] = Atspi.EventListener.new(self.eventWrapper, client)
                for name in names:
                        Atspi.EventListener.register (listener, name)

        def registerEventListenerWithApp(self, client, app, *names):
                """
                Registers a new client callback for the given event names. Supports
                registration for all subevents if only partial event name is specified.
                Do not include a trailing colon.

                For example, 'object' will register for all object events,
                'object:property-change' will register for all property change events,
                and 'object:property-change:accessible-parent' will register only for the
                parent property change event.

                Registered clients will not be automatically removed when the client dies.
                To ensure the client is properly garbage collected, call
                L{deregisterEventListener}.

                @@param client: Callable to be invoked when the event occurs
                @@type client: callable
                @@param names: List of full or partial event names
                @@type names: list of string
                """
                if not self.has_implementations:
                        self._set_default_registry ()
                try:
                        listener = self.event_listeners[client]
                except:
                        listener = self.event_listeners[client] = Atspi.EventListener.new(self.eventWrapper, client)
                for name in names:
                        Atspi.EventListener.register_with_app (listener, name, None, app)

        def deregisterEventListener(self, client, *names):
                """
                Unregisters an existing client callback for the given event names. Supports 
                unregistration for all subevents if only partial event name is specified.
                Do not include a trailing colon.

                This method must be called to ensure a client registered by
                L{registerEventListener} is properly garbage collected.

                @@param client: Client callback to remove
                @@type client: callable
                @@param names: List of full or partial event names
                @@type names: list of string
                @@return: Were event names specified for which the given client was not
                        registered?
                @@rtype: boolean
                """
                if not self.has_implementations:
                        self._set_default_registry ()
                try:
                        listener = self.event_listeners[client]
                except:
                        return
                for name in names:
                        Atspi.EventListener.deregister(listener, name)

        # -------------------------------------------------------------------------------

        # TODO: Remove this hack
        _KEY_PRESSED_EVENT=0
        _KEY_RELEASED_EVENT=1

        def makeSyncType(self, synchronous, preemptive, global_):
                result = Atspi.KeyListenerSyncType.NOSYNC
                if synchronous:
                        result |= Atspi.KeyListenerSyncType.SYNCHRONOUS
                if preemptive:
                        result |= Atspi.KeyListenerSyncType.CANCONSUME
                if global_:
                        result |= Atspi.KeyListenerSyncType.ALL_WINDOWS
                return result

        def makeKind(self, kind):
                result = 0
                for i in kind:
                        result |= (1 << i)
                return result

        def registerKeystrokeListener(self,
                                      client,
                                      key_set=[],
                                      mask=0,
                                      kind=(_KEY_PRESSED_EVENT, _KEY_RELEASED_EVENT),
                                      synchronous=True,
                                      preemptive=True,
                                      global_=False):
                """
                Registers a listener for key stroke events.

                @@param client: Callable to be invoked when the event occurs
                @@type client: callable
                @@param key_set: Set of hardware key codes to stop monitoring. Leave empty
                        to indicate all keys.
                @@type key_set: list of integer
                @@param mask: When the mask is None, the codes in the key_set will be 
                        monitored only when no modifier is held. When the mask is an 
                        integer, keys in the key_set will be monitored only when the modifiers in
                        the mask are held. When the mask is an iterable over more than one 
                        integer, keys in the key_set will be monitored when any of the modifier
                        combinations in the set are held.
                @@type mask: integer, iterable, None
                @@param kind: Kind of events to watch, KEY_PRESSED_EVENT or 
                        KEY_RELEASED_EVENT.
                @@type kind: list
                @@param synchronous: Should the callback notification be synchronous, giving
                        the client the chance to consume the event?
                @@type synchronous: boolean
                @@param preemptive: Should the callback be allowed to preempt / consume the
                        event?
                @@type preemptive: boolean
                @@param global_: Should callback occur even if an application not supporting
                        AT-SPI is in the foreground? (requires xevie)
                @@type global_: boolean
                """
                if not self.has_implementations:
                        self._set_default_registry ()
                try:
                        listener = self.event_listeners[client]
                except:
                        listener = self.event_listeners[client] = Atspi.DeviceListener.new(self.eventWrapper, client)
                syncFlag = self.makeSyncType(synchronous, preemptive, global_)
                if hasattr(mask, '__iter__'):
                        masks = mask
                else:
                        masks = [mask]
                for m in masks:
                        Atspi.register_keystroke_listener(listener,
                                                          key_set,
                                                          m,
                                                          self.makeKind (kind),
                                                          syncFlag)

        def deregisterKeystrokeListener(self,
                                        client,
                                        key_set=[],
                                        mask=0,
                                        kind=(_KEY_PRESSED_EVENT, _KEY_RELEASED_EVENT)):
                """
                Deregisters a listener for key stroke events.

                @@param client: Callable to be invoked when the event occurs
                @@type client: callable
                @@param key_set: Set of hardware key codes to stop monitoring. Leave empty
                        to indicate all keys.
                @@type key_set: list of integer
                @@param mask: When the mask is None, the codes in the key_set will be 
                        monitored only when no modifier is held. When the mask is an 
                        integer, keys in the key_set will be monitored only when the modifiers in
                        the mask are held. When the mask is an iterable over more than one 
                        integer, keys in the key_set will be monitored when any of the modifier
                        combinations in the set are held.
                @@type mask: integer, iterable, None
                @@param kind: Kind of events to stop watching, KEY_PRESSED_EVENT or 
                        KEY_RELEASED_EVENT.
                @@type kind: list
                @@raise KeyError: When the client isn't already registered for events
                """
                if not self.has_implementations:
                        self._set_default_registry ()
                try:
                        listener = self.event_listeners[client]
                except:
                        return

                if hasattr(mask, '__iter__'):
                        masks = mask
                else:
                        masks = [mask]
                for m in masks:
                        Atspi.deregister_keystroke_listener (listener, key_set,
                                m, self.makeKind(kind))

                # TODO: enqueueEvent, etc?

        def generateKeyboardEvent(self, keycode, keysym, kind):
                """
                Generates a keyboard event. One of the keycode or the keysym parameters
                should be specified and the other should be None. The kind parameter is 
                required and should be one of the KEY_PRESS, KEY_RELEASE, KEY_PRESSRELEASE,
                KEY_SYM, KEY_STRING, KEY_LOCKMODIFIERS, or KEY_UNLOCKMODIFIERS.

                @@param keycode: Hardware keycode or None
                @@type keycode: integer
                @@param keysym: Symbolic key string or None
                @@type keysym: string
                @@param kind: Kind of event to synthesize
                @@type kind: integer
                """
                if not self.has_implementations:
                        self._set_default_registry ()
                if keysym is None:
                        keysym = ""
                Atspi.generate_keyboard_event (keycode, keysym, kind)

        def generateMouseEvent(self, x, y, name):
                """
                Generates a mouse event at the given absolute x and y coordinate. The kind
                of event generated is specified by the name. For example, MOUSE_B1P 
                (button 1 press), MOUSE_REL (relative motion), MOUSE_B3D (butten 3 
                double-click).

                @@param x: Horizontal coordinate, usually left-hand oriented
                @@type x: integer
                @@param y: Vertical coordinate, usually left-hand oriented
                @@type y: integer
                @@param name: Name of the event to generate
                @@type name: string
                """
                if not self.has_implementations:
                        self._set_default_registry ()
                Atspi.generate_mouse_event (x, y, name)

        def setReferenceWIndow(accessible):
                """
                Sets the reference window that will be used when
                generateMouseEvent is called. Coordinates will be assumed to
                be relative to this window. This * is needed because, due to
                Wayland's security model, it is not currently possible to
                possible to retrieve global coordinates.
                If NULL is passed, then AT-SPI will use the window that has
                focus at the time that atspi_generate_mouse_event is called.

                @@param accessible: the accessible corresponding to the window
                to select. should be a top-level window with a role of
                pyatspi.ROLE_APPLICATION.
                """
                if not self.has_implementations:
                        self._set_default_registry ()
                Atspi.setReferenceWindow(accessible)

        def pumpQueuedEvents (self):
                """
                Dispatch events that have been queued.
                """
                pass

def set_default_registry (main_loop, app_name=None):
        registry = Registry ()
        registry._set_registry (main_loop, app_name)
