libcaca documentation

Functions
libcaca event handling

## Functions
__extern int | caca_get_event (caca_display_t *, int, caca_event_t *, int)
| Get the next mouse or keyboard input event.
__extern int | caca_get_mouse_x (caca_display_t const *)
| Return the X mouse coordinate.
__extern int | caca_get_mouse_y (caca_display_t const *)
| Return the Y mouse coordinate.
__extern enum caca_event_type | caca_get_event_type (caca_event_t const *)
| Return an event's type.
__extern int | caca_get_event_key_ch (caca_event_t const *)
| Return a key press or key release event's value.
__extern uint32_t | caca_get_event_key_utf32 (caca_event_t const *)
| Return a key press or key release event's Unicode value.
__extern int | caca_get_event_key_utf8 (caca_event_t const *, char *)
| Return a key press or key release event's UTF-8 value.
__extern int | caca_get_event_mouse_button (caca_event_t const *)
| Return a mouse press or mouse release event's button.
__extern int | caca_get_event_mouse_x (caca_event_t const *)
| Return a mouse motion event's X coordinate.
__extern int | caca_get_event_mouse_y (caca_event_t const *)
| Return a mouse motion event's Y coordinate.
__extern int | caca_get_event_resize_width (caca_event_t const *)
| Return a resize event's display width value.
__extern int | caca_get_event_resize_height (caca_event_t const *)
| Return a resize event's display height value.

## Detailed Description

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

## Function Documentation

__extern int caca_get_event | ( | caca_display_t * | dp,
|  | 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.

References CACA_EVENT_NONE.

Referenced by caca_conio_getch(), and caca_conio_kbhit().

__extern int caca_get_mouse_x | ( | caca_display_t const * | 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.

References caca_get_canvas_width().

__extern int caca_get_mouse_y | ( | caca_display_t const * | 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.

References caca_get_canvas_height().

__extern enum caca_event_type caca_get_event_type | ( | caca_event_t const * | ev | ) |

Return the type of an event. This function may always be called on an event after caca_get_event() was called, and its return value indicates which other functions may be called:

- `CACA_EVENT_NONE:` no other function may be called.
- `CACA_EVENT_KEY_PRESS`, `CACA_EVENT_KEY_RELEASE:` caca_get_event_key_ch(), caca_get_event_key_utf32() and caca_get_event_key_utf8() may be called.
- `CACA_EVENT_MOUSE_PRESS`, `CACA_EVENT_MOUSE_RELEASE:` caca_get_event_mouse_button() may be called.
- `CACA_EVENT_MOUSE_MOTION:` caca_get_event_mouse_x() and caca_get_event_mouse_y() may be called.
- `CACA_EVENT_RESIZE:` caca_get_event_resize_width() and caca_get_event_resize_height() may be called.
- `CACA_EVENT_QUIT:` no other function may be called.

This function never fails.

Parameters:

  ev | The libcaca event.

Returns:
  The event's type.

__extern int caca_get_event_key_ch | ( | caca_event_t const * | ev | ) |

Return either the ASCII value for an event's key, or if the key is not an ASCII character, an appropriate enum caca_key value.

This function never fails, but must only be called with a valid event of type `CACA_EVENT_KEY_PRESS` or `CACA_EVENT_KEY_RELEASE`, or the results will be undefined. See caca_get_event_type() for more information.

Parameters:

  ev | The libcaca event.

Returns:
  The key value.

Referenced by caca_conio_getch(), and caca_conio_kbhit().

__extern uint32_t caca_get_event_key_utf32 | ( | caca_event_t const * | ev | ) |

Return the UTF-32/UCS-4 value for an event's key if it resolves to a printable character.

This function never fails, but must only be called with a valid event of type `CACA_EVENT_KEY_PRESS` or `CACA_EVENT_KEY_RELEASE`, or the results will be undefined. See caca_get_event_type() for more information.

Parameters:

  ev | The libcaca event.

Returns:
  The key's Unicode value.

__extern int caca_get_event_key_utf8 | ( | caca_event_t const * | ev,
|  | char * | utf8
| ) |  |

Write the UTF-8 value for an event's key if it resolves to a printable character. Up to 6 UTF-8 bytes and a null termination are written.

This function never fails, but must only be called with a valid event of type `CACA_EVENT_KEY_PRESS` or `CACA_EVENT_KEY_RELEASE`, or the results will be undefined. See caca_get_event_type() for more information.

Parameters:

  ev | The libcaca event.
  utf8 | A string buffer with enough bytes to hold the pressed key value in UTF-8. Though fewer bytes may be written to it, 7 bytes is the minimum safe size.

Returns:
  This function always returns 0.

__extern int caca_get_event_mouse_button | ( | caca_event_t const * | ev | ) |

Return the mouse button index for an event.

This function never fails, but must only be called with a valid event of type `CACA_EVENT_MOUSE_PRESS` or `CACA_EVENT_MOUSE_RELEASE`, or the results will be undefined. See caca_get_event_type() for more information.

This function returns 1 for the left mouse button, 2 for the right mouse button, and 3 for the middle mouse button.

Parameters:

  ev | The libcaca event.

Returns:
  The event's mouse button.

__extern int caca_get_event_mouse_x | ( | caca_event_t const * | ev | ) |

Return the X coordinate for a mouse motion event.

This function never fails, but must only be called with a valid event of type `CACA_EVENT_MOUSE_MOTION`, or the results will be undefined. See caca_get_event_type() for more information.

Parameters:

  ev | The libcaca event.

Returns:
  The event's X mouse coordinate.

__extern int caca_get_event_mouse_y | ( | caca_event_t const * | ev | ) |

Return the Y coordinate for a mouse motion event.

This function never fails, but must only be called with a valid event of type `CACA_EVENT_MOUSE_MOTION`, or the results will be undefined. See caca_get_event_type() for more information.

Parameters:

  ev | The libcaca event.

Returns:
  The event's Y mouse coordinate.

__extern int caca_get_event_resize_width | ( | caca_event_t const * | ev | ) |

Return the width value for a display resize event.

This function never fails, but must only be called with a valid event of type `CACA_EVENT_RESIZE`, or the results will be undefined. See caca_get_event_type() for more information.

Parameters:

  ev | The libcaca event.

Returns:
  The event's new display width value.

__extern int caca_get_event_resize_height | ( | caca_event_t const * | ev | ) |

Return the height value for a display resize event.

This function never fails, but must only be called with a valid event of type `CACA_EVENT_RESIZE`, or the results will be undefined. See caca_get_event_type() for more information.

Parameters:

  ev | The libcaca event.

Returns:
  The event's new display height value.