FireMonkey TForms: Events for Virtual Keyboard  Navigation and Scroll Box Control

This is the second post of a four-post series on Delphi's FireMonkey support for mobile device virtual keyboards. For the first in the series, see Using Delphi's FireMonkey Vertical Scroll Box With a Virtual Keyboard.

There is source code that accompanies these blogs. The project group FMXVertScrollBoxEtude can be downloaded from GitHub:

https://github.com/Pasquina/FMXVertScrollBoxEtude/releases

Source code was developed using RAD Studio 10.1 Berlin (No updates.)

Objectives

• Understand the FireMonkey TForm events that are useful for virtual keyboard support, the order that they are fired, and the values of the parameters that are passed to the event handlers. Addtionally, some anomalies will be discussed that will become apparent when the handler log is examined.
• Develop a simple technique to permit input field navigation by using the Return key on the virtual keyboard. Additonally, an anomaly in the implementation of this feature will be discussed.

Note that the objective of implementing a Vertical Scroll Box to reveal otherwise hidden input fields is not implemented by this program. When you run the program on a mobile device, the input fields will be hidden by the virtual keyboard. Implementing the Vertical Scroll Box is deferred to the next blog post.

The VKLogger.exe Program

While the program will run as a Windows application, it is most effective when run on a mobile device. The illustrations that follow are from a Samsung Galaxy Tab 3 running Android 4.4.2. 

The GUI

VKLogger.exe GUI

Always Show Checkbox: This is useful when running the program on a windows PC or any device that has a hardware keyboard. Devices with hardware keyboards do not normally show the virtual keyboard. Checking this box modifies that behavior so that the virtual keyboard is shown even in cases where a hardware keyboard is present.

Input Field Array: The eight input fields are arranged in two columns using a TGridPanelLayout. Each of the input fields specifies a different type of virtual keyboard required for input. The TextPrompt property is used to indicate the type of keyboard specified for the field. Additionally, each input field specifies a ReturnKeyType of Next with the exception of the last field (URL) that specifies a ReturnKeyType of Done.

Some Button: is an arbitrary control that is outside of the TGridPanelLayout that contains the input fields. It does nothing.

Navigation

The desired behavior is as follows: The user selects the first input field (Default) and complete data entry. The Next key on the virtual keyboard causes the cursor to navigate to the next input field, which selects the desired virtual keyboard type. The process is repeated for all input fields except the last, that displays Done rather than Next. Selecting Done results in navigation to the Some Button button.

Within the TGridPanelLayout this is accomplished by setting an appropriate tab order. In the IDE, right click on the TGridPanelLayout and choose Tab Order... This displays the Tab Order editor.

Tab Order Editor for TGridPanelLayout

The individual controls within the TGridPanelLayout will be navigated in the order specified from top to bottom. You can make any changes you deem necessary by moving controls up and down in the list.

Similarly, right click on the TForm component and choose Tab Order... The tab order editor will present a similar screen but this time itemizing the controls that are children of the TForm component.

Tab Order Editor for TForm

Note that the TButton control follows the TGridPanelLayout control. Navigation from the last control in the TGridPanelLayout will be to the TButton control, the next control after the TGridPanelLayout.

Navigation using Tab Order is accomplished by the keyboard tab key. However, the virtual keyboard does not have a tab key. Instead, the Return Key is employed by intercepting the Return and changing it to a Tab. This is accomplished in the Form Key Down event handler using the following code:

Statement 10 is required to cause the modified key code to be reprocessed by the TForm to effect navigation.

Setting the tab order and implementing the FormKeyDown event handler as illustrated is all that is needed to effect a simple and straightforward navigation scheme.

It should be noted that despite indicating the ReturnKeyType on each input field, this value is not reliably observed by FireMonkey. Frequently, Done is not displayed at all and sometimes the ordinary return key symbol is displayed rather than the designated type. This is a cosmetic failing, however. The key is always a return key as you can see by the FormKeyDown processing; the only difference is the label on the return key.

Event Tracing

VKLogger traces three events:

• FormFocusChanged
• FormVirtualKeyboardHidden
• FormVirtualKeyboardShown

Each time one of these event handlers is entered, a line is added to the memo box at the top of the form. Parameters passed to the handler are displayed on the same line. The following is a typical display after all eight input fields have been navigated by using the Next key (Return.) The display is from  a Samsung Tab Galaxy Tab 3) (Model SM-T310) running Android 4.4.2.

VKLogger Trace Sample 1

Notice several things:

• The first Focused event (FormFocusChanged) is followed by two identical Shown (FormVirtualKeyboardShown) events. This is not unusual and is not reliably reproduced. All that can be said is that it sometimes happens. Further, the duplication is not always precisely the same; occasionally the second or subsequent occurrence has one or more parameters that differ from its predecessor. Usually, the difference is in the height parameter (H). 
• The Shown event following the Focused event for Edit five is simply wrong. No virtual keyboard has a height of 5; it's much to small. This anomaly is not reliably reproduced but seems to occur when the KeyboardType is specified as NumberPad. The NumberPad virtual keyboard is different (on this device and Android version) in that it has a grab handle enabling the user to move it about the form. Other virtual keyboards remain fixed at the bottom of the screen.
• The final Focused moves from the last input field to the Some Button. Some Button does not require a virtual keyboad and so the FormVirtualKeyboardHidden event is fired resulting in the last entry in the memo box. However, aside from the Visible parameter (V) correctly having a value of False, the rest of the parameters are incorrect. A hidden virtual keyboard has no height or width nor does it have a meaningful position.
• When switching virtual keyboards, the Hidden event does not fire. In other words, the old virtual keyboard is not hidden followed by showing the new virtual keyboard. The switch is indicated by a single Shown event that implies that a prior virtual keyboard has been dismissed.

Here is a similar execution of VKLogger on a different Samsung Galaxy Tab 3 Model SM-T217S) also running Android 4.4.2.

VKLogger Trace Sample 2

Despite being the same environment (so far as I can tell) there are some differences between this and the first sample:

• The Shown event following TEdit1 is not repeated.
• The Shown height following TEdit5 is not incorrectly reported as 25. Instead, the more reasonable 327 is reported.
• However, the Shown height following TEdit6 is now an very unreasonable 489.

I can't explain these differences. I can only observe that they exist.

Conclusion

Navigation and event tracing of significant TForm events is fairly straightforward and largely predictable. Problem areas include the misreported parameters for some virtual keyboards, the occasional and unpredictable duplication of Shown events (that sometimes do not have identical parameters) and the cosmetic irritation of the virtual keyboard return key not displaying the specified value.

Armed with this knowledge and the knowledge gained from ScrollDemo about scroll boxes, we are now ready to build a component that will handle repositioning a viewport to reveal input fields when a virtual keyboard is shown. That is the subject of the next blog post:

See the next post in this series at FireMonkey VyDVSBHelper: A Component to Manage a Vertical Scroll Box to Reveal Input Fields Obscured by a Virtual Keyboard

Comments are welcomed. Thanks for reading this far.