Layout

Wiki Pages: Home | FAQ | Setup | 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 - [Array] 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.

• 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
  • {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.
  • {meta1}, {meta2}, {meta3}, {meta4} - meta keys that change the key set.
  • {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.
  • When a meta key is clicked, the {shift} and {alt} keys have no effect on the meta keyset, in fact clicking on either will turn off the meta key set.
  • 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 positioning

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

  <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;" />

  $('.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, 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 the 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.