libcaca documentation

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:

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.