.. _RefTextEngine:

Text-input engine back-end
============================================================================

The text-input engine is a convenient, always available implementation
designed to be used via the :meth:`engine.mimic` method.

To initialize the text-input engine, do the following::

    get_engine("text")

Note that :meth:`dragonfly.engines.get_engine` called without
``"text"`` will **never** initialize the text-input engine.  This is
because real speech recognition backends should be returned from the
function by default.

All dragonfly elements and rule classes should be
supported. `executable`, `title`, and `handle` keyword arguments may
optionally be passed to :meth:`engine.mimic` to simulate a particular
foreground window.


Engine Configuration
----------------------------------------------------------------------------

Dragonfly's :ref:`command-line interface <RefCLI>` can be used to test
command modules with the text-input engine.  Below are a few use cases
for this engine:

.. code:: shell

   # Example 1:
   # Initialize the text-input engine back-end, load a command module and
   # recognize from stdin.
   echo "hello world" | python -m dragonfly test _module1.py

   # Example 2:
   # Initialize the text-input engine back-end and load a command module
   # for browser commands and recognize from stdin with a processing delay
   # of 2 seconds.  This allows testing context-specific browser commands.
   python -m dragonfly test _browser.py --delay 2

   # Example 3:
   # Initialize the text-input engine back-end using German (de) as the
   # language, then load a command module and recognize from stdin.
   python -m dragonfly test _german_commands.py --language de



Engine API
----------------------------------------------------------------------------

.. autoclass:: dragonfly.engines.backend_text.engine.TextInputEngine
   :members:


.. _RefTextEngineResultsClass:

Text Recognition Results Class
----------------------------------------------------------------------------

.. autoclass:: dragonfly.engines.backend_text.engine.Results
   :members: