---
name: "event"
section: "3caca"
platform: "linux"
package: "libcucul-dev"
version: "0.99.beta11.debian-2"
release: "Debian 4.0 (Etch)"
platforms: ["linux"]
url: "https://new.carta.tech/event/3caca"
---

# event(3caca)

## NAME

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.