@@ -4,12 +4,218 @@ This chapter contains functions you can use to record the participant’s or the
## getKeyValue
function: getKeyValue
**Description**
Use this function to get the key values used for getAnswer. Simply start the program and when ready press a key. The program will give you the internal code for this key. Not a function that should be called during an experiment but during preparation.
**See also**
getAnswer
## keyBuffer (animal)
function: total = keyBuffer(duration,varargin)
**Description**
This buffer stores behavioral responses over a period of time specified in duration. In addition, it terminates if a specified number of responses on "good keys", "neutral keys" or "bad keys" is reached.
To use this feature specify at least the position of the good, neutral or bad keys and the number of responses. This function can be used either with a touchscreen or with input-keys.
It is up to you to determine which responde key is good, neutral or bad key. These differentiations will help you to analyse the response, since the answers are stored separately.
For auditory feedback use the 'sound' option. It plays a previously loaded sound file for every response.
**Inputs**
~~~
duration the time in sec to wait unless defined number of responses has been reached before
~~~
**Inputs-optional**
~~~
varargin ‘goodKey’ followed by a vector of pin numbers and a scalar of response amount
‘badKey’ followed by a vector of pin numbers and a scalar of response amount
‘neutralKey’ followed by a vector of pin numbers and a scalar of response amount
‘timeoutBad’ increase the waiting duration for each response to a bad key.
Needs to be followed by a specified time in sec
‘sound’ sound that will be played every time an answer is given.
Needs to be followed by a wav file handle, loaded with loadSound
‘remoteStop’ a remote computer can interrupt the execution via network.
You can also use the stopRemoteKeyBuffer function.
‘sendNetID’ send the clients network ID after a *successful* response to a control computer (network init required)
~~~
**Outputs**
~~~
total a struct containing all possible information
.raw a matrix containing time and position of responses
.goodKey a vector containing the summary of all responses on good keys
.badKey a vector containing the summary of all responses on bad keys
.neutralKey a vector containing the summary of all responses on neutral keys
.offKey amount of responses to undefined keys
.rt time of the function to finish (reaction time in seconds)
.globalValue coordinates of the whole screen (only touchscreen)
.localValue coordinates of the stimulus
.definedGoodKey vector of pin numbers from optional input, zero otherwise
.definedBadKey vector of pin numbers from optional input, zero otherwise
.definedNeutralKey vector of pin numbers from optional input, zero otherwise
~~~
**Examples**
~~~
1. total = keyBuffer(10, ‘goodKey’, [1 2], 3);
% keyBuffer terminates after 10 seconds OR after three responses on keys at position
% keyBuffer terminates after 4 seconds OR after three responses on keys at position 1
% or 2 OR after three responses on key at position 3. In addition every answer is
% rewarded with a sound that was loaded with loadSound and saved into the variable
% soundH.
~~~
**See also**
switchBuffer, touchBuffer, bIO, getAnswer
## getAnswer (human)
function: total = getAnswer(duration,varargin)
**Description**
Use this function to get access to the user’s response keys in human experiments and the keyboard option. It is more flexible to use and replaces the function keyBuffer in most human experiments. getAnswer allows the ESC Key to be pressed to cancel the user input.
**Inputs**
~~~
duration the time to wait unless defined number of responses has been reached before
~~~
**Inputs-Optional**
~~~
varargin ‘goodKey’ followed by a vector of keyboard values and a scalar of response amount
‘badKey’ followed by a vector of keyboard values and a scalar of response amount
‘anyKey’ without argument, waits the given time and continues if the user pressed any key.
Not to be used with 'goodKey' or 'badKey'
‘waitAnyway’ waits the given time, even if the user pressed a key
(reaction time is saved in the extra field rt)
‘wait4release’ without argument, waits until the key is released.
Bad for exact timing, but necessary in some cases
~~~
**Outputs**
~~~
out a struct containing all possible information
.key a vector containing the characters of the keys the user pressed during response
.keyVal a vector containing the key values of the keys the user pressed during response
.answer defines if the answer was correct or not (needs goodKey and badKey to define the answer)
1 = good, -1 = bad, 0 = no answer
.time time in s the function was running (usually this is equal to the reaction time, but not in case 'waitAnyway')
.rt response time of the user in seconds (in all cases)
.goodKey a vector containing the summary of all responses on good keys
.badKey a vector containing the summary of all responses on bad keys
.start start time of the function
.stop stop time of the function
.escape this entry is set to one, if ESC was pressed
~~~
**Examples**
~~~
1) out = getAnswer(10, 'goodKey', 65);
Waits 10 seconds or continues after the user presses key a (65 represents kay a). All other keys are ignored
2) out = getAnswer(5, 'goodKey', 77, 'badKey', [74 75]);
Waits 5 seconds or continues after a button press on m (77 as goodKey) or j and k (74, 75 as badKeys).
The result struct marks answer as incorrect (-1) if button j or k were pressed and correct (1) if button m was pressed
3) out = getAnswer(10, 'anyKey');
Waits 10 seconds or continues after a button press on any key. To test this feature in the command line use the following code:
WaitSecs(0.2);getAnswer(5, 'anyKey')
~~~
## createButton
function: bHand = createButton(text, varargin)
**Description**
Creates a ‘button’ on the stimulus window. Position defines the left upper corner of the ‘button’. The function actually only creates text similar to showText with a box around it. To activate this ‘button’ on the screen use the getButtonClick function.
**Inputs**
~~~
text displayed text as string (‘/n’ for new line works! ‘/t’ for tab does not work!)
~~~
**Inputs-optional**
~~~
varargin ‘x’ x position in percent (0 -> left, 100 -> right)
‘y’ y position in percent (0 -> top, 100 -> bottom)
‘color’ text color as RGB vector with values from 0:255
% displays two button with text "Start" and "Stop" in the upper part of the screen.
~~~
**See also**
getMouse, showText, keyBuffer, getButtonClick
## getButtonClick
function: out = getButtonClick(stopTime, varargin)
**Description**
Get the click on a button that was created with createButton. Function ends after specified time, after button click or after ESC was clicked to exit the function.
**Inputs**
~~~
stopTime time to wait for a button click in sec
~~~
**Inputs-optional**
~~~
varargin vector of button handles created by createButton
~~~
**Outputs**
~~~
out a struct containing all possible information
.click.pos returns button number of clicking position
.time reaction time/ time the function was running in sec
.escape this entry is set to one, if ESC was pressed
~~~
**Examples**
~~~
1. out = getButtonClick(5, bHand1, bHand2, bHand3);
% Waits 5 seconds or until a click on any of the buttons occurs
~~~
## getMousePos
function: out = getMousePos(waitTime)
**Description**
This function returns the Mouse position (x, y) after a left click on the stimulus presentation window. Calling getMousePos without arguments blocks execution until a click is done. A call with the argument waitTime exits after a left click or after the given time.
**Inputs-Optional**
~~~
waitTime the time to wait (in sec) unless defined number of responses has been reached before
~~~
**Outputs**
~~~
out a struct containing all possible information
.x the X position of the point where the user clicked. Zero if the user did not click.
.y the Y position of the point where the user clicked. Zero if the user did not click.
.time response time of the user in seconds
.escape this entry is set to one, if ESC was pressed
