Client Modules¶

The base set of objects used by Wayland clients. Users should only be directly creating Display and EventQueue objects. The Proxy objects to interfaces should be returned by making request calls.

Proxy

Display¶

class pywayland.client.Display(name_or_fd: Union[int, str] = None)¶

connect() → None¶

Connect to a Wayland display

Connect to the Wayland display by name of fd. An int parameter opens the connection using the file descriptor. The Display takes ownership of the fd and will close it when the display is destroyed. The fd will also be closed in case of failure. A string will open the display of the given name. If name is None, its value will be replaced with the WAYLAND_DISPLAY environment variable if it is set, otherwise display "wayland-0" will be used.

disconnect() → None¶

Close a connection to a Wayland display

Close the connection to display and free all resources associated with it.

dispatch(*, block=False, queue: pywayland.client.eventqueue.EventQueue = None) → int¶

Process incoming events

If block is False, it does not attempt to read the display fd or event queue and simply returns zero if the queue is empty.

If the given queue is empty and block is True, this function blocks until there are events to be read from the display fd. Events are read and queued on the appropriate event queues. Finally, events on the default event queue are dispatched.

Note

It is not possible to check if there are events on the queue or not.

flush() → int¶

Send all buffered requests on the display to the server

Send all buffered data on the client side to the server. Clients should call this function before blocking. On success, the number of bytes sent to the server is returned. On failure, this function returns -1 and errno is set appropriately.

Display.flush() never blocks. It will write as much data as possible, but if all data could not be written, errno will be set to EAGAIN and -1 returned. In that case, use poll on the display file descriptor to wait for it to become writable again.

get_fd() → int¶

Get a display context’s file descriptor

Return the file descriptor associated with a display so it can be integrated into the client’s main loop.

read(*, queue: pywayland.client.eventqueue.EventQueue = None) → None¶

Read events from display file descriptor

Calling this function will result in data available on the display file descriptor being read and read events will be queued on their corresponding event queues.

Parameters:	queue – If specified, queue the events onto the given event queue, otherwise the default display queue will be used.

roundtrip(*, queue: pywayland.client.eventqueue.EventQueue = None) → int¶

Block until all pending request are processed by the server

This function blocks until the server has processed all currently issued requests by sending a request to the display server and waiting for a reply before returning.

This function uses wl_display_dispatch_queue() internally. It is not allowed to call this function while the thread is being prepared for reading events, and doing so will cause a dead lock.

Note

This function may dispatch other events being received on the default queue.

Parameters:	queue (`EventQueue`) – The queue on which to run the roundtrip, if not given, uses the default queue.
Returns:	The number of dispatched events on success or -1 on failure

EventQueue¶

class pywayland.client.EventQueue(display)¶

A queue for wl_proxy object events.

Event queues allows the events on a display to be handled in a thread-safe manner. See Display for details.

destroy()¶

Destroy an event queue

Destroy the given event queue. Any pending event on that queue is discarded.

The wl_display object used to create the queue should not be destroyed until all event queues created with it are destroyed with this function.