The Google Virtual Keyboard API has been officially deprecated as of May 26, 2011. It will continue to work as per our deprecation policy.

Getting Started

  1. Introduction
    1. Scope
    2. Browser compatibility
    3. Audience
    4. The "Hello World" of Virtual Keyboard
  2. Getting started
    1. Loading the JavaScript API
  3. Using the API
    1. Creating a new keyboard instance
    2. Getting the active keyboard layout
    3. Returning the language of the active keyboard layout
    4. Setting the keyboard layout
    5. Showing or hiding the keyboard
    6. Detecting if the keyboard is visible
    7. Calling the onLoad handler
  4. Layout code enum
  5. Troubleshooting

With the Virtual Keyboard API, you can enable an onscreen keyboard on any text field or text area on your webpage. This keyboard allows users to type in any language using the keyboard layouts familiar to that language.

What is a virtual keyboard? A virtual keyboard is an on-screen interface used to transition from one keyboard layout to another. Some ways to use this API include:

  • Allowing users to type their own languages on foreign keyboards, such as when they are traveling abroad, living in a country where their language is not official, and so forth.
  • Providing a more accessible on-screen keyboard allowing disabled users to type with mouse clicks.
  • Allowing multi-lingual users to rapidly switch between different character sets and/or alphabets.

Introduction

This developer's guide provides a basic model for using the Google Virtual Keyboard API, along with granular explanations of the API's configurable JavaScript components. You can use this guide to enable Virtual Keyboard on your webpage or application.

Scope

This document describes how to use the functions and properties specific to the Virtual Keyboard API.

Browser compatibility

The Virtual Keyboard API supports Firefox 1.5+, IE6+, Safari, Opera 9+, and Chrome.

Audience

This documentation is intended for developers who wish to add Google Virtual Keyboard functionality to their pages or applications.

The "Hello World" of Virtual Keyboard

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <script type="text/javascript" src="https://www.google.com/jsapi=INSERT-YOUR-KEY"></script>
    <script type="text/javascript">

      // Load the Google Onscreen Keyboard API
      google.load("elements", "1", {
          packages: "keyboard"
      });

      function onLoad() {
        var kbd = new google.elements.keyboard.Keyboard(
          [google.elements.keyboard.LayoutCode.RUSSIAN],
          ['t1']);
      }

      google.setOnLoadCallback(onLoad);
    </script>
  </head>
  <body>
  Type in Russian<br/>
  <textarea id="t1" style="width: 600px; height: 200px;"></textarea>
  </body>
</html>
    

Visit the code playground to play with this sample.

Getting Started

Loading the JavaScript API

To begin using the Virtual Keyboard API, include the following script in the header of your web page.

<script type="text/javascript" src="https://www.google.com/jsapi"></script>

Next, load the Virtual Keyboard API with google.load(module, version, package), where:

  • module calls the specific API module you wish to use on your page (in this case, elements).
  • version is the version number of the module you wish to load (in this case, 1).
  • package specifies the specific elements package you wish to load, in this case Virtual Keyboard.
<script type="text/javascript">
  google.load("elements", "1", {
  packages: "keyboard"
  });
</script>

You can find out more about google.load in the Google Loader developer's guide.

When we do a significant update to the API, we will increase the version number and post a notice on the API discussion group. Take note of any required code changes when this occurs, and update your URLs to the new version when they are compliant.

The Google API team will also periodically update the API with recent bug fixes and performance enhancements without requiring a version update. For the most part, these fixes should remain transparent to you, but we may inadvertently break some API clients. Please use the API discussion group to report such issues.

Using the API

The following sections demonstrate how to incorporate the Google Virtual Keyboard API into your web page or application. Using this API requires an asynchronous call to a server, so you need a callback to exchange the data.

Create a new keyboard instance

Unless otherwise noted, all of the methods described below inherit from the google.elements.keyboard.Keyboard base class.

