Skip to content

Layout

Jump to bottom Edit New page
Rob Garrison edited this page Feb 4, 2012 · 51 revisions

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

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.
  • 'num' - Numerical (ten-key) layout.
  • '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#'.

  • 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
customLayout: { 'default': ['r o w 1 {c}', 'r o w 2 {a}'] }
// example: four rows; no shift/alt key sets
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.
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
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 from the end of the content (for now).
    • {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)
    • {e}, {enter} - (optional) Enter/New Line. {e} is the narrow enter key.
    • {lock} (optional) Adds a cap lock key. The state of this key is not 100% reliable.
    • {meta1}, {meta2} ... {meta#} - meta keys that change the key set (no limit on numbers).
    • {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 (1em).
    • {space} - (optional) Spacebar
    • {t}, {tab} - (optional) Tab. {t} is the narrow tab key.

  • 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}' ]
  }
});

  • 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 (view demo.js for another example - Meta):

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

    • View demo.js source for more examples.

position - [Object]

  • Set keyboard position.

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

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

  • 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.

    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)
}

  • 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.

  • 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".

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

  • The default settings are shown above.

Wiki Pages: Home | FAQ | Setup | Usage | Options ( Layout, Language, Useability, 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