Actions

Sections: Add Action Keys | Modify Action Keys | Default Actions

Add Action Keys

• Add a keyaction function, e.g.

  $.keyboard.keyaction.test = function(base){};

  or extend the variable to add more than one, e.g.

  $.extend( $.keyboard.keyaction, {
    test  : function(base){},
    test2 : function(base){}
  });

• Add a display option name update (optional) into the keyboard initialization options. In the example below, if you don't change the display name, the action key name will be "test"

• Add the new action key to your layout by simply wrapping the key name in curly brackets e.g. "{test}"

• Some action keys can get the button action class applied as follows:

  • The action class (options.css.buttonAction) is applied and makes the button stand out like the {accept}, {cancel} & {enter} keys.
  • Add double exclamation point to the custom key name {custom!!} or to any built-in action key except: {accept}, {alt}, {bksp}, {cancel}, {combo}, {dec}, {enter}, {meta#}, {shift}, {sign}, {sp:#}, {space} or {tab}.
  • For an example, see "Custom Action Key" demo.

// Add a "test" keyaction
$.keyboard.keyaction.test = function(base){
  alert('you smell like cheese');
};

$('#junk').keyboard({
  layout: 'custom',
  display: {
    'test' : 'Cheese' // change the test keyaction displayed name to "Cheese"
  },
  customLayout: {
    'default' : [
    // {test} adds the keyaction key and displays the alert
    // "test" will enter the text "test" into the input
    '{test} test'
    ]
  }
});

• Here is an example that adds two action keys which add or subtract one from the current value - demo made in response to issue #54. Note the use of jQuery's extend function.

$.extend($.keyboard.keyaction, {
    plus: function(base){
        var v = parseFloat(base.$preview.val()) || 0;
        base.$preview.val(v+1);
    },
    minus: function(base){
        var v = parseFloat(base.$preview.val()) || 0;
        base.$preview.val(v-1);
    }
});

$('#keyboard').keyboard({
    acceptValid: false,
    layout: 'custom',
    display: {
        'alt'   : '\u2666', // Diamond
        'plus'  : '+',
        'minus' : '-'
    },
    customLayout: {
        'default': ['{alt} {accept} {cancel}', '{plus} {minus}'],
        'alt': ['{alt} {accept} {cancel}', '1 2 3', '4 5 6', '7 8 9', '0 . c']
    },
    alwaysOpen: true,
    visible: function(e, key, el) {
        key.$preview[0].select();
    },
    validate: function(e, key, el) {
        // Accept only numeric
        var test = /\d+/.test(key);
        if (!test) {
            e.$preview.val('');
        }
        return test;
    }

});

• See the scientific calculator script for a lot more examples.

Modify an Action Key

• As described in this issue, you could modify the enter key action (both typed and clicked in the virtual keyboard) to submit the form when activated.

$.keyboard.keyaction.enter = function(base){
  if (base.el.nodeName === "INPUT") {
    base.accept();      // accept the content
    $('form').submit(); // submit form on enter
  } else {
    base.insertText('\r\n'); // textarea
  }
};

Default Actions

• Any of the following keyaction functions can be modified as desired.
• I wouldn't recommend modifying the "alt", "shift" or "meta" functions. As they change the visible keyset, but I left it in here to show how to determine which keyset is active or to even switch them.
• In v1.24.0, keyaction definitions can be just a string. Using this method will override the keyaction name with the keyaction value. See the zero-width character definitions in the code below.

// Action key function list
$.keyboard.keyaction = {
  accept : function(base) {
    base.close(true); // same as base.accept();
    return false;     // return false prevents further processing
  },
  alt : function(base, el) {
    base.altActive = !base.altActive;
    base.showKeySet(el);
  },
  bksp : function(base) {
    // the script looks for the '\b' string and initiates a backspace
    base.insertText('\b');
  },
  cancel : function(base) {
    base.close();
    return false; // return false prevents further processing
  },
  clear : function(base) {
    base.$preview.val('');
    if (base.$decBtn.length) {
      base.checkDecimal();
    }
  },
  combo : function(base) {
    var c = !base.options.useCombos;
    base.options.useCombos = c;
    base.$keyboard.find('.' + $keyboard.css.keyPrefix + 'combo').toggleClass(base.options.css.buttonActive, c);
    if (c) { base.checkCombos(); }
    return false;
  },
  dec : function(base) {
    base.insertText((base.decimal) ? '.' : ',');
  },
  del : function(base) {
    // the script looks for the '\\d' string and initiates a delete
    base.insertText('\\d');
  },
  // resets to base keyset (deprecated because "default" is a reserved word)
  'default' : function(base, el) {
    base.shiftActive = base.altActive = base.metaActive = false;
    base.showKeySet(el);
  },
  // el is the pressed key (button) object; it is null when the real keyboard enter is pressed
  enter : function(base, el, e) {
    var tag = base.el.nodeName, o = base.options;
    // shift-enter in textareas
    if (e.shiftKey) {
      // textarea & input - enterMod + shift + enter = accept, then go to prev;
      //  base.switchInput(goToNext, autoAccept)
      // textarea & input - shift + enter = accept (no navigation)
      return (o.enterNavigation) ? base.switchInput(!e[o.enterMod], true) : base.close(true);
    }
    // input only - enterMod + enter to navigate
    if (o.enterNavigation && (tag !== 'TEXTAREA' || e[o.enterMod])) {
      return base.switchInput(!e[o.enterMod], o.autoAccept ? 'true' : false);
    }
    // pressing virtual enter button inside of a textarea - add a carriage return
    // e.target is span when clicking on text and button at other times
    if (tag === 'TEXTAREA' && $(e.target).closest('button').length) {
      base.insertText(' \n'); // IE8 fix (space + \n) - fixes #71 thanks Blookie!
    }
  },
  // caps lock key
  lock : function(base,el) {
    base.last.keyset[0] = base.shiftActive = base.capsLock = !base.capsLock;
    base.showKeySet(el);
  },
  left : function(base) {
    var p = $keyboard.caret( base.$preview );
    if (p.start - 1 >= 0) {
      // move both start and end of caret (prevents text selection) & save caret position
      base.last.start = base.last.end = p.start - 1;
    }
  },
  meta : function(base, el) {
    base.metaActive = !$(el).hasClass(base.options.css.buttonActive);
    base.showKeySet(el);
  },
  next : function(base) {
    base.switchInput(true, base.options.autoAccept);
    return false;
  },
  // same as 'default' - resets to base keyset
  normal : function(base, el) {
    base.shiftActive = base.altActive = base.metaActive = false;
    base.showKeySet(el);
  },
  prev : function(base) {
    base.switchInput(false, base.options.autoAccept);
    return false;
  },
  right : function(base) {
    var p = $keyboard.caret( base.$preview );
    if (p.start + 1 <= base.$preview.val().length) {
      // move both start and end of caret (prevents text selection) && save caret position
      base.last.start = base.last.end = p.start + 1;
    }
  },
  shift : function(base, el) {
    base.last.keyset[0] = base.shiftActive = !base.shiftActive;
    base.showKeySet(el);
  },
  sign : function(base) {
    if(/^\-?\d*\.?\d*$/.test( base.$preview.val() )) {
      base.$preview.val( (base.$preview.val() * -1) );
    }
  },
  space : function(base) {
    base.insertText(' ');
  },
  tab : function(base) {
    var tag = base.el.nodeName,
      o = base.options;
    if (tag === 'INPUT') {
      if (o.tabNavigation) {
        return base.switchInput(!base.shiftActive, true);
      } else {
        // ignore tab key in input
        return false;
      }
    }
    base.insertText('\t');
  },
  toggle : function(base) {
    base.enabled = !base.enabled;
    base.toggle();
  },
  // *** Special action keys: NBSP & zero-width characters ***
  // Non-breaking space
  NBSP : '\u00a0',
  // zero width space
  ZWSP : '\u200b',
  // Zero width non-joiner
  ZWNJ : '\u200c',
  // Zero width joiner
  ZWJ : '\u200d',
  // Left-to-right Mark
  LRM : '\u200e',
  // Right-to-left Mark
  RLM : '\u200f'
};