Provided by: python3-pywayland_0.4.18-4_amd64 
NAME
pywayland - pywayland Documentation
PyWayland provides Python bindings to the Wayland library, using pure Python by making calls through the
CFFI module. PyWayland supports Python >=3.6, including sufficiently new versions of PyPy 3. This is
currently a highly experimental package, and the usage is likely to change between releases. Check back
as development continues, contributions are always welcome!
Check out the different sections below for information on installing and running PyWayland. There is
also information on running and developing from source (feedback and contributions are always welcome on
the issue tracker). Finally, the module documentation is included.
DOCUMENTATION
Installation
To install PyWayland, you will need to have a base set of dependencies installed. This should be all the
configuration that is required to run the packaged version on PyPI. The additional steps to build and
install from source are outlined below.
If you have any problems with anything outlined here, feedback is greatly appreciated.
External Dependencies
In order to run PyWayland, you will need to have installed the Wayland libraries and headers such that
they can be found by CFFI. This can be done with the libwayland-dev apt package; however, note that it
is probably best to use the most recent version of Wayland available from the Wayland releases site, and
the pip package will try to track the most recent version.
You will also need to have the Python headers installed and a version of GCC to compile the cffi library.
The headers are typically available through the python-dev package.
Optionally, you can have installed the wayland-protocols package, also available from the Wayland
releases page. The package uploaded to PyPI will already have these protocols included, so this is only
needed if you plan on installing from source.
Installing with pip
Once the external dependencies are in place you should just be able to run:
$ pip install pywayland
Any additional unfulfilled dependencies should be downloaded.
Installing from Source
You can download and run PyWayland from source, which will not only give you the latest improvements and
fixes, but will let you build the protocol files against a different version than is available through
pip (the version of Wayland the protocol is compiled against is listed on the top of the PyPI page).
Getting the Source
You can download the most recent version of PyWayland from the git repository, or clone the repository
as:
$ git clone https://github.com/flacjacket/pywayland.git
Python Dependencies
PyWayland depends on a minimal set of dependencies. All Python version require cffi (to perform Wayland
library calls), which can be pip installed for non-PyPy installations. Note that PyPy platforms ship
with cffi.
Generating the Wayland Protocol
At this point, you have the base PyWayland module, which contains some core objects and objects specific
to client and server implementations. The client and server exchange messages defined in the Wayland
protocol, which is an XML file that ships with Wayland. The scanner parses this XML file and generates
the relevant objects.
If the Wayland protocol file is in the default location (/usr/share/wayland/wayland.xml) or can be found
with pkg-config, you should be able to build the protocol files without any problems:
$ python -m pywayland.scanner
This will output the protocol files to the directory ./pywayland/protocol/. The input file and the
output directory can be set from the command line options, see python -m pywayland.scanner -h for more
information.
Running PyWayland inplace
Once the protocol files are created, you can generate the cffi module. Note: this is only required if
you want to run from the source in place. If the libwayland header files are correctly installed, you
will just need to run:
$ python pywayland/ffi_build.py
At this point, you should be able to use the PyWayland library. You can check that you have everything
installed correctly by running the associated test-suite (note that you will also need pytest to run the
tests). Simply run:
$ pytest
from the root directory.
Installing PyWayland
The package can be installed from source using typical setup.py mechanisms:
$ python setup.py install
Additional arguments can be used to automatically generate the Wayland protocols for the standard Wayland
package (which will fail if it cannot run) and the wayland-protocols package (which will be attempted by
default, but will not raise an error if it fails).
If you have any problems or have any feedback, please report back to the issue tracker, contribution is
always welcome, see Contributing.
Contributing
Build Status Build Coverage
Contributions of any form are always welcome, whether it is general feedback on the use of PyWayland, bug
reports, or pull requests. All development is done through GitHub.
If you wish to develop PyWayland, it is recommended that you follow the outline given in Installing from
Source. A few things to be aware of when writing code:
• Continuous integration testing in done with Travis, and tests are run against all supported Python
versions (currently 3.6+ and PyPy 3). You can check that your changes pass locally by running py.test
from the root directory (this requires installing pytest). Currently, the tests also run with nose,
however, they may not always in the future.
• Code coverage is assessed using Coveralls. Currently, coverage is fairly low, any work to help this
would be greatly appreciated.
• Code quality is assessed in the tests with ruff, be sure any new code meets Python standards.
• Type annotations are included in much of the codebase and checked with mypy. Additional checks using
other type checkers are appreciated.
PyWayland Scanner
The PyWayland scanner parses the wayland.xml protocol definition file and outputs interfaces with the
events, requests, and enums defined by the protocol. See Scanner Modules for details on the scanner
implementation.
Command-line Invocation
If you have installed PyWayland, the scanner is placed in your path as pywayland-scanner.py. By default,
invoking the scanner reads in the XML file from /usr/share/wayland/wayland.xml and outputs the protocol
definitions to ./protocol/.
If you are running PyWayland from source, you can use the scanner in ./bin/pywayland-scanner.py. This
file sets the path to the current source directory and runs method used by the entry-point. Otherwise,
this functions the same as above.
Script Invocation
In addition to the command-line use, you can use the scanner from within Python scripts. This is done,
for example, when installing or building the docs to ensure the protocol modules are included in both.
For details on invoking the scanner module, see Scanner.
Module Reference
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.
Display
class pywayland.client.Display(name_or_fd: int | str | None = None)
Represents a connection to the compositor
A Display object 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 Display.disconnect().
A Display is also used as the Proxy for the pywayland.protocol.wayland.WlDisplay protocol object
on the compositor side.
A Display object handles all the data sent from and to the compositor. When a Proxy marshals 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 flush().
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 Proxy is called.
A Display has at least one event queue, called the default queue. Clients can create additional
event queues with Display.create_queue() and assign 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 (int or 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
wayland-0
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: 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.
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: 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.
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: 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.
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.
property destroyed: bool
Determine the state of the event queue
Server Modules
The base set of objects used by Wayland servers.
Client
class pywayland.server.Client(display: ~pywayland.server.display.Display | None = None, fd: int | None =
None, ptr: <MagicMock name='mock.ffi.ClientCData.__or__()' id='140737181137280'> = None)
Create a client for the given file descriptor
Given a file descriptor corresponding to one end of a socket, create a client struct and add the
new client to the compositors client list. At that point, the client is initialized and ready to
run, as if the client had connected to the servers listening socket. Alternatively, pass a pointer
to an existing client and use that instead of creating a new one.
The other end of the socket can be passed to connect() on the client side or used with the
WAYLAND_SOCKET environment variable on the client side.
Parameters
• display (Display) -- The display object
• fd (int) -- The file descriptor for the socket to the client
• ptr (ffi.ClientCData) -- A pointer to an existing wl_client
add_destroy_listener(listener: Listener) -> None
Add a listener for the destroy signal
Parameters
listener (Listener) -- The listener object
destroy() -> None
Destroy the client
flush() -> None
Flush pending events to the client
Events sent to clients are queued in a buffer and written to the socket later - typically
when the compositor has handled all requests and goes back to block in the event loop.
This function flushes all queued up events for a client immediately.
classmethod from_resource(resource: <MagicMock name='mock.ffi.ResourceCData'
id='140737181137280'>) -> Client
Look up the corresponding wl_client for a wl_resource
Parameters
resource (pywayland.protocol_core.Resource) -- The wl_resource
Returns
A Client instance.
get_credentials() -> tuple[int, int, int]
Return Unix credentials for the client.
This function returns the process ID, the user ID and the group ID for the given client.
The credentials come from getsockopt() with SO_PEERCRED, on the client socket fd.
get_object(object_id: int) -> Any
Look up an object in the client name space
This looks up an object in the client object name space by its object ID.
Parameters
object_id (int) -- The object id
Returns
The object, or None if there is not object for the given ID
Display
class pywayland.server.Display(ptr=None)
Create a Wayland Display object
add_shm_format(shm_format) -> None
Add support for a Shm pixel format
Add the specified format format to the list of formats the WlShm object advertises when a
client binds to it. Adding a format to the list means that clients will know that the
compositor supports this format and may use it for creating WlShm buffers. The compositor
must be able to handle the pixel format when a client requests it.
The compositor by default supports WL_SHM_FORMAT_ARGB8888 and WL_SHM_FORMAT_XRGB8888.
Parameters
shm_format (format) -- The shm pixel format to advertise
add_socket(name: str | None = None) -> str
Add a socket to Wayland display for the clients to connect.
This adds a Unix socket to Wayland display which can be used by clients to connect to
Wayland display.
If None is passed as name, then it would look for WAYLAND_DISPLAY environment variable for
the socket name. If WAYLAND_DISPLAY is not set, then default wayland-0 is used.
The Unix socket will be created in the directory pointed to by environment variable
XDG_RUNTIME_DIR. If XDG_RUNTIME_DIR is not set, then this function throws an exception.
The length of socket path, i.e., the path set in XDG_RUNTIME_DIR and the socket name, must
not exceed the maxium length of a Unix socket path. The function also fails if the user do
not have write permission in the XDG_RUNTIME_DIR path or if the socket name is already in
use.
Parameters
name (string or None) -- Name of the Unix socket.
destroy() -> None
Destroy Wayland display object.
This function emits the Display destroy signal, releases all the sockets added to this
display, free's all the globals associated with this display, free's memory of additional
shared memory formats and destroy the display object.
SEE ALSO:
Display.add_destroy_listener()
property destroyed: bool
Returns if the display has been destroyed
flush_clients() -> None
Flush client connections
get_event_loop() -> EventLoop
Get the event loop for the display
Returns
The EventLoop for the Display
get_serial() -> int
Get the current serial number
This function returns the most recent serial number, but does not increment it.
init_shm() -> None
Initialize shm for this display
next_serial() -> int
Get the next serial
This function increments the display serial number and returns the new value.
run() -> None
Run the display
terminate() -> None
Stop the display from running
EventLoop
class pywayland.server.EventLoop(display: Display | None = None)
An event loop to add events to
Returns an event loop. Either returns the event loop of a given display (which will trigger when
the Display is run), or creates a new event loop (which can be triggered by using
EventLoop.dispatch()).
Parameters
display (Display) -- The display to create the EventLoop on (default to None)
class FdMask(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1,
boundary=None)
add_destroy_listener(listener)
Add a listener for the destroy signal
Parameters
listener (Listener) -- The listener object
add_fd(fd, callback, mask=<FdMask.WL_EVENT_READABLE: 1>, data=None)
Add file descriptor callback
Triggers function call when file descriptor state matches the mask.
The callback should take three arguments:
• fd - file descriptor (int)
• mask - file descriptor mask (uint)
• data - any object
Parameters
• fd (int) -- File descriptor
• callback -- Callback function
• mask -- File descriptor mask
• data (object) -- User data to send to callback
Returns
EventSource for specified callback
SEE ALSO:
pywayland.server.eventloop.EventSource.check()
add_idle(callback, data=None)
Add idle callback
Parameters
• callback (function with callback void(void *data)) -- Callback function
• data -- User data to send to callback
Returns
EventSource for specified callback
add_signal(signal_number, callback, data=None)
Add signal callback
Triggers function call signal is received.
The callback should take three arguments:
• signal_number - signal (int)
• data - any object
Parameters
• signal_number (int) -- Signal number to trigger on
• callback -- Callback function
• data (object) -- User data to send to callback
Returns
EventSource for specified callback
add_timer(callback, data=None)
Add timer callback
Triggers function call after a specified time.
The callback should take one argument:
• data - any object
Parameters
• callback (function with callback int(void *data)) -- Callback function
• data (object) -- User data to send to callback
Returns
EventSource for specified callback
SEE ALSO:
pywayland.server.eventloop.EventSource.timer_update()
destroy()
Destroy the event loop
dispatch(timeout)
Dispatch callbacks on the event loop
dispatch_idle()
Dispatch idle callback on the event loop
Listener
class pywayland.server.Listener(function: Callable)
A single listener for Wayland signals
Provides the means to listen for wl_listener signal notifications. Many Wayland objects use
wl_listener for notification of significant events like object destruction.
Clients should create Listener objects manually and can register them as listeners to objects
destroy events using the object's .add_destroy_listener() method. A listener can only listen to
one signal at a time.
Parameters
function (callable) -- callback function for the Listener
remove() -> None
Remove the listener
Protocol Core Modules
Interface
Interface objects are only created as a subclass of Interface. The Interface class wraps the protocol
objects, and serves to initialize a set of parameters for the Interface and provide decorators for
defining Message objects on the interface.
class pywayland.protocol_core.Interface
Wrapper class for wl_wayland structs
Base class for interfaces that are defined by the wayland.xml class and generated by the scanner.
Sub-classes should use the InterfaceMeta metaclass, which will define subclass.events and
subclass.requests, the lists of the methods on this interface. These class variables are
populated by the Interface.event() and Interface.request() decorators.
classmethod event(*arguments: Argument, version: int | None = None) -> Callable
Decorator for interface events
Adds the decorated method to the list of events of the interface (server-side method).
Parameters
• signature (string) -- Encodes the types of the arguments to the decorated
function.
• types (list) -- List of the types of any objects included in the argument list,
None if otherwise.
classmethod request(*arguments: Argument, version: int | None = None)
Decorator for interface requests
Adds the decorated method to the list of requests of the interface (client-side method).
Parameters
• signature (string) -- Encodes the types of the arguments to the decorated
function.
• types (list) -- List of the types of any objects included in the argument list,
None if otherwise.
Interface Metaclass
This metaclass initializes lists for the requests and events on an interface and initializes a cdata
struct for the class.
class pywayland.protocol_core.interface.InterfaceMeta(name, bases, dct)
Metaclass for Interfaces
Initializes empty lists for events and requests for the given class.
Proxy
Proxy objects are not created directly, and users should generally not create a proxy class on their own.
Proxy classes give client side access to the interfaces defined by the Wayland protocol. Proxies are
returned from the server after calling protocol methods which return new_id's.
class pywayland.protocol_core.Proxy(ptr, display=None)
destroy() -> None
Frees the pointer associated with the Proxy
property destroyed: bool
Determine if proxy has been destroyed
Returns true if the proxy has been destroyed.
Resource
class pywayland.protocol_core.Resource(client, version: int | None = None, id: int = 0)
A server-side Interface object for the client
Not created directly, created from the Interface object.
Parameters
• client (Client or cdata for wl_client *) -- The client that the Resource is for
• version (int) -- The version to use for the Interface, uses current version if not
specified
• id (int) -- The id for the item
add_destroy_listener(listener) -> None
Add a listener for the destroy signal
Parameters
listener (Listener) -- The listener object
destroy() -> None
Destroy the Resource
Global
class pywayland.protocol_core.Global(display, version=None)
A server-side Interface object for the server
Not created directly, created from the Interface object.
Parameters
• display (Display) -- The display the object is created on
• version (int) -- The version to use for the Interface, uses current version if not
specified
destroy()
Destroy the global object
Message
Message objects are used to wrap the method calls on the protocol objects. The Message objects are added
to the Interface's as either requests (client-side functions) or events (server-side functions).
class pywayland.protocol_core.message.Message(func: Callable, arguments: list[Argument], version: int |
None)
Wrapper class for wl_message structs
Base class that correspond to the methods defined on an interface in the wayland.xml protocol, and
are generated by the scanner. Subclasses specify the type of method, whether it is a server-side
or client-side method.
Parameters
• func (function) -- The function that is represented by the message
• signature (string) -- The signature of the arguments of the message
• types (list) -- List of the types of any objects included in the argument list, None if
otherwise.
arguments_to_c(*args)
Create an array of wl_argument C structs
Generate the CFFI cdata array of wl_argument structs that correspond to the arguments of
the method as specified by the method signature.
Parameters
args (list) -- Input arguments
Returns
cdata union wl_argument [] of args
build_message_struct(wl_message_struct) -> tuple
Bulid the wl_message struct for this message
Parameters
wl_message_struct -- The wl_message cdata struct to use to build the message struct.
Returns
A tuple of elements which must be kept alive for the message struct to remain valid.
c_to_arguments(args_ptr)
Create a list of arguments
Generate the arguments of the method from a CFFI cdata array of wl_argument structs that
correspond to the arguments of the method as specified by the method signature.
Parameters
args_ptr (cdata union wl_argument []) -- Input arguments
Returns
list of args
Argument
class pywayland.protocol_core.argument.Argument(argument_type: 'ArgumentType', nullable: 'bool' = False,
interface: 'type[Interface] | None' = None)
ArgumentType
class pywayland.protocol_core.argument.ArgumentType(value, names=<not given>, *values, module=None,
qualname=None, type=None, start=1, boundary=None)
Protocol Modules
Wayland protocols built against Wayland 1.21.0 and Wayland Protocols 1.25.
wayland Module
WlBuffer
class pywayland.protocol.wayland.WlBuffer
Content for a WlSurface
A buffer provides the content for a WlSurface. Buffers are created through factory interfaces such
as WlShm, wp_linux_buffer_params (from the linux-dmabuf protocol extension) or similar. It has a
width and a height and can be attached to a WlSurface, but the mechanism by which a client
provides and updates the contents is defined by the buffer factory interface.
Color channels are assumed to be electrical rather than optical (in other words, encoded with a
transfer function) unless otherwise specified. If the buffer uses a format that has an alpha
channel, the alpha channel is assumed to be premultiplied into the electrical color channel values
(after transfer function encoding) unless otherwise specified.
Note, because WlBuffer objects are created from multiple independent factory interfaces, the
WlBuffer interface is frozen at version 1.
destroy() -> 'None'
Request -- opcode 0 (attached to Resource instance)
Destroy a buffer
Destroy a buffer. If and how you need to release the backing storage is defined by the
buffer factory interface.
For possible side-effects to a surface, see WlSurface.attach().
release() -> 'None'
Event -- opcode 0 (attached to Proxy instance)
Compositor releases buffer
Sent when this WlBuffer is no longer used by the compositor. The client is now free to
reuse or destroy this buffer and its backing storage.
If a client receives a release event before the frame callback requested in the same
WlSurface.commit() that attaches this WlBuffer to a surface, then the client is immediately
free to reuse the buffer and its backing storage, and does not need a second buffer for the
next surface content update. Typically this is possible, when the compositor maintains a
copy of the WlSurface contents, e.g. as a GL texture. This is an important optimization for
GL(ES) compositors with WlShm clients.
WlCallback
class pywayland.protocol.wayland.WlCallback
Callback object
Clients can handle the 'done' event to get notified when the related request is done.
Note, because WlCallback objects are created from multiple independent factory interfaces, the
WlCallback interface is frozen at version 1.
done(callback_data: 'int') -> 'None'
Event -- opcode 0 (attached to Proxy instance)
Done event
Notify the client when the related request is done.
Parameters
callback_data (ArgumentType.Uint) -- request-specific data for the callback
WlCompositor
class pywayland.protocol.wayland.WlCompositor
The compositor singleton
A compositor. This object is a singleton global. The compositor is in charge of combining the
contents of multiple surfaces into one displayable output.
create_surface() -> 'Proxy[WlSurface]'
Request -- opcode 0 (attached to Resource instance)
Create new surface
Ask the compositor to create a new surface.
Returns
WlSurface -- the new surface
create_region() -> 'Proxy[WlRegion]'
Request -- opcode 1 (attached to Resource instance)
Create new region
Ask the compositor to create a new region.
Returns
WlRegion -- the new region
WlDataDevice
class pywayland.protocol.wayland.WlDataDevice
Data transfer device
There is one WlDataDevice per seat which can be obtained from the global WlDataDeviceManager
singleton.
A WlDataDevice provides access to inter-client data transfer mechanisms such as copy-and-paste and
drag-and-drop.
start_drag(source: 'WlDataSource | None', origin: 'WlSurface', icon: 'WlSurface | None', serial:
'int') -> 'None'
Request -- opcode 0 (attached to Resource instance)
Start drag-and-drop operation
This request asks the compositor to start a drag-and-drop operation on behalf of the
client.
The source argument is the data source that provides the data for the eventual data
transfer. If source is NULL, enter, leave and motion events are sent only to the client
that initiated the drag and the client is expected to handle the data passing internally.
If source is destroyed, the drag-and-drop session will be cancelled.
The origin surface is the surface where the drag originates and the client must have an
active implicit grab that matches the serial.
The icon surface is an optional (can be NULL) surface that provides an icon to be moved
around with the cursor. Initially, the top-left corner of the icon surface is placed at
the cursor hotspot, but subsequent WlSurface.offset() requests can move the relative
position. Attach requests must be confirmed with WlSurface.commit() as usual. The icon
surface is given the role of a drag-and-drop icon. If the icon surface already has another
role, it raises a protocol error.
The input region is ignored for wl_surfaces with the role of a drag- and-drop icon.
The given source may not be used in any further set_selection or start_drag requests.
Attempting to reuse a previously-used source may send a used_source error.
Parameters
• source (WlDataSource or None) -- data source for the eventual transfer
• origin (WlSurface) -- surface where the drag originates
• icon (WlSurface or None) -- drag-and-drop icon surface
• serial (ArgumentType.Uint) -- serial number of the implicit grab on the origin
set_selection(source: 'WlDataSource | None', serial: 'int') -> 'None'
Request -- opcode 1 (attached to Resource instance)
Copy data to the selection
This request asks the compositor to set the selection to the data from the source on behalf
of the client.
To unset the selection, set the source to NULL.
The given source may not be used in any further set_selection or start_drag requests.
Attempting to reuse a previously-used source may send a used_source error.
Parameters
• source (WlDataSource or None) -- data source for the selection
• serial (ArgumentType.Uint) -- serial number of the event that triggered this
request
release() -> 'None'
Request -- opcode 2 (attached to Resource instance)
Destroy data device
This request destroys the data device.
data_offer(id: 'WlDataOffer') -> 'None'
Event -- opcode 0 (attached to Proxy instance)
Introduce a new WlDataOffer
The data_offer event introduces a new WlDataOffer object, which will subsequently be used
in either the data_device.enter event (for drag- and-drop) or the data_device.selection
event (for selections). Immediately following the data_device.data_offer event, the new
data_offer object will send out data_offer.offer events to describe the mime types it
offers.
Parameters
id (WlDataOffer) -- the new data_offer object
enter(serial: 'int', surface: 'WlSurface', x: 'float', y: 'float', id: 'WlDataOffer | None') ->
'None'
Event -- opcode 1 (attached to Proxy instance)
Initiate drag-and-drop session
This event is sent when an active drag-and-drop pointer enters a surface owned by the
client. The position of the pointer at enter time is provided by the x and y arguments, in
surface-local coordinates.
Parameters
• serial (ArgumentType.Uint) -- serial number of the enter event
• surface (WlSurface) -- client surface entered
• x (ArgumentType.Fixed) -- surface-local x coordinate
• y (ArgumentType.Fixed) -- surface-local y coordinate
• id (WlDataOffer or None) -- source data_offer object
leave() -> 'None'
Event -- opcode 2 (attached to Proxy instance)
End drag-and-drop session
This event is sent when the drag-and-drop pointer leaves the surface and the session ends.
The client must destroy the WlDataOffer introduced at enter time at this point.
motion(time: 'int', x: 'float', y: 'float') -> 'None'
Event -- opcode 3 (attached to Proxy instance)
Drag-and-drop session motion
This event is sent when the drag-and-drop pointer moves within the currently focused
surface. The new position of the pointer is provided by the x and y arguments, in
surface-local coordinates.
Parameters
• time (ArgumentType.Uint) -- timestamp with millisecond granularity
• x (ArgumentType.Fixed) -- surface-local x coordinate
• y (ArgumentType.Fixed) -- surface-local y coordinate
drop() -> 'None'
Event -- opcode 4 (attached to Proxy instance)
End drag-and-drop session successfully
The event is sent when a drag-and-drop operation is ended because the implicit grab is
removed.
The drag-and-drop destination is expected to honor the last action received through
WlDataOffer.action(), if the resulting action is "copy" or "move", the destination can
still perform WlDataOffer.receive() requests, and is expected to end all transfers with a
WlDataOffer.finish() request.
If the resulting action is "ask", the action will not be considered final. The
drag-and-drop destination is expected to perform one last WlDataOffer.set_actions()
request, or WlDataOffer.destroy() in order to cancel the operation.
selection(id: 'WlDataOffer | None') -> 'None'
Event -- opcode 5 (attached to Proxy instance)
Advertise new selection
The selection event is sent out to notify the client of a new WlDataOffer for the selection
for this device. The data_device.data_offer and the data_offer.offer events are sent out
immediately before this event to introduce the data offer object. The selection event is
sent to a client immediately before receiving keyboard focus and when a new selection is
set while the client has keyboard focus. The data_offer is valid until a new data_offer or
NULL is received or until the client loses keyboard focus. Switching surface with keyboard
focus within the same client doesn't mean a new selection will be sent. The client must
destroy the previous selection data_offer, if any, upon receiving this event.
Parameters
id (WlDataOffer or None) -- selection data_offer object
WlDataDeviceManager
class pywayland.protocol.wayland.WlDataDeviceManager
Data transfer interface
The WlDataDeviceManager is a singleton global object that provides access to inter-client data
transfer mechanisms such as copy-and-paste and drag-and-drop. These mechanisms are tied to a
WlSeat and this interface lets a client get a WlDataDevice corresponding to a WlSeat.
Depending on the version bound, the objects created from the bound WlDataDeviceManager object will
have different requirements for functioning properly. See WlDataSource.set_actions(),
WlDataOffer.accept() and WlDataOffer.finish() for details.
create_data_source() -> 'Proxy[WlDataSource]'
Request -- opcode 0 (attached to Resource instance)
Create a new data source
Create a new data source.
Returns
WlDataSource -- data source to create
get_data_device(seat: 'WlSeat') -> 'Proxy[WlDataDevice]'
Request -- opcode 1 (attached to Resource instance)
Create a new data device
Create a new data device for a given seat.
Parameters
seat (WlSeat) -- seat associated with the data device
Returns
WlDataDevice -- data device to create
WlDataOffer
class pywayland.protocol.wayland.WlDataOffer
Offer to transfer data
A WlDataOffer represents a piece of data offered for transfer by another client (the source
client). It is used by the copy-and-paste and drag-and-drop mechanisms. The offer describes the
different mime types that the data can be converted to and provides the mechanism for transferring
the data directly from the source client.
accept(serial: 'int', mime_type: 'str | None') -> 'None'
Request -- opcode 0 (attached to Resource instance)
Accept one of the offered mime types
Indicate that the client can accept the given mime type, or NULL for not accepted.
For objects of version 2 or older, this request is used by the client to give feedback
whether the client can receive the given mime type, or NULL if none is accepted; the
feedback does not determine whether the drag-and-drop operation succeeds or not.
For objects of version 3 or newer, this request determines the final result of the
drag-and-drop operation. If the end result is that no mime types were accepted, the
drag-and-drop operation will be cancelled and the corresponding drag source will receive
WlDataSource.cancelled(). Clients may still use this event in conjunction with
WlDataSource.action() for feedback.
Parameters
• serial (ArgumentType.Uint) -- serial number of the accept request
• mime_type (ArgumentType.String or None) -- mime type accepted by the client
receive(mime_type: 'str', fd: 'int') -> 'None'
Request -- opcode 1 (attached to Resource instance)
Request that the data is transferred
To transfer the offered data, the client issues this request and indicates the mime type it
wants to receive. The transfer happens through the passed file descriptor (typically
created with the pipe system call). The source client writes the data in the mime type
representation requested and then closes the file descriptor.
The receiving client reads from the read end of the pipe until EOF and then closes its end,
at which point the transfer is complete.
This request may happen multiple times for different mime types, both before and after
WlDataDevice.drop(). Drag-and-drop destination clients may preemptively fetch data or
examine it more closely to determine acceptance.
Parameters
• mime_type (ArgumentType.String) -- mime type desired by receiver
• fd (ArgumentType.FileDescriptor) -- file descriptor for data transfer
destroy() -> 'None'
Request -- opcode 2 (attached to Resource instance)
Destroy data offer
Destroy the data offer.
finish() -> 'None'
Request -- opcode 3 (attached to Resource instance)
The offer will no longer be used
Notifies the compositor that the drag destination successfully finished the drag-and-drop
operation.
Upon receiving this request, the compositor will emit WlDataSource.dnd_finished() on the
drag source client.
It is a client error to perform other requests than WlDataOffer.destroy() after this one.
It is also an error to perform this request after a NULL mime type has been set in
WlDataOffer.accept() or no action was received through WlDataOffer.action().
If WlDataOffer.finish() request is received for a non drag and drop operation, the
invalid_finish protocol error is raised.
set_actions(dnd_actions: 'int', preferred_action: 'int') -> 'None'
Request -- opcode 4 (attached to Resource instance)
Set the available/preferred drag-and-drop actions
Sets the actions that the destination side client supports for this operation. This request
may trigger the emission of WlDataSource.action() and WlDataOffer.action() events if the
compositor needs to change the selected action.
This request can be called multiple times throughout the drag-and-drop operation, typically
in response to WlDataDevice.enter() or WlDataDevice.motion() events.
This request determines the final result of the drag-and-drop operation. If the end result
is that no action is accepted, the drag source will receive WlDataSource.cancelled().
The dnd_actions argument must contain only values expressed in the
WlDataDeviceManager.dnd_actions() enum, and the preferred_action argument must only contain
one of those values set, otherwise it will result in a protocol error.
While managing an "ask" action, the destination drag-and-drop client may perform further
WlDataOffer.receive() requests, and is expected to perform one last
WlDataOffer.set_actions() request with a preferred action other than "ask" (and optionally
WlDataOffer.accept()) before requesting WlDataOffer.finish(), in order to convey the action
selected by the user. If the preferred action is not in the WlDataOffer.source_actions()
mask, an error will be raised.
If the "ask" action is dismissed (e.g. user cancellation), the client is expected to
perform WlDataOffer.destroy() right away.
This request can only be made on drag-and-drop offers, a protocol error will be raised
otherwise.
Parameters
• dnd_actions (ArgumentType.Uint) -- actions supported by the destination client
• preferred_action (ArgumentType.Uint) -- action preferred by the destination client
offer(mime_type: 'str') -> 'None'
Event -- opcode 0 (attached to Proxy instance)
Advertise offered mime type
Sent immediately after creating the WlDataOffer object. One event per offered mime type.
Parameters
mime_type (ArgumentType.String) -- offered mime type
source_actions(source_actions: 'int') -> 'None'
Event -- opcode 1 (attached to Proxy instance)
Notify the source-side available actions
This event indicates the actions offered by the data source. It will be sent immediately
after creating the WlDataOffer object, or anytime the source side changes its offered
actions through WlDataSource.set_actions().
Parameters
source_actions (ArgumentType.Uint) -- actions offered by the data source
action(dnd_action: 'int') -> 'None'
Event -- opcode 2 (attached to Proxy instance)
Notify the selected action
This event indicates the action selected by the compositor after matching the
source/destination side actions. Only one action (or none) will be offered here.
This event can be emitted multiple times during the drag-and-drop operation in response to
destination side action changes through WlDataOffer.set_actions().
This event will no longer be emitted after WlDataDevice.drop() happened on the drag-
and-drop destination, the client must honor the last action received, or the last preferred
one set through WlDataOffer.set_actions() when handling an "ask" action.
Compositors may also change the selected action on the fly, mainly in response to keyboard
modifier changes during the drag-and-drop operation.
The most recent action received is always the valid one. Prior to receiving
WlDataDevice.drop(), the chosen action may change (e.g. due to keyboard modifiers being
pressed). At the time of receiving WlDataDevice.drop() the drag-and-drop destination must
honor the last action received.
Action changes may still happen after WlDataDevice.drop(), especially on "ask" actions,
where the drag-and-drop destination may choose another action afterwards. Action changes
happening at this stage are always the result of inter-client negotiation, the compositor
shall no longer be able to induce a different action.
Upon "ask" actions, it is expected that the drag-and-drop destination may potentially
choose a different action and/or mime type, based on WlDataOffer.source_actions() and
finally chosen by the user (e.g. popping up a menu with the available options). The final
WlDataOffer.set_actions() and WlDataOffer.accept() requests must happen before the call to
WlDataOffer.finish().
Parameters
dnd_action (ArgumentType.Uint) -- action selected by the compositor
WlDataSource
class pywayland.protocol.wayland.WlDataSource
Offer to transfer data
The WlDataSource object is the source side of a WlDataOffer. It is created by the source client in
a data transfer and provides a way to describe the offered data and a way to respond to requests
to transfer the data.
offer(mime_type: 'str') -> 'None'
Request -- opcode 0 (attached to Resource instance)
Add an offered mime type
This request adds a mime type to the set of mime types advertised to targets. Can be
called several times to offer multiple types.
Parameters
mime_type (ArgumentType.String) -- mime type offered by the data source
destroy() -> 'None'
Request -- opcode 1 (attached to Resource instance)
Destroy the data source
Destroy the data source.
set_actions(dnd_actions: 'int') -> 'None'
Request -- opcode 2 (attached to Resource instance)
Set the available drag-and-drop actions
Sets the actions that the source side client supports for this operation. This request may
trigger WlDataSource.action() and WlDataOffer.action() events if the compositor needs to
change the selected action.
The dnd_actions argument must contain only values expressed in the
WlDataDeviceManager.dnd_actions() enum, otherwise it will result in a protocol error.
This request must be made once only, and can only be made on sources used in drag-and-drop,
so it must be performed before WlDataDevice.start_drag(). Attempting to use the source
other than for drag-and-drop will raise a protocol error.
Parameters
dnd_actions (ArgumentType.Uint) -- actions supported by the data source
target(mime_type: 'str | None') -> 'None'
Event -- opcode 0 (attached to Proxy instance)
A target accepts an offered mime type
Sent when a target accepts pointer_focus or motion events. If a target does not accept any
of the offered types, type is NULL.
Used for feedback during drag-and-drop.
Parameters
mime_type (ArgumentType.String or None) -- mime type accepted by the target
send(mime_type: 'str', fd: 'int') -> 'None'
Event -- opcode 1 (attached to Proxy instance)
Send the data
Request for data from the client. Send the data as the specified mime type over the passed
file descriptor, then close it.
Parameters
• mime_type (ArgumentType.String) -- mime type for the data
• fd (ArgumentType.FileDescriptor) -- file descriptor for the data
cancelled() -> 'None'
Event -- opcode 2 (attached to Proxy instance)
Selection was cancelled
This data source is no longer valid. There are several reasons why this could happen:
• The data source has been replaced by another data source.
• The drag-and-drop operation was performed, but the drop destination did not accept any of
the mime types offered through WlDataSource.target().
• The drag-and-drop operation was performed, but the drop destination did not select any of
the actions present in the mask offered through WlDataSource.action().
• The drag-and-drop operation was performed but didn't happen over a surface.
• The compositor cancelled the drag-and-drop operation (e.g. compositor dependent timeouts
to avoid stale drag-and-drop transfers).
The client should clean up and destroy this data source.
For objects of version 2 or older, WlDataSource.cancelled() will only be emitted if the
data source was replaced by another data source.
dnd_drop_performed() -> 'None'
Event -- opcode 3 (attached to Proxy instance)
The drag-and-drop operation physically finished
The user performed the drop action. This event does not indicate acceptance,
WlDataSource.cancelled() may still be emitted afterwards if the drop destination does not
accept any mime type.
However, this event might however not be received if the compositor cancelled the
drag-and-drop operation before this event could happen.
Note that the data_source may still be used in the future and should not be destroyed here.
dnd_finished() -> 'None'
Event -- opcode 4 (attached to Proxy instance)
The drag-and-drop operation concluded
The drop destination finished interoperating with this data source, so the client is now
free to destroy this data source and free all associated data.
If the action used to perform the operation was "move", the source can now delete the
transferred data.
action(dnd_action: 'int') -> 'None'
Event -- opcode 5 (attached to Proxy instance)
Notify the selected action
This event indicates the action selected by the compositor after matching the
source/destination side actions. Only one action (or none) will be offered here.
This event can be emitted multiple times during the drag-and-drop operation, mainly in
response to destination side changes through WlDataOffer.set_actions(), and as the data
device enters/leaves surfaces.
It is only possible to receive this event after WlDataSource.dnd_drop_performed() if the
drag-and-drop operation ended in an "ask" action, in which case the final
WlDataSource.action() event will happen immediately before WlDataSource.dnd_finished().
Compositors may also change the selected action on the fly, mainly in response to keyboard
modifier changes during the drag-and-drop operation.
The most recent action received is always the valid one. The chosen action may change
alongside negotiation (e.g. an "ask" action can turn into a "move" operation), so the
effects of the final action must always be applied in WlDataOffer.dnd_finished().
Clients can trigger cursor surface changes from this point, so they reflect the current
action.
Parameters
dnd_action (ArgumentType.Uint) -- action selected by the compositor
WlDisplay
class pywayland.protocol.wayland.WlDisplay
Core global object
The core global object. This is a special singleton object. It is used for internal Wayland
protocol features.
sync() -> 'Proxy[WlCallback]'
Request -- opcode 0 (attached to Resource instance)
Asynchronous roundtrip
The sync request asks the server to emit the 'done' event on the returned WlCallback
object. Since requests are handled in-order and events are delivered in-order, this can be
used as a barrier to ensure all previous requests and the resulting events have been
handled.
The object returned by this request will be destroyed by the compositor after the callback
is fired and as such the client must not attempt to use it after that point.
The callback_data passed in the callback is undefined and should be ignored.
Returns
WlCallback -- callback object for the sync request
get_registry() -> 'Proxy[WlRegistry]'
Request -- opcode 1 (attached to Resource instance)
Get global registry object
This request creates a registry object that allows the client to list and bind the global
objects available from the compositor.
It should be noted that the server side resources consumed in response to a get_registry
request can only be released when the client disconnects, not when the client side proxy is
destroyed. Therefore, clients should invoke get_registry as infrequently as possible to
avoid wasting memory.
Returns
WlRegistry -- global registry object
error(object_id: 'Any', code: 'int', message: 'str') -> 'None'
Event -- opcode 0 (attached to Proxy instance)
Fatal error event
The error event is sent out when a fatal (non-recoverable) error has occurred. The
object_id argument is the object where the error occurred, most often in response to a
request to that object. The code identifies the error and is defined by the object
interface. As such, each interface defines its own set of error codes. The message is a
brief description of the error, for (debugging) convenience.
Parameters
• object_id (ArgumentType.Object) -- object where the error occurred
• code (ArgumentType.Uint) -- error code
• message (ArgumentType.String) -- error description
delete_id(id: 'int') -> 'None'
Event -- opcode 1 (attached to Proxy instance)
Acknowledge object id deletion
This event is used internally by the object ID management logic. When a client deletes an
object that it had created, the server will send this event to acknowledge that it has seen
the delete request. When the client receives this event, it will know that it can safely
reuse the object ID.
Parameters
id (ArgumentType.Uint) -- deleted object ID
WlKeyboard
class pywayland.protocol.wayland.WlKeyboard
Keyboard input device
The WlKeyboard interface represents one or more keyboards associated with a seat.
Each WlKeyboard has the following logical state:
• an active surface (possibly null),
• the keys currently logically down,
• the active modifiers,
• the active group.
By default, the active surface is null, the keys currently logically down are empty, the active
modifiers and the active group are 0.
release() -> 'None'
Request -- opcode 0 (attached to Resource instance)
Release the keyboard object
keymap(format: 'int', fd: 'int', size: 'int') -> 'None'
Event -- opcode 0 (attached to Proxy instance)
Keyboard mapping
This event provides a file descriptor to the client which can be memory-mapped in read-only
mode to provide a keyboard mapping description.
From version 7 onwards, the fd must be mapped with MAP_PRIVATE by the recipient, as
MAP_SHARED may fail.
Parameters
• format (ArgumentType.Uint) -- keymap format
• fd (ArgumentType.FileDescriptor) -- keymap file descriptor
• size (ArgumentType.Uint) -- keymap size, in bytes
enter(serial: 'int', surface: 'WlSurface', keys: 'list') -> 'None'
Event -- opcode 1 (attached to Proxy instance)
Enter event
Notification that this seat's keyboard focus is on a certain surface.
The compositor must send the WlKeyboard.modifiers() event after this event.
In the WlKeyboard logical state, this event sets the active surface to the surface argument
and the keys currently logically down to the keys in the keys argument. The compositor must
not send this event if the WlKeyboard already had an active surface immediately before this
event.
Parameters
• serial (ArgumentType.Uint) -- serial number of the enter event
• surface (WlSurface) -- surface gaining keyboard focus
• keys (ArgumentType.Array) -- the keys currently logically down
leave(serial: 'int', surface: 'WlSurface') -> 'None'
Event -- opcode 2 (attached to Proxy instance)
Leave event
Notification that this seat's keyboard focus is no longer on a certain surface.
The leave notification is sent before the enter notification for the new focus.
In the WlKeyboard logical state, this event resets all values to their defaults. The
compositor must not send this event if the active surface of the WlKeyboard was not equal
to the surface argument immediately before this event.
Parameters
• serial (ArgumentType.Uint) -- serial number of the leave event
• surface (WlSurface) -- surface that lost keyboard focus
key(serial: 'int', time: 'int', key: 'int', state: 'int') -> 'None'
Event -- opcode 3 (attached to Proxy instance)
Key event
A key was pressed or released. The time argument is a timestamp with millisecond
granularity, with an undefined base.
The key is a platform-specific key code that can be interpreted by feeding it to the
keyboard mapping (see the keymap event).
If this event produces a change in modifiers, then the resulting WlKeyboard.modifiers()
event must be sent after this event.
In the WlKeyboard logical state, this event adds the key to the keys currently logically
down (if the state argument is pressed) or removes the key from the keys currently
logically down (if the state argument is released). The compositor must not send this event
if the WlKeyboard did not have an active surface immediately before this event. The
compositor must not send this event if state is pressed (resp. released) and the key was
already logically down (resp. was not logically down) immediately before this event.
Parameters
• serial (ArgumentType.Uint) -- serial number of the key event
• time (ArgumentType.Uint) -- timestamp with millisecond granularity
• key (ArgumentType.Uint) -- key that produced the event
• state (ArgumentType.Uint) -- physical state of the key
modifiers(serial: 'int', mods_depressed: 'int', mods_latched: 'int', mods_locked: 'int', group:
'int') -> 'None'
Event -- opcode 4 (attached to Proxy instance)
Modifier and group state
Notifies clients that the modifier and/or group state has changed, and it should update its
local state.
The compositor may send this event without a surface of the client having keyboard focus,
for example to tie modifier information to pointer focus instead. If a modifier event with
pressed modifiers is sent without a prior enter event, the client can assume the modifier
state is valid until it receives the next WlKeyboard.modifiers() event. In order to reset
the modifier state again, the compositor can send a WlKeyboard.modifiers() event with no
pressed modifiers.
In the WlKeyboard logical state, this event updates the modifiers and group.
Parameters
• serial (ArgumentType.Uint) -- serial number of the modifiers event
• mods_depressed (ArgumentType.Uint) -- depressed modifiers
• mods_latched (ArgumentType.Uint) -- latched modifiers
• mods_locked (ArgumentType.Uint) -- locked modifiers
• group (ArgumentType.Uint) -- keyboard layout
repeat_info(rate: 'int', delay: 'int') -> 'None'
Event -- opcode 5 (attached to Proxy instance)
Repeat rate and delay
Informs the client about the keyboard's repeat rate and delay.
This event is sent as soon as the WlKeyboard object has been created, and is guaranteed to
be received by the client before any key press event.
Negative values for either rate or delay are illegal. A rate of zero will disable any
repeating (regardless of the value of delay).
This event can be sent later on as well with a new value if necessary, so clients should
continue listening for the event past the creation of WlKeyboard.
Parameters
• rate (ArgumentType.Int) -- the rate of repeating keys in characters per second
• delay (ArgumentType.Int) -- delay in milliseconds since key down until repeating
starts
WlOutput
class pywayland.protocol.wayland.WlOutput
Compositor output region
An output describes part of the compositor geometry. The compositor works in the 'compositor
coordinate system' and an output corresponds to a rectangular area in that space that is actually
visible. This typically corresponds to a monitor that displays part of the compositor space.
This object is published as global during start up, or when a monitor is hotplugged.
release() -> 'None'
Request -- opcode 0 (attached to Resource instance)
Release the output object
Using this request a client can tell the server that it is not going to use the output
object anymore.
geometry(x: 'int', y: 'int', physical_width: 'int', physical_height: 'int', subpixel: 'int', make:
'str', model: 'str', transform: 'int') -> 'None'
Event -- opcode 0 (attached to Proxy instance)
Properties of the output
The geometry event describes geometric properties of the output. The event is sent when
binding to the output object and whenever any of the properties change.
The physical size can be set to zero if it doesn't make sense for this output (e.g. for
projectors or virtual outputs).
The geometry event will be followed by a done event (starting from version 2).
Clients should use WlSurface.preferred_buffer_transform() instead of the transform
advertised by this event to find the preferred buffer transform to use for a surface.
Note: WlOutput only advertises partial information about the output position and
identification. Some compositors, for instance those not implementing a desktop-style
output layout or those exposing virtual outputs, might fake this information. Instead of
using x and y, clients should use xdg_output.logical_position. Instead of using make and
model, clients should use name and description.
Parameters
• x (ArgumentType.Int) -- x position within the global compositor space
• y (ArgumentType.Int) -- y position within the global compositor space
• physical_width (ArgumentType.Int) -- width in millimeters of the output
• physical_height (ArgumentType.Int) -- height in millimeters of the output
• subpixel (ArgumentType.Int) -- subpixel orientation of the output
• make (ArgumentType.String) -- textual description of the manufacturer
• model (ArgumentType.String) -- textual description of the model
• transform (ArgumentType.Int) -- additional transformation applied to buffer
contents during presentation
mode(flags: 'int', width: 'int', height: 'int', refresh: 'int') -> 'None'
Event -- opcode 1 (attached to Proxy instance)
Advertise available modes for the output
The mode event describes an available mode for the output.
The event is sent when binding to the output object and there will always be one mode, the
current mode. The event is sent again if an output changes mode, for the mode that is now
current. In other words, the current mode is always the last mode that was received with
the current flag set.
Non-current modes are deprecated. A compositor can decide to only advertise the current
mode and never send other modes. Clients should not rely on non-current modes.
The size of a mode is given in physical hardware units of the output device. This is not
necessarily the same as the output size in the global compositor space. For instance, the
output may be scaled, as described in WlOutput.scale(), or transformed, as described in
WlOutput.transform(). Clients willing to retrieve the output size in the global compositor
space should use xdg_output.logical_size instead.
The vertical refresh rate can be set to zero if it doesn't make sense for this output (e.g.
for virtual outputs).
The mode event will be followed by a done event (starting from version 2).
Clients should not use the refresh rate to schedule frames. Instead, they should use the
WlSurface.frame() event or the presentation-time protocol.
Note: this information is not always meaningful for all outputs. Some compositors, such as
those exposing virtual outputs, might fake the refresh rate or the size.
Parameters
• flags (ArgumentType.Uint) -- bitfield of mode flags
• width (ArgumentType.Int) -- width of the mode in hardware units
• height (ArgumentType.Int) -- height of the mode in hardware units
• refresh (ArgumentType.Int) -- vertical refresh rate in mHz
done() -> 'None'
Event -- opcode 2 (attached to Proxy instance)
Sent all information about output
This event is sent after all other properties have been sent after binding to the output
object and after any other property changes done after that. This allows changes to the
output properties to be seen as atomic, even if they happen via multiple events.
scale(factor: 'int') -> 'None'
Event -- opcode 3 (attached to Proxy instance)
Output scaling properties
This event contains scaling geometry information that is not in the geometry event. It may
be sent after binding the output object or if the output scale changes later. The
compositor will emit a non-zero, positive value for scale. If it is not sent, the client
should assume a scale of 1.
A scale larger than 1 means that the compositor will automatically scale surface buffers by
this amount when rendering. This is used for very high resolution displays where
applications rendering at the native resolution would be too small to be legible.
Clients should use WlSurface.preferred_buffer_scale() instead of this event to find the
preferred buffer scale to use for a surface.
The scale event will be followed by a done event.
Parameters
factor (ArgumentType.Int) -- scaling factor of output
name(name: 'str') -> 'None'
Event -- opcode 4 (attached to Proxy instance)
Name of this output
Many compositors will assign user-friendly names to their outputs, show them to the user,
allow the user to refer to an output, etc. The client may wish to know this name as well to
offer the user similar behaviors.
The name is a UTF-8 string with no convention defined for its contents. Each name is
unique among all WlOutput globals. The name is only guaranteed to be unique for the
compositor instance.
The same output name is used for all clients for a given WlOutput global. Thus, the name
can be shared across processes to refer to a specific WlOutput global.
The name is not guaranteed to be persistent across sessions, thus cannot be used to
reliably identify an output in e.g. configuration files.
Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc. However, do not assume that the
name is a reflection of an underlying DRM connector, X11 connection, etc.
The name event is sent after binding the output object. This event is only sent once per
output object, and the name does not change over the lifetime of the WlOutput global.
Compositors may re-use the same output name if the WlOutput global is destroyed and
re-created later. Compositors should avoid re- using the same name if possible.
The name event will be followed by a done event.
Parameters
name (ArgumentType.String) -- output name
description(description: 'str') -> 'None'
Event -- opcode 5 (attached to Proxy instance)
Human-readable description of this output
Many compositors can produce human-readable descriptions of their outputs. The client may
wish to know this description as well, e.g. for output selection purposes.
The description is a UTF-8 string with no convention defined for its contents. The
description is not guaranteed to be unique among all WlOutput globals. Examples might
include 'Foocorp 11" Display' or 'Virtual X11 output via :1'.
The description event is sent after binding the output object and whenever the description
changes. The description is optional, and may not be sent at all.
The description event will be followed by a done event.
Parameters
description (ArgumentType.String) -- output description
WlPointer
class pywayland.protocol.wayland.WlPointer
Pointer input device
The WlPointer interface represents one or more input devices, such as mice, which control the
pointer location and pointer_focus of a seat.
The WlPointer 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.
set_cursor(serial: 'int', surface: 'WlSurface | None', hotspot_x: 'int', hotspot_y: 'int') ->
'None'
Request -- opcode 0 (attached to Resource instance)
Set the pointer surface
Set the pointer surface, i.e., the surface that contains the pointer image (cursor). This
request gives the surface the role of a cursor. If the surface already has another role, it
raises a protocol error.
The cursor actually changes only 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 WlSurface.offset() requests to the pointer surface, hotspot_x and hotspot_y are
decremented by the x and y parameters passed to the request. The offset must be applied by
WlSurface.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 input region is ignored for wl_surfaces with the role of a cursor. When the use as a
cursor ends, the WlSurface is unmapped.
The serial parameter must match the latest WlPointer.enter() serial number sent to the
client. Otherwise the request will be ignored.
Parameters
• serial (ArgumentType.Uint) -- serial number of the enter event
• surface (WlSurface or None) -- pointer surface
• hotspot_x (ArgumentType.Int) -- surface-local x coordinate
• hotspot_y (ArgumentType.Int) -- surface-local y coordinate
release() -> 'None'
Request -- opcode 1 (attached to Resource instance)
Release the pointer object
Using this request a client can tell the server that it is not going to use the pointer
object anymore.
This request destroys the pointer proxy object, so clients must not call
wl_pointer_destroy() after using this request.
enter(serial: 'int', surface: 'WlSurface', surface_x: 'float', surface_y: 'float') -> 'None'
Event -- opcode 0 (attached to Proxy instance)
Enter event
Notification that this seat's pointer is focused on a certain surface.
When a 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.
Parameters
• serial (ArgumentType.Uint) -- serial number of the enter event
• surface (WlSurface) -- surface entered by the pointer
• surface_x (ArgumentType.Fixed) -- surface-local x coordinate
• surface_y (ArgumentType.Fixed) -- surface-local y coordinate
leave(serial: 'int', surface: 'WlSurface') -> 'None'
Event -- opcode 1 (attached to Proxy instance)
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.
Parameters
• serial (ArgumentType.Uint) -- serial number of the leave event
• surface (WlSurface) -- surface left by the pointer
motion(time: 'int', surface_x: 'float', surface_y: 'float') -> 'None'
Event -- opcode 2 (attached to Proxy instance)
Pointer motion event
Notification of pointer location change. The arguments surface_x and surface_y are the
location relative to the focused surface.
Parameters
• time (ArgumentType.Uint) -- timestamp with millisecond granularity
• surface_x (ArgumentType.Fixed) -- surface-local x coordinate
• surface_y (ArgumentType.Fixed) -- surface-local y coordinate
button(serial: 'int', time: 'int', button: 'int', state: 'int') -> 'None'
Event -- opcode 3 (attached to Proxy instance)
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.
The button is a button code as defined in the Linux kernel's linux/input-event-codes.h
header file, e.g. BTN_LEFT.
Any 16-bit button code value is reserved for future additions to the kernel's event code
list. All other button codes above 0xFFFF are currently undefined but may be used in future
versions of this protocol.
Parameters
• serial (ArgumentType.Uint) -- serial number of the button event
• time (ArgumentType.Uint) -- timestamp with millisecond granularity
• button (ArgumentType.Uint) -- button that produced the event
• state (ArgumentType.Uint) -- physical state of the button
axis(time: 'int', axis: 'int', value: 'float') -> 'None'
Event -- opcode 4 (attached to Proxy instance)
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, a client can transform its content relative to the scroll distance.
Parameters
• time (ArgumentType.Uint) -- timestamp with millisecond granularity
• axis (ArgumentType.Uint) -- axis type
• value (ArgumentType.Fixed) -- length of vector in surface-local coordinate space
frame() -> 'None'
Event -- opcode 5 (attached to Proxy instance)
End of a pointer event sequence
Indicates the end of a set of events that logically belong together. A client is expected
to accumulate the data in all events within the frame before proceeding.
All WlPointer events before a WlPointer.frame() event belong logically together. For
example, in a diagonal scroll motion the compositor will send an optional
WlPointer.axis_source() event, two WlPointer.axis() events (horizontal and vertical) and
finally a WlPointer.frame() event. The client may use this information to calculate a
diagonal vector for scrolling.
When multiple WlPointer.axis() events occur within the same frame, the motion vector is the
combined motion of all events. When a WlPointer.axis() and a WlPointer.axis_stop() event
occur within the same frame, this indicates that axis movement in one axis has stopped but
continues in the other axis. When multiple WlPointer.axis_stop() events occur within the
same frame, this indicates that these axes stopped in the same instance.
A WlPointer.frame() event is sent for every logical event group, even if the group only
contains a single WlPointer event. Specifically, a client may get a sequence: motion,
frame, button, frame, axis, frame, axis_stop, frame.
The WlPointer.enter() and WlPointer.leave() events are logical events generated by the
compositor and not the hardware. These events are also grouped by a WlPointer.frame(). When
a pointer moves from one surface to another, a compositor should group the
WlPointer.leave() event within the same WlPointer.frame(). However, a client must not rely
on WlPointer.leave() and WlPointer.enter() being in the same WlPointer.frame().
Compositor-specific policies may require the WlPointer.leave() and WlPointer.enter() event
being split across multiple WlPointer.frame() groups.
axis_source(axis_source: 'int') -> 'None'
Event -- opcode 6 (attached to Proxy instance)
Axis source event
Source information for scroll and other axes.
This event does not occur on its own. It is sent before a WlPointer.frame() event and
carries the source information for all events within that frame.
The source specifies how this event was generated. If the source is
WlPointer.axis_source().finger, a WlPointer.axis_stop() event will be sent when the user
lifts the finger off the device.
If the source is WlPointer.axis_source().wheel, WlPointer.axis_source().wheel_tilt or
WlPointer.axis_source().continuous, a WlPointer.axis_stop() event may or may not be sent.
Whether a compositor sends an axis_stop event for these sources is hardware- specific and
implementation-dependent; clients must not rely on receiving an axis_stop event for these
scroll sources and should treat scroll sequences from these scroll sources as unterminated
by default.
This event is optional. If the source is unknown for a particular axis event sequence, no
event is sent. Only one WlPointer.axis_source() event is permitted per frame.
The order of WlPointer.axis_discrete() and WlPointer.axis_source() is not guaranteed.
Parameters
axis_source (ArgumentType.Uint) -- source of the axis event
axis_stop(time: 'int', axis: 'int') -> 'None'
Event -- opcode 7 (attached to Proxy instance)
Axis stop event
Stop notification for scroll and other axes.
For some WlPointer.axis_source() types, a WlPointer.axis_stop() event is sent to notify a
client that the axis sequence has terminated. This enables the client to implement kinetic
scrolling. See the WlPointer.axis_source() documentation for information on when this event
may be generated.
Any WlPointer.axis() events with the same axis_source after this event should be considered
as the start of a new axis motion.
The timestamp is to be interpreted identical to the timestamp in the WlPointer.axis()
event. The timestamp value may be the same as a preceding WlPointer.axis() event.
Parameters
• time (ArgumentType.Uint) -- timestamp with millisecond granularity
• axis (ArgumentType.Uint) -- the axis stopped with this event
axis_discrete(axis: 'int', discrete: 'int') -> 'None'
Event -- opcode 8 (attached to Proxy instance)
Axis click event
Discrete step information for scroll and other axes.
This event carries the axis value of the WlPointer.axis() event in discrete steps (e.g.
mouse wheel clicks).
This event is deprecated with WlPointer version 8 - this event is not sent to clients
supporting version 8 or later.
This event does not occur on its own, it is coupled with a WlPointer.axis() event that
represents this axis value on a continuous scale. The protocol guarantees that each
axis_discrete event is always followed by exactly one axis event with the same axis number
within the same WlPointer.frame(). Note that the protocol allows for other events to occur
between the axis_discrete and its coupled axis event, including other axis_discrete or axis
events. A WlPointer.frame() must not contain more than one axis_discrete event per axis
type.
This event is optional; continuous scrolling devices like two-finger scrolling on touchpads
do not have discrete steps and do not generate this event.
The discrete value carries the directional information. e.g. a value of -2 is two steps
towards the negative direction of this axis.
The axis number is identical to the axis number in the associated axis event.
The order of WlPointer.axis_discrete() and WlPointer.axis_source() is not guaranteed.
Parameters
• axis (ArgumentType.Uint) -- axis type
• discrete (ArgumentType.Int) -- number of steps
axis_value120(axis: 'int', value120: 'int') -> 'None'
Event -- opcode 9 (attached to Proxy instance)
Axis high-resolution scroll event
Discrete high-resolution scroll information.
This event carries high-resolution wheel scroll information, with each multiple of 120
representing one logical scroll step (a wheel detent). For example, an axis_value120 of 30
is one quarter of a logical scroll step in the positive direction, a value120 of -240 are
two logical scroll steps in the negative direction within the same hardware event. Clients
that rely on discrete scrolling should accumulate the value120 to multiples of 120 before
processing the event.
The value120 must not be zero.
This event replaces the WlPointer.axis_discrete() event in clients supporting WlPointer
version 8 or later.
Where a WlPointer.axis_source() event occurs in the same WlPointer.frame(), the axis source
applies to this event.
The order of WlPointer.axis_value120 and WlPointer.axis_source() is not guaranteed.
Parameters
• axis (ArgumentType.Uint) -- axis type
• value120 (ArgumentType.Int) -- scroll distance as fraction of 120
axis_relative_direction(axis: 'int', direction: 'int') -> 'None'
Event -- opcode 10 (attached to Proxy instance)
Axis relative physical direction event
Relative directional information of the entity causing the axis motion.
For a WlPointer.axis() event, the WlPointer.axis_relative_direction() event specifies the
movement direction of the entity causing the WlPointer.axis() event. For example: - if a
user's fingers on a touchpad move down and this causes a WlPointer.axis() vertical_scroll
down event, the physical direction is 'identical' - if a user's fingers on a touchpad
move down and this causes a WlPointer.axis() vertical_scroll up scroll up event ('natural
scrolling'), the physical direction is 'inverted'.
A client may use this information to adjust scroll motion of components. Specifically,
enabling natural scrolling causes the content to change direction compared to traditional
scrolling. Some widgets like volume control sliders should usually match the physical
direction regardless of whether natural scrolling is active. This event enables clients to
match the scroll direction of a widget to the physical direction.
This event does not occur on its own, it is coupled with a WlPointer.axis() event that
represents this axis value. The protocol guarantees that each axis_relative_direction event
is always followed by exactly one axis event with the same axis number within the same
WlPointer.frame(). Note that the protocol allows for other events to occur between the
axis_relative_direction and its coupled axis event.
The axis number is identical to the axis number in the associated axis event.
The order of WlPointer.axis_relative_direction(), WlPointer.axis_discrete() and
WlPointer.axis_source() is not guaranteed.
Parameters
• axis (ArgumentType.Uint) -- axis type
• direction (ArgumentType.Uint) -- physical direction relative to axis motion
WlRegion
class pywayland.protocol.wayland.WlRegion
Region interface
A region object describes an area.
Region objects are used to describe the opaque and input regions of a surface.
destroy() -> 'None'
Request -- opcode 0 (attached to Resource instance)
Destroy region
Destroy the region. This will invalidate the object ID.
add(x: 'int', y: 'int', width: 'int', height: 'int') -> 'None'
Request -- opcode 1 (attached to Resource instance)
Add rectangle to region
Add the specified rectangle to the region.
Parameters
• x (ArgumentType.Int) -- region-local x coordinate
• y (ArgumentType.Int) -- region-local y coordinate
• width (ArgumentType.Int) -- rectangle width
• height (ArgumentType.Int) -- rectangle height
subtract(x: 'int', y: 'int', width: 'int', height: 'int') -> 'None'
Request -- opcode 2 (attached to Resource instance)
Subtract rectangle from region
Subtract the specified rectangle from the region.
Parameters
• x (ArgumentType.Int) -- region-local x coordinate
• y (ArgumentType.Int) -- region-local y coordinate
• width (ArgumentType.Int) -- rectangle width
• height (ArgumentType.Int) -- rectangle height
WlRegistry
class pywayland.protocol.wayland.WlRegistry
Global registry object
The singleton global registry object. The server has a number of global objects that are
available to all clients. These objects typically represent an actual object in the server (for
example, an input device) or they are singleton objects that provide extension functionality.
When a client creates a registry object, the registry object will emit a global event for each
global currently in the registry. Globals come and go as a result of device or monitor hotplugs,
reconfiguration or other events, and the registry will send out global and global_remove events to
keep the client up to date with the changes. To mark the end of the initial burst of events, the
client can use the WlDisplay.sync() request immediately after calling WlDisplay.get_registry().
A client can bind to a global object by using the bind request. This creates a client-side handle
that lets the object emit events to the client and lets the client invoke requests on the object.
bind(name: 'int', interface: 'type[T]', version: 'int') -> 'Proxy[T]'
Request -- opcode 0 (attached to Resource instance)
Bind an object to the display
Binds a new, client-created object to the server using the specified name as the
identifier.
Parameters
• name (ArgumentType.Uint) -- unique numeric name of the object
• interface (string) -- Interface name
• version (int) -- Interface version
Returns
pywayland.client.proxy.Proxy of specified Interface -- bounded object
global_(name: 'int', interface: 'str', version: 'int') -> 'None'
Event -- opcode 0 (attached to Proxy instance)
Announce global object
Notify the client of global objects.
The event notifies the client that a global object with the given name is now available,
and it implements the given version of the given interface.
Parameters
• name (ArgumentType.Uint) -- numeric name of the global object
• interface (ArgumentType.String) -- interface implemented by the object
• version (ArgumentType.Uint) -- interface version
global_remove(name: 'int') -> 'None'
Event -- opcode 1 (attached to Proxy instance)
Announce removal of global object
Notify the client of removed global objects.
This event notifies the client that the global identified by name is no longer available.
If the client bound to the global using the bind request, the client should now destroy
that object.
The object remains valid and requests to the object will be ignored until the client
destroys it, to avoid races between the global going away and a client sending a request to
it.
Parameters
name (ArgumentType.Uint) -- numeric name of the global object
WlSeat
class pywayland.protocol.wayland.WlSeat
Group of input devices
A seat is a group of keyboards, pointer and touch devices. This object is published as a global
during start up, or when such a device is hot plugged. A seat typically has a pointer and
maintains a keyboard focus and a pointer focus.
get_pointer() -> 'Proxy[WlPointer]'
Request -- opcode 0 (attached to Resource instance)
Return pointer object
The ID provided will be initialized to the WlPointer interface for this seat.
This request only takes effect if the seat has the pointer capability, or has had the
pointer capability in the past. It is a protocol violation to issue this request on a seat
that has never had the pointer capability. The missing_capability error will be sent in
this case.
Returns
WlPointer -- seat pointer
get_keyboard() -> 'Proxy[WlKeyboard]'
Request -- opcode 1 (attached to Resource instance)
Return keyboard object
The ID provided will be initialized to the WlKeyboard interface for this seat.
This request only takes effect if the seat has the keyboard capability, or has had the
keyboard capability in the past. It is a protocol violation to issue this request on a seat
that has never had the keyboard capability. The missing_capability error will be sent in
this case.
Returns
WlKeyboard -- seat keyboard
get_touch() -> 'Proxy[WlTouch]'
Request -- opcode 2 (attached to Resource instance)
Return touch object
The ID provided will be initialized to the WlTouch interface for this seat.
This request only takes effect if the seat has the touch capability, or has had the touch
capability in the past. It is a protocol violation to issue this request on a seat that has
never had the touch capability. The missing_capability error will be sent in this case.
Returns
WlTouch -- seat touch interface
release() -> 'None'
Request -- opcode 3 (attached to Resource instance)
Release the seat object
Using this request a client can tell the server that it is not going to use the seat object
anymore.
capabilities(capabilities: 'int') -> 'None'
Event -- opcode 0 (attached to Proxy instance)
Seat capabilities changed
This is emitted whenever a seat gains or loses the pointer, keyboard or touch capabilities.
The argument is a capability enum containing the complete set of capabilities this seat
has.
When the pointer capability is added, a client may create a WlPointer object using the
WlSeat.get_pointer() request. This object will receive pointer events until the capability
is removed in the future.
When the pointer capability is removed, a client should destroy the WlPointer objects
associated with the seat where the capability was removed, using the WlPointer.release()
request. No further pointer events will be received on these objects.
In some compositors, if a seat regains the pointer capability and a client has a previously
obtained WlPointer object of version 4 or less, that object may start sending pointer
events again. This behavior is considered a misinterpretation of the intended behavior and
must not be relied upon by the client. WlPointer objects of version 5 or later must not
send events if created before the most recent event notifying the client of an added
pointer capability.
The above behavior also applies to WlKeyboard and WlTouch with the keyboard and touch
capabilities, respectively.
Parameters
capabilities (ArgumentType.Uint) -- capabilities of the seat
name(name: 'str') -> 'None'
Event -- opcode 1 (attached to Proxy instance)
Unique identifier for this seat
In a multi-seat configuration the seat name can be used by clients to help identify which
physical devices the seat represents.
The seat name is a UTF-8 string with no convention defined for its contents. Each name is
unique among all WlSeat globals. The name is only guaranteed to be unique for the current
compositor instance.
The same seat names are used for all clients. Thus, the name can be shared across processes
to refer to a specific WlSeat global.
The name event is sent after binding to the seat global. This event is only sent once per
seat object, and the name does not change over the lifetime of the WlSeat global.
Compositors may re-use the same seat name if the WlSeat global is destroyed and re-created
later.
Parameters
name (ArgumentType.String) -- seat identifier
WlShell
class pywayland.protocol.wayland.WlShell
Create desktop-style surfaces
This interface is implemented by servers that provide desktop-style user interfaces.
It allows clients to associate a WlShellSurface with a basic surface.
Note! This protocol is deprecated and not intended for production use. For desktop-style user
interfaces, use xdg_shell. Compositors and clients should not implement this interface.
get_shell_surface(surface: 'WlSurface') -> 'Proxy[WlShellSurface]'
Request -- opcode 0 (attached to Resource instance)
Create a shell surface from a surface
Create a shell surface for an existing surface. This gives the WlSurface the role of a
shell surface. If the WlSurface already has another role, it raises a protocol error.
Only one shell surface can be associated with a given surface.
Parameters
surface (WlSurface) -- surface to be given the shell surface role
Returns
WlShellSurface -- shell surface to create
WlShellSurface
class pywayland.protocol.wayland.WlShellSurface
Desktop-style metadata interface
An interface that may be implemented by a WlSurface, for implementations that provide a
desktop-style user interface.
It provides requests to treat surfaces like toplevel, fullscreen or popup windows, move, resize or
maximize them, associate metadata like title and class, etc.
On the server side the object is automatically destroyed when the related WlSurface is destroyed.
On the client side, wl_shell_surface_destroy() must be called before destroying the WlSurface
object.
pong(serial: 'int') -> 'None'
Request -- opcode 0 (attached to Resource instance)
Respond to a ping event
A client must respond to a ping event with a pong request or the client may be deemed
unresponsive.
Parameters
serial (ArgumentType.Uint) -- serial number of the ping event
move(seat: 'WlSeat', serial: 'int') -> 'None'
Request -- opcode 1 (attached to Resource instance)
Start an interactive move
Start a pointer-driven move of the surface.
This request must be used in response to a button press event. The server may ignore move
requests depending on the state of the surface (e.g. fullscreen or maximized).
Parameters
• seat (WlSeat) -- seat whose pointer is used
• serial (ArgumentType.Uint) -- serial number of the implicit grab on the pointer
resize(seat: 'WlSeat', serial: 'int', edges: 'int') -> 'None'
Request -- opcode 2 (attached to Resource instance)
Start an interactive resize
Start a pointer-driven resizing of the surface.
This request must be used in response to a button press event. The server may ignore resize
requests depending on the state of the surface (e.g. fullscreen or maximized).
Parameters
• seat (WlSeat) -- seat whose pointer is used
• serial (ArgumentType.Uint) -- serial number of the implicit grab on the pointer
• edges (ArgumentType.Uint) -- which edge or corner is being dragged
set_toplevel() -> 'None'
Request -- opcode 3 (attached to Resource instance)
Make the surface a toplevel surface
Map the surface as a toplevel surface.
A toplevel surface is not fullscreen, maximized or transient.
set_transient(parent: 'WlSurface', x: 'int', y: 'int', flags: 'int') -> 'None'
Request -- opcode 4 (attached to Resource instance)
Make the surface a transient surface
Map the surface relative to an existing surface.
The x and y arguments specify the location of the upper left corner of the surface relative
to the upper left corner of the parent surface, in surface-local coordinates.
The flags argument controls details of the transient behaviour.
Parameters
• parent (WlSurface) -- parent surface
• x (ArgumentType.Int) -- surface-local x coordinate
• y (ArgumentType.Int) -- surface-local y coordinate
• flags (ArgumentType.Uint) -- transient surface behavior
set_fullscreen(method: 'int', framerate: 'int', output: 'WlOutput | None') -> 'None'
Request -- opcode 5 (attached to Resource instance)
Make the surface a fullscreen surface
Map the surface as a fullscreen surface.
If an output parameter is given then the surface will be made fullscreen on that output. If
the client does not specify the output then the compositor will apply its policy - usually
choosing the output on which the surface has the biggest surface area.
The client may specify a method to resolve a size conflict between the output size and the
surface size - this is provided through the method parameter.
The framerate parameter is used only when the method is set to "driver", to indicate the
preferred framerate. A value of 0 indicates that the client does not care about framerate.
The framerate is specified in mHz, that is framerate of 60000 is 60Hz.
A method of "scale" or "driver" implies a scaling operation of the surface, either via a
direct scaling operation or a change of the output mode. This will override any kind of
output scaling, so that mapping a surface with a buffer size equal to the mode can fill the
screen independent of buffer_scale.
A method of "fill" means we don't scale up the buffer, however any output scale is applied.
This means that you may run into an edge case where the application maps a buffer with the
same size of the output mode but buffer_scale 1 (thus making a surface larger than the
output). In this case it is allowed to downscale the results to fit the screen.
The compositor must reply to this request with a configure event with the dimensions for
the output on which the surface will be made fullscreen.
Parameters
• method (ArgumentType.Uint) -- method for resolving size conflict
• framerate (ArgumentType.Uint) -- framerate in mHz
• output (WlOutput or None) -- output on which the surface is to be fullscreen
set_popup(seat: 'WlSeat', serial: 'int', parent: 'WlSurface', x: 'int', y: 'int', flags: 'int') ->
'None'
Request -- opcode 6 (attached to Resource instance)
Make the surface a popup surface
Map the surface as a popup.
A popup surface is a transient surface with an added pointer grab.
An existing implicit grab will be changed to owner-events mode, and the popup grab will
continue after the implicit grab ends (i.e. releasing the mouse button does not cause the
popup to be unmapped).
The popup grab continues until the window is destroyed or a mouse button is pressed in any
other client's window. A click in any of the client's surfaces is reported as normal,
however, clicks in other clients' surfaces will be discarded and trigger the callback.
The x and y arguments specify the location of the upper left corner of the surface relative
to the upper left corner of the parent surface, in surface-local coordinates.
Parameters
• seat (WlSeat) -- seat whose pointer is used
• serial (ArgumentType.Uint) -- serial number of the implicit grab on the pointer
• parent (WlSurface) -- parent surface
• x (ArgumentType.Int) -- surface-local x coordinate
• y (ArgumentType.Int) -- surface-local y coordinate
• flags (ArgumentType.Uint) -- transient surface behavior
set_maximized(output: 'WlOutput | None') -> 'None'
Request -- opcode 7 (attached to Resource instance)
Make the surface a maximized surface
Map the surface as a maximized surface.
If an output parameter is given then the surface will be maximized on that output. If the
client does not specify the output then the compositor will apply its policy - usually
choosing the output on which the surface has the biggest surface area.
The compositor will reply with a configure event telling the expected new surface size. The
operation is completed on the next buffer attach to this surface.
A maximized surface typically fills the entire output it is bound to, except for desktop
elements such as panels. This is the main difference between a maximized shell surface and
a fullscreen shell surface.
The details depend on the compositor implementation.
Parameters
output (WlOutput or None) -- output on which the surface is to be maximized
set_title(title: 'str') -> 'None'
Request -- opcode 8 (attached to Resource instance)
Set surface title
Set a short title for the surface.
This string may be used to identify the surface in a task bar, window list, or other user
interface elements provided by the compositor.
The string must be encoded in UTF-8.
Parameters
title (ArgumentType.String) -- surface title
set_class(class_: 'str') -> 'None'
Request -- opcode 9 (attached to Resource instance)
Set surface class
Set a class for the surface.
The surface class identifies the general class of applications to which the surface
belongs. A common convention is to use the file name (or the full path if it is a
non-standard location) of the application's .desktop file as the class.
Parameters
class (ArgumentType.String) -- surface class
ping(serial: 'int') -> 'None'
Event -- opcode 0 (attached to Proxy instance)
Ping client
Ping a client to check if it is receiving events and sending requests. A client is
expected to reply with a pong request.
Parameters
serial (ArgumentType.Uint) -- serial number of the ping
configure(edges: 'int', width: 'int', height: 'int') -> 'None'
Event -- opcode 1 (attached to Proxy instance)
Suggest resize
The configure event asks the client to resize its surface.
The size is a hint, in the sense that the client is free to ignore it if it doesn't resize,
pick a smaller size (to satisfy aspect ratio or resize in steps of NxM pixels).
The edges parameter provides a hint about how the surface was resized. The client may use
this information to decide how to adjust its content to the new size (e.g. a scrolling area
might adjust its content position to leave the viewable content unmoved).
The client is free to dismiss all but the last configure event it received.
The width and height arguments specify the size of the window in surface-local coordinates.
Parameters
• edges (ArgumentType.Uint) -- how the surface was resized
• width (ArgumentType.Int) -- new width of the surface
• height (ArgumentType.Int) -- new height of the surface
popup_done() -> 'None'
Event -- opcode 2 (attached to Proxy instance)
Popup interaction is done
The popup_done event is sent out when a popup grab is broken, that is, when the user clicks
a surface that doesn't belong to the client owning the popup surface.
WlShm
class pywayland.protocol.wayland.WlShm
Shared memory support
A singleton global object that provides support for shared memory.
Clients can create WlShmPool objects using the create_pool request.
On binding the WlShm object one or more format events are emitted to inform clients about the
valid pixel formats that can be used for buffers.
create_pool(fd: 'int', size: 'int') -> 'Proxy[WlShmPool]'
Request -- opcode 0 (attached to Resource instance)
Create a shm pool
Create a new WlShmPool object.
The pool can be used to create shared memory based buffer objects. The server will mmap
size bytes of the passed file descriptor, to use as backing memory for the pool.
Parameters
• fd (ArgumentType.FileDescriptor) -- file descriptor for the pool
• size (ArgumentType.Int) -- pool size, in bytes
Returns
WlShmPool -- pool to create
release() -> 'None'
Request -- opcode 1 (attached to Resource instance)
Release the shm object
Using this request a client can tell the server that it is not going to use the shm object
anymore.
Objects created via this interface remain unaffected.
format(format: 'int') -> 'None'
Event -- opcode 0 (attached to Proxy instance)
Pixel format description
Informs the client about a valid pixel format that can be used for buffers. Known formats
include argb8888 and xrgb8888.
Parameters
format (ArgumentType.Uint) -- buffer pixel format
WlShmPool
class pywayland.protocol.wayland.WlShmPool
A shared memory pool
The WlShmPool object encapsulates a piece of memory shared between the compositor and client.
Through the WlShmPool object, the client can allocate shared memory WlBuffer objects. All objects
created through the same pool share the same underlying mapped memory. Reusing the mapped memory
avoids the setup/teardown overhead and is useful when interactively resizing a surface or for many
small buffers.
create_buffer(offset: 'int', width: 'int', height: 'int', stride: 'int', format: 'int') ->
'Proxy[WlBuffer]'
Request -- opcode 0 (attached to Resource instance)
Create a buffer from the pool
Create a WlBuffer object from the pool.
The buffer is created offset bytes into the pool and has width and height as specified.
The stride argument specifies the number of bytes from the beginning of one row to the
beginning of the next. The format is the pixel format of the buffer and must be one of
those advertised through the WlShm.format() event.
A buffer will keep a reference to the pool it was created from so it is valid to destroy
the pool immediately after creating a buffer from it.
Parameters
• offset (ArgumentType.Int) -- buffer byte offset within the pool
• width (ArgumentType.Int) -- buffer width, in pixels
• height (ArgumentType.Int) -- buffer height, in pixels
• stride (ArgumentType.Int) -- number of bytes from the beginning of one row to the
beginning of the next row
• format (ArgumentType.Uint) -- buffer pixel format
Returns
WlBuffer -- buffer to create
destroy() -> 'None'
Request -- opcode 1 (attached to Resource instance)
Destroy the pool
Destroy the shared memory pool.
The mmapped memory will be released when all buffers that have been created from this pool
are gone.
resize(size: 'int') -> 'None'
Request -- opcode 2 (attached to Resource instance)
Change the size of the pool mapping
This request will cause the server to remap the backing memory for the pool from the file
descriptor passed when the pool was created, but using the new size. This request can only
be used to make the pool bigger.
This request only changes the amount of bytes that are mmapped by the server and does not
touch the file corresponding to the file descriptor passed at creation time. It is the
client's responsibility to ensure that the file is at least as big as the new pool size.
Parameters
size (ArgumentType.Int) -- new size of the pool, in bytes
WlSubcompositor
class pywayland.protocol.wayland.WlSubcompositor
Sub-surface compositing
The global interface exposing sub-surface compositing capabilities. A WlSurface, that has
sub-surfaces associated, is called the parent surface. Sub-surfaces can be arbitrarily nested and
create a tree of sub-surfaces.
The root surface in a tree of sub-surfaces is the main surface. The main surface cannot be a
sub-surface, because sub-surfaces must always have a parent.
A main surface with its sub-surfaces forms a (compound) window. For window management purposes,
this set of WlSurface objects is to be considered as a single window, and it should also behave as
such.
The aim of sub-surfaces is to offload some of the compositing work within a window from clients to
the compositor. A prime example is a video player with decorations and video in separate WlSurface
objects. This should allow the compositor to pass YUV video buffer processing to dedicated overlay
hardware when possible.
destroy() -> 'None'
Request -- opcode 0 (attached to Resource instance)
Unbind from the subcompositor interface
Informs the server that the client will not be using this protocol object anymore. This
does not affect any other objects, WlSubsurface objects included.
get_subsurface(surface: 'WlSurface', parent: 'WlSurface') -> 'Proxy[WlSubsurface]'
Request -- opcode 1 (attached to Resource instance)
Give a surface the role sub-surface
Create a sub-surface interface for the given surface, and associate it with the given
parent surface. This turns a plain WlSurface into a sub-surface.
The to-be sub-surface must not already have another role, and it must not have an existing
WlSubsurface object. Otherwise the bad_surface protocol error is raised.
Adding sub-surfaces to a parent is a double-buffered operation on the parent (see
WlSurface.commit()). The effect of adding a sub-surface becomes visible on the next time
the state of the parent surface is applied.
The parent surface must not be one of the child surface's descendants, and the parent must
be different from the child surface, otherwise the bad_parent protocol error is raised.
This request modifies the behaviour of WlSurface.commit() request on the sub- surface, see
the documentation on WlSubsurface interface.
Parameters
• surface (WlSurface) -- the surface to be turned into a sub-surface
• parent (WlSurface) -- the parent surface
Returns
WlSubsurface -- the new sub- surface object ID
WlSubsurface
class pywayland.protocol.wayland.WlSubsurface
Sub-surface interface to a WlSurface
An additional interface to a WlSurface object, which has been made a sub-surface. A sub-surface
has one parent surface. A sub-surface's size and position are not limited to that of the parent.
Particularly, a sub-surface is not automatically clipped to its parent's area.
A sub-surface becomes mapped, when a non-NULL WlBuffer is applied and the parent surface is
mapped. The order of which one happens first is irrelevant. A sub-surface is hidden if the parent
becomes hidden, or if a NULL WlBuffer is applied. These rules apply recursively through the tree
of surfaces.
The behaviour of a WlSurface.commit() request on a sub-surface depends on the sub-surface's mode.
The possible modes are synchronized and desynchronized, see methods WlSubsurface.set_sync() and
WlSubsurface.set_desync(). Synchronized mode caches the WlSurface state to be applied when the
parent's state gets applied, and desynchronized mode applies the pending WlSurface state directly.
A sub- surface is initially in the synchronized mode.
Sub-surfaces also have another kind of state, which is managed by WlSubsurface requests, as
opposed to WlSurface requests. This state includes the sub-surface position relative to the parent
surface (WlSubsurface.set_position()), and the stacking order of the parent and its sub-surfaces
(WlSubsurface.place_above() and .place_below). This state is applied when the parent surface's
WlSurface state is applied, regardless of the sub-surface's mode. As the exception, set_sync and
set_desync are effective immediately.
The main surface can be thought to be always in desynchronized mode, since it does not have a
parent in the sub-surfaces sense.
Even if a sub-surface is in desynchronized mode, it will behave as in synchronized mode, if its
parent surface behaves as in synchronized mode. This rule is applied recursively throughout the
tree of surfaces. This means, that one can set a sub-surface into synchronized mode, and then
assume that all its child and grand-child sub-surfaces are synchronized, too, without explicitly
setting them.
Destroying a sub-surface takes effect immediately. If you need to synchronize the removal of a
sub-surface to the parent surface update, unmap the sub-surface first by attaching a NULL
WlBuffer, update parent, and then destroy the sub-surface.
If the parent WlSurface object is destroyed, the sub-surface is unmapped.
A sub-surface never has the keyboard focus of any seat.
The WlSurface.offset() request is ignored: clients must use set_position instead to move the
sub-surface.
destroy() -> 'None'
Request -- opcode 0 (attached to Resource instance)
Remove sub-surface interface
The sub-surface interface is removed from the WlSurface object that was turned into a
sub-surface with a WlSubcompositor.get_subsurface() request. The wl_surface's association
to the parent is deleted. The WlSurface is unmapped immediately.
set_position(x: 'int', y: 'int') -> 'None'
Request -- opcode 1 (attached to Resource instance)
Reposition the sub-surface
This schedules a sub-surface position change. The sub-surface will be moved so that its
origin (top left corner pixel) will be at the location x, y of the parent surface
coordinate system. The coordinates are not restricted to the parent surface area. Negative
values are allowed.
The scheduled coordinates will take effect whenever the state of the parent surface is
applied.
If more than one set_position request is invoked by the client before the commit of the
parent surface, the position of a new request always replaces the scheduled position from
any previous request.
The initial position is 0, 0.
Parameters
• x (ArgumentType.Int) -- x coordinate in the parent surface
• y (ArgumentType.Int) -- y coordinate in the parent surface
place_above(sibling: 'WlSurface') -> 'None'
Request -- opcode 2 (attached to Resource instance)
Restack the sub-surface
This sub-surface is taken from the stack, and put back just above the reference surface,
changing the z-order of the sub-surfaces. The reference surface must be one of the sibling
surfaces, or the parent surface. Using any other surface, including this sub-surface, will
cause a protocol error.
The z-order is double-buffered. Requests are handled in order and applied immediately to a
pending state. The final pending state is copied to the active state the next time the
state of the parent surface is applied.
A new sub-surface is initially added as the top-most in the stack of its siblings and
parent.
Parameters
sibling (WlSurface) -- the reference surface
place_below(sibling: 'WlSurface') -> 'None'
Request -- opcode 3 (attached to Resource instance)
Restack the sub-surface
The sub-surface is placed just below the reference surface. See WlSubsurface.place_above().
Parameters
sibling (WlSurface) -- the reference surface
set_sync() -> 'None'
Request -- opcode 4 (attached to Resource instance)
Set sub-surface to synchronized mode
Change the commit behaviour of the sub-surface to synchronized mode, also described as the
parent dependent mode.
In synchronized mode, WlSurface.commit() on a sub-surface will accumulate the committed
state in a cache, but the state will not be applied and hence will not change the
compositor output. The cached state is applied to the sub-surface immediately after the
parent surface's state is applied. This ensures atomic updates of the parent and all its
synchronized sub-surfaces. Applying the cached state will invalidate the cache, so further
parent surface commits do not (re-)apply old state.
See WlSubsurface for the recursive effect of this mode.
set_desync() -> 'None'
Request -- opcode 5 (attached to Resource instance)
Set sub-surface to desynchronized mode
Change the commit behaviour of the sub-surface to desynchronized mode, also described as
independent or freely running mode.
In desynchronized mode, WlSurface.commit() on a sub-surface will apply the pending state
directly, without caching, as happens normally with a WlSurface. Calling WlSurface.commit()
on the parent surface has no effect on the sub-surface's WlSurface state. This mode allows
a sub-surface to be updated on its own.
If cached state exists when WlSurface.commit() is called in desynchronized mode, the
pending state is added to the cached state, and applied as a whole. This invalidates the
cache.
Note: even if a sub-surface is set to desynchronized, a parent sub- surface may override it
to behave as synchronized. For details, see WlSubsurface.
If a surface's parent surface behaves as desynchronized, then the cached state is applied
on set_desync.
WlSurface
class pywayland.protocol.wayland.WlSurface
An onscreen surface
A surface is a rectangular area that may be displayed on zero or more outputs, and shown any
number of times at the compositor's discretion. They can present wl_buffers, receive user input,
and define a local coordinate system.
The size of a surface (and relative positions on it) is described in surface-local coordinates,
which may differ from the buffer coordinates of the pixel content, in case a buffer_transform or a
buffer_scale is used.
A surface without a "role" is fairly useless: a compositor does not know where, when or how to
present it. The role is the purpose of a WlSurface. Examples of roles are a cursor for a pointer
(as set by WlPointer.set_cursor()), a drag icon (WlDataDevice.start_drag()), a sub-surface (‐
WlSubcompositor.get_subsurface()), and a window as defined by a shell protocol (e.g.
WlShell.get_shell_surface()).
A surface can have only one role at a time. Initially a WlSurface does not have a role. Once a
WlSurface is given a role, it is set permanently for the whole lifetime of the WlSurface object.
Giving the current role again is allowed, unless explicitly forbidden by the relevant interface
specification.
Surface roles are given by requests in other interfaces such as WlPointer.set_cursor(). The
request should explicitly mention that this request gives a role to a WlSurface. Often, this
request also creates a new protocol object that represents the role and adds additional
functionality to WlSurface. When a client wants to destroy a WlSurface, they must destroy this
role object before the WlSurface, otherwise a defunct_role_object error is sent.
Destroying the role object does not remove the role from the WlSurface, but it may stop the
WlSurface from "playing the role". For instance, if a WlSubsurface object is destroyed, the
WlSurface it was created for will be unmapped and forget its position and z-order. It is allowed
to create a WlSubsurface for the same WlSurface again, but it is not allowed to use the WlSurface
as a cursor (cursor is a different role than sub- surface, and role switching is not allowed).
destroy() -> 'None'
Request -- opcode 0 (attached to Resource instance)
Delete surface
Deletes the surface and invalidates its object ID.
attach(buffer: 'WlBuffer | None', x: 'int', y: 'int') -> 'None'
Request -- opcode 1 (attached to Resource instance)
Set the surface contents
Set a buffer as the content of this surface.
The new size of the surface is calculated based on the buffer size transformed by the
inverse buffer_transform and the inverse buffer_scale. This means that at commit time the
supplied buffer size must be an integer multiple of the buffer_scale. If that's not the
case, an invalid_size error is sent.
The x and y arguments specify the location of the new pending buffer's upper left corner,
relative to the current buffer's upper left corner, in surface-local coordinates. In other
words, the x and y, combined with the new surface size define in which directions the
surface's size changes. Setting anything other than 0 as x and y arguments is discouraged,
and should instead be replaced with using the separate WlSurface.offset() request.
When the bound WlSurface version is 5 or higher, passing any non-zero x or y is a protocol
violation, and will result in an 'invalid_offset' error being raised. The x and y arguments
are ignored and do not change the pending state. To achieve equivalent semantics, use
WlSurface.offset().
Surface contents are double-buffered state, see WlSurface.commit().
The initial surface contents are void; there is no content. WlSurface.attach() assigns the
given WlBuffer as the pending WlBuffer. WlSurface.commit() makes the pending WlBuffer the
new surface contents, and the size of the surface becomes the size calculated from the
WlBuffer, as described above. After commit, there is no pending buffer until the next
attach.
Committing a pending WlBuffer allows the compositor to read the pixels in the WlBuffer. The
compositor may access the pixels at any time after the WlSurface.commit() request. When the
compositor will not access the pixels anymore, it will send the WlBuffer.release() event.
Only after receiving WlBuffer.release(), the client may reuse the WlBuffer. A WlBuffer that
has been attached and then replaced by another attach instead of committed will not receive
a release event, and is not used by the compositor.
If a pending WlBuffer has been committed to more than one WlSurface, the delivery of
WlBuffer.release() events becomes undefined. A well behaved client should not rely on
WlBuffer.release() events in this case. Alternatively, a client could create multiple
WlBuffer objects from the same backing storage or use wp_linux_buffer_release.
Destroying the WlBuffer after WlBuffer.release() does not change the surface contents.
Destroying the WlBuffer before WlBuffer.release() is allowed as long as the underlying
buffer storage isn't re-used (this can happen e.g. on client process termination). However,
if the client destroys the WlBuffer before receiving the WlBuffer.release() event and
mutates the underlying buffer storage, the surface contents become undefined immediately.
If WlSurface.attach() is sent with a NULL WlBuffer, the following WlSurface.commit() will
remove the surface content.
If a pending WlBuffer has been destroyed, the result is not specified. Many compositors are
known to remove the surface content on the following WlSurface.commit(), but this behaviour
is not universal. Clients seeking to maximise compatibility should not destroy pending
buffers and should ensure that they explicitly remove content from surfaces, even after
destroying buffers.
Parameters
• buffer (WlBuffer or None) -- buffer of surface contents
• x (ArgumentType.Int) -- surface-local x coordinate
• y (ArgumentType.Int) -- surface-local y coordinate
damage(x: 'int', y: 'int', width: 'int', height: 'int') -> 'None'
Request -- opcode 2 (attached to Resource instance)
Mark part of the surface damaged
This request is used to describe the regions where the pending buffer is different from the
current surface contents, and where the surface therefore needs to be repainted. The
compositor ignores the parts of the damage that fall outside of the surface.
Damage is double-buffered state, see WlSurface.commit().
The damage rectangle is specified in surface-local coordinates, where x and y specify the
upper left corner of the damage rectangle.
The initial value for pending damage is empty: no damage. WlSurface.damage() adds pending
damage: the new pending damage is the union of old pending damage and the given rectangle.
WlSurface.commit() assigns pending damage as the current damage, and clears pending damage.
The server will clear the current damage as it repaints the surface.
Note! New clients should not use this request. Instead damage can be posted with
WlSurface.damage_buffer() which uses buffer coordinates instead of surface coordinates.
Parameters
• x (ArgumentType.Int) -- surface-local x coordinate
• y (ArgumentType.Int) -- surface-local y coordinate
• width (ArgumentType.Int) -- width of damage rectangle
• height (ArgumentType.Int) -- height of damage rectangle
frame() -> 'Proxy[WlCallback]'
Request -- opcode 3 (attached to Resource instance)
Request a frame throttling hint
Request a notification when it is a good time to start drawing a new frame, by creating a
frame callback. This is useful for throttling redrawing operations, and driving animations.
When a client is animating on a WlSurface, it can use the 'frame' request to get notified
when it is a good time to draw and commit the next frame of animation. If the client
commits an update earlier than that, it is likely that some updates will not make it to the
display, and the client is wasting resources by drawing too often.
The frame request will take effect on the next WlSurface.commit(). The notification will
only be posted for one frame unless requested again. For a WlSurface, the notifications are
posted in the order the frame requests were committed.
The server must send the notifications so that a client will not send excessive updates,
while still allowing the highest possible update rate for clients that wait for the reply
before drawing again. The server should give some time for the client to draw and commit
after sending the frame callback events to let it hit the next output refresh.
A server should avoid signaling the frame callbacks if the surface is not visible in any
way, e.g. the surface is off-screen, or completely obscured by other opaque surfaces.
The object returned by this request will be destroyed by the compositor after the callback
is fired and as such the client must not attempt to use it after that point.
The callback_data passed in the callback is the current time, in milliseconds, with an
undefined base.
Returns
WlCallback -- callback object for the frame request
set_opaque_region(region: 'WlRegion | None') -> 'None'
Request -- opcode 4 (attached to Resource instance)
Set opaque region
This request sets the region of the surface that contains opaque content.
The opaque region is an optimization hint for the compositor that lets it optimize the
redrawing of content behind opaque regions. Setting an opaque region is not required for
correct behaviour, but marking transparent content as opaque will result in repaint
artifacts.
The opaque region is specified in surface-local coordinates.
The compositor ignores the parts of the opaque region that fall outside of the surface.
Opaque region is double-buffered state, see WlSurface.commit().
WlSurface.set_opaque_region() changes the pending opaque region. WlSurface.commit() copies
the pending region to the current region. Otherwise, the pending and current regions are
never changed.
The initial value for an opaque region is empty. Setting the pending opaque region has copy
semantics, and the WlRegion object can be destroyed immediately. A NULL WlRegion causes the
pending opaque region to be set to empty.
Parameters
region (WlRegion or None) -- opaque region of the surface
set_input_region(region: 'WlRegion | None') -> 'None'
Request -- opcode 5 (attached to Resource instance)
Set input region
This request sets the region of the surface that can receive pointer and touch events.
Input events happening outside of this region will try the next surface in the server
surface stack. The compositor ignores the parts of the input region that fall outside of
the surface.
The input region is specified in surface-local coordinates.
Input region is double-buffered state, see WlSurface.commit().
WlSurface.set_input_region() changes the pending input region. WlSurface.commit() copies
the pending region to the current region. Otherwise the pending and current regions are
never changed, except cursor and icon surfaces are special cases, see
WlPointer.set_cursor() and WlDataDevice.start_drag().
The initial value for an input region is infinite. That means the whole surface will accept
input. Setting the pending input region has copy semantics, and the WlRegion object can be
destroyed immediately. A NULL WlRegion causes the input region to be set to infinite.
Parameters
region (WlRegion or None) -- input region of the surface
commit() -> 'None'
Request -- opcode 6 (attached to Resource instance)
Commit pending surface state
Surface state (input, opaque, and damage regions, attached buffers, etc.) is
double-buffered. Protocol requests modify the pending state, as opposed to the active state
in use by the compositor.
A commit request atomically creates a content update from the pending state, even if the
pending state has not been touched. The content update is placed in a queue until it
becomes active. After commit, the new pending state is as documented for each related
request.
When the content update is applied, the WlBuffer is applied before all other state. This
means that all coordinates in double-buffered state are relative to the newly attached
wl_buffers, except for WlSurface.attach() itself. If there is no newly attached WlBuffer,
the coordinates are relative to the previous content update.
All requests that need a commit to become effective are documented to affect
double-buffered state.
Other interfaces may add further double-buffered surface state.
set_buffer_transform(transform: 'int') -> 'None'
Request -- opcode 7 (attached to Resource instance)
Sets the buffer transformation
This request sets the transformation that the client has already applied to the content of
the buffer. The accepted values for the transform parameter are the values for
WlOutput.transform().
The compositor applies the inverse of this transformation whenever it uses the buffer
contents.
Buffer transform is double-buffered state, see WlSurface.commit().
A newly created surface has its buffer transformation set to normal.
WlSurface.set_buffer_transform() changes the pending buffer transformation.
WlSurface.commit() copies the pending buffer transformation to the current one. Otherwise,
the pending and current values are never changed.
The purpose of this request is to allow clients to render content according to the output
transform, thus permitting the compositor to use certain optimizations even if the display
is rotated. Using hardware overlays and scanning out a client buffer for fullscreen
surfaces are examples of such optimizations. Those optimizations are highly dependent on
the compositor implementation, so the use of this request should be considered on a
case-by-case basis.
Note that if the transform value includes 90 or 270 degree rotation, the width of the
buffer will become the surface height and the height of the buffer will become the surface
width.
If transform is not one of the values from the WlOutput.transform() enum the
invalid_transform protocol error is raised.
Parameters
transform (ArgumentType.Int) -- transform for interpreting buffer contents
set_buffer_scale(scale: 'int') -> 'None'
Request -- opcode 8 (attached to Resource instance)
Sets the buffer scaling factor
This request sets an optional scaling factor on how the compositor interprets the contents
of the buffer attached to the window.
Buffer scale is double-buffered state, see WlSurface.commit().
A newly created surface has its buffer scale set to 1.
WlSurface.set_buffer_scale() changes the pending buffer scale. WlSurface.commit() copies
the pending buffer scale to the current one. Otherwise, the pending and current values are
never changed.
The purpose of this request is to allow clients to supply higher resolution buffer data for
use on high resolution outputs. It is intended that you pick the same buffer scale as the
scale of the output that the surface is displayed on. This means the compositor can avoid
scaling when rendering the surface on that output.
Note that if the scale is larger than 1, then you have to attach a buffer that is larger
(by a factor of scale in each dimension) than the desired surface size.
If scale is not greater than 0 the invalid_scale protocol error is raised.
Parameters
scale (ArgumentType.Int) -- scale for interpreting buffer contents
damage_buffer(x: 'int', y: 'int', width: 'int', height: 'int') -> 'None'
Request -- opcode 9 (attached to Resource instance)
Mark part of the surface damaged using buffer coordinates
This request is used to describe the regions where the pending buffer is different from the
current surface contents, and where the surface therefore needs to be repainted. The
compositor ignores the parts of the damage that fall outside of the surface.
Damage is double-buffered state, see WlSurface.commit().
The damage rectangle is specified in buffer coordinates, where x and y specify the upper
left corner of the damage rectangle.
The initial value for pending damage is empty: no damage. WlSurface.damage_buffer() adds
pending damage: the new pending damage is the union of old pending damage and the given
rectangle.
WlSurface.commit() assigns pending damage as the current damage, and clears pending damage.
The server will clear the current damage as it repaints the surface.
This request differs from WlSurface.damage() in only one way - it takes damage in buffer
coordinates instead of surface-local coordinates. While this generally is more intuitive
than surface coordinates, it is especially desirable when using wp_viewport or when a
drawing library (like EGL) is unaware of buffer scale and buffer transform.
Note: Because buffer transformation changes and damage requests may be interleaved in the
protocol stream, it is impossible to determine the actual mapping between surface and
buffer damage until WlSurface.commit() time. Therefore, compositors wishing to take both
kinds of damage into account will have to accumulate damage from the two requests
separately and only transform from one to the other after receiving the WlSurface.commit().
Parameters
• x (ArgumentType.Int) -- buffer-local x coordinate
• y (ArgumentType.Int) -- buffer-local y coordinate
• width (ArgumentType.Int) -- width of damage rectangle
• height (ArgumentType.Int) -- height of damage rectangle
offset(x: 'int', y: 'int') -> 'None'
Request -- opcode 10 (attached to Resource instance)
Set the surface contents offset
The x and y arguments specify the location of the new pending buffer's upper left corner,
relative to the current buffer's upper left corner, in surface-local coordinates. In other
words, the x and y, combined with the new surface size define in which directions the
surface's size changes.
Surface location offset is double-buffered state, see WlSurface.commit().
This request is semantically equivalent to and the replaces the x and y arguments in the
WlSurface.attach() request in WlSurface versions prior to 5. See WlSurface.attach() for
details.
Parameters
• x (ArgumentType.Int) -- surface-local x coordinate
• y (ArgumentType.Int) -- surface-local y coordinate
enter(output: 'WlOutput') -> 'None'
Event -- opcode 0 (attached to Proxy instance)
Surface enters an output
This is emitted whenever a surface's creation, movement, or resizing results in some part
of it being within the scanout region of an output.
Note that a surface may be overlapping with zero or more outputs.
Parameters
output (WlOutput) -- output entered by the surface
leave(output: 'WlOutput') -> 'None'
Event -- opcode 1 (attached to Proxy instance)
Surface leaves an output
This is emitted whenever a surface's creation, movement, or resizing results in it no
longer having any part of it within the scanout region of an output.
Clients should not use the number of outputs the surface is on for frame throttling
purposes. The surface might be hidden even if no leave event has been sent, and the
compositor might expect new surface content updates even if no enter event has been sent.
The frame event should be used instead.
Parameters
output (WlOutput) -- output left by the surface
preferred_buffer_scale(factor: 'int') -> 'None'
Event -- opcode 2 (attached to Proxy instance)
Preferred buffer scale for the surface
This event indicates the preferred buffer scale for this surface. It is sent whenever the
compositor's preference changes.
Before receiving this event the preferred buffer scale for this surface is 1.
It is intended that scaling aware clients use this event to scale their content and use
WlSurface.set_buffer_scale() to indicate the scale they have rendered with. This allows
clients to supply a higher detail buffer.
The compositor shall emit a scale value greater than 0.
Parameters
factor (ArgumentType.Int) -- preferred scaling factor
preferred_buffer_transform(transform: 'int') -> 'None'
Event -- opcode 3 (attached to Proxy instance)
Preferred buffer transform for the surface
This event indicates the preferred buffer transform for this surface. It is sent whenever
the compositor's preference changes.
Before receiving this event the preferred buffer transform for this surface is normal.
Applying this transformation to the surface buffer contents and using
WlSurface.set_buffer_transform() might allow the compositor to use the surface buffer more
efficiently.
Parameters
transform (ArgumentType.Uint) -- preferred transform
WlTouch
class pywayland.protocol.wayland.WlTouch
Touchscreen input device
The WlTouch interface represents a touchscreen associated with a seat.
Touch interactions can consist of one or more contacts. For each contact, a series of events is
generated, starting with a down event, followed by zero or more motion events, and ending with an
up event. Events relating to the same contact point can be identified by the ID of the sequence.
release() -> 'None'
Request -- opcode 0 (attached to Resource instance)
Release the touch object
down(serial: 'int', time: 'int', surface: 'WlSurface', id: 'int', x: 'float', y: 'float') ->
'None'
Event -- opcode 0 (attached to Proxy instance)
Touch down event and beginning of a touch sequence
A new touch point has appeared on the surface. This touch point is assigned a unique ID.
Future events from this touch point reference this ID. The ID ceases to be valid after a
touch up event and may be reused in the future.
Parameters
• serial (ArgumentType.Uint) -- serial number of the touch down event
• time (ArgumentType.Uint) -- timestamp with millisecond granularity
• surface (WlSurface) -- surface touched
• id (ArgumentType.Int) -- the unique ID of this touch point
• x (ArgumentType.Fixed) -- surface-local x coordinate
• y (ArgumentType.Fixed) -- surface-local y coordinate
up(serial: 'int', time: 'int', id: 'int') -> 'None'
Event -- opcode 1 (attached to Proxy instance)
End of a touch event sequence
The touch point has disappeared. No further events will be sent for this touch point and
the touch point's ID is released and may be reused in a future touch down event.
Parameters
• serial (ArgumentType.Uint) -- serial number of the touch up event
• time (ArgumentType.Uint) -- timestamp with millisecond granularity
• id (ArgumentType.Int) -- the unique ID of this touch point
motion(time: 'int', id: 'int', x: 'float', y: 'float') -> 'None'
Event -- opcode 2 (attached to Proxy instance)
Update of touch point coordinates
A touch point has changed coordinates.
Parameters
• time (ArgumentType.Uint) -- timestamp with millisecond granularity
• id (ArgumentType.Int) -- the unique ID of this touch point
• x (ArgumentType.Fixed) -- surface-local x coordinate
• y (ArgumentType.Fixed) -- surface-local y coordinate
frame() -> 'None'
Event -- opcode 3 (attached to Proxy instance)
End of touch frame event
Indicates the end of a set of events that logically belong together. A client is expected
to accumulate the data in all events within the frame before proceeding.
A WlTouch.frame() terminates at least one event but otherwise no guarantee is provided
about the set of events within a frame. A client must assume that any state not updated in
a frame is unchanged from the previously known state.
cancel() -> 'None'
Event -- opcode 4 (attached to Proxy instance)
Touch session cancelled
Sent if the compositor decides the touch stream is a global gesture. No further events are
sent to the clients from that particular gesture. Touch cancellation applies to all touch
points currently active on this client's surface. The client is responsible for finalizing
the touch points, future touch points on this surface may reuse the touch point ID.
No frame event is required after the cancel event.
shape(id: 'int', major: 'float', minor: 'float') -> 'None'
Event -- opcode 5 (attached to Proxy instance)
Update shape of touch point
Sent when a touchpoint has changed its shape.
This event does not occur on its own. It is sent before a WlTouch.frame() event and carries
the new shape information for any previously reported, or new touch points of that frame.
Other events describing the touch point such as WlTouch.down(), WlTouch.motion() or
WlTouch.orientation() may be sent within the same WlTouch.frame(). A client should treat
these events as a single logical touch point update. The order of WlTouch.shape(),
WlTouch.orientation() and WlTouch.motion() is not guaranteed. A WlTouch.down() event is
guaranteed to occur before the first WlTouch.shape() event for this touch ID but both
events may occur within the same WlTouch.frame().
A touchpoint shape is approximated by an ellipse through the major and minor axis length.
The major axis length describes the longer diameter of the ellipse, while the minor axis
length describes the shorter diameter. Major and minor are orthogonal and both are
specified in surface-local coordinates. The center of the ellipse is always at the
touchpoint location as reported by WlTouch.down() or WlTouch.move().
This event is only sent by the compositor if the touch device supports shape reports. The
client has to make reasonable assumptions about the shape if it did not receive this event.
Parameters
• id (ArgumentType.Int) -- the unique ID of this touch point
• major (ArgumentType.Fixed) -- length of the major axis in surface-local
coordinates
• minor (ArgumentType.Fixed) -- length of the minor axis in surface-local
coordinates
orientation(id: 'int', orientation: 'float') -> 'None'
Event -- opcode 6 (attached to Proxy instance)
Update orientation of touch point
Sent when a touchpoint has changed its orientation.
This event does not occur on its own. It is sent before a WlTouch.frame() event and carries
the new shape information for any previously reported, or new touch points of that frame.
Other events describing the touch point such as WlTouch.down(), WlTouch.motion() or
WlTouch.shape() may be sent within the same WlTouch.frame(). A client should treat these
events as a single logical touch point update. The order of WlTouch.shape(),
WlTouch.orientation() and WlTouch.motion() is not guaranteed. A WlTouch.down() event is
guaranteed to occur before the first WlTouch.orientation() event for this touch ID but both
events may occur within the same WlTouch.frame().
The orientation describes the clockwise angle of a touchpoint's major axis to the positive
surface y-axis and is normalized to the -180 to +180 degree range. The granularity of
orientation depends on the touch device, some devices only support binary rotation values
between 0 and 90 degrees.
This event is only sent by the compositor if the touch device supports orientation reports.
Parameters
• id (ArgumentType.Int) -- the unique ID of this touch point
• orientation (ArgumentType.Fixed) -- angle between major axis and positive surface
y-axis in degrees
Scanner Modules
Argumet
class pywayland.scanner.argument.Argument(name: str, type: ArgumentType, summary: str | None, interface:
str | None, allow_null: bool, enum: str | None, description: Description | None)
Argument to a request or event method
Required attributes: name and type
Optional attributes: summary, interface, and allow-null
Child elements: description
property argument: str
Output as an Argument
property interface_class: str
Returns the Interface class name
Gives the class name for the Interface coresponding to the type of the argument.
output_doc_param(printer: Printer) -> None
Document the argument as a parameter
output_doc_ret(printer: Printer) -> None
Document the argument as a return
property signature: str
Output as the argument appears in the signature.
class pywayland.scanner.argument.ArgumentType(value, names=<not given>, *values, module=None,
qualname=None, type=None, start=1, boundary=None)
Entry
class pywayland.scanner.entry.Entry(name: str, value: str, summary: str | None, since: str | None,
description: Description | None)
Scanner for enum entries
Required attributes: name and value
Optional attributes: summary and since
Child elements: description
output(enum_name: str, printer: Printer) -> None
Generate the output for the entry in the enum
Enum
class pywayland.scanner.enum.Enum(name: str, since: str | None, is_bitfield: bool, description:
Description | None, entry: list[Entry])
Scanner for enum objects
Required attributes: name and since
Child elements: description and entry
output(printer: Printer) -> None
Generate the output for the enum to the printer
Event
class pywayland.scanner.event.Event(name: str, since: str | None, description: Description | None, arg:
list[Argument])
Scanner for event objects (server-side method)
Required attributes: name
Optional attributes: since
Child elements: description and arg`
property method_args: Iterator[str]
Generator of the arguments to the method
All arguments to be sent to ._post_event must be passed in
output_body(printer: Printer, opcode: int) -> None
Output the body of the event to the printer
output_doc_params(printer: Printer) -> None
Aguments documented as parameters
All arguments are event parameters.
Interface
class pywayland.scanner.interface.Interface(name: 'str', version: 'str', description: 'Description |
None', enum: 'list[Enum]', event: 'list[Event]', request: 'list[Request]')
property class_name: str
Returns the name of the class of the interface
Camel cases the name of the interface, to be used as the class name.
output(printer: Printer, module_imports: dict[str, str]) -> None
Generate the output for the interface to the printer
classmethod parse(element: Element) -> Interface
Scanner for interface objects
Required attributes: name and version
Child elements: description, request, event, enum
Method
class pywayland.scanner.method.Method(name: str, since: str | None, description: Description | None, arg:
list[Argument])
Scanner for methods
Corresponds to event and requests defined on an interface
imports(interface: str, module_imports: dict[str, str]) -> list[tuple[str, str]]
Get the imports required for each of the interfaces
Parameters
• interface -- The name of the interface that the method is a part of.
• module_imports -- A mapping from the name of an interface in the associated module
that the interface comes from.
Returns
A list of 2-tuples, each specifying the path to an imported module and the imported
class.
output(printer: Printer, opcode: int, in_class: str, module_imports: dict[str, str]) -> None
Generate the output for the given method to the printer
output_doc(printer: Printer) -> None
Output the documentation for the interface
Printer
Request
class pywayland.scanner.request.Request(name: str, since: str | None, description: Description | None,
arg: list[Argument], type: str | None)
Scanner for request objects (client-side method)
Required attributes: name
Optional attributes: type and since
Child elements: description and arg
property marshal_args: Iterable[str]
Arguments sent to ._marshal
property method_args: Iterable[str]
Generator of the arguments to the method
The new_id args are generated in marshaling the args, they do not appear in the args of the
method.
output_body(printer: Printer, opcode: int) -> None
Output the body of the request to the printer
output_doc_params(printer: Printer) -> None
Aguments documented as parameters
Anything that is not a new_id is
output_doc_ret(printer: Printer) -> None
Aguments documented as return values
Arguments of type new_id are returned from requests.
property return_type: str
The return type for the request.
Scanner
Using the Scanner module
The PyWayland scanner allows you to generate the protocol scanner output within Python scripts. The
general procedure to invoke the scanner will be to make a Protocol object, scan the input file, and have
the Protocol output to a directory. These steps are done as:
Protocol.parse_file(path_to_xml_file)
Protocol.output(path_to_output_dir, {})
See the definitions below for more information on using Protocol objects.
Protocol Module
class pywayland.scanner.Protocol(name: str, copyright: Copyright | None, description: Description | None,
interface: list[Interface])
Protocol scanner object
Main scanner object that acts on the input xml files to generate protocol files.
Required attributes: name
Child elements: copyright?, description?, and interface+
Parameters
input_file -- Name of input XML file
output(output_dir: str, module_imports: dict[str, str]) -> None
Output the scanned files to the given directory
Parameters
output_dir (string) -- Path of directory to output protocol files to
Utilities Module
AnonymousFile Class
class pywayland.utils.AnonymousFile(size: int)
Anonymous file object
Provides access to anonymous file objects that can be used by Wayland clients to render to
surfaces. Uses a method similar to Weston to open an anonymous file, so XDG_RUNTIME_DIR must be
set for this to work properly.
This class provides a content manager, that is, it can be used with Python with statements, where
the value returned is the file descriptor.
close() -> None
Close the anonymous file
Closes the file descriptor and sets the fd property to None. Does nothing if the file is
not open.
open() -> None
Open an anonymous file
Opens the anonymous file and sets the fd property to the file descriptor that has been
opened.
AUTHOR
Sean Vig
COPYRIGHT
2016, Sean Vig
0.4.18 Mar 08, 2025 PYWAYLAND(1)