define tests demos and errors for getResponse

Author: Remi-Gau

demos/CPP_getResponseDemo.m

@@ -1,100 +1,100 @@
 %% Demo showing how to use the getResponse function
 
 % This small script shows how to use the getReponse function
-%  (a wrapper around the KbQueue function from PTB)
 
-% start with a clean slate
-cd ..
-clear; clc;
+% add parent directory to matlab path (so we can access the CPP_PTB functions)
+addpath(fullfile(pwd, '..')) 
+
+
+%% start with a clean slate
+clear; 
+clc;
+
 if IsOctave
     more off % for a better display experience
 end
 
-%% set parameters
+% use the default set up (use main keyboard and use the ESCAPE key to abort)
+cfg = setDefaultsPTB;
 
-% cfg.responseBox would be the device number of the device used by the participant to give his/her
-% response: like the button box in the scanner or a separate keyboard for a behavioral experiment
-%
-% cfg.keyboard would be the device number of the keyboard on which the experimenter will type or
-% press the keys necessary to start or abort the experiment.
+% show the default option
+disp(cfg.keyboard)
 
-%  cfg.responseBox and cfg.keyboard can be different or the same.
+%% set parameters
 
-% If you want to know the device number of all the keyboards and responses
-% boxes connected to the computer you can use the following code.
-% [cfg.keyboardNumbers, cfg.keyboardNames] = GetKeyboardIndices
+% Change the values set by defaults (for more info about the keyboard see the doc) 
+% cfg.keyboard.keyboard = ??
+% cfg.keyboard.responseBox = ??
+% cfg.keyboard.escapeKey = ??
 
-% Using empty vectors should work for linux when to select the "main"
-%  keyboard. You might have to try some other values for Windows. To
-%  assigne a specific keyboard input the kb assigned value (see README)
-cfg.keyboard = [];
-cfg.responseBox = [];
+% Decide which device you want to collect responses from
+deviceNumber = []; % default device (PTB will find it for you)
+% deviceNumber = cfg.keyboard.keyboard; % the one you may have chosen as the main keyboard
+% deviceNumber = cfg.keyboard.responseBox; % the one you may have chosen as the response box
 
-cfg.escapeKey = 'ESCAPE';
+% if you want getResponse to ignore the key release
+getOnlyPress = 1;
 
 % We set which keys are "valid", any keys other than those will be ignored
-expParameters.responseKey = {};
+cfg.keyboard.responseKey = {'a', 'b'};
 
+% This would make sure that you listen to presses of the escape key
+cfg.keyboard.responseKey{end+1} = cfg.keyboard.escapeKey; 
 
-%% init
 
-% Keyboard
-%  Make sure keyboard mapping is the same on all supported operating systems
-%  Apple MacOS/X, MS-Windows and GNU/Linux:
-KbName('UnifyKeyNames');
-
-
-% we ask PTB to tell us which keyboard devices are connected to the computer
-[cfg.keyboardNumbers, cfg.keyboardNames] = GetKeyboardIndices;
-
-cfg.keyboardNumbers
-cfg.keyboardNames
+%% Final checks 
 
+% Make sure keyboard mapping is the same on all supported operating systems
+KbName('UnifyKeyNames');
 
 % Test that the keyboards are correctly configured
 testKeyboards(cfg);
 
-% Give the time to the test key to be released and not listened
+% Give the time to the test key to be released and not listened to
 WaitSecs(1);
 
-
 fprintf('\nDuring the next 5 seconds we will collect responses on the following keys: \n\n');
-if isempty(expParameters.responseKey)
+if isempty(cfg.keyboard.responseKey)
     fprintf('\nALL KEYS\n\n');
 else
-    for iKey=1:numel(expParameters.responseKey)
-        fprintf('\n%s', expParameters.responseKey{iKey});
+    for iKey=1:numel(cfg.keyboard.responseKey)
+        fprintf('\n%s', cfg.keyboard.responseKey{iKey});
     end
     fprintf('\n\n');
 end
 
 
 %% Run demo
 
+try 
+    
 % Create the keyboard queue to collect responses.
-getResponse('init', cfg, expParameters, 1);
+getResponse('init', deviceNumber, cfg);
 
 % Start collecting responses for 5 seconds
 %  Each new key press is added to the queue of events recorded by KbQueue
 startSecs = GetSecs();
-getResponse('start', cfg, expParameters, 1);
+getResponse('start', deviceNumber);
 
 % Here we wait for 5 seconds but are still collecting responses.
 %  So you could still be doing something else (presenting audio and visual stim) and
 %  still collect responses.
 WaitSecs(5);
 
 % Check what keys were pressed (all of them)
