root/projects/WinDictator/trunk/windictator/linux/typist.py

# WinDictator:
# Dictate in Windows, have the text typed in Linux via X faked keystroke events
#
# Copyright (C) 2005-2006 by Edwin A. Suominen, http://www.eepatents.com
#
# This program is free software; you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free Software
# Foundation; either version 2 of the License, or (at your option) any later
# version.
# 
# 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 file COPYING for more details.
# 
# You should have received a copy of the GNU 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


"""
A virtual typist
"""

from twisted.internet import defer

import observer, keyer, keycodes


class Typist(object):
    """
    I type what you send. Give me some text and I'll see that the right fake
    keystrokes are generated

    """
    def __init__(self):
        self.history = observer.KeyHistory()
        self.observer = observer.Observer(self.history)
        self.keyer = keyer.Keyer()
        self.keyCoder = keycodes.KeyCoder()

    def startup(self, *null):
        """
        Starts up all my helpers, returning a C{Deferred} that fires when all
        are ready.
        """
        d1 = self.keyer.startup()
        d2 = self.observer.startup()
        return defer.DeferredList([d1,d2])

    def shutdown(self, *null):
        """
        Shuts down up all my helpers, returning a C{Deferred} that fires when
        all are stopped.
        """
        d1 = self.keyer.shutdown()
        d2 = self.observer.shutdown()
        return defer.DeferredList([d1,d2])

    @defer.deferredGenerator
    def pressAndReleaseKeys(self, keyList):
        """
        This method is decorated with L{defer.deferredGenerator} to immediately
        return a C{Deferred} that fires upon completion of an iteration over
        key combinations, which are supplied as sub-sequences of the I{keyList}
        sequence. The deferred fires with C{True} if all keys were observed to
        have been pressed and reseased, C{False} otherwise.

        The generator sends fake X key events for each key of each
        sub-sequence, a keypress followed by a release, and waits for
        confirmation of each faked key event before proceeding with the next
        one.
        """
        running = True
        
        def gotConfirmation(confirmed):
            running = confirmed
            return confirmed
        
        def keyAndConfirm(func, key):
            d = func(key)
            d.addCallback(self.observer.confirm)
            d.addCallback(gotConfirmation)
            return defer.waitForDeferred(d)
        
        stack = []
        while running and keyList:
            keySequence = keyList.pop(0)
            # Depress each key in order
            for key in keySequence:
                stack.append(key)
                wfd = keyAndConfirm(self.keyer.pressKey, key)
                yield wfd
                if not wfd.getResult():
                    # Key depression not noted, try one more time
                    yield defer.waitForDeferred(self.keyer.releaseKey(key))
                    wfd = keyAndConfirm(self.keyer.pressKey, key)
                    yield wfd
                    if not wfd.getResult():
                        # Key depression still not noted, bail out
                        yield defer.waitForDeferred(self.keyer.releaseKey(key))
                        running = False
                        break
            # Release each key in reverse order
            while running and stack:
                key = stack.pop()
                wfd = keyAndConfirm(self.keyer.releaseKey, key)
                yield wfd
                if not wfd.getResult():
                    # Key release not noted, bail out
                    running = False
        # Final yield of a Boolean, rather than a wfd, is supplied to the
        # deferredGenerator's callback
        yield running

    def backspace(self, N):
        """
        Deletes backwards I{N} characters using the C{BackSpace} keysym.
        """
        if self.typingEnabled():
            self.history.backspace(N)
            keyList = [("BackSpace",)] * N
            d = self.pressAndReleaseKeys(keyList)
        else:
            # Typing isn't enabled, just return a Deferred that immediately
            # fires with False typing-failed status
            d = defer.succeed(False)
        return d

    def insert(self, text):
        """
        Parses the supplied I{text} and sends chunks to the appropriate methods
        of the keyer, returning C{True} if entry of all text was noted and
        C{False} if not.
        """
        if self.typingEnabled:
            text = self.contextAdjust(text)
            keyList = self.keyCoder.textToKeys(text)
            d = self.pressAndReleaseKeys(keyList)
        else:
            # Typing isn't enabled, just return a Deferred that immediately
            # fires with False typing-failed status
            d = defer.succeed(False)
        return d

    def typingEnabled(self, text=None):
        """
        Indicates whether typing is currently enabled based on the last text
        supplied and a recent history of observed keystrokes. Typing is B{not}
        enabled if any of the following conditions are met:

            - the last observed keystroke was recently typed and implemented
              cursor movement;

            - the last observed keystroke implemented cursor movement and the
              last-supplied text consists of single word;

            - the dictation mode is 'sleep' instead of 'active'

        """
        # TODO
        return True
   
    def contextAdjust(self, text):
        """
        Adjusts the supplied I{text} based on a recent history of observed
        keystrokes, excluding I{charsBackwards} characters that are being
        skipped over or trimmed off the tail end of the history to reach the
        insertion point. Here are the rules:

            - If a word, comma, or semicolon followed by zero or one space was
              previously entered, and the beginning of this text is another
              word, this text will be adjusted as needed to have a single space
              present.

            - If a period, exclamation point, or question mark followed by zero
              through two spaces was previously entered, and the beginning of
              this text is another word, this text will be adjusted as needed
              to have two spaces present and have the new text start with a
              capital letter.

            - If a hyphen was previously entered with no spaces thereafter, any
              spaces at the beginning of this text will be deleted and the
              first letter will be forced to lowercase.
            
        """
        # TODO
        return text