Usage

Sections: Get keyboard Object | Open keyboard | Switch keyset | Add Content | Simulate Typing | Enable/Disable | window.prompt

Get the keyboard object

The following methods are equivalent:

var keyboard = $('#keyboard').getkeyboard();
var keyboard = $('#keyboard').data('keyboard');

The examples below use the following button HTML

<button class="open">Open Keyboard</button>

Open the keyboard

Open the keyboard by clicking on a button:

$('button.open').click(function(){
  $('#keyboard').getkeyboard().reveal();
});

Switch keyset

Pass a string to the showKeySet function.

• Use normal for the default keyset.
• Use shift to show the shift keyset.
• Use alt to show the alt keyset.
• Use meta{name} to show the meta keyset.
  • In version 1.26.8, {name} includes any of the following characters: A-Za-z0-9_-, e.g. metakeys, meta_greek, meta1 or meta-astrology.
  • In older versions, the {name} placeholder must be followed by at least one number, then A-Za-z0-9_, e.g. meta1, meta1test or meta0_symbols.

Combine any of the above keyset names with a + symbol separating each one. For example,

• shift+meta_symbols
• meta-1+shift+alt
• The order in which the keysets are listed does not matter.

$('button.show-altgr').click(function(){
  var keyboard = $('#keyboard').data('keyboard');
  keyboard.showKeySet('alt+shift');
});

If the keyset does not exist, any of the matching keyset names will be used, or it will fallback to the normal keyset.

For example:

• Using shift+meta1, but meta1 does not exist, then the normal+shift keyset will be shown.
• Using shift+alt+meta_keys but the meta_keys only has a shift keyset defined, then the meta_keys+shift keyset will be shown.
• Using random text, will default to the normal keyset.

See the Methods page for more examples.

Open keyboard, then immediately add content

$('button.open').click(function(){
  var keyboard = $('#keyboard').getkeyboard();
  keyboard
    .reveal()
    .insertText('Hello, my name is Inigo Montoya. You killed my father, prepare to die!');
});

Please note that the insertText function does not trigger a change event on the input. If you require this event, you will need to trigger it manually.

$('button.open').click(function(){
  var keyboard = $('#keyboard').getkeyboard();
  keyboard
    .reveal()
    .insertText('Anybody want a peanut?')
    // added in v1.26.8; insertText returns the keyboard object
    // this will trigger the change event on the original input
    .$el.trigger('change');
});

As of v1.26.8, the insertText() function will return the keyboard object to allow further chaining. See issue #506.

Open keyboard, then simulate typing in content

This needs the typing extension loaded and initialized - see the Setup page for more details.

$('button.open').click(function(){
  var keyboard = $('#keyboard').getkeyboard();
  keyboard
    .reveal()
    .typeIn('As you wish!', 500, function(kb) {
      // do something after text is added (kb = keyboard)
      // kb.accept(); // close keyboard and accept changes
    });
});

Dynamically enable or disable the keyboard keys & input

Add a {toggle} button to your keyboard, or if your keyboard is always open, you can add an external button to toggle the keyboard state:

$('button.toggle').click(function(){
  var keyboard = $('#keyboard').getkeyboard();
  // if keyboard.enable = false, all keys & preview will be disabled
  keyboard.enable = !keyboard.enable;
  keyboard.toggle();
});

Emulating window.prompt

If we want the on-screen keyboard to emulate the built-in window.prompt function:

result = window.prompt(message, defaultValue);

and so allow the app logic of accepted values to move out of "accepted" functions and events and into their natural UI handlers, we could write

function keyboardPrompt(message, defaultValue) {
  var box = $('#keyboard');
  box.show().val(defaultValue).attr('placeholder', message).getkeyboard().reveal();
  return new Promise(accept => box.on('accepted cancelled', e => accept(e.type == 'accepted' ? box.val() : null)));
}

Example usage:

async function enterName() {
  var name = await keyboardPrompt('What is your name?', 'Anonymous');
  if (name != null) console.log('Your name is ' + name);
}

enterName();