Detailed Description

touch screens (wraps all the PTB TouchQueue* functions), and also provides touch area management methods.

TOUCHMANAGER – call this and setup with screen manager, then run your task. This class can handles touch windows (circular or rectangular), exclusion zones and more for multiple touch screens.

Inheritance diagram for touchManager:

Public Member Functions
function	touchManager (in varargin)
	Class constructor.

function	setup (in me, in sM)

function	createQueue (in me)

function	start (in me)

function	stop (in me)

function	close (in me, in choice)

function	flush (in me)

function	syncTime (in me, in timestamp)

function	eventAvail (in me)

function	resetWindow (in me, in N)

function	updateWindow (in me, in X, in Y, in radius, in doNegation, in negationBuffer, in strict, in init, in hold, in release)

function	reset (in me, in softReset)

function	getEvent (in me)
	getEvent gets and processes the latest event(s) from the touch queue @detailed get event(s) from the touch queue and process them to update the state of the touchManager object. This is the main function for getting touch events and should be called in your main loop to update the state of the touchManager. It handles both real touch events and dummy mouse events, and updates the properties of the touchManager accordingly.

function	isTouch (in me, in getEvt)

function	checkTouchWindows (in me, in windows, in getEvt)

function	isHold (in me)

function	testHold (in me, in yesString, in noString)

function	testHoldRelease (in me, in yesString, in noString)

function	demo (in me, in nTrials, in useaudio, in holdTime, in releaseTime)

function	testEvents (in me)

function	displayInfo (in me)

Public Member Functions inherited from optickaCore
function	optickaCore (in varargin)
	Class constructor.

function get	fullName (in me)

function	getALF (in me, in subject, in lab, in create)
	get the ALF path

function	makeReport (in me, in rpt)
	Generate a detailed report for the opticka object.

function	findAttributes (in me, in attrName, in attrValue)

function	findAttributesandType (in me, in attrName, in attrValue, in type)
	find properties of object with specific attributes, for example all properties whose GetAcccess attribute is public and type is logical.

function	findPropertyDefault (in me, in propName)
	Return the declared default value for a class property.

function	clone (in me)
	Use this syntax to make a deep copy of the object, i.e. OBJ_OUT has the same field values, but will not behave as a handle-copy of me anymore.

function	checkSuperclasses (in List)

function	editProperties (in me, in properties)
	method to modify a set of properties

function	setProp (in me, in property, in value)
	method to fast change a particular value. This is useful for use in anonymous functions, like in the state machine.

function	initialiseSaveFile (in me, in varargin)
	just get date fragment for backwards compatibility

function	checkPaths (in me)
	checks the paths are valid

Static Public Member Functions
static function	enableTouchDevice (in deviceName, in enable)

Static Public Member Functions inherited from optickaCore
static function	initialiseGlobals (in doReset, in doOpen)

static function	makeArgs (in args)
	Converts cell args to structure array.

static function	addDefaults (in args, in defs)
	regularises and adds default options to arg input

static function	hasKey (in in, in key)
	check if a struct / object has a propery / field

static function	getKeys (in device)
	PTB Get key presses, stops key bouncing.

Public Attributes
Property	device
	which touch device to connect to?

Property	deviceName

Property	isDummy
	use the mouse instead of the touch screen for debugging

Property	window
	window is a touch window - see windowTemplate below for the exact struct

Property	exclusionZone

Property	drainEvents

Property	trackID
	there can be up to 10 touch events, do we check if the touch ID matches?

Property	mainID

Property	panelType
	panel type, 1 = "front", 2 = "back" (reverses X position)

Property	verbose

Property	nSlots
	number of slots for touch events

Property	silentMode
	functions return immediately, useful for mocking

Public Attributes inherited from optickaCore
Property	name
	object name

Property	comment
	comment

Property	verbose
	verbose logging, subclasses must assign this. This is normally logical true/false

Property	optickaVersion
	version number

Property	dateStamp
	clock() dateStamp set on construction

Property	uuid
	universal ID

Property	paths
	storage of various paths

Property	fullName
	The fullName is the object name combined with its uuid and class name.

Protected Member Functions
function	getAvailableEvents (in me)

function	calculateWindow (in me, in x, in y, in tempWindow, in isLast)

Protected Member Functions inherited from optickaCore
function	parseArgs (in me, in args, in allowedProperties)
	Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties.

function	addArgs (in me, in args)

function	setPaths (in me)
	Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties.

function	getFonts (in me)
	set paths for object

function	toStructure (in me)
	Converts properties to a structure.

function	getType (in me, in in)

function	logOutput (in me, in in, in message, in override)
	Give a metaproperty return the likely property class.

function	salutation (in me, in varargin)
	Prints messages dependent on verbosity.

Additional Inherited Members
Protected Attributes inherited from optickaCore
Property	cloning
	are we cloning this from another object

Property	mversion
	Matlab version number, this is transient so it is not saved.

Property	sansFont
	sans font

Property	monoFont
	monoFont

Property	className
	class name

Property	savePrefix
	save prefix generated from clock time

Property	fullName_
	cached full name

Constructor & Destructor Documentation

◆ touchManager()

touchManager::touchManager ( in varargin )

Class constructor.

Initialises the class sending any parameters to parseArgs.

Parameters

varargin are passed as a structure of properties which is parsed.

Returns: instance of the class.

Member Function Documentation

◆ calculateWindow()

touchManager::calculateWindow	(	in	me,
		in	x,
		in	y,
		in	tempWindow,
		in	isLast
	)

protected

Parameters

return

◆ checkTouchWindows()

function touchManager::checkTouchWindows	(	in	me,
		in	windows,
		in	getEvt
	)

◆ close()

touchManager::close	(	in	me,
		in	choice
	)

Parameters

choice which touch device to use, default uses me.device

Returns

◆ createQueue()

touchManager::createQueue ( in me )

Parameters

choice which touch device to use, default uses me.device

Returns

◆ demo()

touchManager::demo	(	in	me,
		in	nTrials,
		in	useaudio,
		in	holdTime,
		in	releaseTime
	)

Parameters

return

◆ displayInfo()

function touchManager::displayInfo ( in me )

◆ enableTouchDevice()

static function touchManager::enableTouchDevice	(	in	deviceName,
		in	enable
	)

static

◆ eventAvail()

touchManager::eventAvail ( in me )

Parameters

return navail number of available events

◆ flush()

touchManager::flush ( in me )

Parameters

return n number of flushed events

◆ getAvailableEvents()

touchManager::getAvailableEvents ( in me )

protected

On linux we can use xinput to list and enable/disable touch interfaces, here we try to make the named touch interface enabled or disabled.

Parameters

return evt

Returns: n

◆ getEvent()

evt touchManager::getEvent ( in me )

getEvent gets and processes the latest event(s) from the touch queue @detailed get event(s) from the touch queue and process them to update the state of the touchManager object. This is the main function for getting touch events and should be called in your main loop to update the state of the touchManager. It handles both real touch events and dummy mouse events, and updates the properties of the touchManager accordingly.

Parameters

me	– touchManager object

Returns: evt – the last event from the touch screen

◆ isHold()

touchManager::isHold ( in me )

This is the main function which runs touch timers and calculates the logic of whether the touch is in a region and for how long. Use me.window to set the parameters for the hold, for example: me.window(1).X = 0; me.window(1).Y = 0; me.window(1).radius = 2;

Returns: held logical/double indicating if touch is currently in window (-100 = negation); heldtime logical indicating if hold duration requirement met; release logical indicating if release condition satisfied; releasing logical indicating if currently in release phase; searching logical indicating if still searching for touch initiation; failed logical indicating if touch attempt failed; touch logical indicating if touch event was detected, whether in window or not; negation was a negation touch event detected?

◆ isTouch()

touchManager::isTouch	(	in	me,
		in	getEvt
	)

Simply checks for touch event irrespective of position / time etc.

Parameters

getEvt – do we force a getEvent() or use the last valid event?

Returns: touch – logical for if there is a touch event

◆ reset()

touchManager::reset	(	in	me,
		in	softReset
	)

Parameters

softReset – soft reset = keep lastPressed and event flags (reason: because touch screen has no state and subject holding a touch screen without moving is the same as no touch, a soft reset keeps the last event state but resets other properties)

◆ resetWindow()

function touchManager::resetWindow	(	in	me,
		in	N
	)

◆ setup()

touchManager::setup	(	in	me,
		in	sM
	)

Parameters

sM	screenManager to use

Returns

◆ start()

touchManager::start ( in me )

Returns

◆ stop()

touchManager::stop ( in me )

Returns

◆ syncTime()

touchManager::syncTime	(	in	me,
		in	timestamp
	)

