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

    ```javascript
    // 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.
  • {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.

        ```javascript
        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):

    ```javascript
    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 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

        ```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

    ```javascript
    $('.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.

    ```javascript
    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.