Meta Developers

This page describes how you can incorporate your custom integrations with Virtual Keyboard. It also lists some best practices to follow when using Virtual Keyboard.

Reposition the Keyboard

You can reposition the keyboard by updating the transform of the OVRVirtualKeyboard MonoBehaviour’s GameObject. Note that the keyboard scale must be uniform across the three axes.

You can also move the keyboard to a reference position using the OVRVirtualKeyboard’sUseSuggestedLocation(OVRVirtualKeyboard.KeyboardPosition keyboardPosition) method.

Handle Input from the Keyboard

Set Virtual Keyboard’s TextCommitField property with a Unity Input Field to automatically handle the keyboard events.

The OVRVirtualKeyboard MonoBehaviour also exposes events to bind for other implementations, such as Text Mesh Pro.

class OVRVirtualKeyboard : Monobehaviour {
…
	Action<string> CommitText;
	Action Backspace;
	Action Enter;
	Action KeyboardShown;
	Action KeyboardHidden;
…
}

CommitText, Backspace, and Enter are each triggered on their appropriate key event. CommitText’s string result can be a single character or a full word depending on the keyboard interaction.

KeyboardShown confirms the keyboard is ready to receive input. KeyboardHidden is triggered when the keyboard hide key is pressed, or the keyboard is otherwise hidden.

Provide Text Context

If you are using Virtual Keyboard’s TextCommitField property with a Unity Input Field, the text context is handled automatically. If you need a more custom implementation, you should provide text context so the keyboard can properly return text suggestions and handle corrections with swipe input.

OVRVirtualKeyboard.ChangeTextContext accepts a string of text content. Set it when changing input fields or if the input text has changed via another script.

Use TextMeshPro Inputs

To use TextMeshPro inputs with Virtual Keyboard, here’s an example script showing how it could be integrated.

using TMPro;
using UnityEngine;

public class TextMeshProVirtualKeyboardInputSource : MonoBehaviour
{
    [SerializeField]
    private OVRVirtualKeyboard virtualKeyboard;

    [SerializeField]
    private TMP_InputField inputField;

    void Start()
    {
        inputField.onSelect.AddListener(OnInputFieldSelect);
        inputField.onValueChanged.AddListener(OnInputFieldValueChange);
        virtualKeyboard.CommitText += OnCommitText;
        virtualKeyboard.Backspace += OnBackspace;
        virtualKeyboard.KeyboardHidden += OnKeyboardHidden;
    }

    private void OnInputFieldValueChange(string arg0)
    {
        virtualKeyboard.ChangeTextContext(arg0);
    }

    private void OnInputFieldSelect(string arg0)
    {
        virtualKeyboard.ChangeTextContext(arg0);
        virtualKeyboard.gameObject.SetActive(true);
    }

    private void OnKeyboardHidden()
    {
        if (!inputField.isFocused)
        {
            return;
        }
        // if the user hides the keyboard
        inputField.DeactivateInputField();
    }

    private void OnCommitText(string arg0)
    {
        if (!inputField.isFocused)
        {
            return;
        }
        inputField.onValueChanged.RemoveListener(OnInputFieldValueChange);
        if (arg0 == "\n" && !inputField.multiLine)
        {
            inputField.OnSubmit(null);
        }
        inputField.SetTextWithoutNotify(inputField.text + arg0);
        inputField.text += arg0;
        inputField.MoveTextEnd(false);
        inputField.onValueChanged.AddListener(OnInputFieldValueChange);
    }

    private void OnBackspace()
    {
        if (!inputField.isFocused)
        {
            return;
        }
        if (inputField.text.Length > 0)
        {
            inputField.onValueChanged.RemoveListener(OnInputFieldValueChange);
            inputField.text = inputField.text.Substring(0, inputField.text.Length - 1);
            inputField.MoveTextEnd(false);
            inputField.onValueChanged.AddListener(OnInputFieldValueChange);
        }
    }
}

Send Input to the Keyboard

OVRVirtualKeyboard prefab and OVRVirtualKeyboard MonoBehaviour have built-in input handlers for controllers and hands, but it is also possible to use a script to send input to the keyboard. This can be used to customize interactions with the keyboard.

OVRVirtualKeyboard.SendVirtualKeyboardRayInput

Send a ray input to the keyboard from a given transform. The method accepts the following parameters:

Transform inputTransform
- GameObject Transform with the pose and forward orientation of the input ray.
InputSource source
- OVRVirtualKeyboad.InputSource being Controller/Hand Left/Right.
bool isPressed
- If true, will trigger a key press if the ray collides with a keyboard key.
bool useRaycastMask
- Defaults to true, will use the configured raycast mask for the given input source.

OVRVirtualKeyboard.SendVirtualKeyboardDirectInput

Send a direct input to the keyboard from a given transform. The method accepts the following parameters:

Vector3 position
- The collision point which is interacting with the keyboard. For example a hand index finger tip.
InputSource source
- OVRVirtualKeyboad.InputSource being Controller/Hand Left/Right.
bool isPressed
- If the input is triggering a press or not.
bool useRaycastMask
- Defaults to true, will use the configured raycast mask for the given input source.

Best Practices

Consider the following best practices when integrating Virtual Keyboard into your application:

While Virtual Keyboard supports both near interactions via direct touch and far interactions via raycast, we recommend the direct touch near implementation with hands, which enables faster, more intuitive typing than the raycast method.
Position the keyboard as closely as possible to the text input field to make it easy for users to switch focus between the keyboard and the text field.
When text input is needed, instantiate the keyboard at scene load to avoid expensive keyboard model loading.
Use runtime provided positions to ideally position the keyboard. See the Reposition the Keyboard section.

Did you find this page helpful?