Setting Up a Client Host
------------------------

ConsoleUser matches visual patterns on the screen.  This means it's
expects certain visual settings to be in place otherwise the patterns
may not show up.  For example, if the resolution is changed the size of
the button to matchin, in pixels, will be different so the stored
pattern will not find it on the screen.

To help manage this, we provide a set of scripts that use ConsoleUser's
capabilities to apply many of the settings it expects for the system.
These scripts are named ``ConfigureXXX.py`` where the "XXX" is the
type of system to be configured.  E.g., ``ConfigureWin7.py`` will set 
up a Windows 7 system for ConsoleUser's use.  There are 3 ``Configure*``
files that do not configure a speciifc system, and are there for code
organization purposes:  ``ConfigureSystem.py``, ``ConfigureWindows.py``,
and ``ConfigureTester.py``,

To configure a system you will need to know the host and port of the
VNC server for that host.  These values are the ``SystemHost`` and
``SystemPort`` values in the ``user.conf`` for a user.  For some
systems it may also be necessary to pass an administrator username and
password.  To run this script, the target system should already be
logged in as the desired user, then run
``python3 ConfigureXXX.py -v <SystemHost> -p <SystemPort>``.  The
script will then connect to the system and perform a series of steps to
set things like the resolution, desktop theme, visual effects settings
and so forth.

Connection Information
======================

The ``-v`` and ``-p`` flags are required to specify, respectively, the
IP/hostname of the VNC server and the VNC port to connect to.  Any
other options can be passed in with a ``-c key=value`` flag, which can
be repeated many times to pass many values.  While the configuration
scrtips assume they cannot match patterns on the screen, so don't need
a ``regionTarget`` or similar as the normal operation of ConsoleUser
needs, it may need some information about how to interact with the
target system.

The most likely value that will need to be specified this way is one
that tells ConsoleUser how to type.  Some VNC servers exepct a special
character to be typed by sending a SHIFT+"base" character (e.g.,
sending SHIFT + 5 on this type of system will produce a % character).
Others expect the client to send the character itself that it wants
(e.g., just sending a % in the previous example).  And some have a
mixture of some situations using a SHIFT and some sending the desired
character.  These can be selected by setting the ``keyboardStrategy``
option.  The 3 most likely values are ``Simple`` to send SHIFT to
modify each character, as one would with a physical keyboard, or
``SimpleNoShift`` to always send the desired character without using a
SHIFT key to modify anything, or ``SimpleSomeShift`` to use the partial
solution described above.

If one watches the screen and sees that commands are being typed that
result in errors from missing commands or the like, it is most likely
the case that the wrong KeyboardStrategy is being used.

Examples
========

If there is a Windows 10 system that is being hosted 192.168.1.10 on
port 5912 we could invoke the proper script as follows:

.. code-block:: bash

    python3 ConfigureWindows10.py -v 192.168.1.10 -p 5912
    python3 ConfigureWindows7.py -v 192.168.1.10 -p 5910 -c keyboardStrategy=SimpleSomeShift