-responseEvents = getResponse('check', cfg, expParameters, 0);
-
-% The following line would only return key presses and not releases
-% responseEvents = getResponse('check', cfg, expParameters, 1);
+% If the escapeKey was pressed at any time, it will only abort when you
+% getResponse('check')
+responseEvents = getResponse('check', deviceNumber, cfg, getOnlyPress);
 
 % This can be used to flush the queue: empty all events that are still present in the queue
-getResponse('flush', cfg, expParameters, 1);
+getResponse('flush', deviceNumber);
+
+% If you wan to stop listening to key presses. You could start listening again
+% later by calling: getResponse('start', deviceNumber)
+getResponse('stop', deviceNumber);
 
-% If you wan to stop listening to key presses.
-getResponse('stop', cfg, expParameters, 1);
+% If you wan to destroyt the queue: you would have to initialize it again
+getResponse('release', deviceNumber);
 
 
 %% Now we look what keys were pressed and when
@@ -106,9 +106,29 @@
         eventType = 'released';
     end
 
-    fprintf('\n%s was %s at time %.3f seconds\n', ...
+    fprintf('\n %s was %s at time %.3f seconds\n', ...
         responseEvents(iEvent).key_name, ...
         eventType, ...
         responseEvents(iEvent).onset - startSecs);
 
 end
+
+
+catch ME
+    
+    getResponse('release', deviceNumber)
+    
+    switch ME.identifier
+        
+        case 'getResponse:abortRequested'
+            warning('You pressed the escape key: will try to fail gracefully.')
+            
+            fprintf('\nWe did catch your abort signal.\n')
+
+        otherwise
+            rethrow(ME) % display other errors
+            
+    end
+end
+
+

errorAbortGetReponse.m

@@ -0,0 +1,7 @@
+function errorAbortGetReponse
+    
+    errorStruct.message = 'Escape key press detected by getResponse: aborting experiment.';
+    errorStruct.identifier = 'getResponse:abortRequested';
+
+    error(errorStruct)
+end

errorRestrictedKeysGetReponse.m

@@ -0,0 +1,7 @@
+function errorRestrictedKeysGetReponse
+    
+    errorStruct.message = 'getResponse reported a key press on a restricted key';
+    errorStruct.identifier = 'getResponse:restrictedKey';
+    
+    error(errorStruct)
+end

tests/getResponseTest.m

@@ -0,0 +1,81 @@
+addpath(fullfile(pwd, '..'))
+
+clear;
+clc;
+
+if IsOctave
+    more off % for a better display experience
+end
+
+cfg = setDefaultsPTB;
+
+%% Set parameters
+
+% Decide which device you want to collect responses from
+deviceNumber = []; % default device (PTB will find it for you)
+
+cfg.keyboard.responseKey = {'a', 'b'};
+cfg.keyboard.responseKey{end+1} = cfg.keyboard.escapeKey;
+
+
+%% Final checks
+
+getOnlyPress = 1;
+
+% Make sure keyboard mapping is the same on all supported operating systems
+KbName('UnifyKeyNames');
+
+fprintf('\nDuring the next 5 seconds we will collect responses on the following keys: \n\n');
+if isempty(cfg.keyboard.responseKey)
+    fprintf('\nALL KEYS\n\n');
+else
+    for iKey=1:numel(cfg.keyboard.responseKey)
+        fprintf('\n%s', cfg.keyboard.responseKey{iKey});
+    end
+    fprintf('\n\n');
+end
+
+
+%% Run manual test
+try
+    
+    getResponse('init', deviceNumber, cfg);
+    
+    getResponse('start', deviceNumber);
+    
+    WaitSecs(5);
+    
+    responseEvents = getResponse('check', deviceNumber, cfg, getOnlyPress);
+    
+    getResponse('release', deviceNumber);
+    
+    
+    %if some keys were pressed and that we are supposed to listen to only some
+    %keys, we make sure that only those keys were listened to
+    
+    if ~isempty(cfg.keyboard.responseKey) && isfield(responseEvents, 'keyName')
+        
+        for iEvent = 1:size(responseEvents, 1)
+            fprintf(' %s was pressed\n ', ...
+                responseEvents(iEvent).keyName);
+            
+            if ~any(strcmp({responseEvents(iEvent).keyName}, cfg.keyboard.responseKey))
+                errorRestrictedKeysGetReponse();
+            end
+        end
+        
+    end
+    
+catch ME
+    
+    switch ME.identifier
+        case 'getResponse:restrictedKey'
+            rethrow(ME)
+            
+        otherwise
+            getResponse('release', deviceNumber);
+            
+            rethrow(ME)
+    end
+    
+end