docs/input.md
# @title Vedeu Input
# Vedeu Input
A configured and running client application using Vedeu will spend the
majority of its time waiting for input from the terminal by the user.
Input in to Vedeu is essentially characters derived from a keypress or
keypresses, and throughout this document, 'characters' and
'keypresses' may be used interchangably to mean 'input'.
* It should be noted that data can be also be 'piped' into a Vedeu
application as input, though at this time, this is not the mode du
jour.
The input received by Vedeu is handled in one of three ways, depending
on which mode Vedeu has been configured to use;
'{file:docs/input.md#label-Raw+Mode raw}' (default),
'{file:docs/input.md#label-Cooked+Mode cooked}' or
'{file:docs/input.md#label-Fake+Mode fake}'. See below for details of
each.
* Vedeu uses Ruby's 'IO/Console' from the standard library to
facilitate this. For more information relating to this area, consult
the Ruby documentation, or the 'stty(1)' or 'termios(3)' manpages.
## Raw Mode
This is the default mode for Vedeu. Keypresses or characters are not
processed by the underlying terminal, but instead sent directly to
Vedeu to be handled.
Vedeu.configure do
terminal_mode :raw
# or...
raw!
# ...more configuration here
end
This mode is generally used to perform an operation dependent on the
key which was pressed. The configuration of mapping keypresses to
actions is handled on a per-interface basis; each interface having its
own keymap which can perform specific actions.
There is also global keymap available to handle certain keypresses
application-wide, ie. irrespective of the interface or view which is
currently in focus. The global keymap would specify the keypress
needed to exit the application, for example.
See {file:docs/keymaps.md Keymaps} for more information.
## Cooked Mode
Here, the input from the user is stored in an internal buffer by the
terminal itself until a line-feed or carriage-return character is
encountered. The terminal then sends this stream of characters to
Vedeu to be processed.
Vedeu.configure do
terminal_mode :cooked
# or...
cooked!
# ...more configuration here
end
## Fake Mode
Whilst technically the terminal will be in raw mode, with the 'fake'
mode, Vedeu attempts to simulate cooked mode but with some additional
functionality. To do this, Vedeu creates an internal buffer for
characters resulting from keypresses to be either stored or processed
immediately.
Vedeu.configure do
terminal_mode :fake
# or...
fake!
# ...more configuration here
end
## Mode Switching
During the lifecycle of a Vedeu client application it may be necessary
to switch between the different modes offered. This is handled by
triggering the `:_mode_switch_` event. By default, this cycles
through the available modes. When an optional but valid target mode is
given, that mode will be activated instead.
Vedeu.trigger(:_mode_switch_, mode) # Valid values for mode are
# :raw, :cooked or :fake
## Accessing Input
Accessing the input can be achieved in the following ways:
- Via a keymap: Vedeu will interpret the input and trigger events or
call methods based on the input received.
- Via API calls: You can access that which is entered into the client
application with the following methods:
Vedeu.all_commands # => Returns an array of all the commands
# entered.
Vedeu.last_command # => Returns the last command entered.
Vedeu.all_keypresses # => Returns all the individual
# keypresses entered as an array.
Vedeu.last_keypress # => Returns the last keypress entered.
- Via events: You can access that which is entered by binding to
events which Vedeu will trigger as input is received:
Vedeu.bind(:key) do
# ... do something with the key
end
Vedeu.bind(:command) do
# ... do something with the command
end
## Providing Input
Input can be provided in a couple of ways, automatic and manually.
### Automatically
Dependent on the terminal mode as mentioned previously.
- In `:raw` mode, a keypress (a single character e.g. `b`, or
modifier+character e.g. Shift+F12), can be bound via the keymaps
functionality.
- In `:cooked` mode, a group of keypresses, terminated with the
`return` key will trigger the `:command` event which you can bind to
and perform actions dependent on the input provided.
- In `:fake` mode, Vedeu emulates the terminal allowing you all the
benefits of `:cooked` mode but with Vedeu's in-built editor. The
input can be accessed using the API calls as mentioned in
{file:docs/input.md#accessing_input}.
### Manually (semi-automatic)
See {file:docs/api.md#vedeuread}