Merge pull request #27 from Remi-Gau/remi-REF_getResponses

Refactor getResponses

Author: Remi-Gau

.gitignore

@@ -6,3 +6,4 @@
 # exclude content of logfiles folders
 *.tsv
 *.mat
+check_my_code_report.txt

.travis.yml

@@ -0,0 +1,25 @@
+# Travis CI (https://travis-ci.org/)
+
+language: c
+dist: bionic
+cache:
+  apt: true # only works with Pro version
+
+env:
+  global:
+    - OCTFLAGS="--no-gui --no-window-system --silent"
+
+before_install:
+  - travis_retry sudo apt-get -y -qq update
+  - travis_retry sudo apt-get -y install octave
+  - travis_retry sudo apt-get -y install liboctave-dev
+
+install:
+  - octave $OCTFLAGS --eval "addpath (pwd); savepath ();"
+
+before_script:
+  # Change current directory
+  - cd tests
+
+script:
+  - octave $OCTFLAGS --eval "results = runtests; assert(all(~[results.Failed]))"

CPP_getResponseDemo.m

@@ -70,6 +70,30 @@ You can then use the [matlab package manager](https://github.com/mobeets/mpm), t
   end
 ```
 
+## Setting up keyboards
+
+To select a specific keyboard to be used by the experimenter or the participant, you need to know
+the value assigned by PTB to each keyboard device.
+
+To know this copy-paste this on the command window:
+
+``` matlab
+[keyboardNumbers, keyboardNames] = GetKeyboardIndices;
+
+disp(keyboardNumbers);
+disp(keyboardNames);
+```
+
+You can then assign a specific device number to the main keyboard or the response box in the `cfg` structure
+
+-   `cfg.keyboard.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.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.
+
+`cfg.keyboard.responseBox` and `cfg.keyboard.keyboard` can be different or the same.
+
+Using empty vectors (ie `[]`) or a negative value for those means that you will let PTB find and use the default device.
 
 ## Structure and function details
 
@@ -106,23 +130,27 @@ It is wrapper function to use `KbQueue` which is definitely what you should used
 
 You can easily collect responses while running some other code at the same time.
 
-It will only take responses from the `response box` which can simply be the "main keyboard" or
-another keyboard connected to the computer or the response box that the participant is using.
+It will only take responses from one device which can simply be the "main keyboard" 
+(the default device that PTB will find) or another keyboard connected to the computer 
+or the response box that the participant is using.
 
 You can use it in a way so that it only takes responses from certain keys and ignore others (like
 the triggers from an MRI scanner).
 
 If you want to know more on how to use it check its help section and the `CPP_getResponseDemo.m`.
 
-To select a specific keyboard to be used by the experimenter or the participant, you need to know
-the value assigned by PTB to each keyboard device.
+In brief, there are several actions you can execute with this function.
 
-To know this copy-paste this on the command window:
+-   init: initialize the buffer for key presses on a given device (you can also specify the keys of interest that should be listened to).
+-   start: start listening to the key presses (carefully insert into your script - where do you want to start buffering the responses).
+-   check: till that point, it will check the buffer for all key presses. 
+    -   It only reports presses on the keys of interest mentioned at initialization.
+    -   It **can** also check for presses on the escape key and abort if the escape key is part of the keys of interest.
+-   flush: Empties the buffer of key presses in case you want to discard any previous key presses.
+-   stop: Stops buffering key presses. You can still restart by calling "start" again.
+-   release: Closes the buffer for good.
 
-    [keyboardNumbers, keyboardNames] = GetKeyboardIndices;
 
-    keyboardNumbers
-    keyboardNames
 
 ### deg2Pix
 

README.md

@@ -0,0 +1,36 @@
+function checkAbort(cfg, deviceNumber)
+% Check for experiment abortion from operator
+% When no deviceNumber is set then it will check the default device
+% When an abort key s detected this will set a global variable and throw a
+% specific error that can then be catched.
+%
+% Maint script
+% try
+%     % Your awesome experiment
+% catch ME % when something goes wrong
+%     switch ME.identifier
+%         case 'checkAbort:abortRequested'
+%             % stuff to do when an abort is requested (save data...)
+%         otherwise
+%             % stuff to do otherwise
+%             rethrow(ME) % display the error
+%     end
+% end
+
+if nargin < 1 || isempty(cfg)
+    error('I need at least one input.')
+end
+
+if nargin < 2 || isempty(deviceNumber)
+    deviceNumber = -1;
+end
+
+[keyIsDown, ~, keyCode] = KbCheck(deviceNumber);
+
+if keyIsDown && keyCode(KbName(cfg.keyboard.escapeKey))
+    
+    errorAbort();
+    
+end
+
+end

checkAbort.m

@@ -0,0 +1,31 @@
+% add parent directory to the path (to make sure we can access the CPP_PTB
+% functions)
+addpath(fullfile(pwd, '..')) 
+
+% set up
+cfg.keyboard.escapeKey = 'ESCAPE';
+
+% beginning of demo
+KbName('UnifyKeyNames');
+
+
+try
+
+    % stay in the loop until the escape key is pressed
+    while GetSecs < Inf
+
+        checkAbort(cfg)
+
+    end
+
+catch ME
+    
+    switch ME.identifier
+        case 'checkAbort: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