Keyboard and mouse functions

mglDisplayCursor: Hide or display the mouse cursor

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

argument value
display 1 or 0 to display or hide the cursor

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

mglOpen
mglDisplayCursor

mglGetKeys: Get keyboard state

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

argument value
keys array of keycodes. In this case mglGetKeys will only return thestatus of those keys, for example: mglGetKeys([61 46]) will return the values of key 61 and 46.

mglGetMouse: Get mouse state

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

mglGetKeyEvent: Get a key down event off of queue

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)

argument value
waitTicks Ticks to wait for before giving up and returning empty event
mglOpen
mglGetKeyEvent(0.5)

mglGetMouseEvent: Get a mouse button down event off of queue

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

argument value
waitTicks Ticks to wait for before giving up and returning empty event
mglOpen
mglGetMouseEvent(0.5)

mglCharToKeycode: Returns keycode of char

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

argument value
keyname cell array where each entry is a key name string e.g. keyname = {'h','g' '1'}
OUTPUT:keycode vector of integer keycodes for each keyname entry e.g. for the above example, keyname=[44 43 11] (on Linux)

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

mglKeycodeToChar: Returns char of keycode

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

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

argument value
keycode vector of integer keycodes for each keyname entry for example, keyname=[44 43 11]
OUTPUT:keyname cell array where each entry is a key name string for the above example on linux keyname = {'h','g' '1'}

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

mglSimulateRun: Generates simulated key presses

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');

mglEatKeys: Keep key presses from entering buffer

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.

mglListener: Background process that reads mouse and keyboard events

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:

command value
init starts the process running
getKeyEvent Returns a keyboard down event
getMouseEvent Returns a mouse down event
getKeys Returns an array like mglGetKeys except that the time each key that is currently down was initially pressed is returned.
getAllKeyEvents Returns a structure with when/keyCode for all pending keyEvents
getAllMouseEvents Same as getAllKeyEvents but for mouse events
eatKeys specify a string or an array of keyCodes (as arg1) for keyboard events that will not pass through to the application window. The events will still be available from 'getKeyEvent'. This is useful, if you don't want a lot of backtick key presses going into your command window for instance
quit Quits the listener, after this you won't be able to run other commands