Keyboard

As well as the touch screen, RFO-BASIC! programs can accept keyboard input. There are two types of keyboard:
 * Hard keyboard or physical keyboard is an actual hardware device wired to the Android device on which RFO-BASIC! is running. Usually, you attach a USB keyboard.
 * Some Android tablets have a full-size USB connector.
 * Most Android phones have a micro-USB connector. Provided that this connector has "On The Go (OTG)" capability (is available for attachment of devices as well as for charging), you can connect a hard keyboard here, though it will typically require a cable adaptor.
 * Soft keyboard (on-screen keyboard) is a program that appears at the bottom of the screen. The Google Keyboard ships with many phones.  Alternatives, such as the Hacker's Keyboard, can be installed instead.  The soft keyboard has a key configuration like a hard keyboard.  Most soft keyboards can be set for a variety of locales that have different key layouts.

An RFO-BASIC! program can call on Android to display a variety of dialog windows that supervise the reading of keystrokes and return a result to the program. It can also read individual keystrokes, using an interrupt routine to detect a key-press. RFO-BASIC! buffers keystrokes in case the user presses keys faster than the BASIC program acts on them.

Dialog windows
RFO-BASIC! gives the programmer access to a variety of Android dialog windows for brief user interaction. These can be displayed on top of either the text console or the graphic display. Programs usually use these dialogs only in response to a special condition or user action.

The exact appearance of these dialogs varies from one Android version to another.

This section presents the following BASIC statements that put dialogs on the screen:


 * POPUP. A pop-up window is an output-only "dialog"; there is no user input at all.
 * INPUT can display a prompt and retrieve either a string or numeric value from the user through the keyboard.

POPUP
Briefly display an on-screen message

POPUP 
 * Synopsis

The POPUP statement puts a text message on top of the normal display. These messages are either "short" (typically 2 seconds) or "long" (typically 4 seconds). Pop-ups are convenient ways to get information to the user without affecting the normal display or having to work to restore it afterward.

The message_sexp parameter is a string expression producing the text to be displayed. This parameter is required.

Normally, the message is in the center of the screen. The optional x_nexp and y_nexp parameters let the program specify the horizontal and vertical positions, respectively, of the message. These parameters specify a displacement from the center of the screen. Positive values for x_nexp are displacements rightward; positive values for y_nexp are displacements downward. Negative values are displacements in the reverse direction. Directions are based on the orientation (portrait or landscape) the device is currently using.

The optional duration_lexp parameter specifies the duration of the message. If it is 0 or omitted, the message is short. If it is nonzero, the message is long. The POPUP statement does not suspend the program for this duration. However, if the program ends or malfunctions during this duration, the message might not be removed from the screen at the right time; the pop-up window will go away the next time some action clears the screen.

INPUT
Solicit a single-line response from the user

INPUT {}, {, {}{, }}
 * Synopsis

The INPUT statement displays a dialog window with a single-line input area and an OK button. The user may type into the input area using the keyboard, may confirm the input by tapping the OK button, and may cancel the input by tapping anywhere outside the dialog window or by tapping the BACK button.

The prompt_sexp becomes the dialog box title. Usually, a prompt tells the user what specific information is desired. If the prompt expression is empty ("") or omitted, the dialog box is drawn without a title area.

The INPUT statement captures a single string or numeric value. If the program provides a default_exp value, it appears in the input area at the start of the dialog window and the user can edit or delete it. Otherwise, the input area is blank and the user must type the desired response completely. In the case that the user confirms the input by tapping the OK button, the value entered is assigned to result_var. The parameters default_exp and result_var may be the same variable, in which case, when the user confirms the input, the value of the variable is updated. If a default is provided, the variable must be the same type (string or numeric) as result_var. If result_var is numeric, the input must be numeric, so the only key taps accepted are 0-9, "+", "-" and ".".

The statement sets the optional canceled_lvar to 0.0 (false) if the user confirms the input by tapping the OK button, or 1.0 (true) if the user cancels the input by any means.

If the user cancels the input and the INPUT statement did not provide a canceled_lvar to sense the cancellation, it is an error. The program can trap the error with an OnError: trap, in which case GETERROR$ contains. Otherwise, that legend appears on the screen and the program stops.

The following code produced the example illustrated in this section: GR.OPEN 255,64,255,128  % Dark green background fname$ = "myfile.bas" INPUT "Rename the file then press OK",fname$,fname$,canc
 * Example

Reading individual keystrokes
On devices with Android versions 9 (Pie) and later, a soft keyboard cannot be shown using KB.SHOW. (On newer Android versions, only editable ListViews can get a virtual keyboard, but the text console is non-editable.)  A more primitive way to use the keyboard is to read individual keystrokes. In this case, any editing (such as enabling the backspace key to undo keystrokes) must be done by the keyboard itself. The program uses KB.SHOW to enable the keyboard, in case the user has only a soft keyboard. Then the program uses an OnKeyPress interrupt handler to read individual keystrokes with INKEY$.

INKEY$
Read an individual keystroke

INKEY$ 
 * Synopsis

The INKEY$ statement returns in the specified string variable, a description of the key the user most recently pressed. It does not wait for a new key-press. If you use INKEY$ in a loop, it typically returns multiple reports of the same key-press. Typically, you use INKEY$ only in an OnKeyPress: interrupt routine, which receives control only when a new key-press occurs.
 * Description

The $ on the end of the INKEY$ statement is unusual for RFO-BASIC! but is required.

The resulting value of the string variable is as follows:
 * Reports
 * If the user has not pressed a key since the BASIC program began running: "@"
 * If the user pressed an alphanumeric key or the space bar, the variable contains a one-character string that is the key that was pressed. For other keys, the variable contains the string "key " followed by the Android key code, in decimal.
 * If the SHIFT or CAPS LOCK key is down, then there are two key-presses: the alphabetic key, then "key 59".
 * If the CTRL key is down, then there are two key-presses: the alphabetic key, then "key 113".
 * Symbols, such as shifted numerals, are reported likewise. For example, the @ is "key 77".
 * The D-Pad keys are reported as "up", "down", "left", "right", and "go".
 * ENTER is "key 66".
 * The volume-up and volume-down buttons on the side of the device are reported as "key 24" and "key 25", respectively. However, normally they perform their usual functions even when a BASIC program detects the key-press.

Reading keystrokes is done easily by using a list as a queue. The program creates a string list to hold the keystrokes: LIST.CREATE S Keystrokes
 * Example

It includes a key-press interrupt handler, called when a new keystroke is available. It appends the new keystroke to the queue and returns: OnKeyPress: INKEY$ mkey$ LIST.ADD Keystrokes,mkey$ KEY.RESUME

The main code, at its leisure, tests to see if any keystrokes are waiting in the list. If so, it removes the one at the head of the queue:

LIST.SIZE Keystrokes,n IF n > 0 THEN LIST.GET Keystrokes,1,k$ LIST.REMOVE Keystrokes,1 ! Process the new key, in k$ ENDIF

Controlling the soft keyboard
When you are editing an RFO-BASIC! program, the edit window calls the soft keyboard unless a hard keyboard is attached.

When an RFO-BASIC! program starts to run, the soft keyboard is not displayed until the program calls for it. The OnKbChange: interrupt handler lets the program sense a change to the displayed status of the soft keyboard.

KB.SHOW
Show the soft keyboard

KB.SHOW
 * Synopsis

The KB.SHOW statement makes RFO-BASIC! display the soft keyboard. However, the soft keyboard never appears in the following cases:
 * Description
 * A hard keyboard is attached
 * The program has not yet written to the text console with a statement such as PRINT.

If the graphic screen was on display, KB.SHOW switches the screen to the text console.

If the soft keyboard was not on display but KB.SHOW puts it on display, this is a transition that triggers any OnKbChange interrupt routine.

KB.HIDE
Hide the soft keyboard

KB.HIDE
 * Synopsis

The KB.HIDE statement hides the soft keyboard. If it had been displayed, this is a transition that triggers any OnKbChange interrupt routine.
 * Description


 * Automatic transitions
 * The soft keyboard is hidden when a BASIC program starts running, regardless of whether it was showing in the program edit window.
 * The soft keyboard is hidden when you use GR.OPEN to switch to Graphics Mode.
 * The soft keyboard does not show when you execute GR.CLOSE to leave Graphics Mode and return to the text console (until the program calls for it with KB.SHOW).

These automatic transitions do not trigger an OnKbChange interrupt routine.

KB.TOGGLE
Toggle the visibility of the soft keyboard

KB.TOGGLE
 * Synopsis

If the soft keyboard is hidden, KB.TOGGLE shows it, exactly as if KB.SHOW had been called. If the soft keyboard is showing, KB.TOGGLE hides it, exactly as if KB.HIDE had been called. Either transition triggers any OnKbChange interrupt routine.

KB.SHOWING
Test the visibility of the soft keyboard

KB.SHOWING 
 * Synopsis

The KB.SHOWING statement writes a logical value in the specified numeric variable. It is 1.0 (true) if the BASIC program called for display of the soft keyboard with KB.SHOW, and 0.0 (false) if the soft keyboard is hidden.
 * Description

If the BASIC program put up a dialog window, such as with the INPUT statement, the soft keyboard pertains to that window, and KB.SHOWING reports the soft keyboard to be hidden.