implements #489

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
 

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,

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);