Skip to content
This repository has been archived by the owner on Jan 26, 2024. It is now read-only.

Methods

Jump to bottom
Mottie edited this page Mar 13, 2013 · 22 revisions

Sections: Event Callbacks | switchInput | validate | Callback Variables | Callback Functions

visible, hidden, change, beforeClose, canceled or accepted callbacks - [Function]

  • Callbacks / Triggered Events:

    • initialized - Event called immediately after the keyboard has been initialized for the first time.
    • visible - Event called when the virtual keyboard is visible.
    • change - Event called when there is a change in the virtual keyboard input (key clicked or manual input).
    • beforeClose - Event called when the keyboard is about to close
      • This event has an additional variable which indicates if the content was accepted or ignored. Example added below.
      • This event occurs before the accept or cancelled events, but after the content has been validated.
    • accepted - Event called when the accept button on the virtual keyboard is pressed.
    • canceled - Event called when the virtual keyboard was closed without accepting any changes.
    • hidden - Event called when the virtual keyboard is hidden.

  • Add a function to any or all of these callbacks in the initialization code as seen in the example below.

  • When binding to an event, make sure you include the namespace '.keyboard' (e.g. "accepted.keyboard")

  • e is the event variable - e.target is the same object as el.

  • keyboard is the keyboard data object which you can also access using $('#keyboard').getkeyboard()

  • el in the example below is the #keyboard object (non-jQuery object). Use value to get the input/textarea content. Use el.keyboard to access the popup keyboard object.

Callbacks

// Using Callbacks
$('#keyboard').keyboard({
	accepted : function(e, keyboard, el){
		alert('The content "' + el.value + '" was accepted!');
	}
});

Events

// Using triggered events - set up to target all inputs on the page!
$('.ui-keyboard-input').bind('accepted.keyboard', function(e, keyboard, el){
	var txt = 'Input ID of ' + el.id + ' has the accepted content of ' + el.value;
	alert(txt);
});

// Binding to the "beforeClose" event - it has an extra parameter ("accepted")
$('.ui-keyboard-input').bind('beforeClose.keyboard', function(e, keyboard, el, accepted){
	var txt = "Virtual Keyboard for " + el.id + " is about to close, and it's contents were ";
	txt += (accepted ? 'accepted' : 'ignored');
	txt += '. Current content = ' + el.value;
	txt += '. Original content = ' + keyboard.originalContent;
	alert(txt);
});

switchInput - [Function]

  • This function is only called when the enterNavigation option is true and:
    • The "shift+enter" key is pressed; for input and textarea.
    • Or, "enter" is pressed in an input only. In a textarea, a carriage return is added.
  • The following code shows the default behavior of this function.
    • It closes the current keyboard
    • Finds all keyboards on the page and figures out the index of the current keyboard.
    • Finds the next keyboard, if goToNext is true or previous keyboard, if goToNext is false.
    • If the next keyboard doesn't exist, go back to the first.
    • Or, if the previous keyboard doesn't exist, it will go to the last.
    • Give focus to the input that has a keyboard attached to open that keyboard.
$('#keyboard').keyboard({
  // Go to next or prev inputs
  // goToNext = true, then go to next input; if false go to previous
  // isAccepted is from autoAccept option or true if user presses shift-enter
  switchInput : function(keyboard, goToNext, isAccepted){
    // close this keyboard
    keyboard.close(isAccepted);
    // find ALL inputs with a keyboard attached, but make sure we aren't
    // targetting the preview window - it's a clone of the original input
    var all = $('.ui-keyboard-input:not(.ui-keyboard-preview)'),
    // find the index of the current keyboard, then go forward or backward one input
    indx = all.index(keyboard.$el) + (goToNext ? 1 : -1);
    // If we're on the last input, go back to the first (zero-based index)
    if (indx > all.length - 1) { indx = 0; } // go to first input
    // focus on the selected input; this opens the keyboard for that input;
    // if indx is -1, all.eq(-1) will open the last keyboard
    all.eq(indx).focus();
  }
});

This callback was added to change the enter navigation behaviour. For example, if you don't care if a keyboard is attached to the input, then just change the following line to target all inputs (that are not the preview):

    var all = $('input:not(.ui-keyboard-preview)'),

validate - [Function]

This function is unlike the other callbacks in that it is only a callback - there is no triggered event, so you can not use bind('validate') because this function needs to return a flag of true or false to the plugin. This function is called at two points:

  • During user input

    • But only if the acceptValid option is true.
    • It will validate the content while the user is typing.
    • If the function returns true because the content is valid, the accept button will have the class of "ui-keyboard-valid-input".
    • If the function returns false because the content is invalid the accept button will have the class of "ui-keyboard-invalid-input".
    • When adding your own validate function, make sure to use the isClosing variable to determine if the check is during active input or before keyboard closing. See the example below.

  • Before the beforeClose event to check the validity of the content and abort or continue the keyboard closing.

    • The validity function is always run at this point, even if the acceptValid option is false.
    • If the function returns true, the keyboard will continue on, accept the content and close (if not always open).
    • If this function returns false and the keyboard will abort the close, but only if the cancelClose option is true.

  • This function is set by default to function(keyboard, value, isClosing){ return true; }.

  • Any other actions can be performed or called from inside of this function. For example, if the value is invalid, and you wish to then clear the keyboard input, do the following:

