SR Research Support Site
Macros | Functions
Keyboard Input Functions

Macros

#define CURS_UP   0x4800
 
#define CURS_DOWN   0x5000
 
#define CURS_LEFT   0x4B00
 
#define CURS_RIGHT   0x4D00
 
#define ESC_KEY   0x001B
 
#define ENTER_KEY   0x000D
 
#define PAGE_UP   0x4900
 
#define PAGE_DOWN   0x5100
 
#define JUNK_KEY   1
 
#define TERMINATE_KEY   0x7FFF
 

Functions

void flush_getkey_queue (void)
 
UINT16 read_getkey_queue (void)
 
UINT16 echo_key (void)
 
UINT16 getkey (void)
 
UINT32 getkey_with_mod (UINT16 *unicode)
 
INT16 escape_pressed (void)
 
INT16 break_pressed (void)
 
void terminal_break (INT16 assert)
 

Detailed Description

Macro Definition Documentation

#define CURS_DOWN   0x5000

Cursor down key.

#define CURS_LEFT   0x4B00

Cursor left key.

#define CURS_RIGHT   0x4D00

Cursor right key.

#define CURS_UP   0x4800

Cursor up key.

#define ENTER_KEY   0x000D

Return key.

#define ESC_KEY   0x001B

Escape key.

#define JUNK_KEY   1

Junk key to indicate untranslatable key.

#define PAGE_DOWN   0x5100

Page down key.

#define PAGE_UP   0x4900

Page up key.

#define TERMINATE_KEY   0x7FFF

Returned by getkey if program should exit.

Function Documentation

INT16 break_pressed ( void  )

Tests if the program is being interrupted. You should break out of loops immediately if this function does not return 0, if getkey() return TERMINATE_KEY, or if eyelink_is_connected() returns 0.

Returns
1 if CTRL-C is pressed, terminal_break() was called, or the program has been terminated with ALT-F4; 0 otherwise.

Example:

1 // This program illustrates the use of break_pressed() and escape_pressed()
2 
3 #include <eyelink.h>
4 
5 // reset keys and buttons from tracker
6 eyelink_flush_keybuttons(0);
7 
8 // Trial loop: till timeout or response
9 while(1)
10 {
11  // Checks if recording aborted
12  if((error=check_recording())!=0) return error;
13 
14  // check for program termination or ALT-F4 or CTRL-C keys
15  if(break_pressed())
16  return ABORT_EXPT;
17 
18  // check for local ESC key to abort trial (useful in debugging)
19  if(escape_pressed())
20  return SKIP_TRIAL;
21 
22  ...
23  // Other code for display update, trial terminating, etc.
24 }
See also
echo_key(), escape_pressed() and getkey()
UINT16 echo_key ( void  )

Checks for Windows keystroke events and dispatches messages; similar to getkey(), but also sends keystroke to tracker.

Returns
0 if no key pressed, else key code.
TERMINATE_KEY if CTRL-C held down or program has been terminated.

Example:

1 // This program illustrates the use of echo_key(), if you want to write your own code for do_tracker_setup routine
2 #include <eyelink.h>
3 
4 // Resets keys and buttons from tracker
5 eyelink_flush_keybutton();
6 // dump any accumulated key presses
7 while(getkey());
8 
9 // If we make sure that we are in set-up mode
10 while(eyelink_current_mode() & IN_SETUP_MODE)
11 {
12  int i = eyelink_current_mode();
13 
14  // calibrate, validate, etc: show targets
15  if(i & IN_TARGET_MODE)
16  {
17  ...
18  // Code here for displaying and updating calibration target
19  // If using Windows library, call target_mode_display();
20  }
21  else if(i & IN_IMAGE_MODE)
22  {
23  ...
24  // Code here for showing the camera image
25  // If using Windows library, call target_mode_display();
26  }
27 
28  // If we allow local tracker control, echo to tracker for remote control
29  echo_key();
30 }
See also
eyelink_read_keybutton(), eyelink_send_keybutton() and getkey()
INT16 escape_pressed ( void  )

This function tests if the 'ESC' key is held down, and is usually used to break out of nested loops. This does not allow processing of Windows messages, unlike getkey().

Returns
1 if 'ESC' key held down; 0 if not.

Example: See break_pressed()

See also
break_pressed(), getkey() and echo_key()
void flush_getkey_queue ( void  )

Initializes the key queue used by getkey(). This should be called at the start of your program. It may be called at any time to get rid any of old keys from the queue.

Example:

