SR Research Support Site
Functions
Eyelink Button Functions

Functions

UINT16 eyelink_read_keybutton (INT16 FARTYPE *mods, INT16 FARTYPE *state, UINT16 *kcode, UINT32 FARTYPE *time)
 
INT16 eyelink_send_keybutton (UINT16 code, UINT16 mods, INT16 state)
 
UINT16 eyelink_button_states (void)
 
UINT16 eyelink_last_button_states (UINT32 FARTYPE *time)
 
UINT16 eyelink_last_button_press (UINT32 FARTYPE *time)
 
INT16 eyelink_flush_keybuttons (INT16 enable_buttons)
 

Detailed Description

Function Documentation

UINT16 eyelink_button_states ( void  )

Returns a flag word with bits set to indicate which tracker buttons are currently pressed. This is button 1 for the LSB, up to button 16 for the MSB.

Remarks
Buttons above 8 are not realized on the EyeLink tracker.
Returns
Flag bits for buttons currently pressed.

Example:

1 // This program illustrates the use of eyelink_button_states
2 
3 #include <eyelink.h>
4 int state =0;
5 int prev_state = 0;
6 UINT32 start_time = current_time();
7 
8 // Exits when the tracker is not connected or times out
9 while(eyelink_is_connected()
10  && current_time() > start_time + 5000)
11 {
12  // reads the currently-known state of all buttons
13  state = eyelink_button_states();
14  if (state != prev_state)
15  {
16  eyemsg_printf("Button 1:%s 2:%s 3:%s 4:%s 5:%s",
17  state & 0x01 ? "Pressed" : "Released",
18  (state & 0x02) >> 1 ? "Pressed" : "Released",
19  (state & 0x04) >> 2 ? "Pressed" : "Released",
20  (state & 0x08) >> 3 ? "Pressed" : "Released",
21  (state & 0x10) >> 4 ? "Pressed" : "Released");
22 
23  prev_state = state;
24  }
25 }

Output:

1 BUTTON 4144034 1 1
2 MSG 4144035 Button 1:Pressed 2:Released 3:Released 4:Released 5:Released
3 BUTTON 4144266 1 0
4 MSG 4144267 Button 1:Released 2:Released 3:Released 4:Released 5:Released
5 BUTTON 4144650 2 1
6 MSG 4144651 Button 1:Released 2:Pressed 3:Released 4:Released 5:Released
7 BUTTON 4144898 2 0
8 MSG 4144899 Button 1:Released 2:Released 3:Released 4:Released 5:Released
9 BUTTON 4145260 3 1
10 MSG 4145261 Button 1:Released 2:Released 3:Pressed 4:Released 5:Released
11 BUTTON 4145492 3 0
12 MSG 4145493 Button 1:Released 2:Released 3:Released 4:Released 5:Released
13 BUTTON 4145834 4 1
14 MSG 4145835 Button 1:Released 2:Released 3:Released 4:Pressed 5:Released
15 BUTTON 4146106 4 0
16 MSG 4146107 Button 1:Released 2:Released 3:Released 4:Released 5:Released
17 BUTTON 4146498 5 1
18 MSG 4146499 Button 1:Released 2:Released 3:Released 4:Released 5:Pressed
19 BUTTON 4146778 5 0
20 MSG 4146779 Button 1:Released 2:Released 3:Released 4:Released 5:Released
See also
eyelink_last_button_press()
INT16 eyelink_flush_keybuttons ( INT16  enable_buttons)

Causes the EyeLink tracker and the EyeLink library to flush any stored button or key events. This should be used before a trial to get rid of old button responses. The <enable_buttons> argument controls whether the EyeLink library will store button press and release events. It always stores tracker key events. Even if disabled, the last button pressed and button flag bits are updated.

Parameters
enable_buttonsSet to 0 to monitor last button press only, 1 to queue button events.
Returns
Always 0.

Example:

1 // This program illustrates the use of eyelink_flush_keybuttons.
2 
3 UINT32 wait_time = 5000;
4 int i;
5 
6 // Flushes any waiting keys or buttons
7 eyelink_flush_keybuttons(0);
8 
9 // Sets the time-out duration
10 wait_time += current_msec();
11 
12 // Makes sure that the tracker connection is still alive
13 while(eyelink_is_connected())
14 {
15  // handle the error or abort situations
16  if(getkey()==27 || !eyelink_is_connected())
17  break;
18 
19  // Checks the button response
20  i = eyelink_last_button_press(NULL);
21  if(i)
22  {
23  eyemsg_printf("WAITBUTTON %d", i);
24  break;
25  }
26 
27  // Times out if no button is pressed
28  if(current_time() > wait_time)
29  {
30  eyemsg_printf("WAITBUTTON TIMEOUT");
31  break;
32  }
33 }

Output:

