[curr_val, sample_bin, quit] = inputFunc_mouse(input_device, last_val, respmap, input_args, trial_bin, sample_bin)
INPUTFUNC_MOUSE is an SPTB input_func used to gather data from the mouse. It gathers information about the current mouse state, but also maintains an internal sketchpad to keep track of the cursor's placement on an "internal" coordinate system. Whether internal or OS-level mouse control, is used, INPUTFUNC_MOUSE makes sure the cursor does not leave the legal mouse region; computes displacement in addition to absolute position; performs zone-checking; and applies arbitary rotation to mouse movement as requested.
INPUTFUNC_MOUSE produces cursor state samples. Each mouse state sample gathered and reported by INPUTFUNC_MOUSE has dimensionality 1x4, corresponding to: [cursor_x_position cursor_y_position left_click_down right_click_down] To use INPUTFUNC_MOUSE, supply standard input_func form of input and output arguments. In particular, use the syntax shown above with arguments: input_device: a cursor device token (e.g., as provided by easyLaunch or getInputDevice). last_val: the recent history or initialization value of INPUTFUNC_MOUSE (must take standard sample dimensionality of [n 4], where n is any number of rows, although only the final row is referenced). respmap: response map as generated by makeMap. For proper zone testing, because cursors operate in 2D space, each row of respmap.input should be a numeric array with the form [min_x min_y max_x max_y]. input_args: the mode in which INPUTFUNC_MOUSE functions is controlled by arguments passed through this cell array. Arguments are as follows: 1: token for the current screen being used. 2: rect defining the current drawing area [min_x min_y max_x max_y] 3: boolean: when true, if the cursor enters a zone defined in the respmap, INPUTFUNC_MOUSE triggers the end of a trial in easyScale. 4: boolean: when true, indicates to let the OS handle the cursor, in which case cursor position is passively sampled; rather than keeping track of an internal cursor position, in which case the cursor is reset to the middle of the screen while displacement values are used. 5: boolean: when set to true, cursor displacement values are reported in curr_val instead of absolute [x y] positions. 6: boolean: when set to true, zone testing is performed using the respmap input; otherwise, this input is ignored. 7: angle in degrees: cursor inputs will be distorted by this amount. For example, if 180 were supplied, the cursor would appear to move opposite to its normal direction. trial_bin: argument ignored sample_bin: As with all input_funcs, the sample bin is a cell array with two elements: an INPUT_BIN in position one, and a INPUTFUNC_MOUSE in position two. It is normally initialized and handled by easyScale, and gets updated by INPUTFUNC_MOUSE each time the function is called. The contents of the INPUT_BIN are unique to INPUTFUNC_MOUSE and are as follows: 1: cursor displacement since the prior INPUTFUNC_MOUSE call. 2: current response zone value as defined by the respmap (and and as reported by zoneScore). 3: current response zone corresponding to this same input.
For example usage of INPUTFUNC_MOUSE, please see demoEasyCursor_draw and / or demoEasyCursor_point.
INPUTFUNC_MOUSE produces the following outputs: curr_val: a size [1 4] vector representing cursor state as above. sample_bin: updated version of the sample_bin supplied as input (above). quit: a boolean that, under some parameterizations, calls for the current trial to end when the user enters a response zone.