Layout

Wiki Pages: Home | Setup | Options ( Layout, Language, Useability ) | 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 should 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 {c}', 'r o w 2 {a}'],
      'shift'  : ['R O W 1 {c}', 'R O W 2 {a}']
    }
  
    // 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}' ]
        }
      });
    

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 the 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 alternat 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 refers to a keyboard location. 'center top' is the keyboard point that is attached to the at element location.

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

    position : {
      of : null, // null (attach to input/textarea) or a jQuery object (attach elsewhere)
      my : 'center top',
      at : 'center top'
    }
  

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

• The default settings are shown above.