1 BUTTON 19585661 5 1
2 MSG 19585662 WAITBUTTON 5
3 BUTTON 19586005 5 0
See also
eyelink_button_states(), eyelink_last_button_press(), eyelink_read_keybutton() and eyelink_send_keybutton()
UINT16 eyelink_last_button_press ( UINT32 FARTYPE *  time)

Reads the number of the last button detected by the EyeLink tracker. This is 0 if no buttons were pressed since the last call, or since the buttons were flushed. If a pointer to a variable is supplied the eye-tracker timestamp of the button may be read. This could be used to see if a new button has been pressed since the last read. If multiple buttons were pressed since the last call, only the last button is reported.

Parameters
timeFar pointer to a variable to hold tracker time of last button press. Usually left as NULL to ignore time.
Returns
Button last pressed, 0 if no button pressed since last read, or call to eyelink_flush_keybuttons().

Example:

1 // This program illustrates the use of eyelink_flush_keybuttons
2 
3 #include <eyelink.h>
4 int button;
5 
6 // reset keys and buttons from tracker
7 eyelink_flush_keybuttons(0);
8 
9 while(1)
10 {
11  // Check for eye-tracker buttons pressed
12  button = eyelink_last_button_press(NULL);
13 
14  // Disables button 6 and 7 and process all other button events
15  if(button != 0 && button != 6 && button != 7)
16  {
17  // Presses button 5 to break the loop
18  if (button == 5)
19  {
20  eyemsg_printf("ENDBUTTON %d", button);
21  break;
22  }
23  // Records all other button press messages
24  else
25  eyemsg_printf("BUTTON PRESSED %d", button);
26  }
27 }

Output:

1 BUTTON 19753748 2 1
2 MSG 19753749 BUTTON PRESSED 2
3 BUTTON 19754018 2 0
4 BUTTON 19755595 5 1
5 MSG 19755595 ENDBUTTON 5
6 BUTTON 19755808 5 0
See also
eyelink_flush_keybuttons(), eyelink_button_states(), eyelink_read_keybutton() and eyelink_send_keybutton()
UINT16 eyelink_last_button_states ( UINT32 FARTYPE *  time)

Returns a flag word with bits set to indicate which tracker buttons are currently pressed. This is button 1 for the LSB, up to button 16 for the MSB. Same as eyelink_button_states() except, optionally time of the button states can be acquired.

Parameters
[out]timepointer to return time of the button states.
Returns
Flag bits for buttons currently pressed.
See also
eyelink_send_keybutton()
UINT16 eyelink_read_keybutton ( INT16 FARTYPE *  mods,
INT16 FARTYPE *  state,
UINT16 *  kcode,
UINT32 FARTYPE *  time 
)

Reads any queued key or button events from tracker.

Remarks
Any of the parameters(mods/state/kcode/time) can be null to ignore.
Parameters
modsPointer to variable to hold button number or key modifier (Shift, Alt and Ctrl key states).
statePointer to variable to hold key or button change (KB_PRESS, KB_RELEASE, or KB_REPEAT).
kcodePointer to variable to hold key scan code.
timePointer to a variable to hold tracker time of the key or button change.
Returns
Key character is key press/release/repeat, KB_BUTTON (0xFF00) if button press or release. 0 if none.

Example:

1 // This program illustrates the use of eyelink_read_keybutton to read key press events from the tracker keyboard
2 
3 #include <eyelink.h>
4 
5 UINT16 key;
6 INT16 state;
7 
8 // Reads any queued key or button events from the tracker keyboard
9 key = eyelink_read_keybutton(NULL, &state, NULL, NULL);
10 
11 // Makes sure that we checks only the key press
12 if (key && state == KB_PRESS && key != KB_BUTTON)
13 {
14  // Writes out the pressed key id
15  if(key < 256 && isprint(key))
16  eyemsg_printf("KEY '%c'", key);
17  else
18  eyemsg_printf("WAITKEY 0x%04X", key);
19 }
See also
eyelink_send_keybutton()
INT16 eyelink_send_keybutton ( UINT16  code,
UINT16  mods,
INT16  state 
)

Sends a key or button event to tracker. Only key events are handled for remote control.

Parameters
codeKey character, or KB_BUTTON (0xFF00) if sending button event.
modsButton number, or key modifier (Shift, Alt and Ctrl key states).
stateKey or button change (KB_PRESS or KB_RELEASE).
Returns
0 if OK, else send link error.

Example:

1 // This program illustrates the implementation of echo_key() function using the eyelink_send_keybutton()
2 
3 // ECHO_KEY() function is similar to getkey() but also echoes key to tracker
4 UINT16 echo_key(void)
5 {
6  UINT16 k = getkey();
7 
8  if(k!=0 && k!=1)
9  eyelink_send_keybutton(k, 0, KB_PRESS);
10  return k;
11 }
See also
eyelink_read_keybutton()

Copyright ©2002-2021, SR Research Ltd.