Skip to content

Layout

Jump to bottom Edit New page
Rob Garrison edited this page Jul 31, 2016 · 51 revisions

Sections:

layout - [String]

  • Specify which keyboard layout to use.
  • 'qwerty' - Standard QWERTY layout (Default).
  • 'international' - Standard US-international QWERTY layout.
  • 'alpha' - Alphabetical layout.
  • 'dvorak' - Dvorak Simplified layout.
  • 'colemak' - Colemak layout.
  • 'num' - Numerical (ten-key) layout.
  • 'numpad' - Numerical layout with left & right caret keys (added by extender extension).
  • 'custom' - Uses a custom layout as defined by the customLayout option.
  • Default value is 'qwerty'

customLayout - [Object]

  • Specify a custom layout

  • This was completely changed in version 1.5.3!

  • The layout is defined as an object with arrays.

  • The object is set up as a key : value pair.

  • The key is the name of the key set: 'default' (no modifier), 'shift', 'alt', 'alt-shift', 'meta#'.

  • Please note that default (without quotes) is a reserved javascript word, so make sure to INCLUDE quotes ('default')

  • The value is an array containing blocks of strings that represent a keyboard row.

  • Inside each block are the defined keys, which must be separated from each other with a space.

  • The keys are added from top to bottom and left to right, so set it up appropriately.

  • Regular keys should be a single character or unicode string (e.g. \u2190 = left arrow).

  • Special action keys have curly brackets {a} around them.

    // two row keyboard
layout : 'custom',
customLayout: { 'default': ['r o w 1 {c}', 'r o w 2 {a}'] }
// example: four rows; no shift/alt key sets
layout : 'custom',
customLayout: { 'default': ['r o w 1', 'r o w 2', 'r o w 3', '{accept} {cancel}'] }

  • The default key set is shown above and must be defined in every custom layout.

  • To add additional key sets (e.g. 'shift') copy the same pattern as the default definition:

    // two rows; each row has four key sets. An {accept} or {check}, {shift} and {alt} key are required.
layout : 'custom',
customLayout: {
  'default': ['r o w 1 {shift}', 'r o w 2 {a} {c}'],
  'shift'  : ['R O W 1 {shift}', 'R O W 2 {a} {c}']
}
// example: three rows and three key sets - shift & meta1 keyset rows included
// note: the {shift} needs to be included in both the default and shifted keysets, that's why there are two
layout : 'custom',
customLayout: {
  'default': ['a b c d e', 'f g h i j', '{shift} {meta1} {a} {c}'],
  'shift'  : ['A B C D E', 'F G H I J', '{shift} {meta1} {a} {c}'],
  'meta1'  : ['1 2 3 4 5', '6 7 8 9 0', '{shift} {meta1} {a} {c}']
}

  • In the list below where two special/"Action" keys are shown, both keys have the same action but different appearances.

  • You can define your own key functions by adding the action key name to the $.keyboard.keyaction variable.

  • Default special/"Action" keys include:

    • {a}, {accept} - (required) Updates element value and closes keyboard.
    • {alt}, {altgr} - (optional/required) AltGr for International keyboard which switches the key set. Required for alt keysets.
    • {b}, {bksp} - (optional) Backspace. Deletes characters to the left of the caret.
    • {c}, {cancel} - (optional) Clears changes and closes keyboard (clicking outside or hitting escape does this as well)
    • {clear} - (optional) Clear input window - used in num pad
    • {combo} - (optional) Toggle combo (diacritic) key
    • {dec} - (optional) Decimal for numeric entry, only allows one decimal point in the window (meant for use in num pad)
    • {del} - (optional) Delete. Deletes characters to the right of the caret.
    • {default} - (optional) Changes the keyset back to the original (i.e. "normal" or "default" keyset) - deprecated because "default" is a reserved javascript word.
    • {e}, {enter} - (optional) Enter/New Line. {e} is the narrow enter key.
    • {empty}, {empty:#} - (optional) empty (blank) key. Include a numerical value to set the width of the key (behaves the same as {sp:#})
    • {left} - (optional) Adds a left arrow key which moves the caret left within the input.
    • {lock} - (optional) Adds a cap lock key. The state of this key is not 100% reliable.
    • {meta1}, {meta2} ... {meta#} - (optional/required) meta keys that change the key set (no limit on numbers).
    • {next} - (optional) Switch to next keyboard input/textarea.
    • {normal} - (optional) Changes the keyset back to the original (i.e. "normal" or "default" keyset).
    • {prev} - (optional) Switch to previous keyboard input/textarea.
    • {right} - (optional) Adds a right arrow key which move the caret right within the input.
    • {s}, {shift} - (optional/required) Shift/Capslock. Required to show shifted keysets.
    • {sign} - (optional) Change sign of numeric entry (positive or negative)
    • {sp:#} - (optional) Replace # with a numerical value, adds blank space in the keyboard. A value of 1 ~ width of one key (which is actually 2em).
    • {space} - (optional) Spacebar
    • {t}, {tab} - (optional) Tab. {t} is the narrow tab key.
    • {toggle} - (optional) Enable or disable the keyboard.

  • Meta keys

    • These keys are independent of the {shift} and {alt} keys, but essentially do the same thing - they change the key set.

    • Meta key sets also include {shift} and {alt} key sets.

    • While hovering over any key, scrolling the mousewheel will allow access to all keys from other key sets in the same position.

    • You can add ANY NUMBER of meta key sets.

    • To add a new meta key set, add the name 'meta' plus a number (no spaces) in the customLayout definition, then define the key set.

    • Adding the display meta# name is optional, but the key added will be named 'meta#'.

    • The meta key that switches the key set must match the name defined in the customLayout, but be surrounded by curly brackets {}

    • For example, if I add a 'meta1' key set in the custom layout, then the meta key that activates the set will be called {meta1} - added to the array. See the example below and view the demo source for another example.

      $('#meta').keyboard({
  layout : 'custom',
  display : {
    'meta1'  : '\u2666', // Diamond
    'meta2'  : '\u2665'  // Heart
  },
  customLayout : {
    'default' : [ 'd e f a u l t', '{meta1} {meta2} {accept} {cancel}' ],
    'meta1'   : [ 'm y m e t a 1', '{meta1} {meta2} {accept} {cancel}' ],
    'meta2'   : [ 'M Y M E T A 2', '{meta1} {meta2} {accept} {cancel}' ]
  }
});

  • Spacers

    • {sp:#}:

      • In verisons prior to 1.9.9, a span of zero dimensions with a side margin of #em was added, i.e. {sp:1} would add a "margin: 0 1em" which adds 1em to the left and right making it 2em wide.

      • Because newer versions of Firefox do not seem to render a zero dimension span at all, the plugin now sets the span width.

      • A {sp:1} setting now becomes a span of "2em" width, to keep this consistent with the way this method worked previously.

      • In case this causes problems, one additional change was made so the space can now be set using pixels: {sp:20px} which makes the width 20 pixels.

      • Additionally, non-western formats are now supported. Using {sp:1,5} or {sp:1,5em} will set the span to 3em's in width.

        // examples supported in version 1.9.9+; showing set widths
// 1em     2em    2.2em    2.6em    4em      2.4em      10px
'{sp:.5} {sp:1} {sp:1.1} {sp:1,3} {sp:2em} {sp:1,2em} {sp:10px}'

    • {empty}:

      • This {empty} special key inserts a blank unclickable key into the keyboard. Using {sp:1} does not add a key, but a blank space between keys.
      • Added in version 1.17.0.

    • {empty:#}

      • The empty can also include a width using the same method as the {sp:#} settings.
      • Added in v1.18.3.

  • Key Names:

    • As of version 1.5.4, all keys can be assigned a name (text put into the title attribute).

    • If a tooltip plugin is used on the page, just target '.ui-keyboard-button' and get the tooltip from the title.

    • Keys defined in the display option follow this format "Key Name:Key's Label". The "Key Name" is what is actually shown on the virtual keyboard, while "Key's Label" is added to the key's title attribute. The "Key's Label" can include spaces.

      display: {
  'accept' : 'Accept:Accept the Content',
  'meta1'  : '\u2666:Alternate character set',  // Diamond
  'meta2'  : '\u2665:Some other character set', // Heart
}

    • The key names defined in the customLayout cannot include spaces, the script will assume you want a new key. So only in the customLayout follow this format "key:Key_Label" - replace all spaces with an underscore. Here is an example:

      customLayout: {
  'default' : [
    '! @:this_is_an_at_symbol # $ % ^ & *:this_is_an_asterisk ( ) - + {bksp}'
  ]
}

    • View demo.js source for more examples; look for it in the Meta demo.

position - [Object]

  • Set keyboard position.

  • The portion of the script uses the jQuery UI positioning utility (optional script).

  • Adjust where the keyboard pops up relative to the input area.

    position : {
  of : null, // 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 the bottom of the input/textarea)
  collision: 'flipfit flipfit'
}

  • of refers to an object (selector, element or jQuery object) where the keyboard attaches.

    • The default below is null, but it reverts to the input object. Add a jQuery object (e.g. $('#keyboard-anchor')) to attach the keyboard elsewhere. This method works well for a single keyboard target.

    • If there are multiple keyboard targets, $('.targets') would not work as the position utility would target the first element in that jQuery object (equivalent to $('.targets:first')). So an alternate method was devised where the target object is stored in the element data variable keyboardPosition. For example, multiple hidden inputs have a keyboard link:

      HTML

      <a href="#" class="keyboard-links">Hidden input</a>
<!-- DON'T use type="hidden" because IE doesn't like hidden inputs -->
<input id="hidden" type="text" style="display:none;" />

      Script

      $('.keyboard-links').click(function(){
  $(this).next()                    // input is after the link, so use .next()
    .data('keyboardPosition', this) // store link object for keyboard positioning
    .trigger('focus');              // open keyboard
  return false;                     // disable link
});
// Don't define the position property when the keyboard is initialized
$('.keyboard').keyboard({
  layout: 'qwerty',
  accepted: function(e, keyboard, el){ alert('The content "' + el.value + '" was accepted!'); }
});

  • my (string) refers to a keyboard location. 'center top' is the keyboard point that is attached to the at element location.

  • at (string) refers to the element location (the input or textbox). 'center top' is the element point where the keypoint point is attached.

  • at2 (string) is used when the usePreview option is false. The preview window is removed and all input goes directly into the original input/textarea. The reason this is separate is that the usePreview option can be changed dynamically.

  • collision (string) value repositions the object when the positioned element overflows the window in some direction, it moves it to an alternative position. Similar to my and at, this accepts a single value or a pair for horizontal/vertical, eg. "flip", "fit", "fit flip", "fit none".

  • offset (string) values are added to the left-top values to the calculated position, eg. "50 50" (left top) A single value such as "50" will apply to both removed from the jQuery UI position utility.

  • For more information see the jQuery UI position utility documents.

  • The default settings are shown above.

If you don't want to use jQuery UI's position utility, this css will place the keyboard at the bottom of the page (demo)

/* position keyboard at bottom of the screen */
.ui-keyboard {
  border-radius: 0;
  left: 0;
  top: auto;
  bottom: 0;
  position: fixed;
  width: 100%;
}

reposition - [Boolean]

  • Allow jQuery UI position utility to reposition the keyboard on window resize.
  • This only applies if the postion option is not false and the jQuery UI position utility is included on the page.
  • Default setting is true.

css - [Object]

  • Class names used for theming.

  • By default, this option contains the class names needed to apply a jQuery UI theme to the keyboard.

  • Because of the methods used by the jQuery Mobile theme, it would be best to either clear out all of these class names, or just not load the jQuery UI stylesheet on mobile devices. Please see the Mobile extension demo source for more details.

  • The default values are as follows:

    css : {
  // input & preview styles
  input          : 'ui-widget-content ui-corner-all',
  // keyboard container - this wraps the preview area (if `usePreview` is true) and all keys
  container      : 'ui-widget-content ui-widget ui-corner-all ui-helper-clearfix',
  // default keyboard button state, these are applied to all keys, the remaining css options are toggled as needed
  buttonDefault  : 'ui-state-default ui-corner-all',
  // hovered button
  buttonHover    : 'ui-state-hover',
  // Action keys (e.g. Accept, Cancel, Tab, etc); this replaces the "actionClass" option
  buttonAction   : 'ui-state-active',
  // used when disabling the decimal button {dec} when a decimal exists in the input area
  buttonDisabled : 'ui-state-disabled'
},

Deprecated

actionClass - [String]

  • Class name used to make keys a different color
  • This variable contains the class that is only added to the Accept and cancel buttons to give them a different color from the normal keys.
  • It was originally set to 'ui-state-highlight' which looks good in some themes, but not others.
  • This class name can also be a custom one that you set up for these keys as well.
  • Default is 'ui-state-active'.
  • This option has been replaced by buttonAction within the css option.

Contribute a layout

If you would like to contribute a layout to this project, please check out the Contributing page for more details.

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

Home | FAQ | Setup | Usage | Options | Methods | Contenteditable | Theme | Log
Options: Layout | Language | Usability | Actions
Extensions: AltKeysPopup | Autocomplete | Caret | Extender | Mobile | Navigation | PreviewKeySet | Scramble | Typing

Clone this wiki locally