Keyboard and mouse functions

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.

GRU