Setup

Sections: Page Head | CSS | HTML | Script | Extensions ( Autocomplete, Typing, Mobile, Navigation, Scramble )

Page Head

<!-- jQuery & jQueryUI + theme -->
<link href="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/themes/ui-lightness/jquery-ui.css" rel="stylesheet">
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.6/jquery.min.js"></script>
<script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/jquery-ui.min.js"></script>

<!-- keyboard widget css & script -->
<link href="css/keyboard.css" rel="stylesheet">
<script src="js/jquery.keyboard.js"></script>

<!-- keyboard optional extensions -->
<script src="js/jquery.mousewheel.js"></script>
<script src="js/jquery.keyboard.extension-autocomplete.js"></script>
<script src="js/jquery.keyboard.extension-typing.js"></script>
<script src="js/jquery.keyboard.extension-mobile.js"></script>
<script src="js/jquery.keyboard.extension-navigation.js"></script>
<script src="js/jquery.keyboard.extension-scramble.js"></script>

CSS (from the keyboard.css file)

.ui-keyboard { padding: .3em; position: absolute; left: 0; top: 0; z-index: 16000; }
.ui-keyboard div { font-size: 1.1em; }
.ui-keyboard-button { height: 2em; width: 2em; margin: .1em; cursor: pointer; overflow: hidden; }
.ui-keyboard-button span { padding: 0; margin: 0; white-space:nowrap; }
.ui-keyboard-button-endrow { clear: left; }
.ui-keyboard-widekey { width: 4em; }
.ui-keyboard-space { width: 15em; text-indent: -999em; }
/* width is calculated in IE, since 99% = 99% full browser width =( */
.ui-keyboard-preview { text-align: left; margin: 0 0 3px 0; display: inline; width: 99%; }
.ui-keyboard-keyset { text-align: center; }
.ui-keyboard-input { text-align: left; }
.ui-keyboard-input-current { -moz-box-shadow: 1px 1px 10px #00f; -webkit-box-shadow: 1px 1px 10px #00f; box-shadow: 1px 1px 10px #00f; }
.ui-keyboard-input-placeholder { color: #888; }
/* disabled or readonly inputs, or use input[disabled='disabled'] { color: #f00; } */
.ui-keyboard-nokeyboard { color: #888; border-color: #888; }
.ui-keyboard-button.disabled { opacity: 0.5; filter: alpha(opacity=50); } /* used by the acceptValid option to make the accept button appear faded */

/* combo key styling - toggles diacritics on/off */
.ui-keyboard-button.ui-keyboard-combo.ui-state-default { border-color: #ffaf0f; }

/* jQuery Mobile specific definitions & media queries can be found in keyboard.css file, but not included here */

HTML

<!-- placeholder attribute adds a watermark to the input/textarea; if the
  browser doesn't support HTML5, the plugin will take care of it automatically -->
<textarea id="keyboard" placeholder="Enter Text..."></textarea>

Script (showing defaults)

$('#keyboard').keyboard({

  // *** choose layout ***
  layout       : 'qwerty',
  customLayout : { 'default': ['{cancel}'] },

  position     : {
    of : null, // optional - null (attach to input/textarea) or a jQuery object (attach elsewhere)
    my : 'center top',
    at : 'center top',
    at2: 'center bottom' // used when "usePreview" is false (centers keyboard at bottom of the input/textarea)
  },

  // preview added above keyboard if true, original input/textarea used if false
  usePreview   : true,

  // if true, the keyboard will always be visible
  alwaysOpen   : false,

  // give the preview initial focus when the keyboard becomes visible
  initialFocus : true,

  // if true, keyboard will remain open even if the input loses focus.
  stayOpen     : false,

  // *** change keyboard language & look ***
  display : {
    'a'      : '\u2714:Accept (Shift-Enter)', // check mark - same action as accept
    'accept' : 'Accept:Accept (Shift-Enter)',
    'alt'    : 'AltGr:Alternate Graphemes',
    'b'      : '\u2190:Backspace',    // Left arrow (same as ←)
    'bksp'   : 'Bksp:Backspace',
    'c'      : '\u2716:Cancel (Esc)', // big X, close - same action as cancel
    'cancel' : 'Cancel:Cancel (Esc)',
    'clear'  : 'C:Clear',             // clear num pad
    'combo'  : '\u00f6:Toggle Combo Keys',
    'dec'    : '.:Decimal',           // decimal point for num pad (optional), change '.' to ',' for European format
    'e'      : '\u21b5:Enter',        // down, then left arrow - enter symbol
    'enter'  : 'Enter:Enter',
    'left'   : '\u2190',              // left arrow (move caret)
    'lock'   : '\u21ea Lock:Caps Lock', // caps lock
    'next'   : 'Next',
    'prev'   : 'Prev',
    'right'  : '\u2192',              // right arrow (move caret)
    's'      : '\u21e7:Shift',        // thick hollow up arrow
    'shift'  : 'Shift:Shift',
    'sign'   : '\u00b1:Change Sign',  // +/- sign for num pad
    'space'  : ' :Space',
    't'      : '\u21e5:Tab',          // right arrow to bar (used since this virtual keyboard works with one directional tabs)
    'tab'    : '\u21e5 Tab:Tab'       // \u21b9 is the true tab symbol (left & right arrows)
  },

  // Message added to the key title while hovering, if the mousewheel plugin exists
  wheelMessage : 'Use mousewheel to see other keys',

  css : {
    input          : 'ui-widget-content ui-corner-all', // input & preview
    container      : 'ui-widget-content ui-widget ui-corner-all ui-helper-clearfix', // keyboard container
    buttonDefault  : 'ui-state-default ui-corner-all', // default state
    buttonHover    : 'ui-state-hover',  // hovered button
    buttonAction   : 'ui-state-active', // Action keys (e.g. Accept, Cancel, Tab, etc); replaces "actionClass"
    buttonDisabled : 'ui-state-disabled' // used when disabling the decimal button {dec}
  },

  // *** Useability ***
  // Auto-accept content when clicking outside the keyboard (popup will close)
  autoAccept   : false,

  // Prevents direct input in the preview window when true
  lockInput    : false,

  // Prevent keys not in the displayed keyboard from being typed in
  restrictInput: false,

  // Check input against validate function, if valid the accept button is clickable;
  // if invalid, the accept button is disabled.
  acceptValid  : true,

  // Use tab to navigate between input fields
  tabNavigation: false,

  // press enter (shift-enter in textarea) to go to the next input field
  enterNavigation : true,
  // mod key options: 'ctrlKey', 'shiftKey', 'altKey', 'metaKey' (MAC only)
  enterMod : 'altKey', // alt-enter to go to previous; shift-alt-enter to accept & go to previous

  // if true, the next button will stop on the last keyboard input/textarea; prev button stops at first
  // if false, the next button will wrap to target the first input/textarea; prev will go to the last
  stopAtEnd : true,

  // Set this to append the keyboard immediately after the input/textarea it is attached to.
  // This option works best when the input container doesn't have a set width and when the
  // "tabNavigation" option is true
  appendLocally: false,

  // If false, the shift key will remain active until the next key is (mouse) clicked on;
  // if true it will stay active until pressed again
  stickyShift  : true,

  // Prevent pasting content into the area
  preventPaste : false,

  // Set the max number of characters allowed in the input, setting it to false disables this option
  maxLength    : false,

  // Mouse repeat delay - when clicking/touching a virtual keyboard key, after this delay the key
  // will start repeating
  repeatDelay  : 500,

  // Mouse repeat rate - after the repeatDelay, this is the rate (characters per second) at which the
  // key is repeated. Added to simulate holding down a real keyboard key and having it repeat. I haven't
  // calculated the upper limit of this rate, but it is limited to how fast the javascript can process
  // the keys. And for me, in Firefox, it's around 20.
  repeatRate   : 20,

  // resets the keyboard to the default keyset when visible
  resetDefault : false,

  // Event (namespaced) on the input to reveal the keyboard. To disable it, just set it to ''.
  openOn       : 'focus',

  // When the character is added to the input
  keyBinding   : 'mousedown',

  // combos (emulate dead keys : http://en.wikipedia.org/wiki/Keyboard_layout#US-International)
  // if user inputs `a the script converts it to à, ^o becomes ô, etc.
  useCombos    : true,

  // *** Methods ***
  // Callbacks - add code inside any of these callback functions as desired
  initialized : function(e, keyboard, el) {},
  visible     : function(e, keyboard, el) {},
  change      : function(e, keyboard, el) {},
  beforeClose : function(e, keyboard, el, accepted) {},
  accepted    : function(e, keyboard, el) {},
  canceled    : function(e, keyboard, el) {},
  hidden      : function(e, keyboard, el) {},

  switchInput : null, // called instead of base.switchInput

  // this callback is called just before the "beforeClose" to check the value
  // if the value is valid, return true and the keyboard will continue as it should
  // (close if not always open, etc)
  // if the value is not value, return false and the clear the keyboard value
  // ( like this "keyboard.$preview.val('');" ), if desired
  // The validate function is called after each input, the "isClosing" value will be false;
  // when the accept button is clicked, "isClosing" is true
  validate    : function(keyboard, value, isClosing) { return true; }

});

Extensions

Make sure you include the appropriate extension script in the head (see the page head section above)

Autocomplete - integrate with jQuery UI Autocomplete

// target a specific keyboard, or use $('.ui-keyboard-input') to target all
$('#keyboard')
  // keyboard plugin - see the full list of options above.
  .keyboard(options1)
  // jQuery UI autocomplete - go to http://jqueryui.com/demos/autocomplete/ for a complete list of options
  .autocomplete(options2) 
  // keyboard autocomplete extension, there are no options.
  .addAutocomplete();

Typing - Simulate typing into the keyboard (tutorials or assist user input)

// Setup: targeting a specific keyboard, or use $('.ui-keyboard-input') to target all
$('#keyboard')
  .keyboard(options)
  .addTyping();

// Usage: el.reveal().typeIn('text', time, callback);
// 'text' will be entered into the keyboard, time is the time in milliseconds between
// key strokes, the callback is called when completed.
// the following will type in the text with a 500ms delay then accept and close the keyboard when done.
var kb = $('#keyboard-input').getkeyboard();
kb
  .reveal()
  .typeIn('This is a test', 500, function(){ kb.accept(); });

Mobile - switch keyboard theme to match jQuery Mobile theme styles

// target a specific keyboard, or use $('.ui-keyboard-input') to target all
$('#keyboard')
  .keyboard({
    keyBinding : 'mousedown touchstart',
    alwaysOpen : true,
    // make sure jQuery UI styles aren't applied even if the stylesheet has loaded
    // the Mobile UI theme will still over-ride the jQuery UI theme
    css : {
      input          : '',
      container      : '',
      buttonDefault  : '',
      buttonHover    : '',
      buttonActive   : '',
      buttonDisabled : ''
    }
  })
  // For a better idea of what the theme letters represent, try out the mobile demo, or
  // go directly to the jQuery Mobile theming overview page:
  // http://jquerymobile.com/demos/1.0rc1/docs/api/themes.html
  .addMobile({
    // keyboard wrapper theme
    container    : { theme:'a' },
    // theme added to all regular buttons
    buttonMarkup : { theme:'a', shadow:'true', inline:'true', corners:'false' },
    // theme added to action buttons (e.g. tab, shift, accept, cancel);
    // parameters here will override the settings in the buttonMarkup
    buttonAction : { theme:'b' },
    // theme added to button when it is active (e.g. shift is down)
    // All extra parameters will be ignored
    buttonActive : { theme:'e' }
  });

Navigation - Allows navigating the virtual keyboard using the arrow keys (use F1 to toggle the mode)

CSS needed to better highlight the action keys (shift, enter, accept, etc)

/* Add this css so we can see when the action (orange) keys are highlighted */
.ui-keyboard-button.ui-state-active.ui-state-hover {
  border: 1px solid #fff;
  -moz-box-shadow: 1px 1em 1px #ffba2b inset;
  -webkit-box-shadow: 1px 1em 1px #ffba2b inset;
  box-shadow: 1px 1em 1px #ffba2b inset;
}
/* Class added to indicate the virtual keyboard has navigation focus */
.hasFocus {
  border-color: #59b4d4;
}

Javascript

$('#keyboard')
  .keyboard(options)
  .addNavigation({
    position   : [0,0],     // set start position [row-number, key-index]
    toggleMode : false,     // true = navigate the virtual keyboard, false = navigate in input/textarea
    toggleKey  : 112,       // toggle key; F1 = 112 (event.which value for function 1 key)
    focusClass : 'hasFocus' // css class added to the keyboard when toggle mode is on
  });

Scramble

Scramble targeted keyboard keys by row or entire keyset.

// target a specific keyboard, or use $('.ui-keyboard-input') to target all
$('#keyboard')
  // keyboard plugin - see the full list of options above.
  .keyboard(options1)
  .addScramble({
    targetKeys    : /[a-z\d]/i, // keys to randomize
    byRow         : true,       // randomize by row, otherwise randomize all keys
    randomizeOnce : true        // if true, randomize only once on keyboard visible
  });

---

Wiki Pages: Home | FAQ | Setup | Usage | Options ( Layout, Language, Usability, Actions ) | Methods | Theme | Log