diff --git a/docs/markdown_docs/core_library/jspsych-pluginAPI.md b/docs/markdown_docs/core_library/jspsych-pluginAPI.md index 91b1ce2b..d508014c 100644 --- a/docs/markdown_docs/core_library/jspsych-pluginAPI.md +++ b/docs/markdown_docs/core_library/jspsych-pluginAPI.md @@ -111,7 +111,37 @@ Returns nothing. Clears any pending timeouts that were set using jsPsych.pluginAPI.setTimeout() +--- +## jsPsych.pluginAPI.compareKeys +``` +jsPsych.pluginAPI.compareKeys(key1, key2) +``` + +### Parameters + +Parameter | Type | Description +----------|------|------------ +key1 | string or numeric | The representation of a key, either string or keycode +key2 | string or numeric | The representation of a key, either string or keycode + +### Return value + +Returns true if keycodes or strings refer to the same key, regardless of type. + +### Description + +Compares two keys to see if they are the same, ignoring differences in representational type. + +### Examples + +```javascript +jsPsych.pluginAPI.compareKeys('a', 65); +// returns true + +jsPsych.pluginAPI.convertKeyCharacterToKeyCode('space', 31) +// returns false +``` --- ## jsPsych.pluginAPI.convertKeyCharacterToKeyCode @@ -144,6 +174,37 @@ keycode = jsPsych.pluginAPI.convertKeyCharacterToKeyCode('space') // keycode is 32 ``` +--- +## jsPsych.pluginAPI.convertKeyCodeToKeyCharacter + +``` +jsPsych.pluginAPI.convertKeyCodeToKeyCharacter(character) +``` + +### Parameters + +Parameter | Type | Description +----------|------|------------ +code | numeric | The numeric representation of keyboard key. + +### Return value + +Returns the string representation of the key associated with the `code` parameter. + +### Description + +Converts between the numeric key code of a key and the string representation associated with that key. + +### Examples + +```javascript +var keycode = jsPsych.pluginAPI.convertKeyCharacterToKeyCode(65) +// key is 'a' + +keycode = jsPsych.pluginAPI.convertKeyCharacterToKeyCode(32) +// keycode is 'space' +``` + --- ## jsPsych.pluginAPI.getAudioBuffer diff --git a/jspsych.js b/jspsych.js index 77fbe779..95236571 100755 --- a/jspsych.js +++ b/jspsych.js @@ -1967,6 +1967,17 @@ jsPsych.pluginAPI = (function() { return undefined; } + module.compareKeys = function(key1, key2){ + // convert to numeric values no matter what + if(typeof key1 == 'string') { + key1 = module.convertKeyCharacterToKeyCode(key1); + } + if(typeof key2 == 'string') { + key2 = module.convertKeyCharacterToKeyCode(key2); + } + return key1 == key2; + } + var keylookup = { 'backspace': 8, 'tab': 9, diff --git a/tests/jsPsych.pluginAPI/pluginapi.test.js b/tests/jsPsych.pluginAPI/pluginapi.test.js index 950c1af2..957fbfb3 100644 --- a/tests/jsPsych.pluginAPI/pluginapi.test.js +++ b/tests/jsPsych.pluginAPI/pluginapi.test.js @@ -91,6 +91,17 @@ describe('#cancelAllKeyboardResponses', function(){ }); }); +describe('#compareKeys', function(){ + test('should compare keys regardless of type', function(){ + expect(jsPsych.pluginAPI.compareKeys('q', 81)).toBe(true); + expect(jsPsych.pluginAPI.compareKeys(81, 81)).toBe(true); + expect(jsPsych.pluginAPI.compareKeys('q', 'Q')).toBe(true); + expect(jsPsych.pluginAPI.compareKeys(80, 81)).toBe(false); + expect(jsPsych.pluginAPI.compareKeys('q','1')).toBe(false); + expect(jsPsych.pluginAPI.compareKeys('q',80)).toBe(false); + }); +}); + describe('#convertKeyCharacterToKeyCode', function(){ test('should return the keyCode for a particular character', function(){ expect(jsPsych.pluginAPI.convertKeyCharacterToKeyCode('q')).toBe(81);