purpose: Hide or display the mouse cursor
usage: mglDisplayCursor(<display>)

When you call mglOpen the mouse cursor is hidden by default. You can get it to come back by doing:

mglOpen
mglDisplayCursor

purpose: returns the status of the keyboard (regardless of whether the focus is on the mgl window)
usage: mglGetKeys(<keys>)

usage: mglGetMouse()
purpose: returns the status of the mouse buttons (regardless of whether the focuse is on the mgl window

purpose: returns a key down event waitTicks specifies how long to wait for a key press event in seconds. Note that the timing precision is system-dependent:

• Mac OS X: nanosecond (gets timestamps using a background thread mglListener)
• Linux: 1/HZ s where HZ is the system kernel tick frequency (HZ=100 on older systems, HZ=250 or 500 on more modern systems)

The default wait time is 0, which will return immediately and if no keypress event is found, will return an empty array []. The return structure contains the character (ASCII) code of the pressed key, the system-specific keycode, a keyboard identifier (on Linux, this is the keyboard state, or modifier field), and and the time (in secs) of the key press event. NOTE that to get a key event the focus *MUST* be on the mgl window. For faster timing, try mglGetKeys
usage: mglGetKeyEvent(waitTicks)

mglOpen
mglGetKeyEvent(0.5)

usage: mglGetMouseEvent(waitTicks)
purpose: returns a mouse down event waitTicks specifies how long to wait for a mouse event in seconds. Note that the timing precision is system-dependent:

• Mac OS X: nanosecond (gets timestamp from background thread mglListener)
• Linux: 1/HZ s where HZ is the system kernel tick frequency (HZ=100 on older systems, HZ=250 or 500 on more modern systems)

The default wait time is 0, which will return immediately with the mouse position regardless of button state. The return structure contains the x,y coordinates of the mouse, the button identifier if pressed (on the button-challenged Mac this is always 1) and 0 otherwise, and the time (in secs) of the mouse event. NOTE that the mouse down event has to be *ON* the mgl window for this to work with waitTicks not equal to 0

mglOpen
mglGetMouseEvent(0.5)

Purpose: Returns the keycodes of a (list of) keynames
Usage: keycode=mglCharToKeycode(keyname)

Note on special keys: On Linux (X), special keys and function keys have unique names, e.g., 'Escape', 'F1', etc., so obtaining the keycodes for these is done by mglCharToKeycode({'Escape','F1'}) etc. On Macs, this is not possible; instead, test for the keycode and name of a key using the mglShowKey function.

The keycodes match those used by mglGetKeys and mglGetKeyEvent

Example: testing for specific keypresses:

keycodes=mglCharToKeycode({'1','2' '3'}) % keys 1-3 on main keyboard
while (1); k=mglGetKeys(keycodes); if (any(k)),break;end;end

Technical note: the returned keycodes are identical to system keycodes+1

Purpose: Returns the keynames of a (list of) keycodes
Usage: keyname=mglKeycodeToChar(keycode)

Note on special keys: This repeats the above entry, deleted.

Example: testing which keys were pressed:

while (1); k=mglGetKeys; if (any(k)),break;end;end
keycodes=find(k);
keynames=mglKeycodeToChar(keycodes)

Technical note: keycodes are identical to system keycodes+1

availability: mgl 2.0 Mac OS X only
usage: mglSimulateRun(framePeriod,numFrames,<startDelay>,<char>)
purpose: This function simulates a run (currently only available on Mac) it does this by posting periodic backtick keypresses using mglPostEvent. For example if you want to have 375 backticks occur spaced 1.5 seconds apart:

mglSimulateRun(1.5,375);

Also, you can delay the start of the backticks, by doing

mglSimulateRun(1.5,375,10);

Instead of sending the backtick character, send the character 'a'

           
mglSimulateRun(1.5,375,0,'a');

Note that if you want to stop the keyboard events in the middle, you need to do:

mglPostEvent('quit');

availability: mgl 2.0 Mac OS X only
usage: mglEatKeys(keyCodes)
purpose: Starts eating keypresses (i.e. the sent in keycodes will no longer be sent to the terminal window. This can be useful if you don't want to fill your text buffer with extraneous keyboard backticks and subject responses). keyCodes can also be a char array or the myscreen variable (if the myscreen variable it will eat all keys that initScreen is using for backticks and response keys). Note that if you press any key that is not being eaten, then key eating will stop. Usually, you do not need to call this function directly, but you have initScreen call it, by setting eatKeys in mglEditScreenParams.

availability: mgl 2.0 Mac OS X only
usage: mglListener('init')
purpose: Starts a background thread that monitors keyboard and mouse events. What this does is it uses event taps to record keyboard and mouse events. Event taps are a fairly low-level systems call in Mac OS X which is used by assistive devices (which is why you have to enable access for assistive devices. The time stamps are set by the operating system which gives nominally nanosecond precision. The precision ultimately depends on how the operating system polls devices. But, this is likely to be fairly accurate and our experience with the time stamps has not shown any problems. Could in principle event time stamps get slowed down by other process - yes, but this is unlikely to be a major problem on todays mult-core systems in which the thread running by the kernel to pick up key and mouse events is likely run at a very low level with high priority and probably in a dedicated processor unless you have too many things running. Normally, you don't have to call this function yourself. It is called by the other functions that get key events (or run by the task code). To run yourself, you call it with different commands: