Display(name_or_fd: int | str | None = None)¶
Represents a connection to the compositor
Displayobject represents a client connection to a Wayland compositor. The connection and the corresponding Wayland object are created with
Display.connect(). The display must be connected before it can be used. A connection is terminated using
Displayobject handles all the data sent from and to the compositor. When a
Proxymarshals a request, it will write its wire representation to the display’s write buffer. The data is sent to the compositor when the client calls
Incoming data is handled in two steps: queueing and dispatching. In the queue step, the data coming from the display fd is interpreted and added to a queue. On the dispatch step, the handler for the incoming event set by the client on the corresponding
Displayhas at least one event queue, called the default queue. Clients can create additional event queues with
Proxy’s to it. Events occurring in a particular proxy are always queued in its assigned queue. A client can ensure that a certain assumption, such as holding a lock or running from a given thread, is true when a proxy event handler is called by assigning that proxy to an event queue and making sure that this queue is only dispatched when the assumption holds.
The default queue is dispatched by calling
Display.dispatch(). This will dispatch any events queued on the default queue and attempt to read from the display fd if it’s empty. Events read are then queued on the appropriate queues according to the proxy assignment.
A user created queue is dispatched with
Display.dispatch_queue(). This function behaves exactly the same as
Display.dispatch()but it dispatches given queue instead of the default queue.
A real world example of event queue usage is Mesa’s implementation of glSwapBuffers() for the Wayland platform. This function might need to block until a frame callback is received, but dispatching the default queue could cause an event handler on the client to start drawing gain. This problem is solved using another event queue, so that only the events handled by the EGL code are dispatched during the block.
Parameters: name_or_fd (
str) – Either the name of the display to create or the file descriptor to connect the display to. If not specified, then use the default name, generally
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
Displaytakes 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_DISPLAYenvironment 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: bool = False, queue: EventQueue | None = 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.
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: EventQueue | None = 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: EventQueue | None = 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.
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
A queue for wl_proxy object events.
Event queues allows the events on a display to be handled in a thread-safe manner. See
Parameters: display (
Display) – The display object that the event queue is connected to.
destroy() → None¶
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.
Determine the state of the event queue