$('#keyboard').keyboard({
  validate: function(keyboard, value, isClosing){
    // test value for an email address
    var test = /^\s*[\w\-\+_]+(\.[\w\-\+_]+)*\@[\w\-\+_]+\.[\w\-\+_]+(\.[\w\-\+_]+)*\s*$/.test(value);
    // if the value is invalid, alert the user
    if (!test && isClosing) {
        alert('please enter a valid email address');
    }
    // return valid test (true or false)
    return test;
  }
});

// modify accept keyaction to alert when content has been accepted
$.extend($.keyboard.keyaction, {
    accept: function(base) {
        if (base.accept()) {
            alert('Accepted!');
        }
    }
});

This example shows how to add a signal/notification that the input is invalid

$('#keyboard').keyboard({
  acceptValid : true,
  validate    : function(keyboard, value, isClosing) {

    // only allow a 3-digit number
    var valid = /^\d{3}$/g.test(value);

    if (isClosing && valid) {

      // *** closing and valid ***
      return true;
    } else if (isClosing && !valid) {

      // *** closing and not valid ***
      // add an indicator/popup here to tell the user the input is not valid
      keyboard.$preview.addClass('red-border') // needs css: .red-border { border: #f00 1px solid; }
      // remove indicator after 5 seconds
      setTimeout(function(){
        keyboard.$preview.removeClass('red-border'); // no more red border
      }, 5000);
      // fire off a canceled event
      keyboard.$el.trigger('canceled', [ keyboard, keyboard.el ]  );
      return false;
    }

    // *** not closing ***
    // continuous checking during input, so don't go nuts here
    // accept button is enabled/disabled automatically if "acceptValid" is true
    return valid;
  }
});

Callback Variables

This is a list of variables and functions available during any of the above callback functions Note that if the variable has a $ in it's name, then it is a jQuery object.

Objects

  • keyboard.el - original keyboard input object.
  • keyboard.$el - original keyboard input jQuery object; it's the same as doing $( keyboard.el ).
  • keyboard.preview - will point to the preview window input object, if the usePreview option is true; it will point to keyboard.el if usePreview is false.
  • keyboard.$preview - will point to the preview window input jQuery object, if the usePreview option is true; it will point to keyboard.$el if usePreview is false.
  • keyboard.$keyboard - jQuery object of the entire keyboard

Values

  • keyboard.$preview.val() - always get the current keyboard content using this method
  • keyboard.originalContent - contains the text from the input/textarea before the keyboard opened.
  • keyboard.options.{option} - access any of the options; try not to modify them from here as it may break the keyboard.

States

  • keyboard.isVisible - true when the keyboard is visible; false when hidden.
  • keyboard.isCurrent() - function returns true when the keyboard is the current; Needed to figure out which one has focus when multiple keyboards are open (alwaysOpen: true).
  • keyboard.shiftActive - true when the shift key is active; false when not active.
  • keyboard.altActive - true when the alt key is active; false when not active.
  • keyboard.metaActive - false when the meta key is no active, and contains the meta key name when it is active (e.g. meta99)
  • keyboard.capsLock - true when the caps lock key is active; false when not active. Please note that this particular value is not 100% reliable as it isn't possible to detect the actual state of this key.

Callback Functions

Most of these functions are NOT chainable, except for the reveal function (i.e. keyboard.insertText('hello').close() will NOT work). See the Setup page for more examples on how to use the typing extension.

reveal

  • Use keyboard.reveal()
  • Opens the keyboard.
  • This function is chainable, i.e. keyboard.reveal().insertText('hello') will work.

accept

  • Use keyboard.accept()
  • This function will accept the keyboard contents, then close the keyboard.

close

  • Use keyboard.close()
  • This function will reject the keyboard contents, then close the keyboard.

insertText

  • Use keyboard.insertText("text")
  • This function will insert text into the keyboard at the current caret position.
  • If you want to backspace, then use "bksp" and nothing else to remove the character to the left of the current caret position.

checkCombos

  • Use keyboard.checkCombos()
  • This function will check the current keyboard contents for letter combinations and convert them (e.g. ~ + o becomes õ).

checkMaxLength

  • Use keyboard.checkMaxLength()
  • This function will check the length of the current keyboard contents and remove any excess.
  • Nothing will happen if the maxLength option is false.

showKeySet(meta)

  • Use keyboard.showKeySet(meta)

  • The keyset shown is based on the settings of the following variables: keyboard.shiftActive, keyboard.altActive and keyboard.metaActive.

  • The "meta" variable is needed to tell the function which meta key set to use. See the example below:

    Example: show shift key set

    keyboard.shiftActive = true;
keyboard.altActive = keyboard.metaActive = false;
keyboard.showKeySet();

    Example: show alt-shift key set

    keyboard.altActive = keyboard.shiftActive = true;
keyboard.metaActive = false;
keyboard.showKeySet();

    Example: show meta2 key set

    keyboard.metaActive = true;
keyboard.altActive = keyboard.shiftActive = false;
keyboard.showKeySet({ name : "meta2" });

destroy

  • Use keyboard.destroy()

  • This function completely removes the keyboard and events from the input.

  • This function is needed if you plan to change the keyboard layout when using the same input. See the layout demo.

     keyboard=$('#keyboard').keyboard().getkeyboard();
 keyboard.destroy();

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

Navigation

Clone this wiki locally