Documentation for <wlr/xwayland.h>

Back to index

Table of contents


bool wlr_surface_is_xwayland_surface(​struct wlr_surface *surface);

Returns true if the surface has the xwayland surface role.

struct wlr_xwayland

struct wlr_xwayland {
	struct wlr_xwayland_server *server;
	struct wlr_xwm *xwm;
	struct wlr_xwayland_cursor *cursor;
	const char *display_name;
	struct wl_display *wl_display;
	struct wlr_compositor *compositor;
	struct wlr_seat *seat;
	struct {
		struct wl_signal ready;
		struct wl_signal new_surface;
		struct wl_signal remove_startup_info;
	} events;
	 * Add a custom event handler to xwayland. Return 1 if the event was
	 * handled or 0 to use the default wlr-xwayland handler. wlr-xwayland will
	 * free the event.
	int (*user_event_handler)(​struct wlr_xwm *xwm, xcb_generic_event_t *event);
	struct wl_listener server_ready;
	struct wl_listener server_destroy;
	struct wl_listener seat_destroy;
	void *data;


struct wlr_xwayland *wlr_xwayland_create(​struct wl_display *wl_display, struct wlr_compositor *compositor, bool lazy);

Create an Xwayland server and XWM.

The server supports a lazy mode in which Xwayland is only started when a client tries to connect.

struct wlr_xwayland_cursor

struct wlr_xwayland_cursor;


void wlr_xwayland_destroy(​struct wlr_xwayland *wlr_xwayland);


enum wlr_xwayland_icccm_input_model wlr_xwayland_icccm_input_model(​const struct wlr_xwayland_surface *xsurface);

enum wlr_xwayland_icccm_input_model

enum wlr_xwayland_icccm_input_model {

This represents the input focus described as follows:

struct wlr_xwayland_minimize_event

struct wlr_xwayland_minimize_event {
	struct wlr_xwayland_surface *surface;
	bool minimize;

struct wlr_xwayland_move_event

struct wlr_xwayland_move_event {
	struct wlr_xwayland_surface *surface;


bool wlr_xwayland_or_surface_wants_focus(​const struct wlr_xwayland_surface *xsurface);

Metric to guess if an OR window should "receive" focus

In the pure X setups, window managers usually straight up ignore override redirect windows, and never touch them. (we have to handle them for mapping)

When such a window wants to receive keyboard input (e.g. rofi/dzen) it will use mechanics we don't support (sniffing/grabbing input). [Sadly this is unrelated to xwayland-keyboard-grab]

To still support these windows, while keeping general OR semantics as is, we need to hand a subset of windows focus. The dirty truth is, we need to hand focus to any Xwayland window, though pretending this window has focus makes it easier to handle unmap.

This function provides a handy metric based on the window type to guess if the OR window wants focus. It's probably not perfect, nor exactly intended but works in practice.

Returns: true if the window should receive focus false if it should be ignored

struct wlr_xwayland_remove_startup_info_event

struct wlr_xwayland_remove_startup_info_event {
	const char *id;
	xcb_window_t window;

struct wlr_xwayland_resize_event

struct wlr_xwayland_resize_event {
	struct wlr_xwayland_surface *surface;
	uint32_t edges;

struct wlr_xwayland_server

struct wlr_xwayland_server {
	pid_t pid;
	struct wl_client *client;
	struct wl_event_source *pipe_source;
	int wm_fd[], wl_fd[];
	time_t server_start;
	/* Anything above display is reset on Xwayland restart, rest is conserved */
	int display;
	char display_name[];
	int x_fd[];
	struct wl_event_source *x_fd_read_event[];
	struct wlr_xwayland_server_options options;
	struct wl_display *wl_display;
	struct {
		struct wl_signal ready;
		struct wl_signal destroy;
	} events;
	struct wl_listener client_destroy;
	struct wl_listener display_destroy;
	void *data;


struct wlr_xwayland_server *wlr_xwayland_server_create(​struct wl_display *display, struct wlr_xwayland_server_options *options);


void wlr_xwayland_server_destroy(​struct wlr_xwayland_server *server);

struct wlr_xwayland_server_options

struct wlr_xwayland_server_options {
	bool lazy;
	bool enable_wm;
	bool no_touch_pointer_emulation;
	bool force_xrandr_emulation;
	int terminate_delay; // in seconds, 0 to terminate immediately

struct wlr_xwayland_server_ready_event

struct wlr_xwayland_server_ready_event {
	struct wlr_xwayland_server *server;
	int wm_fd;


void wlr_xwayland_set_cursor(​struct wlr_xwayland *wlr_xwayland, uint8_t *pixels, uint32_t stride, uint32_t width, uint32_t height, int32_t hotspot_x, int32_t hotspot_y);


void wlr_xwayland_set_seat(​struct wlr_xwayland *xwayland, struct wlr_seat *seat);

struct wlr_xwayland_surface

struct wlr_xwayland_surface {
	xcb_window_t window_id;
	struct wlr_xwm *xwm;
	uint32_t surface_id;
	struct wl_list link;
	struct wl_list stack_link;
	struct wl_list unpaired_link;
	struct wlr_surface *surface;
	int16_t x, y;
	uint16_t width, height;
	uint16_t saved_width, saved_height;
	bool override_redirect;
	bool mapped;
	char *title;
	char *class;
	char *instance;
	char *role;
	char *startup_id;
	pid_t pid;
	bool has_utf8_title;
	struct wl_list children; // wlr_xwayland_surface::parent_link
	struct wlr_xwayland_surface *parent;
	struct wl_list parent_link; // wlr_xwayland_surface::children
	xcb_atom_t *window_type;
	size_t window_type_len;
	xcb_atom_t *protocols;
	size_t protocols_len;
	uint32_t decorations;
	xcb_icccm_wm_hints_t *hints;
	xcb_size_hints_t *size_hints;
	bool pinging;
	struct wl_event_source *ping_timer;
	bool modal;
	bool fullscreen;
	bool maximized_vert, maximized_horz;
	bool minimized;
	bool has_alpha;
	struct {
		struct wl_signal destroy;
		struct wl_signal request_configure;
		struct wl_signal request_move;
		struct wl_signal request_resize;
		struct wl_signal request_minimize;
		struct wl_signal request_maximize;
		struct wl_signal request_fullscreen;
		struct wl_signal request_activate;
		struct wl_signal map;
		struct wl_signal unmap;
		struct wl_signal set_title;
		struct wl_signal set_class;
		struct wl_signal set_role;
		struct wl_signal set_parent;
		struct wl_signal set_pid;
		struct wl_signal set_startup_id;
		struct wl_signal set_window_type;
		struct wl_signal set_hints;
		struct wl_signal set_decorations;
		struct wl_signal set_override_redirect;
		struct wl_signal set_geometry;
		struct wl_signal ping_timeout;
	} events;
	struct wl_listener surface_destroy;
	void *data;

An Xwayland user interface component. It has an absolute position in layout-local coordinates.

When a surface is ready to be displayed, the `map` event is emitted. When a surface should no longer be displayed, the `unmap` event is emitted. The `unmap` event is guaranteed to be emitted before the `destroy` event if the view is destroyed when mapped.


void wlr_xwayland_surface_activate(​struct wlr_xwayland_surface *surface, bool activated);


void wlr_xwayland_surface_close(​struct wlr_xwayland_surface *surface);


void wlr_xwayland_surface_configure(​struct wlr_xwayland_surface *surface, int16_t x, int16_t y, uint16_t width, uint16_t height);

struct wlr_xwayland_surface_configure_event

struct wlr_xwayland_surface_configure_event {
	struct wlr_xwayland_surface *surface;
	int16_t x, y;
	uint16_t width, height;
	uint16_t mask; // xcb_config_window_t

enum wlr_xwayland_surface_decorations

enum wlr_xwayland_surface_decorations {


struct wlr_xwayland_surface *wlr_xwayland_surface_from_wlr_surface(​struct wlr_surface *surface);

Get a struct wlr_xwayland_surface from a struct wlr_surface. Asserts that the surface has the xwayland surface role. May return NULL even if the surface has the xwayland surface role if the corresponding xwayland surface has been destroyed.


void wlr_xwayland_surface_ping(​struct wlr_xwayland_surface *surface);


void wlr_xwayland_surface_restack(​struct wlr_xwayland_surface *surface, struct wlr_xwayland_surface *sibling, enum xcb_stack_mode_t mode);

Restack surface relative to sibling. If sibling is NULL, then the surface is moved to the top or the bottom of the stack (depending on the mode).


void wlr_xwayland_surface_set_fullscreen(​struct wlr_xwayland_surface *surface, bool fullscreen);


void wlr_xwayland_surface_set_maximized(​struct wlr_xwayland_surface *surface, bool maximized);


void wlr_xwayland_surface_set_minimized(​struct wlr_xwayland_surface *surface, bool minimized);

struct wlr_xwm

struct wlr_xwm;