# jsPsych.pluginAPI

The pluginAPI module contains functions that are useful when developing new plugins. 

---
## jsPsych.pluginAPI.cancelAllKeyboardResponses

```
jsPsych.pluginAPI.cancelAllKeyboardResponses()
```

### Parameters

None.

### Return value

Returns nothing.

### Description 

Cancels all currently active keyboard listeners created by `jsPsych.pluginAPI.getKeyboardResponse`.

### Examples

```javascript
jsPsych.pluginAPI.cancelAllKeyboardResponses();
```

---
## jsPsych.pluginAPI.cancelKeyboardResponse

```
jsPsych.pluginAPI.cancelKeyboardResponse(listener_id)
```

### Parameters

Parameter | Type | Description
----------|------|------------
listener_id | object | The listener_id object generated by the call to `jsPsych.pluginAPI.getKeyboardResponse`.

### Return value

Returns nothing.

### Description 

Cancels a specific keyboard listener created by `jsPsych.pluginAPI.getKeyboardResponse`.


### Examples

```javascript
// create a persistent keyboard listener
var listener_id = jsPsych.pluginAPI.getKeyboardResponse(after_response, ['p','q'], 'date', true);

// cancel keyboard listener
jsPsych.pluginAPI.cancelKeyboardResponse(listener_id);
```

---
## jsPsych.pluginAPI.enforceArray

```
jsPsych.pluginAPI.enforceArray
```

### Parameters

Parameter | Type | Description
----------|------|------------


### Return value



### Description 



### Examples

```javascript


```

---
## jsPsych.pluginAPI.getKeyboardResponse

```
jsPsych.pluginAPI.getKeyboardResponse(callback_function, valid_responses, rt_method, persist)
```

### Parameters

Parameter | Type | Description
----------|------|------------
callback_function | function | The function to execute whenever a valid keyboard response is generated.
valid_responses | array | An array of key codes or character strings representing valid responses. Responses not on the list will be ignored. An empty array indicates that all responses are acceptable.
rt_method | string | Indicates which method of recording time to use. The `'date'` method uses calls to `(new Date()).getTime()` to record timing information. The `'performance'` method uses calls to `performance.now()`, which is a more modern JavaScript feature. The `'performance'` approach is [not supported by all the major browsers yet](http://caniuse.com/#search=performance), but adoption rates are increasing.
persist | boolean | If false, then the keyboard listener will only trigger the first time a valid key is pressed. If true, then it will trigger every time a valid key is pressed until it is explicitly cancelled by `jsPsych.pluginAPI.cancelKeyboardResponse` or `jsPsych.pluginAPI.cancelAllKeyboardResponses`. 

### Return value

Return an object that uniquely identifies the keyboard listener. This object can be passed to `jsPsych.pluginAPI.cancelKeyboardResponse` to cancel the keyboard listener.

### Description 

Gets a keyboard response from the subject, recording the response time from when the function is first called until a valid response is generated. 

A valid response triggers the `callback_function` specified in the parameters. A single argument is passed to the callback function. The argument contains an object with the properties `key` and `rt`. `key` contains the numeric key code of the response, and `rt` contains the response time.

### Examples

#### Get a single response from any key
```javascript

var after_response = function(info){
	alert('You pressed key '+info.key+' after '+info.rt+'ms');
}

jsPsych.pluginAPI.getKeyboardResponse(after_response, [], 'date', false);
```

#### Get a responses from a key until the letter Q is pressed
```javascript

var after_response = function(info){
	alert('You pressed key '+info.key+' after '+info.rt+'ms');
	
	if(info.key == 81){ // the key code for 'Q' is 81.
		jsPsych.pluginAPI.cancelKeyboardResponse(listener);
	}
}

var listener = jsPsych.pluginAPI.getKeyboardResponse(after_response, [], 'date', true);
```

---
## jsPsych.pluginAPI.normalizeTrialVariables

```
jsPsych.pluginAPI.normalizeTrialVariables(trial, protect)
```

### Parameters

Parameter | Type | Description
----------|------|------------
trial | object | An object representing the trial (typically the same variable that gets passed to the `plugin.trial` method). It contains `key: value` pairs describing all the trial parameters.
protect | array | An array of strings, indicating which parameters in the `trial` object should be protected from normalization

### Return value

Returns a new trial object with all values that were functions replaced by the return value of the function.

### Description 

This method replaces any parameters that are functions with the output of the function.

### Example

```javascript

// a snippet from a trial method

plugin.trial = function(display_element, trial) {
	
	trial = jsPsych.pluginAPI.normalizeTrialVariables(trial);
	 
	 // the rest of the trial code...
}

```