1 // This program illustrates the use of flush_getkey_queue()
2 
3 #include <eyelink.h>
4 
5 // Sets the EyeLink host address, if tracker IP address is different
6 // from the default "100.1.1.1"
7 if (set_eyelink_address("100.1.1.7"))
8  return -1;
9 
10 // Initializes EyeLink library, and opens connection to the tracker
11 if(open_eyelink_connection(0))
12  return -1;
13 
14 flush_getkey_queue(); // initialize getkey() system
15 
16 ...
17 // Code for the setup, recording, and cleanups
18 close_eyelink_connection(); // disconnect from tracker
See also
read_getkey_queue()
UINT16 getkey ( void  )

A routine for checking for Windows keystroke events, and dispatching Windows messages. If no key is pressed or waiting, it returns 0. For a standard ASCII key, a value from 31 to 127 is returned. For extended keys, a special key value is returned. If the program has been terminated by ALT-F4 or a call to terminal_break(), or the "Ctrl" and "C" keys are held down, the value TERMINATE_KEY is returned. The value JUNK_KEY (1) is returned if a non-translatable key is pressed.

Remarks
Warning: This function processes and dispatches any waiting messages. This will allow Windows to perform disk access and negates the purpose of realtime mode. Usually these delays will be only a few milliseconds, but delays over 20 milliseconds have been observed. You may wish to call escape_pressed() or break_pressed() in recording loops instead of getkey() if timing is critical, for example in a gaze-contingent display. Some useful keys are defined in core_expt.h, as:
  • CURS_UP 0x4800
  • CURS_DOWN 0x5000
  • CURS_LEFT 0x4B00
  • CURS_RIGHT 0x4D00
  • ESC_KEY 0x001B
  • ENTER_KEY 0x000D
  • TERMINATE_KEY 0x7FFF
  • JUNK_KEY 0x0001
Returns
0 if no key pressed, else key code.
TERMINATE_KEY if CTRL-C held down or program has been terminated.

Example:

1 // This program illustrates the use of getkey()
2 
3 #include <eyelink.h>
4 UINT32 delay_time = 5000L; // Set the maximum wait time
5 
6 // flushes any waiting keys or buttons
7 eyelink_flush_keybuttons(0);
8 
9 delay_time += current_msec();
10 while(1)
11 {
12  // Waitkey times out
13  if(current_time() > delay_time)
14  {
15  eyemsg_printf("WAITKEY TIMEOUT");
16  break;
17  }
18  key = getkey();
19  if(key) // If key press occurs
20  {
21  // Is this printable key?
22  if(key < 256 && isprint(key))
23  eyemsg_printf("WAITKEY '%c'", key);
24  else
25  eyemsg_printf("WAITKEY 0x%04X", key);
26  break;
27  }
28 }
See also
break_pressed(), echo_key(), escape_pressed(), eyelink_flush_keybuttons() and eyelink_send_keybutton()
UINT32 getkey_with_mod ( UINT16 *  unicode)

Same as getkey except it returns the modifier and the key pressed. It returns a 32 bit unsigned integer. The first 16 bits are reserved for the modifier and the last 16 bits are reserved for the key values. If there are no modifiers present, the return value of this is the same as getkey(). If non null pointer passed in for unicode, the translated key value will be set if a key is preent.

UINT16 read_getkey_queue ( void  )

Reads keys from the key queue. It is similar to getkey(), but does not process Windows messages. This can be used to build key-message handlers in languages other than C.

Remarks
These functions are intended to support languages other than C or C++.
Returns
0 if no key pressed.
JUNK_KEY (1) if untranslatable key.
TERMINATE_KEY (0x7FFF) if CTRL-C is pressed, terminal_break() was called, or the program has been terminated with ALT-F4.
else, code of key if any key pressed.
See also
flush_getkey_queue()
void terminal_break ( INT16  assert)

This function can be called in an event handler to signal that the program is terminating. Calling this function with an argument of 1 will cause break_pressed() to return 1, and getkey() to return TERMINATE_KEY. These functions can be re-enabled by calling terminal_break() with an argument of 0.

Parameters
assert1 to signal a program break, 0 to reset break.

Example:

1 // The following code illustrates the use of terminal_break(). This would usually be called
2 // from a message or event handler (see the w32_demo_window.c module) for a complete example.
3 
4 #include <eyelink.h>
5 
6 switch (message)
7 {
8 case WM_CLOSE: // If ALT-F4 pressed, force program to close
9  PostQuitMessage(0);
10  terminal_break(1);// break out of loops
11  break;
12 
13 case WM_DESTROY: // Window being closed by ALT-F4
14  PostQuitMessage( 0 );
15  ...
16  // Code here for graphics cleaning up
17  terminal_break(1);// break out of loops
18  break;
19 
20 case WM_QUIT: // Needs to break out of any loops
21  terminal_break(1);
22  break;
23  ...
24  // Other windows messages and events
25 }
See also
break_pressed() and getkey()

Copyright ©2002-2021, SR Research Ltd.