time. We can use this function to set the 0 time, for example stimulus onset etc. which can be used for evt.Time and tAll data.

Parameters

timestamp [optional] time to set the queue time to, default is GetSecs

◆ testEvents()

function touchManager::testEvents ( in me )

◆ testHold()

touchManager::testHold	(	in	me,
		in	yesString,
		in	noString
	)

Parameters

return

◆ testHoldRelease()

touchManager::testHoldRelease	(	in	me,
		in	yesString,
		in	noString
	)

Parameters

return

◆ updateWindow()

function touchManager::updateWindow	(	in	me,
		in	X,
		in	Y,
		in	radius,
		in	doNegation,
		in	negationBuffer,
		in	strict,
		in	init,
		in	hold,
		in	release
	)

Member Data Documentation

◆ device

Property touchManager::device

which touch device to connect to?

NOTE: touch interfaces do NOT keep state, so if you touch but do not move your finger then there are no events, so touchManager ensures that the state is handled for you. The touch queue is also asynchronous to the main PTB task and so must be handled specifically. The default here is to drop all but the latest event (drainEvent = true), when false all events are processed which may take more time. Touchscreens can also cause unwanted OS/UI events, especially before/after the task runs (a subject can press buttons, enter text etc.), so on Linux we also enable / disable the touch screen at the OS level when deviceName is passed to try to mitigate this problem.

This class uses the TouchQueue* functions from Psychtoolbox, see: https://psychtoolbox.org/docs/TouchQueue for more details.

◆ deviceName

Property touchManager::deviceName

touch device name, useful to enable it at the OS level before PTB searches for the touch device

◆ drainEvents

Property touchManager::drainEvents

drain the events to only get the latest? This ensures lots of events don't pile up if you only want the current event, but potentially causes lost state from missed events. If enabled you may miss specific events like a NEW touch so ensure this works with your paradigm!!!

◆ exclusionZone

Property touchManager::exclusionZone

Use exclusion zones where no touch allowed: [left,top,right,bottom] Add rows to generate multiple exclusion zones. These are checked before the touch windows are.

◆ isDummy

Property touchManager::isDummy

use the mouse instead of the touch screen for debugging

◆ mainID

Property touchManager::mainID

which id to track as the main one (1 = first event). Note this is different from the event keycode, which increments with each event, this is the order of the touch event

◆ nSlots

Property touchManager::nSlots

number of slots for touch events

◆ panelType

Property touchManager::panelType

panel type, 1 = "front", 2 = "back" (reverses X position)

◆ silentMode

Property touchManager::silentMode

functions return immediately, useful for mocking

◆ trackID

Property touchManager::trackID

there can be up to 10 touch events, do we check if the touch ID matches?

◆ verbose

Property touchManager::verbose

verbose, log more info to command window useful for debugging.

◆ window

Property touchManager::window

window is a touch window - see windowTemplate below for the exact struct

X: X position for the centre of the tocuh window in degrees on screen Y: Y position for the centre of the tocuh window in degrees on screen radius: circular when radius is singular, rectangular when radius = [width height]) init: timer that tests time window allowed to first touch hold: timer that determines how long to hold release: timer to determine the time after hold in which window should be released If release is NaN, release timing checks are disabled and a successful hold is accepted without requiring a release. doNegation: return -100 (fail) if deliberate touch is OUTSIDE window when using the testHold etc functions. negationBuffer: is an area around the window to allow some margin of error for negation... strict: enforce strict rules for hold within the window

The documentation for this class was generated from the following file:

communication/touchManager.m

Detailed Description

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ touchManager()

Member Function Documentation

◆ calculateWindow()

◆ checkTouchWindows()

◆ close()

◆ createQueue()

◆ demo()

◆ displayInfo()

◆ enableTouchDevice()

◆ eventAvail()

◆ flush()

◆ getAvailableEvents()

◆ getEvent()

◆ isHold()

◆ isTouch()

◆ reset()

◆ resetWindow()

◆ setup()

◆ start()

◆ stop()

◆ syncTime()

◆ testEvents()

◆ testHold()

◆ testHoldRelease()

◆ updateWindow()

Member Data Documentation

◆ device

◆ deviceName

◆ drainEvents

◆ exclusionZone

◆ isDummy

◆ mainID

◆ nSlots

◆ panelType

◆ silentMode

◆ trackID

◆ verbose

◆ window