Product SiteDocumentation Site

A.16. wl_pointer - pointer input device

The wl_pointer interface represents one or more input devices, such as mice, which control the pointer location and pointer_focus of a seat.
The wl_pointer interface generates motion, enter and leave events for the surfaces that the pointer is located over, and button and axis events for button presses, button releases and scrolling.

A.16.1. Requests provided by wl_pointer

A.16.1.1. wl_pointer::set_cursor - set the pointer surface

Set the pointer surface, i.e., the surface that contains the pointer image (cursor). This request only takes effect if the pointer focus for this device is one of the requesting client's surfaces or the surface parameter is the current pointer surface. If there was a previous surface set with this request it is replaced. If surface is NULL, the pointer image is hidden.
The parameters hotspot_x and hotspot_y define the position of the pointer surface relative to the pointer location. Its top-left corner is always at (x, y) - (hotspot_x, hotspot_y), where (x, y) are the coordinates of the pointer location, in surface local coordinates.
On surface.attach requests to the pointer surface, hotspot_x and hotspot_y are decremented by the x and y parameters passed to the request. Attach must be confirmed by wl_surface.commit as usual.
The hotspot can also be updated by passing the currently set pointer surface to this request with new values for hotspot_x and hotspot_y.
The current and pending input regions of the wl_surface are cleared, and wl_surface.set_input_region is ignored until the wl_surface is no longer used as the cursor. When the use as a cursor ends, the current and pending input regions become undefined, and the wl_surface is unmapped.
wl_pointer::set_cursor arguments
serial
Type: uint
serial of the enter event
surface
Type: object
hotspot_x
Type: int
x coordinate in surface-relative coordinates
hotspot_y
Type: int
y coordinate in surface-relative coordinates

A.16.1.2. wl_pointer::release - release the pointer object

A.16.2. Events provided by wl_pointer

A.16.2.1. wl_pointer::enter - enter event

Notification that this seat's pointer is focused on a certain surface.
When an seat's focus enters a surface, the pointer image is undefined and a client should respond to this event by setting an appropriate pointer image with the set_cursor request.
wl_pointer::enter arguments
serial
Type: uint
surface
Type: object
surface_x
Type: fixed
x coordinate in surface-relative coordinates
surface_y
Type: fixed
y coordinate in surface-relative coordinates

A.16.2.2. wl_pointer::leave - leave event

Notification that this seat's pointer is no longer focused on a certain surface.
The leave notification is sent before the enter notification for the new focus.
wl_pointer::leave arguments
serial
Type: uint
surface
Type: object

A.16.2.3. wl_pointer::motion - pointer motion event

Notification of pointer location change. The arguments surface_x and surface_y are the location relative to the focused surface.
wl_pointer::motion arguments
time
Type: uint
timestamp with millisecond granularity
surface_x
Type: fixed
x coordinate in surface-relative coordinates
surface_y
Type: fixed
y coordinate in surface-relative coordinates

A.16.2.4. wl_pointer::button - pointer button event

Mouse button click and release notifications.
The location of the click is given by the last motion or enter event. The time argument is a timestamp with millisecond granularity, with an undefined base.
wl_pointer::button arguments
serial
Type: uint
time
Type: uint
timestamp with millisecond granularity
button
Type: uint
state
Type: uint

A.16.2.5. wl_pointer::axis - axis event

Scroll and other axis notifications.
For scroll events (vertical and horizontal scroll axes), the value parameter is the length of a vector along the specified axis in a coordinate space identical to those of motion events, representing a relative movement along the specified axis.
For devices that support movements non-parallel to axes multiple axis events will be emitted.
When applicable, for example for touch pads, the server can choose to emit scroll events where the motion vector is equivalent to a motion event vector.
When applicable, clients can transform its view relative to the scroll distance.
wl_pointer::axis arguments
time
Type: uint
timestamp with millisecond granularity
axis
Type: uint
value
Type: fixed

A.16.3. Enums provided by wl_pointer

A.16.3.1. wl_pointer::button_state - physical button state

Describes the physical state of a button which provoked the button event.
wl_pointer::button_state values
released
Value: 0
The button is not pressed
pressed
Value: 1
The button is pressed

A.16.3.2. wl_pointer::axis - axis types

Describes the axis types of scroll events.
wl_pointer::axis values
vertical_scroll
Value: 0
horizontal_scroll
Value: 1