<vm 1024,768,16,60> <2did "magic touch usb" bottom,0,512,1024,768 left,0,0,.5,1 right,.5,0,1,1> <mpr +right> <mnr +left> <mr +bottom>
One problem used to be devices having cute little symbols as part of the name making it very hard to get the name of a device into an item file. This should be mitigated in version 220.127.116.11 of DMDX, please see the note about this in the input device section.
Built in devices:
There are a few special built in devices for 2D input and these built in devices don't connect to any DirectInput device and instead either get their data from windows messages or other sources.
The first of them is the mouse device that taps into the windows mouse messages and does not need calibration in TimeDX (not that you could calibrate the mouse anyway as it has relative axes and the calibration routines only handle devices with absolute axes). Both left and right clicks generate the same button press. Because the mouse gets it's data from windows messages and those messages can get aggregated timing isn't going to be real accurate but as far as I can tell the whole pointing paradigm is alien to RTs in any event. The mouse also turns the cursor on seeing as it's kinda hard to use a mouse to point at things unless there's a cursor... Turning on DMDX's <MinSleep> option to maximize processing of the mouse system messages may increase RT accuracy of this special device. Also note that the mouse device doesn't work real well with multiple monitor setups unless you're using the Direct3D rendering path. When I wrote the code I assumed no one would ever need that but there you go. The solution when using the classic DirectDraw renderer is to set the video card to clone mode where the two displays are copies of each other. It's also possible setting a clipcursor region (below) in desktop coordinates might enable the mouse to be used on a second display.
The second built in device is the windowstouch device added in version 18.104.22.168 of DMDX. Like the mouse device this device doesn't need calibration in TimeDX instead it is calibrated somewhere in the Windows Control Panel. Like the mouse the windowstouch device gets it's data from windows messages, specifically WM_TOUCH messages, however because it's dealing with isolated touches of the screen I suspect the timing of this device is much better.
The third built in device is the tcpipreply device added in version 22.214.171.124 of DMDX for interfacing with eye trackers. This device does not need calibration in TimeDX as it is presumably calibrated elsewhere in the eye tracker software (or what have you, anything that talks line based ASCII TCP/IP can talk to the tcpipreply device). The 2Did tcpipreply device parses data from a TCP/IP reply setup with the <InputDevice> parameter and is thus unique needing both an <id> parameter and a <2Did> one. The tcpipreply device has to be told the names of the fields that contain the data it uses so it must be followed by three strings as in tcpipreply,xfieldname,yfieldname,validstring. The data in the first two fields are the x coordinate and the y coordinate from the eye tracker and can be real values between zero and one in which case they're multiplied by the relevant dimension of the screen. In addition the device needs a particular validation string, validstring, to be present before the other fields can be considered valid and similar to the strings the <send> keyword sends it can contain '' for double quotes and ., for a semicolon. If your device device doesn't contain a particular validation string per se pick some string that will always be present, it can be a single character. See the <expireif> keyword help for an example of the tcpipreply device in use, typical use of tcpipreply for a Gazepoint eye tracker might be tcpipreply,BPOGX,BPOGY,BPOGV=''1'' (so the BPOGV field is zero when the data isn't valid).
options initiate data logging with each clockon, the original datalogging
being a time based log and the new clicklogging
(added in DMDX 126.96.36.199)
being a log entry with every click and
(also added in 188.8.131.52)
logging coordinates relative to the upper left corner of the button clicked (as
opposed to the other two which are relative to the top left corner of the
display). Only one of the three data logging options can be active at once
and datalogging must be followed by two
and relativeclicklogging by one. Firstly all three
are followed by the maximum number of data points that could be
gathered (not all points may be gathered in a trial, data logging terminates
when a response is registered) and datalogging
must have a second parameter, it being the period between each data point
gathered in milliseconds. Data logged are the coordinates that device
presented at that time and when using datalogging not all devices provide a continuous data stream, a
lot of them only report movement information so if the device isn't being moved
you won't see any data points. When using one of the click logging options
only clicks that occur in button regions are logged (regardless of what DMDX
does with the generated signals). See the
Bitmap notes for demo of relativeclicklogging. Data is dumped at the end of each item
on a single line in the output file in triplets of time,x,y and if you're using
input device the times can be little wild as Windows delivers mouse movement
information at it's leisure.
The last data point in any logging in an item is also saved in the macros .dataloggingx. and .dataloggingy. (as of DMDX 184.108.40.206) opening up a whole new range of things one can do with DMDX as repositioning display elements by subjects is now in play -- although having just had a play around with it myself I needed <cco> to catch clicks between items however <cco> neuters data logging so if someone ever actually needs this I suspect modifications to DMDX will be in order. As it stands having DMDX rearrange display elements is still doable, you just can't have the elements follow the cursor around the screen, you'd have to click on one once to nominate it for moving, then move the cursor to the new location and then a click to deposit the element there, see the demo below.
The normalizedata option (added in DMDX 220.127.116.11) normalizes all data logged (so range 0 to 1), very handy when your item file will run on a number of different displays (not that you couldn't post hoc scale the data by the display resolution as it's emitted in the data file but this is muuuch easier). For relativeclicklogging that normalized range is the button's dimensions, otherwise it's the whole display's dimensions. normalizedata also affects the macros .dataloggingx. and .dataloggingy. so instead of being pixel integers they become real values with six significant digits (so 0.123456 for instance).
The noclick option checks all data points received against the button regions so no clicking of buttons is needed. Not all devices provide a continuous data stream so not all 2D devices can be used with noclick.
The checkoverlapping option forces the routines that check coordinates from some device being within a given button's region to check all regions regardless of whether a match is found or not. Normally DMDX stops once a match is found regardless of whether that region is mapped as a response or not. Turning checkoverlapping on allows you to have multiple overlapping regions and select which one is active with the usual <mpr>, <mnr> etc. keywords instead of having to have lots of non overlapping regions and combining signals out of them (which was a pain, believe me).
The cursoroff and cursoron options override the default windows cursor display state for that device. Eg, if you are using the mouse device you'll need cursoroff if you don't want a cursor and you'll need cursoron for all other devices (to date anyway) if you want to see the cursor. Note options that affect the cursor only work with devices that have drivers that affect the cursor. This means things like touch screens and mice, joysticks won't affect the cursor (see Joysticks below). If you need to change the cursor state while the job is running (ie after <2Did> has been given) because you're doing a multimodal task or want to indicate that an input isn't appropriate then the cursoroff and cursoron options are exposed in <mip> as well.
The clipcursor option confines the cursor to given region of the screen when using the mouse 2Dinputdevice (read: no joystick support, see Joysticks below). clipcursor must be followed by four coordinates in the same way as a button definition (see above).. If you need to change the region as the job is running then the clipcursor option is exposed in <mip> as well. Aside from uses I haven't thought of this allows continuous ratings to be made of video and logged with the datalogging option when the region provided to clip the cursor to is one pixel high and the width of the screen as the following item file demonstrates (a similar file dvRatingsDialdemo.rtf can be found in the digital video demo):
<ep> <cr> <dfm 0.55>
s3 <vm 800,600,16,60> <nfb> <2did mouse datalogging,50,50 clipcursor,0, 525, 800, 526>
$ 0 @-3 "The instructions", @-2 "across", @-1 "multiple", "lines" <branch 99>
mB+@14"0 1 2 3 4 5 6 7 8",
@15" not at all/ somewhat/ extremely/",@16" none some a great deal"+;
+100 * <d 300> <t 4000> <dv -1,.1,.75,.75> "happy/429-53_l.mpg" <dv% 0> / ~B;
+101 * <d 300> <t 4000> <dv -1,.1,.75,.75> "neutral/485-31_l.mpg" <dv% 0> / ~B;
+102 * <d 300> <t 4000> <dv -1,.1,.75,.75> "sad/331-79_l.mpg" <dv% 0> / ~B;
$ 0 "Done"; $
A more complicated use of the clipcursor option entails having the subject move the mouse back to the center of the screen between each rating (utilizing noclick so just positioning the cursor is enough). Although joysticks can now do better job of this, see Joysticks below. Note that <id keyboard> is no longer used as the request is provided by moving the mouse back to the center of the screen:
<ep> <cr> <dfm 0.55>
s3 g2 <vm 800,600,16,60> <nfb> <2did mouse datalogging,50,50 noclick clipcursor,0,525,800,526 center,395,520,405,530> <mr +center>
$ 0 @-3 "The instructions", @-2 "this time", @-1 "the cursor", "needs to be centered" , @16 "Continue" <branch 99>
mB+@14"0 1 2 3 4 5 6 7 8",
@15" not at all/ somewhat/ extremely/",@16" none some a great deal"+;
This is the word rearranging task from above that uses clicklogging along with the .dataloggingx. and .dataloggingy. macros. After setting up the initial positions of the words and a counter to remember what was clicked on last we display them in item 10 and store the coordinates they were displayed at with <sc> so that in item 20 we can set the word1 and word2 button RECTs with <sbr> allowing us to pick up clicks on them or the background (we've carefully arranged our 2Did buttons so the words will be checked first and only if they're not clicked on will we generate a signal for the rest of the screen being clicked on (with the nothing button) allowing us to detect where the previously selected word should be dropped). Also in item 20 we have a <mwb> multi-way branch that splits execution based on what was clicked, if it was one of the words we remember it in our counter, if not we do an indexed branch with <ib> in item 300 that will cunningly not do anything if a word hadn't been selected already in item 400 otherwise in items 401 or 402 we set the coordinate macros of whatever word was selected to the last data logging location in the .dataloggingx. and .dataloggingy. macros and loop around to item 10 again (which will update the button RECTs and so on):
<fd 30> <cr> <id #keyboard> <ntl> <d 0> <nfb>
<2Did mouse clicklogging,10
<xyjustification framebyframe> <inst hardmargin>
0 <inst .2,.3,.7> "In ", "this ", "version ", "of ", "the ", "word ", "rearranging ", "task ", "click ", "on ", "a ", "word ", "(once) ", "and ", "then ", "click ", "elsewhere ", "to ", "move ", "it ", "there.";
~1 m.word1x.+.25+ m.word1y.+.5+
m.word1l.+1+ m.word1t.+2+ m.word1r.+3+ m.word1b.+4+
m.word2l.+1+ m.word2t.+2+ m.word2r.+3+ m.word2b.+4+
<mpr +word1> <mpr +word2> <mpr +nothing>
10 "word1" <xyjustification center> <xy ~.word1x.,~.word1y.>
<sc .word1l., .word1t., .word1r., .word1b.>,
"word2" <xyjustification center> <xy ~.word2x.,~.word2y.>
<sc .word2l., .word2t., .word2r., .word2b.>;
+20 <sbr word1, ~.word1l., ~.word1t., ~.word1r., ~.word1b.>
<sbr word2, ~.word2l., ~.word2t., ~.word2r., ~.word2b.> ! *
<mwb +word1,100 +word2,200 +nothing,300 binr,300>;
~100 <set c1=1> <bu -10>;
~200 <set c1=2> <bu -10>;
~300 <set c2=400+c1> <set c1=0> <ib c2>;
~400 <bu -10>;
~401 m.word1x.+~.dataloggingx.+ m.word1y.+~.dataloggingy.+ <bu -10>;
~402 m.word2x.+~.dataloggingx.+ m.word2y.+~.dataloggingy.+ <bu -10>;