====== 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 [[:mgl:functionreferencekeyboardandmouse#mglListener:_Background_process_that_reads_mouse_and_keyboard_events|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 [[:mgl:functionreferencekeyboardandmouse#mglListener:_Background_process_that_reads_mouse_and_keyboard_events|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:beta|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:beta|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:beta|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  [[https://developer.apple.com/library/mac/#documentation/Carbon/Reference/QuartzEventServicesRef/Reference/reference.html|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 [[mgl:beta#keyboard_events|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 |