Keyboard(layouts, textfieldIds) creates a new Virtual Keyboard instance, where:

  • layouts is an array of keyboard layouts to preload, specified in the form of the LayoutCode enum (for example, google.elements.keyboard.LayoutCode.RUSSIAN). The first layout is the default. See the LayoutCode enum for a complete list of supported scripts.

    Note: The API throws an exception if you supply an invalid value for the layouts array.

  • textfieldIds is an optional array containing strings of text field IDs or element references allowing you to attach the keyboard to the UI. If you don't supply the optional array, the same keyboard instance applies to any input box or text area on your page.

The following sample shows you how to create a new keyboard instance targeted to textarea id="t1" in the body:

var kbd = new google.elements.keyboard.Keyboard(
[google.elements.keyboard.LayoutCode.RUSSIAN],['t1']);
...
<textarea id="t1" style="width: 600px; height: 200px;"></textarea>

Get the active keyboard layout

getLayout() has no arguments and returns the active layout for the keyboard object in the form of google.elements.keyboard.LayoutCode.

Return the language of the active keyboard layout

getLayoutName(layout) returns a string containing the name of the active layout in its native language, where layout is a layout code in the form of google.elements.keyboard.LayoutCode.

Set the keyboard layout

setLayout(layout) changes the keyboard layout for this keyboard instance, where layout is a layout code in the form of google.elements.keyboard.LayoutCode.

setLayout() has no return value.

The following code snippet demonstrates how to use getLayoutName() and setLayout().

function drawMenu() {
  html = ["<ul>"];
  for (var i in google.elements.keyboard.LayoutCode) {
  var code = google.elements.keyboard.LayoutCode[i];
  var name = google.elements.keyboard.getLayoutName(code);
  html.push("<li><a href='#' onclick='kbd.setLayout(\"", code, "\")'>", name, "</a></li>");
  }
html.push("</ul>");
document.getElementById("menu").innerHTML = html.join('');
}

Show or hide the keyboard

setVisible(visible) sets the visibility state for this keyboard instance, where visible is a boolean indicating whether the keyboard is visible.

setVisible() has no return value.

Detect if the keyboard is visible

isVisible() has no arguments and returns a boolean indicating whether the onscreen keyboard is visible for this keyboard instance.

The following sample demonstrates how to use setVisible in conjunction with isVisible to show or hide the keyboard. You can also play with it in the code playground.

function toggleVisible() {
  var button = document.getElementById('btVisible');
  if (kbd.isVisible()) {
    kbd.setVisible(false);
    document.getElementById('btVisible').value = 'Show';
  } else {
    kbd.setVisible(true);
    document.getElementById('btVisible').value = 'Hide';
  }

Calling the onLoad handler

.setOnLoadCallback(callback) is a static function that registers the specified handler function to be called once the page containing this call loads, where callback is a required function called when the containing document is loaded and the API is ready for use (e.g., after onLoad). This function is implemented on the google namespace (i.e., google.setOnLoadCallback(callback);)

.setOnLoadCallback() has no return value.

Note: Previous documentation recommended that you use the body element's onload attribute (<body onload="OnLoad()">). While this is a fine way to go when you are in complete control of the page and all code loaded by the page, this approach can cause problems with some runtimes that destroy your body.onload handler. setOnLoadCallback() does not have these problems, and therefore is the recommended method of registering a callback that calls your code when the API is fully loaded and ready for use.

setOnLoadCallback is implemented on the google namespace:

google.setOnLoadCallback(function);

LayoutCode enum

The google.elements.keyboard.LayoutCode enumeration maps name constants to layout codes. Note that layout code is not the same as language code, because it is possible to have multiple layouts, or input methods, for a single language.

var google.elements.keyboard.LayoutCode = {
  'ALBANIAN': 'sq',
  'ARABIC': 'ar',
  'ARMENIAN_EASTERN': 'hy_east',
  'ARMENIAN_WESTERN': 'hy_west',
  'BASQUE': 'eu',
  'BELARUSIAN': 'be',
  'BENGALI_PHONETIC': 'bn_phone',
  'BOSNIAN': 'bs',
  'BRAZILIAN_PORTUGUESE': 'pt_br',
  'BULGARIAN': 'bg',
  'CATALAN': 'ca',
  'CHEROKEE': 'chr',
  'CROATIAN': 'hr',
  'CZECH': 'cs',
  'CZECH_QWERTZ': 'cs_qwertz',
  'DANISH': 'da',
  'DARI': 'prs',
  'DUTCH': 'nl',
  'DEVANAGARI_PHONETIC': 'deva_phone',
  'ENGLISH': 'en',
  'ESTONIAN': 'et',
  'ETHIOPIC': 'ethi',
  'FINNISH': 'fi',
  'FRENCH': 'fr',
  'GALICIAN': 'gl',
  'GEORGIAN_QWERTY': 'ka_qwerty',
  'GEORGIAN_TYPEWRITER': 'ka_typewriter',
  'GERMAN': 'de',
  'GREEK': 'el',
  'GUJARATI_PHONETIC': 'gu_phone',
  'GURMUKHI_PHONETIC': 'guru_phone',
  'HEBREW': 'he',
  'HINDI': 'hi',
  'HUNGARIAN_101': 'hu_101',
  'ICELANDIC': 'is',
  'ITALIAN': 'it',
  'KANNADA_PHONETIC': 'kn_phone',
  'KAZAKH': 'kk',
  'KHMER': 'km',
  'KOREAN': 'ko',
  'KYRGYZ': 'ky_cyrl',
  'LAO': 'lo',
  'LATVIAN': 'lv',
  'LITHUANIAN': 'lt',
  'MACEDONIAN': 'mk',
  'MALAYALAM_PHONETIC': 'ml_phone',
  'MALTESE': 'mt',
  'MONGOLIAN_CYRILLIC': 'mn_cyrl',
  'MONTENEGRIN': 'srp',
  'NORWEGIAN': 'no',
  'ORIYA_PHONETIC': 'or_phone',
  'PAN_AFRICA_LATIN': 'latn_002',
  'PASHTO': 'ps',
  'PERSIAN': 'fa',
  'POLISH': 'pl',
  'PORTUGUESE': 'pt_pt',
  'ROMANI': 'rom',
  'ROMANIAN': 'ro',
  'RUSSIAN': 'ru',
  'SANSKRIT_PHONETIC': 'sa_phone',
  'SERBIAN_CYRILLIC': 'sr_cyrl',
  'SERBIAN_LATIN': 'sr_latn',
  'SINHALA': 'si',
  'SLOVAK': 'sk',
  'SLOVAK_QWERTY': 'sk_qwerty',
  'SLOVENIAN': 'sl',
  'SOUTHERN_UZBEK': 'uzs',
  'SPANISH': 'es_es',
  'SWEDISH': 'sv',
  'TAMIL_PHONETIC': 'ta_phone',
  'TATAR': 'tt',
  'TELUGU_PHONETIC': 'te_phone',
  'THAI': 'th',
  'TURKISH_F': 'tr_f',
  'TURKISH_Q': 'tr_q',
  'UIGHUR': 'ug',
  'UKRAINIAN_101': 'uk_101',
  'URDU': 'ur',
  'UZBEK_LATIN': 'uz_latn',
  'UZBEK_CYRILLIC_PHONETIC': 'uz_cyrl_phone',
  'UZBEK_CYRILLIC_TYPEWRITTER': 'uz_cyrl_type',
  'VIETNAMESE_TCVN': 'vi_tcvn',
  'VIETNAMESE_TELEX': 'vi_telex',
  'VIETNAMESE_VIQR': 'vi_viqr'
};

Troubleshooting

If you encounter problems:

  • Look for typos. Remember that JavaScript is a case-sensitive language.
  • Use a JavaScript debugger. Google Chrome has a full set of developer tools. In Firefox, you can use the JavaScript console or the Firebug. In IE, you can use the Microsoft Script Debugger.
  • Search the discussion group. If you can't find a post that answers your question, post your question to the group along with a link to a web page that demonstrates the problem.