libcaca documentation

# libcaca event handling

## Functions
int | caca_get_event (caca_display_t *, unsigned int, caca_event_t *, int)
| Get the next mouse or keyboard input event.
unsigned int | caca_get_mouse_x (caca_display_t *)
| Return the X mouse coordinate.
unsigned int | caca_get_mouse_y (caca_display_t *)
| Return the Y mouse coordinate.
int | caca_set_mouse (caca_display_t *, int)
| Show or hide the mouse pointer.

## Detailed Description

These functions handle user events such as keyboard input and mouse clicks.

## Function Documentation

int caca_get_event | ( | caca_display_t * | dp,
|  | unsigned int | event_mask,
|  | caca_event_t * | ev,
|  | int | timeout |
| ) |  |  |

Poll the event queue for mouse or keyboard events matching the event mask and return the first matching event. Non-matching events are discarded. If `event_mask` is zero, the function returns immediately.

The timeout value tells how long this function needs to wait for an event. A value of zero returns immediately and the function returns zero if no more events are pending in the queue. A negative value causes the function to wait indefinitely until a matching event is received.

If not null, `ev` will be filled with information about the event received. If null, the function will return but no information about the event will be sent.

This function never fails.

Parameters:

  | dp | The libcaca graphical context.
  | event_mask | Bitmask of requested events.
  | timeout | A timeout value in microseconds, -1 for blocking behaviour
  | ev | A pointer to a caca_event structure, or NULL.

Returns:
  1 if a matching event was received, or 0 if the wait timeouted.

unsigned int caca_get_mouse_x | ( | caca_display_t * | dp | ) |

Return the X coordinate of the mouse position last time it was detected. This function is not reliable if the ncurses or S-Lang drivers are being used, because mouse position is only detected when the mouse is clicked. Other drivers such as X11 work well.

This function never fails.

Parameters:

  | dp | The libcaca graphical context.

Returns:
  The X mouse coordinate.

unsigned int caca_get_mouse_y | ( | caca_display_t * | dp | ) |

Return the Y coordinate of the mouse position last time it was detected. This function is not reliable if the ncurses or S-Lang drivers are being used, because mouse position is only detected when the mouse is clicked. Other drivers such as X11 work well.

This function never fails.

Parameters:

  | dp | The libcaca graphical context.

Returns:
  The Y mouse coordinate.

int caca_set_mouse | ( | caca_display_t * | dp,
|  | int | flag |
| ) |  |  |

Show or hide the mouse pointer, for devices that support such a feature.

If an error occurs, -1 is returned and errno is set accordingly:

- `ENOSYS` Display driver does not support hiding the mouse pointer.

Parameters:

  | dp | The libcaca display context.
  | flag | 0 hides the pointer, 1 shows the system's default pointer (usually an arrow). Other values are reserved for future use.

Returns:
  0 upon success, -1 if an error occurred.