function KbQueueCreate(deviceNumber, keyList, numValuators, numSlots, flags, win) % KbQueueCreate([deviceNumber][, keyList][, numValuators=0][, numSlots=10000][, flags=0][, windowHandle=0]) % % The routines KbQueueCreate, KbQueueStart, KbQueueStop, KbQueueCheck % KbQueueWait, KbQueueFlush and KbQueueRelease provide replacements for % KbCheck and KbWait, providing the following advantages: % % 1) Brief key presses that would be missed by KbCheck or KbWait % are reliably detected % 2) The times of key presses are recorded more accurately % 3) The times of key releases are also recorded % % Limitations: % % 1) If a key is pressed multiple times before KbQueueCheck is called, % only the times of the first and last presses and releases of that % key can be recovered (this has no effect on other keys) % 2) If many keys are pressed very quickly in succession on OSX, it is % at least theoretically possible for the queue to fill more quickly % than it can be emptied, losing key events temporarily while filled % to capacity. The queue holds up to thirty events, and events are % constantly being removed from the queue and processed, so this is % unlikely to be a problem in actual use. % % The deviceNumber of a HID input device can be specified as 'deviceNumber'. % Allowable devices are "keyboard like" devices, e.g., Keyboards, Keypads, % Mouse, Joystick, Gamepad, Touchpad, etc. - Stuff that has buttons or keys % to press. This way a mouse or joysticks buttons can be used as response % devices, ignoring mouse movements etc. If deviceNumber is not specified, the first % device is the default (like KbCheck). If KbQueueCreate has not been called % first, the other routines will generate an error message. Likewise, if % KbQueueRelease has been called more recently than KbQueueCreate, the other % routines will generate error messages. % % It is acceptable to call KbQueueCreate at any time (e.g., to switch to a new % device or to change the list of queued keys) without calling KbQueueRelease. % % KbQueueCreate([deviceNumber][, keyList][, numValuators=0][, numSlots=10000][, flags=0][, windowHandle=0]) % Creates the queue for the specified (or default) device number % If the device number is less than zero, the default device is used. % % 'keyList' is an optional 256-length vector of doubles (not logicals) % with each element corresponding to a particular key (use KbName % to map between keys and their positions). If the double value % corresponding to a particular key is zero, events for that key % are not added to the queue and will not be reported. % % 'numValuators' is an optional maximum number of additional values to report. % It defaults to zero. For values greater than zero, if the selected type % of input device supports this, and if the operating system supports this, % additional info will be recorded. For pointing devices like mice, the mouse % position may be reported, for joysticks the state of their various axis, etc. % For mouse/joystick/pointing device position reporting numValuators must be % at least 2. On touch devices, a value of 2 treats them like a mouse, a value % >= 4 treats them as touchscreen. However, for touch devices there are separate % functions like TouchQueueCreate, TouchEventGet etc. for convenient handling. % See "help KbEventGet" for how to retrieve potential additionally recorded % information. % % 'numSlots' defines how many events the event buffer can store. If a script % does not periodically remove events via KbEventGet() or KbEventFlush(), the % buffer will fill up, and once 'numSlots' elements are stored, it will stop % recording new events. 10000 elements capacity is the default, which may be % too little if you use 'numValuators' > 0 to store dynamic (motion) data like % mouse movements or touchscreen input, which can be generated at rates of % multiple hundred events per second of data collection. % % 'flags' defines special modes of operation for the queue. These are OS % specific, see "PsychHID KbQueueCreate?" for an up to date list of supported % flags. In general, you don't need these. % % 'windowHandle' defines the optional onscreen window handle of an associated % onscreen window. By default, input is taken for all windows and screens. % This argument is silently ignored on systems other than Linux/X11 at the moment. % % No events are delivered to the queue until KbQueueStart or % KbQueueWait is called. % KbQueueCreate can be called again at any time. The function can also % treat other HID devices with buttons or keys as if they are % keyboards. E.g., it can also record button state of a mouse, a % joystick or a gamepad. % % KbQueueStart([deviceNumber]) % Starts delivering keyboard events from the specified device to the % queue. % % KbQueueStop([deviceNumber]) % Stops delivery of new keyboard events from the specified device to % the queue. % Data regarding events already queued is not cleared and can be % recovered by KbQueueCheck % % [pressed, firstPress, firstRelease, lastPress, lastRelease]= % KbQueueCheck([deviceNumber]) % Obtains data about keypresses on the specified device since the % most recent call to this routine, KbQueueStart, KbQueueWait % Clears all scored events, but unscored events that are still being % processed may remain in the queue % % pressed: a boolean indicating whether a key has been pressed % % firstPress: an array indicating the time that each key was first % pressed since the most recent call to KbQueueCheck or KbQueueStart % % firstRelease: an array indicating the time that each key was first % released since the most recent call to KbQueueCheck or KbQueueStart % % lastPress: an array indicating the most recent time that each key was % pressed since the most recent call to KbQueueCheck or KbQueueStart % % lastRelease: an array indicating the most recent time that each key % was released since the most recent call to KbQueueCheck or % KbQueueStart % % For firstPress, firstRelease, lastPress and lastRelease, a time value % of zero indicates that no event for the corresponding key was % detected since the most recent call to KbQueueCheck or KbQueueStart % % To identify specific keys, use KbName (e.g., KbName(firstPress)) to % generate a list of the keys for which the events occurred % % For compatibility with KbCheck, any key codes stored in % ptb_kbcheck_disabledKeys (see "help DisableKeysForKbCheck"), will % not cause pressed to return as true and will be zeroed out in the % returned arrays. However, a better alternative is to specify a % keyList argument to KbQueueCreate. % % secs=KbQueueWait([deviceNumber]) % Waits for any key to be pressed and returns the time of the press. % % KbQueueFlush should be called immediately prior to this function % (unless the queue has just been created and started) to clear any % prior events. % % Note that this command will not respond to any keys that were % inactivated by using the keyList argument to KbQueueCreate. % % Since KbQueueWait is implemented as a looping call to % KbQueueCheck, it will not respond to any key codes stored in % the global variable ptb_kbcheck_disabledKeys % (see "help DisableKeysForKbCheck") % % KbQueueFlush([deviceNumber]) % Removes all unprocessed events from the queue and zeros out any % already scored events. % % KbQueueRelease([deviceNumber]) % Releases queue-associated resources; once called, KbQueueCreate % must be invoked before using any of the other routines % % This routine is called automatically at clean-up (e.g., when % 'clear mex' is invoked and can be omitted expense of keeping % memory allocated and an additional thread running unnecessarily % % Note that any keyboard typing used to invoke KbQueue commands will be % recorded. This would include the release of the carriage return used % to execute KbQueueStart and the keys pressed and released to invoke % KbQueueCheck % _________________________________________________________________________ % % See also: KbQueueCreate, KbQueueStart, KbQueueStop, KbQueueCheck, % KbQueueWait, KbQueueFlush, KbQueueRelease % 8/19/07 rpw Wrote it. % 8/23/07 rpw Modifications to add KbQueueFlush persistent macosxrecent; if nargin < 1 deviceNumber = []; end % Try to reserve keyboard queue for 'deviceNumber' for our exclusive use: if ~KbQueueReserve(1, 2, deviceNumber) if isempty(deviceNumber) deviceNumber = NaN; end error('Keyboard queue for device %i already in use by GetChar() et al. Use of GetChar/CharAvail/FlushEvents and keyboard queues is mutually exclusive!', deviceNumber); end if isempty(macosxrecent) macosxrecent = IsOSX; LoadPsychHID; end if nargin >= 6 if ~isempty(win) % Onscreen window handle given. Validate and map to windowing system handle: if Screen('WindowKind', win) == 1 % Onscreen window handle of open onscreen window: Map to winsys handle: winfo = Screen('GetWindowInfo', win); win = winfo.SysWindowHandle; elseif ismember(win, Screen('Screens')) % screenid given: Pass in as X-Screen id + 1: win = uint64(win + 1); end end end if nargin == 6 PsychHID('KbQueueCreate', deviceNumber, keyList, numValuators, numSlots, flags, win); elseif nargin == 5 PsychHID('KbQueueCreate', deviceNumber, keyList, numValuators, numSlots, flags); elseif nargin == 4 PsychHID('KbQueueCreate', deviceNumber, keyList, numValuators, numSlots); elseif nargin == 3 PsychHID('KbQueueCreate', deviceNumber, keyList, numValuators); elseif nargin == 2 PsychHID('KbQueueCreate', deviceNumber, keyList); elseif nargin == 1 PsychHID('KbQueueCreate', deviceNumber); elseif nargin == 0 PsychHID('KbQueueCreate'); elseif nargin > 4 error('Too many arguments supplied to KbQueueCreate'); end