zKeyboard
=============================================================================

    The zKeyboard class handles keyboard input. It works in normal and SDK
    modes and can handle extended keys from the remote modem. You should
    use the kb???? constants defined in the KBCODES.H header file to
    interpret the resulting return values.

    The polling releases time slices to various multitaskers!

    You can construct as many zKeyboard objects as you need. The first one
    that you create will install the handler required by the SDK (if used in
    the SDK mode). When destroying, the last object will remove this handler.

    The default operation in SDK mode only captures the right, left, up,
    down, home, end, insert, and delete keys. There is a paranoid mode which
    will also capture (i.e. ProBoard will not see) Alt+F?? keys, PgUp,
    PgDown, Alt+B, Alt+K, Alt+P, Ctrl+Left, and Ctrl+Right. For more on this
    mode, refer to the 'paranoid' class member.

    When there are several keystrokes in the internal queues, the keys from
    the remote end (SDK only) receive precedence.


    ZKEYBOARD::ZKEYBOARD
    -------------------------------------------------------------------------

        Summary   Constructs the keyboard object

        Syntax    zKeyboard();

        Remarks   This constructor takes care of initializing the keyboard
                  object and creating the internal queues. The queue size
                  is 16 characters for local (and another 16 for remote)
                  keys. It also installs (if necessary) the SDK local key
                  handler. You can create as many zKeyboard objects as you
                  want without penalty in performance. The internal instance
                  count determines whether there is a need to install the
                  handlers and detect if a multitasker is running.


    ZKEYBOARD::~ZKEYBOARD
    -------------------------------------------------------------------------

        Summary   Destryos the keyboard object

        Syntax    ~zKeyboard();

        Remarks   This destorys the keyboard object. If there are no other
                  keyboard objects currently running, this also removes the
                  SDK local key handler and destroyes the keyboard queues.


    ZKEYBOARD::PUT
    -------------------------------------------------------------------------

        Summary   Puts a key in the buffer

        Syntax    Boolean put(ushort aCode, Boolean isLocal);

        Remarks   This method attempts to stuff a key in the keyboard object.
                  This 'aCode' parameter should be a normal character or
                  a scan code (use the kb??? constants in KBCODES.H). The
                  'isLocal' parameter determines which queue must be used for
                  this key.

        Return    True if successful, False if the requested queue is full.

        Example   keyboard.put(kbLeft, False);


    ZKEYBOARD::PEEK
    -------------------------------------------------------------------------

        Summary   Return the pending key without removing it from the queue

        Syntax	  ushort peek();

        Remarks   This method returns the curerntly pending key without
                  actually removing it from the queue. You should use the
                  kb??? constants or ASCII codes to interpret the result.

        Return    The pending key or kbNone if none


    ZKEYBOARD::GET
    -------------------------------------------------------------------------

        Summary	  Wait and retrieve a key code

        Syntax    ushort get();

        Remarks   This function will return the current keycode (or wait
                  until one is available). While waiting, this function will
                  release time slices to the currently running multitasker
                  (if any). The supported multitaskers are DESQView, Windows
                  3.1x, Windows95/NT, OS/2, TopView, and others. You can
                  examine the source of the code with the isLocal method.

        Return    The keycode when one becomes available


    ZKEYBOARD::FLUSH
    -------------------------------------------------------------------------

        Summary   Empties the keyboard queues

        Syntax    void flush();

        Remarks   This method empties the keyboard queues (both local and
                  remote in SDK mode).

        Return    Nothing


    ZKEYBOARD::ISLOCAL
    -------------------------------------------------------------------------

        Summary   Return the source of the last key retrieved

        Syntax    Boolean isLocal() const;

        Remarks   This method returns the source of the last key retrieved
                  with the get() member function. Note that you must first
                  retrieve the keycode and then call this routine. Note that
                  in non-SDK mode, this returns True (unless you stuff a
                  fake remote keystroke with the put() method).

        Return    True, if the last keystroke was locally entered
                  False, if the last keystroke came from the remote end


    ZKEYBOARD::ISEMPTY
    -------------------------------------------------------------------------

        Summary   Returns the status of the keyboard queues

        Syntax    Boolean isEmpty();

        Remarks   If there are no keystrokes pending in the any of the two
                  queues, this function returns True.

        Return    True, if both queues are empty, False otherwise


    ZKEYBOARD::PARANOID
    -------------------------------------------------------------------------

        Summary   Controls the local handler (SDK only)

        Syntax    static Boolean paranoid;

        Remarks   This publicly accessible variable (default is False)
                  controls which keys will be captured by the local keyboard
                  handler in SDK mode. When 'paranoid' is False, only the
                  direction keys, Home, End, Insert, and Del are captured
                  by the handler. When 'paranoid' is True, the handler will
                  also capture AltF1-10, Alt-K,P,B, and some others as well.
                  You can set this variable at any time and the handler will
                  revert to the new mode immediately.

